Built-in Module RiscLib

risclibexperimental

These modules provide an experimental interface to the RiscOS toolbox.

They provide a class TBObject that implements the common toolbox methods, and derived classes ColourDbox, IconBar, Menu, Quit, SaveAs, Window. They provide a simple event polling system.

Neither the modules or the documentation are complete. I have added methods and objects when I needed to use them. The methods provided just call the toolbox SWIs, and can be inspected by examining the code.

The event polling system works as follows (using !Ibrowse as an example) :

The controlling program imports tbevent. tbevent imports three dictionaries from a module events that include details of the toolbox events, wimp events and wimp messages that the application is interested in. The dictionaries are called edict, wdict and mdict. They contain event or message numbers as keys and names as values. See !ibrowse.py.events for an example.

The program must supply classes with methods to handle these events. The methods will have the same names as the dictionary values.

The program calls tbevent.initialise("<ibrowse$Dir>") supplying an application directory incuding a Resource file ``res'' and a ``Messages'' file.

The program registers instances of the handler classes with tbevent (see below).

The program then calls tbevent.poll() repeatedly.

Toolbox event handling works as follows:

The ancestor object number of the event is used to find a class instance to handle the event. It is looked up in a dictionary tbevent.tbclasses to find the handler, so each class that handles toolbox methods should have a __init__ method that registers itself in this dictionary.

Here is an example from ``!Graph''

class Display(window.Window):
      actions={}                                 #1
      def __init__(self):
          window.Window.__init__(self,"Display") #2
          tbevent.tbclasses[self.id]=self        #3
          self.handle=self.getwimphandle()       #4
          tbevent.winclasses[self.handle]=self   #5

In line #2 the underlying window class is initialised. This creates a toolbox object from a template named ''Display'' (This must be a window object. It should be an ancestor object, but not autocreated). self.id is set to the object identifier. Line #3 now registers the class instance as a toolbox event handler.

If an event now arrives for an object with this ancestor its event number is looked up in edict. The corresponding name should be the name of a method in class Display. It will be called for this class instance.

The class method names are cached in a dictionary called actions, so each handler class should contain an empty dictionary as in line #1.

Some toolbox events will have no ancestor. These will be sent to a class instance registered with a zero identifier. Most programs will have code such as this, which will handle an autocreated bar icon object.

class Orphans: #class to handle events with zero ancestor
      actions={}
      def __init__(self):
          tbevent.tbclasses[0]=self
      def BarClick(self):
          a=Display("dir","Top")
      def E_Q_Quit(self):
          exit()

oi=Orphans()  #create an instance of the class (the only one!)

Wimp event handling is similar. Wimp codes other than 7, 9, 13, 17 and 18 are sent to class instances registered by their wimp window handles. Codes 7, 9 and 13 are given handles of zero. The classes are registered in the dictionary tbevent.winclasses. Lines #4 and #5 in the example above give an example of registration. The names of the actions are obtained from dictionary wdict. Codes not in this dictionary are ignored. Note that wimp and toolbox codes use the same actions dictionary. This means they must have different event numbers. In practice this means not giving low numbers to user defined toolbox events. Starting user defined nubers at 0x1000 is a safe rule.

Messages are handled by a single class instance tbevent.msghandler method names are looked up from the message number in dictionary mdict.

For example here is a trivial message handling class that just handles the quit message.

class Messenger:                #This is the message handler class
      def Wimp_MQuit(self):
          exit()
          
tbevent.msghandler=Messenger()  #Register the instance

Toolbox event methods can examine the toolbox id block as toolbox.idblock. All methods can use the wimp poll block as tbevent.wblock.

There is a simple system to assist with debugging built in to tbevent. The function tbevent.report(string,[priority]) broadcasts a wimp message containing the string (truncated to 200 characters). The application ``!Reporter'' can display these messages. Messages are only sent if priority<=tbevent.usereport, so debugging messages can be suppressed by setting this variable. priority defaults to 16. tbevent.usereport is initially 8. tbevent generates some reports itself, error reports with priority 2, and reports of all events with priority 32.