MoreDesk: SWI Interface for Programmers

logo

<-  prev | index | next ->

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.


SWI MoreDesk_Move (&58740)

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.


SWI MoreDesk_ReadInfo (&58741)

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.

This SWI contained a bug prior to MoreDesk module version 1.20 which meant that the meaning of registers R1 and R2 on entry was reversed.


In...
  R0 reason code (3) - return module version number
  R1 sub-reason code - must be zero

Out...
  R0 preserved
  R1 module version number * 100 (e.g. version 1.20 becomes 120)

Return an integer containing the version number of the MoreDesk module, multiplied by 100. For example, MoreDesk module version 1.20 returns the value 120 in R1. This is not the same as the MoreDesk application version number. It is intended that this call be used to determine which (future) features of the MoreDesk module are available.

Future versions of this ReadInfo call may return version information for other parts of MoreDesk by using R1 as the sub-reason code. In this release, only the value zero is supported and all other sub-reason codes will return an error.

This reason code was introduced in MoreDesk module version 1.20, earlier versions of the module will return an error from this SWI.


SWI MoreDesk_FlashWindow (&58742)

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 | index | next ->

Copyright © 2013, 7th software