MoreDesk: SWI Interface for Programmers |
|
|
MoreDesk provides some SWI calls which can be used to drive it from your programs. These calls can read the state of MoreDesk, set which desktop is currently being viewed or raise (or clear) a flashing alert for a window.
In...
| R0 | flags word (see below) | |
| R1 | number of desktop columns | |
| R2 | number of desktop rows |
Out...
| None |
This call will either move the current desktop to a specified location (bit zero of R0 is clear on entry) or it will move by the specified offset from the current desktop (bit zero of R0 is set on entry). All other flag bits are reserved and should be zero.
Note: it takes time for the desktop to be changed so you may have to wait before the change is reflected by SWI MoreDesk_ReadInfo.
Bits one to thirty one of R0 are reserved and should be zero.
This call will read various bits of useful information about the MoreDesk deskspace and state. Unrecognised values of reason code in R0 on entry will result in an error being returned.
In...
| R0 | reason code (0) - read desk space dimensions |
Out...
| R0 | preserved | |
| R1 | total number of desktop columns | |
| R2 | total number of desktop rows | |
| R3 | current desktop column | |
| R4 | current desktop row |
If R0 is 0 on entry, then the call will return the current size of the total desktop space along with the co-ordintes of the active desktop (with 0,0 meaning the 'Home' desktop) so the values of R3 and R4 may be negative on exit.
In...
| R0 | reason code (1) - read desk space limits |
Out...
| R0 | preserved | |
| R1 | number of desktop columns to left of 'home' desktop | |
| R2 | number of desktop columns to right of 'home' desktop | |
| R3 | number of desktop rows above 'home' desktop | |
| R4 | number of desktop rows below 'home' desktop |
If R0 is 1 on entry, then the call will return the dimensions of the total desktop space, relative to the 'Home' desktop. This is useful for understanding the active desktop's co-ordinates. The values returned in R1-R4 will never be negative.
This reason code was introduced in MoreDesk module version 1.14, earlier versions of the module will return junk from this call. You must not use this reason code on any version of the MoreDesk module older than 1.14.
In...
| R0 | reason code (2) - return desktop name string | |
| R1 | desktop row number (may be negative) | |
| R2 | desktop column number (may be negative) |
Out...
| R0 | preserved | |
| R1 | pointer to zero-ternimated desktop name string (may be NULL) | |
| R2 | preserved |
If R0 is 2 on entry, then the call will return a pointer to the name of the specified desktop, which may be NULL. The desktop is specified by giving its co-ordinates relative to the Home desktop. Invalid desktop co-ordinates will result in a NULL pointer being returned.
This reason code was introduced in MoreDesk module version 1.14, earlier versions of the module will return junk from this call and there was a bug in MoreDesk modules 1.14 and 1.15 which also means this call returns junk. You must not use this reason code on any version of the MoreDesk module older than 1.16.
In...
| R0 |
flags word. Bit meaning when set: 0 - R1 is a window handle (else pointer to zero-terminated title string) 1 - open the micro view 2 - open the main window (only for very important events) 3 - flash even when window is in current desktop 4 - cancel flash state after flash time Other bits are reserved, should be zero | |
| R1 | window handle or pointer to zero-terminated title string | |
| R2 | flash duration (centi-seconds) |
Out...
| None |
This SWI will start or stop a flash event for the nominated window. A window can be specified using either its title string (which is compared in a case-insensitive manner) or the window handle. Where multiple windows match a given title, the top-most window in the window stack is selected.
A flash event is used to draw the user's attention to a window, usually off-screen. It is cleared automatically by MoreDesk when the flashing window is brought onto the current desktop.
Application programmers can cause flash events to open the MoreDesk micro view, which will flash the desktop corresponding to the one containing the specified window.
The MoreDesk main window view of the entire desk space can be opened when the flast state is set. However, as the main window is usually large and can cause significant distraction to the user, this should only be done if the reason for the flash event is serious (e.g. something has gone wrong).
The flashing event can either automatically clear itself after an elapsed number of seconds or the alert window will stop flashing but remain in a highlighted state until the user switches onto the desktop which contains the flashing window or brings that window into the current desktop.
A window is defined as being in a desktop if the centre of the window's visible extent (i.e. visible area plus scroll bars, title bar, etc.) lies within the bounds of that desktop.
Note: a user can manually close the main or micro windows after a flash event has opened them. This does not affect the flash states.
To cancel a flash event for a specified window, this SWI is called with R2 set to zero. In this case, only bit zero of R0 is significant.
A flash state can be set to continue indefinitely (meaning until the user brings that window onto the current desktop, or the window is closed, or the flash state is specifically cancelled through a call to MoreDesk). To do this, pass -1 in R2.
Note: closed or iconised windows cannot be assigned a flash state. The act of closing or iconising a window will clear its flash state.
This SWI will return the error “Unknown window to flash” if the specified window is not known to MoreDesk (e.g. pane windows are normally ignored).
prev 