Lush provides all the necessary graphic primitives for programming a graphics interface.

• Output primitives include functions for opening windows and functions for producing various elementary drawings. Lush supports multiple fonts, multiple windows and even multiple window systems.
  
• Input functionalities are also present. Lush gathers all events in a common event queue. There are functions for inspecting this event queue ( checkevent and waitevent ). Hook functions are called when events are occuring while Lush is waiting for user commands ( event-hook and idle-hook ).
  

It is rather easy to build simple graphic interfaces using these primitives. For instance, the function snpaint implements a simple drawing program for drawing lines and rectangles using low level primitives.

Graphic interfaces however become quickly complex. The class browser described in the last chapter of this document contains various features, like menus, buttons, requesters, selectors and scrollbars. A direct program would be overwhelmingly complex.

This is why people have developped various toolkits which handle automatically a large part of this complexity. The Ogre library is such a toolkit entirely written using the Lush object oriented language. This manual describes how to build programs with this library.

In the Ogre library, each component of a graphics interface, a button for example, is implemented as an object which is an instance of a subclass of class VisualObject .

The class of such an object defines both the appeareance of the object and its response to user input. Defining a new type of object (e.g. a menu) is thus just a matter of defining a new subclass of VisualObject .

There is a wide variety of such object classes:

• Basic objects are the major components of an interface. For instance, buttons, strings or check boxes are visible and respond to user interaction.
  
• Container objects are rectangular areas containing other objects and maintaining a certain layout. For instance there is a class Column which maintain several objects aligned in a column.
  
• Window objects are special container object affected to a window on the screen. Every object inserted in a window object appears into the window and is eligible for receiving user events.
  

There are two programming levels with the Ogre library. At the simplest level, you just use the provided classes for defining your interface. At the second level, you define subclasses of the standard Ogre classes in order to create new kind of graphic components.

? (ogre)
 [ogre.lsh] (autoload)
= idle-hook

Let us then open a window ww containing a message string and a button arranged in a column named cc :

? (setq ww 
    (new windowobject 0 0 400 300 "Essai"
      (setq cc (new column (new string "Press button to beep")
                           (new stdbutton "Beeper"
                                    (lambda(c) (beep))) ) ) ) )
= ::windowobject:e3100

When you click on the button, the callback function (lambda(c) (beep)) is called and produces an audible beep. Let us add now a check box into the column:

? (==> cc insert (new checkbox "check me"  
                   (lambda(c) 
                        (printf "Check box state is %l\n" 
                                  (==> c getdata))))))
= ()

The callback function takes one argument. This argument is the check box object that we can query using method getdata . Let us add now an editable string named ee into the column:

? (==> cc insert (setq ee (new editstring 18 "hello")))  
;; Argument 18 is the field width.
= ()
? (==> ee setdata "hello people")
= ()
? (==> ee getdata)
= "hello people"

Again we can manipulate the state of the editable string using method setdata and getdata . You may have noticed that the button width has changed when we have inserted the editable string. The column indeed manage its contents in order to keep them properly aligned. We can indeed move and resize the column as a whole:

? (==> cc move 50 70)
= (50 20 129 84)
? (==> cc resize 250 120)
= (50 20 250 100)

We can even add into the column a small object which lets you move the column with the mouse:

? (==> cc insert (new dragarea 50 20))
= () 

Arguments 50 and 20 are the width and height of this object. Since the drag area is inserted into a column, its width is adjusted to the column width.

Let us add a row with two exclusive buttons:

? (==> cc insert (new row (new radiobutton "choice1")
                          (new radiobutton "choice2") ) )
= ()

We can get (or set) the complete state of the column with a single message getdata (or setdata ):

