UDesktop Reference Manual

Are you tired about arranging your windows, especially the text windows, manually, again and again, after EVERY boot, because OS/2 always places them where you do not want them, in sizes not very useful, but does not offer commands for automatic re-arranging?

Then you are in need of 'UDesktop', the "automatic mouse".

'UDesktop' is a small utility ("U" stands for "utility") to manage your desktop from the command line. It can automatically move, size, maximize and minimize windows. With the help of 'UDesktop' you can write batchfiles that arrange text windows the way you like it, without the need to ever touch the mouse. It works with virtually all versions of OS/2, from 1.1 up to 2.0.

'UDesktop' is Freeware. Feel free to use and distribute it further. However note that other actions are restricted by copyright - see the copyright section at the end of this file.

Introduction
In the Presentation Manager User Interface (PM) it is very easy to move and resize windows interactively with the mouse. However there are no means to do such manipulations automatically in a batch file.

The tool 'UDesktop' can be seen as "the program controlled mouse", an extension to the OS/2 command processor that provides commands to manipulate windows. The tool can also save the arrangement of all windows on the screen and exactly restore it later.

Windows
Basically 'UDesktop' operates on ##PM_windows. But not all windows can be accessed, only frame windows. Unfortunately it is impossible to give a complete definition of what a frame window is without getting very technical and use terms like "WC_FRAME window class" and the like.

Thus a less precise but easier-to-understand definition is given here instead: A ##frame_window is a window that has a "System Menu" icon in its title bar and that appears as an entry in the task list. Therefore e.g. a window used to display a dialog box is not a frame window.

As a simplification, in the following mostly "window" is used instead of "frame window".

Text windows are a special class of frame windows. Text windows are something like simulated character-mode screens. Text windows are primary candidates for manipulation with 'UDesktop': The defaults that OS/2 uses for location, size and font when opening a new text window are seldom what is really wanted.

The following attributes of a window are known to 'UDesktop' and can be changed:

- location on the screen - size - state (restored, maximized or minimized i.e. an icon) - position relative to other windows in "Z" direction ("behind" or "in front of" in respect to other windows) - active/inactive (currently with or without the input focus) - font size for text windows

In the following all the windows currently existing on the screen, with all the data relevant to 'UDesktop' about them, is called the matter whether a window or its icon is visible or not; it may be currently covered by other windows.
 * 1) screen_configuration. For the screen configuration it does not

'UDesktop' can only manipulate existing windows but cannot create windows.

Running 'UDesktop'
In the following it is assumed that 'UDesktop' is started from an "OS/2 window" i.e. from command line in a text window.

'UDesktop' is a standalone executable ".EXE" program and does not need any other file. One can start the tool in the active window with:

UDesktop ...

Because it is a PM program the execution of the tool has side effects: The active window is minimized when the tool starts and restored after it terminates. This happens automatically and out of the control of the tool. If 'UDesktop' is started this way it is thus impossible to minimize or maximize the active window.

There is the second possibility of executing the tool in an own session with:

START UDesktop ...

This second way eliminates the problems mentioned and generally results in much less unnecessary window redraws and restores.

Normally 'UDesktop' just runs silently without displaying something. Only in the case of an error a dialog box appears containing an error message. There is a "/TRY" switch that can be used to tell the tool to ignore errors and suppress such error dialog boxes altogether.

Windows as Arguments
'UDesktop' identifies windows by the ##window_title i.e. the text in the title bar of the window. The whole text is taken, exactly as shown, with upper-/lowercase significant. If there is more than one window with the same title on the screen identification would fail. Advanced users may append ",number" at the end of the title where "number" is the local identity of the window. This is exactly the way how windows are identified in the saved desktop configuration. Windows with empty titles cannot be processed at all and are skipped.

The following window titles are "reserved" and have a special meaning when used as arguments for 'UDesktop':

.       the frame window where 'UDesktop' was started active  the frame currently active focus   the frame currently having the input focus top     the currently topmost window bottom  the window currently on bottom (behind all others) next    the window immediately in front of the start window (cyclic) prev    the window immediately behind the start window (cyclic)

More than one of these can be applied by concatenating them with a comma in between, i.e. "bottom,prev,prev".

