The Datafile PD-CD 5

home *** CD-ROM | disk | FTP | other *** search

/ The Datafile PD-CD 5 / DATAFILE_PDCD5.iso / utilities / p / python / pyhtmldoc / r / risclib < prev next >

Wrap

Text File | 1996-11-14 | 6KB | 122 lines

<TITLE>RiscLib -- Python library reference</TITLE> Prev: <A HREF="../d/drawf" TYPE="Prev">drawf</A> Up: <A HREF="../r/riscos_only" TYPE="Up">RISCOS ONLY</A> Top: <A HREF="../t/top" TYPE="Top">Top</A> <H1>13.5. Built-in Module <CODE>RiscLib</CODE></H1> @modindex{risclib}experimental These modules provide an experimental interface to the RiscOS toolbox. They provide a class <CODE>TBObject</CODE> that implements the common toolbox methods, and derived classes <CODE>ColourDbox</CODE>, <CODE>IconBar</CODE>, <CODE>Menu</CODE>, <CODE>Quit</CODE>, <CODE>SaveAs</CODE>, <CODE>Window</CODE>. 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 <CODE>tbevent</CODE>. <CODE>tbevent</CODE> imports three dictionaries from a module <CODE>events</CODE> that include details of the toolbox events, wimp events and wimp messages that the application is interested in. The dictionaries are called <CODE>edict</CODE>, <CODE>wdict</CODE> and <CODE>mdict</CODE>. They contain event or message numbers as keys and names as values. See @verb{!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 @verb{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 <CODE>tbevent.poll()</CODE> 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 <CODE>tbevent.tbclasses</CODE> to find the handler, so each class that handles toolbox methods should have a <CODE>__init__</CODE> method that registers itself in this dictionary. Here is an example from ``!Graph'' <UL COMPACT><CODE>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 </CODE></UL> In line @verb{#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). <CODE>self.id</CODE> is set to the object identifier. Line @verb{#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 <CODE>edict</CODE>. The corresponding name should be the name of a method in class <CODE>Display</CODE>. It will be called for this class instance. The class method names are cached in a dictionary called <CODE>actions</CODE>, so each handler class should contain an empty dictionary as in line @verb{#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. <UL COMPACT><CODE>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!) </CODE></UL> 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 <CODE>tbevent.winclasses</CODE>. Lines @verb{#4} and @verb{#5} in the example above give an example of registration. The names of the actions are obtained from dictionary <CODE>wdict</CODE>. Codes not in this dictionary are ignored. Note that wimp and toolbox codes use the same <CODE>actions</CODE> 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 <CODE>0x1000</CODE> is a safe rule. Messages are handled by a single class instance <CODE>tbevent.msghandler</CODE> method names are looked up from the message number in dictionary <CODE>mdict</CODE>. For example here is a trivial message handling class that just handles the quit message. <UL COMPACT><CODE>class Messenger: #This is the message handler class def Wimp_MQuit(self): exit() tbevent.msghandler=Messenger() #Register the instance </CODE></UL> Toolbox event methods can examine the toolbox id block as <VAR>toolbox.idblock</VAR>. All methods can use the wimp poll block as <VAR>tbevent.wblock</VAR>. There is a simple system to assist with debugging built in to <CODE>tbevent</CODE>. The function <CODE>tbevent.report(string,[priority])</CODE> broadcasts a wimp message containing the string (truncated to 200 characters). The application ``!Reporter'' can display these messages. Messages are only sent if <CODE>priority<=tbevent.usereport</CODE>, so debugging messages can be suppressed by setting this variable. <CODE>priority</CODE> defaults to 16. <CODE>tbevent.usereport</CODE> is initially 8. <CODE>tbevent</CODE> generates some reports itself, error reports with priority 2, and reports of all events with priority 32.