? (==> cc getdata)
= (() "hello people" () t)
? (==> cc setdata '(t "goodbye" t ()))
= ()

The Ogre library provides many more complex object, as shown in the following example:

? (setq h (new filerequester ww))
= ::filerequester:f3ef0
? (==> h popup)
= ::filerequester:f3ef0
? (==> h getdata)
= "/home/leon"

Let us add now a button for destoying the window.

? (==> ww insert (new stdbutton "Bye Bye." 
                     (lambda(c) (==> thiswindowobject delete)) ) )
= ()

This button ends the tutorial.

Here is an example of a very Lush script that opens up an Ogre window and runs until that window is closed by the user:

  #!/bin/sh
  exec lush "$0" "$@"
  !#
  ;; A simple Ogre GUI demo
  (ogre)
  (wait (new autowindowobject 10 10 100 100 "Simple Lush GUI Demo" 
          (new column
            (new stdbutton "    hit me    " (lambda (c) (printf "OUCH\n")))
           (new stdbutton "    feed me   " (lambda (c) (printf "CRUNCH\n"))))))

In the above example, the argument to wait is the WindowObject (i.e. the Ogre window) in which the buttons reside. When the user closes the window, this object is destroyed, hence wait returns, terminating the script.

Using wait in a script that runs an Ogre application is a necessity because scripts terminate as soon as the evaluation of the content of the script terminates. Since the constructors of Ogre applications return immediately (to allow for Ogre apps to run simultaneously with the Lush main prompt), the script woould open the Ogre window and terminate immediately if we did not use wait .

The kernel of the Ogre library ensures these interaction by defining how messages are propagated between the objects in a graphic interface.

Repainting is managed asynchronously. When you want to redraw an object, you must send a message expose to this object to tell the Ogre system to schedule a repainting operation. When the system becomes idle, the Ogre library sends a repaint message to all objects to repaint with a proper ordering which ensures that the topmost objects are repainted last.

Similarly, you never change the location of an object directly. You send message move , resize or moveresize which tell the Ogre system to relocate an object. The Ogre library then enforces all the rules of the container objects, performs a global recomputation of the location of all objects and places the objects by sending them a message geometry .

In general, most operation on the Ogre objects are implemented using two messages.

• The request message (e.g. expose ) is used by a program to tell the Ogre library that you wish to perform a certain operation.
  
• The implementation message (e.g. repaint ) is only called by Ogre to perform the operation and update all the other objects accordingly.
  

When you want to perform a certain operation, you must call the request message and not the implementation message. The Ogre library will call the implementation message for you at a proper time and with the proper order.

When you define a new class of Ogre objects, you must define the implementation method only. The corresponding request message will be inherited from the superclass.

Here is a list of the most useful message pairs:

+-------------------+------------------+------------------+
| Operation         | Request          | Implementation   |
+-------------------+------------------+------------------+
| Drawing           | expose           | repaint          |
|                   |                  | repaint-bw       |
|                   |                  | repaint-color    |
|                   |                  | backpaint        |
|                   |                  | backpaint-bw     |
|                   |                  | backpaint-color  |
+-------------------+------------------+------------------+
| Moving            | move             | geometry         |
|   and resizing    | moverel          | manage-geometry  |
|                   | resize           | compute-geometry |
|                   | moveresize       |                  |
+-------------------+------------------+------------------+
| Making an         | insert           | realize          |
|   object visible  | remove           |                  |
+-------------------+------------------+------------------+

• ``User classes'' define the most useful graphics components. For instance, class StdButton defines a standard push button, class Menu manages popup menus and class Requester manages subwindows which pop up to request information from the user.
  
• ``Abstract classes'' are located on top of the class hierarchy. They define slots and request methods for managing these interactions in behalf of instances of their subclasses. Abstract classes are provided as a choice of superclasses for defining new classes of Ogre objects.
  

Here is a display of the current class hierarchy in the Ogre library. Classes displayed with a star are the abstract classes.

  visualobject *
    control *
      editstring
        editnumber
        editsecretstring
      button *
        stdbutton
          tinybutton
        checkbox
          radiobutton
        filereqbutton
      menuitem
      knob *
        dragarea
        sizearea
      slider *
        hslider
        vslider
        scrollbar *
          hscrollbar
          vscrollbar
      textpane
    container *
      form *
        windowobject *
          autowindowobject *
        requester
          warningrequester
          errorrequester
          yesnorequester
            filerequester
            printrequester
         viewer
         selector
         edittext
       column
         menupopup
       row
       grid
       frame
         framesize
       viewerhole
    emptyspace
    darkspace
    string
    icon
    menu
      choicemenu

Here is the use of the main abstract classes:

• Class VisualObject is the root of the Ogre class tree. It defines how objects are located and repainted. It also defines the default event processing messages.
  
• Class Control is the subclass of the simplest interactive objects. Such objects may be enabled or disabled. They may call a callback function when the user requests it.
  
• Class Button defines common messages handled by an object responding to a single mouse click.
  
• Class Knob defines common messages handled by an object which requests a geometry change of its container. For instance, inserting a DragArea in a container allow the user to move the container by clicking on the dragarea object.
  
• Class Slider and Scrollbar define the common methods for objects allowing the user enter a numerical value proportional to the location of a visible cursor.
  
• Class Container is the superclass of all objects containing other objects. It defines methods used for dispatching the events to the proper objects as well as methods for enforcing a certain layout.
  
• Class Form is a special container used for defining new objects composed of other objects. For instance, a Viewer is a Form containing two scrollbars and a container whose contents is moved according to the scrollbar position.
  
• Class WindowObject is the most important class. It defines a container object attached to a graphic window on the screen. Every object inserted in a window object becomes visible and is eligible for receiving events.
  

This function initializes the library and sets up the event dispatcher. In particular, it creates the object ogre-task and defines the functions event-hook and idle-hook . If the library was already initialized, function Ogre returns immediatly.

The object located in variable ogre-task is set up by function ogre . This object performs three central tasks in the Ogre library:

• It records all operations requested by the user and delayed by the library. This is the case of most repainting requests.
  
• It starts a repainting operation whenever function idle-hook is called.
  
• It sends event messages to the proper window object whenever function event-hook is called.
  

When Lush is waiting for user commands on the standard input, the Ogre library manages events asynchronously. The user can thus either type lisp commands or activate graphic interfaces.

When a Lush program is running, however, the Ogre library manages events when the function process-pending-events is called. It is a good practice to call this function a few times during long programs.

The Ogre library runs Lush functions whenever an event occurs.

An error condition occurs when these functions are incorrectly designed. The error message is printed as usual, but you are not prompted for a debug toplevel.

An interruption occurs if you type Ctrl-C in the Lush console. The break message is printed as usual, but you are not prompted for a break toplevel.

If you wish to be prompted for these debugging utilities, you must redefine functions ogre-debug-hook and ogre-break-hook . Here is a simple way to achieve this:

        (setq ogre-debug-hook nice-debug-hook)
        (setq ogre-break-hook nice-break-hook)

• A black and white screen is barely able to display a few levels of gray using special dithering patterns. Objects must be rendred using simple and visible graphics.
  
• On the other hand, a color screen is able to render three dimensional looking objects using several colors for rendering the various shadow level.
  

Ogre provides a way to test if you are using a black and white or a color screen. It also provides several utility functions for displaying three dimensional looking objects.

If you are using a black and white display, this variable contains the empty list. You can then select three colors using function color .

• Color color-fg is the foreground color (usually black),
  
• Color color-bg is the background color (usually white)
  
• Color color-gray is a 50% dithered gray shade used for rendering disabled objects.
  

If you are using a color display, this variable contains an array containing the color numbers used by Ogre for displaying an object. Several variables are used to name these colors:

palette-left                 (for rendering light)
palette-right                (for rendering shadow)
palette-up                   (for rendering raised objects)
palette-down                 (for rendering depressed objects)     
palette-disabled             (for rendering disabled texts)
palette-selected             (for rendering selected objects)

This function creates a new palette array whose dominant color is defined by its RGB component r , g and b .

You can then store the resulting array into variable color-palette for redefining the default palette. You can also pass the new palette to an existing window object using message palette .

This function returns the color number for the color named n in the current palette. Although any number can be passed as argument n , we suggest using one of the predefined symbols palette-left , palette-right , palette-up , palette-down , palette-disabled or palette-selected for specifying a color. The resulting color number can then be applied using function color .

This function is equivalent to:

  (color-palette <colname>)

This function sets the current color to the color named n in the current palette. Although any number can be passed as argument n , we suggest using one of the predefined symbols palette-left , palette-right , palette-up , palette-down , palette-disabled or palette-selected for specifying a color.

This function is equivalent to:

  (color (getcolor <colname>))

This function fills a rectangle with the background color palette-up of the current palette. The 3d rendering functions are designed for being called on such a background.

This function draws the border of a rectangle using the colors defined in the current palette. The border only is drawn and appears as a slightly raised line.

This function draws the border of a rectangle with round corners using the colors defined in the current palette. The border only is drawn and appears as a slightly raised line.

This function fills a rectangle using color number c and draws a border in order to give the illusion of a rectangle located above the background.

The default value for c is the color number indicated by palette-up .

This function fills a rectangle with the color number c and draws a border in order to give the illusion of a rectangle located below the background.

The default value for c is the color number indicated by palette-down .

This function fills a rectangle with round corners using color number c and draws a border in order to give the illusion of a rectangle located above the background.

The default value for c is the color number indicated by palette-up .

This function fills a rectangle with round corners using the color number c and draws a border in order to give the illusion of a rectangle located below the background.

The default value for c is the color number indicated by palette-down .

This function fills a circle using color number c and draws a border in order to give the illusion of a circle located above the background.

The default value for c is the color number indicated by palette-up .

This function fills a circle using color number c and draws a border in order to give the illusion of a circle located below the background.

The default value for c is the color number indicated by palette-down .

Class VisualObject however defines most request messages which are inherited by the graphic components. It also defines the default implementation of most implementation messages.

Four slots are defined by class VisualObject :

(defclass visualobject object
  (rect (0 0 0 0))
  oldrect
  itscontainer
  window )

• Slot window is the descriptor of the window that contains the object. This slot is set as soon as a window is associated to the object.
  
• Slot itscontainer is set when the object is inserted into a container. It indicates which container (the father) manages this object.
  
• Slot rect is a list (x y w h) that indicates the rectangle associated to the object in the window coordinates.
  
• Slot oldrect is a temporary storage used by method moveresize to store the last acknowledged geometry of an object. This slot is non null whenever a geometry change has been requested.

  
  

This constructor is seldom used for creating new instances. Derived classes (e.g. Control ) usually call this constructor method within their own constructor method in order to initialize the VisualObject part of their instances.

• Repainting the graphic interface components
  
• Changing the geometry of graphic interface components.
  

Unless you have a thorough knowledge of the internals of Ogre, you should neither redefine nor override these messages when defining a subclass of VisualObject .

Exposure messages are propagated down until they reaches the window object. The clipped rectangle are then added to the damaged area list. Repainting is usually performed when the event queue becomes empty.

This request is then signaled to the object's container which gets a chance to redefine its own geometry and to enforce a particular layout. When these recomputations are finished, the Ogre library effectively calls method geometry to relocate the objects.

Method geoemtry is normally called by the method manage-geometry defined by the container objects for enforcing a particular layout. You may call this method directly (this is a backward compatibility requirement), although it is more efficient to use method moveresize .

• Method realize is called whenever an object is associated to or dissociated from a window. Redefining a realization method allows for precomputing font sizes and color numbers at once.
  
• The geometry computation method is called whenever the geoemtry requirement of an object may have changed. This method defines the minimum size of a graphic object.
  
• Repaint methods are called when the Ogre library detects that a part of the object rectangle has been damaged, either because method expose has been called or because the object has been moved or uncovered by another object.
  
• Events methods are called whenever the user performs certain mouse of keyboard actions. They define what actions are performed in response to user events. Event messages are documented in the next section.

  
  

• An object is realized when it is inserted into a realized container. A window object is always realized. When an object becomes realized, method realize is called with a valid window descriptor as argument window . Method realize then sets the slot window , compute the geometry requirement of the object and calls expose in order to paint the object.
  
• An object is unrealized when it is removed from its container. Method realize is then called with an empty list as argument.
  

The default definition of method realize is given below.

(defmethod visualobject realize (w)
  (when (setq window w)
    (==> this compute-geometry)
    (==> itscontainer change-geometry) )
  (==> this expose rect) )

Subclasses of VisualObject may override this default definition. The new definition however must call the superclass method realize in order to perform the essential tasks described above.

Before overriding method realize , you should also consider overriding method compute-geometry instead of method realize .

This method must either return an empty list or compute the minimal size of the object's rectangle and enforce this minimal size by sending a message resize and return the new rectangle rect .

The default method compute-geometry just returns the empty list. Class String for instance overrides this method to compute the size of the string text and resizes the string object to the correct size.

The default method backpaint tests wether you have a black and white or a color display and calls method backpaint-bw or backpaint-color respectively. It is therefore advisable to override methods backpaint-bw and backpaint-color instead of backpaint .

The default backpaint-bw method just clears the object's rectangle with the background color color-bg . This is suitable for most cases.

The default backpaint-color method just clears the object's rectangle with the background color defined in the current palette. This is suitable for most cases.

The default method repaint tests wether you have a black and white or a color display and calls method repaint-bw or repaint-color respectively. It is therefore advisable to override methods repaint-bw and repaint-color instead of repaint .

The default method repaint-bw does nothing.

The default method repaint-color does nothing.

Whenever the user performs certain mouse of keyboard actions, the Lush kernel generates an event as explained in the preceding chapter.

When the Ogre library detects an event in a window, it builds an ordered list of objects eligible for handling the event. An event message is then send to the object with highest priority. If the event method returns the symbol ignored , the library proceed with the next object in the ordered list. This process stops as soon as an object accepts the event (i.e. until an event message returns a value different from symbol ignored .)

Starting with the highest priority, the objects eligible for receiving event messages are:

• The toplevel container,
  
• The chain of embedded containers (if any) managing the topmost object,
  
• The topmost object located below the mouse cursor,
  
• The current actived control object of the window. Activation is discussed later in section ``Control''.
  

Class VisualObject defines a default method for the event messages. These default methods just reject the event by returning symbol ignored .

In practice, the default event rejection mechanism ensures that mouse events are handled by the object located below the mouse cursor and keyboard events are handled by the actived objects. It is however possible to change these settings by overriding the event methods of objects with a higher priority.

Method mouse-down is called when the mouse button is depressed. Arguments x1 and y1 indicate the location of the mouse cursor in the current window when the mouse button has been depressed.

You can use function eventinfo to find the name of the mouse button and the state of the shift and control keys. Names returned by function eventinfo are quite machine dependent however.

Method arrow-left is called whenever the user types the left arrow key. Arguments x and y are the location of the mouse cursor when the key was hit.

You can use function eventinfo to find the exact name of the key and the state of the shift and control keys. Key names returned by function eventinfo are quite machine dependent however.

Method arrow-right is called whenever the user types the right arrow key. Arguments x and y are the location of the mouse cursor when the key was hit.

You can use function eventinfo to find the exact name of the key and the state of the shift and control keys. Key names returned by function eventinfo are quite machine dependent however.

Method arrow-up is called whenever the user types the up arrow key. Arguments x and y are the location of the mouse cursor when the key was hit.

You can use function eventinfo to find the exact name of the key and the state of the shift and control keys. Key names returned by function eventinfo are quite machine dependent however.

Method arrow-down is called whenever the user types the down arrow key. Arguments x and y are the location of the mouse cursor when the key was hit.

You can use function eventinfo to find the exact name of the key and the state of the shift and control keys. Key names returned by function eventinfo are quite machine dependent however.

Method help is called whenever the user types the system dependent help key. Arguments x and y are the location of the mouse cursor when the key was hit.

The help key under Windows is function key F1. The help key under X11 can be configured using program xmodmap .

You can use function eventinfo to find the exact name of the key and the state of the shift and control keys. Key names returned by function eventinfo are quite machine dependent however.

Method fkey is called whenever the user types a key which does not correspond to an ASCII character and yet cannot be processed as an arrow key or a help key. You must then use function eventinfo to analyze the keyname and process the event.

Since key names returned by function eventinfo are quite machine dependent, your event handling procedure should use this name as a hint rather than expecting well defined values.

Remark: All operating systems define certain hot keys for various purposes. Lush cannot override these assignments. Under Windows for instance, keys F9, F10 and CTRL-F4 are directly processed by the operating system and never passed to WinLush.

Class Control is the abstract class for interactive graphics objects like buttons, check boxes, menu items, etc...

Since class Control is a subclass of class VisualObject , all the properties and methods of class VisualObject also apply to class Control . In addition, class Control provides more support for defining the interactive graphics objects.

• Class Control provides standard methods for enabling or disabling a control object. Slot disabled contains a non nil value when a control is disabled.
  
• Class Control provides standard methods for changing the activation status of a control object.
  
• Class Control defines standard methods for changing the appearance of an object. Slot text contains whatever data represents the appearance of an object.
  
• Class Control defines standard methods for storing and handling the state resulting of user interaction. Slot data contains whatever data represent this state.
  
• Class Control stores a callback function in slot callback . This function is called when the user performs certain action defined in by implementation of the specific control object.
  

Creates and return a new instance of class Control . Arguments w and h are the width and the height of the control object. Argument f is the callback function for this control object.

This constructor is seldom used for creating new instances. Derived classes (e.g. Button ) usually call this constructor method within their own constructor method in order to initialize the Control part of their instances.

The enabled/disabled status of a control object is stored in the slot disabled defined by class Control .

• Slot disabled contains () if the object is enabled.
  
• Slot disabled contains a number (the disable count) is the object is disabled.
  

Implementation methods usually test slot disabled before performing their task. Repainting methods must change the rendering colors according to the enabled/disabled status of the object is disabled. Event methods must ignore event messages when the object is disabled.

Two request methods, enable and disable , are defined by class Control for changing the enabled/disabled status of an object:

The disabled count feature proves useful for disabling an object either permanently or temporarily:

• For permanently enabling or disabling a control object whose state is unknown, enable it first and possibly disable it.
  
• For temporarily disabling an object, just disable it. It will retrieve its previous state when you will enable it again.

  
  

If however an error occurs during the program execution, the button would remain disabled. The best way to solve this problem consists in creating a lock object defined by class DisableLock .

If you wish to temporarily disable object c1 to cn , proceed as follows:

(let ((lock (new DisableLock c1...cn)))
        ;;; call your Lush program here
        (......) )

When created, the lock object sends a message disable to the objects c1 to cn . The lock is destroyed when you leave the let instruction. The lock destructor then sends a messages enable to our objects c1 to cn .

If an error occurs during the execution of the Lush program, the lock is destroyed by the garbage collector and the objects retrived to their initial state.

Activation is especially useful for redirecting keyboard events toward objects containing some editable text. Having the keyboard events processed by the object located under the mouse often seems unnatural because the keyboard does not move physically like a mouse.

The user activates such an editable object with a mouse click in the object rectangle. It is customary in Ogre that the editable objects ignore the keyboard events unless they are active. Most keyboard events are then unconditionnally directed to the active object without regard to the position of the mouse cursor.

On the other hand, it is often useful to implement accelerator keys for performing tasks usually achieved by menu items or buttons. Accelerator key events must be defined by the containers managing the related objects. This definition ensures that accelerator keys events are not sent to the active object but handled directly.

The activation status of a control object is stored in slot activated (sic) defined by class Control . This slot contains a non nil value if the control object is active. Implementation methods of editable objects usually test slot activated before performing their task. Repainting methods must indicate the activation status of an object. Event methods must ignore event messages unless the object is actived.

Two request methods are defined by class Control for testing or changing the activation status of an object. These methods ensure that one object only is actived in a given window.

Two request methods are defined by class Control for obtaining and changing the contents of this slot:

Since this change causes a general change in the object appearance, the object is sent a message compute-geometry for redefining its geometry requirements and a message expose for updating the display. Sending message settext sometimes triggers a global relocation of all objects in the window.

Three methods hasdata , setdata and getdata are used for obtaining and changing the state of a control object. These methods are more implementation method than request methods. Several subclasses of Control override these methods in order to pre-process or post-process the state information.

These methods are mostly useful because they provide an abstract way to save and restore the state of a collection of control objects. For instance, a container object can save or restore the state of all its descendants with a single message.

The default method sets the slot data of the target object to the value given by argument d . Since this change usually changes the object appearance, the object is sent a message expose for updating the display.

The default method just returns the contents of slot data . It is prefered to use this method rather than accessing directly the slot data because complex control objects may use other slots for controlling the state of the object.

Method hasdata is used to test if an object provides an adequate implementation for methods setdata and getdata . The default method hasdata indicated that there is some state information in the control object. Certain subclasses, like push button, override this method in order to signal that they carry no state information.

Each control object has a callback function. Callback functions are executed when certain event messages are received. For example, a push button executes the callback function when it is depressed.

Callbacks functions are called with one argument which is the caller object. They are executed within the caller scope and therefore directly access the slots of the caller object. In addition certain local variables are set:

• Variable thiswindowobject always refers to the toplevel container of the control object. See the discussion on class WindowObject for more information.
  
• Variable thisrequester possibly refers to the closest requester containing the control object. See the discussion on class Requester for more information.
  
• Variable thisform possibly refers to the closest form containing the control object. See the discussion on class Form for more information.
  
• Variable thismenu possibly refers to the menu object containing the menu item which has launched the callback function. See the discussion on class Menu for more information.
  

Three methods are implemented by class Control for handling callback functions.

The default implementation defined by class Control just calls method execute . Subclasses of Control usually override method trigger by sending false event messages to the object.

Class Container is the abstract class for container objects. A container object manages several objects called its sons. Sons are only visible through the rectangle of the container. The container dispatches event messages, propagates repainting messages, controls the geometry of its sons and performs a couple of other critical tasks.

Since class Container is a subclass of class VisualObject , all the properties and methods of class VisualObject also apply for class Container . Class Container however defines new slots and new methods for handling container objects.

• Slot contents contains a list whose elements (son x y w h) point to the managed objects son and cache the coordinates for their rectangles.
  
• Class Container defines private method for implementing the core of the Ogre library. These methods deal with the repainting process and the geometry management.
  
• Class Container defines public request methods for handling several control objects as a whole. Method enable and disable allow you to disable or enable all the control objects located in a container. Method getdata returns a list containing the states of all control objects located in the container. This list is built by sending messages getdata to the control objects. Method setdata takes such a list as argument and sets the state of all control objects located in the container.

  
  

Subclasses of Container are very frequently defined for defining structuring container whose sons are arranged according to a certain layout. Classes Row and Column are examples of such subclasses.

This constructor is seldom used for creating new instances. Derived classes (e.g. Row ) usually call this constructor method within their own constructor method in order to initialize the Control part of their instances.

During this operation, the clipping rectangle is the container object's rectangle. Only the portion of the sons which overlap the container's rectangle are rendered.

When an object is inserted into a container, the coordinates of the topleft corner of the container's rectangle are added to the coordinates of the object's rectangle. Therefore, if the initial rectangle of an object is located at cordinates (0, 0) , the object appears on the topleft corner of the container.

If there is a policy for the layout of the container, the new layout is computed and each object in the container is moved, resized and repainted.

When an object removed from a container, the coordinates of the topleft corner of the container's rectangle are subtracted from the coordinates of the object's rectangle. Inserting the object again thus inserts the object at the same location with respect to the container's topleft corner.

• Class Container enforces a very weak policy. If you move an instance of class Container , the managed objects move with their container.
  
• Class Row aligns the objects on a row and ensures that all objects have the same sufficient height,
  
• Class Column aligns the objects on a row and ensures that all objects have the same sufficient width,
  
• Class Grid aligns the objects on a grid with a predefined number of columns. Objects located in a same column have the same sufficient width and objects located in a same row have the same sufficient height.
  

These structuring containers make Ogre more attractive and easier to use than aksing the programmer to precompute the position of each object for all the interface configurations. Yet, geometry management is the most difficult component of the Ogre library.

Containers define the geometry policy using only two implementation methods, compute-geometry and manage-geometry . Here are the steps involved in a geometry computation:

• 1. An object managed by a container receives a geometry change request (i.e. moveresize , move or resize ).
  
• 2. The container of this object receives a message compute-geometry in order to recompute its size requirements by looking at the slots rect of the managed objects. It might then call method resize in order to enforce its new minimal size.
  
• 3. The final rectangle of the container is stored in slot rect of the container. The container then receives a message manage-geometry to get a chance to assign a final rectangle to all managed objects by sending them a message geometry .
  

The hidden part of the iceberg lies in the global computation of the object's location. If the container decides to change its geometry requirements during step 2, the container of the container then receives a message compute-geometry and gets a chance to participate to this geometry discussion. When this second container sets the first container's geometry, it calls the first container's method geometry which calls the first container's method manage-geometry and effectively performs step 3.

Important Note: The geometry management system has been significantly revamped in Lush. It is now faster and skinnier. Old programs still work correctly unless they redefine method geometry of class WindowObject .

This method must compute the minimal size of the container on the basis of the information stored in the slots rect of the managed objects or cached in the list of managed objects stored in slot contents of the container. This method may enforce a minimal size by sending a message resize .

The default method compute-geometry just returns the empty list.

Example:

Class Row defines the following method compute-geometry which computes the minimal size of a row:

(defmethod row compute-geometry ()
  (when window
    (let* ((height (sup (cons 0 (all (((son x y w h) contents)) h))))
           (width (sum (all (((son x y w h) contents)) w))) )
      (==> this resize (+ width (* hspace (length contents))) height)
      rect ) ) )

This method must compute the final rectangle of all the managed objects according to the container's rectangle (found in slot rect of the container) and according to the managed object initial rectangles (found in slot rect of the managed objects and cached in the list of managed objects located in slot contents of the container.) Method manage-geometry then sends a message geometry to the managed objects in order to assign a final rectangle to these objects.

The default method manage-geometry defined in class Container does nothing. A secondary mechanism just moves the managed objects in order to maintain their position with respect to the topleft corner of the container's rectangle.

Example:

Class Row defines the following method manage-geometry which arranges the managed objects in a row starting on the left of the container's rectangle.

(defmethod row manage-geometry ()
  (let (((x y w h) rect))
    (incr x (div hspace 2))
    (each ((i contents))
      (let ((w (nth 3 i)))  ;; get the object's width
         (==> (car i) geometry x y w h)
         (incr x (+ w hspace)) ) ) ) )

Such a task is accomplished by creating an object instance of class GeometryLock as follows:

(let ((lock (new GeometryLock c)))
        ;;; insert your objects here into container c
        (==> c insert ...) )

When created, the lock sets a flag in container c which suspend the usual geometry management. When the lock is destroyed, the flag is cleared and the geometry management is started once. If an error occurs during the object insertion, the lock is destroyed by the garbage collector and the container is left with an acceptable state.

(defmethod container disable ()
  (each ((i contents))
    (==> (car i) disable) ) )

(defmethod container enable ()
  (each ((i contents))
    (==> (car i) enable) ) )

(defmethod container hasdata ()
  (flatten (all ((i contents)) (==> (car i) hasdata))) )

(defmethod container getdata ()
  (all ((i (==> this hasdata)))
    (==> i getdata) ) )

(defmethod container setdata (d)
  (each ((i (==> this hasdata))
         (j d) )
    (==> i setdata j) ) )

Class Form is an abstract class used to group several cooperating objects into a single Ogre component. This component can then be inserted into a window or a requester.

Class Form is a trivial subclass of class Container . Class Form adds three properties to standard containers.

• Method compute-geometry makes a form object large enough to hold all its sons while keeping their initial relative positions.
  
• Method manage-geometry places the sons of a form object at the center of the form object while keeping their relative position.
  
• When Ogre calls the callback function of a descendant of a form object, it sets the temporary variable thisform to the form object.
  

These properties are handy for designing complex graphics objects composed of several components as subclasses of Form . Several classes, like class WindowObject , class Requester and class Viewer , are implemented as subclasses of Form .

Moreover, a form object is sometimes considered as an extended control object. For instance, we can gather a slider and an editable numeric field into a form object and use this object like an usual control object.

This is achieved by defining a subclass of Form whose constructor builds the elements of the composite object and keeps a pointer to these object in some of its slots. This subclass then must define methods hasdata , setdata , getdata , execute and setcall like those of a control object. Method hasdata usually returns this . The other methods are usually forwarded to the components of the composite object.

Class WindowObject is a subclass of class Form which implements the link between a physical window and its managed ogre objects.

• The constructor of class WindowObject creates a window on the screen with the same size than the window object rectangle. It call then method realize to tell its sons that a physical window is now attached to the graphic interface.
  
• Class WindowObject define methods for handling the window events and redirecting event messages to the proper descendant objects.
  
• Class WindowObject define slots and methods to manage the repainting process. The window object remembers which portions of the window has been damaged or exposed (using message expose ) and sends repainting messages when appropriate.
  
• Class WindowObject defines methods for synchronizing the window object rectangle and the physical window geometry.
  

A window object is a toplevel container. Inserting a window object into another container is an almost certain cause of trouble.

Whole graphics interface are often defined as subclasses of WindowObject . Such subclasses usually contain new slots for storing interface specific data. Callback functions then send messages to thiswindowobject . These messages then are executed within the interface scope.

When a window object is created, the constructor creates a window on the screen named name with width w and height h . If both arguments x and y are 0 , the position of this window is defined by the default rule of your computer. If both arguments are positive, they define the position of the topleft corner of the window.

Exemple:

;;; First of all, initialize Ogre !
? (ogre)
= idle-hook
;;; create a window with a button
? (setq win (new WindowObject 100 100 300 300 "Example"
                        (setq b (new stdbutton "Hello"             ;; its name
                                          (lambda(c) (beep)) )) )) ;; its callback
= ::WindowObject:06f00
;;; Now we remove the button b from win
? (==> win remove b)

Note: The event handler of the newly created window is the corresponding Ogre window object. You can thus interactively obtain the Ogre window object for a given window by typing (setq w (waitevent)) and clicking into the corresponding window.

The constructor arguments w and h are only hints for sizing the window. They may be empty lists instead of numbers. The size of the window is eventually given by the size of its contents.

Argument p can be the empty list (for black and white display) or a palette returned by function new-palette (for color display). The color palette selection is enforced even if you do not use an adequate screen.

• When argument m is the empty list, message setmodal undefines the current modal object.
  
• When argument m is one of the objects managed by the window object, message setmodal makes this object modal.

  
  

• Method delete is called when you destroy the window using a the window manager feature (i.e. with the mouse).
  
• Methods compute-geometry and manage-geometry work as usual. They are however called in special cases allowing a dynamical change of the window size.

  
  

The default method delete just deletes the window object. You may override this method, for instance, to pop up a confirmation dialog to the user.

The default method manage-geometry does nothing. Overriding the method manage-geometry in a window object is often useful for adjusting the size of the window object components to the onscreen window size.

The default method compute-geometry does nothing. You may override this method to adjust automatically the size of the onscreen window to the mimial size of its contents.

Structuring containers are used for designing the layout of a graphics interface. They arrange their sons according to a certain policy. Ogre provides three class of structuring containers: class Row , class Column and class Grid .

These containers inherit all the slots and methods of an ordinary container. They just define specific methods compute-geometry and manage-geometry to enforce their layout policy.

In addition, two classes are provided for padding a row or a column with some space, class EmptySpace and class DarkSpace .

Returns a new row object managing the objects specified by ...contents... .

Class Row defines a structuring container which aligns its contents horizontally from left to right. The height of a row is determined by the managed object whose required height is largest.

An empty space is inserted between the objects. This space is defined by slot hspace of the row object and defaults to 4 points.

Returns a new column object managing the objects specified by ...contents... .

Class Column defines a structuring container which aligns its contents vertically from top to bottom. The width of a column is determined by the managed object whose required width is largest.

An empty space is inserted between the objects. This space is defined by slot vspace of the column object and defaults to 4 points.

Example:

;; Creates a window with three buttons
? (setq win 
        (new WindowObject 100 100 300 300 "Essai"
                (new Column
                  (new StdButton "One" (lambda(d) (print 1)))
                  (new StdButton "Two" (lambda(d) (print 2)))
                  (new StdButton "Three" (lambda(d) (print 3))))))
= ::WindowObject:06f00

Returns a new grid object with cols columns and managing the objects specified by ...contents... .

Class Grid defines a structuring container which aligns its contents in a grid with cols columns. The grid is filled left to right. The width of each column is determined by the object of the column whose required width is largest. The height of each row is determined by the object of the row whose required height is largest.

Empty spaces are inserted between rows and columns. These spaces are defined by slot vspace and hspace of the grid object and defaults to 4 points.

Class EmptySpace is a class of emptyspace objects. The constructor expression above returns a new emptyspace object of minimal width w and minimal height h . When argument h is omitted, a square minimal space is assumed.

Of course, the minimal geometry specifications interact with the geometry management of structuring conteners. It is seldom necessary to define all the sizes of an emptyspace object.

Exemple:

;;; Creates a window with three buttons
;;; with a 20 pixels space between button 2 and button 3
? (setq win 
        (new WindowObject 100 100 300 300 "Essai"
                (new Column
                  (new StdButton "One" (lambda(d) (print 1)))
                  (new StdButton "Two" (lambda(d) (print 2)))
                  (new EmptySpace 20)
                  (new StdButton "Three" (lambda(d) (print 3))) )))
= ::WindowObject:06f00

Class DarkSpace is a class of emptyspace objects. The constructor expression above returns a new emptyspace object of minimal width w and minimal height h . When argument h is omitted, a square minimal space is assumed.

Of course, the minimal geometry specifications interact with the geometry management of structuring conteners. Specifying a single argument of 4 , for instance, will define a minimal width and height of 4 points. If such a darkspace object is inserted in a column, the width of object will be increased up to the column width, effectively displaying a 4 points thick line.

Exemple:

;;; Creates a window with three buttons
;;; with a 3 pixels line between button 2 and button 3
? (setq win 
        (new WindowObject 100 100 300 300 "Essai"
                (new Column
                  (new StdButton "One" (lambda(d) (print 1)))
                  (new StdButton "Two" (lambda(d) (print 2)))
                  (new DarkSpace 3)
                  (new StdButton "Three" (lambda(d) (print 3))))))
= ::WindowObject:06f00

• Class StdButton and TinyButton for push buttons,
  
• Class CheckBox for boolean state buttons,
  
• Class RadioButton for exclusive buttons.
  

All these classes are subclasses of Control . Buttons thus inherit all the slots and methods defined in class Control .

Class StdButton implements a standard push button. The label of a standard push button is displayed using the font set by the function stored in slot textfont , which default to a 12 points bold font font-12b .

The constructor expression returns a push button whose name is given by string label . This label may be changed by sending a message settext . When the button is depressed, the callback function call is executed. The button remains disabled while the callback function has not returned.

Example:

;;; A window with a 3 state label
? (setq win 
        (new WindowObject 100 100 300 300 "Essai"
                (new StdButton "One"
                        (lambda(caller)
                                (==> caller settext
                                        (selectq (==> caller gettext)
                                                ("One" "Two")
                                                ("Two" "Three")
                                                (t     "One") ) ) ) ) ) )
= :WindowObject:06f00

Class TinyButton implements a push button with a reduced size. A tiny push button is slightly smaller than a standard push button because the label is written using a smaller font font-12 .

The constructor expression returns a push button whose name is given by string label . This label may be changed by sending a message settext . When the button is depressed, the callback function call is executed. The button remains disabled while the callback function has not returned.

Class CheckBox implements check box buttons. Since class CheckBox is a subclass of class Control , all the slots and methods defined for control objects are inherited.

Returns a new check box whose descriptive text is given by string label . When a check box is depressed, its state changes and the callback function call is executed.

You can query or change the state of a check box ( t or () ) by sending messages getdata and setdata . The descriptive text can be modified using settext .

Example:

;;; A window with a check box that controls 
;;; the enable/disable state of a push button
? (setq win 
        (new WindowObject 100 100 300 300 "Essai"
          (new column
                (setq thebutton 
                        (new StdButton "beep" 
                                (lambda(c) (beep)) ))
                (new CheckBox "Disable button"
                                (lambda(c)
                                        (if (==> c getdata)
                                                (==> thebutton disable)
                                          (==> thebutton enable) ) ) ) ) ) )

Class ImageButton implements a push button whose appearance is an image drawn with rgb-draw-matrix . Each of the first three arguments must be an idx2 or an idx3 of ubytes containing the pixel data (greyscale if an idx2, RGB if an idx3 with at least 3 elements in the last dimension). up-image is the image shown when the button is up, down-image when it is pushed, disabled-image when it is disabled. The A (alpha) component, if present, is ignored. call is the callback function called when the button is clicked.

Here is an example that shows how to create down and disabled image of an ImageButton from an up image.

  (libload "libimage/image-io")
  (libload "libimage/rgbaimage")
  (ogre)
  (setq up (image-read-rgba "my-button-image.png"))
  (setq down (idx-copy up))
  (rgbaim-contbright up down -1 0)
  (setq disabled (idx-copy up))
  (rgbaim-contbright up disabled 0.5 40)
  (setq btn (new ImageButton up down disabled (lambda (c) (printf "coucou\n"))))
  (setq window (new windowobject 10 10 200 200 "test" btn))

This works just like an StdButton except that the image of the button is an RGBA or grayscale image passed as argument (instead of the boring blueish rounded rectangle of StdButton ). The text is displayed on top of the image. The three images passed as argument will be used respectively as the up button image, the clicked (down) button image, and the disabled button image. The text is drawn in black over the background image, so the image colors should not be too dark. The background images are automatically sized/resized to fit the text (without necessarily preserving the aspect ratio). The images must be idx2 (for grayscale images) or idx3 with the last dimension equal to 4 (RGBA images). Tha A (alpha) component is ignored.

Here is an example that shows how to create an StdButtonBg from one of the standard icons:

  (libload "libimage/image-io")
  (libload "libimage/rgbaimage")
  (setq icondir (concat-fname lushdir "lsh/libogre/icons"))
  (ogre)
  (setq btn 
    (new StdButtonBg
      "Click Me"
      (image-read-rgba (concat-fname icondir "button-brushed-metal-02-up.png"))
      (image-read-rgba (concat-fname icondir "button-brushed-metal-02-down.png"))
      (image-read-rgba (concat-fname icondir "button-brushed-metal-02-disabled.png"))
      (lambda (c) (printf "coucou\n"))))
  (setq window (new windowobject 10 10 200 200 "test" btn))
  (==> btn disable)
  (==> btn enable)

Class RadioButton implements exclusive buttons. Since class RadioButton is a subclass of class CheckBox , all the slots and methods defined for checkbox and control objects are inherited.

Returns a new check box whose descriptive text is given by string label . You can query or change the state of a check box ( t or () ) by sending messages getdata and setdata . The descriptive text can be modified using settext .

You must insert a radiobutton in a container containing only radiobuttons. Whenever the user clicks on a radiobutton, the state of all the other radiobuttons in the container becomes () , while the state of the clicked radiobutton becomes t and the callback function call is called.

Example:

;;; A window with a three radio buttons 
;;; building a three state choice
? (setq win 
        (new WindowObject 100 100 300 300 "Essai"
                ;; create a common callback function
                (let ((call (lambda(d) 
                                        (printf "%s has been selected\n"
                                                (==> d gettext) ) )))
                          (new column
                                (new radiobutton "choice 1" call) 
                                (new radiobutton "choice 2" call) 
                                (new radiobutton "choice 3" call) ) ) ) )

Remarks:

• All radiobuttons in a same container are exclusive.
  
• A container of radiobuttons should not contain objects which are not instances of class RadioButton .

  
  

A file requester button is usually associated with a string editor, which displays the file selected in the requester.

See: File Requester.
See: Editable Strings.

• Class String provides a way to display fixed text.
  
• Class EditString provides a way to display a text string that the user can edit using the mouse and the keyboard.
  
• Class EditNumber provides a way to display a numerical text string that the user can edit using the mouse and the keyboard.
  
• Class EditSecretString provides a way to display a secret text string that the user can edit using the mouse and the keyboard.
  
• Classes EditText and TextPane implement a multiline text editor. Class TextPane is the basic class for the editor or viewer. Class EditText manages a text editor and two scrollbars.
  

Creates a new string object displaying text text . The text displayed by a string object may be changed using settext like the text of a control object.

• Argument text may be a string containing or not newline characters. When text contains newline characters, a multiline text is displayed.
  
• Argument text may also be a list of strings, one per line.
  

The text is displayed using a font set by the fonction stored in slot textfont of the string object. This font default to a standard 12 points font.

An editable string is a single line text editor.

An editable string object becomes actived when the user clicks the mouse button above its rectangle. Keypress and arrow events then are bound to editing functions according to a keymap stored in global variable EditStringKeymap .

The text edited by an editable string is controlled by the value of the slot regex of the editable string. This slot contains a regular expression which must match the text at all times. If an editing action results in a non-matching text, the action is discarded and a beep is emited.

• Class EditString implements the editable strings. Since class EditString is a subclass of class Control , all the slots and methods defined for control objects are inherited.
  
• Class EditNumber implements an editable string intended for entering or displaying numbers.
  
• Class EditSecretString implements an editable string intended for entering secret texts by displaying any character as an 'x'.
  

Example:

;;; A window with two editable strings
? (setq win 
        (new WindowObject 100 100 300 300 "Essai"
                 (new grid 2
                        (new string "First string:")
                        (new editstring 16 "number one")
                        (new string "Second string:")
                        (new editstring 16 "number two") ) ) )

Every typed character is matched against the keymap.

• If a binding matches the typed character, message action with no argument is sent to the editable string.
  
• If no binding matches, the character is inserted into the data string at the current cursor location. The cursor is then advanced by one position.
  

The default keymap is loosely modeled after the Emacs text editor:

(setq EditStringKeymap
 '(     ("\n"          execute)         ;; <LineFeed>
        ("\r"          execute)         ;; <Enter> or <Return>
        ("\b"          backspace        ;; <ctrl-H> or <Backspace>
        ("\x7f"        backspace)       ;; <Delete>
        ("\^D"         delete-char)     ;; <Ctrl-D>
        ("Delete"      delete-char)     ;; Key <Delete>
        ("\^A"         begin-of-line)   ;; <Ctrl-A>
        ("Home"        begin-of-line)   ;; Key <Home>
        ("\^E"         end-of-line)     ;; <Ctrl-E>
        ("End"         end-of-line)     ;; Key <End>
        ("\^F"         arrow-right)     ;; <Ctrl-F> and <Right>
        ("\^B"         arrow-left)      ;; <Ctrl-B> and <Left>
        ("\^P"         arrow-up)        ;; <Ctrl-P> and <Up>
        ("\^N"         arrow-down)      ;; <Ctrl-N> and <Down>
        ("\^K"         kill)            ;; <Ctrl-K>
        ("\^Y"         yank) ) )        ;; <Ctrl-Y>

The binding second elements, actions, are the names of methods defined by class EditString to perform the various editing tasks. The valid actions are:

• Action execute calls the callback function. You can install a callback function using message setcall because an editable string is a control object.
  
• Action backspace deletes the character preceding the cursor.
  
• Action delete-char deletes the character located right after the cursor.
  
• Action begin-of-line moves the to cursor the beginning of the line.
  
• Action end-of-line moves the cursor to the end of the line.
  
• Action arrow-left moves the cursor one character left.
  
• Action arrow-right moves the cursor one character right.
  
• Action arrow-up recalls the previous string in the history buffer. Editable strings maintain a buffer of the last 20 strings typed by the user.
  
• Action arrow-down recalls the next string in the history buffer.
  
• Action kill deletes the text between the cursor and the end of the string. This text is copied into the clipboard.
  
• Action yank inserts text from the clipboard. The kill and yank actions implement in fact a simple Copy/Paste mechanism between editable strings.

  
  

Argument minsize is the minimal number of characters dislayed in the object. The initial value of the number is specified by the optional number argument defaultvalue .

When sent to an editable numeric string, message setdata requires a numerical argument. Similarly, message getdata returns a number or the empty list when no text has been entered.

Class EditText is a subclass of Forms that defines composite object containing a TextPane object and two scroll bars. The text editor is actually implemented by class TextPane described hereafter.

Class EditText forwards messages setdata , getdata , read-file and write-file to this underlying TextPane object.
See: (new TextPane w h [ def editp vs hs ])
See: (==> TextPane getdata)
See: (==> TextPane setdata arg )
See: (==> TextPane read-file fname )
See: (==> TextPane write-file fname )

• Argument w is the number of visible columns.
  
• Argument h is the number of visible lines.
  
• Argument def specifies a default contents as a string or a list of strings. Single strings are searched for TAB and NL characters and splitted into multiple strings (one per line).
  
• Flag editp tells if the string is editable or just viewable.
  
• If scrollbars are attached to the text pane, you must pass them as arguments vs and hs . The text pane will then synchronize the scrollbars with the actual contents of the text pane area.

  
  

(setq TextPaneKeymap
 '(     ("\n"     execute)
        ("\r"     execute)
        ("\b"     backspace)
        ("\x7f"   backspace)
        ("\^A"    begin-of-line)
        ("\^B"    arrow-left)
        ("\^D"    delete-char)
        ("\^E"    end-of-line)
        ("\^F"    arrow-right)
        ("\^K"    kill)
        ("\^N"    arrow-down)
        ("\^P"    arrow-up)
        ("\^V"    page-down)
        ("\^Y"    yank) 
        ("Delete" delete-char)
        ("C-Home" begin-of-text)
        ("C-End"  end-of-text)
        ("Home"   begin-of-line)
        ("End"    end-of-line)
        ("Prior"  page-up)
        ("Next"   page-down)
        ("\x1b"   metakey "\x1b")
        ("\x1b<"  begin-of-text)
        ("\x1b>"  end-of-text)
        ("\x1bv"  page-up)
  ) )