"." can also be used if the tool is started in an own session with "START" since the tool determines the start session (otherwise "." would be the tool's own invisible window which is quite useless).

If a window title contains blanks it has to be surrounded with quotes or double quotes as in the following examples:

'Desktop Manager' "Jack's Window"

If the tool outputs a title to the user or a file it doubles all double quotes and vice versa.

Command Notation
Because 'UDesktop' implements something like a tiny command language a notation for the commands is needed. The following rules (close to what is called "EBNF") apply:

- Parenthesis "(" and ")" are not part of the command string but part the notation: They enclose what results in a single argument. - Brackets "[" and "]" are also part of the notation and denote an argument that can be omitted - A vertical bar "|" means that either the left or the right argument must be chosen.

Commands
The general format for running 'UDesktop' from command line:

[ START ] UDesktop [ /TRY ] [ /FONT ] command [ arguments ]

Except for the window titles case does not matter. "Save", "SAVE" and "save" all refer to the same command.

The "/TRY" switch
The "/TRY" switch is valid for any command. It tells the tool not to stop and display a dialog box if an error occurs. With "/TRY" set the tool just terminates in case of an error. This can be useful in batch files which should proceed without user intervention.

The "/FONT" switch
The "/FONT" switch is valid for any command. It tells the tool to handle the font size data too which is usually not part of the configu- ration set of each window. Because it was not possible to set or query the size without opening a dialog box, this results in a short flicker. Otherwise the font size would be always incorporated in the configu- ration set. We hope that will be fixed in the future (so god will).

SAVE [ fileName ]
Save the current screen configuration.

The current screen configuration - all data relevant to 'UDesktop' (location, size etc., see above) about all windows currently existing on the screen - is saved in a textfile. If no file name is given, a file 'UDesktop.SAV' is created in the current directory. An already existing file with the name given is overwritten without an error message. The content is made user readable so one can peek or modify the configuration with any common text editor. Note the usage of the switch "/FONT" for additional storing of the font size of each window.

It is a good idea to use the "START" method of running 'UDesktop' when using the "SAVE" command.

LOAD [ fileName ]
Load a screen configuration previously saved.

This command is the opposite of the "SAVE" command. It moves, resizes etc. the windows on the screen according to the data contained in the textfile given. If no file name is given 'UDesktop.SAV' is assumed.

As mentioned earlier 'UDesktop' in general and the "LOAD" command in particular are not able to create windows. The windows to be manipulated must be open already.

In case information is found in the file about a window that cannot be found on the screen at the moment of the execution of the "LOAD" command, that information is simply ignored. If windows are on the screen that are not mentioned in the file they are left untouched.

Such cases are exceptions, however. The normal situation will probably be that the same windows which were present for the "SAVE" command are again present for the "LOAD" command. Note the usage of the switch "FONT" for restoring the font size of each window when saved with this switch too.

One can savely edit the configuration file with any common editor since syntax errors are catched and made harmless.

The "SAVE" command is especially useful to set up a defined screen configuration after booting. As part of the 'Startup.CMD' batch file one starts all programs and opens all windows, and as the last step one lets 'UDesktop' arrange the windows.

RENAME oldTitle newTitle
Change a window title.

As an example one can use this command to change a window title from "OS/2 Window" to something more meaningful.

The program that is running and controling the window that has the title changed will most probably not react in any way. Changing the window title bypassing the owner of the window is harmless.

PUT title ( TOP | BOTTOM | BEHIND otherTitle )
Change the relative position of the window with the given title in respect to other windows.

SETFONT title ( LARGE | SMALL | x )
Change the font size of a text window.

- OS/2 version 1.1: This command is equivalent to the menu choice "Large Font" / "Small Font" in the System Menu of the text window.

- OS/2 version 1.2 and above: This command is equivalent to selecting the font number x in the dialog box that pops up in the menu- entry "Font Size..." of the System Menu. Due to an error in the operating system during querying the entry of a menu or listbox it isn't possible to select a font by its size in pixel. We hope that this will be fixed in the future (so God will).

MOVE title x,y
Move the window to a given position on the screen.

The screen coordinates "x" and "y" are given in pixels. As a general convention for PM, the lower left border is the point 0,0. In VGA resolution the point 300,200 is approximately the middle of the screen.

This command is equivalent to the System Menu choice "Move".

SIZE title x,y
Change the size of a window to width "x" and height "y".

Like in the "MOVE" command "x" and "y" - the new horizontal and vertical sizes - are given in pixels.

This command is equivalent to the System Menu choice "Size".

MINIMIZE title
Minimize the window.

This command is equivalent to the System Menu choice "Minimize".

MAXIMIZE title
Maximize the window.

This command is equivalent to the System Menu choice "Maximize".

RESTORE title
Restore the window to its previous size.

After minimizing or maximizing this command returns the window to the size it had before.

This command is equivalent to the System Menu choice "Restore".

HIDE title
Hide the window i.e. make it invisible.

After this command the window completly disappears from the screen: It is turned into an "invisible window". It is not closed, however, and does not disappear from the task list either. It can even get the input focus.

This command has no interactive equivalent.

SHOW title
Show the window i.e. make it visible again.

This command is the opposite of the "HIDE" command. Like the "HIDE" command this command has no interactive equivalent.

ACTIVATE title
Activate the window i.e. give it the input focus.

This is equivalent to selecting the window with a mouse click or executing "Switch to" in the Task List.

DEACTIVATE title
Deactivate the window.

The window behind the window becomes the new active window.

CLOSE title
Close the window.

This command is equivalent to selecting "Close" in the System Menu of the window and telling "yes" in the confirm dialog box that appears. One should therefore be careful when using this command.

DESCRIBE ( title | ALL )
Bring up a dialog box with a short description of the look of the window. The description is indeed the same as those used in the configuration file. It contains the title, position, size, status, font size, restore position, restore size and minimize position of the window. With the argument "ALL", this description is displayed for all open windows.

Checks
There is a whole group of commands that allows various checks about the windows on the screen. If the check succeeds (the condition is met) the "ERRORLEVEL" variable of the command processor is set to 0. Otherwise it is set to 1. For more about "ERRORLEVEL" refer to the next chapter.

EXIST title           Is there a window with the given title? IS title1 title2      Are "title1" and "title2" same? ISFONT title font     Is the given font set in the text window? MINIMIZED title       Is the window minimized? MAXIMIZED title       Is the window maximized? RESTORED title        Does the window have its normal size? VISIBLE title         Is the window visible? ACTIVATED title       Is the window the active window?

'UDesktop' as part of a batch file
When using the tool as part of a batch file two things are relevant: The "/TRY" switch and the way the tool sets the "ERRORLEVEL" variable when it terminates.

There are four combinations that can occur:

normal execution, no error        SET ERRORLEVEL 0 normal execution, error           SET ERRORLEVEL 1, after dialog box "/TRY" used, no error             SET ERRORLEVEL 0 "/TRY" used, error                SET ERRORLEVEL 1

The checks also set the error level, with 0 standing for "TRUE" and 1 for "FALSE". In order to be sure about the meaning of a level of 1, one should make sure that the check does indeed check and not lead to an error.

One should note that the question "Did the check succeed and return TRUE?" as well as the question "Did the tool terminate without error?" translate into the following batch file line:

IF NOT ERRORLEVEL 1 ...

The following batch file condition has definitely not the desired effect because it always evaluates to "TRUE":

IF ERRORLEVEL 0 ...

Examples
The following are examples of single runs of 'UDesktop':

UDesktop SAVE UDesktop LOAD UDesktop SAVE C:\TMP\Config.DTP UDesktop RENAME. Workframe START UDesktop PUT Workframe BEHIND "Desktop Manager" UDesktop MOVE. 200,100 UDesktop /TRY CLOSE Workframe

Versions
The version number is displayed by launching the program without arguments. Version history:


 * 1.0  11/89   First release under OS/2 1.1.
 * 1.1  12/90   Configuration saving extended. Window locking and error handling improved.
 * 2.0  06/92   OS/2 2.0 savvy. Configurations are saved in a textfile.

Copyright (c)
This program is freeware and meant to be distributed freely to anyone who likes it. Any other actions like selling or modifying the program fall under the laws of copyright and are prohibited.

This utility was programmed with Logitech/Multiscope Modula-OS/2. Parts of it Copyright (c) Logitech/Multicope Inc.

'UDesktop' has little connection to Megos' main business of writing taylor-made applications under OS/2 for customers in Switzerland; it is a by-product of our long-lasting relationship with OS/2. However, if you like 'UDesktop' you might like our business applications as well...

If you have any suggestions or questions feel free to contact us:

Megos AG                       Froehlichstrasse 33 5200 Brugg Switzerland

Tel: ++41 56 41 34 17 Fax: ++41 56 41 80 10 BIX: wvogt