UDesktop Reference Manual: Difference between revisions

From OS2World.Com Wiki
Jump to navigation Jump to search
m (spelling hyph)
Line 3: Line 3:
Then you are in need of 'UDesktop', the "automatic mouse".
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 batch files 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 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.


'UDesktop' is Freeware. Feel free to use and distribute it further. However note that other actions are restricted by copyright - see the
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.
copyright section at the end of this file.
 
==REFERENCE MANUAL==
 
 
===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===
===Windows===
Basically 'UDesktop' operates on ##PM_windows. But not all 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.
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
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.
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
As a simplification, in the following mostly "window" is used instead of "frame window".
of "frame window".


Text windows are a special class of frame windows. Text windows are
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.
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
The following attributes of a window are known to 'UDesktop' and can be changed:
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 ##screen_configuration. For the screen configuration it does not matter whether a window or its icon is visible or not; it may be currently covered by other windows.


- location on the screen
'UDesktop' can only manipulate existing windows but cannot create windows.
- 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
##screen_configuration. For the screen configuration it does not
matter whether a window or its icon is visible or not; it may be
currently covered by other windows.
 
'UDesktop' can only manipulate existing windows but cannot create
windows.


===Running 'UDesktop'===
===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.


In the following it is assumed that 'UDesktop' is started from an
'UDesktop' is a standalone executable ".EXE" program and does not need any other file. One can start the tool in the active window with:
"OS/2 window" i.e. from command line in a text window.
UDesktop ...
 
'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:
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 ...
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.


This second way eliminates the problems mentioned and generally results
There is the second possibility of executing the tool in an own session with:
in much less unnecessary window redraws and restores.
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.
Normally 'UDesktop' just runs silently without displaying something.
Only in the case of an error a dialog box appears containing an
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.
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===
===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.


'UDesktop' identifies windows by the ##window_title i.e. the text in
The following window titles are "reserved" and have a special meaning when used as arguments for 'UDesktop':
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
   .        the frame window where 'UDesktop' was started
   active  the frame currently active
   active  the frame currently active
Line 113: Line 59:
   next    the window immediately in front of the start window (cyclic)
   next    the window immediately in front of the start window (cyclic)
   prev    the window immediately behind 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".


More than one of these can be applied by concatenating them with a
"." 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).
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:


If a window title contains blanks it has to be surrounded with quotes or double quotes as in the following examples:
   'Desktop Manager'
   'Desktop Manager'
   "Jack's Window"
   "Jack's Window"
 
If the tool outputs a title to the user or a file it doubles all double quotes and vice versa.
If the tool outputs a title to the user or a file it doubles all
double quotes and vice versa.


===Command Notation===
===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:
Because 'UDesktop' implements something like a tiny command language
*Parenthesis "(" and ")" are not part of the command string but part the notation: They enclose what results in a single argument.
a notation for the commands is needed. The following rules (close to
*Brackets "[" and "]" are also part of the notation and denote an argument that can be omitted
what is called "EBNF") apply:
*A vertical bar "|" means that either the left or the right argument must be chosen.
 
- 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===
===Commands===
The general format for running 'UDesktop' from command line:
The general format for running 'UDesktop' from command line:
 
[ START ] UDesktop [ /TRY ] [ /FONT ] command [ arguments ]
  [ 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.
 
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====
 
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 "/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====
 
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 configuration 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.
The "/FONT" switch is valid for any command. It tells the tool to
Otherwise the font size would be always incorporated in the configuration set. We hope that will be fixed in the future (so god will).
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 [ fileName ]====
Save the current screen configuration.
Save the current screen configuration.


The current screen configuration - all data relevant to 'UDesktop'
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
(location, size etc., see above) about all windows currently 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
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.
"/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
It is a good idea to use the "START" method of running 'UDesktop' when using the "SAVE" command.
using the "SAVE" command.


====LOAD [ fileName ]====
====LOAD [ fileName ]====
Load a screen configuration previously saved.
Load a screen configuration previously saved.


This command is the opposite of the "SAVE" command. It moves, resizes
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.
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
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.
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
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.
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
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.
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
One can safely edit the configuration file with any common editor since syntax errors are caught and made harmless.
syntax errors are catched and made harmless.


The "SAVE" command is especially useful to set up a defined screen
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.
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====
====RENAME oldTitle newTitle====
Change a window title.
Change a window title.


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


The program that is running and controling the window that has the title
The program that is running and controlling 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.
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 )====
====PUT title ( TOP | BOTTOM | BEHIND otherTitle )====
 