The first element of each association describes the keystroke or keystroke combination. This string can contain an ASCII character, a string containing a keystroke combination, or a function key name. The leading character of keystroke combinations must be associated to method metakey . The function key names may be preceded by "C-" and "S-" to indicate that the control or shift key must be depressed.

The rest of the association specify which action should be called when the corresponding keystroke is typed by the user. The following actions are supported:

• Action execute calls the callback function. You can install a callback function using message setcall because an editable string is a control object.
  
• Action backspace deletes the character preceding the cursor.
  
• Action delete-char deletes the character located right after the cursor.
  
• Action begin-of-line moves the to cursor the beginning of the line.
  
• Action end-of-line moves the cursor to the end of the line.
  
• Action begin-of-text moves the caret at the beginning of the text.
  
• Action end-of-text moves the caret at the end of the text.
  
• Action arrow-left moves the cursor one character left.
  
• Action arrow-right moves the cursor one character right.
  
• Action arrow-up moves the cursor one line up.
  
• Action arrow-down moves the cursor one line down.
  
• Action page-up moves the cursor one screen up.
  
• Action page-down moves the cursor one screen down.
  
• Action kill deletes the text between the cursor and the end of the string. This text is copied into the clipboard.
  
• Action yank inserts text from the clipboard. The kill and yank actions implement in fact a simple Copy/Paste mechanism between editable strings.
  
