home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Professional / OS2PRO194.ISO / os2 / wps / tools / udesktop / udesktop.doc next >
Encoding:
Text File  |  1992-07-01  |  17.6 KB  |  498 lines
  1.                   
  2.            o   o oooo  ooooo  ooo  o   o ooooo  ooo  oooo
  3.            o   o o   o o     o   o o  o    o   o   o o   o
  4.            o   o o   o o     o     o o     o   o   o o   o
  5.            o   o o   o oooo   ooo  oo      o   o   o oooo
  6.            o   o o   o o         o o o     o   o   o o
  7.            o   o o   o o     o   o o  o    o   o   o o
  8.             ooo  oooo  ooooo  ooo  o   o   o    ooo  o
  9.  
  10.            ************ THE AUTOMATIC MOUSE **************
  11.  
  12.                         Version 2.0
  13.  
  14.                         Developed by A. Rohr
  15.  
  16.                         Megos AG
  17.                         Froehlichstrasse 33
  18.                         5200 Brugg
  19.                         Switzerland
  20.  
  21.                         Copyright (c) 1992 Megos AG
  22.  
  23.  
  24. Are you tired about arranging your windows, especially the text windows,
  25. manually, again and again, after EVERY boot, because OS/2 always places
  26. them where you do not want them, in sizes not very useful, but does not
  27. offer commands for automatic re-arranging?
  28.  
  29. Then you are in need of 'UDesktop', the "automatic mouse".
  30.  
  31.  
  32. 'UDesktop' is a small utility ("U" stands for "utility") to manage your
  33. desktop from the command line. It can automatically move, size, maximize
  34. and minimize windows. With the help of 'UDesktop' you can write
  35. batchfiles that arrange text windows the way you like it, without the
  36. need to ever touch the mouse. It works with virtually all versions of
  37. OS/2, from 1.1 up to 2.0.
  38.  
  39.  
  40. 'UDesktop' is Freeware. Feel free to use and distribute it further.
  41. However note that other actions are restricted by copyright - see the
  42. copyright section at the end of this file.
  43.  
  44.  
  45.  
  46. ========================================================================
  47.  
  48. REFERENCE MANUAL
  49.  
  50.  
  51. Introduction
  52. ============
  53.  
  54. In the Presentation Manager User Interface (PM) it is very easy to move
  55. and resize windows interactively with the mouse. However there are no
  56. means to do such manipulations automatically in a batch file.
  57.  
  58. The tool 'UDesktop' can be seen as "the program controlled mouse", an
  59. extension to the OS/2 command processor that provides commands to
  60. manipulate windows. The tool can also save the arrangement of all
  61. windows on the screen and exactly restore it later.
  62.  
  63. Windows
  64. =======
  65.  
  66. Basically 'UDesktop' operates on ##PM_windows. But not all windows
  67. can be accessed, only frame windows. Unfortunately it is impossible
  68. to give a complete definition of what a frame window is without getting
  69. very technical and use terms like "WC_FRAME window class" and the like.
  70.  
  71. Thus a less precise but easier-to-understand definition is given here
  72. instead: A ##frame_window is a window that has a "System Menu" icon in
  73. its title bar and that appears as an entry in the task list. Therefore
  74. e.g. a window used to display a dialog box is not a frame window.
  75.  
  76. As a simplification, in the following mostly "window" is used instead
  77. of "frame window".
  78.  
  79. Text windows are a special class of frame windows. Text windows are
  80. something like simulated character-mode screens. Text windows are
  81. primary candidates for manipulation with 'UDesktop': The defaults
  82. that OS/2 uses for location, size and font when opening a new text
  83. window are seldom what is really wanted.
  84.  
  85. The following attributes of a window are known to 'UDesktop' and can
  86. be changed:
  87.  
  88. - location on the screen
  89. - size
  90. - state (restored, maximized or minimized i.e. an icon)
  91. - position relative to other windows in "Z" direction ("behind" or
  92.   "in front of" in respect to other windows)
  93. - active/inactive (currently with or without the input focus)
  94. - font size for text windows
  95.  
  96. In the following all the windows currently existing on the screen,
  97. with all the data relevant to 'UDesktop' about them, is called the
  98. ##screen_configuration. For the screen configuration it does not
  99. matter whether a window or its icon is visible or not; it may be
  100. currently covered by other windows.
  101.  
  102. 'UDesktop' can only manipulate existing windows but cannot create
  103. windows.
  104.  
  105. Running 'UDesktop'
  106. ==================
  107.  
  108. In the following it is assumed that 'UDesktop' is started from an
  109. "OS/2 window" i.e. from command line in a text window.
  110.  
  111. 'UDesktop' is a standalone executable ".EXE" program and does not need
  112. any other file. One can start the tool in the active window with:
  113.  
  114.   UDesktop ...
  115.  
  116. Because it is a PM program the execution of the tool has side effects:
  117. The active window is minimized when the tool starts and restored after
  118. it terminates. This happens automatically and out of the control of the
  119. tool. If 'UDesktop' is started this way it is thus impossible to
  120. minimize or maximize the active window.
  121.  
  122. There is the second possibility of executing the tool in an own session
  123. with:
  124.  
  125.   START UDesktop ...
  126.  
  127. This second way eliminates the problems mentioned and generally results
  128. in much less unnecessary window redraws and restores.
  129.  
  130. Normally 'UDesktop' just runs silently without displaying something.
  131. Only in the case of an error a dialog box appears containing an
  132. error message. There is a  "/TRY" switch that can be used to tell the
  133. tool to ignore errors and suppress such error dialog boxes altogether.
  134.  
  135. Windows as Arguments
  136. ====================
  137.  
  138. 'UDesktop' identifies windows by the ##window_title i.e. the text in
  139. the title bar of the window. The whole text is taken, exactly as shown,
  140. with upper-/lowercase significant. If there is more than one window with
  141. the same title on the screen identification would fail. Advanced users
  142. may append ",number" at the end of the title where "number" is the local
  143. identity of the window. This is exactly the way how windows are
  144. identified in the saved desktop configuration. Windows with empty titles
  145. cannot be processed at all and are skipped.
  146.  
  147. The following window titles are "reserved" and have a special meaning
  148. when used as arguments for 'UDesktop':
  149.  
  150.   .        the frame window where 'UDesktop' was started
  151.   active   the frame currently active
  152.   focus    the frame currently having the input focus
  153.   top      the currently topmost window
  154.   bottom   the window currently on bottom (behind all others)
  155.   next     the window immediately in front of the start window (cyclic)
  156.   prev     the window immediately behind the start window (cyclic)
  157.  
  158. More than one of these can be applied by concatenating them with a
  159. comma in between, i.e. "bottom,prev,prev".
  160.  
  161. "." can also be used if the tool is started in an own session with
  162. "START" since the tool determines the start session (otherwise "."
  163. would be the tool's own invisible window which is quite useless).
  164.  
  165. If a window title contains blanks it has to be surrounded with quotes
  166. or double quotes as in the following examples:
  167.  
  168.   'Desktop Manager'
  169.   "Jack's Window"
  170.  
  171. If the tool outputs a title to the user or a file it doubles all
  172. double quotes and vice versa.
  173.  
  174. Command Notation
  175. ================
  176.  
  177. Because 'UDesktop' implements something like a tiny command language
  178. a notation for the commands is needed. The following rules (close to
  179. what is called "EBNF") apply:
  180.  
  181. - Parenthesis "(" and ")" are not part of the command string but part
  182.   the notation: They enclose what results in a single argument.
  183. - Brackets "[" and "]" are also part of the notation and denote an
  184.   argument that can be omitted
  185. - A vertical bar "|" means that either the left or the right argument
  186.   must be chosen.
  187.  
  188. Commands
  189. ========
  190.  
  191. The general format for running 'UDesktop' from command line:
  192.  
  193.   [ START ] UDesktop [ /TRY ] [ /FONT ] command [ arguments ]
  194.  
  195. Except for the window titles case does not matter. "Save", "SAVE" and
  196. "save" all refer to the same command.
  197.  
  198. The "/TRY" switch
  199. -----------------
  200.  
  201. The "/TRY" switch is valid for any command. It tells the tool not to
  202. stop and display a dialog box if an error occurs. With "/TRY" set
  203. the tool just terminates in case of an error. This can be useful in
  204. batch files which should proceed without user intervention.
  205.  
  206. The "/FONT" switch
  207. ------------------
  208.  
  209. The "/FONT" switch is valid for any command. It tells the tool to
  210. handle the font size data too which is usually not part of the configu-
  211. ration set of each window. Because it was not possible to set or query
  212. the size without opening a dialog box, this results in a short flicker.
  213. Otherwise the font size would be always incorporated in the configu-
  214. ration set. We hope that will be fixed in the future (so god will).
  215.  
  216. SAVE [ fileName ]
  217. ------------------
  218.  
  219. Save the current screen configuration.
  220.  
  221. The current screen configuration - all data relevant to 'UDesktop'
  222. (location, size etc., see above) about all windows currently existing
  223. on the screen - is saved in a textfile. If no file name is given, a file
  224. 'UDesktop.SAV' is created in the current directory. An already existing
  225. file with the name given is overwritten without an error message. The
  226. content is made user readable so one can peek or modify the
  227. configuration with any common text editor. Note the usage of the switch
  228. "/FONT" for additional storing of the font size of each window.
  229.  
  230. It is a good idea to use the "START" method of running 'UDesktop' when
  231. using the "SAVE" command.
  232.  
  233. LOAD [ fileName ]
  234. ------------------
  235.  
  236. Load a screen configuration previously saved.
  237.  
  238. This command is the opposite of the "SAVE" command. It moves, resizes
  239. etc. the windows on the screen according to the data contained in the
  240. textfile given. If no file name is given 'UDesktop.SAV' is assumed.
  241.  
  242. As mentioned earlier 'UDesktop' in general and the "LOAD" command in
  243. particular are not able to create windows. The windows to be manipulated
  244. must be open already.
  245.  
  246. In case information is found in the file about a window that cannot be
  247. found on the screen at the moment of the execution of the "LOAD"
  248. command, that information is simply ignored. If windows are on the
  249. screen that are not mentioned in the file they are left untouched.
  250.  
  251. Such cases are exceptions, however. The normal situation will probably
  252. be that the same windows which were present for the "SAVE" command are
  253. again present for the "LOAD" command. Note the usage of the switch
  254. "FONT" for restoring the font size of each window when saved with this
  255. switch too.
  256.  
  257. One can savely edit the configuration file with any common editor since
  258. syntax errors are catched and made harmless.
  259.  
  260. The "SAVE" command is especially useful to set up a defined screen
  261. configuration after booting. As part of the 'Startup.CMD' batch file
  262. one starts all programs and opens all windows, and as the last step
  263. one lets 'UDesktop' arrange the windows.
  264.  
  265. RENAME oldTitle newTitle
  266. ------------------------
  267.  
  268. Change a window title.
  269.  
  270. As an example one can use this command to change a window title from
  271. "OS/2 Window" to something more meaningful.
  272.  
  273. The program that is running and controling the window that has the title
  274. changed will most probably not react in any way. Changing the window
  275. title bypassing the owner of the window is harmless.
  276.  
  277. PUT title ( TOP | BOTTOM | BEHIND otherTitle )
  278. ----------------------------------------------
  279.  
  280. Change the relative position of the window with the given title in
  281. respect to other windows.
  282.  
  283. SETFONT title ( LARGE | SMALL | x )
  284. -------------------------------------
  285.  
  286. Change the font size of a text window.
  287.  
  288.  - OS/2 version 1.1: This command is equivalent to the menu choice
  289.    "Large Font" / "Small Font" in the System Menu of the text window.
  290.  
  291.  - OS/2 version 1.2 and above: This command is equivalent to selecting
  292.    the font number x in the dialog box that pops up in the menu-
  293.    entry "Font Size..." of the System Menu. Due to an error in the
  294.    operating system during querying the entry of a menu or listbox
  295.    it isn't possible to select a font by its size in pixel. We hope
  296.    that this will be fixed in the future (so God will).
  297.  
  298. MOVE title x,y
  299. --------------
  300.  
  301. Move the window to a given position on the screen.
  302.  
  303. The screen coordinates "x" and "y" are given in pixels. As a general
  304. convention for PM, the lower left border is the point 0,0. In VGA
  305. resolution the point 300,200 is approximately the middle of the screen.
  306.  
  307. This command is equivalent to the System Menu choice "Move".
  308.  
  309. SIZE title x,y
  310. --------------
  311.  
  312. Change the size of a window to width "x" and height "y".
  313.  
  314. Like in the "MOVE" command "x" and "y" - the new horizontal and
  315. vertical sizes - are given in pixels.
  316.  
  317. This command is equivalent to the System Menu choice "Size".
  318.  
  319. MINIMIZE title
  320. --------------
  321.  
  322. Minimize the window.
  323.  
  324. This command is equivalent to the System Menu choice "Minimize".
  325.  
  326. MAXIMIZE title
  327. --------------
  328.  
  329. Maximize the window.
  330.  
  331. This command is equivalent to the System Menu choice "Maximize".
  332.  
  333. RESTORE title
  334. -------------
  335.  
  336. Restore the window to its previous size.
  337.  
  338. After minimizing or maximizing this command returns the window to the
  339. size it had before.
  340.  
  341. This command is equivalent to the System Menu choice "Restore".
  342.  
  343. HIDE title
  344. ----------
  345.  
  346. Hide the window i.e. make it invisible.
  347.  
  348. After this command the window completly disappears from the screen: It
  349. is turned into an "invisible window". It is not closed, however, and
  350. does not disappear from the task list either. It can even get the input
  351. focus.
  352.  
  353. This command has no interactive equivalent.
  354.  
  355. SHOW title
  356. ----------
  357.  
  358. Show the window i.e. make it visible again.
  359.  
  360. This command is the opposite of the "HIDE" command. Like the "HIDE"
  361. command this command has no interactive equivalent.
  362.  
  363. ACTIVATE title
  364. --------------
  365.  
  366. Activate the window i.e. give it the input focus.
  367.  
  368. This is equivalent to selecting the window with a mouse click or
  369. executing "Switch to" in the Task List.
  370.  
  371. DEACTIVATE title
  372. ----------------
  373.  
  374. Deactivate the window.
  375.  
  376. The window behind the window becomes the new active window.
  377.  
  378. CLOSE title
  379. -----------
  380.  
  381. Close the window.
  382.  
  383. This command is equivalent to selecting "Close" in the System Menu of
  384. the window and telling "yes" in the confirm dialog box that appears.
  385. One should therefore be careful when using this command.
  386.  
  387. DESCRIBE ( title | ALL )
  388. ------------------------
  389.  
  390. Bring up a dialog box with a short description of the look of the
  391. window. The description is indeed the same as those used in the
  392. configuration file. It contains the title, position, size, status,
  393. font size, restore position, restore size and minimize position of
  394. the window. With the argument "ALL", this description is displayed
  395. for all open windows.
  396.  
  397.  
  398. Checks
  399. ------
  400.  
  401. There is a whole group of commands that allows various checks about
  402. the windows on the screen. If the check succeeds (the condition
  403. is met) the "ERRORLEVEL" variable of the command processor is set to
  404. 0. Otherwise it is set to 1. For more about "ERRORLEVEL" refer to the
  405. next chapter.
  406.  
  407. EXIST title            Is there a window with the given title?
  408. IS title1 title2       Are "title1" and "title2" same?
  409. ISFONT title font      Is the given font set in the text window?
  410. MINIMIZED title        Is the window minimized?
  411. MAXIMIZED title        Is the window maximized?
  412. RESTORED title         Does the window have its normal size?
  413. VISIBLE title          Is the window visible?
  414. ACTIVATED title        Is the window the active window?
  415.  
  416.  
  417. 'UDesktop' as part of a batch file
  418. ==================================
  419.  
  420. When using the tool as part of a batch file two things are relevant:
  421. The "/TRY" switch and the way the tool sets the "ERRORLEVEL" variable
  422. when it terminates.
  423.  
  424. There are four combinations that can occur:
  425.  
  426.   normal execution, no error         SET ERRORLEVEL 0
  427.   normal execution, error            SET ERRORLEVEL 1, after dialog box
  428.   "/TRY" used, no error              SET ERRORLEVEL 0
  429.   "/TRY" used, error                 SET ERRORLEVEL 1
  430.  
  431. The checks also set the error level, with 0 standing for "TRUE" and
  432. 1 for "FALSE". In order to be sure about the meaning of a level of 1,
  433. one should make sure that the check does indeed check and not lead
  434. to an error.
  435.  
  436. One should note that the question "Did the check succeed and return
  437. TRUE?" as well as the question "Did the tool terminate without error?"
  438. translate into the following batch file line:
  439.  
  440.   IF NOT ERRORLEVEL 1 ...
  441.  
  442. The following batch file condition has definitely not the desired effect
  443. because it always evaluates to "TRUE":
  444.  
  445.   IF ERRORLEVEL 0 ...
  446.  
  447. Examples
  448. ========
  449.  
  450. The following are examples of single runs of 'UDesktop':
  451.  
  452.   UDesktop SAVE
  453.   UDesktop LOAD
  454.   UDesktop SAVE C:\TMP\Config.DTP
  455.   UDesktop RENAME . Workframe
  456.   START UDesktop PUT Workframe BEHIND "Desktop Manager"
  457.   UDesktop MOVE . 200,100
  458.   UDesktop /TRY CLOSE Workframe
  459.  
  460. Versions
  461. ========
  462.  
  463. The version number is displayed by launching the program without
  464. arguments. Version history:
  465.  
  466.   1.0   11/89   First release under OS/2 1.1.
  467.   1.1   12/90   Configuration saving extended. Window locking and
  468.                 error handling improved.
  469.   2.0   06/92   OS/2 2.0 savvy. Configurations are saved in a textfile.
  470.  
  471. Copyright (c)
  472. =============
  473.  
  474. This program is freeware and meant to be distributed freely to anyone
  475. who likes it. Any other actions like selling or modifying the program
  476. fall under the laws of copyright and are prohibited.
  477.  
  478. This utility was programmed with Logitech/Multiscope Modula-OS/2. Parts
  479. of it Copyright (c) Logitech/Multicope Inc.
  480.  
  481. 'UDesktop' has little connection to Megos' main business of writing
  482. taylor-made applications under OS/2 for customers in Switzerland; it
  483. is a by-product of our long-lasting relationship with OS/2. However,
  484. if you like 'UDesktop' you might like our business applications as
  485. well...
  486.  
  487. If you have any suggestions or questions feel free to contact us:
  488.  
  489.  
  490.                         Megos AG
  491.                         Froehlichstrasse 33
  492.                         5200 Brugg
  493.                         Switzerland
  494.  
  495.                         Tel: ++41 56 41 34 17
  496.                         Fax: ++41 56 41 80 10
  497.                         BIX: wvogt
  498.