12.3 Creating graphical objects

A common feature needed by an application is to have a number of objects displayed in a window and to make events affect the object underneath the cursor. The CAPI provides the ability to create graphical objects, to place them into a window at a specified size and position, and to display them as necessary. Also a function is provided to determine which object is under any given point so that events can be dispatched correctly.

These graphical objects are called pinboard objects , as they can only be displayed if they are contained within a pinboard-layout . To define a pinboard-object, you define a subclass of drawn-pinboard-object and specify a drawing routine for it (and you can also specify constraints on the size of your object). You can then make instances of these objects and place them into layouts just as if they were ordinary panes. You can also place these objects inside layouts as long as there is a pinboard-layout higher up the layout hierarchy that contains the panes.

Note: pinboard-object s are implement as graphics on a native window. Compare this with simple-pane and its subclasses, where each instance is itself a native window. A consequence of this is that simple-pane s do not work well within a pinboard-layout , since they always appear above the pinboard-object s. For example, to put labels on a pinboard, use item-pinboard-object rather than display-pane or title-pane .

Here is an example of the built-in pinboard object class item-pinboard-object which displays its text like a title-pane . Note that the function contain always creates a pinboard-layout as part of the wrapper for the object to be contained, and so it is possible to test the display of pinboard-object s in just the same way as you can test other classes of CAPI object.

(contain

  ;; CONTAIN makes a pinboard-layout if needed, so we don't

  ;; need one explicitly in this example.

  ;; You will need an explicit pinboard-layout if you define

  ;; your own interface class.

  (make-instance

   'item-pinboard-object

   :text "Hello world"))

Figure 12.4 A pinboard object

There is another example illustrating item-pinboard-object in the file

12.3.1 Buffered drawing

12.3.2 The implementation of graph panes

12.3.3 An example pinboard object

CAPI User Guide (Windows version) - 30 Aug 2011