• Action metakey is used to declare the prefix of a keystroke combination. The action argument will be combined with the next keystroke and the combined string will be searched in the keymap.

  
  

Argument mat is a 2D matrix containing the data to be represented as rectangles using 64 gray levels. By default, the values lower than 0 will be black and the values beyond 1 will be white.

Arguments sx and sy are the width and height of each rectangle.

Argument cmap may be a 1D integer matrix defining 64 colors. When it is defined, its colors are used instead of gray levels.

See: (gray-draw-matrix x y mat minv maxv apartx aparty )
See: (color-draw-matrix x y mat minv maxv apartx aparty cmap )

  (libload "libimage/image-io")
  (setq m (image-read-rgb (concat-fname lushdir "lsh/libimage/demos/sample.jpg")))
  (ogre)
  (setq w (new WindowObject 10 10 400 400 "asd" (new ImageViewer 340 340 m t)))

Menus are implemented with three classes:

• Class Menu defines the menu button. A menu button appears as a bold string preceded by a small upside down triangle. When the menu button is depressed, an instance of class MenuPopup is inserted into the menu button's window.
  
• Class MenuPopup is a subclass of class Column . It arranges the menu items and manages event messages by selecting the appropriate menu item.
  
• Class MenuItem is a subclass of class Control . Menu items may receive settext messages for changing their label and setdata messages for setting slot data . When slot data is not the empty list, a check mark appears on the left of the menu item.
  

