\&
.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 <stdio.h>
#include <X11/Intrinsic.h>
#include <X11/Command.h>
.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
<EnterWindow>: highlight(\|)
<LeaveWindow>: reset(\|)
<Btn1Down>: set(\|)
<Btn1Up>: 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 \\
<FocusIn>: display-caret(on) \\n\\
<FocusOut>: 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[] = ``\\
Ctrl<Key>F: forward-character(\|) \\n\\
Ctrl<Key>B: backward-character(\|) \\n\\
Ctrl<Key>D: delete-next-character(\|) \\n\\
Ctrl<Key>A: beginning-of-line(\|) \\n\\
Ctrl<Key>E: end-of-line(\|) \\n\\
Ctrl<Key>H: delete-previous-character(\|) \\n\\
Ctrl<Key>J: newline-and-indent(\|) \\n\\
Ctrl<Key>K: kill-to-end-of-line(\|) \\n\\
Ctrl<Key>L: redraw-display(\|) \\n\\
Ctrl<Key>M: newline(\|) \\n\\
Ctrl<Key>N: next-line(\|) \\n\\
Ctrl<Key>O: newline-and-backup(\|) \\n\\
Ctrl<Key>P: previous-line(\|) \\n\\
Ctrl<Key>V: next-page(\|) \\n\\
Ctrl<Key>W: kill-selection(\|) \\n\\
Ctrl<Key>Y: unkill(\|) \\n\\
Ctrl<Key>Z: scroll-one-line-up(\|) \\n\\
Meta<Key>F: forward-word(\|) \\n\\
Meta<Key>B: backward-word(\|) \\n\\
Meta<Key>I: insert-file(\|) \\n\\
Meta<Key>K: kill-to-end-of-paragraph(\|) \\n\\
Meta<Key>V: previous-page(\|) \\n\\
Meta<Key>Y: stuff(\|) \\n\\
Meta<Key>Z: scroll-one-line-down(\|) \\n\\
:Meta<Key>d: delete-next-word(\|) \\n\\
:Meta<Key>D: kill-word(\|) \\n\\
:Meta<Key>h: delete-previous-word(\|) \\n\\
:Meta<Key>H: backward-kill-word(\|) \\n\\
:Meta<Key>\\<: beginning-of-file(\|) \\n\\
:Meta<Key>\\>: end-of-file(\|) \\n\\
:Meta<Key>]: forward-paragraph(\|) \\n\\
:Meta<Key>[: backward-paragraph(\|) \\n\\
~Shift Meta<Key>Delete: delete-previous-word(\|) \\n\\
\ Shift Meta<Key>Delete: backward-kill-word(\|) \\n\\
~Shift Meta<Key>Backspace: delete-previous-word(\|) \\n\\
\ Shift Meta<Key>Backspace: backward-kill-word(\|) \\n\\
<Key>Right: forward-character(\|) \\n\\
<Key>Left: backward-character(\|) \\n\\
<Key>Down: next-line(\|) \\n\\
<Key>Up: previous-line(\|) \\n\\
<Key>Delete: delete-previous-character(\|) \\n\\
<Key>BackSpace: delete-previous-character(\|) \\n\\
<Key>Linefeed: newline-and-indent(\|) \\n\\
<Key>Return: newline(\|) \\n\\
<Key>: insert-char(\|) \\n\\
<FocusIn>: focus-in(\|) \\n\\
<FocusOut>: focus-out(\|) \\n\\
<Btn1Down>: select-start(\|) \\n\\
<Btn1Motion>: extend-adjust(\|) \\n\\
<Btn1Up>: extend-end(PRIMARY, CUT_BUFFER0) \\n\\
<Btn2Down>: insert-selection(PRIMARY, CUT_BUFFER0) \\n\\
<Btn3Down>: extend-start(\|) \\n\\
<Btn3Motion>: extend-adjust(\|) \\n\\
<Btn3Up>: 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: \\
<Key>Right: forward-character(\|) \\n\\
<Key>Left: backward-character(\|) \\n\\
Meta<Key>F: forward-word(\|) \\n\\
Meta<Key>B: backward-word(\|) \\n\\
:Meta<Key>]: forward-paragraph(\|) \\n\\
:Meta<Key>[: backward-paragraph(\|) \\n\\
<Key>: 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 <Btn2Down>: 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
<Btn1Down>: StartScroll(Forward)
<Btn2Down>: StartScroll(Continuous) MoveThumb(\|) NotifyThumb(\|)
<Btn3Down>: StartScroll(Backward)
<Btn2Motion>: MoveThumb(\|) NotifyThumb(\|)
<BtnUp>: 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: \\
~Meta<KeyPress>space: StartScroll(Forward) NotifyScroll(FullLength) \\n\\
Meta<KeyPress>space: 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
<Btn1Down>,<Btn1Up>: 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
<Btn1Down>: GripAction(press)
<Btn1Motion>: GripAction(move)
<Btn1Up>: 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
<EnterWindow>: highlight(Always)
<LeaveWindow>: unhighlight(\|)
<Btn1Down>,<Btn1Up>: 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 <X11/copyright.h>
/* 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 <X11/StringDefs.h> */
#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 <X11/copyright.h>
/* 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 <X11/CoreP.h>
/* define unique representation types not found in <X11/StringDefs.h> */
#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 <X11/copyright.h>
/* XConsortium: Template.c,v 1.2 88/10/25 17:40:25 swick Exp $ */
/* Copyright (c) X Consortium 1987, 1988 */
#include <X11/IntrinsicP.h>
#include <X11/StringDefs.h>
#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[] =
" <Key>: 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[] =
" <Key>: input(\|) \\n\\
<BtnDown>: 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