Change the relative position of the window with the given title in respect to other windows.
Change the relative position of the window with the given title in
respect to other windows.


====SETFONT title ( LARGE | SMALL | x )====
====SETFONT title ( LARGE | SMALL | x )====
Change the font size of a text window.
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.1: This command is equivalent to the menu choice
*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).
  "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 title x,y====
Move the window to a given position on the screen.
Move the window to a given position on the screen.


The screen coordinates "x" and "y" are given in pixels. As a general
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.
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".
This command is equivalent to the System Menu choice "Move".


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


Line 263: Line 141:


====MINIMIZE title====
====MINIMIZE title====
Minimize the window.
Minimize the window.


Line 269: Line 146:


====MAXIMIZE title====
====MAXIMIZE title====
Maximize the window.
Maximize the window.


Line 275: Line 151:


====RESTORE title====
====RESTORE title====
Restore the window to its previous size.
Restore the window to its previous size.


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


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


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


After this command the window completly disappears from the screen: It
After this command the window completely 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.
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.
This command has no interactive equivalent.


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


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


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


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


====DEACTIVATE title====
====DEACTIVATE title====
Deactivate the window.
Deactivate the window.


Line 315: Line 180:


====CLOSE title====
====CLOSE title====
Close the window.
Close the window.


This command is equivalent to selecting "Close" in the System Menu of
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.
the window and telling "yes" in the confirm dialog box that appears.
One should therefore be careful when using this command.


====DESCRIBE ( title | ALL )====
====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.
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====
====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
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.
next chapter.
  EXIST title            Is there a window with the given title?
  EXIST title            Is there a window with the given title?
  IS title1 title2      Are "title1" and "title2" same?
  IS title1 title2      Are "title1" and "title2" same?
Line 350: Line 200:


==='UDesktop' as part of a batch file===
==='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.
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:
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.


  normal execution, no error        SET ERRORLEVEL 0
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:
  normal execution, error            SET ERRORLEVEL 1, after dialog box
IF NOT ERRORLEVEL 1 ...
  "/TRY" used, no error              SET ERRORLEVEL 0
The following batch file condition has definitely not the desired effect because it always evaluates to "TRUE":
  "/TRY" used, error                SET ERRORLEVEL 1
IF ERRORLEVEL 0 ...
 
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===
===Examples===
The following are examples of single runs of 'UDesktop':
The following are examples of single runs of 'UDesktop':
 
UDesktop SAVE
  UDesktop SAVE
UDesktop LOAD
  UDesktop LOAD
UDesktop SAVE C:\TMP\Config.DTP
  UDesktop SAVE C:\TMP\Config.DTP
UDesktop RENAME . Workframe
  UDesktop RENAME . Workframe
START UDesktop PUT Workframe BEHIND "Desktop Manager"
  START UDesktop PUT Workframe BEHIND "Desktop Manager"
UDesktop MOVE . 200,100
  UDesktop MOVE . 200,100
UDesktop /TRY CLOSE Workframe
  UDesktop /TRY CLOSE Workframe


===Versions===
===Versions===
 
The version number is displayed by launching the program without arguments. Version history:
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.0  11/89  First release under OS/2 1.1.
*  1.1  12/90  Configuration saving extended. Window locking and error handling improved.
*  1.1  12/90  Configuration saving extended. Window locking and error handling improved.
Line 400: Line 231:


===Copyright (c)===
===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 program is freeware and meant to be distributed freely to anyone
This utility was programmed with Logitech/Multiscope Modula-OS/2. Parts of it Copyright (c) Logitech/Multiscope Inc.
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
'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...
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:
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
                        Megos AG
:Fax: ++41 56 41 80 10
                        Froehlichstrasse 33
:BIX: wvogt
                        5200 Brugg
                        Switzerland
 
                        Tel: ++41 56 41 34 17
                        Fax: ++41 56 41 80 10
                        BIX: wvogt


[[Category:Software]]
[[Category:Software]]

Revision as of 19:17, 2 March 2018

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 batch files 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 ##screen_configuration. For the screen configuration it does not matter whether a window or its icon is visible or not; it may be currently covered by other windows.

'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 configuration 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 configuration 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 safely edit the configuration file with any common editor since syntax errors are caught 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 controlling 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 completely 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/Multiscope 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