The constructor of class Menu sets up all these objects in a single call.

Example:

;;; A window with a menu composed of 3 items
? (setq win 
      (new WindowObject 100 100 300 300 "Essai"
          (new menu "Test Menu"
                ;; the first item toggles its check mark
                "Toggle" 
                (lambda(item) (==> item setdata (not (==> item getdata))))
                ;; the second item activates the bell
                "Bell"   
                (lambda(item) (beep))
                ;; the third one destroy this interface
                ;; remenber that <thiswindowobject> always
                ;; refer to the closest window object.
                "Quit"     
                (lambda(item) (==> thiswindowobject delete)) ) ) )

• If label is the empty list () , message finditems returns a list containing all the menu items.
  
• If label is a number, message finditems returns a list containing the label -th menu item.
  
• If label is a string, message finditems returns a list of menu items whose label string is equal to label .

  
  

When a menu receives a message disable , it sends a message disable to all menu items identified by the arguments ...labels... . Therefore, the corresponding menu items are disabled.

Each argument of message disable is interpreted like the argument label of message finditems. It can be the empty list, a number or a string.

When a menu receives a message disable , it sends a message disable to all menu items identified by the arguments ...labels... . Therefore, the corresponding menu items are disabled.

Each argument of message disable is interpreted like the argument label of message finditems. It can be the empty list, a number or a string.

