Although the task of creating a new widget may at first appear a little daunting, there is a basic simple pattern that all widgets follow. The Athena Widget library contains a special widget called the Template widget that is intended to assist the novice widget programmer in writing a custom widget. Reasons for wishing to write a custom widget include: Providing a graphical interface not currently supported by any existing widget set. Convenient access to resource management procedures to obtain fonts, colors, etc., even if user customization is not desired. Convenient access to user input dispatch and translation management procedures. Access to callback mechanism for building higher-level application libraries. Customizing the interface or behavior of an existing widget to suit a special application need. Desire to allow user customization of resources such as fonts, colors, etc., or to allow convenient re-binding of keys and buttons to internal functions. Converting a non-Toolkit application to use the Toolkit. In each of these cases, the operation needed to create a new widget is to "subclass" an existing one. If the desired semantics of the new widget are similar to an existing one, then the implementation of the existing widget should be examined to see how much work would be required to create a subclass that will then be able to share the existing class methods. Much time will be saved in writing the new widget if an existing widget class Expose, Resize and/or GeometryManager method can be used by the subclass. Note that some trivial uses of a ``bare-bones'' widget may be achieved by simply creating an instance of the Core widget. The class variable to use when creating a Core widget is widgetClass. The geometry of the Core widget is determined entirely by the parent widget. It is very often the case than an application will have a special need for a certain set of functions and that many copies of these functions will be needed. For example, when converting an older application to use the Toolkit, it may be desirable to have a "Window Widget" class that might have the following semantics: Allocate 2 drawing colors in addition to a background color. Allocate a text font. Execute an application-supplied function to handle exposure events. Execute an application-supplied function to handle user input events. It is obvious that a completely general-purpose WindowWidgetClass could be constructed that would export all class methods as callbacks lists, but such a widget would be very large and would have to choose some arbitrary number of resources such as colors to allocate. An application that used many instances of the general-purpose widget would therefore un-necessarily waste many resources. In this section, an outline will be given of the procedure to follow to construct a special-purpose widget to address the items listed above. The reader should refer to the appropriate sections of the X Toolkit Intrinsics - C Language Interface for complete details of the material outlined here. Section 1.4 of the Intrinsics should be read in conjunction with this section. All Athena widgets have three separate files associated with them: A "public" header file containing declarations needed by applications programmers A "private" header file containing additional declarations needed by the widget and any subclasses A source code file containing the implementation of the widget This separation of functions into three files is suggested for all widgets, but nothing in the Toolkit actually requires this format. In particular, a private widget created for a single application may easily combine the "public" and "private" header files into a single file, or merge the contents into another application header file. Similarly, the widget implementation can be merged into other application code. In the following example, the public header file < X11/Xaw/Template.h >, the private header file < X11/Xaw/TemplateP.h > and the source code file < X11/Xaw/Template.c > will be modified to produce the "WindowWidget" described above. In each case, the files have been designed so that a global string replacement of "Template" and "template" with the name of your new widget, using the appropriate case, can be done.