1104 lines
36 KiB
Plaintext
1104 lines
36 KiB
Plaintext
.\" $Xorg: CH2,v 1.3 2000/08/17 19:42:26 cpqbld Exp $
|
|
.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
|
|
.IN "using widgets" "" "@DEF@"
|
|
Widgets serve as the primary tools for building a user interface or
|
|
application environment. The Athena widget set consists of primitive
|
|
widgets that contain no children (for example, a command button) and
|
|
composite widgets which may contain one or more widget children (for
|
|
example, a Box widget).
|
|
.LP
|
|
The remaining chapters explain the widgets that are provided
|
|
by the Athena widget set.
|
|
These user-interface components serve as an interface for
|
|
application programmers who do not want to implement their own widgets.
|
|
In addition, they serve as a starting point
|
|
for those widget programmers who, using the \*(xI mechanisms,
|
|
want to implement alternative application programming interfaces.
|
|
.LP
|
|
This chapter is a brief introduction to widget programming. The
|
|
examples provided use the Athena widgets, though most of the concepts
|
|
will apply to all widget sets. Although there are several programming
|
|
interfaces to the \*(tk, only one is described here. A full
|
|
description of the programming interface is provided in the document
|
|
\fI\*(xT\fP.
|
|
.NH 2
|
|
Setting the Locale
|
|
.LP
|
|
.XS
|
|
Setting the Locale
|
|
.XE
|
|
If it is desirable that the application take advantage of
|
|
internationalization (i18n), you must establish locale with
|
|
.PN XtSetLanguageProc
|
|
before \fBXtDisplayInitialize\fP or \fBXtAppInitialize\fP
|
|
is called. For full details, please refer to the document
|
|
\fI\*(xT\fP, section 2.2. However, the following simplest-case
|
|
call is sufficient in many or most applications.
|
|
.LP
|
|
.IN "internationalization" "" ""
|
|
.IN "XtSetLanguageProc" "" "@DEF@"
|
|
.IN "locale" "" ""
|
|
.Ds
|
|
.TA .5i 2i
|
|
.ta .5i 2i
|
|
XtSetLanguageProc(NULL, NULL, NULL);
|
|
.De
|
|
.LP
|
|
Most notably, this will affect the Standard C locale, determine which
|
|
resource files will be loaded, and what fonts will be required of FontSet
|
|
specifications. In many cases, the addition of this line is the only source change
|
|
required to internationalize Xaw programs, and will not disturb the function
|
|
of programs in the default "C" locale.
|
|
.NH 2
|
|
Initializing the Toolkit
|
|
.LP
|
|
.XS
|
|
Initializing the Toolkit
|
|
.XE
|
|
You must call a toolkit initialization function before invoking any
|
|
other toolkit routines (besides locale setting, above).
|
|
.PN XtAppInitialize
|
|
opens the X server connection, parses the command line,
|
|
and creates an initial widget that will serve as the root of
|
|
a tree of widgets created by this application.
|
|
.IN "initialization" "" "@DEF@"
|
|
.IN "toolkit initialization" "" "@DEF@"
|
|
.IN "XtAppInitialize" "" "@DEF@"
|
|
.IN "fallback resources" "" "@DEF@"
|
|
.FD 0
|
|
Widget XtAppInitialize(\fIapp_context_return\fP, \fIapplication_class\fP, \
|
|
\fIoptions\fP, \fInum_options\fP,
|
|
.ta 2i
|
|
\fIargc_in_out\fP, \fIargv_in_out\fP, \fIfallback_resources\fP, \
|
|
\fIargs\fP, \fInum_args\fP)
|
|
.br
|
|
XtAppContext *\fIapp_context_return\fP;
|
|
.br
|
|
String \fIapplication_class\fP;
|
|
.br
|
|
XrmOptionDescRec \fIoptions\fP[];
|
|
.br
|
|
Cardinal \fInum_options\fP;
|
|
.br
|
|
int *\fIargc_in_out\fP;
|
|
.br
|
|
String *\fIargv_in_out\fP[];
|
|
.br
|
|
String *\fIfallback_resources\fP;
|
|
.br
|
|
ArgList \fIargs\fP;
|
|
.br
|
|
Cardinal \fInum_args\fP;
|
|
.FN
|
|
.IP \fIapp_con_return\fP 1.5i
|
|
Returns the application context of this application, if non-NULL.
|
|
.IP \fIapplication_class\fP 1.5i
|
|
Specifies the class name of this application,
|
|
which is usually the generic name for all instances of this application.
|
|
A useful convention is to form the class name by capitalizing the
|
|
first letter of the application name. For example, the application named
|
|
``xman'' has a class name of ``Xman''.
|
|
.IP \fIoptions\fP 1.5i
|
|
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 1.5i
|
|
Specifies the number of entries in the options list.
|
|
.IP \fIargc_in_out\fP 1.5i
|
|
Specifies a pointer to the number of command line parameters.
|
|
.IP \fIargv_in_out\fP 1.5i
|
|
Specifies the command line parameters.
|
|
.IP \fIfallback_resources\fP 1.5i
|
|
Specifies resource values to be used if the site-wide application class
|
|
defaults file cannot be opened, or NULL.
|
|
.IP \fIargs\fP 1.5i
|
|
Specifies the argument list to use when creating the Application shell.
|
|
.IP \fInum_args\fP 1.5i
|
|
Specifies the number of arguments in \fIargs\fP.
|
|
.LP
|
|
This function will remove the command line arguments that the toolkit
|
|
reads from \fIargc_in_out\fP, and \fIargv_in_out\fP. It will then
|
|
attempt to open the display. If the display cannot be opened, an error
|
|
message is issued and XtAppInitialize terminates the application. Once
|
|
the display is opened, all resources are read from the locations
|
|
specified by the \*(xI. This function returns an ApplicationShell
|
|
widget to be used as the root of the application's widget tree.
|
|
.NH 2
|
|
Creating a Widget
|
|
.LP
|
|
.XS
|
|
Creating a Widget
|
|
.XE
|
|
.IN "widget creation" "" "@DEF@"
|
|
.IN "creating widgets" "" "@DEF@"
|
|
.IN "XtRealizeWidget" "" ""
|
|
Creating a widget is a three-step process. First, the widget instance
|
|
is allocated, and various instance-specific attributes are set by
|
|
using \fBXtCreateWidget\fP. Second, the widget's parent is informed
|
|
of the new child by using \fBXtManageChild\fP. Finally, X windows are
|
|
created for the parent and all its children by using \fBXtRealizeWidget\fP
|
|
and specifying the top-most widget. The first two steps can be
|
|
combined by using \fBXtCreateManagedWidget\fP. In addition,
|
|
\fBXtRealizeWidget\fP is automatically called when the child becomes
|
|
managed if the parent is already realized.
|
|
.LP
|
|
To allocate, initialize, and manage a widget, use
|
|
.PN XtCreateManagedWidget .
|
|
.IN "XtCreateManagedWidget" "" "@DEF@"
|
|
.FD 0
|
|
Widget XtCreateManagedWidget(\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.
|
|
If 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.
|
|
.IN "XtError" "" ""
|
|
.LP
|
|
For further information, see \fI\*(xT\fP.
|
|
.NH 2
|
|
Common Resources
|
|
.XS
|
|
Common Resources
|
|
.XE
|
|
.IN "resource" ""
|
|
.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 regard for the individual widget type.
|
|
Widgets will 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 of the Athena widgets:
|
|
.TS H
|
|
lw(1.5i) lw(1i) lw(1i) lw(2i).
|
|
_
|
|
.sp 3p
|
|
.TB
|
|
Name Class Type Default Value
|
|
.sp 3p
|
|
_
|
|
.TH
|
|
.R
|
|
.sp 3p
|
|
accelerators Accelerators AcceleratorTable NULL
|
|
ancestorSensitive AncestorSensitive Boolean True
|
|
background Background Pixel XtDefaultBackground
|
|
backgroundPixmap Pixmap Pixmap XtUnspecifiedPixmap
|
|
borderColor BorderColor Pixel XtDefaultForeground
|
|
borderPixmap Pixmap Pixmap XtUnspecifiedPixmap
|
|
borderWidth BorderWidth Dimension 1
|
|
colormap Colormap Colormap Parent's Colormap
|
|
depth Depth int Parent's Depth
|
|
destroyCallback Callback XtCallbackList NULL
|
|
height Height Dimension \fIwidget dependent\fP
|
|
mappedWhenManaged MappedWhenManaged Boolean True
|
|
screen Screen Screen Parent's Screen
|
|
sensitive Sensitive Boolean True
|
|
translations Translations TranslationTable \fIwidget dependent\fP
|
|
width Width Dimension \fIwidget dependent\fP
|
|
x Position Position 0
|
|
y Position Position 0
|
|
.sp 3p
|
|
_
|
|
.TE
|
|
.IN "XtDefaultForeground" "" ""
|
|
.IN "XtDefaultBackground" "" ""
|
|
.LP
|
|
The following additional resources are retrieved from the argument list
|
|
or from the resource database by many of the Athena widgets:
|
|
.TS H
|
|
lw(1.5i) lw(1i) lw(1i) lw(2i).
|
|
_
|
|
.sp 3p
|
|
.TB
|
|
Name Class Type Default Value
|
|
.sp 3p
|
|
_
|
|
.TH
|
|
.R
|
|
.sp 3p
|
|
callback Callback XtCallbackList NULL
|
|
cursor Cursor Cursor \fIwidget dependent\fP
|
|
foreground Foreground Pixel XtDefaultForeground
|
|
insensitiveBorder Insensitive Pixmap GreyPixmap
|
|
.sp 3p
|
|
_
|
|
.TE
|
|
.IN "XtDefaultForeground" "" ""
|
|
.NH 2
|
|
Resource Conversions
|
|
.XS
|
|
Resource Conversions
|
|
.XE
|
|
.IN "conversions" "" "@DEF@"
|
|
.IN "string conversions" "" "@DEF@"
|
|
.IN "type conversions" "" "@DEF@"
|
|
.LP
|
|
Most resources in the Athena widget set have a converter registered that
|
|
will translate the string in a resource file to the correct internal
|
|
representation. While some are obvious (string to integer, for example),
|
|
others need specific mention of the allowable values. Three general
|
|
converters are described here:
|
|
.IP \(bu 5
|
|
Cursor
|
|
.IP \(bu 5
|
|
Pixel
|
|
.IP \(bu 5
|
|
Bitmap
|
|
.LP
|
|
Many widgets have defined special converters that apply only to that
|
|
widget. When these occur, the documentation section for that widget
|
|
will describe the converter.
|
|
.NH 3
|
|
Cursor Conversion
|
|
.IN "conversions" "ColorCursor" "@DEF@"
|
|
.IN "conversions" "Cursor" "@DEF@"
|
|
.IN "cursor" "" ""
|
|
.LP
|
|
The value for the \fBcursorName\fP resource is specified in the resource
|
|
database as a string, and is of the following forms:
|
|
.IP \(bu 5
|
|
A standard X cursor name from \fB< X11/cursorfont.h >\fP.
|
|
The names in \fBcursorfont.h\fP each describe a specific cursor. The
|
|
resource names for these cursors are exactly like the names in this file
|
|
except the \fBXC_\fP is not used. The cursor definition \fBXC_gumby\fP
|
|
has a resource name of \fBgumby\fP.
|
|
.IP \(bu 5
|
|
Glyphs, as in \fIFONT font-name glyph-index [[ font-name ] glyph-index ]\fP.
|
|
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.
|
|
.IP \(bu 5
|
|
A relative or absolute file name.
|
|
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 the filename does not start with '/' or './' the the bitmap
|
|
file path is used (see section 2.4.3).
|
|
.NH 3
|
|
Pixel Conversion
|
|
.LP
|
|
.IN "conversions" "Pixel" "@DEF@"
|
|
.IN "pixel" "" ""
|
|
.IN "rgb.txt" "" ""
|
|
.IN "XtDefaultForeground" "" ""
|
|
.IN "XtDefaultBackground" "" ""
|
|
The string-to-pixel converter takes any name that is acceptable to
|
|
XParseColor (see \fI\*(xL\fP). In addition this routine understands
|
|
the special toolkit symbols `XtDefaultForeground' and
|
|
`XtDefaultBackground', described in \fI\*(xT\fP. In short the acceptable
|
|
pixel names are:
|
|
.IP \(bu 5
|
|
Any color name for the rgb.txt file (typically in the directory
|
|
/usr/lib/X11 on POSIX systems).
|
|
.IP \(bu 5
|
|
A numeric specification of the form #<red><green><blue> where these
|
|
numeric values are hexadecimal digits (both upper and lower case).
|
|
.IP \(bu 5
|
|
The special strings `XtDefaultForeground' and `XtDefaultBackground'
|
|
.NH 3
|
|
Bitmap Conversion
|
|
.IN "bitmap conversions" "" "@DEF@"
|
|
.IN "conversions" "Bitmap" "@DEF@"
|
|
.IN "bitmapFilePath" "" "@DEF@"
|
|
.IN "BitmapFilePath" "" "@DEF@"
|
|
.IN "/usr/include/X11/bitmaps" "" ""
|
|
.LP
|
|
The string-to-bitmap converter attempts to locate a file containing
|
|
bitmap data whose name is specified by the input string. If the file
|
|
name is relative (i.e. does not begin with / or ./), the directories to
|
|
be searched are specified in the \fBbitmapFilePath\fP resource--class
|
|
\fBBitmapFilePath\fP. This resource specifies a colon (:) separated
|
|
list of directories that will be searched for the named bitmap or
|
|
cursor glyph (see section 2.4.1). The \fBbitmapFilePath\fP resource is
|
|
global to the application, and may \fBnot\fP be specified differently
|
|
for each widget that wishes to convert a cursor to bitmap. In addition
|
|
to the directories specified in the \fBbitmapFilePath\fP resource a
|
|
default directory is searched. When using POSIX the default
|
|
directory is
|
|
.PN /usr/include/X11/bitmaps .
|
|
.NH 2
|
|
Realizing a Widget
|
|
.LP
|
|
.XS
|
|
Realizing a Widget
|
|
.XE
|
|
.IN "realizing widgets" "" "@DEF@"
|
|
The
|
|
.PN XtRealizeWidget
|
|
function performs two tasks:
|
|
.IP \(bu 5
|
|
Calculates the geometry constraints of all managed descendants
|
|
of this widget. The actual calculation is put off until realize time
|
|
for performance reasons.
|
|
.IP \(bu 5
|
|
Creates an X window for the widget and, if it is a composite widget,
|
|
realizes each of its managed children.
|
|
.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
|
|
Processing Events
|
|
.LP
|
|
.XS
|
|
Processing Events
|
|
.XE
|
|
.IN "events" "" ""
|
|
.IN "XtAppInitialize" "" ""
|
|
Now that the application has created, managed and realized its
|
|
widgets, it is ready to process the events that will be delivered by the
|
|
X Server to this client. A function call that will process the
|
|
events is \fBXtAppMainLoop\fP.
|
|
.IN "XtAppMainLoop" "" "@DEF@"
|
|
.FD 0
|
|
void XtAppMainLoop(\fIapp_context\fP)
|
|
.br
|
|
XtAppContext \fIapp_context\fP;
|
|
.FN
|
|
.IP \fIapp_context\fP 1i
|
|
Specifies the application context of this application. The value is
|
|
normally returned by \fBXtAppInitialize\fP.
|
|
.LP
|
|
This function never returns: it is an infinite loop that processes the
|
|
X events. User input can be handled through callback procedures and
|
|
application defined action routines. More details are provided in
|
|
\fI\*(xT\fP.
|
|
.NH 2
|
|
Standard Widget Manipulation Functions
|
|
.XS
|
|
Standard Widget Manipulation Functions
|
|
.XE
|
|
.LP
|
|
After a widget has been created, a client can interact with that
|
|
widget by calling one of the standard widget manipulation routines
|
|
provided by the \*(xI, or a widget class-specific manipulation routine.
|
|
.LP
|
|
The \*(xI provide generic routines to give the application programmer
|
|
access to a set of standard widget functions. The common widget
|
|
routines let an application or composite widget perform the following
|
|
operations on widgets without requiring explicit knowledge of the widget
|
|
type.
|
|
.IP \(bu 5
|
|
Control the 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 are mapped (made viewable) automatically by
|
|
\fBXtRealizeWidget\fP. This behavior can be disabled by using
|
|
\fBXtSetMappedWhenManaged\fP, making the client responsible for calling
|
|
\fBXtMapWidget\fP to make the widget viewable.
|
|
.IN "XtSetMappedWhenManaged" "" "@DEF@"
|
|
.IN "XtMapWidget" "" ""
|
|
.IN "XtRealizeWidget" "" ""
|
|
.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 \fBTrue\fP, the widget is mapped automatically
|
|
when it is realized. If map_when_managed is \fBFalse\fP, 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
|
|
void XtMapWidget(\fIw\fP)
|
|
.br
|
|
Widget \fIw\fP;
|
|
.FN
|
|
.IP \fIw\fP 1i
|
|
Specifies the widget.
|
|
.LP
|
|
When you are creating several children in sequence for a previously
|
|
realized common parent it is generally more efficient to construct a
|
|
list of children as they are created (using \fBXtCreateWidget\fP) and
|
|
then use \fBXtManageChildren\fP to request that their parent managed
|
|
them all at once. 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@"
|
|
.IN "XtCreateWidget" "" ""
|
|
.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\*(xT\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 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 \fBaddress\fP
|
|
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 providing space
|
|
into which the returned resource value is copied; the \fBArgList\fP
|
|
contains a pointer to this storage (e.g. x and y must be
|
|
allocated as Position). 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 an array of name and \fBvalue\fP 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 that are passed will 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 \fBXtSetValues\fP request is
|
|
ignored.
|
|
.LP
|
|
For further information about these functions, see the \fI\*(xT\fP.
|
|
.IN "XtGetValues" "" ""
|
|
.IN "XtSetValues" "" ""
|
|
.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
|
|
Using the Client Callback Interface
|
|
.XE
|
|
.IN "callbacks" "" ""
|
|
Widgets can 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
|
|
XtPointer \fIclient_data\fP;
|
|
.br
|
|
XtPointer \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. If no
|
|
additional information is necessary, NULL may be passed as this argument.
|
|
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 \fBjumpProc\fP callback list,
|
|
it passes the current position of the thumb in \fIcall_data\fP.
|
|
.LP
|
|
Callbacks can be registered either by creating an argument containing
|
|
the callback list described below or by using the special convenience
|
|
routines \fBXtAddCallback\fP and \fBXtAddCallbacks\fP. 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 "XtAddCallbacks"
|
|
.IN "XtAddCallback"
|
|
.IN "XtCallbackList" "" "@DEF@"
|
|
.IN "XtCallbackRec" "" "@DEF@"
|
|
.LP
|
|
.Ds 0
|
|
.TA .5i 3i
|
|
.ta .5i 3i
|
|
typedef struct {
|
|
XtCallbackProc callback;
|
|
XtPointer closure;
|
|
} XtCallbackRec, *XtCallbackList;
|
|
.De
|
|
.LP
|
|
The callback list must be allocated and initialized before calling
|
|
.PN XtCreateWidget .
|
|
.IN "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
|
|
XtPointer \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 destroyCallback
|
|
.IN "destroyCallback" "" "@DEF@"
|
|
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 \fIcall_data\fP argument is unused for
|
|
destroy callbacks.
|
|
.NH 2
|
|
Programming Considerations
|
|
.LP
|
|
.XS
|
|
Programming Considerations
|
|
.XE
|
|
This section provides some guidelines on how to set up an application
|
|
program that uses the \*(tk.
|
|
.NH 3
|
|
Writing Applications
|
|
.LP
|
|
.IN "writing applications"
|
|
.IN "StringDefs.h"
|
|
.IN "Intrinsic.h"
|
|
When writing an application that uses the X 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.
|
|
It may also be necessary to include \fB< X11/StringDefs.h >\fP when setting
|
|
up argument lists, as many of the XtN\fIsomething\fP definitions are
|
|
only defined in this file.
|
|
.IP 2. 5
|
|
Include the widget-specific header files for each widget type
|
|
that you need to use.
|
|
For example,
|
|
.Pn < X11/Xaw/Label.h >
|
|
and
|
|
.Pn < X11/Xaw/Command.h >.
|
|
.IP 3. 5
|
|
Call the
|
|
.PN XtAppInitialize
|
|
.IN "XtAppInitialize"
|
|
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 override
|
|
any site or user customizations, set up argument lists. In this
|
|
document, a list of valid argument names is provided in the discussion
|
|
of each widget. The names each have a global symbol defined that begins
|
|
with \fBXtN\fP to help catch spelling errors. For example,
|
|
\fBXtNlabel\fP is defined for the \fBlabel\fP resource of many widgets.
|
|
.IN "XtN" "" "@DEF@"
|
|
.IP
|
|
For further information, see Section 2.9.2.2.
|
|
.IP 5. 5
|
|
When the argument list is set up, create the widget with the
|
|
\fBXtCreateManagedWidget\fP function. For further information, see
|
|
Section 2.2 and the \fI\*(xT\fP.
|
|
.IN "XtCreateManagedWidget"
|
|
.IP 6. 5
|
|
If the widget has any callback routines, set by the
|
|
.PN XtNcallback
|
|
argument or the
|
|
.PN XtAddCallback
|
|
function, declare these routines within the application.
|
|
.IN "XtAddCallback"
|
|
.IP 7. 5
|
|
After creating the initial widget hierarchy, windows must be created
|
|
for each widget by calling
|
|
.PN XtRealizeWidget
|
|
on the top level widget.
|
|
.IN "XtRealizeWidget"
|
|
.IP 8. 5
|
|
Most applications now sit in a loop processing events using
|
|
.PN XtAppMainLoop ,
|
|
for example:
|
|
.IN "XtAppMainLoop"
|
|
.IP
|
|
.Ds 0
|
|
XtCreateManagedWidget(\fIname\fP, \fIclass\fP, \fIparent\fP, \fIargs\fP, \fInum_args\fP);
|
|
XtRealizeWidget(\fIshell\fP);
|
|
XtAppMainLoop(\fIapp_context\fP);
|
|
.De
|
|
.IP
|
|
For information about this function, see the \fI\*(xT\fP.
|
|
.IP 9. 5
|
|
Link your application with
|
|
.PN libXaw
|
|
(the Athena widgets),
|
|
.PN libXmu
|
|
(miscellaneous utilities),
|
|
.PN libXt
|
|
(the \*(tk \*(xI),
|
|
.PN libSM
|
|
(Session Management),
|
|
.PN libICE
|
|
(Inter-Client Exchange),
|
|
.PN libXext
|
|
(the extension library needed for the shape extension code which allows
|
|
rounded Command buttons), and
|
|
.PN libX11
|
|
(the core X library).
|
|
The following provides a sample command line:
|
|
.IN "libXaw"
|
|
.IN "libXmu"
|
|
.IN "libXt"
|
|
.IN "libSM"
|
|
.IN "libICE"
|
|
.IN "libXext"
|
|
.IN "libX11"
|
|
.IN "linking applications"
|
|
.IN "compiling applications"
|
|
.IP
|
|
.Ds 0
|
|
cc -o \fIapplication\fP \fIapplication\fP.c \-lXaw \-lXmu \-lXt \
|
|
\-lSM \-lICE \-lXext \-lX11
|
|
.De
|
|
.NH 3
|
|
Changing Resource Values
|
|
.IN "resource" ""
|
|
.LP
|
|
The \*(xI support two methods of changing the default resource
|
|
values; the resource manager, and an argument list passed into
|
|
XtCreateWidget. While resources values will get updated no matter
|
|
which method you use, the two methods provide slightly different
|
|
functionality.
|
|
.IP "Resource Manager" 1.5i
|
|
This method picks up resource definitions described in \fI\*(xL\fP from
|
|
many different locations at run time. The locations most important to
|
|
the application programmer are the \fIfallback resources\fP and the
|
|
\fIapp-defaults\fP file, (see \fI\*(xT\fP for the complete list).
|
|
Since these resource are loaded at run time, they can be overridden by
|
|
the user, allowing an application to be customized to fit the
|
|
particular needs of each individual user. These values can also be
|
|
modified without the need to rebuild the application, allowing rapid
|
|
prototyping of user interfaces. Application programmers should use
|
|
resources in preference to hard-coded values whenever possible.
|
|
.IP "Argument Lists" 1.5i
|
|
The values passed into the widget at creation time via an argument list
|
|
cannot be modified by the user, and allow no opportunity for
|
|
customization. It is used to set resources that cannot be specified as
|
|
strings (e.g. callback lists) or resources that should not be
|
|
overridden (e.g. window depth) by the user.
|
|
.NH 4
|
|
Specifying Resources
|
|
.LP
|
|
It is important for all X Toolkit application programmers to
|
|
understand how to use the X Resource Manager to specify resources for
|
|
widgets in an X application. This section will describe the most common
|
|
methods used to specify these resources, and how to use the X Resource
|
|
manager.
|
|
.IN "xrdb"
|
|
.IP \fBXrdb\fP 1.5i
|
|
The \fBxrdb\fP utility may be used to load a file containing
|
|
resources into the X server. Once the resources are loaded, the
|
|
resources will affect any new applications started on the display that
|
|
they were loaded onto.
|
|
.IN "application defaults"
|
|
.IN "app-defaults"
|
|
.IN "/usr/lib/X11/app-defaults"
|
|
.IP "\fBApplication Defaults\fP" 1.5i
|
|
The application defaults (app-defaults) file (normally in
|
|
/usr/lib/X11/app-defaults/\fIclassname\fP) for an application is loaded
|
|
whenever the application is started.
|
|
.LP
|
|
The resource specification has two colon-separated parts, a name, and
|
|
a value. The \fIvalue\fP is a string whose format is dependent on the
|
|
resource specified by \fIname\fP. \fIName\fP is constructed by
|
|
appending a resource name to a full widget name.
|
|
.LP
|
|
The full widget name is a list of the name of every ancestor of the
|
|
desired widget separated by periods (.). Each widget also has a class
|
|
associated with it. A class is a type of widget (e.g. Label or
|
|
Scrollbar or Box). Notice that class names, by convention, begin with
|
|
capital letters and instance names begin with lower case letters. The
|
|
class of any widget may be used in place of its name in a resource
|
|
specification. Here are a few examples:
|
|
.IP xman.form.button1 1.5i
|
|
This is a fully specified resource name, and will affect only widgets
|
|
called button1 that are children of widgets called form that are
|
|
children of
|
|
applications named xman. (Note that while typically two widgets that
|
|
are siblings will have different names, it is not prohibited.)
|
|
|
|
.IP Xman.Form.Command 1.5i
|
|
This will match any Command widget that is a child of a Form widget
|
|
that is itself a child of an application of class \fIXman\fP.
|
|
.IP Xman.Form.button1 1.5i
|
|
This is a mixed resource name with both widget names and classes specified.
|
|
.LP
|
|
This syntax allows an application programmer to specify any widget
|
|
in the widget tree. To match more than one widget (for example a user
|
|
may want to make all Command buttons blue), use an asterisk (*)
|
|
instead of a period. When an asterisk is used, any number of widgets
|
|
(including zero) may exist between the two widget names. For example:
|
|
.IP Xman*Command 1.5i
|
|
This matches all Command widgets in the Xman application.
|
|
.IP Foo*button1 1.5i
|
|
This matches any widget in the Foo application that is named \fIbutton1\fP.
|
|
.LP
|
|
The root of all application widget trees is the widget returned by
|
|
\fBXtAppInitialize\fP. Even though this is actually an
|
|
ApplicationShell widget, the toolkit replaces its widget class with the
|
|
class name of the application. The name of this widget is either
|
|
the name used to invoke the application (\fBargv[0]\fP) or the name of
|
|
the application specified using the standard \fI-name\fP command line
|
|
option supported by the \*(xI.
|
|
.LP
|
|
The last step in constructing the resource name is to append the name of
|
|
the resource with either a period or asterisk to the full or partial
|
|
widget name already constructed.
|
|
.IP *foreground:Blue 2.25i
|
|
Specifies that all widgets in all applications will have a foreground
|
|
color of blue.
|
|
.IP Xman*borderWidth:10 2.25i
|
|
Specifies that all widgets in an application whose class is Xman will
|
|
have a border width of 10 (pixels).
|
|
.IP xman.form.button1.label:Testing 2.25i
|
|
Specifies that a particular widget in the xman application will have a
|
|
label named \fITesting\fP.
|
|
.LP
|
|
An exclamation point (!) in the first column of a line indicates
|
|
that the rest of the line should be treated as a comment.
|
|
.LP
|
|
\fBFinal Words\fP
|
|
.LP
|
|
The Resource manager is a powerful tool that can be used very
|
|
effectively to customize \*(tk applications at run time by either the
|
|
application programmer or the user. Some final points to note:
|
|
.IP \(bu 5
|
|
An application programmer may add new resources to their
|
|
application. These resources are associated with the global
|
|
application, and not any particular widget. The \*(tk function used for
|
|
adding the application resources is \fBXtGetApplicationResources\fP.
|
|
.IN "XtGetApplicationResources"
|
|
.IP \(bu 5
|
|
Be careful when creating resource files. Since widgets will
|
|
ignore resources that they do not understand, any spelling
|
|
errors will cause a resource to have no effect.
|
|
.IP \(bu 5
|
|
Only one resource line will match any given resource. There is a set
|
|
of precedence rules, which take the following general stance.
|
|
.ta 10n
|
|
.IP "" 5
|
|
\(bu More specific overrides less specific, thus period always overrides asterisk.
|
|
.IP "" 5
|
|
\(bu Names on the left are more specific and override names on the right.
|
|
.IP "" 5
|
|
\(bu When resource specifications are exactly the same, user defaults
|
|
.br
|
|
will override program defaults.
|
|
.LP
|
|
For a complete explanation of the rules of precedence, and
|
|
other specific topics see \fI\*(xT\fP and \fI\*(xL\fP.
|
|
.NH 4
|
|
Creating Argument Lists
|
|
.IN "argument lists" "" "@DEF@"
|
|
.LP
|
|
To set up an argument list for the inline specification of widget attributes,
|
|
you may use any of the four approaches discussed in this section.
|
|
Each resource name has a global symbol associated with it. This
|
|
global symbol has the form XtN\fIresource name\fP. For example, the
|
|
symbol for ``foreground'' is \fBXtNforeground\fP. For further information,
|
|
see the \fI\*(xT\fP.
|
|
.LP
|
|
Argument are specified by using the following structure:
|
|
.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 is to 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 is convenient for lists that do not need to be computed
|
|
at runtime and makes adding or deleting new elements easy.
|
|
The
|
|
.IN "XtNumber"
|
|
.PN XtNumber
|
|
macro is used to compute the number of elements in the argument list,
|
|
preventing simple programming errors:
|
|
.LP
|
|
.Ds
|
|
XtCreateWidget(\fIname\fP, \fIclass\fP, \fIparent\fP, \fIarglist\fP, XtNumber(\fIarglist\fP));
|
|
.De
|
|
.IN "XtSetArg" "" "@DEF@"
|
|
.LP
|
|
The second approach is to 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:
|
|
.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,
|
|
.IN "XtNumber"
|
|
.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 is to individually set the elements of the
|
|
argument list array:
|
|
.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,
|
|
.IN "XtNumber"
|
|
.PN XtNumber
|
|
would return 10, not 2, and therefore would not be useful.
|
|
.LP
|
|
The fourth approach is to 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,
|
|
.IN "XtNumber"
|
|
.PN XtNumber
|
|
can be used, as in the first approach, for easier code maintenance.
|
|
.NH 2
|
|
Example Programs
|
|
.XS
|
|
Example Programs
|
|
.XE
|
|
.IN "examples"
|
|
.LP
|
|
The best way to understand how to use any programming library is by
|
|
trying some simple examples. A collection of example programs that
|
|
introduces each of the widgets in that Athena widget set, as well as many
|
|
important toolkit programming concepts, is available in the X11R6
|
|
release as distributed by the X Consortium. It can be found in the
|
|
distribution directory \fBcontrib/examples/mit/Xaw\fP, but see your
|
|
site administrator for the exact location of these files on your system.
|
|
See the README file from that directory for a guide to the examples.
|
|
|