Choice menus supports the methods of standard menus, in addition to their own methods.

Requesters are useful for asking the user to provide additional information about an action trigerred by a button or a menu item. The callback function of the button or menu item then just send a message popup to the requester which performs all the remaining tasks.

• Class Requester implements the basic mechanism of a requester.
  
• Class ErrorRequester and WarningRequester implement requesters specialized for displaying error messages.
  
• Class YesNoRequester defines a requester with a standard state and two standard buttons for accepting or cancelling an action. These requesters are useful for entering extra information about an action trigerred by a button or a menu item.
  
• Class PrintRequester implements a standard requester for selecting a printer.
  
• Class FileRequester implements a standard requester for entering a filename for reading or writing.

  
  

Example:

;;; A window with a button that pops a requester up.
;;; The requester contains an editstring and two buttons.
;;; 1- Create the window
? (setq win 
          (new WindowObject 100 100 300 300 "Essai"
                (setq thebutton
                        (new StdButton "Pop the requester up"
                                (lambda(d) (==> therequester popup)) ))))
= ::WindowObject:06f00
;;; 2- Create the requester
? (setq therequester
        (new Requester win
          (new Column
                ;; The first button pops the requester down
                ;; Variable <thisrequester> always refers to the closest
                (new StdButton "Pop the requester down"
                        (lambda(d)
                          (==> thisrequester popdown)) )
                ;; The second button changes the label of the popup button
                (new EditString 8 "Pop it up again")
                (new StdButton "Change label"
                        (lambda(d)
                          (==> thebutton settext
                                ;; Collective <getdata> on the requester!
                                (car (==> thisrequester getdata)))))))))
= ::Requester:0702c

All event messages are then directed to the requester. Since no other component of the interface toplevel is active, it is advisable to insert a button whose action consists in sending message popdown to the requester itself.

Example:

;;; Pop up the requester defined above in this section and block:
? (==> therequester popuplock)
;;; Lush only returns when you activate the 'popdown' button
= ()

While message popuphard is active, no other window object accepts user events. If the user click in another Ogre window, the computer beeps and put the window containing the requester above all other window on the screen.

Message popuphard is useful for requesting an information which requires immediate attention from the user.

Using a warning requester with messages popup and popdown allows for displaying messages indicating what is being computed.

Using a warning requester with popuplock allows for displaying a temporary warning message.

Such a requester is very useful for signaling an error to the user. The user must depress the button "Ok" to remove the requester. This button actually sends a message popdown to the error requester.

Example:

;;; Assuming window object <win> already exists:
? (setq error-dialog (new ErrorRequester win))
= ::ErrorRequester:07120
? (==> error-dialog popup "Error message")
= ()

Using a warning requester with messages popup and popdown allows for displaying messages indicating what is being computed.

Like usual requesters, yes/no requesters are popped up when they receive a message popup or popuplock . Both the positive and the negative button pop the yes/no requester down.

When you create the yes/no requester however, you specify a callback function.

• When the positive button is depressed, the yes/no requester is popped down and the callback function is executed.
  
• When the negative button is depressed, the yes/no requester object is popped down and the state of the user defined part of the requester is restored to the state recorded when the requester was popped up. The callback function is not executed.
  

If you have popped up the requester using message popuplock , you can also test which button has been depressed by looking at the value returned by message popupdown . This value is the empty list if the negative button has been depressed.

Slots yesbutton and nobutton of a yes/no requester contain the positive and negative buttons. These buttons may be programmatically actived by sending them a message trigger .

