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-2016, Franz Inc. Oakland, CA., USA. All rights reserved.
This page was not revised from the 8.1 page.
Created 2010.1.21.