Class | Package: cg | ToC | DocOverview | CGDoc | RelNotes | FAQ | Index | PermutedIndex
| Allegro CL version 9.0 Unrevised from 8.2 to 9.0. 8.2 version

## lisp-widget

This is the class of all dialog-items that are implemented from scratch in Common Graphics, rather than utilizing controls that are supplied by the operating system. Common Graphics exports several such widgets, namely the `outline`, `dropping-outline`, `grid-widget`, `multi-picture-button`, `drawable`, and `group-box` widgets.

Applications may also write their own lisp-widgets. The basic procedure for defining a custom lisp-widget consists of the following:

1. Creating a subclass of `lisp-widget` for the dialog-item itself.
2. Creating a class that is a subclass of `lisp-widget-top-window`, to serve as the actual window that appears on the screen for the dialog-item. (In release 6.2 and earlier, two superclasses needed to be specified: `lisp-widget-top-window` and `lisp-widget-window`. In 7.0, only `lisp-widget-top-window` should be a superclass. Specifying `lisp-widget-window` as well will cause problems.)
3. Adding a widget-device method to associate the two subclasses above with each other.
4. Adding a device-open method for the `lisp-widget-top-window` subclass, which gets called automatically whenever an instance of the lisp-widget subclass is placed onto a parent window. This method should call open-lisp-widget-window on the stream object that is passed to device-open; this will create the actual window on the screen that is represented by the `lisp-widget-window` object. The device-open method should also do any needed initial setup of the widget, such as processing the initargs that were passed to make-instance to create the dialog-item instance. There is a built-in device-open method for `lisp-widget-top-window` that simply calls open-lisp-widget-window, so if that is sufficient then this step can be skipped.
5. Adding a redisplay-window method for the `lisp-widget-window` subclass, to draw the widget whenever it is uncovered or its value changes.
6. If the widget may have a value and needs to be redisplayed to reflect a new value, then adding a widget-set-value method for the `lisp-widget-window` subclass. This method should call invalidate on the `lisp-widget-window`, which causes its redisplay-window method to be called.
7. If the widget should respond to user mouse or keyboard events, adding methods on the `lisp-widget-window` subclass for such generic functions as mouse-left-down, mouse-moved, or virtual-key-down. These methods will typically determine a new value for the widget and call (setf value) to update the widget according to the user gesture.
8. Perhaps defining additional `lisp-widget-window` subclasses for any child windows that the widget may have. (Widgets usually do not have child windows.) These classes should NOT also be subclasses of `lisp-widget-top-window`. The device-open method should also create the needed child window instances, but by calling make-window rather than calling open-lisp-widget-window. The name of the `lisp-widget-window` subclass should be passed as the :class argument to make-window.
9. Perhaps adding a lisp-widget-draw-focus method and a lisp-widget-clear-focus for the `lisp-widget-window` subclass that either draws or erases an indication that the widget currently has the keyboard focus. These methods are called automatically as the widget gains and loses the keyboard focus. If the widget does not need to visually indicate when it has the focus, then these methods are not needed.

Details of the above procedure may be found in the source code for the Navigator examples called "Custom Widgets: implementing in lisp" and "Circle Widget: a simpler lisp widget". Navigator examples are displayed by the Help menu | CG Examples menu command.

A diagram of window and widget classes is shown in Widget and window classes in cgide.htm.

Copyright (c) 1998-2019, Franz Inc. Oakland, CA., USA. All rights reserved.
This page was not revised from the 8.2 page.
Created 2012.5.30.

|  | ToC | DocOverview | CGDoc | RelNotes | FAQ | Index | PermutedIndex
| Allegro CL version 9.0 Unrevised from 8.2 to 9.0. 8.2 version