Argument dialog is the user defined part of the requester. String yes is the label of the positive button. String no is the label of the negative button. Argument call is a callback function or the empty list.

Example:

;;; A button that pops up a yesnorequester
;;; for changing its label...
? (setq win 
        (new WindowObject 100 100 400 200 "Essai"
                (setq thebutton
                        (new StdButton "Hello"
                                (lambda(c) (==> theyesnoreq popup)) ))))
= ::windowobject:07010
? (setq theyesnoreq
        (new YesNoRequester win
                ;; The user defined part
                (new Column
                        (new String "Change button label")
                        (new EditString 8 "new label") )
                ;; The yes and no labels
                " Ok " "Cancel"
                ;; The callback
                (lambda(caller)
                        (==> thebutton settext
                                (car (==> caller getdata)) ))))))))
= ::yesnorequester:07040

There is usually a default button indicated by a wider outline. This button is triggered if the user hits the carriage return key. This default button is usually the positive one, but may be changed with argument default of message settext .

• If default is 'yes , the positive button is the default,
  
• if default is 'no , the negative button becomes the default,
  
• if default is the empty list, no default button is set.

  
  

This message should be used with yes/no requesters whose user defined component is a single String object.

When such a requester receives message ask , it first sets the text of the string object to text and the button labels to yes and no . The default button is indicated by argument default .

The requester is then popped up using popuphard . The user can then press either the positive or the negative button. When the requester is popped down, message ask returns t or () according to the user answer.

Example:

;;; Creates a confirmation dialog in an exiting win <win>.
? (setq confirm-dialog 
        (new YesNoRequester win
                (new string "msg")         ; dummy message
                "yes" "no"                 ; dummy labels
                () )                       ; no callback
= ::yesnorequester:070c0
? (==> confirm-dialog ask 
        "Should I really do that"          ; the message
        "Proceed" "Please don't"           ; the button labels
        'no )                              ; the default
;;; Waiting for your answer...
= t or ()

A print requester lets the user choose a valid destination for printing a graphics. Function getdata will return a string that can be used verbatim as the destination argument of function print-window .

Creates a new print requester for displaying in the window object w . The optional argument callback defines a callback function that will be called if the user presses button "Ok" (as usual with Yes/No Requesters.)

Starting from the current filename, the selector displays the contents of the directory. A first click on a selector item selects a file or directory and copies its name in the editable filename string. Alternatively, the user can type a filename in the filename field. The button "Ok" is disabled if the user types an invalid filename.

This selection is validated by a second click, by pressing the enter key or by depressing the button "Ok" .

• If the selected item is a directory, the contents of this directory is displayed and the user can select again an item.
  
• If the selected item is a file, the requester is popped down and the callback function is executed.
  

Class FileRequester is a subclass of class YesNoRequester which implements the standard Ogre file requester.

Special behavior are selected by argument flag :

• When flag is 'no-newfile , it is forbidden to enter the name of a non existent file.
  
• When flag is 'ask-newfile , validating the name of a non existent file pops up a confirmation requester. This is useful before creating a new file.
  
• When flag is 'ask-oldfile , validating the name of an existent file pops up a confirmation requester. This is useful before overwriting an existing file.

  Argument filter is a function with one argument for testing the filenames. It returns a non nil value if its argument is a valid file name for this file request. For instance, this function might test an extension or examine the file header. Files rejected by the function filter are not displayed in the selector. If the user types such an invalid filename in the filename field, validation is prevented by disabling the button "Ok" .

  
  

• If the user validates a file name, a non nil value is returned. The filename can be accessed by sending a getdata message.
  
• If the user selects the Cancel button, the empty list is returned.

  
  

Other arguments are the same as for method ask of class FileRequester .

See: (==> FileRequester ask message flag [ filter [ fname ]])

A dragging area appears as a rectangle with a gray outline. When you depress the mouse inside a dragging area, you can drag its container to another place.

Two slots affect the behavior of a dragging area:

• The moved object always remains inside rectangle constraintrect . This rectangle defaults to the empty list () which means that the object remains confined within its container's rectangle.
  
• Slot magnet should contain a list (mx my) . The moved object keeps aligned on an invisible grid whose columns are mx pixels wide and whose rows are my pixels high. It defaults to the empty list () which means that objects may be moved at any pixel position.

  
  

A sizing area appears as two overlapping gray squares. When you depress the mouse inside a sizing area, you can change the size of its container. Just drag the mouse until you touch a container boundary. This container boundary then follows the mouse until you release the mouse button.

Two slots affect the behavior of a size area.

• The resized object always remains confined within the rectangle constraintrect . This rectangle defaults to the empty list () which means that the object remains confined within its container's rectangle.
  
• Slot formfactor should contain a list (fx fy) . The width of resized object remains an integer multiple of fx , the height of the resized object remains an integer multiple of fy , and both coefficients are equal. Slot formfactor defaults to the empty list () which means that no form factor constraint apply.

  
  

Class Frame is a subclass of class Container . A frame always contains a dragging area located in the background of the container. A frame thus is a container that the user can move.

Example:

? (setq win (new windowobject 0 0 400 400 "Essai"
                (new Frame 50 30 200 140 
                        (new stdbutton "Beep" 
                                (lambda(c) (beep)) ) ) ))

Class FrameSize is a subclass of class Frame . A sizable frame always contains a dragging area located in the background of the container. A sizable frame also contains a small size area in its bottom right corner. A sizable frame thus is a container that the user can move and resize.

Example:

? (setq win (new windowobject 0 0 400 400 "Essai"
                (new FrameSize 50 30 200 140 
                        (new stdbutton "Beep" 
                                (lambda(c) (beep)) ) ) ))

• Sliders are rendered as symbolized potentiometers. Sliders are mostly used as a way to enter numerical values.
  
• Scrollbars are rendered as a gray area with a white handle. Scrollbars are mostly used for controlling other objects.
  

The user can grab and move the handle with the mouse. The user might also maintain the mouse button depressed on either side of the handle. In this case, the handle moves slowly towards the mouse pointer.

The standard callback function is called whenever the user releases the mouse button. An additional callback might be set up with message setdrag . This callback is called whenever the user moves the handle.

Sliders and scrollbars are implemented by a set of specialized subclasses of class Control .

Control                 abstract class for all controls
  Slider                abstract class for all sliders and scrollbars
    HSlider               horizontal sliders
    VSlider               vertical sliders
    Scrollbar           abstract class for all sliders and scrollbars
      HScrollbar          horizontal scrollbars 
      VScrollbar          vertical scrollbars

Example: Example:

? (setq win (new windowobject 100 100 400 200 "Sliders & Scrollbars"
                (new row
                  (new grid 2
                   (new emptyspace 100 100) 
                   (new vslider 0 100 ())
                   (new hslider 0 100 ()) 
                   (new emptyspace 10 10) )
                  (new grid 2
                   (new emptyspace 100 100) 
                   (new vscrollbar 100 ())
                   (new hscrollbar 100 ()) 
                   (new emptyspace 10 10) ) ) ) )

Message setrange redefines the minimal and maximal values allowed in a slider or a scrollbar.

The initial increment is always 1. This initial increment ensures that the slider or scrollbar is limited to integer values. Specifying the empty list as an increment means that any value in the legal range are allowed.

Scrollbars are implemented by classes HScrollbar and VScrollbar which are indirect subclasses of class Slider . All the methods defined by class Slider are thus inherited by scrollbars.

Message setrange redefines the minimal and maximal values allowed in a scrollbar. When the optional argument prop is provided, the maximal value is reduced by prop and the value prop is used for defining the size of the knob. This is useful for scrolling lists of texts.

Class Viewer implements viewer objects.

Example:

? (setq win (new WindowObject 0 0 400 200 "Essai"
                (new Viewer 300 150 
                        (new column (new stdbutton "One" ())
                                    (new emptyspace 60 60)
                                    (new stdbutton "Two" ())
                                    (new stdbutton "Three" ())
                                    (new stdbutton "Four" ()) )
                         t t) ) )

Class Selector implements a selector object. The complete behavior of a selector is controlled by three slots of the selector object: multiple , call1 and call2 .

• When slot multiple contains a non nil value, the user might select multiple items. In this case, message getdata sets and message setdata returns the list of the selected strings.
  
• If slot multiple contains the empty list, one item at most can be selected at a given time. Message getdata sets and message setdata returns the selected string or the empty list.
  

Two callback functions are called when the user selects items.

• Callback call1 is called whenever the user selects an item by clicking the mouse button over an unselected string.
  
• Callback call2 is called whenever the user selects an item a second time by clicking the mouse button over a hilighted string.
  

Argument callback of the constructor controls the values of these flags.

• If argument callback is t , the user might select multiple items.
  
• If argument callback is a function, one item at most can be selected at a given time. The specified callback function is called whenever the user selects a new item.
  
• If argument callback is a non-nil list, one item at most can be selected at a given time. The list is assumed to be made of two functions or nil values. The first one is used whenever the user selects a new item. The second one is used whenever the user selects again a selected item.
  

Argument items optionally gives a list of strings initially displayed in the selector.

• If slot multiple contains a non nil value, the user can select multiple items. In this case, message getdata returns the list of the selected strings.
  
• If slot multiple contains the empty list, the user can select at most one item. Message getdata then returns the selected string or the empty list if no string is selected.

  
  

• If slot multiple contains a non nil value, the user can select multiple items. In this case, message getdatanum returns the list of the order numbers of selected strings.
  
• If slot multiple contains the empty list, the user can select at most one item. Message getdata then returns the order number of the selected string or the empty list if no string is selected.

  
  

• If slot multiple contains a non nil value, argument data must be a list of strings or a list of numbers indicating which items must be selected.
  
• If slot multiple contains the empty list, argument data is the empty list (to desselect the selected item), a string or a number indicating which string must be selected.

  
  

Since the minimal size of a selector depends on the width of the largest string in the item list, sending message setitems can trigger a geometry negociation and readjust the location of all interface components.

The class browser interface is composed of a menu and six selectors:

• Selector ``Sub-Classes'' displays the names of the subclasses of class cl . A mouse click on one of these subclasses changes the current class to the selected class.
  
• Selector ``Slots'' displays the names of all slots defined by class cl .
  
• Selector ``Method'' displays the names of all method selectors defined for class cl .
  
• Selector ``Super-Classes'' displays the names of the successive superclasses of cl . A mouse click on one of these subclasses changes the current class to the selected class.
  
• Selector ``Inherited Slots'' displays the names of all slots defined by the successive superclasses of class cl . A mouse click on a method item prints the definition of the selected method.
  
• Selector ``Inherited Methods'' displays the names of all methods inherited from the successive superclasses of class cl . A mouse click on a method item prints the definition of the selected method.
  

The top of the class browser contains a menu and an information string. The information string displays the number of slots, the number of inherited slots, the number of methods and the number of inherited methods for the current class. The name of the menu is always the name of the current class, displayed in large characters.

The menu itself contains four items:

• Selecting item "Show Class" prints the definition of class cl .
  
• Selecting item "Show Subtree" prints an indented list of the subclasses of class cl .
  
• Selecting item "Refresh" reads again the information for class cl and reflects possible changes on the display.
  
• Selecting item "Select" pops up a requester which lets the user enter the name of a class. The class browser jumps to the selected class when the user presses button "Ok" . If the typed class name is not a valid class name, a message is displayed.

  
  

     <lushdir>/lib/classtool.lsh

The first executable line of file "classtool.lsh" initializes the Ogre library by calling function ogre . This is necessary to ensure that the Ogre class library is properly loaded and initialized.

(ogre)

Then we define a subclass c-classtool of class WindowObject . This class contains several slots for referencing the major components of the interface.

(defclass c-classtool windowobject
  the-menu                ;; the menu
  the-string              ;; the information string
  the-i-classes           ;; the superclass selector
  the-i-slots             ;; the inherited slots selector
  the-i-methods           ;; the inherited methods selector
  the-classes             ;; the subclass selector
  the-slots               ;; the slots selector
  the-methods             ;; the method selector
  the-error-requester     ;; a signaling requester
  the-class-requester     ;; the requester
  cl )                    ;; the current class

We define then the constructor of class c-classtool . This constructor first calls the constructor of its superclass WindowObject and defines the contents of the window object. This very long call sets up the major components of the classtool interface.

All the interface is a single column which contains:

• A row implements the menu bar. The menu bar contains only one menu object (stored in slot the-menu ) and an information string (stored in slot the-string ).

  The menu defines the five items documented above. The callback functions of the menu items do not perform very much. They merely send an appropriate action message to the interface itself (acceded through variable thiswindowobject ) or pop up a suitable the requester.
  

         (setq the-menu
             (new Menu "object"
                "Show Class"    
                (lambda(c) (==> thiswindowobject display-action))
                "Show Subtree"    
                (lambda(c) (==> thiswindowobject subtree-action))
                "Refresh" 
                (lambda(c) (==> thiswindowobject refresh-action))
                "Select"  
                (lambda(c) (==> the-class-requester popup))
                "Quit"    
                (lambda(c) (==> thiswindowobject delete)) ) )

• A dark space object provides a clear separation between the menu bar and the rest of the interface. Although the minimal space allocated for the dark space 3 points wide, the column layout policy makes this space as wide as the column itself.
  
• A grid with 3 columns contains all the other objects. It includes the selector titles (string objects) and the selector themselves which are stored in appropriate slots of the classtool object. The callback functions of the selector do not perform much. They just send messages classes-action or methods-action to the classtool object itself.

  The grid also include three emptyspace object which specify a minimal size for the grid columns. This technique avoids troublesome geometry changes because it ensures that the selectors are already wide enough for displaying most names.

  The constructor of class c-classtool then adjust the font used in the menu title by directly poking into the object slot textfont . It calls then method compute-geometry to ensure that the object size is adjusted for the new font.
  

  (setq :the-menu:textfont font-18)
  (==> the-menu compute-geometry)

The constructor of class c-classtool then creates two requesters.

• The error requester the-error-requester is used later for displaying error messages.
  

  (setq the-error-requester 
        (new ErrorRequester this) )

• The class requester is popped up when you select menu item "select" for directly entering a class name. It defines a callback function which just sends a message select-action to the classtool object.

  We poke a new regular expression in the slot regex of the editable string in order to ensure that the text typed by the user is a valid symbol.
  

  (setq the-class-requester 
        (new YesNoRequester this
             (new column
                  (new String "Type a class name")
                  (new DarkSpace 3)
                  (let ((x (new EditString 20)))
                    (setq :x:regex "[A-Za-z]?[-_|A-Za-z0-9]*") x) )
             " Ok " "Cancel"
             (lambda(c) (==> thiswindowobject select-action)) ) ) )

Method setclass is then defined. This method collects the class information for the selected class and updates the information displayed in the selectors.

It first checks that its argument is a valid class and pops up the error requester if this check is negative.

(defmethod c-classtool setclass(c)
  (if (not (and c (classp c)))
      (==> the-error-requester popup "This is not a valid class")

If the check is positive, method setclass displays a message "working" in the message string and force an immediate display update using message repair-damaged .

    (==> the-string settext "<<working>>")
    (==> this repair-damaged)

The menu title is then changed to the class name using method settext . Since the display update is delayed until all events are processed, this change becomes visible when all selectors are updated.

Method setclass then collects the class information into six lists: the subclass list ( cc ), the slot list ( cs ), the method list ( cm ), the superclass list ( ic ), the inherited slot list ( is ) and the inherited method list ( im ). We take a particular care of separating the various inherited classes by a dummy entry in the inherited lists.

This information is then loaded into the selectors using method setitems . The message string is then updated to the class statistics.

        (==> the-classes setitems cc)
        (==> the-slots setitems cs)
        (==> the-methods setitems (sort-list cm >))
        (==> the-i-classes setitems ic)
        (==> the-i-slots setitems is)
        (==> the-i-methods setitems im)
        (==> the-string settext 
             (sprintf "  %l: %d+%d slots, %d+%d methods"
                      cn (length cs) isc (length cm) imc) ) ) ) ) )

