\& .sp 1 .ce 3 \s+1\fBChapter 1\fP\s-1 \s+1\fBAthena Widgets and The Intrinsics\fP\s-1 .sp 2 .nr H1 1 .nr H2 0 .nr H3 0 .nr H4 0 .nr H5 0 .LP .XS Chapter 1 \- Athena Widgets and The Intrinsics .XE The Athena widget set and the \*(xI make up the \*(tk. In the \*(tk, a widget is the combination of an X window or subwindow and its associated input and output semantics. The Athena widgets provide the base functionality necessary to build a wide variety of application environments. Because the \*(xI mask implementation details from the widget and application programmer, the Athena widgets and the application environments built with them are fully compatible with the other widget sets built with the \*(xI. For information about the \*(xI, see the \fI\*(xT\fP. .LP The Athena widget set is a library package layered on top of the \*(xI and Xlib. This layer extends the basic abstractions provided by X and provides the next layer of functionality primarily by supplying a cohesive set of sample widgets. .LP To the extent possible, the \*(tk is policy free. The application environment, not the \*(tk, defines, implements, and enforces: .IP \(bu 5 Policy .IP \(bu 5 Consistency .IP \(bu 5 Style .LP Each individual widget implementation defines its own policy. The \*(tk design allows for but does not necessarily encourage the free mixing of radically differing widget implementations. .NH 2 Introduction to the \*(tk Library .LP .XS \*(SN Introduction to the \*(tk Library .XE The \*(tk library provides tools that simplify the design of application user interfaces in the X Window System programming environment. It assists application programmers by providing a set of common underlying user-interface functions. It also lets widget programmers modify existing widgets or add new widgets. By using the \*(tk library in their applications, programmers present a similar user interface across applications to all workstation users. .LP The \*(tk consists of: .IP \(bu 5 A set of \*(xI functions for building widgets .IP \(bu 5 An architectural model for constructing widgets .IP \(bu 5 A sample interface (widget set) for programming .LP While the majority of the \*(xI functions are intended for the widget programmer, a subset of the \*(xI functions are to be used by application programmers (see \fI\*(xT\fP). The architectural model lets the widget programmer design new widgets by using the \*(xI and by combining other widgets. The application interface layers built on top of the \*(tk include a coordinated set of widgets and composition policies. Some of these widgets and policies are specific to an application domain, and others are common across a number of application domains. .LP The \*(tk also can implement one or more application interface layers to: .IP \(bu 5 Verify the toolkit architecture .IP \(bu 5 Provide a base set of widgets and composition policies that can be incorporated in other application interface layers .IP \(bu 5 Make the \*(tk immediately usable by those application programmers who find that a supplied application interface layer meets their needs .LP The remainder of this chapter discusses the \*(tk: .IP \(bu 5 Terminology .IP \(bu 5 Model .IP \(bu 5 Design principles and philosophy .LE .NH 2 Terminology .LP .XS \*(SN Terminology .XE .LP In addition to the terms already defined for X programming (see \fI\*(xL\fP), the following terms are specific to the \*(xI and used throughout this book. .LP \fBApplication programmer\fP .IN "Application programmer" "" "@DEF@" .IP A programmer who uses the \*(tk to produce an application user interface. .LP .PN Child .IP A widget that is contained within another ("parent") widget. .LP \fBClass\fP .IN "Class" "" "@DEF@" .IP The general group to which a specific object belongs. .LP \fBClient\fP .IN "Client" "" "@DEF@" .IP A function that uses a widget in an application or for composing other widgets. .LP .PN "Full\ name" .IP The name of a widget instance appended to the full name of its parent. .LP \fBInstance\fP .IN "Instance" "" "@DEF@" .IP A specific widget object as opposed to a general widget class. .LP \fBMethod\fP .IN "Method" "" "@DEF@" .IP The functions or procedures that a widget class implements. .LP \fBName\fP .IN "Name" "" "@DEF@" .IP The name that is specific to an instance of a widget for a given client. .LP \fBObject\fP .IN "Object" "" "@DEF@" .IP A software data abstraction consisting of private data and private and public functions that operate on the private data. Users of the abstraction can interact with the object only through calls to the object's public functions. In the \*(tk, some of the object's public functions are called directly by the application, while others are called indirectly when the application calls the common \*(xI functions. In general, if a function is common to all widgets, an application uses a single \*(xI function to invoke the function for all types of widgets. If a function is unique to a single widget type, the widget exports the function as another ``Xt'' function. .LP .PN Parent .IP A widget that contains at least one other ("child") widget. A parent widget is also known as a composite widget. .LP \fBResource\fP .IN "Resource" "" "@DEF@" .IP A named piece of data in a widget that can be set by a client, by an application, or by user defaults. .LP .PN Superclass .IP A larger class of which a specific class is a member. All members of a class are also members of the superclass. .LP \fBUser\fP .IN "User" "" "@DEF@" .IP A person interacting with a workstation. .LP \fBWidget\fP .IN "Widget" "" "@DEF@" .IP An object providing a user-interface abstraction (for example, a Scrollbar widget). .LP \fBWidget class\fP .IN "Widget class" "" "@DEF@" .IP The general group to which a specific widget belongs, otherwise known as the type of the widget. .LP \fBWidget programmer\fP .IN "Widget programmer" "" "@DEF@" .IP A programmer who adds new widgets to the \*(tk. .NH 2 Underlying Model .LP .XS \*(SN Underlying Model .XE The underlying architectural model is based on the following premises: .KS .IP "Widgets are X windows" .IP Every user-interface widget is contained in a unique X window. The X window ID for a widget is readily available from the widget ID, so standard Xlib window manipulation procedures can operate on widgets. .KE .KS .IP "Information hiding" .IP The data for every widget is private to the widget and its subclasses. That is, the data is neither directly accessible nor visible outside of the module implementing the widget. All program interaction with the widget is performed by a set of operations (methods) that are defined for the widget. .KE .KS .IP "Widget semantics and widget layout geometry" .IP Widget semantics are clearly separated from widget layout geometry. Widgets are concerned with implementing specific user-interface semantics. They have little control over issues such as their size or placement relative to other widget peers. Mechanisms are provided for associating geometric managers with widgets and for widgets to make suggestions about their own geometry. .KE .NH 2 Design Principles and Philosophy .LP .XS \*(SN Design Principles and Philosophy .XE The \*(tk follows two design principles throughout, which cover languages and language bindings as well as widget IDs. .NH 3 Languages and Language Bindings .LP The \*(tk facilitates access from objective languages. However, the \*(tk library is conveniently usable by application programs written in nonobjective languages. Procedural interface guidelines are required when the \*(tk is used with nonobjective languages. .LP The guidelines for the procedural interfaces are: .IP \(bu 5 Strings are passed as null-terminated character arrays. .IP \(bu 5 Most other arrays are passed using two parameters: a size and a pointer to the first element. .IP \(bu 5 Most numeric arguments are passed by value. .IP \(bu 5 Structures as arguments are avoided, unless a method for building them is provided for languages without pointers. Pointers embedded in structures are allowed, but they should be avoided if an equivalent alternative is available. .IP \(bu 5 Pointers are not recommended as return arguments, unless they will never have to be dereferenced by the caller. If they need to be dereferenced, the caller should allocate storage and pass the address to the procedure to fill in. .IP \(bu 5 Procedures can be passed as parameters. .IP \(bu 5 The ownership of dynamically allocated storage is determined on a case-by-case basis. The application is also permitted to replace the standard memory allocation and freeing routines used by the library at build time. .NH 3 Widget IDs .LP All references to widgets use a unique identifier that is known as the widget ID. The widget ID is returned to the client by the .PN XtCreateWidget function. From an application programmer's perspective, a widget ID is an opaque data type; no particular interpretation can be assigned to it. Given a widget ID, you can retrieve the corresponding X window ID, the .PN Display and .PN Screen structures, and other information by using \*(xI functions. .LP From a widget programmer's perspective, the widget ID actually is a pointer to a data structure known as the widget instance record. Several parts of the data structure are common to all widget types, while other parts are unique to a particular widget type. The widget's private data that is associated with a particular widget instance normally is included directly in the widget instance record. .bp \& .sp 1 .ce 3 \s+1\fBChapter 2\fP\s-1 \s+1\fBUsing Widgets\fP\s-1 .sp 2 .nr H1 2 .nr H2 0 .nr H3 0 .nr H4 0 .nr H5 0 .LP .XS Chapter 2 \- Using Widgets .XE Widgets serve as the primary tools for building a user interface or application environment. The widget set consists of primitive widgets (for example, a command button) and composite widgets (for example, a Dialog widget). .LP The remaining chapters of this guide explain the widgets and the geometry managers that work together to provide a set of user-interface components. These user-interface components serve as a default interface for application programmers who do not want to implement their own widgets. In addition, they serve as examples or a starting point for those widget programmers who, using the \*(xI mechanisms, want to implement alternative application programming interfaces. .LP This chapter discusses the common features of the \*(tk widgets. .NH 2 Initializing the Toolkit .LP .XS \*(SN Initializing the Toolkit .XE You must invoke the toolkit initialization function .PN XtInitialize before invoking any other toolkit routines. .PN XtInitialize opens the X server connection, parses standard parts of the command line, and creates an initial widget that is to serve as the root of a tree of widgets that will be created by this application. .IN "XtInitialize" "" "@DEF@" .FD 0 Widget XtInitialize(\fIshell_name\fP, \fIapplication_class\fP, \fIoptions\fP, \ \fInum_options\fP, \fIargc\fP, \fIargv\fP) .br String \fIshell_name\fP; .br String \fIapplication_class\fP; .br XrmOptionDescRec \fIoptions\fP[]; .br Cardinal \fInum_options\fP; .br Cardinal *\fIargc\fP; .br String \fIargv\fP[]; .FN .IP \fIshell_name\fP 1i Specifies the name of the application shell widget instance, which usually is something generic like ``main''. .IP \fIapplication_class\ \ \ \fP 1i Specifies the class name of this application, which usually is the generic name for all instances of this application. By convention, the class name is formed by reversing the case of the application's first significant letter. For example, an application named ``xterm'' would have a class name of ``XTerm''. .IP \fIoptions\fP 1i Specifies how to parse the command line for any application-specific resources. The options argument is passed as a parameter to .PN XrmParseCommand . For further information, see \fI\*(xL\fP. .IP \fInum_options\fP 1i Specifies the number of entries in the options list. .IP \fIargc\fP 1i Specifies a pointer to the number of command line parameters. .IP \fIargv\fP 1i Specifies the command line parameters. .LP For further information about this function, see the \fI\*(xI\fP. .NH 2 Creating a Widget .LP .XS \*(SN Creating a Widget .XE Creating a widget is a three-step process. First, the widget instance is allocated, and various instance-specific attributes are set by using .PN XtCreateWidget . Second, the widget's parent is informed of the new child by using .PN XtManageChild . Finally, X windows are created for the parent and all its children by using .PN XtRealizeWidget and specifying the top-most widget. The first two steps can be combined by using .PN XtCreateManagedWidget . In addition, .PN XtRealizeWidget is automatically called when the child becomes managed if the parent is already realized. .LP To allocate and initialize a widget, use .PN XtCreateWidget . .IN "XtCreateWidget" "" "@DEF@" .FD 0 Widget XtCreateWidget(\fIname\fP, \fIwidget_class\fP, \fIparent\fP, \ \fIargs\fP, \fInum_args\fP) .br String \fIname\fP; .br WidgetClass \fIwidget_class\fP; .br Widget \fIparent\fP; .br ArgList \fIargs\fP; .br Cardinal \fInum_args\fP; .FN .IP \fIname\fP 1i Specifies the instance name for the created widget that is used for retrieving widget resources. .IP \fIwidget_class\fP 1i Specifies the widget class pointer for the created widget. .IP \fIparent\fP 1i Specifies the parent widget ID. .IP \fIargs\fP 1i Specifies the argument list. The argument list is a variable-length list composed of name and value pairs that contain information pertaining to the specific widget instance being created. For further information, see Section 2.7.2. .IP \fInum_args\fP 1i Specifies the number of arguments in the argument list. When the num_args is zero, the argument list is never referenced. .LP When a widget instance is successfully created, the widget identifier is returned to the application. If an error is encountered, the .PN XtError routine is invoked to inform the user of the error. .LP For further information, see the \fI\*(xI\fP. .NH 2 Common Arguments in the Widget Argument List .LP Although a widget can have unique arguments that it understands, all widgets have common arguments that provide some regularity of operation. The common arguments allow arbitrary widgets to be managed by higher-level components without regards to the individual widget type. All widgets ignore any argument that they do not understand. .LP The following resources are retrieved from the argument list or from the resource database by all \*(tk widgets: .ps 9 .nr PS 9 .vs 11 .nr VS 11 .TS H lw(1.5i) lw(1i) lw(1i) lw(2i). _ .sp 3p .TB Name Type Default Description .sp 3p _ .TH .R .sp 3p XtNbackground Pixel XtDefaultBackground Window background color XtNbackgroundPixmap Pixmap None Window background pixmap XtNborderColor Pixel XtDefaultForeground Window border color XtNborderPixmap Pixmap None Window border pixmap XtNborderWidth Dimension 1 Width of the border in pixels T{ XtNdestroyCallback T} T{ XtCallbackList T} T{ NULL T} T{ Callback for .PN XtDestroyWidget T} XtNheight Dimension Widget dependent Height of the widget T{ XtNmappedWhenManaged T} T{ Boolean T} T{ True T} T{ Whether .PN XtMapWidget is automatic T} XtNsensitive Boolean True Whether widget should receive input XtNtranslations TranslationTable None Event-to-action translations XtNwidth Dimension Widget dependent Width of the widget XtNx Position 0 x coordinate within parent XtNy Position 0 y coordinate within parent .sp 3p _ .TE .ps 11 .nr PS 11 .vs 13 .nr VS 13 .LP The following additional resources are retrieved from the argument list or from the resource database by many \*(tk widgets: .ps 9 .nr PS 9 .vs 11 .nr VS 11 .TS H lw(1.5i) lw(1i) lw(1i) lw(2i). _ .sp 3p .TB Name Type Default Description .sp 3p _ .TH .R .sp 3p XtNcallback XtCallbackList NULL Callback functions and client data XtNcursor Cursor None Pointer cursor XtNforeground Pixel XtDefaultForeground Foreground color .sp 3p _ .TE .ps 11 .nr PS 11 .vs 13 .nr VS 13 .LP The value for the XtNcursor resource can be specified in the resource database as a string, which can be specified as one of the following: .IP \(bu 5 A standard X cursor name from .Pn < X11/cursorfont.h > .IP \(bu 5 FONT font-name glyph-index [[ font-name ] glyph-index ] .IP \(bu 5 A relative or absolute file name .LP The first font and glyph specify the cursor source pixmap. The second font and glyph specify the cursor mask pixmap. The mask font defaults to the source font, and the mask glyph index defaults to the source glyph index. .LP If a relative or absolute file name is specified, that file is used to create the source pixmap. Then the string "Mask" is appended to locate the cursor mask pixmap. If the "Mask" file does not exist, the suffix "msk" is tried. If "msk" fails, no cursor mask will be used. If a relative file name is used, the directory specified by the resource name .PN bitmapFilePath or class .PN BitmapFilePath is added to the beginning of the file name. If the .PN bitmapFilePath resource is not defined, the default directory on a UNIX-based system is .PN /usr/include/X11/bitmaps . .NH 2 Realizing a Widget .LP .XS \*(SN Realizing a Widget .XE The .PN XtRealizeWidget function performs two tasks: .IP \(bu 5 Creates an X window for the widget and, if it is a composite widget, for each of its managed children. .IP \(bu 5 Maps each window onto the screen. .IN "XtRealizeWidget" "" "@DEF@" .FD 0 void XtRealizeWidget(\fIw\fP) .br Widget \fIw\fP; .FN .IP \fIw\fP 1i Specifies the widget. .LP For further information about this function, see the \fI\*(xT\fP. .NH 2 Standard Widget Manipulation Functions .LP .XS \*(SN Standard Widget Manipulation Functions .XE After a widget has been created, a client can interact with that widget by calling either of the following: .IP \(bu 5 One of the standard widget manipulation routines that provide functions that all widgets support .IP \(bu 5 A widget class-specific manipulation routine .LP The \*(tk provides generic routines to provide the application programmer access to a set of standard widget functions. These routines let an application or composite widget manipulate widgets without requiring explicit knowledge of the widget type. The standard widget manipulation functions let you: .IP \(bu 5 Control the location, size and mapping of widget windows .IP \(bu 5 Destroy a widget instance .IP \(bu 5 Obtain an argument value .IP \(bu 5 Set an argument value .NH 3 Mapping Widgets .LP By default, widget windows automatically are mapped (made viewable) by .PN XtRealizeWidget . This behavior can be changed by using .PN XtSetMappedWhenManaged , and it then is the client's responsibility to use the .PN XtMapWidget function to make the widget viewable. .IN "XtSetMappedWhenManaged" "" @DEF@" .FD 0 void XtSetMappedWhenManaged(\fIw\fP, \fImap_when_managed\fP) .br Widget \fIw\fP; .br Boolean \fImap_when_managed\fP; .FN .IP \fIw\fP 1i Specifies the widget. .IP \fImap_when_managed\fP 1i Specifies the new value. If map_when_managed is .PN True , the widget is mapped automatically when it is realized. If map_when_managed is .PN False , the client must call .PN XtMapWidget or make a second call to .PN XtSetMappedWhenManaged to cause the child window to be mapped. .LP .sp The definition for .PN XtMapWidget is: .IN "XtMapWidget" "" "@DEF@" .FD 0 XtMapWidget(\fIw\fP) .br Widget \fIw\fP; .FN .IP \fIw\fP 1i Specifies the widget. .LP When you create several children in sequence for a common parent after it has been realized, it is generally more efficient to construct a list of children as they are created and use .PN XtManageChildren to inform their parent of them all at once, instead of causing each child to be managed separately. By managing a list of children at one time, the parent can avoid wasteful duplication of geometry processing and the associated "screen flash". .IN "XtManageChildren" "" "@DEF@" .FD 0 void XtManageChildren(\fIchildren\fP, \fInum_children\fP) .br WidgetList \fIchildren\fP; .br Cardinal \fInum_children\fP; .FN .IP \fIchildren\fP 1i Specifies a list of children to add. .IP \fInum_children\fP 1i Specifies the number of children to add. .LP If the parent is already visible on the screen, it is especially important to batch updates so that the minimum amount of visible window reconfiguration is performed. .LP For further information about these functions, see the \fI\*(xI\fP. .NH 3 Destroying Widgets .LP To destroy a widget instance of any type, use .PN XtDestroyWidget . .IN "XtDestroyWidget" "" "@DEF@" .FD 0 void XtDestroyWidget(\fIw\fP) .br Widget \fIw\fP; .FN .IP \fIw\fP 1i Specifies the widget. .LP .PN XtDestroyWidget destroys the widget and recursively destroys any children that it may have, including the windows created by its children. After calling .PN XtDestroyWidget , no further references should be made to the widget or to the widget IDs of any children that the destroyed widget may have had. .NH 3 Retrieving Widget Resource Values .LP To retrieve the current value of a resource attribute associated with a widget instance, use .PN XtGetValues . .IN "XtGetValues" "" "@DEF@" .FD 0 void XtGetValues(\fIw\fP, \fIargs\fP, \fInum_args\fP) .br Widget \fIw\fP; .br ArgList \fIargs\fP; .br Cardinal \fInum_args\fP; .FN .IP \fIw\fP 1i Specifies the widget. .IP \fIargs\fP 1i Specifies a variable-length argument list of name and address pairs that contain the resource name and the address into which the resource value is stored. .IP \fInum_args\fP 1i Specifies the number of arguments in the argument list. .LP The arguments and values passed in the argument list are dependent on the widget. Note that the caller is responsible for allocating space into which the returned resource value is copied; the .PN ArgList contains a pointer to this storage. The caller must allocate storage of the type as represented in the widget. For example, x and y must be allocated as Position and so on. For further information, see the \fI\*(xT\fP. .NH 3 Modifying Widget Resource Values .LP To modify the current value of a resource attribute associated with a widget instance, use .PN XtSetValues . .IN "XtSetValues" "" "@DEF@" .FD 0 void XtSetValues(\fIw\fP, \fIargs\fP, \fInum_args\fP) .br Widget \fIw\fP; .br ArgList \fIargs\fP; .br Cardinal \fInum_args\fP; .FN .IP \fIw\fP 1i Specifies the widget. .IP \fIargs\fP 1i Specifies a variable-length argument list of name and value pairs that contain the arguments to be modified and their new values. .IP \fInum_args\fP 1i Specifies the number of arguments in the argument list. .LP The arguments and values passed in the argument list depend on the widget being modified. Some widgets may not allow certain resources to be modified after the widget instance has been created or realized. No notification is given if any part of a .PN XtSetValues request is ignored. .LP For further information about these functions, see the \fI\*(xI\fP. .NT The argument list entry for .PN XtGetValues specifies the address to which the caller wants the value copied. The argument list entry for .PN XtSetValues , however, contains the new value itself if the size of value is less than sizeof(XtArgVal) (architecture dependent, but at least sizeof(long)); otherwise, it is a pointer to the value. String resources are always passed as pointers, regardless of the length of the string. .NE .NH 2 Using the Client Callback Interface .LP .XS \*(SN Using the Client Callback Interface .XE Widgets communicate changes in their state to their clients by means of a callback facility. The format for a client's callback handler is: .IN "CallbackProc" "" "@DEF@" .FD 0 void \fICallbackProc\fP(\fIw\fP, \fIclient_data\fP, \fIcall_data\fP) .br Widget \fIw\fP; .br caddr_t \fIclient_data\fP; .br caddr_t \fIcall_data\fP; .FN .IP \fIw\fP 1i Specifies widget for which the callback is registered. .IP \fIclient_data\fP 1i Specifies arbitrary client-supplied data that the widget should pass back to the client when the widget executes the client's callback procedure. This is a way for the client registering the callback to also register client-specific data: a pointer to additional information about the widget, a reason for invoking the callback, and so on. It is perfectly normal to have client_data of NULL if all necessary information is in the widget. This field is also frequently known as the \fIclosure\fP. .IP \fIcall_data\fP 1i Specifies any callback-specific data the widget wants to pass to the client. For example, when Scrollbar executes its jumpProc callback list, it passes the current position of the thumb in the call_data argument. .LP Callbacks can be registered with widgets in one of two ways. When the widget is created, a pointer to a list of callback procedure and data pairs can be passed in the argument list to .PN XtCreateWidget . The list is of type .PN XtCallbackList : .IN "XtCallbackProc" .IN "XtCallbackList" "" "@DEF@" .LP .Ds 0 .TA .5i 3i .ta .5i 3i typedef struct { XtCallbackProc callback; caddr_t closure; } XtCallbackRec, *XtCallbackList; .De .LP The callback list must be allocated and initialized before calling .PN XtCreateWidget . The end of the list is identified by an entry containing NULL in callback and closure. Once the widget is created, the client can change or de-allocate this list; The widget itself makes no further reference to it. The closure field contains the client_data passed to the callback when the callback list is executed. .LP The second method for registering callbacks is to use .PN XtAddCallback after the widget has been created. .IN "XtAddCallback" "" "@DEF@" .FD 0 void XtAddCallback(\fIw\fP, \fIcallback_name, \fP\fIcallback\fP, \ \fIclient_data\fP) .br Widget \fIw\fP; .br String \fIcallback_name\fP; .br XtCallbackProc \fIcallback\fP; .br caddr_t \fIclient_data\fP; .FN .IP \fIw\fP 1i Specifies the widget to add the callback to. .IP \fIcallback_name\fP 1i Specifies the callback list within the widget to append to. .IP \fIcallback\fP 1i Specifies the callback procedure to add. .IP \fIclient_data\fP 1i Specifies the data to be passed to the callback when it is invoked. .LP .PN XtAddCallback adds the specified callback to the list for the named widget. .LP All widgets provide a callback list named .PN XtNdestroyCallback where clients can register procedures that are to be executed when the widget is destroyed. The destroy callbacks are executed when the widget or an ancestor is destroyed. The call_data argument is unused for destroy callbacks. .LP The \*(tk \*(xI provide additional functions for further manipulating a callback list. For information about these functions, see .PN XtCallCallbacks , .PN XtRemoveCallback , .PN XtRemoveCallbacks , and .PN XtRemoveAllCallbacks in the \fI\*(xT\fP. .NH 2 Programming Considerations .LP .XS \*(SN Programming Considerations .XE This section provides some guidelines to set up an application program that uses the \*(tk. This section discusses: .IP \(bu 5 Writing applications .IP \(bu 5 Creating argument lists .NH 3 Writing Applications .LP When writing an application that uses the toolkit, you should make sure that your application performs the following: .IP 1. 5 Include .Pn < X11/Intrinsic.h > in your application programs. This header file automatically includes .Pn < X11/Xlib.h >, so all Xlib functions also are defined. .IP 2. 5 Include the widget-specific header files for each widget type that you need to use. For example, .Pn < X11/Label.h > and .Pn < X11/Command.h >. .IP 3. 5 Call the .PN XtInitialize function before invoking any other toolkit or Xlib functions. For further information, see Section 2.1 and the \fI\*(xT\fP. .IP 4. 5 To pass attributes to the widget creation routines that will over-ride any site or user customizations, set up argument lists. In this document, a list of valid argument names that start with .PN XtN is provided in the discussion of each widget. .IP For further information, see Section 2.7.2. .IP 5. 5 When the argument list is set up, create the widget by using the .PN XtCreateWidget function. For further information, see Section 2.2 and the \fI\*(xT\fP. .IP 6. 5 If the widget has any callback routines, which are usually defined by the .PN XtNcallback argument or the .PN XtAddCallback function, declare these routines within the application. .IP 7. 5 After a widget has been created, use .PN XtManageChild to manage it. If there is no manipulation of the widget between .PN XtCreateWidget and .PN XtManageChild, you can do this in a single step by using .PN XtCreateManagedWidget . For further information about these functions, see the \fI\*(xI\fP. .IP 8. 5 After creating the initial widget hierarchy, windows must be created for each widget by calling .PN XtRealizeWidget on the top level widget. .IP 9. 5 Most applications now sit in a loop processing events using .PN XtMainLoop , for example: .IP .Ds 0 XtCreateManagedWidget(\fIname\fP, \fIclass\fP, \fIparent\fP, \fIargs\fP, \fInum_args\fP); XtRealizeWidget(\fIparent\fP); XtMainLoop(\|); .De .IP For information about this function, see the \fI\*(xT\fP. .IP 10. 5 Link your application with .PN libXaw.a (the Athena widgets), .PN libXmu.a (miscellaneous utilities), .PN libXt.a (the \*(tk \*(xI), and .PN libX11.a (the core X library). The following provides a sample command line: .IP .Ds 0 cc -o \fIapplication\fP \fIapplication\fP.c \-lXaw \-lXmu \-lXt \-lX11 .De .NH 3 Creating Argument Lists .LP To set up an argument list for the inline specification of widget attributes, you can use one of the four approaches discussed in this section. You should use whichever approach fits the needs of the application and you are most comfortable with. In general, argument lists should be kept as short as possible to allow widget attributes to be specified through the resource database. Whenever a client inserts a specific attribute value in an argument list, the user is prevented from customizing the behavior of the widget. Resource names in the resource database, by convention, correspond to their symbolic names that are used in argument list without the .PN XtN prefix. For example, the resource name for .PN XtNforeground is ``foreground''. For further information, see the \fI\*(xI\fP. .LP The .PN Arg structure contains: .IN "ArgList" "" "@DEF@" .IN "Arg" "" "@DEF@" .LP .Ds 0 .TA .5i 1.5i .ta .5i 1.5i typedef struct { String name; XtArgVal value; } Arg, *ArgList; .De .LP The first approach lets you statically initialize the argument list. For example: .LP .Ds 0 .TA .5i .ta .5i static Arg arglist[] = { {XtNwidth, (XtArgVal) 400}, {XtNheight, (XtArgVal) 300}, }; .De .LP This approach makes it easy to add or delete new elements. The .PN XtNumber macro can be used to compute the number of elements in the argument list, thus preventing simple programming errors. The following provides an example: .LP .Ds XtCreateWidget(\fIname\fP, \fIclass\fP, \fIparent\fP, \fIarglist\fP, XtNumber(\fIarglist\fP)); .De .LP The second approach lets you use the .PN XtSetArg macro. For example: .LP .Ds 0 .TA .5i .ta .5i Arg arglist[10]; XtSetArg(arglist[1], XtNwidth, 400); XtSetArg(arglist[2], XtNheight, 300); .De .LP To make it easier to insert and delete entries, you also can use a variable index, as in this example: .LP .Ds 0 .TA .5i .ta .5i Arg arglist[10]; Cardinal i=0; XtSetArg(arglist[i], XtNwidth, 400); i++; XtSetArg(arglist[i], XtNheight, 300); i++; .De .LP The i variable can then be used as the argument list count in the widget create function. In this example, .PN XtNumber would return 10, not 2, and therefore is not useful. .NT You should not use auto-increment or auto-decrement within the first argument to .PN XtSetArg . As it is currently implemented, .PN XtSetArg is a macro that dereferences the first argument twice. .NE .LP The third approach lets you individually set the elements of the argument list array, one piece at a time. For example: .LP .Ds 0 .TA .5i .ta .5i Arg arglist[10]; arglist[0].name = XtNwidth; arglist[0].value = (XtArgVal) 400; arglist[1].name = XtNheight; arglist[1].value = (XtArgVal) 300; .De .LP Note that in this example, as in the previous example, .PN XtNumber would return 10, not 2, and therefore is not useful. .LP The fourth approach lets you use a mixture of the first and third approaches: you can statically define the argument list but modify some entries at runtime. For example: .LP .Ds 0 .TA .5i .ta .5i static Arg arglist[] = { {XtNwidth, (XtArgVal) 400}, {XtNheight, (XtArgVal) NULL}, }; arglist[1].value = (XtArgVal) 300; .De .LP In this example, .PN XtNumber can be used, as in the first approach, for easier code maintenance. .NH 3 Sample Program .LP The following program creates one command button that, when pressed, causes the program to exit. This example is a complete program that illustrates: .IP \(bu 5 Toolkit initialization .IP \(bu 5 Optional command-line arguments .IP \(bu 5 Widget creation .IP \(bu 5 Callback routines .LP .bp .ps 9 .nr PS 9 .Ds 0 .TA .5i 2i .ta .5i 2i #include #include #include .sp 6p static XrmOptionDescRec options[] = { {"\-label", "*button.label", XrmoptionSepArg, NULL} }; .sp 6p Syntax(call) char *call; { fprintf(stderr, "Usage: %s\\n", call); } .sp 6p void Activate(w, client_data, call_data) Widget w; caddr_t client_data; /* unused */ caddr_t call_data; /* unused */ { printf("button was activated.\\n"); exit(0); } .sp 6p void main(argc, argv) unsigned int argc; char **argv; { Widget toplevel; static XtCallbackRec callbacks[] = { \ \ \ \ { Activate, NULL }, \ \ \ \ { NULL, NULL }, }; .sp 6p static Arg args[] = { \ \ { XtNcallback, (XtArgVal)callbacks }, }; .sp 6p toplevel = XtInitialize("main", "Demo", options, XtNumber(options), &argc, argv ); if (argc != 1) Syntax(argv[0]); .sp 6p XtCreateManagedWidget("button",commandWidgetClass,toplevel,args,XtNumber(args)); .sp 6p XtRealizeWidget(toplevel); XtMainLoop(\|); } .De .ps 11 .nr PS 11 .bp \& .sp 1 .ce 3 \s+1\fBChapter 3\fP\s-1 \s+1\fBAthena Widget Set\fP\s-1 .sp 2 .nr H1 3 .nr H2 0 .nr H3 0 .nr H4 0 .nr H5 0 .na .LP .XS Chapter 3 - Athena Widget Set .XE .LP This chapter describes the following Athena widgets: .IP \(bu 5 Command .IP \(bu 5 Label .IP \(bu 5 Text .IP \(bu 5 Scrollbar .IP \(bu 5 Viewport .IP \(bu 5 Box .\".IP \(bu 5 .\"MenuBox .IP \(bu 5 VPaned .IP \(bu 5 Form .IP \(bu 5 Dialog .IP \(bu 5 List .IP \(bu 5 Grip .IP \(bu 5 Toggle .LE .NH 2 Command Widget .LP .XS \*(SN Command Widget .XE .IN "Command widget" "" "@DEF@" The Command widget is a rectangular button that contains a text or pixmap label. When the pointer cursor is on the button, the button border is highlighted to indicate that the button is available for selection. Then, when a pointer button is pressed and released the button is selected, and the application's callback routine is invoked. .LP The class variable for the Command widget is .PN commandWidgetClass . .LP When creating a Command widget instance, the following resources are retrieved from the argument list or from the resource database: .IN "Command widget" "resources" .ps 9 .nr PS 9 .vs 11 .nr VS 11 .TS H lw(1.5i) lw(1i) lw(1i) lw(2i). _ .sp 3p .TB Name Type Default Description .sp 3p _ .TH .R .sp 3p XtNbackground Pixel XtDefaultBackground Window background color XtNbackgroundPixmap Pixmap None Window background pixmap T{ XtNbitmap T} T{ Pixmap T} T{ None T} T{ Pixmap to display in place of the label T} XtNborderColor Pixel XtDefaultForeground Window border color XtNborderPixmap Pixmap None Window border pixmap XtNborderWidth Dimension 1 Width of button border XtNcallback XtCallbackList NULL Callback for button select XtNcursor Cursor None Pointer cursor T{ XtNdestroyCallback T} T{ XtCallbackList T} T{ NULL T} T{ Callbacks for .PN XtDestroyWidget T} XtNfont XFontStruct* XtDefaultFont Label font XtNforeground Pixel XtDefaultForeground Foreground color XtNheight Dimension Text height Button height T{ XtNhighlightThickness T} T{ Dimension T} T{ 2 T} T{ Width of border to be highlighted T} XtNinsensitiveBorder Pixmap Gray Border when not sensitive T{ XtNinternalHeight T} T{ Dimension T} T{ 2 T} T{ Internal border height for highlighting T} T{ XtNinternalWidth T} T{ Dimension T} T{ 4 T} T{ Internal border width for highlighting T} XtNjustify XtJustify XtJustifyCenter Type of text alignment XtNlabel String Button name Button label T{ XtNmappedWhenManaged T} T{ Boolean T} T{ True T} T{ Whether .PN XtMapWidget is automatic T} XtNresize Boolean True Whether to auto-resize in SetValues XtNsensitive Boolean True Whether widget receives input XtNtranslations TranslationTable see below Event-to-action translations XtNwidth Dimension Text width Button width XtNx Position 0 x coordinate XtNy Position 0 y coordinate .sp 3p _ .TE .ps 11 .nr PS 11 .vs 13 .nr VS 13 .LP The new resources associated with the Command widget are: .TS lw(1.5i) lw(4i). T{ .PN XtNbitmap T} T{ Specifies a bitmap to display in place of the text label. See the description of this resource in the Label widget for further details. T} .sp 6p T{ .PN XtNheight T} T{ Specifies the height of the Command widget. The default value is the minimum height that will contain: .br XtNinternalheight + height of XtNlabel + XtNinternalHeight .br If the specified height is larger than the minimum, the label string is centered vertically. T} .sp 6p T{ .PN XtNinternalHeight T} T{ Represents the distance in pixels between the top and bottom of the label text or bitmap and the horizontal edges of the Command widget. HighlightThickness can be larger or smaller than this value. T} .sp 6p T{ .PN XtNinternalWidth T} T{ Represents the distance in pixels between the ends of the label text or bitmap and the vertical edges of the Command widget. HighlightThickness can be larger or smaller than this value. T} .sp 6p T{ .PN XtNjustify T} T{ Specifies left, center, or right alignment of the label string within the Command widget. If it is specified within an .PN ArgList , one of the values .PN XtJustifyLeft , .PN XtJustifyCenter , or .PN XtJustifyRight can be specified. In a resource of type ``string'', one of the values ``left'', ``center'', or ``right'' can be specified. T} .sp 6p T{ .PN XtNlabel T} T{ Specifies the text string that is to be displayed in the Command widget if no bitmap is specified. The default is the widget name of the Command widget. T} .sp 6p T{ .PN XtNresize T} T{ Specifies whether the Command widget should attempt to resize to its preferred dimensions whenever .PN XtSetValues is called for it. The default is .PN True . T} .sp 6p T{ .PN XtNsensitive T} T{ If set to .PN False , the Command widget will change its window border to .PN XtNinsensitiveBorder and will stipple the label string. T} .sp 6p T{ .PN XtNwidth T} T{ Specifies the width of the Command widget. The default value is the minimum width that will contain: .br XtNinternalWidth + width of XtNlabel + XtNinternalWidth .br If the width is larger or smaller than the minimum, .PN XtNjustify determines how the label string is aligned. T} .TE .LP The Command widget supports the following actions: .IP \(bu 5 Switching the button between the foreground and background colors with \fBset\fP and \fBunset\fP .IP \(bu 5 Processing application callbacks with \fBnotify\fP .IP \(bu 5 Switching the internal border between highlighted and unhighlighted states with \fBhighlight\fP and \fBunhighlight\fP .LE .LP The following are the default translation bindings that are used by the Command widget: .LP .Ds 0 .TA .5i 2.25i .ta .5i 2.25i : highlight(\|) : reset(\|) : set(\|) : notify(\|) unset(\|) .De .LP With these bindings, the user can cancel the action before releasing the button by moving the pointer out of the Command widget. .NH 3 Command Actions .LP The full list of actions supported by Command is: .IP \fBhighlight\fP(\fIcondition\fP) 1.5i Displays the internal highlight border in the color (\fBXtNforeground\fP or .PN XtNbackground ) that contrasts with the interior color of the Command widget. This action procedure takes one of the following conditions: WhenUnset and Always. If no argument is passed then WhenUnset is assumed, this maintains backwards compatibility. .IP \fBunhighlight\fP(\|) 1.5i Displays the internal highlight border in the color (\fBXtNforeground\fP or .PN XtNbackground ) that matches the interior color of the Command widget. .IP \fBset\fP(\|) 1.5i Enters the "set" state, in which \fBnotify\fP is possible and displays the interior of the button in the .PN XtNforeground color. The label is displayed in the .PN XtNbackground color. .IP \fBunset\fP(\|) 1.5i Cancels the "set" state and displays the interior of the button in the .PN XtNbackground color. The label is displayed in the .PN XtNforeground color. .IP \fBreset\fP(\|) 1.5i Cancels any \fBset\fP or \fBhighlight\fP and displays the interior of the button in the .PN XtNbackground color, with the label displayed in the .PN XtNforeground color. .IP \fBnotify\fP(\|) 1.5i Executes the .PN XtNcallback callback list if executed in the \fBset\fP state. The value of the call_data argument is undefined. .LP .IN "Command widget" "creating" .IN "Creating widgets" "Command" To create a Command widget instance, use .PN XtCreateWidget and specify the class variable .PN commandWidgetClass . .LP .IN "Command widget" "destroying" .IN "Destroying widgets" "Command" To destroy a Command widget instance, use .PN XtDestroyWidget and specify the widget ID of the button. .LP The Command widget supports two callback lists: .PN XtNdestroyCallback and .PN XtNcallback . The notify action executes the callbacks on the .PN XtNcallback list. The call_data argument is unused. .NH 2 Label Widget .LP .XS \*(SN Label Widget .XE .IN "Label widget" "" "@DEF@" A Label is an noneditable text string or pixmap that is displayed within a window. The string is limited to one line and can be aligned to the left, right, or center of its window. A Label can neither be selected nor directly edited by the user. .LP The class variable for the Label widget is .PN labelWidgetClass . .LP When creating a Label widget instance, the following resources are retrieved from the argument list or from the resource database: .IN "Label widget" "resources" .ps 9 .nr PS 9 .vs 11 .nr VS 11 .TS H lw(1.5i) lw(1i) lw(1i) lw(2i). _ .sp 3p .TB Name Type Default Description .sp 3p _ .TH .R .sp 3p XtNbackground Pixel XtDefaultBackground Window background color XtNbackgroundPixmap Pixmap None Window background pixmap T{ XtNbitmap T} T{ Pixmap T} T{ None T} T{ Pixmap to display in place of the label T} XtNborderColor Pixel XtDefaultForeground Window border color XtNborderPixmap Pixmap None Window border pixmap XtNborderWidth Dimension 1 Border width in pixels XtNcursor Cursor None Pointer cursor T{ XtNdestroyCallback T} T{ XtCallbackList T} T{ NULL T} T{ Callbacks for .PN XtDestroyWidget T} XtNfont XFontStruct* XtDefaultFont Label font XtNforeground Pixel XtDefaultForeground Foreground color XtNheight Dimension text height Height of widget XtNinsensitiveBorder Pixmap Gray Border when not sensitive XtNinternalHeight Dimension 2 See note XtNinternalWidth Dimension 4 See note XtNjustify XtJustify XtJustifyCenter Type of text alignment XtNlabel String label name String to be displayed T{ XtNmappedWhenManaged T} T{ Boolean T} T{ True T} T{ Whether .PN XtMapWidget is automatic T} XtNresize Boolean True Whether to auto-resize in SetValues XtNsensitive Boolean True Whether widget receives input XtNwidth Dimension text width Width of widget XtNx Position 0 x coordinate in pixels XtNy Position 0 y coordinate in pixels .sp 3p _ .TE .ps 11 .nr PS 11 .vs 13 .nr VS 13 .LP The new resources associated with Label are: .TS lw(1.5i) lw(4i). T{ .PN XtNbitmap T} T{ Specifies a bitmap to display in place of the text label. The bitmap can be specified as a string in the resource data base. The StringToPixmap converter will interpret the string as the name of a file in the bitmap utility format that is to be loaded into a pixmap. The string can be an absolute or a relative file name. If a relative file name is used, the directory specified by the resource name .PN bitmapFilePath or the resource class .PN BitmapFilePath is add to the beginning of the specified file name. If the .PN bitmapFilePath resource is not defined, the default directory on a UNIX-based system is .PN /usr/include/X11/bitmaps . T} .sp 6p T{ .PN XtNheight T} T{ Specifies the height of the Label widget. The default value is the minimum height that will contain: .br XtNinternalheight + height of XtNlabel + XtNinternalHeight .br If the specified height is larger than the minimum, the label string is centered vertically. T} .sp 6p T{ .PN XtNinternalHeight T} T{ Represents the distance in pixels between the top and bottom of the label text or bitmap and the horizontal edges of the Label widget. T} .sp 6p T{ .PN XtNinternalWidth T} T{ Represents the distance in pixels between the ends of the label text or bitmap and the vertical edges of the Label widget. T} .sp 6p T{ .PN XtNjustify T} T{ Specifies left, center, or right alignment of the label string within the Label widget. If it is specified within an .PN ArgList , one of the values .PN XtJustifyLeft , .PN XtJustifyCenter , or .PN XtJustifyRight can be specified. In a resource of type ``string'', one of the values ``left'', ``center'', or ``right'' can be specified. T} .sp 6p T{ .PN XtNlabel T} T{ Specifies the text string that is to be displayed in the button if no bitmap is specified. The default is the widget name of the Label widget. T} .sp 6p T{ .PN XtNresize T} T{ Specifies whether the Label widget should attempt to resize to its preferred dimensions whenever .PN XtSetValues is called for it. T} .sp 6p T{ .PN XtNsensitive T} T{ If set to .PN False , the Label widget will change its window border to .PN XtNinsensitiveBorder and will stipple the label string. T} .sp 6p T{ .PN XtNwidth T} T{ Specifies the width of the Label widget. The default value is the minimum width that will contain: .br XtNinternalWidth + width of XtNlabel + XtNinternalWidth .br If the width is larger or smaller than the minimum, .PN XtNjustify determines how the label string is aligned. T} .TE .LP .IN "Label widget" "creating" .IN "Creating widgets" "Label" To create a Label widget instance, use .PN XtCreateWidget and specify the class variable .PN labelWidgetClass . .LP .IN "Label widget" "destroying" .IN "Destroying widgets" "Label" To destroy a Label widget instance, use .PN XtDestroyWidget and specify the widget ID of the label. .LP The Label widget supports only the .PN XtNdestroyCallback callback list. .NH 2 Text Widget .LP .XS \*(SN Text Widget .XE .IN "Text widget" "" "@DEF@" A Text widget is a window that provides a way for an application to display one or more lines of text. The displayed text can reside in a file on disk or in a string in memory. An option also lets an application display a vertical Scrollbar in the Text window, letting the user scroll through the displayed text. Other options allow an application to let the user modify the text in the window. .LP The Text widget is divided into three parts: .IP \(bu 5 Source .IP \(bu 5 Sink .IP \(bu 5 Text widget .LP The idea is to separate the storage of the text (source) from the painting of the text (sink). The Text widget coordinates the sources and sinks. Clients usually will use .PN AsciiText widgets that automatically create the source and sink for the client. A client can, if it so chooses, explicitly create the source and sink before creating the Text widget. .LP The source stores and manipulates the text. The \*(tk provides string and disk file sources. The source determines what editing functions may be performed on the text. .LP The sink obtains the fonts and the colors in which to paint the text. The sink also computes what text can fit on each line. The \*(tk provides a single-font, single-color ASCII sink. .LP If a disk file is used to display the text, two edit modes are available: .IP \(bu 5 Append .IP \(bu 5 Read-only .LP Append mode lets the user enter text into the window, while read-only mode does not. Text may only be entered if the insertion point is after the last character in the window. .LP If a string in memory is used, the application must allocate the amount of space needed. If a string in memory is used to display text, three types of edit mode are available: .IN "Text widget" "edit modes" .IP \(bu 5 Append-only .IP \(bu 5 Read-only .IP \(bu 5 Editable .LP The first two modes are the same as displaying text from a disk file. Editable mode lets the user place the cursor anywhere in the text and modify the text at that position. The text cursor position can be modified by using the key strokes or pointer buttons defined by the event bindings. .LE Many standard keyboard editing facilities are supported by the event bindings. The following actions are supported: .LP .Ds 0 .TA .5i 2.5i 3i .ta .5i 2.5i 3i Cursor Movement Delete forward-character delete-next-character backward-character delete-previous-character forward-word delete-next-word backward-word delete-previous-word forward-paragraph delete-selection backward-paragraph beginning-of-line end-of-line Selection next-line select-word previous-line select-all next-page select-start previous-page select-adjust beginning-of-file select-end end-of-file extend-start scroll-one-line-up extend-adjust scroll-one-line-down extend-end New Line Miscellaneous newline-and-indent redraw-display newline-and-backup insert-file newline insert-char insert-string display-caret do-nothing Kill Unkill kill-word unkill backward-kill-word stuff kill-selection insert-selection kill-to-end-of-line kill-to-end-of-paragraph .De .NT Notes .IP 1. 5 A page corresponds to the size of the Text window. For example, if the Text window is 50 lines in length, scrolling forward one page is the same as scrolling forward 50 lines. .IP 2. 5 The \fBinsert-char\fP action may only be attached to a key event. It calls XLookupString to translate the event into a (rebindable) Latin-1 character (sequence) and inserts that sequence into the text at the current position. The \fBinsert-string\fP action takes one or more arguments and inserts the arguments into the text at the current position. An argument beginning with the characters "0x" and containing only valid hexadecimal digits in the remainder is interpreted as a hexadecimal constant and the corresponding single character is inserted instead. .IP 3. 5 The \fBdelete\fP action deletes a text item. The \fBkill\fP action deletes a text item and puts the item in the kill buffer (X cut buffer 1). .IP 4. 5 The \fBunkill\fP action inserts the contents of the kill buffer into the text at the current position. The \fBstuff\fP action inserts the contents of the paste buffer (X cut buffer 0) into the text at the current position. The \fBinsert-selection\fP action retrieves the value of a specified X selection or cut buffer, with fall-back to alternative selections or cut buffers. .IP 5. 5 The \fBdisplay-caret\fP action allows the insert position marker to be turned on and off. The first argument specifies the desired state as any of the string values accepted for Boolean resources (e.g. "on", "true", "off", "false", etc.). If no arguments are specified, the default value is "on". The second argument specifies, for .PN EnterNotify or .PN LeaveNotify events whether or not the focus field in the event is to be examined. If the second argument is not specified, or specified as something other than "always" then if the action is bound to an .PN EnterNotify or .PN LeaveNotify event, the action will be taken only if the focus field is \fBTrue\fP. An augmented binding that might be useful is: .LP .Ds 0 .TA .5i 2.25i .ta .5i 2.25i *Text.Translations: #override \\ : display-caret(on) \\n\\ : display-caret(off) .De .NE .LP The default event bindings for the Text widget are: .IN "Text widget" "default bindings" .LP .Ds 0 .TA .5i 2.5i .ta .5i 2.5i char defaultTextTranslations[] = ``\\ CtrlF: forward-character(\|) \\n\\ CtrlB: backward-character(\|) \\n\\ CtrlD: delete-next-character(\|) \\n\\ CtrlA: beginning-of-line(\|) \\n\\ CtrlE: end-of-line(\|) \\n\\ CtrlH: delete-previous-character(\|) \\n\\ CtrlJ: newline-and-indent(\|) \\n\\ CtrlK: kill-to-end-of-line(\|) \\n\\ CtrlL: redraw-display(\|) \\n\\ CtrlM: newline(\|) \\n\\ CtrlN: next-line(\|) \\n\\ CtrlO: newline-and-backup(\|) \\n\\ CtrlP: previous-line(\|) \\n\\ CtrlV: next-page(\|) \\n\\ CtrlW: kill-selection(\|) \\n\\ CtrlY: unkill(\|) \\n\\ CtrlZ: scroll-one-line-up(\|) \\n\\ MetaF: forward-word(\|) \\n\\ MetaB: backward-word(\|) \\n\\ MetaI: insert-file(\|) \\n\\ MetaK: kill-to-end-of-paragraph(\|) \\n\\ MetaV: previous-page(\|) \\n\\ MetaY: stuff(\|) \\n\\ MetaZ: scroll-one-line-down(\|) \\n\\ :Metad: delete-next-word(\|) \\n\\ :MetaD: kill-word(\|) \\n\\ :Metah: delete-previous-word(\|) \\n\\ :MetaH: backward-kill-word(\|) \\n\\ :Meta\\<: beginning-of-file(\|) \\n\\ :Meta\\>: end-of-file(\|) \\n\\ :Meta]: forward-paragraph(\|) \\n\\ :Meta[: backward-paragraph(\|) \\n\\ ~Shift MetaDelete: delete-previous-word(\|) \\n\\ \ Shift MetaDelete: backward-kill-word(\|) \\n\\ ~Shift MetaBackspace: delete-previous-word(\|) \\n\\ \ Shift MetaBackspace: backward-kill-word(\|) \\n\\ Right: forward-character(\|) \\n\\ Left: backward-character(\|) \\n\\ Down: next-line(\|) \\n\\ Up: previous-line(\|) \\n\\ Delete: delete-previous-character(\|) \\n\\ BackSpace: delete-previous-character(\|) \\n\\ Linefeed: newline-and-indent(\|) \\n\\ Return: newline(\|) \\n\\ : insert-char(\|) \\n\\ : focus-in(\|) \\n\\ : focus-out(\|) \\n\\ : select-start(\|) \\n\\ : extend-adjust(\|) \\n\\ : extend-end(PRIMARY, CUT_BUFFER0) \\n\\ : insert-selection(PRIMARY, CUT_BUFFER0) \\n\\ : extend-start(\|) \\n\\ : extend-adjust(\|) \\n\\ : extend-end(PRIMARY, CUT_BUFFER0) \\ ''; .De .LP A user-supplied resource entry can use application-specific bindings, a subset of the supplied default bindings, or both. The following is an example of a user-supplied resource entry that uses a subset of the default bindings: .LP .Ds 0 .TA .5i 1.75i .ta .5i 1.75i Xmh*Text.Translations: \\ Right: forward-character(\|) \\n\\ Left: backward-character(\|) \\n\\ MetaF: forward-word(\|) \\n\\ MetaB: backward-word(\|) \\n\\ :Meta]: forward-paragraph(\|) \\n\\ :Meta[: backward-paragraph(\|) \\n\\ : insert-char(\|) .De .LP An augmented binding that is useful with the xclipboard utility is: .LP .Ds 0 .TA .5i 2.25i .ta .5i 2.25i *Text.Translations: #override \\ Button1 : extend-end(CLIPBOARD) .De .LP A Text widget lets both the user and the application take control of the text being displayed. The user takes control with the scroll bar or with key strokes defined by the event bindings. The scroll bar option places the scroll bar on the left side of the widget and can be used with any editing mode. The application takes control with procedure calls to the Text widget to: .IP \(bu 5 Display text at a specified position .IP \(bu 5 Highlight specified text areas .IP \(bu 5 Replace specified text areas .LE .LP The text that is selected within a Text widget may be assigned to an X selection or copied into a cut buffer and can be retrieved by the application with the Intrinsics .PN XtGetSelectionValue or the Xlib .PN XFetchBytes functions respectively. Several standard selection schemes (e.g. character/word/paragraph with multi-click) are supported through the event bindings. .LP The class variable for the Text widget is .PN textWidgetClass . .LP .IN "Text widget" "creating" .IN "Creating widgets" "Text string" To create a Text string widget, use .PN XtCreateWidget and specify the class variable .PN asciiStringWidgetClass . .LP .IN "Creating widgets" "Text file" To create a Text file widget, use .PN XtCreateWidget and specify the class variable .PN asciiDiskWidgetClass . .NT If you want to create an instance of the class .PN textWidgetClass , you must provide a source and a sink when the widget is created. The Text widget cannot be instantiated without both. .NE .LP When creating a Text widget instance, the following resources are retrieved from the argument list or from the resource database: .IN "Text widget" "resources" .ps 9 .nr PS 9 .vs 11 .nr VS 11 .TS H lw(1.5i) lw(1i) lw(1i) lw(2i). _ .sp 3p .TB Name Type Default Description .sp 3p _ .TH .R .sp 3p XtNbackground Pixel XtDefaultBackground Window background color XtNbackgroundPixmap Pixmap None Window background pixmap XtNborderColor Pixel XtDefaultForeground Window border color XtNborderPixmap Pixmap None Window border pixmap XtNborderWidth Dimension 4 Border width in pixels XtNcursor Cursor XC_xterm Pointer cursor XtNdialogHOffset int 10 Offset of insert file dialog XtNdialogVOffset int 10 Offset of insert file dialog T{ XtNdestroyCallback T} T{ XtCallbackList T} T{ NULL T} T{ Callbacks for .PN XtDestroyWidget T} XtNdisplayCaret Boolean True Display a marker at the insert position XtNdisplayNonPrinting Boolean True Display control char as ^C XtNdisplayPosition int 0 Character position of first line XtNecho Boolean True Whether or not to display output XtNeditType XtEditType XttextRead Edit mode (see note) T{ XtNfile T} T{ char* T} T{ tmpnam(\|) T} T{ File for .PN asciiDiskWidgetClass T} XtNforeground Pixel Black Foreground color XtNfont XFontStruct* Fixed Fontname XtNheight Dimension Font height Height of widget XtNinsertPosition int 0 Character position of caret XtNleftMargin Dimension 2 Left margin in pixels T{ XtNlength T} T{ int T} T{ String length T} T{ Size of the string buffer T} T{ XtNmappedWhenManaged T} T{ Boolean T} T{ True T} T{ Whether .PN XtMapWidget is automatic T} XtNselectTypes XtTextSelectType* See below Selection units for multi-click XtNsensitive Boolean True Whether widget receives input T{ XtNstring T} T{ char* T} T{ Blank T} T{ String for .PN asciiStringWidgetClass T} XtNtextOptions int None See below XtNtextSink XtTextSink None See below XtNtextSource XtTextSource None See below XtNtranslations TranslationTable See above event-to-action translations XtNwidth Dimension 100 Width of widget (pixels) XtNx Position 0 x coordinate in pixels XtNy Position 0 y coordinate in pixels .sp 3p _ .TE .ps 11 .nr PS 11 .vs 13 .nr VS 13 .NT Notes .IP 1. 5 You cannot use .PN XtNeditType , .PN XtNfile , .PN XtNlength , and .PN XtNfont with the .PN XtTextSetValues and the .PN XtTextGetValues calls. .IP 2. 5 The .PN XtNeditType attribute has one of the values .PN XttextAppend , .PN XttextEdit , or .PN XttextRead . .IP 3. 5 If .PN asciiStringWidgetClass is used, the resource .PN XtNstring specifies a buffer containing the text to be displayed and edited. .PN AsciiStringWidget does not copy this buffer but uses it in-place. .IP 4. 5 If .PN XtNdisplayNonPrinting is .PN True any control characters will be displayed as the two-character sequence "^", "C" where "C" is the uppercase (printing) equivalent of the control character. If the value is .PN False any control characters will be displayed as a single space character. .IP 5. 5 If .PN XtNecho is .PN False then no text is displayed. Text may still be selected and modified, though invisibly. .NE .LP The options for the .PN XtNtextOptions attribute are: .TS H lw(1.5i) lw(4.5i). _ .sp 3p .TB Option Description .sp 3p _ .TH .R .sp 3p T{ .PN editable T} T{ Whether or not the user is allowed to modify the text. T} .sp 3p T{ .PN resizeHeight T} T{ Makes a request to the parent widget to lengthen the widget if all the text cannot fit in the window. T} .sp 3p T{ .PN resizeWidth T} T{ Makes a request to the parent widget to widen the widget if the text becomes too long to fit on one line. T} .\".sp 3p .\"T{ .\".PN scrollHorizontal .\"T} T{ .\"Puts a scroll bar on the top of the widget. .\"T} .sp 3p T{ .PN scrollOnOverflow T} T{ Automatically scrolls the text up when new text is entered below the bottom (last) line. T} .sp 3p T{ .PN scrollVertical T} T{ Puts a scroll bar on the left side of the widget. T} .sp 3p T{ .PN wordBreak T} T{ Starts a new line when a word does not fit on the current line. T} .sp 3p _ .TE .LP These options can be ORed together to set more than one at the same time. .LP .PN XtNselectionTypes is an array of entries of type .PN XtTextSelectType and is used for multiclick. As the pointer button is clicked in rapid succession, each click highlights the next ``type'' described in the array. .TS lw(1.25i) lw(4.25i). T{ XtselectAll T} T{ Selects the contents of the entire buffer. T} .sp 6p T{ XtselectChar T} T{ Selects text characters as the pointer moves over them. T} .sp 6p T{ XtselectLine T} T{ Selects the entire line. T} .sp 6p T{ XtselectNull T} T{ Indicates the end of the selection array. T} .sp 6p T{ XtselectParagraph T} T{ Selects the entire paragraph (delimited by newline characters). T} .sp 6p T{ XtselectPosition T} T{ Selects the current pointer position. T} .sp 6p T{ XtselectWord T} T{ Selects whole words (delimited by whitespace) as the pointer moves onto them. T} .TE .LP The default selectType array is: .LP .Ds 0 {XtselectPosition, XtselectWord, XtselectLine, XtselectParagraph, XtselectAll, XtselectNull} .De .LP For the default case, two rapid pointer clicks highlight the current word, three clicks highlight the current line, four clicks highlight the current paragraph, and five clicks highlight the entire text. If the timeout value is exceeded, the next pointer click returns to the first entry in the selection array. The selection array is not copied by the Text widget. The client must allocate space for the array and cannot deallocate or change it until the Text widget is destroyed or until a new selection array is set. .NH 3 Selection Actions .LP The Text widget fully supports the X selection and cut buffer mechanisms. The following actions can be used to specify button bindings that will cause Text to assert ownership of one or more selections, to store the selected text into a cut buffer, and to retrieve the value of a selection or cut buffer and insert it into the text value. .IP \fBinsert-selection\fP(\fIname\fP[,\fIname\fP,...]) 1i Retrieves the value of the first (left-most) named selection that exists or the cut buffer that is not empty and inserts it into the input stream. The specified name can be that of any selection (for example, .PN PRIMARY or .PN SECONDARY ) or a cut buffer (i.e. .PN CUT_BUFFER0 through .PN CUT_BUFFER7 ). Note that case matters. .IP \fBselect-start\fP(\^) 1i Unselects any previously selected text and begins selecting new text. .sp 6p .IP \fBselect-adjust\fP(\^) 1i .br .ns .IP \fBextend-adjust\fP(\^)\ \ \ 1i Continues selecting text from the previous start position. .sp 6p .IP \fBstart-extend\fP(\^) 1i Begins extending the selection from the farthest (left or right) edge. .sp 6p .IP \fBselect-end\fP(\fIname\fP[,\fIname\fP,...]) 1i .br .ns .IP \fBextend-end\fP(\fIname\fP[,\fIname\fP,...]) 1i Ends the text selection, asserts ownership of the specified selection(s) and stores the text in the specified cut buffer(s). The specified name can be that of a selection (for example, .PN PRIMARY or .PN SECONDARY ) or a cut buffer (i.e. .PN CUT_BUFFER0 through .PN CUT_BUFFER7 ). Note that case is significant. If .PN CUT_BUFFER0 is listed, the cut buffers are rotated before storing into buffer 0. .NH 3 Selecting Text .LP To enable an application to select a piece of text, use .PN XtTextSetSelection . .IN "XtTextSetSelection" "" "@DEF@" .FD 0 typedef long XtTextPosition; .sp 6p void XtTextSetSelection(\fIw\fP, \fIleft\fP, \fIright\fP) .br Widget \fIw\fP; .br XtTextPosition \fIleft\fP, \fIright\fP; .FN .IP \fIw\fP 1i Specifies the widget ID. .IP \fIleft\fP 1i Specifies the character position at which the selection begins. .IP \fIright\fP 1i Specifies the character position at which the selection ends. .LP If redisplay is not disabled, this function highlights the text and makes it the PRIMARY selection. .LP .NH 3 Unhighlighting Text .LP To unhighlight previously highlighted text in a widget, use .PN XtTextUnsetSelection . .IN "XtTextUnsetSelection" "" "@DEF@" .FD 0 void XtTextUnsetSelection(\fIw\fP) .br Widget \fIw\fP; .FN .LP .NH 3 Getting Selected Text Character Positions .LP To enable the application to get the character positions of the selected text, use .PN XtTextGetSelectionPos . .IN "XtTextGetSelectionPos" "" "@DEF@" .FD 0 void XtTextGetSelectionPos(\fIw\fP, \fIpos1\fP, \fIpos2\fP) .br Widget \fIw\fP; .br XtTextPosition *\fIpos1\fP, *\fIpos2\fP; .FN .IP \fIw\fP 1i Specifies the widget ID. .IP \fIpos1\fP 1i Specifies a pointer to the location to which the beginning character position of the selection is returned. .IP \fIpos2\fP 1i Specifies a pointer to the location to which the ending character position of the selection is returned. .LP If the returned values are equal, there is no current selection. .NH 3 Replacing Text .LP To enable an application to replace text, use .PN XtTextReplace . .IN "XtTextReplace" "" "@DEF@" .FD 0 int XtTextReplace(\fIw\fP, \fIstart_pos\fP, \fIend_pos\fP, \fItext\fP) .br Widget \fIw\fP; .br XtTextPosition \fIstart_pos\fP, \fIend_pos\fP; .br XtTextBlock *\fItext\fP; .FN .IP \fIw\fP 1i Specifies the widget ID. .IP \fIstart_pos\fP 1i Specifies the starting character position of the text replacement. .IP \fIend_pos\fP 1i Specifies the ending character position of the text replacement. .IP \fItext\fP 1i Specifies the text to be inserted into the file. .LP The .PN XtTextReplace function deletes text in the specified range (startPos, endPos) and inserts the new text at startPos. The return value is .PN XawEditDone if the replacement is successful, .PN XawPositionError if the edit mode is .PN XttextAppend and startPos is not the last character of the source, or .PN XawEditError if either the source was read-only or the range to be deleted is larger than the length of the source. .LP The .PN XtTextBlock structure (defined in .Pn < X11/Text.h > contains: .LP .IN "XtTextBlock" "" "@DEF@" .Ds 0 .TA .5i 1.5i 2.25i .ta .5i 1.5i 2.25i typedef struct { int firstPos; int length; char *ptr; Atom format; } XtTextBlock, *TextBlockPtr; .De .LP The firstPos field is the starting point to use within the ptr field. The value is usually zero. The length field is the number of characters that are transferred from the ptr field. The number of characters transferred is usually the number of characters in ptr. This format field indicates whether the data pointed to by \fBptr\fP is char or wchar_t. When the associated widget has \fBinternational\fP set to \fBfalse\fP this field must be XawFmt8Bit. When the associated widget has \fBinternational\fP set to \fBtrue\fP this field must be either XawFmt8Bit or XawFmtWide. .LP Note: Previous versions of Xaw used .PN FMT8BIT , which has been retained for backwards compatibility. \fBFMT8BIT\fP is deprecated and will eventually be removed from the implementation. The .PN XtTextReplace arguments \fBstart_pos\fP and \fBend_pos\fP represent the text source character positions for the existing text that is to be replaced by the text in the .PN XtTextBlock structure. The characters from start_pos up to but not including end_pos are deleted, and the characters that are specified by the text block are inserted in their place. If start_pos and end_pos are equal, no text is deleted and the new text is inserted after start_pos. .NT Only ASCII text is currently supported, and only one font can be used for each Text widget. .NE .NH 3 Redisplaying Text .LP To redisplay a range of characters, use .PN XtTextInvalidate . .IN "XtTextInvalidate" "" "@DEF@" .FD 0 void XtTextInvalidate(\fIw\fP, \fIfrom\fP, \fIto\fP) .br Widget \fIw\fP; .br XtTextPosition \fIfrom\fP, \fIto\fP; .FN The .PN XtTextInvalidate function causes the specified range of characters to be redisplayed immediately if redisplay is enabled or the next time that redisplay is enabled. .LP .sp To enable redisplay, use .PN XtTextEnableRedisplay . .IN "XtTextEnableRedisplay" "" "@DEF@" .FD 0 void XtTextEnableRedisplay(\fIw\fP) .br Widget \fIw\fP; .FN The .PN XtTextEnableRedisplay function flushes any changes due to batched updates when .PN XtTextDisableRedisplay was called and allows future changes to be reflected immediately. .LP .sp To disable redisplay while making several changes, use .PN XtTextDisableRedisplay . .IN "XtTextDisableRedisplay" "" "@DEF@" .FD 0 void XtTextDisableRedisplay(\fIw\fP) .br Widget \fIw\fP; .FN The .PN XtTextDisableRedisplay function causes all changes to be batched until .PN XtTextDisplay or .PN XtTextEnableRedisplay is called. .LP .sp To display batched updates, use .PN XtTextDisplay . .IN "XtTextDisplay" "" "@DEF@" .FD 0 void XtTextDisplay(\fIw\fP) .br Widget \fIw\fP; .FN The .PN XtTextDisplay function forces any accumulated updates to be displayed. .LP .sp To notify the source that the length has been changed, use .PN XtTextSetLastPos . .IN "XtTextSetLastPos" "" "@DEF@" .FD 0 void XtTextSetLastPos(\fIw\fP, \fIlast\fP); .br Widget \fIw\fP; .br XtTextPosition \fIlast\fP; .FN .LP The .PN XtTextSetLastPos function notifies the text source that data has been added to or removed from the end of the source. .NH 3 Changing Resources .LP The following procedures are convenience procedures that replace calls to .PN XtSetValues or .PN XtGetValues when only a single resource is to be modified or retrieved. .LP .sp To assigns a new value to XtNtextOptions resource, use .PN XtTextChangeOptions . .IN "XtTextChangeOptions" "" "@DEF@" .FD 0 void XtTextChangeOptions(\fIw\fP, \fIoptions\fP) .br Widget \fIw\fP; .br int \fIoptions\fP; .FN .LP .sp To obtain the current value of XtNtextOptions for the specified widget, use .PN XtTextGetOptions . .IN "XtTextGetOptions" "" "@DEF@" .FD 0 int XtTextGetOptions(\fIw\fP) .br Widget \fIw\fP; .FN .LP .sp To obtain the character position of the left-most character on the first line displayed in the widget (that is, the value of XtNdisplayPosition), use .PN XtTextTopPosition . .IN "XtTextTopPosition" "" @DEF@" .FD 0 XtTextPosition XtTextTopPosition(\fIw\fP) .br Widget \fIw\fP; .FN .LP .sp To move the insertion caret to the specified source position, use .PN XtTextSetInsertionPoint . .IN "XtTextSetInsertionPoint" "" "@DEF@" .FD 0 void XtTextSetInsertionPoint(\fIw\fP, \fIposition\fP) .br Widget \fIw\fP; .br XtTextPosition \fIposition\fP; .FN .LP The text will be scrolled vertically if necessary to make the line containing the insertion point visible. The result is equivalent to setting the XtNinsertPosition resource. .LP .sp To obtain the current position of the insertion caret, use .PN XtTextGetInsertionPoint . .IN "XtTextGetInsertionPoint" "" "@DEF@" .FD 0 XtTextPosition XtTextGetInsertionPoint(\fIw\fP) .br Widget \fIw\fP; .FN The result is equivalent to retrieving the value of the XtNinsertPosition resource. .LP .sp To replace the text source in the specified widget, use .PN XtTextSetSource . .IN "XtTextSetSource" "" "@DEF@" .FD 0 void XtTextSetSource(\fIw\fP, \fIsource\fP, \fIposition\fP) .br Widget \fIw\fP; .br XtTextSource \fIsource\fP; .br XtTextPosition \fIposition\fP; .FN A display update will be performed if redisplay has not been disabled. .LP .sp To obtain the current text source for the specified widget, use .PN XtTextGetSource . .IN "XtTextGetSource" "" "@DEF@" .FD 0 XtTextSource XtTextGetSource(\fIw\fP) .br Widget \fIw\fP; .FN .LP .sp To enable and disable the insert position marker, use .PN XtTextDisplayCaret . .IN "XtTextDisplayCaret" "" "@DEF@" .FD 0 void XtTextDisplayCaret(\fIw\fP, \fIvisible\fP) .br Widget \fIw\fP; .br Boolean \fIvisible\fP; .FN .IP \fIw\fP 1i Specifies the widget ID of the Text widget. .IP \fIvisible\fP 1i Specifies whether or not the caret should be displayed. .LP If visible is \fBFalse\fP the insert position marker will be disabled. The marker is re-enabled either by setting visible to \fBTrue\fP, by calling .PN XtSetValues , or by executing the \fBdisplay-caret\fP action routine. .NH 3 Creating Sources and Sinks .LP The following functions for creating and destroying text sources and sinks are called automatically by .PN AsciiStringWidget and .PN AsciiDiskWidget and it is therefore only necessary for the client to use them when creating an instance of .PN textWidgetClass . .LP .sp To create a new ASCII text sink, use .PN XtAsciiSinkCreate . .IN "XtAsciiSinkCreate" "" "@DEF@" .FD 0 XtTextSink XtAsciiSinkCreate(\fIw\fP, \fIargs\fP, \fInum_args\fP) .br Widget \fIw\fP; .br ArgList \fIargs\fP; .br Cardinal \fInum_args\fP; .FN .LP The resources required by the sink are qualified by the name and class of the parent and the sub-part name .PN XtNtextSink and class .PN XtCTextSink . .LP .sp To deallocate an ASCII text sink, use .PN XtAsciiSinkDestroy . .IN "XtAsciiSinkDestroy" "" "@DEF@" .FD 0 void XtAsciiSinkDestroy(\fIsink\fP) .br XtTextSink \fIsink\fP; .FN .LP The sink must not be in use by any widget or an error will result. .LP .sp To create a new text disk source, use .PN XtDiskSourceCreate . .IN "XtDiskSourceCreate" "" "@DEF@" .FD 0 XtTextSource XtDiskSourceCreate(\fIw\fP, \fIargs\fP, \fInum_args\fP) .br Widget \fIw\fP; .br ArgList \fIargs\fP; .br Cardinal \fInum_args\fP; .FN .LP The resources required by the source are qualified by the name and class of the parent and the sub-part name .PN XtNtextSource and class .PN XtCTextSource . .LP .sp To deallocate a text disk source, use .PN XtDiskSourceDestroy . .IN "XtDiskSourceDestroy" "" "@DEF@" .FD 0 void XtDiskSourceDestroy(\fIsource\fP) .br XtTextSource \fIsource\fP; .FN .LP The source must not be in use by any widget or an error will result. .LP .sp To create a new text string source, use .PN XtStringSourceCreate . .IN "XtStringSourceCreate" "" "@DEF@" .FD 0 XtTextSource XtStringSourceCreate(\fIw\fP, \fIargs\fP, \fInum_args\fP) .br Widget \fIw\fP; .br ArgList \fIargs\fP; .br Cardinal \fInum_args\fP; .FN .LP The resources required by the source are qualified by the name and class of the parent and the sub-part name .PN XtNtextSource and class .PN XtCTextSource . .LP .sp To deallocate a text string source, use .PN XtStringSourceDestroy . .IN "XtStringSourceDestroy" "" "@DEF@" .FD 0 void XtStringSourceDestroy(\fIsource\fP) .br XtTextSource \fIsource\fP; .FN .LP The source must not be in use by any widget or an error will result. .NH 2 Scrollbar Widget .LP .XS \*(SN Scrollbar Widget .XE .IN "Scrollbar widget" "" "@DEF@" The Scrollbar widget is a rectangular area that contains a slide region and a thumb (slide bar). A Scrollbar can be used alone, as a valuator, or it can be used within a composite widget (for example, a Viewport). A Scrollbar can be aligned either vertically or horizontally. .LP When a Scrollbar is created, it is drawn with the thumb in a contrasting color. The thumb is normally used to scroll client data and to give visual feedback on the percentage of the client data that is visible. .LP Each pointer button invokes a specific scroll bar action. That is, given either a vertical or horizontal alignment, the pointer button actions will scroll or return data as appropriate for that alignment. Pointer buttons 1 and 3 do not perform scrolling operations by default. Instead, they return the pixel position of the cursor on the scroll region. When pointer button 2 is clicked, the thumb moves to the current pointer position. When pointer button 2 is held down and the pointer pointer is moved, the thumb follows the pointer. .LP The cursor in the scroll region changes depending on the current action. When no pointer button is pressed, the cursor appears as an arrow that points in the direction that scrolling can occur. When pointer button 1 or 3 is pressed, the cursor appears as a single-headed arrow that points in the logical direction that the client will move the data. When pointer button 2 is pressed, the cursor appears as an arrow that points to the thumb. .LP While scrolling is in progress, the application receives notification from callback procedures. For both scrolling actions, the callback returns the Scrollbar widget ID, the client_data, and the pixel position of the pointer when the button was released. For smooth scrolling, the callback routine returns the scroll bar widget, the client data, and the current relative position of the thumb. When the thumb is moved using pointer button 2, the callback procedure is invoked continuously. When either button 1 or 3 is pressed, the callback procedure is invoked only when the button is released and the client callback procedure is responsible for moving the thumb. .LP The class variable for the Scrollbar widget is .PN scrollbarWidgetClass . .LP When creating a Scrollbar widget instance, the following resources are retrieved from the argument list or from the resource database: .IN "Scrollbar widget" "resources" .ps 9 .nr PS 9 .vs 11 .nr VS 11 .TS H lw(1.5i) lw(1i) lw(1i) lw(2i). _ .sp 3p .TB Name Type Default Description .sp 3p _ .TH .R .sp 3p XtNbackground Pixel white Window background color XtNbackgroundPixmap Pixmap None Window background pixmap XtNborderColor Pixel XtDefaultForeground Window border color XtNborderPixmap Pixmap None Window border pixmap XtNborderWidth Dimension 1 Width of button border T{ XtNdestroyCallback T} T{ XtCallbackList T} T{ NULL T} T{ Callbacks for .PN XtDestroyWidget T} XtNforeground Pixel black Thumb color XtNheight Dimension See below Height of scroll bar XtNjumpProc XtCallbackList NULL Callback for thumb select XtNlength Dimension None Major dimension (height of XtorientVertical) T{ XtNmappedWhenManaged T} T{ Boolean T} T{ True T} T{ Whether .PN XtMapWidget is automatic T} T{ XtNorientation T} T{ XtOrientation T} T{ XtorientVertical T} T{ Orientation (vertical or horizontal) T} T{ XtNscrollDCursor T} T{ Cursor T} T{ XC_sb_down_arrow T} T{ Cursor for scrolling down T} T{ XtNscrollHCursor T} T{ Cursor T} T{ XC_sb_h_double_arrow T} T{ Idle horizontal cursor T} T{ XtNscrollLCursor T} T{ Cursor T} T{ XC_sb_left_arrow T} T{ Cursor for scrolling left T} XtNscrollProc XtCallbackList NULL Callback for the slide region T{ XtNscrollRCursor T} T{ Cursor T} T{ XC_sb_right_arrow T} T{ Cursor for scrolling right T} T{ XtNscrollUCursor T} T{ Cursor T} T{ XC_sb_up_arrow T} T{ Cursor for scrolling up T} T{ XtNscrollVCursor T} T{ Cursor T} T{ XC_sb_v_double_arrow T} T{ Idle vertical cursor T} XtNsensitive Boolean True Whether widget receives input XtNshown float NULL Percentage the thumb covers XtNthickness Dimension 14 Minor dimension (height if XtorientHorizontal) XtNthumb Pixmap Grey Thump pixmap XtNtop float NULL Position on scroll bar XtNtranslations TranslationTable See below Event-to-action translations XtNwidth Dimension See below Width of scroll bar XtNx Position NULL x position of scroll bar XtNy Position NULL y position of scroll bar .sp 3p _ .TE .ps 11 .nr PS 11 .vs 13 .nr VS 13 .LP The class for all cursor resources is .PN XtCCursor . .LP You can set the dimensions of the Scrollbar two ways. As for all widgets, you can use the .PN XtNwidth and .PN XtNheight resources. In addition, you can use an alternative method that is independent of the vertical or horizontal orientation: .TS lw(1.5i) lw(4.5i). T{ .PN XtNlength T} T{ Specifies the height for a vertical Scrollbar and the width for a horizontal Scrollbar. T} T{ .PN XtNthickness T} T{ Specifies the width for a vertical Scrollbar and the height for a horizontal Scrollbar. T} .TE .LP .IN "Scrollbar widget" "creating" .IN "Creating widgets" "Scrollbar" To create a Scrollbar widget instance, use .PN XtCreateWidget and specify the class variable .PN scrollbarWidgetClass . .LP .IN "Scrollbar widget" "destroying" .IN "Destroying widgets" "Scrollbar" To destroy a Scrollbar widget instance, use .PN XtDestroyWidget and specify the widget ID for the Scrollbar. .LP .sp The arguments to the .PN XtNscrollProc callback procedure are: .IN "ScrollProc" "" "@DEF@" .FD 0 void \fIScrollProc\fP(\fIscrollbar\fP, \fIclient_data\fP, \fIposition\fP) .br Widget \fIscrollbar\fP; .br caddr_t \fIclient_data\fP; .br caddr_t \fIposition\fP; /* int */ .FN .IP \fIscrollbar\fP 1i Specifies the ID of the Scrollbar. .IP \fIclient_data\fP 1i Specifies the client data. .IP \fIposition\fP 1i Returns the pixel position of the thumb in integer form. .LP The .PN XtNscrollProc callback is used for incremental scrolling and is called by the \fBNotifyScroll\fP action. The position argument is a signed quantity and should be cast to an int when used. Using the default button bindings, button 1 returns a positive value, and button 3 returns a negative value. In both cases, the magnitude of the value is the distance of the pointer in pixels from the top (or left) of the Scrollbar. The value will never be less than zero or greater than the length of the Scrollbar. .LP .sp The arguments to the .PN XtNjumpProc callback procedure are: .IN "JumpProc" "" "@DEF@" .FD 0 void \fIJumpProc\fP(\fIscrollbar\fP, \fIclient_data\fP, \fIpercent\fP) .br Widget \fIscrollbar\fP; .br caddr_t \fIclient_data\fP; .br caddr_t \fIpercent_ptr\fP; /* float* */ .FN .IP \fIscrollbar\fP 1i Specifies the ID of the scroll bar widget. .IP \fIclient_data\fP 1i Specifies the client data. .IP \fIpercent_ptr\fP 1i Specifies the floating point position of the thumb (0.0 \- 1.0). .LP The .PN XtNjumpProc callback is used to implement smooth scrolling and is called by the \fBNotifyThumb\fP action. Percent_ptr must be cast to a pointer to float before use; i.e. .LP .Ds 0 .TA .5i .ta .5i float percent = *(float*)percent_ptr; .De .LP With the default button bindings, button 2 moves the thumb interactively, and the .PN XtNjumpProc is called on each new position of the pointer. .NT An older interface used .PN XtNthumbProc and passed the percentage by value rather than by reference. This interface is not portable across machine architectures and therefore is no longer supported but is still implemented for those (non-portable) applications which used it. .NE .LP .IN "Scrollbar widget" "setting thumb values" To set the position and length of a Scrollbar thumb, use .PN XtScrollbarSetThumb . .IN "XtScrollbarSetThumb" "" "@DEF@" .FD 0 void XtScrollbarSetThumb(\fIw\fP, \fItop\fP, \fIshown\fP) .br Widget \fIw\fP; .br float \fItop\fP; .br float \fIshown\fP; .FN .IP \fIw\fP 1i Specifies the Scrollbar widget ID. .IP \fItop\fP 1i Specifies the position of the top of the thumb as a fraction of the length of the Scrollbar. .IP \fIshown\fP 1i Specifies the length of the thumb as a fraction of the total length of the Scrollbar. .LP .PN XtScrollbarThumb moves the visible thumb to position (0.0 \- 1.0) and length (0.0 \- 1.0). Either the top or shown arguments can be specified as \-1.0, in which case the current value is left unchanged. Values greater than 1.0 are truncated to 1.0. .LP If called from .PN XtNjumpProc , .PN XtScrollbarSetThumb has no effect. .LP .sp The actions supported by the Scrollbar widget are: .IP \fBStartScroll\fP(\fIvalue\fP) 1i The possible values are Forward, Backward, or Continuous. This must be the first action to begin a new movement. .IP \fBNotifyScroll\fP(\fIvalue\fP) 1i The possible values are Proportional or FullLength. If the argument to StartScroll was Forward or Backward, NotifyScroll executes the .PN XtNscrollProc callbacks and passes either the position of the pointer if its argument is Proportional or the full length of the scroll bar if its argument is FullLength. If the argument to StartScroll was Continuous, NotifyScroll returns without executing any callbacks. .IP \fBEndScroll\fP(\^) 1i This must be the last action after a movement is complete. .IP \fBMoveThumb\fP(\^) 1i Repositions the scroll bar thumb to the current pointer location. .IP \fBNotifyThumb\fP(\^)\ \ \ 1i Calls the .PN XtNjumpProc callbacks and passes the relative position of the pointer as a percentage of the scroll bar length. .LP The default bindings for Scrollbar are: .LP .Ds 0 .TA .5i 1.75i .ta .5i 1.75i : StartScroll(Forward) : StartScroll(Continuous) MoveThumb(\|) NotifyThumb(\|) : StartScroll(Backward) : MoveThumb(\|) NotifyThumb(\|) : NotifyScroll(Proportional) EndScroll(\|) .De .LP Examples of additional bindings a user might wish to specify in a resource file are: .LP .Ds 0 .TA .5i 2.25i .ta .5i 2.25i *Scrollbar.Translations: \\ ~Metaspace: StartScroll(Forward) NotifyScroll(FullLength) \\n\\ Metaspace: StartScroll(Backward) NotifyScroll(FullLength) \\n\\ EndScroll(\|) .De .NH 2 Viewport Widget .LP .XS \*(SN Viewport Widget .XE .IN "Viewport widget" "" "@DEF@" The Viewport widget consists of a frame window, one or two Scrollbars, and an inner window. The frame window is determined by the viewing size of the data that is to be displayed and the dimensions to which the Viewport is created. The inner window is the full size of the data that is to be displayed and is clipped by the frame window. The Viewport widget controls the scrolling of the data directly. No application callbacks are required for scrolling. .LP When the geometry of the frame window is equal in size to the inner window, or when the data does not require scrolling, the Viewport widget automatically removes any scroll bars. The .PN forceBars option causes the Viewport widget to display any scroll bar permanently. .LP The class variable for the Viewport widget is .PN viewportWidgetClass . .LP When creating a Viewport widget instance, the following resources are retrieved from the argument list or from the resource database: .IN "Viewport widget" "resources" .ps 9 .nr PS 9 .vs 11 .nr VS 11 .TS H lw(1.5i) lw(1i) lw(1i) lw(2i). _ .sp 3p .TB Name Type Default Description .sp 3p _ .TH .R .sp 3p XtNallowHoriz Boolean False Flag to allow horizontal scroll bars XtNallowVert Boolean False Flag to allow vertical scroll bars XtNbackground Pixel XtDefaultBackground Window background color XtNbackgroundPixmap Pixmap None Window background pixmap XtNborderColor Pixel XtDefaultForeground Window border color XtNborderPixmap Pixmap None Window border pixmap XtNborderWidth Dimension 1 Width of the border in pixels T{ XtNdestroyCallback T} T{ XtCallbackList T} T{ NULL T} T{ Callback for .PN XtDestroyWidget T} XtNforceBars Boolean False Flag to force display of scroll bars XtNheight Dimension height of child Height of the widget T{ XtNmappedWhenManaged T} T{ Boolean T} T{ True T} T{ Whether .PN XtMapWidget is automatic T} XtNsensitive Boolean True Whether widget should receive input XtNtranslations TranslationTable None Event-to-action translations XtNuseBottom Boolean False Flag to indicate bottom/top bars XtNuseRight Boolean False Flag to indicate right/left bars XtNwidth Dimension width of child Width of the widget XtNx Position 0 x coordinate within parent XtNy Position 0 y coordinate within parent .sp 3p _ .TE .ps 11 .nr PS 11 .vs 13 .nr VS 13 .LP The Viewport widget manages a single child widget. When the size of the child is larger than the size of the Viewport, the user can interactively move the child within the Viewport by repositioning the Scrollbars. .LP The default size of the Viewport before it is realized is the width and/or height of the child. After it is realized, the viewport will allow its child to grow vertically or horizontally if .PN XtNallowVert or .PN XtNallowHoriz were set, respectively. If the corresponding vertical or horizontal scrolling were not enabled, the viewport will propagate the geometry request to its own parent and the child will be allowed to change size only if the (grand) parent allows it. Regardless of whether or not scrolling was enabled in the corresponding direction, if the child requests a new size smaller than the viewport size, the change will be allowed only if the parent of the viewport allows the viewport to shrink to the appropriate dimension. .LP .IN "Viewport widget" "creating" To create a Viewport widget instance, use .PN XtCreateWidget and specify the class variable .PN viewportWidgetClass . .LP .IN "Viewport widget" "inserting a child" To insert a child into a Viewport widget, use .PN XtCreateWidget and specify the widget ID of the previously created Viewport as the parent. .LP .IN "Viewport widget" "removing a child" To remove a child from a Viewport widget, use .PN XtUnmanageChild or .PN XtDestroyWidget and specify the widget ID of the child. .LP .IN "Viewport widget" "destroying" .IN "Destroying widgets" "Viewport" To delete the inner window, any children, and the frame window, use .PN XtDestroyWidget and specify the widget ID of the Viewport widget. .NH 2 Box Widget .LP .XS \*(SN Box Widget .XE .IN "Box widget" "" "@DEF@" The Box widget provides geometry management of arbitrary widgets in a box of a specified dimension. The children are rearranged when resizing events occur either on the Box or when children are added or deleted. The Box widget always attempts to pack its children as closely as possible within the geometry allowed by its parent. .LP Box widgets are commonly used to manage a related set of Command widgets and are frequently called ButtonBox widgets, but the children are not limited to buttons. .LP The children are arranged on a background that has its own specified dimensions and color. .LP The class variable for the Box widget is .PN boxWidgetClass . .LP When creating a Box widget instance, the following resources are retrieved from the argument list or from the resource database: .IN "Box widget" "resources" .ps 9 .nr PS 9 .vs 11 .nr VS 11 .TS H lw(1.5i) lw(1i) lw(1i) lw(2i) . _ .sp 3p .TB Name Type Default Description .sp 3p _ .TH .R .sp 3p XtNbackground Pixel XtDefaultBackground Window background color XtNbackgroundPixmap Pixmap None Window background pixmap XtNborderColor Pixel XtDefaultForeground Window border color XtNborderPixmap Pixmap None Window border pixmap XtNborderWidth Dimension 1 Border width on button box T{ XtNdestroyCallback T} T{ XtCallbackList T} T{ NULL T} T{ Callbacks for .PN XtDestroyWidget T} XtNhSpace Dimension 4 Pixel distance left and right of children XtNheight Dimension see below Viewing height of inner window T{ XtNmappedWhenManaged T} T{ Boolean T} T{ True T} T{ Whether .PN XtMapWidget is automatic T} XtNtranslations TranslationTable None Event-to-action translations XtNvSpace Dimension 4 Pixel distance top and bottom of children XtNwidth Dimension width of widest child Viewing width of inner window XtNx Position 0 Widget location x coordinate XtNy Position 0 Widget location y coordinate .sp 3p _ .TE .ps 11 .nr PS 11 .vs 13 .nr VS 13 .LP The Box widget positions its children in rows with .PN XtNhSpace pixels to the left and right of each child and .PN XtNvSpace pixels between rows. If the Box width is not specified, the Box widget uses the width of the widest child. Each time a child is managed or unmanaged, the Box widget will attempt to reposition the remaining children to compact the box. Children are positioned in order left to right, top to bottom. When the next child does not fit on the current row, a new row is started. If a child is wider than the width of the box, the box will request a larger width from it parent and will begin the layout process from the beginning if a new width is granted. After positioning all children, the Box widget attempts to shrink its own size to the minimum dimensions required for the layout. .LP .IN "Box widget" "creating" .IN "Creating widgets" "Box" To create a box widget instance, use .PN XtCreateWidget and specify the class variable .PN boxWidgetClass . .LP .IN "Box widget" "adding children" To add a child to the Box, use .PN XtCreateWidget and specify the widget ID of the Box as the parent of the new widget. .LP .IN "Box widget" "removing children" To remove a child from the Box, use .PN XtUnmanageChild or .PN XtDestroyWidget and specify the widget ID of the child. .LP .IN "Box widget" "destroying" .IN "Destroying widgets" "Box" To destroy a Box widget instance, use .PN XtDestroyWidget and specify the widget ID of the Box widget. All the children of this box are automatically destroyed at the same time. .\".NH 2 .\"MenuBox Widget .\".LP .\".XS .\"\*(SN MenuBox Widget .\".XE .\".IN "MenuBox widget" "" "@DEF@" .\"The MenuBox widget allows for menus of arbitrary complexity. .\"A MenuBox consists of a main window and a number of entries that .\"are added to it. .\"Although these entries typically are Command widgets, .\"any kind of widget can be added to a MenuBox. .\".LP .\"The class variable for the MenuBox widget is .\".PN menuBoxWidgetClass . .\".LP .\"An application can use the MenuBox widget to create: .\".IP \(bu 5 .\"Pop-up menus .\".IP \(bu 5 .\"Pull-down menus .\".IP \(bu 5 .\"Cascading menus .\".LP .\"For example, to create a pop-up menu, .\"use .\".PN XtCreateWidget .\"and specifies the class variable .\".PN menuBoxWidgetClass . .\"This creates an empty main window. .\"Then, to create a menu item that is to be added to the MenuBox, .\"specify the widget ID of this empty menu as the parent .\"of each new item. .\".LP .\"The MenuBox can arrange its children either vertically or horizontally. .\".LP .\"The MenuBox widget automatically makes all items the same width .\"(for vertical orientation) or the same height (for horizontal orientation) .\"as the largest one passed to it. .\"Then, to make the MenuBox visible, .\"use .\".PN XtRealize .\"to map the MenuBox widget. .\".LP .\"When creating a MenuBox widget, .\"the following resources are retrieved from the argument list .\"or from the resource database: .\".IN "MenuBox widget" "resources" .\".ps 9 .\".nr PS 9 .\".vs 11 .\".nr VS 11 .\".TS H .\"lw(1.5i) lw(1i) lw(1i) lw(2i). .\"_ .\".sp 3p .\".TB .\"Name Type Default Description .\".sp 3p .\"_ .\".TH .\".R .\".sp 3p .\"XtNbackgroundPixmap Pixmap None Window background pixmap .\"XtNborderPixmap Pixmap None Window border pixmap .\"XtNwidth Dimension 1 Menu window width .\"XtNheight Dimension 1 Menu window height .\"XtNorientation XtOrientation XtorientVertical Row/column layout .\"XtNborderWidth Dimension 1 Menu window border width .\"XtNborder Pixmap BlackPixmap Border color .\"XtNbackground int WhitePixel Background color .\"T{ .\"XtNinternalWidth .\"T} T{ .\"int .\"T} T{ .\"2 .\"T} T{ .\"Space between first item and top .\".br .\"Space between last item and bottom .\"T} .\"XtNinternalHeight int 2 First menu item to window top .\"XtNspace int 1 Space between menu items .\"XtNtranslations TranslationTable None event-to-action translations .\"XtNx Position 0 Widget location x coordinate .\"XtNy Position 0 Widget location y coordinate .\"XtNcallback XtCallbackList Dummy Callback function .\".sp 3p .\"_ .\".TE .\".ps 11 .\".nr PS 11 .\".vs 13 .\".nr VS 13 .\".LP .\".IN "MenuBox widget" 'creating" .\".IN "Creating widgets" "MenuBox" .\"To create a MenuBox widget instance, use .\".PN XtCreateWidget .\"and specify the class variable .\".PN menuBoxWidgetClass . .\".LP .\".IN "MenuBox widget" "adding entries" .\"To add entries, .\"specify the widget ID of the previously created MenuBox widget .\"as the parent of each new entry. .\".LP .\".IN "MenuBox widget" "deleting entries" .\"To delete an entry, use .\".PN XtUnmanageChild .\"or .\".PN XtDestroyWidget .\"and specify the widget ID of the entry. .\".LP .\"The MenuBox widget resides in whatever parent widget the application specifies. .\"For example, it does not automatically create a pop-up widget. .\"To create a pop-up menu, use .\".PN XtCreatePopupShell .\"and then create the MenuBox as a child of this newly created shell. .\".LP .\".IN "MenuBox widget" "over-riding geometry manager" .\"The MenuBox widget has a built-in geometry manager that enables the menu to .\"become as large as necessary. .\"To override the built-in geometry manager, .\"create your own geometry manager and call it .\".PN XtMenuGeometryManager . .\".IN "XtMenuGeometryManager" "" "@DEF@" .\".FD 0 .\"GeometryReturnCode XtMenuGeometryManager(\fIw\fP, \fIrequest\fP, \ .\"\fIrequest_box\fP, \fIreply_box\fP) .\".br .\" Widget \fIw\fP; .\".br .\" int \fIrequest\fP; .\".br .\"XtWidgetGeometry *\fIrequest_box\fP, *\fIreply_box\fP; .\".FN .\".IP \fIw\fP 1i .\"Specifies the widget ID. .\".IP \fIrequest\fP 1i .\"Specifies the geometry management request. .\".IP \fIrequest_box\fP 1i .\"Specifies the desired widget geometry. .\".IP \fIreply_box\fP 1i .\"Specifies an argument to which the allowed widget size is returned. .\".LP .\".IN "MenuBox widget" "destroying" .\".IN "Destroying widgets" "MenuBox" .\"To destroy a MenuBox widget instance, .\"use .\".PN XtDestroyWidget .\"and specify the widget ID of the MenuBox widget. .NH 2 VPaned Widget .LP .XS \*(SN VPaned Widget .XE .IN "VPaned widget" "" "@DEF@" The VPaned widget manages children in a vertically tiled fashion. A region, called a grip, appears on the border between each child. When the pointer is positioned on a grip and pressed, an arrow is displayed that indicates the significant pane that is being resized. While keeping the pointer button down, the user can move the pointer up or down. This, in turn, changes the window borders, causing one pane to shrink and some other pane to grow. The cursor indicates the pane that is of interest to the user; some other pane in the opposite direction will be chosen to grow or shrink an equal amount. The choice of alternate pane is a function of the .PN XtNmin , .PN XtNmax and .PN XtNskipAdjust constraints on the other panes. With the default bindings, button 1 resizes the pane above the selected grip, button 3 resizes the pane below the selected grip and button 2 repositions the border between two panes only. .LP The class variable for the VPaned widget is .PN vPanedWidgetClass . .LP When creating a VPaned widget instance, the following resources are retrieved from the argument list or from the resource database: .IN "VPaned widget" "resources" .ps 9 .nr PS 9 .vs 11 .nr VS 11 .TS H lw(1.5i) lw(1i) lw(1i) lw(2i) . _ .sp 3p .TB Name Type Default Description .sp 3p _ .TH .R .sp 3p XtNbackground Pixel XtDefaultBackground Window background color XtNbackgroundPixmap Pixmap None Window background pixmap T{ XtNbetweenCursor T} T{ Cursor T} T{ XC_sb_left_arrow T} T{ Cursor for changing the boundary between two panes T} XtNborderColor Pixel XtDefaultForeground Window border color XtNborderPixmap Pixmap None Window border pixmap XtNborderWidth Dimension 1 Border width (pixels) T{ XtNdestroyCallback T} T{ XtCallbackList T} T{ NULL T} T{ Callbacks for .PN XtDestroyWidget T} XtNforeground Pixel Black Pixel value for the foreground color XtNgripCursor Cursor XC_sb_v_double_arrow Cursor for grip when not active XtNgripIndent Position 10 Offset of grip from margin (pixels) XtNgripTranslations TranslationTable internal button bindings for grip XtNheight Dimension sum of child heights Height of vPane T{ XtNlowerCursor T} T{ Cursor T} T{ XC_sb_down_arrow T} T{ Cursor for resizing pane below grip T} T{ XtNmappedWhenManaged T} T{ Boolean T} T{ True T} T{ Whether .PN XtMapWidget is automatic T} XtNrefigureMode Boolean On Whether vPane should adjust children XtNsensitive Boolean True Whether widget receives input XtNtranslations TranslationTable None Event-to-action translations T{ XtNupperCursor T} T{ Cursor T} T{ XC_sb_up_arrow T} T{ Cursor for resizing pane above grip T} XtNwidth Dimension width of widest child Width of vPane XtNx Position 0 x position of vPane XtNy Position 0 y position of vPane .sp 3p _ .TE .ps 11 .nr PS 11 .vs 13 .nr VS 13 .LP .IN "VPaned widget" "creating" .IN "Creating widgets" "VPaned" To create a VPaned widget instance, use .PN XtCreateWidget and specify the class variable .PN vPanedWidgetClass . .LP Once the parent frame is created, you then add panes to it. Any type of widget can be paned. .LP .IN "VPaned widget" "adding pane" To add a child pane to a VPaned frame, use .PN XtCreateWidget and specify the widget ID of the VPaned widget as the parent of each new child pane. .LP During the creation of a child pane, the following resources, by which the VPaned widget controls the placement of the child, can be specified in the argument list or retrieved from the resource database: .IN "VPaned widget" "child resources" .LP .ps 9 .nr PS 9 .vs 11 .nr VS 11 .TS H lw(1.5i) lw(1i) lw(1i) lw(2i) . _ .sp 3p .TB Name Type Default Description .sp 3p _ .TH .R .sp 3p T{ XtNallowResize T} T{ Boolean T} T{ False T} T{ If False, ignore child resize requests T} XtNmax Dimension unlimited Maximum height for pane XtNmin Dimension 1 Minimum height for pane T{ XtNskipAdjust T} T{ Boolean T} T{ False T} T{ True if VPaned widget should not automatically resize pane T} .sp 3p _ .TE .ps 11 .nr PS 11 .vs 13 .nr VS 13 .LP .IN "VPaned widget" "deleting pane" To delete a pane from a vertically paned window frame, use .PN XtUnmanageWidget or .PN XtDestroyWidget and specify the widget ID of the child pane. .LP .IN "VPaned widget" "enable pane resizing" .IN "VPaned widget" "disable pane resizing" To enable or disable a child's request for pane resizing, use .PN XtPanedAllowResize . .IN "XtPanedAllowResize" "" "@DEF@" .FD 0 void XtPanedAllowResize(\fIw\fP, \fIallow_resize\fP) .br Widget \fIw\fP; .br Boolean \fIallow_resize\fP; .FN .IP \fIw\fP 1i Specifies the widget ID of the child widget pane. .IP \fIallow_resize\fP Enables or disables a pane widget for resizing requests. .LP If allow_resize is .PN True , VPane allows geometry requests from the child to change the pane's height. If allow_resize is .PN False , VPane ignores geometry requests from the child to change the pane's height. The default state is .PN True before the VPane is realized and .PN False after it is realized. This procedure is equivalent to changing the .PN XtNallowResize resource for the child. .LP .sp .IN "VPaned widget" "change height settings" To change the minimum and maximum height settings for a pane, use .PN XtPanedSetMinMax . .IN "XtPanedSetMinMax" "" "@DEF@" .FD 0 void XtPanedSetMinMax(\fIw\fP, \fImin\fP, \fImax\fP) .br Widget \fIw\fP; .br int \fImin\fP, \fImax\fP; .FN .IP \fIw\fP 1i Specifies the widget ID of the child widget pane. .IP \fImin\fP 1i New minimum height of the child, expressed in pixels. .IP \fImax\fP 1i New maximum height of the child, expressed in pixels. .LP This procedure is equivalent to setting the .PN XtNmin and .PN XtNmax resources for the child. .LP .sp .IN "VPaned widget" "enable auto-reconfiguring" .IN "VPaned widget" "disable auto-reconfiguring" To enable or disable automatic recalculation of pane sizes and positions, use .PN XtPanedSetRefigureMode . .IN "XtPanedSetRefigureMode" "" "@DEF@" .FD 0 void XtPanedSetRefigureMode(\fIw\fP, \fImode\fP) .br Widget \fIw\fP; .br Boolean \fImode\fP; .FN .IP \fIw\fP 1i Specifies the widget ID of the VPaned widget. .IP \fImode\fP 1i Enables or disables refiguration. .LP You should set the mode to FALSE if you add multiple panes to or remove multiple panes from the parent frame after it has been realized, unless you can arrange to manage all the panes at once using .PN XtManageChildren . After all the panes are added, set the mode to TRUE. This avoids unnecessary geometry calculations and ``window dancing''. .LP .IN "VPaned widget" "destroying" .IN "Destroying widgets" "VPaned" To delete an entire VPaned widget and all associated data structures, use .PN XtDestroyWidget and specify the widget ID of the VPaned widget. All the children of the VPaned widget are automatically destroyed at the same time. .NH 2 Form Widget .LP .XS \*(SN Form Widget .XE .IN "Form widget" "" "@DEF@" The Form widget can contain an arbitrary number of children or subwidgets. The Form provides geometry management for its children, which allows individual control of the position of each child. Any combination of children can be added to a Form. The initial positions of the children may be computed relative to the positions of other children. When the Form is resized, it computes new positions and sizes for its children. This computation is based upon information provided when a child is added to the Form. .LP The class variable for a Form widget is .PN formWidgetClass . .LP When creating a Form widget instance, the following resources are retrieved from the argument list or from the resource database: .IN "Form widget" "resources" .ps 9 .nr PS 9 .vs 11 .nr VS 11 .TS H lw(1.5i) lw(1i) lw(1i) lw(2i). _ .sp 3p .TB Name Type Default Description .sp 3p _ .TH .R .sp 3p XtNbackground Pixel XtDefaultBackground Window background color XtNbackgroundPixmap Pixmap None Window background pixmap XtNborderColor Pixel XtDefaultForeground Window border color XtNborderPixmap Pixmap None Window border pixmap XtNborderWidth Dimension 1 Width of border in pixels T{ XtNdefaultDistance T} T{ int T} T{ 4 T} T{ Default value for XtNhorizDistance .br and XtNvertDistance T} T{ XtNdestroyCallback T} T{ XtCallbackList T} T{ NULL T} T{ Callbacks for .PN XtDestroyWidget T} XtNheight Dimension computed at realize Height of form T{ XtNmappedWhenManaged T} T{ Boolean T} T{ True T} T{ Whether .PN XtMapWidget is automatic T} XtNsensitive Boolean True Whether widget receives input XtNtranslations TranslationTable None Event-to-action translations XtNwidth Dimension computed at realize Width of form XtNx Position NULL x position of form XtNy Position NULL y position of form .sp 3p _ .TE .ps 11 .nr PS 11 .vs 13 .nr VS 13 .LP .IN "Form widget" "creating" .IN "Creating widgets" "Form" To create a Form widget instance, use .PN XtCreateWidget and specify the class variable .PN formWidgetClass . .LP .IN "Form widget" "adding children" To add a new child to a Form, use .PN XtCreateWidget and specify the widget ID of the previously created Form as the parent of the child. .LP When creating children that are to be added to a Form, the following additional resources are retrieved from the argument list or from the resource database: .IN "Form widget" "child resources" .ps 9 .nr PS 9 .vs 11 .nr VS 11 .TS H lw(1.5i) lw(1i) lw(1i) lw(2i). _ .sp 3p .TB Name Type Default Description .sp 3p _ .TH .R .sp 3p XtNbottom XtEdgeType XtRubber See text XtNfromHoriz Widget NULL See text XtNfromVert Widget NULL See text XtNhorizDistance int XtdefaultDistance See text XtNleft XtEdgeType XtRubber See text XtNresizable Boolean FALSE TRUE if allowed to resize XtNright XtEdgeType XtRubber See text XtNtop XtEdgeType XtRubber See text XtNvertDistance int XtdefaultDistance See text .sp 3p _ .TE .ps 11 .nr PS 11 .vs 13 .nr VS 13 .LP When a widget is added to a Form, constraints can be specified to the Form to indicate where the child should be positioned within the Form. .LP The resources .PN XtNhorizDistance and .PN XtNfromHoriz let the widget position itself a specified number of pixels horizontally away from another widget in the form. As an example, .PN XtNhorizDistance could equal 10 and .PN XtNfromHoriz could be the widget ID of another widget in the Form. The new widget will be placed 10 pixels to the right of the widget defined in .PN XtNfromHoriz . If .PN XtNfromHoriz equals NULL, then .PN XtNhorizDistance is measured from the left edge of the Form. .LP Similarly, the resources .PN XtNvertDistance and .PN XtNfromVert let the widget position itself a specified number of pixels vertically away from another widget in the Form. If .PN XtNfromVert equals NULL, then .PN XtNvertDistance is measured from the top of the Form. Form provides a StringToWidget conversion procedure. Using this procedure, the resource database may be used to specify the .PN XtNfromHoriz and .PN XtNfromVert resources by widget name rather than widget id. The string value must be the name of a child of the same Form widget parent. .LP The .PN XtNtop , .PN XtNbottom , .PN XtNleft , and .PN XtNright resources tell the Form where to position the child when the Form is resized. .PN XtEdgeType is defined in .Pn < X11/Form.h > and is one of .IN "XtEdgeType" "" "@DEF@" .PN XtChainTop , .PN XtChainBottom , .PN XtChainLeft , .PN XtChainRight or .PN XtRubber . .LP The values .PN XtChainTop , .PN XtChainBottom , .PN XtChainLeft , and .PN XtChainRight specify that a constant distance from an edge of the child to the top, bottom, left, and right edges respectively of the Form is to be maintained. The value .PN XtRubber specifies that a proportional distance from the edge of the child to the left or top edge of the Form is to be maintained when the form is resized. The proportion is determined from the initial position of the child and the initial size of the Form. Form provides a StringToEdgeType conversion procedure to allow the resize constraints to be easily specified in a resource file. .LP The default width of the Form is the minimum width needed to enclose the children after computing their initial layout, with a margin of .PN XtNdefaultDistance at the right and bottom edges. If a width and height is assigned to the Form that is too small for the layout, the children will be clipped by the right and bottom edges of the Form. .LP .IN "Form widget" "deleting children" To remove a child from a Form, use .PN XtUnmanageChild or .PN XtDestroyWidget and specify the widget ID of the child widget. .LP .IN "Form widget" "destroying" .IN "Destroying widgets" "Form" To destroy a Form widget instance, use .PN XtDestroyWidget and specify the widget ID of the Form. All children of the Form are automatically destroyed at the same time. .LP When a new child becomes managed or an old child unmanaged, Form will recalculate the positions of its children according to the values of the .PN XtNhorizDistance , .PN XtNfromHoriz , .PN XtNvertDistance and .PN XtNfromVert constraints at the time the change is made. No re-layout is performed when a child makes a geometry request. .LP .sp To force or defer a re-layout of the Form, use .PN XtFormDoLayout . .IN "Form widget" "re-layout" .IN "XtFormDoLayout" "" "@DEF@" .FD 0 void XtFormDoLayout(\fIw\fP, \fIdo_layout\fP) .br Widget \fIw\fP; .br Boolean \fIdo_layout\fP; .FN .IP \fIw\fP 1i Specifies the Form widget. .IP \fIdo_layout\fP 1i Enables (if .PN True ) or disables (if .PN False ) layout of the Form widget. .LP When making several changes to the children of a Form widget after the Form has been realized, it is a good idea to disable re-layout until all changes have been made, then allow the layout. Form increments an internal count each time .PN XtFormDoLayout is called with do_layout .PN False and decrements the count when do_layout is .PN True . When the count reaches 0, Form performs a re-layout. .NH 2 Dialog Widget .LP .XS \*(SN Dialog Widget .XE .IN "Dialog widget" "" "@DEF@" The Dialog widget implements a commonly used interaction semantic to prompt for auxiliary input from a user. For example, you can use a Dialog widget when an application requires a small piece of information, such as a file name, from the user. A Dialog widget is simply a special case of the Form widget that provides a convenient way to create a ``preconfigured form''. .LP The typical Dialog widget contains three areas. The first line contains a description of the function of the Dialog widget, for example, the string ``Filename:''. The second line contains an area into which the user types input. The third line can contain buttons that let the user confirm or cancel the Dialog input. .LP The class variable for the Dialog widget is .PN dialogWidgetClass . .LP When creating a Dialog widget instance, the following resources are retrieved from the argument list or from the resource database: .IN "Dialog widget" "resources" .ps 9 .nr PS 9 .vs 11 .nr VS 11 .TS H lw(1.5i) lw(1i) lw(1i) lw(2i). _ .sp 3p .TB Name Type Default Description .sp 3p _ .TH .R XtNbackground Pixel XtDefaultBackground Window background color XtNbackgroundPixmap Pixmap None Window background pixmap XtNborderColor Pixel XtDefaultForeground Window border color XtNborderPixmap Pixmap None Window border pixmap XtNborderWidth Dimension 1 Width of border in pixels T{ XtNdestroyCallback T} T{ XtCallbackList T} T{ NULL T} T{ Callbacks for .PN XtDestroyWidget T} XtNheight Dimension computed at create Height of dialog XtNlabel String Label name String to be displayed T{ XtNmappedWhenManaged T} T{ Boolean T} T{ True T} T{ Whether .PN XtMapWidget is automatic T} XtNmaximumLength int 256 Length of input buffer XtNsensitive Boolean True Whether widget receives input XtNtranslations TranslationTable None Event-to-action translations XtNvalue char* NULL Pointer to default value string XtNwidth Dimension computed at create Width of dialog XtNx Position NULL x position of dialog XtNy Position NULL y position of dialog .sp 3p _ .TE .ps 11 .nr PS 11 .vs 13 .nr VS 13 .LP The instance name of the label widget within the Dialog widget is ``label'', and the instance name of the Dialog value widget is ``value''. .LP .IN "Dialog widget" "creating" .IN "Creating widgets" "Dialog" To create a Dialog widget instance, you can use .PN XtCreateWidget and specify the class variable .PN dialogWidgetClass . .LP .IN "Dialog widget" "adding children" To add a child button to the Dialog box, use .PN XtCreateWidget and specify widget ID of the previously created Dialog box as the parent of each child. When creating buttons, you do not have to specify form constraints. The Dialog box will automatically add the constraints. .LP .sp To return the character string in the text field, use .PN XtDialogGetValueString . .IN "XtDialogGetValueString" "" "@DEF@" .FD 0 char *XtDialogGetValueString(\fIw\fP) .br Widget \fIw\fP; .FN .IP \fIw\fP 1i Specifies the widget ID of the Dialog box. .LP If a string was specified in the .PN XtNvalue resource, Dialog copy the string internally and will use it as the initial (i.e. default) value for the input text. The value string may be freed immediately after creating the Dialog widget. If the length of the value string is greater than the maximumLength resource, the larger value is used. .LP If no value resource is specified for the Dialog widget, the text user input area is not displayed. In order to display a blank input area, an empty string must be passed as the value resource. .LP .sp .IN "Dialog widget" "removing children" To remove a child button from the Dialog box, use .PN XtUnmanageChild or .PN XtDestroyWidget and specify the widget ID of the child. .LP .IN "Dialog widget" "destroying" .IN "Destroying widgets" "Dialog" To destroy a Dialog widget instance, use .PN XtDestroyWidget and specify the widget ID of the Dialog widget. All children of the Dialog are automatically destroyed at the same time. .NH 2 List Widget .LP .XS \*(SN List Widget .XE .IN "List widget" "" "@DEF@" The List widget is a rectangle that contains a list of strings formatted into rows and columns. When one of the strings is selected, it is highlighted, and an application callback routine is invoked. .\"When the cursor pointer is clicked on one of the strings .\"it is shown to be selected by highlighting and the application's .\"callback routine is invoked. .LP The class variable for the List widget is .PN listWidgetClass . .LP When creating a List widget instance, the following resources are retrieved from the argument list or from the resource database: .IN "List widget" "resources" .ps 9 .nr PS 9 .vs 11 .nr VS 11 .TS H lw(1.5i) lw(1i) lw(1i) lw(2i). _ .sp 3p .TB Name Type Default Description .sp 3p _ .TH .R .sp 3p XtNbackground Pixel XtDefaultBackground Window background color XtNbackgroundPixmap Pixmap None Window background pixmap XtNborderColor Pixel XtDefaultForeground Window border color XtNborderPixmap Pixmap None Window border pixmap XtNborderWidth Dimension 1 Width of border XtNcallback XtCallbackList NULL Selection callback function XtNcolumnSpacing Dimension 6 Space between columns in the list XtNcursor Cursor left_ptr Pointer cursor XtNdefaultColumns int 2 Number of columns to use T{ XtNdestroyCallback T} T{ XtCallbackList T} T{ NULL T} T{ Callbacks for .PN XtDestroyWidget T} XtNfont XFontStruct* XtDefaultFont Font for list text XtNforceColumns Boolean False Force the use of XtNdefaultColumns XtNforeground Pixel XtDefaultForeground Foreground (text) color XtNheight Dimension Contains list exactly Height of widget XtNinsensitiveBorder Pixmap Gray Border when not sensitive T{ XtNinternalHeight T} T{ Dimension T} T{ 2 T} T{ Spacing between list and widget edges T} T{ XtNinternalWidth T} T{ Dimension T} T{ 4 T} T{ Spacing between list and widget edges T} XtNlist String * List name An array of strings that is the list T{ XtNlongest T} T{ int T} T{ Longest item T} T{ Length of the longest list item in pixels T} T{ XtNmappedWhenManaged T} T{ Boolean T} T{ True T} T{ Whether .PN XtMapWidget is automatic T} T{ XtNnumberStrings T} T{ int T} T{ Number of strings T} T{ Number of items in the list T} XtNpasteBuffer Boolean False Copy the selected item to cut buffer 0 XtNrowSpacing Dimension 4 Space between rows in the list XtNsensitive Boolean True Whether widget receives input XtNtranslations TranslationTable None Event-to-action translations XtNverticalList Boolean False Specify the layout of list items XtNwidth Dimension Contains list exactly Width of widget XtNx Position 0 Widget x coordinate XtNy Position 0 Widget y coordinate .sp 3p _ .TE .ps 11 .nr PS 11 .vs 13 .nr VS 13 .LP The new resources associated with the List widget are: .TS lw(1.7i) lw(4i). T{ .PN XtNcolumnSpacing .br .PN XtNrowSpacing T} T{ Specify the amount of space between each of the rows and columns in the list. T} .sp T{ .PN XtNdefaultColumns T} T{ Specifies the default number of columns, which is used when neither the width nor the height of the List widget is specified or when XtNforceColumns is .PN True . T} .sp 6p T{ .PN XtNforceColumns T} T{ Specifies that the default number of columns is to be used no matter what the current size of the List widget is. T} .sp 6p T{ .PN XtNheight T} T{ Specifies the height of the List widget. The default value is the minimum height that will contain the entire list with the spacing values specified. If the specified height is larger than the minimum, the list is put in the upper left corner. T} .sp 6p T{ .PN XtNinternalHeight T} T{ Represents a margin, in pixels, between the top and bottom of the list and the edges of the List widget. T} .sp 6p T{ .PN XtNinternalWidth T} T{ Represents a margin, in pixels, between the left and right edges of the list and the edges of the List widget. T} .sp 6p T{ .PN XtNlist T} T{ Specifies the array of text strings that is to displayed in the List widget. If the default for XtNnumberStrings is used, the list must be null-terminated. If a value is not specified for the list, the number of strings is set to 1, and the name of the widget is used as the list. T} .sp 6p T{ .PN XtNlongest T} T{ Specifies the length of the longest string in the current list in pixels. If the client knows the length, it should specify it. The List widget will compute a default length by searching through the list. T} .sp 6p T{ .PN XtNnumberStrings T} T{ Specifies the number of strings in the current list. If a value is not specified, the list must be null-terminated. T} .sp 6p T{ .PN XtNpasteBuffer T} T{ If this is .PN True , then the value of the string selected will be put into X cut buffer 0. T} .sp 6p T{ .PN XtNsensitive T} T{ If set to .PN False , the List widget will change its window border to .PN XtNinsensitiveBorder and display all items in the list as stippled strings. While the List widget is insensitive, no item in the list can be selected or highlighted. T} .sp 6p T{ .PN XtNverticalList T} T{ If this is .PN True , the elements in the list are arranged vertically; if .PN False , the elements are arranged horizontally. T} .sp 6p T{ .PN XtNwidth T} T{ Specifies the width of the List widget. The default value is the minimum width that will contain the entire list with the spacing values specified. If the specified width is larger than the minimum, the list is put in the upper left corner. T} .TE .LP The List widget has three predefined actions: Set, Unset, and Notify. Set and Unset allow switching the foreground and background colors for the current list item. Notify allows processing application callbacks. .LP The following is the default translation table used by the List Widget: .LP .Ds .TA .5i 2.25i .ta .5i 2.25i ,: Set(\|) Notify(\|) .De .LP .IN "List widget" "creating" .IN "Creating widgets" "List" To create a List widget instance, use .PN XtCreateWidget and specify the class variable .PN listWidgetClass . .LP .IN "List widget" "destroying" .IN "Destroying widgets" "list" To destroy a List widget instance, use .PN XtDestroyWidget and specify the widget ID of the List widget. .LP The List widget supports two callback lists: .IP \(bu 5 .PN XtNdestroyCallback .IP \(bu 5 .PN XtNcallback .LP The notify action executes the callbacks on the the .PN XtNcallback list. .LP The call_data argument passed to callbacks on the .PN XtNcallback list is a pointer to an .PN XtListReturnStruct structure, defined in .Pn < X11/List.h >: .LP .Ds 0 .TA .5i 2.25i .ta .5i 2.25i .IN "XtListReturnStruct" "" "@DEF@" typedef struct _XtListReturnStruct { String string; /* string shown in the list. */ int index; /* index of the item selected. */ } XtListReturnStruct; .De .NH 3 Changing the List .LP To change the list that is displayed, use .PN XtListChange . .IN "XtListChange" "" "@DEF@" .FD 0 void XtListChange(\fIw\fP, \fIlist\fP, \fInitems\fP, \fIlongest\fP, \fIresize\fP) .br Widget \fIw\fP; .br String * \fIlist\fP; .br int \fInitems\fP, \fIlongest\fP; .br Boolean \fIresize\fP; .FN .IP \fIw\fP 1i Specifies the widget ID. .IP \fIlist\fP 1i Specifies the new list for the list widget to display. .IP \fInitems\fP 1i Specifies the number of items in the list. If a value less than 1 is specified, list must be null terminated. .IP \fIlongest\fP 1i Specifies the length of the longest item in the list in pixels. If a value less than 1 is specified, the List widget calculates the value for you. .IP \fIresize\fP 1i Specifies a Boolean value that indicates whether the List widget should try to resize itself .Pn ( True ) or not .Pn ( False ) after making the change. Note that the constraints of the parent of this widget are always enforced, regardless of the value specified. .LP .PN XtListChange changes the list of strings that the List widget is to display. .NH 3 Highlighting an Item .LP To highlight an item in the list use, .PN XtListHighlight .IN "XtListHighlight" "" "@DEF@" .FD 0 void XtListHighlight(\fIw\fP, \fIitem\fP); .br Widget \fIw\fP; .br int \fIitem\fP; .FN .IP \fIw\fP 1i Specifies the widget ID. .IP \fIitem\fP 1i Specifies the index into the current list that indicates the item to be highlighted. .LP Only one item can be highlighted at a time. If an item is already highlighted when .PN XtListHighlight is called, the highlighted item is immediately unhighlighted and the new item is highlighted. .NH 3 Unhighlighting an Item .LP To unhighlight the currently highlighted item in the list, use .PN XtListUnhighlight .IN "XtListUnhighlight" "" "@DEF@" .FD 0 void XtListUnhightlight(\fIw\fP); .br Widget \fIw\fP; .FN .IP \fIw\fP 1i Specifies the widget ID. .NH 3 Retrieving the Currently Selected Item .LP To retrieve an item in the list use, .PN XtListShowCurrent .IN "XtListShowCurrent" "" "@DEF@" .FD 0 XtListReturnStruct *XtListShowCurrent(\fIw\fP); .br Widget \fIw\fP; .FN .IP \fIw\fP 1i Specifies the widget ID. .LP The .PN XtListShowCurrent function returns a pointer to an .PN XtListReturnStruct structure, contains the currently highlighted item. If the value of the index member is XT_LIST_NONE, .IN "XT_LIST_NONE" the string member is undefined, which indicates that no item is currently selected. .\"------------------------------------------------------------------------ .NH 2 Grip Widget .LP .XS \*(SN Grip Widget .XE .IN "Grip widget" "" "@DEF@" .LP The Grip widget provides a small region in which user input events (such as .PN ButtonPress or .PN ButtonRelease ) may be handled. The most common use for the grip is as an attachment point for visually repositioning an object, such as the pane border in a VPaned widget. .LP The class variable for the Grip widget is .PN gripWidgetClass . .LP When creating a Grip widget instance, the following resources are retrieved from the argument list or from the resource database: .ps 9 .nr PS 9 .vs 11 .nr VS 11 .TS H lw(1.5i) lw(1i) lw(1i) lw(2i). _ .sp 3p .TB Name Type Default Description .sp 3p _ .TH .R .sp 3p XtNborderColor Pixel XtDefaultForeground Window border color XtNborderPixmap Pixmap None Window border pixmap XtNborderWidth Dimension 0 Width of the border in pixels XtNcallback XtCallbackList None Action routine XtNcursor Cursor None Cursor for the grip T{ XtNdestroyCallback T} T{ XtCallbackList T} T{ NULL T} T{ Callback for .PN XtDestroyWidget T} XtNforeground Pixel XtDefaultForeground Window background color XtNheight Dimension 8 Height of the widget T{ XtNmappedWhenManaged T} T{ Boolean T} T{ True T} T{ Whether .PN XtMapWidget is automatic T} XtNsensitive Boolean True Whether widget should receive input XtNtranslations TranslationTable None Event-to-action translations XtNwidth Dimension 8 Width of the widget XtNx Position 0 x coordinate within parent XtNy Position 0 y coordinate within parent .sp 3p _ .TE .ps 11 .nr PS 11 .vs 13 .nr VS 13 .LP Note that the Grip widget displays its region with the foreground pixel only. .LP The Grip widget does not declare any default event translation bindings, but it does declare a single action routine named GripAction in its action table. The client specifies an arbitrary event translation table giving parameters to the GripAction routine. .LP The .PN GripAction action executes the callbacks on the .PN XtNcallback list, passing as call_data a pointer to a .PN GripCallData structure, defined in .Pn < X11/Grip.h > : .LP .Ds 0 .TA .5i 2.25i .ta .5i 2.25i .IN "GripCallData" "" "@DEF@" .IN "GripCallDataRec" "" "@DEF@" typedef struct _GripCallData { XEvent *event; String *params; Cardinal num_params; } GripCallDataRec, *GripCallData; .De .LP In this structure, the event field is a pointer to the input event that triggered the action, and params and num_params give the string parameters specified in the translation table for the particular event binding. .IN "Grip widget" "GripAction table" .LP The following is an example of a GripAction translation table: .LP .Ds 0 .TA .5i 2.5i .ta .5i 2.5i : GripAction(press) : GripAction(move) : GripAction(release) .De For a complete description of the format of action routines, see the \fI\*(xT\fP. .LP .IN "Grip widget" "creating" .IN "Creating widgets" "Grip" To create a Grip widget instance, use .PN XtCreateWidget and specify the class variable .PN gripWidgetClass . .LP .IN "Grip widget" "destroying" .IN "Destroying widgets" "Grip" To destroy a Command button widget instance, use .PN XtDestroyWidget and specify the ID of the Grip widget. .\"------------------------------------------------------------------------ .NH 2 Toggle Widget .LP .XS \*(SN Toggle Widget .XE .IN "Toggle widget" "" "@DEF@" The Toggle widget is a rectanglular button that contains a text label or pixmap. This widget maintains a Boolean state (e.g. True/False or On/Off) and changes state whenever it is selected. When the pointer cursor is on the Toggle it highlights to indicate that the Toggle is available for selection. When the pointer button is pressed the Toggle is selected. This causes the state of the Toggle to reverse and its callback routine to be invoked. .LP Toggle buttons may also be part of a radio group. A radio group is a list of Toggle buttons in which only one Toggle may be set at any time. A radio group is identified by giving the widget id of any one of its members. There is a convenience routine, .PN XtToggleGetCurrent that will return information about the Toggle in the radio group that is currently set. More information on radio groups is presented below. .LP The class variable for the Toggle widget is .PN toggleWidgetClass . .LP When creating a Toggle widget instance, the following resources are retrieved from the argument list or from the resource database: .IN "Toggle widget" "resources" .ps 9 .nr PS 9 .vs 11 .nr VS 11 .TS H lw(1.5i) lw(1i) lw(1i) lw(2i). _ .sp 3p .TB Name Type Default Description .sp 3p _ .TH .R .sp 3p XtNbackground Pixel XtDefaultBackground Window background color XtNbackgroundPixmap Pixmap None Window background pixmap T{ XtNbitmap T} T{ Pixmap T} T{ None T} T{ Pixmap to display in place of the label T} XtNborderColor Pixel XtDefaultForeground Window border color XtNborderPixmap Pixmap None Window border pixmap XtNborderWidth Dimension 1 Width of button border XtNcallback XtCallbackList NULL Callback for button select XtNcursor Cursor None Pointer cursor T{ XtNdestroyCallback T} T{ XtCallbackList T} T{ NULL T} T{ Callbacks for .PN XtDestroyWidget T} XtNfont XFontStruct* XtDefaultFont Label font XtNforeground Pixel XtDefaultForeground Foreground color XtNheight Dimension Text height Button height T{ XtNhighlightThickness T} T{ Dimension T} T{ 2 T} T{ Width of border to be highlighted T} XtNinsensitiveBorder Pixmap Gray Border when not sensitive T{ XtNinternalHeight T} T{ Dimension T} T{ 2 T} T{ Internal border height for highlighting T} T{ XtNinternalWidth T} T{ Dimension T} T{ 4 T} T{ Internal border width for highlighting T} XtNjustify XtJustify XtJustifyCenter Type of text alignment XtNlabel String Button name Button label T{ XtNmappedWhenManaged T} T{ Boolean T} T{ True T} T{ Whether .PN XtMapWidget is automatic T} XtNradioData Pointer Name of widget Value that will be returned by \fBXtToggleGetCurrent\fP XtNradioGroup Widget NULL Any other widget in the Toggle's radio group XtNresize Boolean True Whether to auto-resize in \fBSetValues\fP XtNsensitive Boolean True Whether widget receives input XtNstate Boolean Off State of the Toggle widget XtNtranslations TranslationTable see below Event-to-action translations XtNwidth Dimension Text width Button width XtNx Position 0 x coordinate XtNy Position 0 y coordinate .sp 3p _ .TE .ps 11 .nr PS 11 .vs 13 .nr VS 13 .TS lw(1.7i) lw(4i). T{ .PN XtNbitmap T} T{ Specifies a bitmap to display in place of the text label [See the description of this resource in the Label widget for further details]. T} .sp 6p T{ .PN XtNcallback T} T{ Specifies the callback list of functions to be called when the Toggle widget changes state. This usually occurs when the Toggle widget's notify action is called, but when a toggle is in a radio group it may change state at other times. The places where this can occur include: .PN XtToggleSetCurrent , .PN XtToggleUnsetCurrent , .PN XtToggleChangeRadioGroup , the .PN set action, .PN XtSetValues, and .PN XtCreateWidget. T} .sp 6p T{ .PN XtNheight T} T{ Specifies the height of the Toggle widget. The default value is the minimum height that will contain: .br \fBXtNinternalheight\fP + height of \fBXtNlabel\fP + \fBXtNinternalHeight\fP .br If the specified height is larger than the minimum, the label string is centered vertically. T} .sp 6p T{ .PN XtNinternalHeight T} T{ Represents the distance in pixels between the top and bottom of the label text or bitmap and the horizontal edges of the Toggle widget. HighlightThickness can be larger or smaller than this value. T} .sp 6p T{ .PN XtNinternalWidth T} T{ Represents the distance in pixels between the ends of the label text or bitmap and the vertical edges of the Toggle widget. HighlightThickness can be larger or smaller than this value. T} .sp 6p T{ .PN XtNjustify T} T{ Specifies left, center, or right alignment of the label string within the Toggle widget. If it is specified within an .PN ArgList , one of the values .PN XtJustifyLeft , .PN XtJustifyCenter , or .PN XtJustifyRight can be specified. In a resource of type ``string'', one of the values ``left'', ``center'', or ``right'' can be specified. T} .sp 6p T{ .PN XtNlabel T} T{ Specifies the text string that is to be displayed in the Toggle widget if no bitmap is specified. The default is the widget name of the Toggle widget. T} .sp 6p T{ .PN XtNradioData T} T{ Specifies the data that will be returned from a call to .PN XtToggleGetCurrent if this widget is the one that is set in a radio group. This data is also used to identify the toggle that will be set by a call to .PN XtToggleSetCurrent. The value NULL is returned by .PN XtToggleGetCurrent if no widget is set in a radio group. Programmers not specify NULL as \fBXtNradioData\fP, if they intend to use \fBXtToggleGetCurrent\fP T} .sp 6p T{ .PN XtNradioGroup T} T{ Specifies another Toggle widget which is in the radio group to which this Toggle widget should be added. A radio group is a group of Toggle widgets, only one of which may be "set" at a time. If this value is NULL (the default) then the Toggle will not be part of any radio group and can change state without effecting any other Toggle widgets. If the widget specified in this resource is not already in a radio group then a new radio group will be created containing these two Toggle widgets. No Toggle widget can be in multiple radio groups. T} .sp 6p T{ .PN XtNresize T} T{ Specifies whether the Toggle widget should attempt to resize to its preferred dimensions whenever .PN XtSetValues is called for it. The default is .PN True . T} .sp 6p T{ .PN XtNsensitive T} T{ If set to .PN False , the Toggle widget will change its window border to .PN XtNinsensitiveBorder and will stipple the label string. T} .sp 6p T{ .PN XtNstate T} T{ Specifies whether the Toggle widget is set (True/On) or unset (False/Off). T} .sp 6p T{ .PN XtNwidth T} T{ Specifies the width of the Toggle widget. The default value is the minimum width that will contain: .br \fBXtNinternalwidth\fP + width of \fBXtNlabel\fP + \fBXtNinternalWidth\fP .br If the width is larger or smaller than the minimum, .PN XtNjustify determines how the label string is aligned. T} .TE .LP The Toggle widget supports the following actions: .IP \(bu 5 Switching the button between the foreground and background colors with \fBset\fP, \fBunset\fP and \fBtoggle\fP .IP \(bu 5 Processing application callbacks with \fBnotify\fP. .IP \(bu 5 Switching the internal border between highlighted and unhighlighted states with \fBhighlight\fP and \fBunhighlight\fP .LE .LP The following are the default translation bindings that are used by the Toggle widget: .LP .Ds 0 .TA .5i 2.25i .ta .5i 2.25i : highlight(Always) : unhighlight(\|) ,: toggle(\|) notify(\|) .De .LP With these bindings, the user can cancel the action before releasing the button by moving the pointer out of the Toggle widget. .NH 3 Toggle Actions .LP The full list of actions supported by the Toggle widget is: .IP \fBhighlight\fP(\fIvalue\fP) 1.5i Displays the internal highlight border in the color (\fBXtNforeground\fP or .PN XtNbackground ) that contrasts with the interior color of the Toggle widget. This action procedure takes one of the following conditions: WhenUnset and Always. If no argument is passed then WhenUnset is assumed, this maintains backwards compatibility. .IP \fBunhighlight\fP(\|) 1.5i Displays the internal highlight border in the color (\fBXtNforeground\fP or .PN XtNbackground ) that matches the interior color of the Toggle widget. .IP \fBset\fP(\|) 1.5i Enters the "set" state, in which \fBnotify\fP is possible and displays the interior of the button in the .PN XtNforeground color. The label is displayed in the .PN XtNbackground color. If the widget to be set is in a radio group then this procedure may unset another widget, which will cause all routines on its callback list to be invoked. Since only one toggle in a radio group may be set at a time the callback routines for the toggle that is to be unset will be called before the one that is to be set. .IP \fBunset\fP(\|) 1.5i Cancels the "set" state and displays the interior of the button in the .PN XtNbackground color. The label is displayed in the .PN XtNforeground color. .IP \fBtoggle\fP(\|) 1.5i Changes the current state of the Toggle widget, causing to be set if it was previously unset, and unset if it was previously set. If the widget is to be set, and is in a radio group then this procedure may unset another widget, which will cause all routines on its callback list to be invoked. Since only one toggle in a radio group may be set at a time the callback routines for the toggle that is to be unset will be called before the one that is to be set. .IP \fBreset\fP(\|) 1.5i Cancels any \fBset\fP or \fBhighlight\fP and displays the interior of the button in the .PN XtNbackground color, with the label displayed in the .PN XtNforeground color. .IP \fBnotify\fP(\|) 1.5i Executes the .PN XtNcallback callback list. The call_data contains a Boolean which is the current state of the widget. .LP .IN "Toggle widget" "creating" .IN "Creating widgets" "Toggle" To create a Toggle widget instance, use .PN XtCreateWidget and specify the class variable .PN toggleWidgetClass . .LP .IN "Toggle widget" "destroying" .IN "Destroying widgets" "toggle" To destroy a Toggle widget instance, use .PN XtDestroyWidget and specify the widget ID of the Toggle widget. .LP The Toggle widget supports two callbacks: .PN XtNdestroyCallback and .PN XtNcallback . The notify action executes the callbacks on the the .PN XtNcallback list. .SH Changing the Toggle's Radio Group. .LP To enable an application to change the Toggle's current radio group, add the Toggle to a radio group, or remove the Toggle from a radio group, use .PN XtToggleChangeRadioGroup. .IN ""XtToggleChangeRadioGroup"" "@DEF@" .sp 6p void XtToggleChangeRadioGroup(\fIw\fP, \fIradio_group\fP) .br Widget \fIw\fP, \fIradio_group\fP; .FN .IP \fIw\fP 1i Specifies the widget ID of the Toggle widget. .IP \fIradio_group\fP 1i This should be any Toggle on the new radio group. If NULL then the Toggle will be removed from any radio group of which it is a member. .LP If a toggle is already in the set state in the new radio group, and the toggle to be added is also set then the previously set toggle in the new radio group is unset and its callback procedures are invoked. .SH Finding the Currently selected Toggle in a radio group of Toggles .LP To find the currently selected Toggle in a radio group of Toggle widgets use .PN XtToggleGetCurrent. .IN ""XtToggleGetCurrent"" "@DEF@" .sp 6p caddr_t XtToggleGetCurrent(\fIradio_group\fP); .br Widget \fIradio_group\fP; .FN .IP \fIradio_group\fP 1i Specifies the widget ID of any Toggle in the radio group. .LP The value returned by this function is the data pointed to by .PN XtNradioData, for the Toggle in the radio group that is currently set. The default value for .PN XtNradioData is the name of that Toggle widget. If no Toggle is set in the radio group specified then NULL is returned. .SH Changing the Toggle that is set in a radio group. .LP To change the Toggle that is currently set in a radio group use .PN XtToggleSetCurrent. .IN ""XtToggleSetCurrent"" "@DEF@" .sp 6p void XtToggleSetCurrent(\fIradio_group\fP, \fIradio_data\fP); .br Widget \fIradio_group\fP; caddr_t \fIradio_data\fP; .FN .IP \fIradio_group\fP 1i Specifies the widget ID of any Toggle in the radio group. .IP \fIradio_data\fP 1i Specifies the .PN XtNradioData identifying the Toggle that should be set in the radio group specified by the \fIradio_group\fP argument. .LP \fBXtToggleSetCurrent\fP locates the Toggle widget to be set by matching \fIradio_data\fP against the \fBXtNradioData\fP for each Toggle in the radio group. If none match \fBXtToggleSetCurrent\fP returns without making any changes. If more than one Toggle matches, \fBXtToggleSetCurrent\fP will choose a Toggle to set arbitrarily. If this causes any Toggle widgets to change state all routines in their callback lists will be invoked. Since only one toggle in a radio group may be set at a time the callback routines for a Toggle that is to be unset will be called before the one that is to be set. .SH Unsetting all Toggles in a radio group. .LP To unset all Toggle widgets in a radio group use .PN XtToggleUnsetCurrent. .IN ""XtToggleUnsetCurrent"" "@DEF@" .sp 6p void XtToggleUnsetCurrent(\fIradio_group\fP); .br Widget \fIradio_group\fP; .FN .IP \fIradio_group\fP 1i Specifies the widget ID of any Toggle in the radio group. .LP If this causes a Toggle widget to change state all routines on its callback list will be invoked. .\"------------------------------------------------------------------------ .NH 2 Template Widget - Creating A Custom Widget .LP .XS \*(SN Template Widget - Creating A Custom Widget .XE .IN "Template widget" "" "@DEF@" .LP 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 three files that are intended to assist in writing a custom widget. .LP Reasons for wishing to write a custom widget include: .IP \(bu 3 Convenient access to resource management procedures to obtain fonts, colors, etc., even if user customization is not desired. .IP \(bu 3 Convenient access to user input dispatch and translation management procedures. .IP \(bu 3 Access to callback mechanism for building higher-level application libraries. .IP \(bu 3 Customizing the interface or behavior of an existing widget to suit a special application need. .IP \(bu 3 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. .IP \(bu 3 Converting a non-Toolkit application to use the Toolkit. .LP 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 shared by the subclass. .LP 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 .PN widgetClass . The geometry of the Core widget is determined entirely by the parent widget. .LP 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 desireable to have a "Window Widget" class that might have the following semantics: .IP \(bu 3 Allocate 2 drawing colors in addition to a background color. .IP \(bu 3 Allocate a text font. .IP \(bu 3 Execute an application-supplied function to handle exposure events. .IP \(bu 3 Execute an application-supplied function to handle user input events. .LP 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. .LP .sp 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 \fI\*(xT\fP for complete details of the material outlined here. Section 1.4 of the \fI\*(xI\fP should be read in conjunction with this section. .LP All Athena widgets have three separate files associated with them: .LP .IP \(bu 3 A "public" header file containing declarations needed by applications programmers .IP \(bu 3 A "private" header file containing additional declarations needed by the widget and any subclasses .IP \(bu 3 A source code file containing the implementation of the widget .LP 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. .LP .sp In the following example, the public header file .Pn < X11/Template.h >, the private header file .Pn < X11/TemplateP.h > and the source code file .Pn < X11/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. .NH 3 Public Header File .LP The public header file contains declarations that will be required by any application module that needs to refer to the widget; whether to create an instance of the class, to perform an .PN XtSetValues operation, or to call a public routine implemented by the widget class. .LP The contents of the Template public header file, .Pn < X11/Template.h >, are: .de CB .sp .ps 9 .nr PS 9 .vs 10 .Ds 0 .in +.25i .TA .25i 1.4i 2.4i 2.75i 3.5i .ta .25i 1.4i 2.4i 2.75i 3.5i .. .de CE .De .\".in -.25i .ps 11 .nr PS 11 .vs 13 .. .CB .\".so ../../lib/Xaw/Template.h #include /* XConsortium: Template.h,v 1.2 88/10/25 17:22:09 swick Exp $ */ /* Copyright (c) X Consortium 1987, 1988 */ #ifndef _Template_h #define _Template_h /**************************************************************** * * Template widget * ****************************************************************/ /* Resources: Name Class RepType Default Value ---- ----- ------- ------------- background Background Pixel XtDefaultBackground border BorderColor Pixel XtDefaultForeground borderWidth BorderWidth Dimension 1 destroyCallback Callback Pointer NULL height Height Dimension 0 mappedWhenManaged MappedWhenManaged Boolean True sensitive Sensitive Boolean True width Width Dimension 0 x Position Position 0 y Position Position 0 */ /* define any special resource names here that are not in */ #define XtNtemplateResource "templateResource" #define XtCTemplateResource "TemplateResource" /* declare specific TemplateWidget class and instance datatypes */ typedef struct _TemplateClassRec* TemplateWidgetClass; typedef struct _TemplateRec* TemplateWidget; /* declare the class constant */ extern WidgetClass templateWidgetClass; #endif _Template_h .CE .LP .sp You will notice that most of this file is documentation. The crucial parts are the last 8 lines where macros for any private resource names and classes are defined and where the widget class datatypes and class record pointer are declared. .LP For the "WindowWidget", we want 2 drawing colors, a callback list for user input and an \fBXtNexposeCallback\fP callback list, and we will declare three convenience procedures, so we need to add .LP .sp .CB /* Resources: ... callback Callback Callback NULL drawingColor1 Color Pixel XtDefaultForeground drawingColor2 Color Pixel XtDefaultForeground exposeCallback Callback Callback NULL font Font XFontStruct* XtDefaultFont ... */ #define XtNdrawingColor1 "drawingColor1" #define XtNdrawingColor2 "drawingColor2" #define XtNexposeCallback "exposeCallback" extern Pixel WindowColor1(\|/* Widget */\|); extern Pixel WindowColor2(\|/* Widget */\|); extern Font\ \ WindowFont(\|/* Widget */\|); .CE .LP Note that we have chosen to call the input callback list by the generic name, .PN XtNcallback , rather than a specific name. If widgets that define a single user-input action all choose the same resource name then there is greater possibility for an application to switch between widgets of different types. .NH 3 Private Header File .LP The private header file contains the complete declaration of the class and instance structures for the widget and any additional private data that will be required by anticipated subclasses of the widget. Information in the private header file is normally hidden from the application and is designed to be accessed only through other public procedures; e.g. .PN XtSetValues . .LP The contents of the Template private header file, .Pn < X11/TemplateP.h >, are: .CB .\".so ../../lib/Xaw/TemplateP.h #include /* XConsortium: TemplateP.h,v 1.2 88/10/25 17:31:47 swick Exp $ */ /* Copyright (c) X Consortium 1987, 1988 */ #ifndef _TemplateP_h #define _TemplateP_h #include "Template.h" /* include superclass private header file */ #include /* define unique representation types not found in */ #define XtRTemplateResource "TemplateResource" typedef struct { int empty; } TemplateClassPart; typedef struct _TemplateClassRec { CoreClassPart core_class; TemplateClassPart template_class; } TemplateClassRec; extern TemplateClassRec templateClassRec; typedef struct { /* resources */ char* resource; /* private state */ } TemplatePart; typedef struct _TemplateRec { CorePart core; TemplatePart template; } TemplateRec; #endif _TemplateP_h .CE .LP .sp The private header file includes the private header file of its superclass, thereby exposing the entire internal structure of the widget. It may not always be advantageous to do this; your own project development style will dictate the appropriate level of detail to expose in each module. .LP The "WindowWidget" needs to declare two fields in its instance structure to hold the drawing colors, a resource field for the font and a field for the expose and user input callback lists: .CB typedef struct { /* resources */ Pixel color_1; Pixel color_2; XFontStruct* font; XtCallbackList expose_callback; XtCallbackList input_callback; /* private state */ /* (none) */ } WindowPart; .CE .NH 3 Widget Source File .LP The source code file implements the widget class itself. The unique part of this file is the declaration and initialization of the widget class record structure and the declaration of all resources and action routines added by the widget class. .LP The contents of the Template implementation file, .Pn < X11/Template.c >, are: .CB .\".so ../../lib/Xaw/Template.c #include /* XConsortium: Template.c,v 1.2 88/10/25 17:40:25 swick Exp $ */ /* Copyright (c) X Consortium 1987, 1988 */ #include #include #include "TemplateP.h" static XtResource resources[] = { #define offset(field) XtOffset(TemplateWidget, template.field) /* {name, class, type, size, offset, default_type, default_addr}, */ { XtNtemplateResource, XtCTemplateResource, XtRTemplateResource, sizeof(char*), offset(resource), XtRString, "default" }, #undef offset }; static void TemplateAction(/* Widget, XEvent*, String*, Cardinal* */); static XtActionsRec actions[] = { /* {name, procedure}, */ {"template", TemplateAction}, }; static char translations[] = " : template(\|) \\n\\ "; TemplateClassRec templateClassRec = { { /* core fields */ /* superclass */ (WidgetClass) &widgetClassRec, /* class_name */ "Template", /* widget_size */ sizeof(TemplateRec), /* class_initialize */ NULL, /* class_part_initialize */ NULL, /* class_inited */ FALSE, /* initialize */ NULL, /* initialize_hook */ NULL, /* realize */ XtInheritRealize, /* actions */ actions, /* num_actions */ XtNumber(actions), /* resources */ resources, /* num_resources */ XtNumber(resources), /* xrm_class */ NULLQUARK, /* compress_motion */ TRUE, /* compress_exposure */ TRUE, /* compress_enterleave */ TRUE, /* visible_interest */ FALSE, /* destroy */ NULL, /* resize */ NULL, /* expose */ NULL, /* set_values */ NULL, /* set_values_hook */ NULL, /* set_values_almost */ XtInheritSetValuesAlmost, /* get_values_hook */ NULL, /* accept_focus */ NULL, /* version */ XtVersion, /* callback_private */ NULL, /* tm_table */ translations, /* query_geometry */ XtInheritQueryGeometry, /* display_accelerator */ XtInheritDisplayAccelerator, /* extension */ NULL }, { /* template fields */ /* empty */ 0 } }; WidgetClass templateWidgetClass = (WidgetClass)&templateClassRec; .CE The resource list for the "WindowWidget" might look like the following: .CB static XtResource resources[] = { #define offset(field) XtOffset(WindowWidget, window.field) /* {name, class, type, size, offset, default_type, default_addr}, */ { XtNdrawingColor1, XtCColor, XtRPixel, sizeof(Pixel), offset(color_1), XtRString, XtDefaultForeground }, { XtNdrawingColor2, XtCColor, XtRPixel, sizeof(Pixel), offset(color_2), XtRString, XtDefaultForeground }, { XtNfont, XtCFont, XtRFontStruct, sizeof(XFontStruct*), offset(font), XtRString, XtDefaultFont }, { XtNexposeCallback, XtCCallback, XtRCallback, sizeof(XtCallbackList), offset(expose_callback), XtRCallback, NULL }, { XtNcallback, XtCCallback, XtRCallback, sizeof(XtCallbackList), offset(input_callback), XtRCallback, NULL }, #undef offset }; .CE .LP The user input callback will be implemented by an action procedure which passes the event pointer as call_data. The action procedure is declared as: .CB /* ARGSUSED */ static void InputAction(w, event, params, num_params) Widget w; XEvent *event; String *params; /* unused */ Cardinal *num_params; /* unused */ { XtCallCallbacks(w, XtNcallback, (caddr_t)event); } static XtActionsRec actions[] = { /* {name, procedure}, */ {"input", InputAction}, }; .CE .LP and the default input binding will be to execute the input callbacks on .PN KeyPress and .PN ButtonPress : .LP .CB static char translations[] = " : input(\|) \\n\\ : input(\|) \\ "; .CE .LP In the class record declaration and initialization, the only field that is different from the Template is the expose procedure: .CB /* ARGSUSED */ static void Redisplay(w, event, region) Widget w; XEvent *event; /* unused */ Region region; { XtCallCallbacks(w, XtNexposeCallback, (caddr_t)region); } WindowClassRec windowClassRec = { ... /* expose */ Redisplay, .CE .LP .sp The "WindowWidget" will also declare three public procedures to return the drawing colors and the font id, saving the application the effort of constructing an argument list for a call to .PN XtGetValues : .LP .CB Pixel WindowColor1(w) Widget w; { return ((WindowWidget)w)->window.color_1; } Pixel WindowColor2(w) Widget w; { return ((WindowWidget)w)->window.color_2; } Font WindowFont(w) Widget w; { return ((WindowWidget)w)->window.font->fid; } .CE .LP The "WindowWidget" is now complete. The application can retrieve the two drawing colors from the widget instance by calling either .PN XtGetValues , or the \fBWindowColor\fP functions. The actual window created for the "WindowWidget" is available by calling the .PN XtWindow function. .LP To test the new ``WindowWidget'', you may substitute ``window'' for ``command'' in the sample program given in Section 2.7.3. .TC