We define then the various action methods which are called by the menu items, by the selectors, or by the class selection requester.

Method classes-action is called when the user selects a class in the subclass or superclass requester. This method just sends a message setclass to switch to the new class.

(defmethod c-classtool classes-action(c)
  (let ((cn (==> c getdata)))
    (==> this setclass (apply scope (list (named cn)))) ) )

Method methods-action is called when the user selects a method in the method selector or the inherited method selector. Method methods-action first makes sure that the user did not select a dummy entry used for separating the classes in the inherited method selector. It uses then function pretty-method to print the definition of the selected method.

(defmethod c-classtool methods-action(c)
  (let ((m (==> c getdata))
        (cl cl))
    (when (<> (left m 5) "=====")
          (setq m (named m))
          (while (and cl ~(member m (methods cl)))
            (setq cl (super cl)) )
          (when cl
                (==> this repair-damaged)
                (==> c setdata ())
                (print) 
                (pretty-method cl m) ) ) ) )

Method refresh-action is called by the menu item "Refresh" . It just calls method setclass on the current class (from slot cl ) in order to reload the class information.

(defmethod c-classtool refresh-action()
  (==> this setclass cl) )

Method display-action is called by the menu item "Show Class" . It just prints the class definition when adequate.

(defmethod c-classtool display-action()
  (if (not (super cl))
      (beep)
    (print)
    (pprint (nconc (list 'defclass (classname cl) (classname (super cl))) 
                   (slots cl) )) ) )

Method subtree-action is called by the menu item "Show Subtree" . It just prints an indented list of the subclasses of the current class.

(defmethod c-classtool subtree-action()
  (let ((subtree (lambda(cl tb)
                   (tab tb)
                   (print (classname cl))
                   (each ((c (subclasses cl)))
                         (subtree c (+ tb 2)) ) ) ))
    (print)
    (subtree cl 2) ) )

Method select-action is called when the class selection requester pops down. It gets the class name typed by the user (using getdata ), normalize the name and calls method setclass again.

(defmethod c-classtool select-action()
  (let ((cn (car (==> the-class-requester getdata))))
    (if (regex-match "\\|.*\\|" cn)
        (setq cn (regex-subst "^\\|(.*)\\|$" "%0" cn))
      (setq cn (downcase cn)) )
    (==> this setclass (apply scope (list (named cn)))) ) )

We override then method keypress in order to define an accelerator key. Depressing the space bar pops up the class selection requester. All other keypress events are handled by the default method which just ignore these events.

(defmethod c-classtool keypress(c x y)
  (selectq c
    (" " (==> the-class-requester popup))
    (t (==> this (windowobject . keypress) c x y)) ) )

Finally the hook function classtool creates an instance of class c-classtool and sets the initial class displayed in the browser

(de classtool( &optional (cl object) )
    (when (symbolp cl) 
          (setq cl (eval cl)) )
    (when (not (classp cl)) 
          (error t "Not a class" cl) )
    (let ((w (new c-classtool)))
      (==> w setclass cl) ) )

In addition, an autoload function classtool is defined in file "stdenv.lsh" which loads file "classtool.lsh" and calls this function classtool .