Motif Reference Manual for Motif 2.1

Motif Reference Manual for Motif 2.1
THE DEFINITIVE GUIDES TO THE
X WINDOW SYSTEM
VOLUME SIX B
Motif Reference Manual
for Motif 2.1
Open Source Edition
Antony Fountain and Paula Ferguson
Motif Reference Manual, Open Source Edition
by Antony Fountain and Paula Ferguson
December 2001
Copyright  1993, 2000, 2001 O’Reilly & Associates, Inc. and Antony Fountain. This
material may be distributed only subject to the terms and conditions set forth in the
Open Publication License, v1.0 or later (the latest version is presently available at
http://www.opencontent.org/openpub/).
This is a modified version of the Motif Reference Manual, Second Edition, published
by O’Reilly & Associates in February 2000. The source files for the Second Edition can
be found at http://www.oreilly.com/openbook/motif/. A description of the
modifications is contained in the Preface to the Open Source Edition.
Many of the designations used by manufacturers and sellers to distinguish their
products are claimed as trademarks. Where those designations appear in this book,
and O’Reilly & Associates, Inc. was aware of a trademark claim, the designations have
been printed in caps or initial caps.
While every precaution has been taken in the preparation of this book, the publisher
assumes no responsibility for errors or omissions, or for damages resulting from the
use of the information contained herein.
Published by:
Imperial Software Technology Limited
Kings Court
185 Kings Road
Reading
Berkshire RG1 4EX
Tel: +44 118 958 7055
Fax: +44 118 958 9005
email: sales@ist.co.uk
URL: http://www.ist.co.uk
Contents
Preface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . v
Section 1 - Motif Functions and Macros . . . . . . . . . . . . . . . . . . . . . . . . 1
Section 2 - Motif and Xt Widget Classes . . . . . . . . . . . . . . . . . . . . . 557
Section 3 - Mrm Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 961
Section 4 - Mrm Clients . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 999
Section 5 - UIL File Format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1033
Section 6 - UIL Data Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1053
Section 7 - UIL Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1113
Appendix A - Function Summaries . . . . . . . . . . . . . . . . . . . . . . . . . 1125
Appendix B - Data Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1159
Appendix C - Table of Motif Resources . . . . . . . . . . . . . . . . . . . . . 1199
Appendix D Table of UIL Objects . . . . . . . . . . . . . . . . . . . . . . . . . . 1225
Appendix E - New Features in Motif 2.0 and 2.1 . . . . . . . . . . . . . 1233
Motif Reference Manual
iii
Contents
Motif Reference Manual
iv
Preface
Preface to the Open Source Edition
Many thanks to all at O’Reilly and Associates for releasing this, Volume 6B, and the
companion Volume 6A, the Motif Programming Manual, in open source. Both have
been extensively revised for Motif 2.1; this, the Motif Reference Manual, has had
several alterations to the 2nd edition as printed:
•
•
•
•
•
•
all the function prototypes and examples have been converted to strict ANSI format
the UIL sections have been restored
the Xt Session Shell is documented
many bug patches have been folded in
new examples have been added to Motif 2.1 procedure sections
the book sources have been converted from the original troff into FrameMaker and PDF
formats
Removing the UIL portions from the original printed second edition was a hard
decision; the Motif 2.1 toolkit was a much expanded library since previous versions of
the book, and something had to give - the book was over a thousand pages as it was.
However, an electronic copy does not have the same space restrictions as the printed
tome, and so these materials, originally in the Motif 1.2 version of the manual, have
been restored. They also have been reworked for Motif 2.1.
Antony J. Fountain
Preface to the Second Edition
What to put in, and what to leave out, of this update to the Motif Reference Manual
was the hardest decision of all. The guiding principle has been to consider for whom
this material is intended. This is a Programmer’s Reference, and not a Widget Author’s
handbook. Accordingly, those aspects of the new Trait mechanisms which an
application programmer needs to know have been included, but the Xme utilities have
not. Specifying a Trait as a well-defined piece of behaviour which a widget supports,
it is enough to know which traits a Widget Class supports, and how this affects objects
in the widget instance hierarchy. How a Trait is implemented, and which methods are
associated with the given Trait, are generally the domain of the widget author. Hence
it is recorded that the VendorShell holds the XmQTspecifyRenderTableTrait, and that
this means that widget classes further down the widget instance hierarchy inherit
default Render Table information from the VendorShell. This is all that the Application
Programmer needs to know: the rest is silence.
Motif Reference Manual
v
Preface
Conversely, the Motif Input Method utilities have been included. Although mostly
defined originally in the Motif 1.2 release, and although the Motif widget classes
generally handle connections to an Input Method when and where this is required, there
is an important exception. The Motif Drawing Area does not register itself with an Input
Method automatically, and hence anyone who needs to directly implement
internationalized input for this widget class most certainly would need to know about
the XmIm functions. The World does not all speak English: for these reasons, the XmIm
functions are included in the Manual.
A brief note concerning the status of Motif as the premier Unix toolkit. A number of
alternative toolkits have arisen, particularly in the Linux domain, which offer an X-based
windowing system for the Unix, and other, platforms. I refer principally to the likes of
Qt, and GTK+. These on the whole dispense with the Xt layer, in order to provide small,
lightweight GUI components which are, from the application programmer’s perspective,
relatively easy to port to non-Unix domains. Although admirable in many ways, these
suffer from one crucial drawback, precisely because Xt has been excluded: there is no
object component model associated with any of the objects which can be created in an
interface1. Compare and contrast with something like JavaBeans, where a GUI builder
can be designed which can dynamically load and query objects from whatever source,
and from thence inspect the attributes of the object, construct resource panels, and
generate code for the components, all without any external configuration. Based on Xt,
Motif also has this important property: I can in principle dynamically load into my GUI
builder any third party component, construct an internal attribute list, present resource
panels for object configuration to the user, and from there generate source code. Just by
interrogating the widget class. All the commercial GUI builders available for Motif
support this.
The newer alternative Linux toolkits do not have this introspective quality. Writing GUI
builders happens to be what I do for a living: sad to say, I cannot write one for these
toolkits precisely because these is no component model at the object level. Not
surprisingly, no third party component market exists for the toolkits either: there is no
GUI builder into which these components can be dynamically slotted. Each needs the
other, but there is nothing which allows them to talk. In the absence of either a
commercial component market, or a dynamic GUI builder, there remains serious
question marks concerning the scalability of the alternative toolkits, whatever merits
they hold. The only alternatives are to write all the code by hand, or pass control of the
1.True at the moment of writing. It is still true that all the information required to dynamically introspect an object’s entire
resource set, particularly if user-defined and not built-in to the basic set, is not completely forthcoming. Introspecting
third party components remains troublesome for a dynamic GUI builder.
vi
Motif Reference Manual
Preface
application to a private piece of hobbyware which masquerades as a support
environment. Ironically, the advent of Java has cemented Motif: the JDK relies on Motif
for the native implementation on the Unix platform. Until such time as a native toolkit
surfaces which has this important introspective property, Motif remains what it has
long been, the only native toolkit for Unix which supports large scale internationalized
applications.1
About the Motif Toolkit
The Motif toolkit, from the Open Software Foundation (OSF), is based on the X Toolkit
Intrinsics (Xt), which is the standard mechanism on which many of the toolkits written
for the X Window System are based. Xt provides a library of user-interface objects
called widgets and gadgets, which provide a convenient interface for creating and
manipulating X windows, colormaps, events, and other cosmetic attributes of the
display. In short, widgets can be thought of as building blocks that the programmer
uses to construct a complete application.
However, the widgets that Xt provides are generic in nature and impose no userinterface policy whatsoever. Providing the look and feel of an interface is the job of a
user-interface toolkit such as Motif. Motif provides a complete set of widgets that are
designed to implement the application look and feel specified in the Motif Style Guide
and the Motif Application Environment Specification. The Motif toolkit also includes a
library of functions for creating and manipulating the widgets and other aspects of the
user interface.
The Motif toolkit has other components in addition to the widget set and related
functions. Motif provides a User Interface Language (UIL) for describing the initial
state of a user interface. UIL is designed to permit rapid prototyping of the user
interface for an application. The Motif Resource Manager (Mrm) functions provide the
interface between C language application code and UIL. Motif also provides the Motif
Window Manager (mwm). The appearance and behavior of this window manager is
designed to be compatible with the appearance and behavior of the Motif widget set.
About This Manual
This manual contains reference material on the Motif toolkit. This edition is based on
Motif 2.1, which is the latest major release of the Motif toolkit. Motif 1.2 is based on
1.The contents of this paragraph were true at the moment of writing. There is now a commercial GUI builder for the
Linux toolkits; whether it survives in a free software environment remains to be seen. It is still true that the large scale
commercial concerns continue to use Motif for their native Unix toolkit.
Motif Reference Manual
vii
Preface
Release 6 of the Xlib and Xt specifications (X11R6). This release of Motif provides many
new features, including new widget classes and several new functions. In order to cover
all of the material, it became necessary to split Volume Six into two separate manuals, a
programming manual and a reference manual. Volume Six A is the Motif Programming
Manual and Volume Six B is the Motif Reference Manual.
This manual is part of the sixth volume in the O’Reilly & Associates X Window System
Series. It includes reference pages for each of the Motif functions and macros, for the
Motif and Xt Intrinsics widget classes, for the Mrm functions, for the Motif clients, and
for the UIL file format, data types, and functions. A permuted index and numerous quick
reference appendices are also provided.
Volume Six B includes reference pages for all of the new functions and widgets in Motif
2.0 and 2.1. When the functionality of an existing routine or widget has changed in Motif
2.0 or 2.1, the reference page explains the differences between the two versions. Volume
Six B also provides a complete set of reference material for UIL and Mrm, which was not
covered in the previous edition.
Volumes Six A and B are designed to be used together. Volume Six A provides a
complete programmer’s guide to the Motif toolkit. Each chapter of the book covers a
particular component of the Motif toolkit. Each chapter includes basic tutorial material
about creating and manipulating the component, intermediate-level information about
the configurable aspects of the component, and any advanced programming topics that
are relevant. The chapters also provide numerous programming examples.
To get the most out of the examples in Volume Six A, you will need the exact calling
sequences of each function from Volume Six B. To understand fully how to use each of
the routines described in Volume Six B, all but the most experienced Motif programmers
will need the explanations and examples in Volume Six A.
While the Motif toolkit is based on Xt, the focus of this manual is on Motif itself, not on
the X Toolkit Intrinsics. Reference pages for the Xt widget classes are included here to
provide a complete picture of the widget class hierarchy. Many reference pages mention
related Xt routines, but the functionality of these routines is not described. Detailed
information about Xt is provided by Volume 4, X Toolkit Intrinsics Programming Manual,
Motif Edition, and Volume 5, X Toolkit Intrinsics Reference Manual.
How This Manual is Organized
Volume Six B is designed to make it easy and fast to look up virtually any fact about the
Motif toolkit. It contains reference pages and numerous helpful appendices.
viii
Motif Reference Manual
Preface
The book is organized as follows:
Preface
Describes the organization of the book and the conventions it follows.
Section 1
Motif Functions and Macros, contains reference pages for all of
Motif functions and macros.
Section 2
Motif and Xt Widget Classes, contains reference pages for the
widget classes defined by the Motif toolkit and the X Toolkit Intrinsics.
Section 3
Mrm Functions, contains reference pages for the Motif Resource
Manager functions that are used in conjuctions with the User Interface Language.
Section 4
Motif Clients, contains reference pages for the Motif clients: mwm,
uil, and xmbind.
Section 5
UIL File Format, contains reference pages that describe the file format of a User Interface Language module.
Section 6
UIL Data Types, contains reference pages for the data types supported by the User Interface Language.
Section 7
UIL Functions, contains reference pages for the User Interface Language functions.
Appendix A
Function Summaries, provides quick reference tables that list each
Motif function alphabetically and also by functional groups.
Appendix B
Data Types, lists and explains in alphabetical order the structures,
enumerated types, and other typedefs used for arguments to Motif
and Mrm functions.
Appendix C
Table of Motif Resources, lists all of the resources provided by
Motif and Xt widget classes, along with their types and the classes
that define them.
Appendix D
Table of UIL Objects, lists all of the objects supported by the User
Interface Language, along with their corresponding Motif widget
classes.
Appendix E
New Features in Motif 1.2, lists the new functions, widget classes,
and widget resources in Motif 1.2.
Index
Should help you to find what you need to know.
Motif Reference Manual
ix
Preface
Assumptions
This book assumes that the reader is familiar with the C programming language and
the concepts and architecture of the X Toolkit, which are presented in Volume 4, X
Toolkit Intrinsics Programming Manual, Motif Edition, and Volume 5, X Toolkit Intrinsics
Reference Manual. A basic understanding of the X Window System is also useful. For
some advanced topics, the reader may need to consult Volume 1, Xlib Programming
Manual, and Volume 2, Xlib Reference Manual.
Related Documents
The following books on the X Window System are available from O’Reilly &
Associates, Inc.:
Volume Zero
X Protocol Reference Manual
Volume One
Xlib Programming Manual
Volume Two
Xlib Reference Manual
Volume Three
X Window System User’s Guide, Motif Edition
Volume Four
Edition
X Toolkit Intrinsics Programming Manual, Motif
Volume Five
X Toolkit Intrinsics Reference Manual
Volume Six A
Motif Programming Manual
Volume Seven
ing reference volume.
XView Programming Manual with accompany-
Volume Eight
X Window System Administrator’s Guide
PHIGS Programming Manual
PHIGS Reference Manual
PEXlib Programming Manual
PEXlib Reference Manual
Quick Reference
The X Window System in a Nutshell
Programming Supplement for Release 6 of the X Window System
Conventions Used in This Book
Italic is used for:
Motif Reference Manual
x
Preface
•
•
UNIX pathnames, filenames, program names, user command names, options for user
commands, and variable expressions in syntax sections.
New terms where they are defined.
Constant Width Font is used for:
•
•
•
•
Anything that would be typed verbatim into code, such as examples of source code and
text on the screen.
Variables, data structures (and fields), symbols (defined constants and bit flags), functions,
macros, and a general assortment of anything relating to the C programming language.
All functions relating to Motif, Xt, and Xlib.
Names of subroutines in example programs.
Constant Width Italic Font is used for:
•
Arguments to functions, since they could be typed in code as shown but are arbitrary
names that could be changed.
Helvetica Italic is used for:
•
Titles of examples, figures, and tables.
Boldface is used for:
•
Chapter headings, section headings, and the names of buttons and menus.
We’d Like to Hear From You
We have tested and verified all of the information in this book to the best of our ability,
but you may find that features have changed (or even that we have made mistakes!).
Please let us know about any errors you find, as well as your suggestions for future
editions, by writing:
O’Reilly & Associates, Inc.
103 Morris Street, Suite A
Sebastopol, CA 95472
1-800-998-9938 (in the US or Canada)
1-707-829-0515 (international/local)
1-707-829-0104 (FAX)
Motif Reference Manual
xi
Preface
Acknowledgements
This book developed out of the realization that it would be impossible to update the
first edition of Volume Six to cover Motif 1.2 without dividing the original book into
two books. Dan Heller, David Flanagan, Adrian Nye, and Tim O’Reilly all provided
valuable suggestions on how best to expand the original reference appendices into a
full-fledged reference manual.
The Motif reference pages in this book are based on the reference appendices from the
first edition, which were developed by Daniel Gilly. His work meant that I didn’t have
to start from scratch, and thus saved many hours of toil. The OSF/Motif reference
material also provided a helpful foundation from which to explore the complexities of
the Motif toolkit. Many of the Motif examples in the book were borrowed from the first
edition of Volume Six. These example were written by Dan Heller, although they have
been updated for Motif 1.2
Dave Brennan, of HaL Computer Systems, took on the unenviable task of learning
everything there is to know about UIL and Mrm, so that he could write the UIL
reference material. He did a great job.
Adrian Nye deserves special recognition for freeing me to work on this project, when
I’m sure that he had other projects he would have liked to send my way. I don’t think
either one of us had any idea how involved this update project would become. The
other inhabitants of the "writer’s block" at O’Reilly & Associates, Valerie Quercia,
Linda Mui, and Ellie Cutler, provided support that kept me sane while I was working
on the book. Extra gratitude goes to Linda Mui for her work on the cross references and
the reference tables; her knowledge of various tools prevented me from doing things
the hard way. Tim O’Reilly also provided editorial support that improved the quality
of the reference material.
Special thanks go to the people who worked on the production of this book. The final
form of this book is the work of the staff at O’Reilly & Associates. The authors would
like to thank Chris Reilly for the figures, Ellie Cutler for indexing, Lenny Muellner for
tools support, Eileen Kramer for copy editing and production of the final copy, and
Clairemarie Fisher O’Leary for final proofing and printing. Thanks also to Donna
Woonteiler for her patience in answering my questions and helping me to understand
the production process.
Despite the efforts of all of these people, the authors alone are responsible for any
errors or omissions that remain.
Paula M. Ferguson
Motif Reference Manual
xii
Preface
Acknowledgements to the Motif 2.1 Edition
Many thanks to all at IST who gave me the time and opportunity to perform this work.
I would like to thank all those who reviewed the material, which in a Reference Manual
of this type is a tedious but necessary task: a very big "Thank You" to Andy Bartlett
who took the trouble of sitting down with the Motif sources whilst pouring over every
technical detail, and to Tricia Lovell who reviewed the format at particularly short
notice.
A special thanks also to Richard Offer and Doug Rand from Silicon Graphics, and
Mark Riches for casting expert and independent eyes over the materials. I would also
like to thank Andy Lovell and Derek Lambert for allowing and freeing me up to
perform the task. To the rest of the company, who have had to wait whilst yet another
batch of print jobs ran to completion, all I can say is "Sorry".
A very big “Thank You” indeed to all at O’Reilly for allowing me to undertake this
important task, and especially to Paula Ferguson, my editor: I could not have done this
without you.
But to my wife Emma, who put up with some seriously late nights over a long period,
goes the biggest "Thank You" of all. This would not have happened without any of you,
and I am extremely grateful.
Antony J. Fountain
Acknowledgements to the Open Source Edition
Again, many thanks to all at IST who helped me convert the original troff to Frame and
PDF formats. A special thank you to Denise Huxtable who enlightened me on the
mysteries of Reference Pages, Indexes, and Tables of Contents. Denise also performed
much of the cross-referencing in the manual. Thank you also to Ruth Lambert, who
showed me how to mark up the document sources.
Again, a very big “Thank You” to all at O’Reilly, and Paula Fergusson in particular, for
helping this open source edition come about.
And again, to my wife Emma: a big kiss, and I’ll be home real soon now.
Antony J. Fountain
Motif Reference Manual
xiii
Section 1 - Motif Functions and Macros
This page describes the format and contents of each reference page in Section 1,
which covers the Motif functions and macros.
Name
Function – a brief description of the function.
Synopsis
This section shows the signature of the function: the names and types of the arguments, and the type of the return value. If header file other than <Xm/Xm.h> is
needed to declare the function, it is shown in this section as well.
Inputs
This subsection describes each of the function arguments that pass information to
the function.
Outputs
This subsection describes any of the function arguments that are used to return
information from the function. These arguments are always of some pointer type,
so you should use the C address-of operator (&) to pass the address of the variable in which the function will store the return value. The names of these arguments are sometimes suffixed with _return to indicate that values are returned in
them. Some arguments both supply and return a value; they will be listed in this
section and in the "Inputs" section above. Finally, note that because the list of
function arguments is broken into "Input" and "Output" sections, they do not
always appear in the same order that they are passed to the function. See the
function signature for the actual calling order.
Returns
This subsection explains the return value of the function, if any.
Availability
This section appears for functions that were added in Motif 2.0 and later, and also
for functions that are now superseded by other, preferred, functions.
Description
This section explains what the function does and describes its arguments and
return value. If you’ve used the function before and are just looking for a
refresher, this section and the synopsis above should be all you need.
Usage
This section appears for most functions and provides less formal information
about the function: when and how you might want to use it, things to watch out
for, and related functions that you might want to consider.
Motif Reference Manual
1
Motif Functions and Macros
Example
This section appears for some of the most commonly used Motif functions, and
provides an example of their use.
Structures
This section shows the definition of any structures, enumerated types, typedefs,
or symbolic constants used by the function.
Procedures
This section shows the syntax of any prototype procedures used by the function.
See Also
This section refers you to related functions, widget classes, and clients. The numbers in parentheses following each reference refer to the sections of this book in
which they are found.
2
Motif Reference Manual
Motif Functions and Macros
XmActivateProtocol
Name
XmActivateProtocol – activate a protocol.
Synopsis
#include <Xm/Protocols.h>
void XmActivateProtocol (Widget shell, Atom property, Atom protocol)
Inputs
shell
property
protocol
- Specifies the widget associated with the protocol property.
- Specifies the property that holds the protocol data.
- Specifies the protocol atom.
Description
XmActivateProtocol() activates the specified protocol. If the shell is realized, XmActivateProtocol() updates its protocol handlers and the specified
property. If the protocol is active, the protocol atom is stored in property; if the
protocol is inactive, the protocol atom is not stored in property.
Usage
A protocol is a communication channel between applications. Protocols are simply atoms, stored in a property on the top-level shell window for the application.
XmActivateProtocol() makes the shell able to respond to ClientMessage
events that contain the specified protocol. Before you can activate a protocol, the
protocol must be added to the shell with XmAddProtocols(). Protocols are
automatically activated when they are added. The inverse routine is XmDeactivateProtocol().
See Also
XmActivateWMProtocol(1), XmAddProtocols(1) XmDeactivateProtocol(1), XmInternAtom(1), VendorShell(2).
Motif Reference Manual
3
XmActivateWMProtocol
Motif Functions and Macros
Name
XmActivateWMProtocol – activate the XA_WM_PROTOCOLS protocol.
Synopsis
#include <Xm/Protocols.h>
void XmActivateWMProtocol (Widget shell, Atom protocol)
Inputs
shell
protocol
- Specifies the widget associated with the protocol property.
- Specifies the protocol atom.
Description
XmActivateWMProtocol() is a convenience routine that calls XmActivateProtocol() with property set to XA_WM_PROTOCOL, the window
manager protocol property.
Usage
The property XA_WM_PROTOCOLS is a set of predefined protocols for communication between clients and window managers. Before you can activate the
protocols, they must be added to the shell with XmAddProtocols() or XmAddWMProtocols(). Protocols are automatically activated when they are added.
The inverse routine is XmDeactivateWMProtocol().
See Also
XmActivateProtocol(1), XmAddProtocols(1),
XmAddWMProtocols(1), XmDeactivateWMProtocol(1),
XmInternAtom(1), VendorShell(2).
4
Motif Reference Manual
Motif Functions and Macros
XmAddProtocolCallback
Name
XmAddProtocolCallback – add client callbacks to a protocol.
Synopsis
#include <Xm/Protocols.h>
void XmAddProtocolCallback ( Widget
Atom
Atom
XtCallbackProc
XtPointer
Inputs
shell
property
protocol
callback
closure
shell,
property,
protocol,
callback,
closure)
- Specifies the widget associated with the protocol property.
- Specifies the property that holds the protocol data.
- Specifies the protocol atom.
- Specifies the procedure to invoke when the protocol message
is received.
- Specifies any client data that is passed to the callback.
Description
XmAddProtocolCallback() adds client callbacks to a protocol. The routine verifies that the protocol is registered, and if it is not, it calls XmAddProtocols().
XmAddProtocolCallback() adds the callback to the internal list of callbacks, so
that it is called when the corresponding client message is received.
Usage
A protocol is a communication channel between applications. Protocols are simply atoms, stored in a property on the top-level shell window for the application.
To communicate using a protocol, a client sends a ClientMessage event containing a property and protocol, and the receiving client responds by calling the associated protocol callback routine. XmAddProtocolCallback() allows you to
register these callback routines.
See Also
XmAddProtocols(1), XmAddWMProtocolCallback(1),
XmInternAtom(1), VendorShell(2).
Motif Reference Manual
5
XmAddProtocols
Motif Functions and Macros
Name
XmAddProtocols – add protocols to the protocol manager.
Synopsis
#include <Xm/Protocols.h>
void XmAddProtocols (Widget shell, Atom property, Atom *protocols, Cardinal
num_protocols)
Inputs
shell
property
protocols
Specifies the widget associated with the protocol property.
Specifies the property that holds the protocol data.
Specifies a list of protocol atoms.
num_protocols Specifies the number of atoms in protocols.
Description
XmAddProtocols() registers a list of protocols to be stored in the specified
property of the specified shell widget. The routine adds the protocols to the protocol manager and allocates the internal tables that are needed for the protocol.
Usage
A protocol is a communication channel between applications. Protocols are simply atoms, stored in a property on the top-level shell window for the application.
XmAddProtocols() allows you to add protocols that can be understood by
your application. The inverse routine is XmRemoveProtocols(). To communicate using a protocol, a client sends a ClientMessage event containing a property and protocol, and the receiving client responds by calling the associated
protocol callback routine. Use XmAddProtocolCallback() to add a callback function to be executed when a client message event containing the specified protocol atom is received.
See Also
XmAddProtocolCallback(1), XmAddWMProtocols(1),
XmInternAtom(1), XmRemoveProtocols(1), VendorShell(2).
6
Motif Reference Manual
Motif Functions and Macros
XmAddTabGroup
Name
XmAddTabGroup – add a widget to a list of tab groups.
Synopsis
void XmAddTabGroup (Widget tab_group)
Inputs
tab_group
Specifies the widget to be added.
Availability
In Motif 1.1, XmAddTabGroup() is obsolete. It has been superceded by setting
XmNnavigationType to XmEXCLUSIVE_TAB_GROUP.
Description
XmAddTabGroup() makes the specified widget a separate tab group. This routine is retained for compatibility with Motif 1.0 and should not be used in newer
applications. If traversal behavior needs to be changed, this should be done
directly by setting the XmNnavigationType resource, which is defined by Manager and Primitive.
Usage
A tab group is a group of widgets that can be traversed using the keyboard rather
than the mouse. Users move from widget to widget within a single tab group by
pressing the arrow keys. Users move between different tab groups by pressing
the Tab or Shift-Tab keys. If the tab_group widget is a manager, its children are
all members of the tab group (unless they are made into separate tab groups). If
the widget is a primitive, it is its own tab group. Certain widgets must not be
included with other widgets within a tab group. For example, each List, Scrollbar, OptionMenu, or multi-line Text widget must be placed in a tab group by
itself, since these widgets define special behavior for the arrow or Tab keys,
which prevents the use of these keys for widget traversal. The inverse routine is
XmRemoveTabGroup().
See Also
XmGetTabGroup(1), XmRemoveTabGroup(1),
XmManager(2), XmPrimitive(2).
Motif Reference Manual
7
XmAddToPostFromList
Motif Functions and Macros
Name
XmAddToPostFromList – make a menu accessible from a widget.
Synopsis
#include <Xm/RowColumn.h>
void XmAddToPostFromList (Widget menu, Widget widget)
Inputs
menu
widget
Specifies a menu widget
Specifies the widget from which to make menu accessible
Availability
In Motif 2.0 and later, the function prototype is removed from RowColumn.h,
although there is otherwise no indication that the procedure is obsolete.
Description
XmAddToPostFromList() is a convenience function which makes menu
accessible from widget. There is no limit to how many widgets may share the
same menu. The event sequence required to popup the menu is the same in each
widget context.
Usage
Rather than creating a new and identical hierarchy for each context in which a
pulldown or popup menu is required, a single menu can be created and shared. If
the type of the menu is XmMENU_PULLDOWN, the value of the XmNsubMenuId resource of widget is set to menu. If the type of the menu is
XmMENU_POPUP, button and key press event handlers are added to widget in
order to post the menu.
There are implicit assumptions that widget is a CascadeButton or CascadeButtonGadget when menu is XmMENU_PULLDOWN, and that widget is not a
Gadget when menu is XmMENU_POPUP. These are not checked by the procedure.
See Also
XmGetPostedFromWidget(1), XmRemoveFromPostFromList(1),
XmCascadeButton(2), XmCascadeButtonGadget(2), XmGadget(2),
XmPopupMenu(2), XmPulldownMenu(2), XmRowColumn(2).
8
Motif Reference Manual
Motif Functions and Macros
XmAddWMProtocolCallback
Name
XmAddWMProtocolCallback – add client callbacks to an
XA_WM_PROTOCOLS protocol.
Synopsis
#include <Xm/Protocols.h>
void XmAddWMProtocolCallback ( Widget
Atom
XtCallbackProc
XtPointer
Inputs
shell
protocol
callback
closure
shell,
protocol,
callback,
closure)
Specifies the widget associated with the protocol property.
Specifies the protocol atom.
Specifies the procedure to invoke when the protocol message
is received.
Specifies any client data that is passed to the callback.
Description
XmAddWMProtocolCallback() is a convenience routine that calls XmAddProtocolCallback() with property set to XA_WM_PROTOCOL, the window manager protocol property.
Usage
The property XA_WM_PROTOCOLS is a set of predefined protocols for communication between clients and window managers. To communicate using a protocol, a client sends a ClientMessage event containing a property and protocol,
and the receiving client responds by calling the associated protocol callback routine. XmAddWMProtocolCallback() allows you to register these callback
routines with the window manager protocol property. The inverse routine is
XmRemoveWMProtocolCallback().
Example
The following code fragment shows the use of XmAddWMProtocolCallback() to save the state of an application using the WM_SAVE_YOURSELF
protocol:
Atom wm_save_yourself;
wm_save_yourself = XInternAtom1 (XtDisplay
(toplevel),
1.From Motif 2.0, XmInternAtom() is marked for deprecation.
Motif Reference Manual
9
XmAddWMProtocolCallback
Motif Functions and Macros
"WM_SAVE_YOURSELF
", False);
XmAddWMProtocols (toplevel, &wm_save_yourself, 1);
XmAddWMProtocolCallback (toplevel,
wm_save_yourself,
save_state, toplevel);
save_state is a callback routine that saves the state of the application.
See Also
XmAddProtocolCallback(1), XmInternAtom(1),
XmRemoveWMProtocolCallback(1), VendorShell(2).
10
Motif Reference Manual
Motif Functions and Macros
XmAddWMProtocols
Name
XmAddWMProtocols – add the XA_WM_PROTOCOLS protocols to the protocol manager.
Synopsis
#include <Xm/Protocols.h>
void XmAddWMProtocols (Widget shell, Atom *protocols, Cardinal
num_protocols)
Inputs
shell
protocols
num_protocols
Specifies the widget associated with the protocol property.
Specifies a list of protocol atoms.
Specifies the number of atoms in protocols.
Description
XmAddWMProtocols() is a convenience routine that calls XmAddProtocols()
with property set to XA_WM_PROTOCOL, the window manager protocol property.
Usage
The property XA_WM_PROTOCOLS is a set of predefined protocols for communication between clients and window managers. XmAddWMProtocols()
allows you to add this protocol so that it can be understood by your application.
The inverse routine is XmRemoveWMProtocols(). To communicate using a
protocol, a client sends a ClientMessage event containing a property and protocol, and the receiving client responds by calling the associated protocol callback
routine. Use XmAddWMProtocolCallback() to add a callback function to
be executed when a client message event containing the specified protocol atom
is received.
Example
The following code fragment shows the use of XmAddWMProtocols() to add the
window manager protocols, so that the state of an application can be saved using the
WM_SAVE_YOURSELF protocol:
Atom wm_save_yourself;
wm_save_yourself = XmInternAtom (XtDisplay
(toplevel),
"WM_SAVE_YOURSELF
", False);
XmAddWMProtocols (toplevel, &wm_save_yourself, 1);
Motif Reference Manual
11
XmAddWMProtocols
Motif Functions and Macros
XmAddWMProtocolCallback (toplevel,
wm_save_yourself,
save_state, toplevel);
save_state is a callback routine that saves the state of the application.
See Also
XmAddProtocols(1), XmAddWMProtocolCallback(1),
XmInternAtom(1), XmRemoveWMProtocols(1), VendorShell(2).
12
Motif Reference Manual
Motif Functions and Macros
XmCascadeButtonHighlight
Name
XmCascadeButtonHighlight, XmCascadeButtonGadgetHighlight – set the highlight state of a CascadeButton.
Synopsis
#include <Xm/CascadeB.h>
void XmCascadeButtonHighlight (Widget cascadeButton, Boolean highlight)
#include <Xm/CascadeBG.h>
void XmCascadeButtonGadgetHighlight (Widget cascadeButton, Boolean highlight)
Inputs
cascadeButton
highlight
Specifies the CascadeButton or CascadeButtonGadget.
Specifies the highlight state.
Description
XmCascadeButtonHighlight() sets the state of the shadow highlight
around the specified cascadeButton, which can be a CascadeButton or a CascadeButtonGadget.
XmCascadeButtonGadgetHighlight() sets the highlight state of the
specified cascadeButton, which must be a CascadeButtonGadget.
Both routines draw the shadow if highlight is True and erase the shadow if highlight is False.
Usage
CascadeButtons do not normally display a shadow like other buttons, so the highlight shadow is often used to show that the button is armed. XmCascadeButtonHighlight() and XmCascadeButtonGadgetHighlight() provide a
way for you to cause the shadow to be displayed.
See Also
XmCascadeButton(2), XmCascadeButtonGadget(2).
Motif Reference Manual
13
XmChangeColor
Motif Functions and Macros
Name
XmChangeColor – update the colors for a widget.
Synopsis
void XmChangeColor (Widget widget, Pixel background)
Inputs
widget
background
Specifies the widget whose colors are to be changed.
Specifies the background color.
Description
XmChangeColor() changes all of the colors for the specified widget based on
the new background color. The routine recalculates the foreground color, the
select color, the arm color, the trough color, and the top and bottom shadow
colors and updates the corresponding resources for the widget.
Usage
XmChangeColor() is a convenience routine for changing all of the colors for a
widget, based on the background color. Without the routine, an application would
have to call XmGetColors() to get the new colors and then set the XmNforeground, XmNtopShadowColor, XmNbottomShadowColor, XmNtroughColor,
XmNarmColor, XmNselectColor resources for the widget with XtSetValues(). The XmNhighlightColor is set to the value of the XmNforeground.
XmChangeColor() calls XmGetColors() internally to allocate the required
pixels. In Motif 1.2 and earlier, this uses the default color calculation procedure
unless a customized color calculation procedure has been set with XmSetColorCalculation(). In Motif 2.0 and later, color calculation can be specified on a per-screen basis, and any specified XmNcolorCalculationProc
procedure of the XmScreen object associated with the widget is used in preference.
See Also
XmGetColorCalculation(1), XmGetColors(1),
XmSetColorCalculation(1), XmScreen(2).
14
Motif Reference Manual
Motif Functions and Macros
XmClipboardBeginCopy
Name
XmClipboardBeginCopy – set up storage for a clipboard copy operation.
Synopsis
#include <Xm/CutPaste.h>
int XmClipboardBeginCopy ( Display
Window
XmString
Widget
VoidProc
long
Inputs
display
window
clip_label
widget
callback
Outputs
item_id
*display,
window,
clip_label,
widget,
callback,
*item_id)
Specifies a connection to an X server; returned from XOpenDisplay() or XtDisplay().
Specifies a window ID that identifies the client to the clipboard.
Specifies a label that is associated with the data item.
Specifies the widget that receives messages requesting data that has
been passed by name.
Specifies the callback function that is called when the clipboard
needs data that has been passed by name.
Returns the ID assigned to the data item.
Returns
ClipboardSuccess on success or ClipboardLocked if the clipboard is locked by
another application.
Description
XmClipboardBeginCopy() is a convenience routine that calls XmClipboardStartCopy() with identical arguments and with a timestamp of CurrentTime.
Usage
XmClipboardBeginCopy() can be used to start a normal copy operation or a
copy-by-name operation. In order to pass data by name, the widget and callback
arguments to XmClipboardBeginCopy() must be specified.
Procedures
The VoidProc has the following format:
typedef void (*VoidProc) (Widget widget, int *data_id, int *private_id, int
*reason)
Motif Reference Manual
15
XmClipboardBeginCopy
Motif Functions and Macros
The VoidProc takes four arguments. The first argument, widget, is the widget
passed to the callback routine, which is the same widget as passed to XmClipboardBeginCopy(). The data_id argument is the ID of the data item that is
returned by XmClipboardCopy() and private_id is the private data passed to
XmClipboardCopy().
The reason argument takes the value XmCR_CLIPBOARD_DATA_REQUEST,
which indicates that the data must be copied to the clipboard, or
XmCR_CLIPBOARD_DATA_DELETE, which indicates that the client can
delete the data from the clipboard. Although the last three parameters are pointers
to integers, the values are read-only and changing them has no effect.
See Also
XmClipboardCancelCopy(1), XmClipboardCopy(1),
XmClipboardCopyByName(1), XmClipboardEndCopy(1),
XmClipboardStartCopy(1).
16
Motif Reference Manual
Motif Functions and Macros
XmClipboardCancelCopy
Name
XmClipboardCancelCopy – cancel a copy operation to the clipboard.
Synopsis
#include <Xm/CutPaste.h>
int XmClipboardCancelCopy (Display *display, Window window, long item_id)
Inputs
display
Specifies a connection to an X server; returned from XOpenDisplay() or XtDisplay().
window
Specifies a window ID that identifies the client to the clipboard.
item_id
Specifies the ID of the data item.
Returns
ClipboardSuccess on success, ClipboardLocked if the clipboard is locked by
another application, or ClipboardFail on failure.
Description
XmClipboardCancelCopy() cancels the copy operation that is in progress
and frees temporary storage that has been allocated for the operation. The function returns ClipboardFail if XmClipboardStartCopy() has not been called
or if the data item has too many formats.
Usage
A call to XmClipboardCancelCopy() is valid only between calls to
XmClipboardStartCopy() and XmClipboardEndCopy(). XmClipboardCancelCopy() can be called instead of XmClipboardEndCopy()
when you need to terminate a copying operation before it completes. If you have
previously locked the clipboard, XmClipboardCancelCopy() unlocks it, so
you should not call XmClipboardUnlock().
See Also
XmClipboardBeginCopy(1), XmClipboardCopy(1),
XmClipboardEndCopy(1), XmClipboardStartCopy(1).
Motif Reference Manual
17
XmClipboardCopy
Motif Functions and Macros
Name
XmClipboardCopy – copy a data item to temporary storage for later copying to
the clipboard.
Synopsis
#include <Xm/CutPaste.h>
int XmClipboardCopy ( Display
Window
long
char
XtPointer
unsigned long
long
long
*display,
window,
item_id,
*format_name,
buffer,
length,
private_id,
*data_id)
Inputs
display
Specifies a connection to an X server; returned from XOpenDisplay() or XtDisplay().
window
Specifies a window ID that identifies the client to the clipboard.
item_id
Specifies the ID of the data item.
format_name
Specifies the name of the format of the data item.
buffer
Specifies the buffer from which data is copied to the clipboard.
length
Specifies the length of the data being copied to the clipboard.
private_id
Specifies the private data that is stored with the data item.
Outputs
data_id
Returns an ID for a data item that is passed by name.
Returns
ClipboardSuccess on success, ClipboardLocked if the clipboard is locked by
another application, or ClipboardFail on failure.
Description
XmClipboardCopy() copies the data item specified by buffer to temporary
storage. The data item is moved to the clipboard data structure when XmClipboardEndCopy() is called. The item_id is the ID of the data item returned by
XmClipboardStartCopy() and format_name is a string that describes the
type of the data.
18
Motif Reference Manual
Motif Functions and Macros
XmClipboardCopy
Since the data item is not actually stored in the clipboard until XmClipboardEndCopy() is called, multiple calls to XmClipboardCopy() add data item
formats to the same data item or will append data to an existing format. The function returns ClipboardFail if XmClipboardStartCopy() has not been called
or if the data item has too many formats.
Usage
XmClipboardCopy() is called between calls to XmClipboardStartCopy() and XmClipboardEndCopy(). If you need to make multiple calls to
XmClipboardCopy() to copy a large amount of data, you should call
XmClipboardLock() to lock the clipboard for the duration of the copy operation.
When there is a large amount of clipboard data and the data is unlikely to be
retrieved, it can be copied to the clipboard by name. Since the data itself is not
copied to the clipboard until it is requested with a retrieval operation, copying by
name can improve performance. To pass data by name, call XmClipboardCopy() with buffer specified as NULL. A unique number is returned in data_id
that identifies the data item for later use. When another application requests data
that has been passed by name, a callback requesting the actual data will be sent to
the application that owns the data and the owner must then call XmClipboardCopyByName() to transfer the data to the clipboard. Once data that is passed by
name has been deleted from the clipboard, a callback notifies the owner that the
data is no longer needed.
Example
The following callback shows the sequence of calls needed to copy data to the
clipboard:
void to_clipbd ( Widget
widget,
XtPointer client_data,
XtPointer call_data)
{
long
item_id = 0;
int
status;
XmString clip_label;
char
buffer[32];
Display
*dpy
Window
window = XtWindowOfObject (widget);
Motif Reference Manual
= XtDisplayOfObject (widget);
19
XmClipboardCopy
Motif Functions and Macros
char
*data
= (char *) client_data;
(void) sprintf (buffer, "%s", data);
clip_label = XmStringCreateLocalized ("Data");
/* start a copy; retry until unlocked */
do
status = XmClipboardStartCopy (dpy, window,
clip_label,
CurrentTime,
NULL, NULL,
&item_id);
while (status == ClipboardLocked);
XmStringFree (clip_label);
/* copy the data; retry until unlocked */
do {
status = XmClipboardCopy (dpy, window,
item_id, "STRING",
(XtPointer) buffer,
(unsigned long) strlen
(buffer) + 1,
(long) 0, (long *) 0);
} while (status == ClipboardLocked);
/* end the copy; retry until unlocked */
do
status = XmClipboardEndCopy (dpy, window,
item_id);
while (status == ClipboardLocked);
}
See Also
XmClipboardBeginCopy(1), XmClipboardCancelCopy(1),
XmClipboardCopyByName(1), XmClipboardEndCopy(1),
XmClipboardStartCopy(1).
20
Motif Reference Manual
Motif Functions and Macros
XmClipboardCopyByName
Name
XmClipboardCopyByName – copy a data item passed by name.
Synopsis
#include <Xm/CutPaste.h>
int XmClipboardCopyByName (
Display
Window
long
XtPointer
unsigned long
long
*display,
window,
data_id,
buffer,
length,
private_id)
Inputs
display
Specifies a connection to an X server; returned from XOpenDisplay() or XtDisplay().
window
Specifies a window ID that identifies the client to the clipboard.
data_id
Specifies the ID number assigned to the data item by XmClipboardCopy().
buffer
Specifies the buffer from which data is copied to the clipboard.
length
Specifies the length of the data being copied to the clipboard.
private_id
Specifies the private data that is stored with the data item.
Returns
ClipboardSuccess on success or ClipboardLocked if the clipboard is locked by
another application.
Description
XmClipboardCopyByName() copies the actual data to the clipboard for a data
item that has been previously passed by name. The data that is copied is specified
by buffer. The data_id is the ID assigned to the data item by XmClipboardCopy().
Usage
XmClipboardCopyByName() is typically used for incremental copying; new
data is appended to existing data with each call to XmClipboardCopyByName(). If you need to make multiple calls to XmClipboardCopyByName()
to copy a large amount of data, you should call XmClipboardLock() to lock
the clipboard for the duration of the copy operation.
Copying by name improves performance when there is a large amount of clipboard data and when this data is likely never to be retrieved, since the data itself
is not copied to the clipboard until it is requested with a retrieval operation. Data
is passed by name when XmClipboardCopy() is called with a buffer value of
NULL. When a client requests the data passed by name, the callback registered
Motif Reference Manual
21
XmClipboardCopyByName
Motif Functions and Macros
by XmClipboardStartCopy() is invoked. See XmClipboardStartCopy() for more information about the format of the callback. This callback calls
XmClipboardCopyByName() to copy the actual data to the clipboard.
Example
The following XmCutPasteProc callback shows the use of XmClipboardCopyByName() to copy data passed by name:
void copy_by_name ( Widget widget,
long
*data_id,
long
*private_id;
int
*reason)
{
Display *dpy
= XtDisplay (toplevel);
Window
window = XtWindow (toplevel);
int
status;
char
buffer[32];
if (*reason == XmCR_CLIPBOARD_DATA_REQUEST) {
(void) sprintf (buffer, "stuff");
do
status = XmClipboardCopyByName (dpy, window, *data_id,
(XtPointer) buffer,
(unsigned long)
strlen (buffer)+1,
*private_id);
while (status != ClipboardSuccess);
}
See Also
XmClipboardBeginCopy(1), XmClipboardCopy(1),
XmClipboardEndCopy(1), XmClipboardStartCopy(1).
22
Motif Reference Manual
Motif Functions and Macros
XmClipboardEndCopy
Name
XmClipboardEndCopy – end a copy operation to the clipboard.
Synopsis
#include <Xm/CutPaste.h>
int XmClipboardEndCopy (Display *display, Window window, long item_id)
Inputs
display
Specifies a connection to an X server; returned from XOpenDisplay() or XtDisplay().
window
Specifies a window ID that identifies the client to the clipboard.
item_id
Specifies the ID of the data item.
Returns
ClipboardSuccess on success, ClipboardLocked if the clipboard is locked by
another application, or ClipboardFail on failure.
Description
XmClipboardEndCopy() locks the clipboard, places data that has been accumulated by calling XmClipboardCopy() into the clipboard data structure, and
then unlocks the clipboard. The item_id is the ID of the data item returned by
XmClipboardStartCopy(). The function returns ClipboardFail if XmClipboardStartCopy() has not been called previously.
Usage
XmClipboardEndCopy() frees temporary storage that was allocated by
XmClipboardStartCopy(). XmClipboardStartCopy() must be called
before XmClipboardEndCopy(), which does not need to be called if
XmClipboardCancelCopy() has already been called.
Example
The following callback shows the sequence of calls needed to copy data to the
clipboard:
static void to_clipbd ( Widget
widget,
XtPointer
client_data,
XtPointer
call_data)
{
long
item_id = 0;
int
status;
XmString clip_label;
char
buffer[32];
Display *dpy
= XtDisplayOfObject (widget);
Window
window = XtWindowOfObject (widget);
Motif Reference Manual
23
XmClipboardEndCopy
char
Motif Functions and Macros
*data
= (char *) client_data;
(void) sprintf (buffer, "%s", data);
clip_label = XmStringCreateLocalized ("Data");
/* start a copy; retry until unlocked */
do
status = XmClipboardStartCopy (dpy, window,
clip_label,
CurrentTime,
NULL, NULL,
&item_id);
while (status == ClipboardLocked);
XmStringFree (clip_label);
/* copy the data; retry until unlocked */
do
status = XmClipboardCopy (dpy, window,
item_id, "STRING",
(XtPointer) buffer,
(unsigned
long)strlen(buffer)+1,
0, NULL);
while (status == ClipboardLocked);
/* end the copy; retry until unlocked */
do
status = XmClipboardEndCopy (dpy, window,
item_id);
while (status == ClipboardLocked);
}
See Also
XmClipboardBeginCopy(1), XmClipboardCancelCopy(1),
XmClipboardCopy(1), XmClipboardCopyByName(1),
XmClipboardStartCopy(1).
24
Motif Reference Manual
Motif Functions and Macros
XmClipboardEndRetrieve
Name
XmClipboardEndRetrieve – end a copy operation from the clipboard.
Synopsis
#include <Xm/CutPaste.h>
int XmClipboardEndRetrieve (Display *display, Window window)
Inputs
display
Specifies a connection to an X server; returned from XOpenDisplay() or XtDisplay().
window
Specifies a window ID that identifies the client to the clipboard.
Returns
ClipboardSuccess on success or ClipboardLocked if the clipboard is locked by
another application.
Description
XmClipboardEndRetrieve() ends the incremental copying of data from the clipboard.
Usage
A call to XmClipboardEndRetrieve() is preceded by a call to XmClipboardStartRetrieve(), which begins the incremental copy, and calls to
XmClipboardRetrieve(), which incrementally retrieve the data items from
clipboard storage. XmClipboardStartRetrieve() locks the clipboard and
it remains locked until XmClipboardEndRetrieve() is called.
Example
The following code fragment shows the sequence of calls needed to perform an
incremental retrieve. Note that this code does not store the data as it is retrieved:
int
status;
unsigned long received;
char
buffer[32];
Display
*dpy
= XtDisplayOfObject (widget);
Window
window = XtWindowOfObject (widget);
do
status = XmClipboardStartRetrieve (dpy, window,
CurrentTime);
while (status == ClipboardLocked);
do {
/* retrieve data from clipboard */
status = XmClipboardRetrieve (dpy, window,
Motif Reference Manual
25
XmClipboardEndRetrieve
Motif Functions and Macros
"STRING",
(XtPointer) buffer,
(unsigned long)
sizeof (buffer),
&received,
(long *) 0);
} while (status == ClipboardTruncate);
status = XmClipboardEndRetrieve (dpy, window);
See Also
XmClipboardRetrieve(1), XmClipboardStartRetrieve(1).
26
Motif Reference Manual
Motif Functions and Macros
XmClipboardInquireCount
Name
XmClipboardInquireCount – get the number of data item formats available on
the clipboard.
Synopsis
#include <Xm/CutPaste.h>
int XmClipboardInquireCount (Display
Window
int
unsigned long
*display,
window,
*count,
*max_length)
Inputs
display
Specifies a connection to an X server; returned from XOpenDisplay() or XtDisplay().
window
Specifies a window ID that identifies the client to the clipboard.
Outputs
count
the clipboard.
max_length
Returns the number of data item formats available for the data on
Returns the maximum length of data item format names.
Returns
ClipboardSuccess on success, ClipboardLocked if the clipboard is locked by
another application, or ClipboardNoData if there is no data on the clipboard.
Description
XmClipboardInquireCount() returns the number of data formats available
for the current clipboard data item and the length of its longest format name. The
count includes the formats that were passed by name. If there are no formats
available, count is 0 (zero).
Usage
To inquire about the formats of the data on the clipboard, you use XmClipboardInquireCount() and XmClipboardInquireFormat() in conjunction. XmClipboardInquireCount() returns the number of formats for
the data item and XmClipboardInquireFormat() allows you to iterate
through all of the formats.
See Also
XmClipboardInquireFormat(1).
Motif Reference Manual
27
XmClipboardInquireFormat
Motif Functions and Macros
Name
XmClipboardInquireFormat – get the specified clipboard data format name.
Synopsis
#include <Xm/CutPaste.h>
int XmClipboardInquireFormat (
Display
Window
int
XtPointer
unsigned long
unsigned long
*display,
window,
index,
format_name_buf,
buffer_len,
*copied_len)
Inputs
display
Specifies a connection to an X server; returned from XOpenDisplay() or XtDisplay().
window
Specifies a window ID that identifies the client to the clipboard.
index
Specifies the index of the format name to retrieve.
buffer_len
Specifies the length of format_name_buf in bytes.
Outputs
format_name_buf
copied_len
format_name_buf.
Returns the format name.
Returns the length (in bytes) of the string copied to
Returns
ClipboardSuccess on success, ClipboardLocked if the clipboard is locked by
another application, ClipboardTruncate if format_name_buf is not long enough
to hold the returned data, or ClipboardNoData if there is no data on the clipboard.
Description
XmClipboardInquireFormat() returns a format name for the current data
item in the clipboard. The format name returned is specified by index, where 1
refers to the first format. If index exceeds the number of formats for the data item,
then XmClipboardInquireFormat() returns a value of 0 (zero) in the
copied_len argument. XmClipboardInquireFormat() returns the format
name in the format_name_buf argument. This argument is a buffer of a fixed
length that is allocated by the programmer. If the buffer is not large enough to
hold the format name, the routine copies as much of the format name as will fit in
the buffer and returns ClipboardTruncate.
28
Motif Reference Manual
Motif Functions and Macros
XmClipboardInquireFormat
Usage
To inquire about the formats of the data on the clipboard, you use XmClipboardInquireCount() and XmClipboardInquireFormat() in conjunction. XmClipboardInquireCount() returns the number of formats for
the data item and XmClipboardInquireFormat() allows you to iterate
through all of the formats.
See Also
XmClipboardInquireCount(1).
Motif Reference Manual
29
XmClipboardInquireLength
Motif Functions and Macros
Name
XmClipboardInquireLength – get the length of the data item on the clipboard.
Synopsis
#include <Xm/CutPaste.h>
int XmClipboardInquireLength ( Display
Window
char
unsigned long
*display,
window,
*format_name,
*length)
Inputs
display
Specifies a connection to an X server; returned from XOpenDisplay() or XtDisplay().
window
Specifies a window ID that identifies the client to the clipboard.
format_name
Specifies the format name for the data.
Outputs
length
Returns the length of the data item for the specified format.
Returns
ClipboardSuccess on success, ClipboardLocked if the clipboard is locked by
another application, or ClipboardNoData if there is no data on the clipboard for
the requested format.
Description
XmClipboardInquireLength() returns the length of the data stored under
the specified format_name for the current clipboard data item. If no data is found
corresponding to format_name or if there is no item on the clipboard, XmClipboardInquireLength() returns a length of 0 (zero). When a data item is
passed by name, the length of the data is assumed to be passed in a call to
XmClipboardCopy(), even though the data has not yet been transferred to the
clipboard.
Usage
XmClipboardInquireLength() provides a way for an application to find
out how much data is on the clipboard, so that it can allocate a buffer that is large
enough to retrieve the data with one call to XmClipboardRetrieve().
Example
The following code fragment demonstrates how to use XmClipboardInquireLength() to retrieve all of the data on the clipboard:
int
status;
unsigned long recvd, length;
30
Motif Reference Manual
Motif Functions and Macros
char
Display
Window
XmClipboardInquireLength
*data;
*dpy
= XtDisplayOfObject (widget);
window = XtWindowOfObject (widget);
do
status = XmClipboardInquireLength (dpy, window,
"STRING",
&length);
while (status == ClipboardLocked);
if (length != 0) {
data = XtMalloc ((unsigned) (length+1) * sizeof
(char));
do
status = XmClipboardRetrieve (dpy, window,
"STRING",
(XtPointer)
data,
(unsigned long)
length+1,
&recvd, (long *)
0);
while (status == ClipboardLocked);
if (status != ClipboardSuccess || recvd !=
length) {
XtWarning ("Failed to receive all clipboard
data");
}
}
See Also
XmClipboardRetrieve(1).
Motif Reference Manual
31
XmClipboardInquirePendingItems
Motif Functions and Macros
Name
XmClipboardInquirePendingItems – get a list of pending data ID/private ID
pairs.
Synopsis
#include <Xm/CutPaste.h>
int XmClipboardInquirePendingItems ( Display
Window
char
*format_name,
XmClipboardPendingList
unsigned long
*display,
window,
*item_list,
*count)
Inputs
display
Specifies a connection to an X server; returned from XOpenDisplay() or XtDisplay().
window
Specifies a window ID that identifies the client to the clipboard.
format_name Specifies the format name for the data.
Outputs
item_list
mat.
count
Returns an array of data_id/private_id pairs for the specified forReturns the number of items in the item_list array.
Returns
ClipboardSuccess on success or ClipboardLocked if the clipboard is locked by
another application.
Description
XmClipboardInquirePendingItems() returns for the specified
format_name a list of pending data items, represented by data_id/private_id
pairs. The data_id and private_id arguments are specified in the clipboard functions for copying and retrieving. A data item is considered pending under these
conditions: the application that owns the data item originally passed it by name,
the application has not yet copied the data, and the data item has not been deleted
from the clipboard. If there are no pending items for the specified format_name,
the routine returns a count of 0 (zero). The application is responsible for freeing
the memory that is allocated by XmClipboardInquirePendingItems() to
store the list. Use XtFree() to free the memory.
Usage
An application should call XmClipboardInquirePendingItems() before exiting, to
determine whether data that has been passed by name should be copied to the
clipboard.
32
Motif Reference Manual
Motif Functions and Macros
XmClipboardInquirePendingItems
Structures
The XmClipboardPendingList is defined as follows:
typedef struct {
long DataId;
long PrivateId;
} XmClipboardPendingRec, *XmClipboardPendingList;
See Also
XmClipboardStartCopy(1).
Motif Reference Manual
33
XmClipboardLock
Motif Functions and Macros
Name
XmClipboardLock – lock the clipboard.
Synopsis
#include <Xm/CutPaste.h>
int XmClipboardLock (Display *display, Window window)
Inputs
display
Specifies a connection to an X server; returned from XOpenDisplay() or XtDisplay().
window
Specifies a window ID that identifies the client to the clipboard.
Returns
ClipboardSuccess on success or ClipboardLocked if the clipboard is locked by
another application.
Description
XmClipboardLock() locks the clipboard on behalf of an application, which
prevents access to the clipboard by other applications. If the clipboard has
already been locked by another application, the routine returns ClipboardLocked.
If the same application has already locked the clipboard, the lock level is
increased.
Usage
An application uses XmClipboardLock() to ensure that clipboard data is not
changed by calls to clipboard functions by other applications. An application
does not need to lock the clipboard between calls to XmClipboardStartRetrieve() and XmClipboardEndRetrieve(), because the clipboard is
locked automatically between these calls. XmClipboardUnlock() allows
other applications to access the clipboard again.
See Also
XmClipboardEndCopy(1), XmClipboardEndRetrieve(1),
XmClipboardStartCopy(1), XmClipboardStartRetrieve(1),
XmClipboardUnlock(1).
34
Motif Reference Manual
Motif Functions and Macros
XmClipboardRegisterFormat
Name
XmClipboardRegisterFormat – register a new format for clipboard data items.
Synopsis
#include <Xm/CutPaste.h>
int XmClipboardRegisterFormat (Display *display, char *format_name, int
format_length)
Inputs
display
Specifies a connection to an X server; returned from XOpenDisplay() or XtDisplay().
format_name
Specifies the string name for the format.
format_length
Specifies the length of the format in bits (0, 8, 16, or 32).
Returns
ClipboardSuccess on success, ClipboardBadFormat if the format is not properly
specified, ClipboardLocked if the clipboard is locked by another application, or
ClipboardFail on failure.
Description
XmClipboardRegisterFormat() registers a new format having the specified format_name and format_length. XmClipboardRegisterFormat()
returns ClipboardFail if the format is already registered with the specified length
or ClipboardBadFormat if format_name is NULL or format_length is not 0, 8,
16, or 32 bits.
Usage
XmClipboardRegisterFormat() is used by applications that support cutting and pasting of arbitrary data types. Every format that is stored on the clipboard needs to have a length associated with it, so that clipboard operations
between applications that run on platforms with different byte-swapping orders
function properly. Format types that are defined by the ICCCM are preregistered.
If format_length is 0, XmClipboardRegisterFormat() searches through
the preregistered format types, and returns ClipboardSuccess if format_name is
found, ClipboardFail otherwise.
If you are registering your own data structure as a format, you should choose an
appropriate name, and use 32 as the format size.
See Also
XmClipboardStartCopy(1).
Motif Reference Manual
35
XmClipboardRetrieve
Motif Functions and Macros
Name
XmClipboardRetrieve – retrieve a data item from the clipboard.
Synopsis
#include <Xm/CutPaste.h>
int XmClipboardRetrieve (Display
Window
char
XtPointer
unsigned long
unsigned long
long
*display,
window,
*format_name,
buffer,
length,
*num_bytes,
*private_id)
Inputs
display
Specifies a connection to an X server; returned from XOpenDisplay() or XtDisplay().
window
Specifies a window ID that identifies the client to the clipboard.
format_name Specifies the format name for the data.
buffer
Specifies the buffer to which the clipboard data is copied.
length
Specifies the length of buffer.
Outputs
num_bytes Returns the number of bytes of data copied into buffer.
private_id Returns the private data that was stored with the data item.
Returns
ClipboardSuccess on success, ClipboardLocked if the clipboard is locked by
another application, ClipboardTruncate if buffer is not long enough to hold the
returned data, or ClipboardNoData if there is no data on the clipboard for the
requested format.
Description
XmClipboardRetrieve() fetches the current data item from the clipboard
and copies it to the specified buffer. The format_name specifies the type of data
being retrieved. The num_bytes parameter returns the amount of data that is copied into buffer. The routine returns ClipboardTruncate when all of the data does
not fit in the buffer, to indicate that more data remains to be copied.
Usage
XmClipboardRetrieve() can be used to retrieve data in one large piece or in
multiple smaller pieces. To retrieve data in one chunk, call XmClipboardInquireLength() to determine the size of the data on the clipboard. Multiple
calls to XmClipboardRetrieve() with the same format_name, between calls
to XmClipboardStartRetrieve() and XmClipboardEndRetrieve(),
36
Motif Reference Manual
Motif Functions and Macros
XmClipboardRetrieve
copy data incrementally. Since the clipboard is locked by a call to XmClipboardStartRetrieve(), it is suggested that your application call any clipboard inquiry routines between this call and the first call to
XmClipboardRetrieve()1.
Example
The following code fragment shows the sequence of calls needed to perform an
incremental retrieve. Note that this code does not store the data as it is retrieved:
int
status;
unsigned long received;
char
buffer[32];
Display
*dpy
= XtDisplayOfObject (widget);
Window
window = XtWindowOfObject (widget);
do
status = XmClipboardStartRetrieve (dpy, window,
CurrentTime);
while (status == ClipboardLocked);
do {
/* retrieve data from clipboard */
status = XmClipboardRetrieve (dpy, window,
"STRING",
(XtPointer) buffer,
(unsigned long)
sizeof (buffer),
&received,
(long *) 0);
} while (status == ClipboardTruncate);
status = XmClipboardEndRetrieve (dpy, window);
See Also
XmClipboardEndRetrieve(1), XmClipboardInquireLength(1),
XmClipboardLock(1), XmClipboardStartRetrieve(1),
XmClipboardUnlock(1).
1.Erroneously given as ClipboardRetrieve() in 1st and 2nd editions.
Motif Reference Manual
37
XmClipboardStartCopy
Motif Functions and Macros
Name
XmClipboardStartCopy – set up storage for a clipboard copy operation.
Synopsis
#include <Xm/CutPaste.h>
int XmClipboardStartCopy ( Display
Window
XmString
Time
Widget
XmCutPasteProc
long
Inputs
display
window
clip_label
timestamp
widget
callback
Outputs
item_id
*display,
window,
clip_label,
timestamp,
widget,
callback,
*item_id)
Specifies a connection to an X server; returned from XOpenDisplay() or XtDisplay().
Specifies a window ID that identifies the client to the clipboard.
Specifies a label that is associated with the data item.
Specifies the time of the event that triggered the copy operation.
Specifies the widget that receives messages requesting data
that has been passed by name.
Specifies the callback function that is called when the clipboard needs data that has been passed by name.
Returns the ID assigned to the data item.
Returns
ClipboardSuccess on success or ClipboardLocked if the clipboard is locked by
another application.
Description
XmClipboardStartCopy() creates the storage and data structures that
receive clipboard data. During a cut or copy operation, an application calls this
function to initiate the operation. The data that is copied to the structures
becomes the next clipboard data item.
Several arguments to XmClipboardStartCopy() provide identifying information. The window argument specifies the window that identifies the application
to the clipboard; an application should pass the same window ID to each clipboard routine that it calls. clip_label assigns a text string to the data item that
could be used as the label for a clipboard viewing window. The timestamp passed
38
Motif Reference Manual
Motif Functions and Macros
XmClipboardStartCopy
to the routine must be a valid timestamp. The item_id argument returns a number
that identifies the data item. An application uses this number to specify the data
item in other clipboard calls.
Usage
Since copying a large piece of data to the clipboard can take a long time and it is
possible that the data will never be requested by another application, the clipboard copy routines provide a mechanism to copy data by name. When a clipboard data item is passed by name, the application does not need to copy the data
to the clipboard until it has been requested by another application. In order to
pass data by name, the widget and callback arguments to XmClipboardStartCopy() must be specified. widget specifies the ID of the widget that
receives messages requesting that data be passed by name. All of the message
handling is done by the clipboard operations, so any valid widget ID can be used.
callback specifies the procedure that is invoked when the clipboard needs the data
that was passed by name and when the data item is removed from the clipboard.
The callback function copies the actual data to the clipboard using XmClipboardCopyByName().
Example
The following routines show the sequence of calls needed to copy data by name.
The to_clipbd callback shows the copying of data and copy_by_name shows the
callback that actually copies the data:
void copy_by_name ( Widget widget,
long
*data_id,
long
*private_id,
int
*reason)
{
Display
*dpy
= XtDisplay (toplevel);
Window
window = XtWindow (toplevel);
int
status;
char
buffer[32];
if (*reason == XmCR_CLIPBOARD_DATA_REQUEST) {
(void) sprintf (buffer, "stuff");
do
status = XmClipboardCopyByName (dpy, window, *data_id,
(XtPointer) buffer,
(unsigned long)
strlen (buffer)+1,
*private_id);
Motif Reference Manual
39
XmClipboardStartCopy
Motif Functions and Macros
while (status != ClipboardSuccess);
}
}
void to_clipbd ( Widget
widget,
XtPointer
client_data,
XtPointer
call_data)
{
unsigned long item_id = 0;
int
status;
XmString
clip_label;
Display
*dpy
= XtDisplayOfObject
(widget);
Window
window = XtWindowOfObject
(widget);
unsigned long size = DATA_SIZE;
char
*data = (char *) client_data;
clip_label = XmStringCreateLocalized ("Data");
/* start a copy; retry until unlocked */
do
status = XmClipboardStartCopy (dpy, window,
clip_label,
CurrentTime,
widget,
copy_by_name,
&item_id);
while (status == ClipboardLocked);
XmStringFree (clip_label);
/* copy the data; retry until unlocked */
do
status = XmClipboardCopy (dpy, window,
item_id,
"STRING", NULL,
size, 0, NULL);
while (status == ClipboardLocked);
/* end the copy; retry until unlocked */
do
status = XmClipboardEndCopy (dpy, window,
item_id);
while (status == ClipboardLocked);
}
40
Motif Reference Manual
Motif Functions and Macros
XmClipboardStartCopy
Procedures
The XmCutPasteProc has the following format:
typedef void (*XmCutPasteProc) (Widget widget, long *data_id, long
*private_id, int *reason)
An XmCutPasteProc takes four arguments. The first argument, widget, is the
widget passed to the callback routine, which is the same widget as passed to
XmClipboardBeginCopy(). The data_id argument is the ID of the data item
that is returned by XmClipboardCopy() and private_id is the private data
passed to XmClipboardCopy().
The reason argument takes the value XmCR_CLIPBOARD_DATA_REQUEST,
which indicates that the data must be copied to the clipboard, or
XmCR_CLIPBOARD_DATA_DELETE, which indicates that the client can
delete the data from the clipboard. Although the last three parameters are pointers
to integers, the values are read-only and changing them has no effect.
See Also
XmClipboardBeginCopy(1), XmClipboardCancelCopy(1),
XmClipboardCopy(1), XmClipboardCopyByName(1),
XmClipboardEndCopy(1), XmClipboardLock(1),
XmClipboardRegisterFormat(1), XmClipboardUndoCopy(1),
XmClipboardUnlock(1), XmClipboardWithdrawFormat(1).
Motif Reference Manual
41
XmClipboardStartRetrieve
Motif Functions and Macros
Name
XmClipboardStartRetrieve – start a clipboard retrieval operation.
Synopsis
#include <Xm/CutPaste.h>
int XmClipboardStartRetrieve (Display *display, Window window, Time timestamp)
Inputs
display
Specifies a connection to an X server; returned from XOpenDisplay() or XtDisplay().
window
Specifies a window ID that identifies the client to the clipboard.
timestamp
Specifies the time of the event that triggered the retrieval operation.
Returns
ClipboardSuccess on success or ClipboardLocked if the clipboard is locked by
another application.
Description
XmClipboardStartRetrieve() starts a clipboard retrieval operation by
telling the clipboard that an application is ready to start copying data from the
clipboard. XmClipboardStartRetrieve() locks the clipboard until
XmClipboardEndRetrieve() is called. The window argument specifies the
window that identifies the application to the clipboard; an application should pass
the same window ID to each clipboard routine that it calls. The timestamp passed
to the routine must be a valid timestamp.
Usage
Multiple calls to XmClipboardRetrieve() with the same format_name,
between calls to XmClipboardStartRetrieve() and XmClipboardEndRetrieve(), copy data incrementally.
Example
The following code fragment shows the sequence of calls needed to perform an
incremental retrieve. Note that this code does not store the data as it is retrieved:
int
status;
unsigned long received;
char
buffer[32];
Display
*dpy = XtDisplayOfObject (widget);
Window
window = XtWindowOfObject (widget);
do
42
Motif Reference Manual
Motif Functions and Macros
XmClipboardStartRetrieve
status = XmClipboardStartRetrieve (dpy, window,
CurrentTime);
while (status == ClipboardLocked);
do {
/* retrieve data from clipboard */
status = XmClipboardRetrieve (dpy, window,
"STRING",
(XtPointer) buffer,
(unsigned long)
sizeof (buffer),
&received,
(long *) 0);
} while (status == ClipboardTruncate);
status = XmClipboardEndRetrieve (dpy, window);
See Also
XmClipboardEndRetrieve(1), XmClipboardInquireCount(1),
XmClipboardInquireFormat(1), XmClipboardInquireLength(1),
XmClipboardInquirePendingItems(1), XmClipboardLock(1),
XmClipboardRetrieve(1), XmClipboardUnlock(1).
Motif Reference Manual
43
XmClipboardUndoCopy
Motif Functions and Macros
Name
XmClipboardUndoCopy – remove the last item copied to the clipboard.
Synopsis
#include <Xm/CutPaste.h>
int XmClipboardUndoCopy (Display *display, Window window)
Inputs
display
Specifies a connection to an X server; returned from XOpenDisplay() or XtDisplay().
window
Specifies a window ID that identifies the client to the clipboard.
Returns
ClipboardSuccess on success or ClipboardLocked if the clipboard is locked by
another application.
Description
XmClipboardUndoCopy() deletes the item most recently placed on the clipboard, provided that the application that originally placed the item has matching
values for display and window. If the values do not match, no action is taken. The
routine also restores any data item that was deleted from the clipboard by the call
to XmClipboardCopy().
Usage
Motif maintains a two-deep stack of items that have been placed on the clipboard. Once an item has been copied to the clipboard, the copy can be undone by
calling XmClipboardUndoCopy(). Calling this routine twice undoes the last
undo operation.
See Also
XmClipboardBeginCopy(1), XmClipboardCopy(1),
XmClipboardCopyByName(1), XmClipboardEndCopy(1),
XmClipboardStartCopy(1).
44
Motif Reference Manual
Motif Functions and Macros
XmClipboardUnlock
Name
XmClipboardUnlock – unlock the clipboard.
Synopsis
#include <Xm/CutPaste.h>
int XmClipboardUnlock (Display *display, Window window, Boolean
remove_all_locks)
Inputs
display
Specifies a connection to an X server; returned from
XOpenDisplay() or XtDisplay().
window
Specifies a window ID that identifies the client to the clipboard.
remove_all_locks Specifies whether nested locks should be removed.
Returns
ClipboardSuccess on success or ClipboardFail if the clipboard is not locked or if
it is locked by another application.
Description
XmClipboardUnlock() unlocks the clipboard, which allows other applications to access it. If remove_all_locks is True, all nested locks are removed. If it
is False, only one level of lock is removed.
Usage
Multiple calls to XmClipboardLock() can increase the lock level, and normally, each XmClipboardLock() call requires a corresponding call to
XmClipboardUnlock(). However, by setting remove_all_locks to True,
nested locks can be removed with a single call.
See Also
XmClipboardBeginCopy(1), XmClipboardCancelCopy(1),
XmClipboardEndCopy(1), XmClipboardEndRetrieve\(1)
XmClipboardLock(1), XmClipboardStartCopy(1),
XmClipboardStartRetrieve(1).
Motif Reference Manual
45
XmClipboardWithdrawFormat
Motif Functions and Macros
Name
XmClipboardWithdrawFormat – indicate that an application does not want to
supply a data item any longer.
Synopsis
#include <Xm/CutPaste.h>
int XmClipboardWithdrawFormat (Display *display, Window window, long
data_id)
Inputs
display
Specifies a connection to an X server; returned from XOpenDisplay() or XtDisplay().
window
Specifies a window ID that identifies the client to the clipboard.
data_id
Specifies the ID for the passed-by-name data item.
Returns
ClipboardSuccess on success or ClipboardLocked if the clipboard is locked by
another application.
Description
XmClipboardWithdrawFormat() withdraws a data item that has been
passed by name from the clipboard. The data_id is the ID that was assigned to
the item when it was passed by XmClipboardCopy().
Usage
Despite its name, XmClipboardWithdrawFormat() does not remove a format specification from the clipboard. The routine provides an application with a
way to withdraw data of a particular format from the clipboard.
See Also
XmClipboardBeginCopy(1), XmClipboardCopy(1),
XmClipboardCopyByName(1), XmClipboardStartCopy(1).
46
Motif Reference Manual
Motif Functions and Macros
XmComboBoxAddItem
Name
XmComboBoxAddItem – add a compound string to the ComboBox list.
Synopsis
#include <Xm/ComboBox.h>
void XmComboBoxAddItem (Widget widget, XmString item, int position,
Boolean unique)
Inputs
widget
item
position
unique
Specifies the ComboBox widget.
Specifies the compound string that is added to the ComboBox list.
Specifies the position at which to add the new item.
Specifies whether the item must be unique in the list.
Availability
Motif 2.1 and later.
Description
XmComboBoxAddItem() is a convenience routine that adds an item into a
ComboBox list. XmComboBoxAddItem() inserts the specified item into the list
component of the ComboBox widget at the specified position. A position value of
1 indicates the first location in the list, a position value of 2 indicates the second
location, and so forth. A value of 0 (zero) specifies the last location in the list. If
the value exceeds the current number of items in the list, the item is silently
appended. If unique is true, the item is only added if it does not already appear in
the list.
Usage
In order to use this routine, a compound string must be created for the item. The
routine calls XmListAddItemUnselected() to insert the item into the list
component. The ComboBox list takes a copy of the supplied item. It is the
responsibility of the programmer to reclaim the space by calling XmStringFree()
at an appropriate point.
See Also
XmComboBoxSelectItem(1), XmComboBoxSetItem(1),
XmComboBoxDeletePos(1), XmComboBoxUpdate(1), XmComboBox(2).
Motif Reference Manual
47
XmComboBoxDeletePos
Motif Functions and Macros
Name
XmComboBoxDeletePos – delete an item at the specified position from a ComboBox list.
Synopsis
#include <Xm/ComboBox.h>
void XmComboBoxDeletePos (Widget widget, int position)
Inputs
widget
position
Specifies the ComboBox widget.
Specifies the position from which to delete an item.
Availability
Motif 2.1 and later.
Description
XmComboBoxDeletePos() removes the item at the specified position from the
ComboBox list. The first location within the list is at position 1, the second list
item is at position 2, and so forth. A position value of 0 (zero) specifies the last
location in the list. If the ComboBox list does not have an item at the specified
position, a warning message is displayed.
Usage
XmComboBoxDeletePos() is a convenience routine that allows you to remove
an item from a ComboBox list. The routine calls XmListDeletePos() on the
list component of the ComboBox.
See Also
XmComboBoxAddItem(1), XmComboBoxSelectItem(1),
XmComboBoxSetItem(1), XmComboBoxUpdate(1), XmComboBox(2).
48
Motif Reference Manual
Motif Functions and Macros
XmComboBoxSelectItem
Name
XmComboBoxSelectItem – select an item from a ComboBox list.
Synopsis
#include <Xm/ComboBox.h>
void XmComboBoxSelectItem (Widget widget, XmString item)
Inputs
widget
item
Specifies the ComboBox widget.
Specifies the item that is to be selected.
Availability
Motif 2.1 and later.
Description
XmComboBoxSelectItem() selects the first occurrence of the specified item
in the ComboBox list. If the item is found within the list, the value is also inserted
into the ComboBox text field. Otherwise, a warning message is displayed.
Usage
XmComboBoxSelectItem() is a convenience routine that allows you to select
an item in the ComboBox list. In order to use this routine, a compound string
must be created for the item. No ComboBox selection callbacks are invoked as a
result of calling this procedure. The routine internally calls XmListSelectPos() on the list component of the ComboBox, after performing a linear search
through the XmNitems of the list: the item parameter is used only for the search
and is not directly used as the newly selected item. It is the responsibility of the
programmer to reclaim any allocated memory for the compound string item by
calling XmStringFree() at an appropriate time.
See Also
XmComboBoxAddItem(1), XmComboBoxDeletePos(1),
XmComboBoxSetItem(1), XmComboBoxUpdate(1), XmComboBox(2).
Motif Reference Manual
49
XmComboBoxSetItem
Motif Functions and Macros
Name
XmComboBoxSetItem – select and make visible an item from a ComboBox list.
Synopsis
#include <Xm/ComboBox.h>
void XmComboBoxSetItem (Widget widget, XmString item)
Inputs
widget
item
Specifies the ComboBox widget.
Specifies the item that is to be selected.
Availability
Motif 2.1 and later.
Description
XmComboBoxSetItem() selects the first occurrence of the specified item in the
ComboBox list, and makes the selection the first visible item in the list. If the
item is found within the list, the value is also inserted into the ComboBox text
field. Otherwise, a warning message is displayed.
Usage
XmComboBoxSetItem() is a convenience routine that allows you to select an
item in the ComboBox. In order to use this routine, a compound string must be
created for the item. No ComboBox selection callbacks are invoked as a result of
calling this procedure. The routine internally calls XmListSelectPos() on
the list component of the ComboBox, after performing a linear search through
the XmNitems of the list: the item parameter is used only for the search and is not
directly used as the newly selected item. It is the responsibility of the programmer to reclaim any allocated memory for the compound string item by calling
XmStringFree() at an appropriate time.
See Also
XmComboBoxAddItem(1), XmComboBoxDeletePos(1),
XmComboBoxSelectItem(1), XmComboBoxUpdate(1), XmComboBox(2).
50
Motif Reference Manual
Motif Functions and Macros
XmComboBoxUpdate
Name
XmComboBoxUpdate – update the ComboBox list after changes to component
widgets.
Synopsis
#include <Xm/ComboBox.h>
void XmComboBoxUpdate (Widget widget)
Inputs
widget
Specifies the ComboBox widget.
Availability
Motif 2.0 and later.
Description
XmComboBoxUpdate() updates the ComboBox to reflect the state of component child widgets. This may be required where the programmer has directly
modified the contents or resources of the ComboBox list component rather than
through resources and functions of the ComboBox itself.
Usage
XmComboBoxUpdate() is a convenience routine that synchronizes the internal
state of the ComboBox with that of the component list and text field. In particular, the value of XmNselectedPosition is reset to the value taken from the internal
list. In addition, if the text field is unchanged, the XmNitems and XmNitemCount
resources of the list are queried and used in conjunction with the recalculated
XmNselectedPosition to reset the ComboBox selected item.
This routine should be called, for example, when the component list is directly
manipulated to change the selected item without notifying the ComboBox
directly.
See Also
XmComboBoxAddItem(1), XmComboBoxSelectItem(1),
XmComboBoxSetItem(1), XmComboBoxDeletePos(1), XmComboBox(2).
Motif Reference Manual
51
XmCommandAppendValue
Motif Functions and Macros
Name
XmCommandAppendValue – append a compound string to the command.
Synopsis
#include <Xm/Command.h>
void XmCommandAppendValue (Widget widget, XmString command)
Inputs
widget
command
Specifies the Command widget.
Specifies the string that is appended.
Description
XmCommandAppendValue() appends the specified command to the end of the
string that is displayed on the command line of the specified Command widget.
Usage
XmCommandAppendValue() is a convenience routine that changes the value
of the XmNcommand resource of the Command widget. In order to use this routine, a compound string must be created for the command. The widget internally
copies command, and it is the responsibility of the programmer to reclaim any
allocated memory for the compound string at an appropriate time.
See Also
XmCommandSetValue(1), XmCommand(2).
52
Motif Reference Manual
Motif Functions and Macros
XmCommandError
Name
XmCommandError – display an error message in a Command widget.
Synopsis
#include <Xm/Command.h>
void XmCommandError (Widget widget, XmString error)
Inputs
widget
error
Specifies the Command widget.
Specifies the error message to be displayed.
Description
XmCommandError() displays an error message in the history region of the
specified Command widget. The error string remains displayed until the next
command takes effect.
Usage
XmCommandError() displays the error message as one of the items in the
XmNhistoryItems list. When the next command is entered, the error message is
deleted from the list. In order to use this routine, a compound string must be created for the error item. The widget internally copies error, and it is the responsibility of the programmer to reclaim any allocated memory for the compound
string at an appropriate time.
See Also
XmCommand(2).
Motif Reference Manual
53
XmCommandGetChild
Motif Functions and Macros
Name
XmCommandGetChild – get the specified child of a Command widget.
Synopsis
#include <Xm/Command.h>
Widget XmCommandGetChild (Widget widget, unsigned char child)
Inputs
widget
child
Specifies the Command widget.
Specifies a type of child of the Command widget.
Returns
The widget ID of the specified child of the Command widget.
Availability
As of Motif 2.0, the abstract child fetch routines in the toolkit are generally considered deprecated. Although XmCommandGetChild() continues to work, you
should prefer XtNameToWidget() to access children of the XmCommand
component.
Description
XmCommandGetChild() returns the widget ID of the specified child of the Command widget.
Usage
The child XmDIALOG_COMMAND_TEXT specifies the command text entry
area, XmDIALOG_PROMPT_LABEL specifies the prompt label for the command line, XmDIALOG_HISTORY_LIST specifies the command history list,
and XmDIALOG_WORK_AREA specifies any work area child that has been
added to the Command widget. For more information on the different children of
the Command widget, see the manual page in Section 2, Motif and Xt Widget
Classes.
Structures
The possible values for child are:
XmDIALOG_COMMAND_TEXT
XmDIALOG_PROMPT_LABEL
54
XmDIALOG_HISTORY_LIST
XmDIALOG_WORK_AREA
Motif Reference Manual
Motif Functions and Macros
XmCommandGetChild
Widget Hierarchy
The following names are associated with the Command children:
“Selection”
“Text”
“ItemsList”1
XmDIALOG_PROMPT_LABEL
XmDIALOG_COMMAND_TEXT
XmDIALOG_HISTORY_LIST
See Also
XmCommand(2).
1.The List is not a direct descendant of the Command widget, but of an intermediary ScrolledList. Therefore if fetching
the widget via XtNameToWidget(), you should use the value “*ItemsList”.
Motif Reference Manual
55
XmCommandSetValue
Motif Functions and Macros
Name
XmCommandSetValue – replace the command string.
Synopsis
#include <Xm/Command.h>
void XmCommandSetValue (Widget widget, XmString command)
Inputs
widget
command
Specifies the Command widget.
Specifies the string that is displayed.
Description
XmCommandSetValue() replaces the currently displayed command-line text
of the specified Command widget with the string specified by command. Specifying a zero-length string clears the command line.
Usage
XmCommandSetValue() is a convenience routine that changes the value of the
XmNcommand resource of the Command widget. In order to use this routine, a
compound string must be created for the command. The widget internally copies
command, and it is the responsibility of the programmer to reclaim any allocated
memory for the compound string at an appropriate time.
See Also
XmCommandAppendValue(1), XmCommand(2).
56
Motif Reference Manual
Motif Functions and Macros
XmContainerCopy
Name
XmContainerCopy – copy the Container primary selection onto the clipboard.
Synopsis
#include <Xm/Container.h>
Boolean XmContainerCopy (Widget container, Time timestamp)
Inputs
container
timestamp
Specifies a Container widget.
Specifies the server time at which to modify the selection.
Returns
True if the Container selection is transferable to the clipboard, False otherwise.
Availability
Motif 2.0 and later.
Description
XmContainerCopy() copies the primary selection from a Container widget to
the clipboard. The primary selection of a Container widget consists of a set of
selected Container items.
If there are no selected Container items within container, or if the container
widget does not own the primary selection, or if container cannot gain ownership
of the clipboard selection, the function returns False.
Usage
XmContainerCopy() is a convenience routine that copies a Container primary
selection to the clipboard. The procedures identified by the XmNconvertCallback
list of the Container are called to transfer the selection: the selection member of
the XmConvertCallbackStruct passed to callbacks has the value CLIPBOARD,
and the parm member is set to XmCOPY. See XmTransfer(1) for specific
details of the XmConvertCallbackStruct, and of the Uniform Transfer Model
(UTM) in general.
See Also
XmContainerCut(1), XmContainerCopyLink(1),
XmContainerGetItemChildren(1), XmContainerPaste(1),
XmContainerPasteLink(1), XmContainerRelayout(1),
XmContainerReorder(1), XmTransfer(1), XmContainer(2).
Motif Reference Manual
57
XmContainerCopyLink
Motif Functions and Macros
Name
XmContainerCopyLink – copy links to the Container primary selection onto the
clipboard.
Synopsis
#include <Xm/Container.h>
Boolean XmContainerCopyLink (Widget container, Time timestamp)
Inputs
container
timestamp
Specifies a Container widget.
Specifies a time stamp at which to modify the selection.
Returns
True if the Container selection is transferable to the clipboard, False otherwise.
Availability
Motif 2.0 and later.
Description
XmContainerCopyLink() copies links to the primary selection of a Container widget onto the clipboard. The primary selection of a Container widget
consists of a set of selected Container items.
If there are no selected Container items within container, or if the container
widget does not own the primary selection, or if container cannot gain ownership
of the clipboard selection, the function returns False.
Usage
XmContainerCopyLink() is a convenience routine that copies links to a
Container primary selection to the clipboard. The procedures identified by the
XmNconvertCallback list of the Container are called, possibly many times: the
selection member of the XmConvertCallbackStruct passed to callbacks has the
value CLIPBOARD, and the parm member is set to XmLINK. See XmTransfer(1) for specific details of the XmConvertCallbackStruct, and of the Uniform
Transfer Model (UTM) in general.
See Also
XmContainerCut(1), XmContainerCopy(1),
XmContainerGetItemChildren(1), XmContainerPaste(1),
XmContainerPasteLink(1), XmContainerRelayout(1),
XmContainerReorder(1), XmTransfer(1), XmContainer(2).
58
Motif Reference Manual
Motif Functions and Macros
XmContainerCut
Name
XmContainerCut – cuts the Container primary selection onto the clipboard.
Synopsis
#include <Xm/Container.h>
Boolean XmContainerCut (Widget container, Time timestamp)
Inputs
container
timestamp
Specifies a Container widget.
Specifies the time at which to modify the selection.
Returns
True if the Container selection is transferable to the clipboard, False otherwise.
Availability
Motif 2.0 and later.
Description
XmContainerCut() cuts the primary selection from a Container widget onto
the clipboard. The primary selection of a Container widget consists of a set of
selected Container items.
If there are no selected Container items within container, or if the container
widget does not own the primary selection, or if container cannot gain ownership
of the clipboard selection, the function returns False.
Usage
XmContainerCut() is a convenience routine that moves a Container primary
selection onto the clipboard, then removes the primary selection. The procedures
identified by the XmNconvertCallback list of the Container are invoked to move
the selection to the clipboard: the selection member of the XmConvertCallbackStruct passed to callbacks has the value CLIPBOARD, and the parm member is
set to XmMOVE. Thereafter, if the data was transferred, the convert callbacks are
invoked again to delete the primary selection: the selection member is set to
CLIPBOARD, and the target member is set to DELETE. See XmTransfer(1)
for specific details of the XmConvertCallbackStruct, and of the Uniform Transfer
Model (UTM) in general.
See Also
XmContainerCopy(1), XmContainerCopyLink(1),
XmContainerGetItemChildren(1), XmContainerPaste(1),
XmContainerPasteLink(1), XmContainerRelayout(1),
XmContainerReorder(1), XmTransfer(1), XmContainer(2).
Motif Reference Manual
59
XmContainerGetItemChildren
Motif Functions and Macros
Name
XmContainerGetItemChildren – find the children of a Container item.
Synopsis
#include <Xm/Container.h>
int XmContainerGetItemChildren (Widget container, Widget item, WidgetList
*item_children)
Inputs
container
item
trait.
Specifies a Container widget.
A child of the Container which holds the XmQTcontainerItem
Outputs
item_children
The list of logical children associated with the item.
Returns
The number of logical children within the item_children list.
Availability
Motif 2.0 and later.
Description
XmContainerGetItemChildren() constructs a list of Container items
which have item as a logical parent. item must hold the XmQTcontainerItem
trait: an IconGadget child of container, for example. A widget is a logical child of
item if the value of its constraint resource XmNentryParent is equal to item. container is the Container widget which has item as a child, and the list of logical
children of item is placed in item_children. The function returns the number of
logical children found.
Usage
XmContainerGetItemChildren() is a convenience routine which allocates a WidgetList to contain the set of all Container children whose XmNentryParent resource matches that of a designated item.
If item is NULL, or if item is not a child of container, or if item has no logical
children, the item_children parameter is not set and the function returns 0.
Storage for the returned WidgetList is allocated by the function, and it is the
responsibility of the programmer to free the memory using XtFree() at an
appropriate point.
60
Motif Reference Manual
Motif Functions and Macros
XmContainerGetItemChildren
See Also
XmContainerCut(1), XmContainerCopy(1),
XmContainerCopyLink(1), XmContainerPaste(1),
XmContainerPasteLink(1), XmContainerRelayout(1),
XmContainerReorder(1), XmContainer(2).
Motif Reference Manual
61
XmContainerPaste
Motif Functions and Macros
Name
XmContainerPaste – pastes the clipboard selection into a Container.
Synopsis
#include <Xm/Container.h>
Boolean XmContainerPaste (Widget container)
Inputs
container
Specifies a Container widget.
Returns
True if the clipboard selection is transferable to the Container, False otherwise.
Availability
Motif 2.0 and later.
Description
XmContainerPaste() initiates data transfer of the clipboard primary selection to the container widget.
If data is transferred from the clipboard, the function returns True, otherwise
False.
Usage
XmContainerPaste() is a convenience routine that initiates copying of the
clipboard primary selection to a Container widget. The procedures identified by
the XmNdestinationCallback list of the Container are called: the selection member of the XmDestinationCallbackStruct passed to callbacks has the value CLIPBOARD, and the operation member is set to XmCOPY.
XmContainerPaste() does not transfer data itself: it is the responsibility of
the programmer to supply a destination callback which will copy the clipboard
selection into the Container. See XmTransfer(1) for specific details of the
XmDestinationCallbackStruct, and of the Uniform Transfer Model (UTM) in
general.
See Also
XmContainerCut(1), XmContainerCopy(1),
XmContainerCopyLink(1), XmContainerGetItemChildren(1),
XmContainerPasteLink(1), XmContainerRelayout(1),
XmContainerReorder(1), XmTransfer(1), XmContainer(2).
62
Motif Reference Manual
Motif Functions and Macros
XmContainerPasteLink
Name
XmContainerPasteLink – copies links from the clipboard selection into a Container.
Synopsis
#include <Xm/Container.h>
Boolean XmContainerPasteLink (Widget container)
Inputs
container
Specifies a Container widget.
Returns
True if the clipboard selection is transferable to the Container, False otherwise.
Availability
Motif 2.0 and later.
Description
XmContainerPasteLink() initiates data transfer of the clipboard primary
selection to the container widget.
If data is transferred from the clipboard, the function returns True, otherwise
False.
Usage
XmContainerPasteLink() is a convenience routine that initiates copying
links from the clipboard primary selection into a Container widget. The procedures identified by the XmNdestinationCallback list of the Container are called:
the selection member of the XmDestinationCallbackStruct passed to callbacks
has the value CLIPBOARD, and the operation member is set to XmLINK.
XmContainerPasteLink() does not transfer data itself: it is the responsibility of the programmer to supply a destination callback which will link the clipboard selection into the Container. See XmTransfer(1) for specific details of
the XmConvertCallbackStruct, and of the Uniform Transfer Model (UTM) in
general.
See Also
XmContainerCut(1), XmContainerCopy(1),
XmContainerCopyLink(1), XmContainerGetItemChildren(1),
XmContainerPaste(1), XmContainerRelayout(1),
XmContainerReorder(1), XmTransfer(1), XmContainer(2).
Motif Reference Manual
63
XmContainerRelayout
Motif Functions and Macros
Name
XmContainerRelayout – force relayout of a Container widget.
Synopsis
#include <Xm/Container.h>
void XmContainerRelayout (Widget container)
Inputs
container
Specifies a Container widget.
Availability
Motif 2.0 and later.
Description
XmContainerRelayout() forces the container widget to recalculate the layout of all Container items.
Usage
XmContainerRelayout() is a convenience routine that recalculates the grid
layout of a Container. The function has no effect if the widget is not realized, if
XmNlayoutType is not XmSPATIAL, or if XmNspatialStyle is XmNONE.
The function does not cause geometry management effects when performing the
relayout, although the Container window is completely cleared and redrawn if
the widget is realized.
XmContainerRelayout() utilizes the place_item method of the Container
widget class. If this is NULL in any derived class, XmContainerRelayout()
will have no effect upon the layout of Container items.
See Also
XmContainerCut(1), XmContainerCopy(1),
XmContainerCopyLink(1), XmContainerGetItemChildren(1),
XmContainerPaste(1), XmContainerPasteLink(1),
XmContainerReorder(1), XmContainer(2).
64
Motif Reference Manual
Motif Functions and Macros
XmContainerReorder
Name
XmContainerReorder – reorder children of a Container.
Synopsis
#include <Xm/Container.h>
void XmContainerReorder (Widget container, WidgetList item_list, int
item_count)
Inputs
container
item_list
item_count
Specifies a Container widget.
Specifies a list of Container child widgets.
Specifies the number of widgets in item_list.
Availability
Motif 2.0 and later.
Description
XmContainerReorder() reorders an item_list set of items of a Container.
item_count is the number of items within the item_list array.
Usage
XmContainerReorder() is a convenience routine that reorders Container
items according to the value of the XmNpositionIndex constraint resource of
each item, using a quicksort algorithm. If the XmNlayoutType is XmOUTLINE
or XmDETAIL, the Container will subsequently relayout all the items within the
widget.
Neither relayout nor reorder is performed if item_count is less than or equal to 1;
there is no error checking performed on item_list to compare it with NULL, or to
ensure that it matches the number of items specified by item_count.
See Also
XmContainerCut(1), XmContainerCopy(1),
XmContainerCopyLink(1), XmContainerGetItemChildren(1),
XmContainerPaste(1), XmContainerPasteLink(1),
XmContainerRelayout(1), XmContainer(1).
Motif Reference Manual
65
XmConvertStringToUnits
Motif Functions and Macros
Name
XmConvertStringToUnits – convert a string to an integer, optionally translating
the units.
Synopsis
int XmConvertStringToUnits (
Inputs
screen
spec
orientation
unit_type
Outputs
error_return
Screen
String
int
int
XtEnum
*screen,
spec,
orientation,
unit_type,
*error_return)
Specifies a pointer to the screen structure.
Specifies a value to be converted.
Specifies whether to use horizontal or vertical screen resolution. Pass either XmHORIZONTAL or XmVERTICAL.
The units required for the result.
Returns the error status of the conversion.
Returns
The converted value.
Availability
Motif 2.0 and later.
Description
XmConvertStringToUnits() converts a string spec into an integer. The
conversion of spec is into the units specified by unit_type. Resolution for the conversion is determined from the screen, and orientation determines whether the
horizontal or vertical screen resolution is used. The converted value is returned
by the function. The error_return parameter is set by the function to indicate any
error in the conversion process.
Usage
XmConvertStringToUnits() converts a string into an integer, translating
the units of the original string into those specified by unit_type. If the screen is
NULL, or if orientation is an invalid value, or if an invalid unit_type is supplied,
or if the string spec is not parsable, the function returns 0 (zero), and error_return
is set True. Otherwise, error_return is set False, and the function returns the converted value.
The string spec is assumed to be in the following format:
66
Motif Reference Manual
Motif Functions and Macros
XmConvertStringToUnits
<float> <unit>
where <float> is a floating point number. The <unit> specification is optional: if
omitted, the default unit of XmPIXELS is used. Otherwise, <unit> is one of the
following strings:
pix
in
cm
mm
pt
fu
pixel
inch
centimeter
millimeter
point
font_unit
pixels
inches
centimeters
millimeters
points
font_units
Structures
The possible values for unit_type are:
XmPIXELS
TERS
Xm100TH_MILLIMETERS
Xm1000TH_INCHES
XmPOINTS
XmFONT_UNITS
Xm100TH_FONT_UNITS
XmCENTIMETERS
XmMILLIME-
XmINCHES
Xm100TH_POINTS
Example
The following are valid string specifications:
3.1415926 pix
-3.1 pt
6.3
0.3 font_units
1
See Also
XmConvertUnits(1), XmScreen(2).
Motif Reference Manual
67
XmConvertUnits
Motif Functions and Macros
Name
XmConvertUnits – convert a value to a specified unit type.
Synopsis
int XmConvertUnits (
Inputs
widget
orientation
from_unit_type
from_value
to_unit_type
Widget
int
int
int
int
widget,
orientation,
from_unit_type,
from_value,
to_unit_type)
Specifies the widget for which to convert the data.
Specifies the screen orientation that is used in the conversion. Pass either XmHORIZONTAL or XmVERTICAL.
Specifies the unit type of the value that is being converted.
Specifies the value that is being converted.
Specifies the new unit type of the value.
Returns
The converted value or 0 (zero) if the input parameters are not specified correctly.
Description
XmConvertUnits() converts the value specified in from_value into the equivalent value in a different unit of measurement. This function returns the resulting
value if successful; it returns 0 (zero) if widget is NULL or if incorrect values are
supplied for orientation or conversion unit arguments. orientation matters only
when conversion values are font units, which are measured differently in the horizontal and vertical dimensions.
Usage
XmConvertUnits() allows an application to manipulate resolution-independent values. XmPIXELS specifies a normal pixel value,
Xm100TH_MILLIMETERS specifies a value in terms of 1/100 of a millimeter,
Xm1000TH_INCHES specifies a value in terms of 1/1000 of an inch,
Xm100TH_POINTS specifies a value in terms of 1/100 of a point (1/72 of an
inch), and Xm100TH_FONT_UNITS specifies a value in terms of 1/100 of a font
unit. A font unit has horizontal and vertical components which are specified by
the XmScreen resources XmNhorizontalFontUnit and XmNverticalFontUnit.
Structures
The possible values for from_unit_type and to_unit_type are:
XmPIXELS
XmMILLIMETERS
XmINCHES
68
XmCENTIMETERS
Xm100TH_MILLIMETERS
Xm1000TH_INCHES
Motif Reference Manual
Motif Functions and Macros
XmPOINTS
XmFONT_UNITS
XmConvertUnits
Xm100TH_POINTS
Xm100TH_FONT_UNITS
The values XmPOINTS, XmINCHES, XmCENTIMETERS, XmFONT_UNITS,
and XmMILLIMETERS are available in Motif 2.0 and later.
See Also
XmSetFontUnits(1), XmScreen(2).
Motif Reference Manual
69
XmCreate<Emphasis>Object<Default Para Font>
Motif Functions and Macros
Name
XmCreateObject – create an instance of a particular widget class or compound
object.
Synopsis
Simple Widgets
#include <Xm/ArrowB.h>
Widget XmCreateArrowButton (Widget parent, char *name, ArgList argv, Cardinal argc)
#include <Xm/ArrowBG.h>
Widget XmCreateArrowButtonGadget (Widget parent, char *name, ArgList
argv, Cardinal argc)
#include <Xm/BulletinB.h>
Widget XmCreateBulletinBoard (Widget parent, char *name, ArgList argv, Cardinal argc)
#include <Xm/CascadeB.h>
Widget XmCreateCascadeButton (Widget parent, char *name, ArgList argv,
Cardinal argc)
#include <Xm/CascadeBG.h>
Widget XmCreateCascadeButtonGadget (Widget parent, char *name, ArgList
argv, Cardinal argc)
#include <Xm/Command.h>
Widget XmCreateCommand (Widget parent, char *name, ArgList argv, Cardinal
argc)
#include <Xm/ComboBox.h>
Widget XmCreateComboBox (Widget parent, char *name, ArgList argv, Cardinal argc)
Widget XmCreateDropDownComboBox (Widget parent, char *name, ArgList
argv, Cardinal argc)
Widget XmCreateDropDownList (Widget parent, char *name, ArgList argv, Cardinal argc)
#include <Xm/Container.h>
Widget XmCreateContainer (Widget parent, char *name, ArgList argv, Cardinal
argc)
#include <Xm/DialogS.h>
Widget XmCreateDialogShell (Widget parent, char *name, ArgList argv, Cardinal argc)
70
Motif Reference Manual
Motif Functions and Macros
XmCreate<Emphasis>Object<Default Para Font>
#include <Xm/DragIcon.h>
Widget XmCreateDragIcon (Widget parent, char *name, ArgList argv, Cardinal
argc)
#include <Xm/DrawingA.h>
Widget XmCreateDrawingArea (Widget parent, char *name, ArgList argv, Cardinal argc)
#include <Xm/DrawnB.h>
Widget XmCreateDrawnButton (Widget parent, char *name, ArgList argv, Cardinal argc)
#include <Xm/FileSB.h>
Widget XmCreateFileSelectionBox (Widget parent, char *name, ArgList argv,
Cardinal argc)
#include <Xm/Form.h>
Widget XmCreateForm (Widget parent, char *name, ArgList argv, Cardinal
argc)
#include <Xm/Frame.h>
Widget XmCreateFrame (Widget parent, char *name, ArgList argv, Cardinal
argc)
#include <Xm/GrabShell.h>
Widget XmCreateGrabShell (Widget parent, char *name, ArgList argv, Cardinal
argc)
#include <Xm/IconG.h>
Widget XmCreateIconGadget (Widget parent, char *name, ArgList argv, Cardinal argc)
#include <Xm/Label.h>
Widget XmCreateLabel (Widget parent, char *name, ArgList argv, Cardinal
argc)
#include <Xm/LabelG.h>
Widget XmCreateLabelGadget (Widget parent, char *name, ArgList argv, Cardinal argc)
#include <Xm/List.h>
Widget XmCreateList (Widget parent, char *name, ArgList argv, Cardinal argc)
#include <Xm/MainW.h>
Widget XmCreateMainWindow (Widget parent, char *name, ArgList argv, Cardinal argc)
#include <Xm/MenuShell.h>
Motif Reference Manual
71
XmCreate<Emphasis>Object<Default Para Font>
Motif Functions and Macros
Widget XmCreateMenuShell (Widget parent, char *name, ArgList argv, Cardinal argc)
#include <Xm/MessageB.h>
Widget XmCreateMessageBox (Widget parent, char *name, ArgList argv, Cardinal argc)
#include <Xm/Notebook.h>
Widget XmCreateNotebook (Widget parent, char *name, ArgList argv, Cardinal
argc)
#include <Xm/PanedW.h>
Widget XmCreatePanedWindow (Widget parent, char *name, ArgList argv, Cardinal argc)
#include <Xm/PushB.h>
Widget XmCreatePushButton (Widget parent, char *name, ArgList argv, Cardinal argc)
#include <Xm/PushBG.h>
Widget XmCreatePushButtonGadget (Widget parent, char *name, ArgList argv,
Cardinal argc)
#include <Xm/RowColumn.h>
Widget XmCreateRowColumn (Widget parent, char *name, ArgList argv, Cardinal argc)
Widget XmCreateRadioBox (Widget parent, char *name, ArgList argv, Cardinal
argc)
Widget XmCreateWorkArea (Widget parent, char *name, ArgList argv, Cardinal
argc)
#include <Xm/Scale.h>
Widget XmCreateScale (Widget parent, char *name, ArgList argv, Cardinal
argc)
#include <Xm/ScrollBar.h>
Widget XmCreateScrollBar (Widget parent, char *name, ArgList argv, Cardinal
argc)
#include <Xm/ScrolledW.h>
Widget XmCreateScrolledWindow (Widget parent, char *name, ArgList argv,
Cardinal argc)
#include <Xm/SelectioB.h>
Widget XmCreateSelectionBox (Widget parent, char *name, ArgList argv, Cardinal argc)
72
Motif Reference Manual
Motif Functions and Macros
XmCreate<Emphasis>Object<Default Para Font>
#include <Xm/Separator.h>
Widget XmCreateSeparator (Widget parent, char *name, ArgList argv, Cardinal
argc)
#include <Xm/SeparatoG.h>
Widget XmCreateSeparatorGadget (Widget parent, char *name, ArgList argv,
Cardinal argc)
#include <Xm/SSpinB.h>
Widget XmCreateSimpleSpinBox (Widget parent, char *name, ArgList argv,
Cardinal argc)
#include <Xm/SpinB.h>
Widget XmCreateSpinBox (Widget parent, char *name, ArgList argv, Cardinal
argc)
#include <Xm/Text.h>
Widget XmCreateText (Widget parent, char *name, ArgList argv, Cardinal argc)
#include <Xm/TextF.h>
Widget XmCreateTextField (Widget parent, char *name, ArgList argv, Cardinal
argc)
#include <Xm/ToggleB.h>
Widget XmCreateToggleButton (Widget parent, char *name, ArgList argv, Cardinal argc)
#include <Xm/ToggleBG.h>
Widget XmCreateToggleButtonGadget (Widget parent, char *name, ArgList
argv, Cardinal argc)
Dialog Objects
#include <Xm/BulletinB.h>
Widget XmCreateBulletinBoardDialog (Widget parent, char *name, ArgList
argv, Cardinal argc)
#include <Xm/FileSB.h>
Widget XmCreateFileSelectionDialog (Widget parent, char *name, ArgList argv,
Cardinal argc)
#include <Xm/Form.h>
Widget XmCreateFormDialog (Widget parent, char *name, ArgList argv, Cardinal argc)
#include <Xm/MessageB.h>
Widget XmCreateErrorDialog (Widget parent, char *name, ArgList argv, Cardinal argc)
Motif Reference Manual
73
XmCreate<Emphasis>Object<Default Para Font>
Motif Functions and Macros
Widget XmCreateInformationDialog (Widget parent, char *name, ArgList argv,
Cardinal argc)
Widget XmCreateMessageDialog (Widget parent, char *name, ArgList argv,
Cardinal argc)
Widget XmCreateQuestionDialog (Widget parent, char *name, ArgList argv,
Cardinal argc)
Widget XmCreateTemplateDialog (Widget parent, char *name, ArgList argv,
Cardinal argc)
Widget XmCreateWarningDialog (Widget parent, char *name, ArgList argv,
Cardinal argc)
Widget XmCreateWorkingDialog (Widget parent, char *name, ArgList argv,
Cardinal argc)
#include <Xm/SelectioB.h>
Widget XmCreatePromptDialog (Widget parent, char *name, ArgList argv, Cardinal argc)
Widget XmCreateSelectionDialog (Widget parent, char *name, ArgList argv,
Cardinal argc)
#include <Xm/Command.h>
Widget XmCreateCommandDialog (Widget parent, char *name, ArgList argv,
Cardinal argc)
Menu Objects
#include <Xm/RowColumn.h>
Widget XmCreateMenuBar (Widget parent, char *name, ArgList argv, Cardinal
argc)
Widget XmCreateOptionMenu (Widget parent, char *name, ArgList argv, Cardinal argc)
Widget XmCreatePopupMenu (Widget parent, char *name, ArgList argv, Cardinal argc)
Widget XmCreatePulldownMenu (Widget parent, char *name, ArgList argv,
Cardinal argc)
Simple Menu Objects
#include <Xm/Xm.h>
Widget XmCreateSimpleCheckBox (Widget parent, char *name, ArgList argv,
Cardinal argc)
Widget XmCreateSimpleMenuBar (Widget parent, char *name, ArgList argv,
Cardinal argc)
Widget XmCreateSimpleOptionMenu (Widget parent, char *name, ArgList argv,
Cardinal argc)
Widget XmCreateSimplePopupMenu (Widget parent, char *name, ArgList argv,
Cardinal argc)
74
Motif Reference Manual
Motif Functions and Macros
XmCreate<Emphasis>Object<Default Para Font>
Widget XmCreateSimplePulldownMenu (Widget parent, char *name, ArgList
argv, Cardinal argc)
Widget XmCreateSimpleRadioBox (Widget parent, char *name, ArgList argv,
Cardinal argc)
Scrolled Objects
#include <Xm/List.h>
Widget XmCreateScrolledList (Widget parent, char *name, ArgList argv, Cardinal argc)
#include <Xm/Text.h>
Widget XmCreateScrolledText (Widget parent, char *name, ArgList argv, Cardinal argc)
Inputs
parent
name
argv
widget.
argc
Specifies the widget ID of the parent of the new widget.
Specifies the string name of the new widget for resource lookup.
Specifies the resource name/value pairs used in creating the
Specifies the number of name/value pairs in argv.
Returns
The simple widget creation routines return the widget ID of the widget that is
created. The dialog creation routines return the widget ID of the widget that is
created as a child of the DialogShell. The menu creation routines return the
widget ID of the RowColumn widget that is created. The scrolled object creation
routines return the widget ID of the List or Text widget.
Availability
XmCreateDragIcon() and XmCreateTemplateDialog() are only available in Motif 1.2 and later.
XmCreateGrabShell(), XmCreateIconGadget(), XmCreateComboBox(),
XmCreateDropDownComboBox(), XmCreateDropDownList(), XmCreateNotebook(), XmCreateContainer(), and XmCreateSpinBox() are
available from Motif 2.0 onwards.
XmCreateSimpleSpinBox() is available from Motif 2.1 and onwards.
Description
The XmCreate*() routines are convenience routines for creating an instance of
a particular widget class or a particular compound object. Each creation routine
takes the same four arguments: the parent’s widget ID, the name of the new
widget, a list of resource name/value pairs, and the number of name/value pairs.
Motif Reference Manual
75
XmCreate<Emphasis>Object<Default Para Font>
Motif Functions and Macros
The simple creation routines create a single widget with the default resource settings for the widget class, except for XmCreateRadioBox() and XmCreateWorkArea(), which create specially configured RowColumn widgets.
The dialog creation routines are convenience routines for creating a particular
unmanaged widget as a child of a DialogShell. The parent argument specifies
the parent of the DialogShell and name specifies the string name of the particular
widget that is created. The name of the DialogShell is the string that results from
appending "_popup" to the name of the widget. The routines return the widget ID
of the widget that is created as the child of the DialogShell.
The menu creation routines are convenience routines for creating particular types
of menu objects. Each routine creates a RowColumn widget with specific
resource settings that configure the widget to operate as the particular type of
menu. XmCreatePopupMenu() and XmCreatePulldownMenu() create
the RowColumn widget as the child of a MenuShell.
Except for XmCreateSimpleSpinBox(), the simple menu creation routines
are convenience routines for creating particular configurations of RowColumn
widgets and their children. For example, XmCreateSimpleCheckBox() creates a CheckBox with ToggleButtonGadgets as its children.
XmCreateScrolledList() and XmCreateScrolledText() are convenience routines that create a List or Text widget as the child of a ScrolledWindow.
The parent argument specifies the parent of the ScrolledWindow and name specifies the string name of the List or Text widget. The name of the ScrolledWindow
is the string that results from appending "SW" to the name of the widget. The
routines return the widget ID of the List or Text widget.
Usage
Each widget or compound object that can be created with an XmCreate*() routine can also be created using XtCreateWidget(). The simple Motif creation
routines are simply veneers to XtCreateWidget(). The rest of the Motif creation routines create multiple widgets and/or set specific widget resources. In
order to use XtCreateWidget() to create these objects, you need to have a
complete understanding of the compound object that you are trying to create. For
more information on each widget and compound object that can be created, see
the appropriate manual page in Section 2, Motif and Xt Widget Classes.
76
Motif Reference Manual
Motif Functions and Macros
XmCreate<Emphasis>Object<Default Para Font>
See Also
XmArrowButtonGadget(2), XmArrowButton(2),
XmBulletinBoardDialog(2), XmBulletinBoard(2),
XmCascadeButtonGadget(2), XmCascadeButton(2),
XmCheckBox(2), XmComboBox(2), XmCommand(2),
XmCommandDialog(2), XmContainer(2), XmDialogShell(2),
XmDragIcon(2), XmDrawingArea(2), XmDrawnButton(2),
XmErrorDialog(2), XmFileSelectionBox(2),
XmFileSelectionDialog(2), XmFormDialog(2), XmForm(2),
XmFrame(2), XmGrabShell(2), XmIconGadget(2),
XmInformationDialog(2), XmLabelGadget(2), XmLabel(2),
XmList(2), XmMainWindow(2), XmMenuBar(2),
XmMenuShell(2), XmMessageBox(2), XmMessageDialog(2),
XmNotebook(2), XmOptionMenu(2), XmPanedWindow(2),
XmPopupMenu(2), XmPromptDialog(2),
XmPulldownMenu(2), XmPushButtonGadget(2)
XmPushButton(2), XmQuestionDialog(2), XmRadioBox(2),
XmRowColumn(2), XmScale(2), XmScrollBar(2),
XmScrolledList(2), XmScrolledText(2),
XmScrolledWindow(2), XmSelectionBox(2),
XmSelectionDialog(2), XmSeparatorGadget(2),
XmSeparator(2), XmSpinBox(2), XmSimpleSpinBox(2),
XmTemplateDialog(2), XmTextField(2), XmText(2),
XmToggleButtonGadget(2), XmToggleButton(2),
XmWarningDialog(2), XmWorkingDialog(2).
Motif Reference Manual
77
XmCvtByteStreamToXmString
Motif Functions and Macros
Name
XmCvtByteStreamToXmString – convert a byte stream to a compound string.
Synopsis
XmString XmCvtByteStreamToXmString (unsigned char *property)
Inputs
property
Specifies a byte stream.
Returns
An allocated compound string.
Availability
Motif 2.0 and later.
Description
XmCvtByteStreamToXmString() converts a stream of bytes to a compound
string. The function is typically used by the destination of a data transfer operation.
Usage
XmCvtByteStreamToXmString() converts a compound string in byte
stream format into an XmString. The function allocates storage for the returned
compound string, and it is the responsibility of the programmer to free the allocated memory by calling XmStringFree() at an appropriate point.
See Also
XmCvtXmStringToByteStream(1), XmStringFree(1),
78
Motif Reference Manual
Motif Functions and Macros
XmCvtCTToXmString
Name
XmCvtCTToXmString – convert compound text to a compound string.
Synopsis
XmString XmCvtCTToXmString (char *text)
Inputs
text
Specifies the compound text that is to be converted.
Returns
The converted compound string.
Description
XmCvtCTToXmString() converts the specified text string from compound text
format, which is an X Consortium Standard defined in Compound Text Encoding,
to a Motif compound string. The routine assumes that the compound text is
NULL-terminated and NULLs within the compound text are handled correctly. If
text contains horizontal tabulation (HT) control characters, the result is undefined. XmCvtCTToXmString() allocates storage for the converted compound
string. The application is responsible for freeing this storage using XmStringFree().
Usage
Compound text is an encoding that is designed to represent text from any locale.
Compound text strings identify their encoding using embedded escape
sequences. The compound text representation was standardized for X11R4 for
use as a text interchange format for interclient communication. An application
must call XtAppInitialize() before calling XmCvtCTToXmString(). The
conversion of compound text to compound strings is implementation dependent.
XmCvtCTToXmString() is the complement of XmCvtXmStringToCT().
See Also
XmCvtXmStringToCT(1).
Motif Reference Manual
79
XmCvtStringToUnitType
Motif Functions and Macros
Name
XmCvtStringToUnitType – convert a string to a unit-type value.
Synopsis
void XmCvtStringToUnitType ( XrmValuePtr
Cardinal
XrmValue
XrmValue
args,
*num_args,
*from_val,
*to_val)
Inputs
args
Specifies additional XrmValue arguments that are need to perform
the conversion.
num_args
Specifies the number of items in args.
from_val
Specifies value to convert.
Outputs
to_val
Returns the converted value.
Availability
In Motif 1.2, XmCvtStringToUnitType() is obsolete. It has been superseded by a new resource converter that uses the RepType facility.
Description
XmCvtStringToUnitType() converts the string specified in from_val to one
of the unit-type values: XmPIXELS, Xm100TH_MILLIMETERS,
Xm1000TH_INCHES, Xm100TH_POINTS, or Xm100TH_FONT_UNITS.
This value is returned in to_val.
Usage
XmCvtStringToUnitType() should not be called directly; it should be
installed as a resource converter using the R3 routine XtAddConverter(). The
routine only needs to be installed if the XmNunitType resource for a widget is
being set in a resource file. In this case, XmCvtStringToUnitType() must be
installed with XtAddConverter() before the widget is created. Use the following call to XtAddConverter() to install the converter:
XtAddConverter (XmRString, XmRUnitType, XmCvtStringToUnitType,
NULL, 0);
In Motif 1.2, the use of XmCvtStringToUnitType() as a resource converter
is obsolete. A new resource converter that uses the RepType facility has replaced
the routine.
See Also
XmGadget(2), XmManager(2), XmPrimitive(2).
80
Motif Reference Manual
Motif Functions and Macros
XmCvtTextPropertyToXmStringTable
Name
XmCvtTextPropertyToXmStringTable – convert an XTextProperty to a Compound String Table.
Synopsis
#include <Xm/TxtPropCv.h>
int XmCvtTextPropertyToXmStringTable (
Display
XTextProperty
XmStringTable
*display,
*text_prop,
int
*count_return)
*str_table_return,
Inputs
display
text_prop
Specifies the connection to the X server.
Specifies a pointer to an XTextProperty structure.
Outputs
str_table_return
count_return
The XmStringTable array converted from text_prop.
The number of XmStrings in str_table_return.
Returns
Success if the conversion succeeded, XLocaleNotSupported if the current locale
is unsupported, XConverterNotFound if no converter is available in the current
locale.
Availability
Motif 2.0 and later.
Description
XmCvtTextPropertyToXmStringTable() converts the data specified
within text_prop into an array of XmStrings, returned through str_table_return.
The number of XmStrings in the array is returned in count_return.
Usage
The XmCvtTextPropertyToXmStringTable() function converts data
specified within an XTextProperty structure into an XmStringTable. The data to
be converted is the value member of text_prop, where value is an array of bytes,
consisting of a series of concatenated items, each NULL separated. The number
of such items is given by the nitems member of text_prop. The last item is terminated by two NULL bytes. The interpretation of each item depends upon the
encoding member of text_prop.
If the encoding member of text_prop is COMPOUND_TEXT, the data is converted using the function XmCvtCTToXmString(). If encoding is
COMPOUND_STRING, the data is converted using the function XmCvt-
Motif Reference Manual
81
XmCvtTextPropertyToXmStringTable
Motif Functions and Macros
ByteStreamToXmString(). Conversion requires that a converter has been
registered for the current locale, otherwise the function returns XConverterNotFound. If encoding is XA_STRING, each returned XmString is converted
through XmStringGenerate() with a tag of "ISO8859-1" and a text type of
XmCHARSET_TEXT. If encoding is that of the current locale, each returned
XmString is converted through XmStringGenerate() with a tag of
_MOTIF_DEFAULT_LOCALE, and a text type of XmMULTIBYTE_TEXT. For
other values of encoding, the function returns XLocaleNotSupported.
XmCvtTextPropertyToXmStringTable() returns allocated storage, and
it is the responsibility of the programmer to free the utilized memory at an appropriate point by freeing each element of the array through XmStringFree(),
and subsequently the array itself through XtFree().
Structures
The XTextProperty structure is defined in <X11/Xutil.h> as follows:
typedef struct {
unsigned char
Atom
int
unsigned long
} XTextProperty;
*value;
encoding;
format;
nitems;
/* same as Property routines
*/
/* the property type
*/
/* property data format: 8, 16, or 32. */
/* number of data items in value
*/
See Also
XmCvtByteStreamToXmString(1), XmCvtCTToXmString(1),
XmStringFree(1), XmStringGenerate(1).
82
Motif Reference Manual
Motif Functions and Macros
XmCvtXmStringTableToTextProperty
Name
XmCvtXmStringTableToTextProperty – convert an XmStringTable to an XTextProperty.
Synopsis
#include <Xm/TxtPropCv.h>
int XmCvtXmStringTableToTextProperty (
play,
Display
*dis-
XmStringTable
string_table,
int
XmICCEncodingStyle
XTextProperty
count,
style,
*prop_return)
Inputs
display
string_table
count
style
string_table.
Specifies the connection to the X server.
Specifies an array of compound strings.
Specifies the number of compound strings in string_table.
Specifies the encoding style from which to convert
Outputs
prop_return
The XTextProperty structure converted from string_table.
Returns
Success if the conversion succeeded, XLocaleNotSupported if the current locale
is unsupported.
Availability
Motif 2.0 and later.
Description
XmCvtXmStringTableToTextProperty() is the inverse function to
XmCvtTextPropertyToXmStringTable(). It converts an array of compound strings, specified by string_table, into the elements of an XTextProperty
structure. The number of compound strings within the string_table is given by
count.
Usage
XmCvtXmStringTableToTextProperty() converts an XmStringTable
into the elements of an XTextProperty structure. The encoding member contains
an Atom representing the requested style. The value member contains a list of the
Motif Reference Manual
83
XmCvtXmStringTableToTextProperty
Motif Functions and Macros
converted items, each separated by NULL bytes, and terminated by two NULL
bytes, the nitems member is the number of such items converted.
If style is XmSTYLE_COMPOUND_STRING, encoding is
_MOTIF_COMPOUND_STRING, and value contains a list of XmStrings in
byte stream format.
If style is XmSTYLE_COMPOUND_TEXT, encoding is COMPOUND_TEXT,
and value contains compound text items.
If style is XmSTYLE_LOCALE, encoding is the Atom representing the encoding
for the current locale. value contains items converted into the current locale.
If style is XmSTYLE_STRING, encoding is STRING, and value contains items
converted into ISO8859-1 strings.
If style is XmSTYLE_TEXT, and all the XmStrings in string_table are convertible into the encoding for the current locale, the function behaves as though style
is XmSTYLE_LOCALE. Otherwise, the function behaves as though style is
XmSTYLE_COMPOUND_TEXT.
If style is XmSTYLE_STANDARD_ICC_TEXT, and all the XmStrings in
string_table are convertible as though the style is XmSTYLE_STRING, the function behaves as though style is indeed XmSTYLE_STRING. Otherwise, the
function behaves as though style is XmSTYLE_COMPOUND_TEXT.
XmCvtXmStringTableToTextProperty() returns XLocaleNotSupported
if the conversion cannot be performed within the current locale, or if style is not
valid. Otherwise, the function returns Success.
Structures
The XTextProperty structure is defined in <X11/Xutil.h> as follows:
typedef struct {
unsigned char
Atom
int
unsigned long
} XTextProperty;
*value;
encoding;
format;
nitems;
/* same as Property routines
*/
/* property type
*/
/* property data format: 8, 16, or 32 */
/* number of data items in value */
The possible values of the XmICCEncodingStyle parameter style are:
XmSTYLE_COMPOUND_STRING
XmSTYLE_COMPOUND_TEXT
XmSTYLE_LOCALE
XmSTYLE_STANDARD_ICC_TEXT
XmSTYLE_STRING
XmSTYLE_TEXT
84
Motif Reference Manual
Motif Functions and Macros
XmCvtXmStringTableToTextProperty
See Also
XmCvtByteStreamToXmString(1), XmCvtCTToXmString(1),
XmCvtTextPropertyToStringTable(1), XmStringFree(1),
XmStringGenerate(1).
Motif Reference Manual
85
XmCvtXmStringToByteStream
Motif Functions and Macros
Name
XmCvtXmStringToByteStream – convert a compound string to byte stream format.
Synopsis
unsigned int XmCvtXmStringToByteStream (XmString string, unsigned char
**prop_return)
Inputs
string
Specifies the compound string that is to be converted.
Outputs
prop_return
The converted compound string in byte stream format.
Returns
The number of bytes in the byte stream.
Availability
Motif 2.0 and later.
Description
XmCvtXmStringToByteStream() converts a compound string string into a
stream of bytes, returning the number of bytes required for the conversion. The
byte stream is returned in prop_return. The function is the inverse of XmCvtByteStreamToXmString().
Usage
XmCvtXmStringToByteStream() converts an XmString into byte stream
format. If prop_return is not NULL, the function places into prop_return the converted string, and returns its length in bytes. If prop_return is NULL, the number
of bytes is calculated and returned, but no conversion is performed.
XmCvtXmStringToByteStream() returns allocated storage in prop_return,
and it is the responsibility of the programmer to free the utilized memory at an
appropriate point by calling XtFree().
See Also
XmCvtByteStreamToXmString(1).
86
Motif Reference Manual
Motif Functions and Macros
XmCvtXmStringToCT
Name
XmCvtXmStringToCT – convert a compound string to compound text.
Synopsis
char * XmCvtXmStringToCT (XmString string)
Inputs
string
Specifies the compound string that is to be converted.
Returns
The converted compound text string.
Description
XmCvtXmStringToCT() converts the specified Motif compound string to a
string in X11 compound text format, which is described in the X Consortium
Standard Compound Text Encoding.
Usage
Compound text is an encoding that is designed to represent text from any locale.
Compound text strings identify their encoding using embedded escape
sequences. The compound text representation was standardized for X11R4 for
use as a text interchange format for interclient communication. XmCvtXmStringToCT() is the complement of XmCvtCTToXmString().
In Motif 1.2 and later, an application must not call XmCvtXmStringToCT()
until after XtAppInitialize() is called, so that the locale is established correctly. The routine uses the font list tag of each compound string segment to
select a compound text format for the segment. A mapping between font list tags
and compound text encoding formats is stored in a registry.
If the compound string segment tag is associated with
XmFONTLIST_DEFAULT_TAG in the registry, the converter calls XmbTextListToTextProperty() with the XCompoundTextStyle encoding style and
uses the resulting compound text for the segment. If the compound string segment tag is mapped to a registered MIT charset, the routine creates the compound
text using the charset as defined in the X Consortium Standard Compound Text
Encoding. If the compound string segment tag is associated with a charset that is
not XmFONTLIST_DEFAULT_TAG or a registered charset, the converter creates the compound text using the charset and the text as an "extended segment"
with a variable number of octets per character. If the compound string segment
tag is not mapped in the registry, the result depends upon the implementation.
See Also
XmCvtCTToXmString(1), XmMapSegmentEncoding(1),
XmRegisterSegmentEncoding(1).
Motif Reference Manual
87
XmDeactivateProtocol
Motif Functions and Macros
Name
XmDeactivateProtocol – deactivate a protocol.
Synopsis
#include <Xm/Protocols.h>
void XmDeactivateProtocol (Widget shell, Atom property, Atom protocol)
Inputs
shell
property
protocol
Specifies the widget associated with the protocol property.
Specifies the property that holds the protocol data.
Specifies the protocol atom.
Description
XmDeactivateProtocol() deactivates the specified protocol without
removing it. If the shell is realized, XmDeactivateProtocol() updates its
protocol handlers and the specified property. A protocol may be active or inactive. If protocol is active, the protocol atom is stored in property; if protocol is
inactive, the protocol atom is not stored in property.
Usage
A protocol is a communication channel between applications. Protocols are simply atoms, stored in a property on the top-level shell window for the application.
XmDeactivateProtocol() allows a client to temporarily stop participating
in the communication. The inverse routine is XmActivateProtocol().
See Also
XmActivateProtocol(1), XmDeactivateWMProtocol(1),
XmInternAtom(1), VendorShell(2).
88
Motif Reference Manual
Motif Functions and Macros
XmDeactivateWMProtocol
Name
XmDeactivateWMProtocol – deactivate the XA_WM_PROTOCOLS protocol.
Synopsis
#include <Xm/Protocols.h>
void XmDeactivateWMProtocol (Widget shell, Atom protocol)
Inputs
shell
protocol
Specifies the widget associated with the protocol property.
Specifies the protocol atom.
Description
XmDeactivateWMProtocol() is a convenience routine that calls XmDeactivateProtocol() with property set to XA_WM_PROTOCOL, the window
manager protocol property.
Usage
The property XA_WM_PROTOCOLS is a set of predefined protocols for communication between clients and window managers. XmDeactivateWMProtocol() allows a client to temporarily stop participating in the communication
with the window manager. The inverse routine is XmActivateWMProtocol().
See Also
XmActivateWMProtocol(1), XmDeactivateProtocol(1),
XmInternAtom(1), VendorShell(2).
Motif Reference Manual
89
XmDestroyPixmap
Motif Functions and Macros
Name
XmDestroyPixmap – remove a pixmap from the pixmap cache.
Synopsis
Boolean XmDestroyPixmap (Screen *screen, Pixmap pixmap)
Inputs
screen
pixmap
Specifies the screen on which the pixmap is located.
Specifies the pixmap.
Returns
True on success or False if there is no matching pixmap and screen in the cache.
Description
XmDestroyPixmap() removes the specified pixmap from the pixmap cache
when it is no longer needed. A pixmap is not completely freed until there are no
further reference to it.
Usage
The pixmap cache maintains a per-client list of the pixmaps that are in use.
Whenever a pixmap is requested using XmGetPixmap(), an internal reference
counter for the pixmap is incremented. XmDestroyPixmap() decrements this
counter, so that when it reaches 0 (zero), the pixmap is removed from the cache.
See Also
XmGetPixmap(1), XmInstallImage(1), XmUninstallImage(1).
90
Motif Reference Manual
Motif Functions and Macros
XmDirectionMatch
Name
XmDirectionMatch – compare two directions.
Synopsis
Boolean XmDirectionMatch (XmDirection dir_1, XmDirection dir_2)
Inputs
dir_1
dir_2
Specifies a direction.
Specifies a direction to compare with dir_1.
Returns
True if the directions match, otherwise False.
Availability
Motif 2.0 and later.
Description
XmDirectionMatch() is a convenience function which compares two direction values, dir_1 and dir_2, returning True or False, depending upon whether the
values are a logical match for each other.
Usage
An XmDirection consists of three parts: a horizontal component, a vertical component, and an order of precedence between each. XmDirection values match if
both the horizontal components and vertical components of each are logically the
same, and the order between the components is the same. If one value does not
have a horizontal component, this always matches the horizontal component of
the other value. Similarly, if one value has no vertical component, the vertical
component in the other value is automatically considered to match. Where a
match is found between the directions, the function returns True, otherwise False.
For example, suppose dir_1 is XmTOP_TO_BOTTOM_LEFT_TO_RIGHT.
This has a vertical component XmTOP_TO_BOTTOM, a horizontal component
XmLEFT_TO_RIGHT, the vertical component being first in the order of precedence. If dir_2 is XmLEFT_TO_RIGHT, this has no vertical component, which
automatically matches the vertical component of dir_1. The horizontal components are identical, and therefore the two directions are considered a match (it is
also a match if dir_1 is XmLEFT_TO_RIGHT_TOP_TO_BOTTOM). If dir_2 is
XmRIGHT_TO_LEFT, or XmTOP_TO_BOTTOM_RIGHT_TO_LEFT, no
match is found because the horizontal components differ, and the function returns
False. If dir_2 is XmLEFT_TO_RIGHT_TOP_TO_BOTTOM, the function also
returns False because the horizontal and vertical components, although fully
specified and equal in value, have different orders of precedence.
Motif Reference Manual
91
XmDirectionMatch
Motif Functions and Macros
Structures
Valid XmDirection values for each of dir_1 and dir_2 are:
XmLEFT_TO_RIGHT
XmBOTTOM_TO_TOP
XmBOTTOM_TO_TOP_LEFT_TO_RIGHT
XmBOTTOM_TO_TOP_RIGHT_TO_LEFT
XmTOP_TO_BOTTOM_LEFT_TO_RIGHT
XmTOP_TO_BOTTOM_RIGHT_TO_LEFT
XmLEFT_TO_RIGHT_BOTTOM_TO_TOP
XmRIGHT_TO_LEFT_BOTTOM_TO_TOP
XmLEFT_TO_RIGHT_TOP_TO_BOTTOM
XmRIGHT_TO_LEFT_TOP_TO_BOTTOM
XmRIGHT_TO_LEFT
XmTOP_TO_BOTTOM
See Also
XmDirectionMatchPartial(1),
XmDirectionToStringDirection(1),
XmStringDirectionToDirection(1),
92
Motif Reference Manual
Motif Functions and Macros
XmDirectionMatchPartial
Name
XmDirectionMatchPartial – partially compare two directions.
Synopsis
Boolean XmDirectionMatchPartial (XmDirection dir_1, XmDirection dir_2,
XmDirection mask)
Inputs
dir_1
dir_2
mask
Specifies a direction.
Specifies another direction to compare with dir_1.
Specifies whether the horizontal component
(XmHORIZONTAL_MASK), vertical component
(XmVERTICAL_MASK), or the order of component precedence
(XmPRECEDENCE_MASK) is compared.
Returns
True if the directions match, otherwise False.
Availability
Motif 2.0 and later.
Description
XmDirectionMatchPartial() is a convenience function which compares
two direction values, dir_1 and dir_2 according to the comparison rule specified
in mask.
Usage
An XmDirection consists of three logical parts: a horizontal component, a vertical component, and an order of precedence between each. The function compares
corresponding logical parts of two XmDirection values. If mask is
XmHORIZONTAL_MASK, the horizontal components of dir_1 and dir_2 are
compared. If mask is XmVERTICAL_MASK, the vertical components are compared. If mask is XmPRECEDENCE_MASK, the order of precedence between
the horizontal and vertical components is compared. If one value does not have a
particular logical part, this always matches the logical part in the second value.
Where a match is found, the function returns True, otherwise False.
For example, suppose dir_1 is XmTOP_TO_BOTTOM_LEFT_TO_RIGHT, and
that dir_2 is XmBOTTOM_TO_TOP_LEFT_TO_RIGHT. If mask is
XmHORIZONTAL_MASK, the two values match because each has an equivalent horizontal component (XmLEFT_TO_RIGHT). If mask is
XmVERTICAL_MASK, there is no match because each has different vertical
components. If mask is XmPRECEDENCE_MASK, the two values are a match
because each has the vertical component before the horizontal.
Motif Reference Manual
93
XmDirectionMatchPartial
Motif Functions and Macros
Structures
Valid XmDirection values for each of dir_1 and dir_1 are:
XmLEFT_TO_RIGHT
XmBOTTOM_TO_TOP
XmBOTTOM_TO_TOP_LEFT_TO_RIGHT
XmBOTTOM_TO_TOP_RIGHT_TO_LEFT
XmTOP_TO_BOTTOM_LEFT_TO_RIGHT
XmTOP_TO_BOTTOM_RIGHT_TO_LEFT
XmLEFT_TO_RIGHT_BOTTOM_TO_TOP
XmRIGHT_TO_LEFT_BOTTOM_TO_TOP
XmLEFT_TO_RIGHT_TOP_TO_BOTTOM
XmRIGHT_TO_LEFT_TOP_TO_BOTTOM
XmRIGHT_TO_LEFT
XmTOP_TO_BOTTOM
See Also
XmDirectionMatch(1), XmDirectionToStringDirection(1),
XmStringDirectionToDirection(1),
94
Motif Reference Manual
Motif Functions and Macros
XmDirectionToStringDirection
Name
XmDirectionToStringDirection – convert a direction to a string direction.
Synopsis
XmStringDirection XmDirectionToStringDirection (XmDirection direction)
Inputs
direction
Specifies the direction to be converted.
Returns
The equivalent XmStringDirection.
Availability
Motif 2.0 and later.
Description
XmDirectionToStringDirection() converts an XmDirection value specified by direction into an XmStringDirection value.
Usage
XmDirectionToStringDirection() converts between the XmDirection
and XmStringDirection data types. If direction has a horizontal component, that
component is converted. If the horizontal component is XmLEFT_TO_RIGHT,
the function returns XmSTRING_DIRECTION_LEFT_TO_RIGHT. If the horizontal component is XmRIGHT_TO_LEFT, the function returns
XmSTRING_DIRECTION_RIGHT_TO_LEFT. If direction has no horizontal
component, the function returns XmSTRING_DIRECTION_DEFAULT.
For example, if direction is XmRIGHT_TO_LEFT_TOP_TO_BOTTOM, the
horizontal component is XmRIGHT_TO_LEFT, and the return value is
XmSTRING_DIRECTION_RIGHT_TO_LEFT. If direction is
XmBOTTOM_TO_TOP, the value has only a vertical component, and the function returns XmSTRING_DIRECTION_DEFAULT.
See Also
XmDirectionMatch(1), XmDirectionMatchPartial(1),
XmStringDirectionToDirection(1).
Motif Reference Manual
95
XmDragCancel
Motif Functions and Macros
Name
XmDragCancel – cancel a drag operation.
Synopsis
#include <Xm/DragDrop.h>
void XmDragCancel (Widget dragcontext)
Inputs
dragcontext
Specifies the ID of the DragContext object for the drag operation
that is being cancelled.
Description
XmDragCancel() cancels the drag operation that is in progress for the specified
dragcontesxt. If the DragContext has any actions pending, they are terminated.
The routine can only be called by the client that initiated the drag operation.
XmDragCancel() frees the DragContext object associated with the drag operation.
Usage
XmDragCancel() allows an initiating client to cancel a drag operation if it
decides that the operation should not continue for whatever reason. Calling
XmDragCancel() is equivalent to the user pressing KCancel during the drag.
The XmNdropStartCallback informs the initiating client of the cancellation by
setting the dropAction field to XmDROP_CANCEL. So that it can undo any
drag-under effects under the dynamic protocol, the receiving client gets an
XmCR_DROP_SITE_LEAVE_MESSAGE when the drag is cancelled.
See Also
XmDragStart(1), XmDragContext(2).
96
Motif Reference Manual
Motif Functions and Macros
XmDragStart
Name
XmDragStart – start a drag operation.
Synopsis
#include <Xm/DragDrop.h>
Widget XmDragStart (Widget widget, XEvent *event, ArgList arglist, Cardinal
argcount)
Inputs
widget
event
arglist
argcount
Specifies the widget or gadget that contains the data that is being
dragged.
Specifies the event that caused the drag operation.
Specifies the resource name/value pairs used in creating the DragContext.
Specifies the number of name/value pairs in arglist.
Returns
The ID of the DragContext object that is created.
Availability
In Motif 2.0 and later, XmDragStart() is subsumed into the Uniform Transfer
Model (UTM). The Motif widget classes do not call XmDragStart() directly,
but install the XmQTtransfer trait to provide data transfer and conversion, and
initiate the drag through UTM mechanisms which calls XmDragStart() internally.
Description
XmDragStart() starts a drag operation by creating and returning a DragContext object. The DragContext stores information that the toolkit needs to process
a drag transaction. The DragContext object is widget-like, in that it uses
resources to specify its attributes. The toolkit frees the DragContext upon completion of the drag and drop operation.
The widget argument to XmDragStart() should be the smallest widget that
contains the source data for the drag operation. The event that starts the drag
operation must be a ButtonPress event. The arglist and argcount parameters work
as for any creation routine; any DragContext resources that are not set by the
arguments are retrieved from the resource database or set to their default values.
Usage
Motif supports the drag and drop model of selection actions. In a widget that acts
as a drag source, a user can make a selection and then drag the selection, using
BTransfer, to other widgets that are registered as drop sites. These drop sites can
be in the same application or another application.
Motif Reference Manual
97
XmDragStart
Motif Functions and Macros
The Text and TextField widgets, the List widget, and Label and its subclasses are
set up to act as drag sources by the toolkit. In order for another widget to act as a
drag source, it must have a translation for BTransfer. The action routine for the
translation calls XmDragStart(), either directly or indirectly through the UTM,
to initiate the drag and drop operation.
The only DragContext resource that must be specified when XmDragStart() is
called is the XmNconvertProc procedure. This resource specifies a procedure of
type XtConvertSelectionIncrProc that converts the source data to the format(s)
requested by the receiving client. The specification of the other resources, such as
those for operations and drag-over visuals, is optional. For more information
about the DragContext object, see the manual page in Section 2, Motif and Xt
Widget Classes].
Example
The following routines show the use of XmDragStart() in setting up a ScrollBar to function as a drag source. When the ScrollBar is created, the translations
are overridden to invoke StartDrag when BTransfer is pressed. ConvertProc,
which is not shown here, is set up by StartDrag to perform the translation of the
scrollbar data into compound text format.
/*
** XmSCOMPOUND_TEXT is defined in Motif 2.0 and
later
*/
#ifndef
XmSCOMPOUND_TEXT
#define
XmSCOMPOUND_TEXT
"COMPOUND_TEXT"
#endif /* XmSCOMPOUND_TEXT */
/* global variable */
Atom COMPOUND_TEXT;
/* start the drag operation */
static void StartDrag( Widget
XEvent
String
Cardinal
{
Arg args[10];
int n = 0;
Atom exportList[1];
widget,
*event,
*params,
*num_params)
exportList[0] = COMPOUND_TEXT;
98
Motif Reference Manual
Motif Functions and Macros
XtSetArg (args[n],
exportList); n++;
XtSetArg (args[n],
(exportList));
n++;
XtSetArg (args[n],
XmDROP_COPY); n++;
XtSetArg (args[n],
n++;
XtSetArg (args[n],
XmDragStart
XmNexportTargets,
XmNnumExportTargets, XtNumber
XmNdragOperations,
XmNconvertProc, ConvertProc);
XmNclientData, widget); n++;
XmDragStart (widget, event, args, n);
}
/* define translations and actions */
static char dragTranslations[] =
"#override <Btn2Down>: StartDrag()";
static XtActionsRec dragActions[] =
{ {"StartDrag", (XtActionProc) StartDrag} };
void main (unsigned int argc, char **argv)
{
Arg
args[10];
int
n;
Widget
top, bboard, scrollbar;
XtAppContext
app;
XtTranslations parsed_trans;
XtSetLanguageProc (NULL, (XtLanguageProc) NULL,
NULL);
top = XtAppInitialize (&app, "Drag", NULL, 0,
&argc, argv, NULL, NULL,
0);
COMPOUND_TEXT = XInternAtom (XtDisplay (widget),
XmSCOMPOUND_TEXT,
False);
n = 0;
bboard = XmCreateBulletinBoard (top, "bboard",
args, n);
XtManageChild (bboard);
/* override button two press to start a drag */
Motif Reference Manual
99
XmDragStart
Motif Functions and Macros
parsed_trans = XtParseTranslationTable
(dragTranslations);
XtAppAddActions (app, dragActions, XtNumber
(dragActions));
n = 0;
XtSetArg (args[n], XmNtranslations,
parsed_trans); n++;
XtSetArg (args[n], XmNorientation, XmHORIZONTAL); n++;
XtSetArg (args[n], XmNwidth, 100); n++;
scrollbar = XmCreateScrollBar (bboard, "scrollbar", args, n);
XtManageChild (scrollbar);
XtRealizeWidget (top);
XtAppMainLoop (app);
}
See Also
XmDragCancel(1), XmTransfer(1), XmDragContext(2).
100
Motif Reference Manual
Motif Functions and Macros
XmDropSiteConfigureStackingOrder
Name
XmDropSiteConfigureStackingOrder – change the stacking order of a drop site.
Synopsis
#include <Xm/DragDrop.h>
void XmDropSiteConfigureStackingOrder (Widget widget, Widget sibling, Cardinal stack_mode)
Inputs
widget
sibling
stack_mode
XmBELOW.
Specifies the widget ID associated with the drop site.
Specifies an optional widget ID of a sibling drop site.
Specifies the stacking position. Pass either XmABOVE or
Description
XmDropSiteConfigureStackingOrder() changes the stacking order of a
drop site relative to its siblings. The routine changes the stacking order of the
drop site associated with the specified widget. The stacking order is changed only
if the drop sites associated with widget and sibling are siblings in both the widget
hierarchy and the drop site hierarchy. The parent of both of the widgets must be
registered as a composite drop site.
If sibling is specified, the stacking order of the drop site is changed relative to the
stack position of the drop site associated with sibling, based on the value of
stack_mode. If stack_mode is XmABOVE, the drop site is positioned just above
the sibling; if stack_mode is XmBELOW, the drop site is positioned just below
the sibling. If sibling is not specified, a stack_mode of XmABOVE causes the
drop site to be placed at the top of the stack, while a stack_mode of XmBELOW1
causes it to be placed at the bottom of the stack.
Usage
A drop site for drag and drop operations can be a composite drop site, which
means that it has children which are also drop sites. The stacking order of the
drop sites controls clipping of drag-under effects during a drag and drop operation. When drop sites overlap, the drag-under effects of the drop sites lower in the
stacking order are clipped by the drop sites above them, regardless of whether or
not the drop sites are active. You can use XmDropSiteConfigureStackingOrder() to modify the stacking order. Use XmDropSiteQueryStackingOrder() to get the current stacking order.
See Also
XmDropSiteQueryStackingOrder(1),
XmDropSiteRegister(1), XmDropSite(2)
1.Erroneously given as BELOW in 1st and 2nd editions.
Motif Reference Manual
101
XmDropSiteEndUpdate
Motif Functions and Macros
Name
XmDropSiteEndUpdate – end an update of multiple drop sites.
Synopsis
#include <Xm/DragDrop.h>
void XmDropSiteEndUpdate (Widget widget)
Inputs
widget
Specifies any widget in the hierarchy associated with the drop sites
that are to be updated.
Description
XmDropSiteEndUpdate() finishes an update of multiple drop sites. The
widget parameter specifies a widget in the widget hierarchy that contains all of
the widgets associated with the drop sites being updated. The routine uses widget
to identify the shell that contains all of the drop sites.
Usage
XmDropSiteEndUpdate() is used with XmDropSiteStartUpdate() and
XmDropSiteUpdate() to update information about multiple drop sites in the
DropSite registry. XmDropSiteStartUpdate() starts the update processing,
XmDropSiteUpdate() is called multiple times to update information about
different drop sites, and XmDropSiteEndUpdate() completes the processing.
These routines optimize the updating of drop site information. Calls to XmDropSiteStartUpdate() and XmDropSiteEndUpdate() can be nested recursively.
See Also
XmDropSiteStartUpdate(1), XmDropSiteUpdate(1),
XmDropSite(2).
102
Motif Reference Manual
Motif Functions and Macros
XmDropSiteQueryStackingOrder
Name
XmDropSiteQueryStackingOrder – get the stacking order of a drop site.
Synopsis
#include <Xm/DragDrop.h>
Status XmDropSiteQueryStackingOrder ( Widget
Widget
Widget
Cardinal
Inputs
widget
site.
Outputs
parent_return
widget.
child_returns
as drop sites.
num_child_returns
widget,
*parent_return,
**child_returns,
*num_child_returns)
Specifies the widget ID associated with a composite drop
Returns the widget ID of the parent of the specified
Returns a list of the children of widget that are registered
Returns the number of children in child_returns.
Returns
A non-zero value on success or 0 (zero) on failure.
Description
XmDropSiteQueryStackingOrder() retrieves information about the
stacking order of drop sites. For the specified widget, the routine returns its parent
and a list of its children that are registered as drop sites. The children are returned
in child_returns, which lists the children in the current stacking order, with the
lowest child in the stacking order at the beginning of the list and the top child at
the end of the list. XmDropSiteQueryStackingOrder() allocates storage
for the list of returned children. The application is responsible for managing this
storage, which can be freed using XtFree(). The routine returns a non-zero
value on success or 0 (zero) on failure.
Motif Reference Manual
103
XmDropSiteQueryStackingOrder
Motif Functions and Macros
Usage
A drop site for drag and drop operations can be a composite drop site, which
means that it has children which are also drop sites. The stacking order of the
drop sites controls clipping of drag-under effects during a drag and drop operation. When drop sites overlap, the drag-under effects of the drop sites lower in the
stacking order are clipped by the drop sites above them, regardless of whether or
not the drop sites are active. Use XmDropSiteQueryStackingOrder() to
get the current stacking order for a composite drop site. You can use XmDropSiteConfigureStackingOrder() to modify the stacking order.
Text, TextField, and Container widgets are automatically registered as drop sites
by the Motif toolkit.
See Also
XmDropSiteConfigureStackingOrder(1),
XmDropSiteRegister(1), XmDropSite(2).
104
Motif Reference Manual
Motif Functions and Macros
XmDropSiteRegister
Name
XmDropSiteRegister – register a drop site.
Synopsis
#include <Xm/DragDrop.h>
void XmDropSiteRegister (Widget widget, ArgList arglist, Cardinal argcount)
Inputs
widget
arglist
site.
argcount
Specifies the widget ID that is to be associated with the drop site.
Specifies the resource name/value pairs used in registering the drop
Specifies the number of name/value pairs in arglist.
Availability
In Motif 2.0 and later, XmDropSiteRegister() is subsumed into the Uniform
Transfer Model (UTM). The Motif widget classes do not call XmDropSiteRegister() directly, but initiate the site through UTM mechanisms which
call XmDropSiteRegister() internally. The callbacks specified by the
XmNdestinationCallback resource of a widget handle the data drop.
Description
XmDropSiteRegister() registers the specified widget as a drop site, which
means the widget has a drop site associated with it in the DropSite registry. Drop
sites are widget-like, in that they use resources to specify their attributes. The
arglist and argcount parameters work as for any creation routine; any drop site
resources that are not set by the arguments are retrieved from the resource database or set to their default values. If the drop site is registered with XmNdropSiteActivity set to XmDROP_SITE_ACTIVE and XmNdropProc set to NULL,
the routine generates a warning message.
Usage
Motif supports the drag and drop model of selection actions. In a widget that acts
as a drag source, a user can make a selection and then drag the selection, using
BTransfer, to other widgets that are registered as drop sites. The DropSite registry stores information about all of the drop sites for a display. Text and TextField
widgets are automatically registered as drop sites when they are created. An
application can register other widgets as drop sites using XmDropSiteRegister(). Once a widget is registered as a drop site, it can participate in drag and
drop operations. A drop site can be removed from the registry using XmDropSiteUnregister(). When a drop site is removed, the widget no longer participates in drag and drop operations.
Motif Reference Manual
105
XmDropSiteRegister
Motif Functions and Macros
A drop site for drag and drop operations can be a composite drop site, which
means that it has children which are also drop sites. If the drop site being registered is a descendant of a widget that has already been registered as a drop site,
the XmNdropSiteType resource of the ancestor must be set to
XmDROP_SITE_COMPOSITE. A composite drop site must be registered as a
drop site before its descendants are registered. The stacking order of the drop
sites controls clipping of drag-under effects during a drag and drop operation.
When drop sites overlap, the drag-under effects of the drop sites lower in the
stacking order are clipped by the drop sites above them, regardless of whether or
not the drop sites are active. When a descendant drop site is registered, it is
stacked above all of its sibling drop sites that have already been registered.
Example
The following routine shows the use of XmDropSiteRegister() to register a
Label widget as a drop site. When a drop operation occurs in the Label, the HandleDrop routine, which is not shown here, handles the drop:
/* global variable */
Atom COMPOUND_TEXT;
void main (unsigned int argc, char **argv)
{
Arg
args[10];
int
n;
Widget
top, bb, label;
XtAppContext app;
Atom
importList[1];
XtSetLanguageProc (NULL, (XtLanguageProc) NULL,
NULL);
top = XtAppInitialize (&app, "Drop", NULL, 0,
&argc, argv, NULL, NULL,
0);
n = 0;
bb = XmCreateBulletinBoard (top, "bb", args, n);
XtManageChild (bb);
COMPOUND_TEXT = XInternAtom (XtDisplay (top),
"COMPOUND_TEXT",
False);
n = 0;
label = XmCreateLabel (bb, "Drop Here", args,
n);
106
Motif Reference Manual
Motif Functions and Macros
XmDropSiteRegister
XtManageChild (label);
/* register the label as a drop site */
importList[0] = COMPOUND_TEXT;
n = 0;
XtSetArg (args[n], XmNimportTargets,
importList); n++;
XtSetArg (args[n], XmNnumImportTargets, XtNumber
(importList)); n++;
XtSetArg (args[n], XmNdropSiteOperations,
XmDROP_COPY); n++;
XtSetArg (args[n], XmNdropProc, HandleDrop);
n++;
XmDropSiteRegister (label, args, n);
XtRealizeWidget (top);
XtAppMainLoop (app);
}
See Also
XmDropSiteConfigureStackingOrder(1),
XmDropSiteEndUpdate(1), XmDropSiteQueryStackingOrder(1),
XmDropSiteRetrieve(1), XmDropSiteStartUpdate(1),
XmDropSiteUpdate(1), XmDropSiteUnregister(1),
XmTransfer(1), XmDisplay(2), XmDropSite(2), XmScreen(2).
Motif Reference Manual
107
XmDropSiteRetrieve
Motif Functions and Macros
Name
XmDropSiteRetrieve – get the resource values for a drop site.
Synopsis
#include <Xm/DragDrop.h>
void XmDropSiteRetrieve (Widget widget, ArgList arglist, Cardinal argcount)
Inputs
widget
arglist
argcount
Specifies the widget ID associated with the drop site.
Specifies the resource name/address pairs that contain the resource
names and addresses into which the resource values are stored.
Specifies the number of name/value pairs in arglist.
Description
XmDropSiteRetrieve() gets the specified resources for the drop site associated with the specified widget. Drop sites are widget-like, in that they use
resources to specify their attributes. The arglist and argcount parameters work as
for XtGetValues().
Usage
XmDropSiteRetrieve() can be used to get the current attributes of a drop
site from the DropSite registry. The DropSite registry stores information about all
of the drop sites for a display. An initiating client can also use XmDropSiteRetrieve() to retrieve information about the current drop site by passing the
DragContext for the operation to the routine. The initiator can access all of the
drop site resources except XmNdragProc and XmNdropProc1 using this technique.
See Also
XmDropSiteRegister(1), XmDropSiteUpdate(1), XmDropSite(2).
1.Erroneously given as XmdropProc in 1st and 2nd editions.
108
Motif Reference Manual
Motif Functions and Macros
XmDropSiteStartUpdate
Name
XmDropSiteStartUpdate – start an update of multiple drop sites.
Synopsis
#include <Xm/DragDrop.h>
void XmDropSiteStartUpdate (Widget widget)
Inputs
widget
Specifies any widget in the hierarchy associated with the drop sites
that are to be updated.
Description
XmDropSiteStartUpdate() begins an update of multiple drop sites. The
widget parameter specifies a widget in the widget hierarchy that contains all of
the widgets associated with the drop sites being updated. The routine uses widget
to identify the shell that contains all of the drop sites.
Usage
XmDropSiteStartUpdate() is used with XmDropSiteUpdate() and
XmDropSiteEndUpdate() to update information about multiple drop sites in
the DropSite registry. XmDropSiteStartUpdate() starts the update processing, XmDropSiteUpdate() is called multiple times to update information
about different drop sites, and XmDropSiteEndUpdate() completes the
processing. These routines optimize the updating of drop site information. Calls
to XmDropSiteStartUpdate() and XmDropSiteEndUpdate() can be
nested recursively.
See Also
XmDropSiteEndUpdate(1), XmDropSiteUpdate(1), XmDropSite(2).
Motif Reference Manual
109
XmDropSiteUnregister
Motif Functions and Macros
Name
XmDropSiteUnregister – remove a drop site.
Synopsis
#include <Xm/DragDrop.h>
void XmDropSiteUnregister (Widget widget)
Inputs
widget
Specifies the widget ID associated with the drop site.
Description
XmDropSiteUnregister() removes the drop site associated with the specified widget from the DropSite registry. After the routine is called, the widget cannot be the receiver in a drag and drop operation. The routine frees all of the
information associated with the drop site.
Usage
Motif supports the drag and drop model of selection actions. In a widget that acts
as a drag source, a user can make a selection and then drag the selection, using
BTransfer, to other widgets that are registered as drop sites. Once a widget is
registered as a drop site with XmDropSiteRegister(), it can participate in
drag and drop operations. Text and TextField widgets are automatically registered as drop sites when they are created. XmDropSiteUnregister() provides a way to remove a drop site from the registry, so that the widget no longer
participates in drag and drop operations.
See Also
XmDropSiteRegister(1), XmDropSite(2).
110
Motif Reference Manual
Motif Functions and Macros
XmDropSiteUpdate
Name
XmDropSiteUpdate – change the resource values for a drop site.
Synopsis
#include <Xm/DragDrop.h>
void XmDropSiteUpdate (Widget widget, ArgList arglist, Cardinal argcount)
Inputs
widget
arglist
site.
argcount
Specifies the widget ID associated with the drop site.
Specifies the resource name/value pairs used in updating the drop
Specifies the number of name/value pairs in arglist.
Description
XmDropSiteUpdate() changes the resources for the drop site associated with
the specified widget. Drop sites are widget-like, in that they use resources to
specify their attributes. The arglist and argcount parameters work as for XtSetValues().
Usage
XmDropSiteUpdate() can be used by itself to update the attributes of a drop
site. The routine can also be used with XmDropSiteStartUpdate() and
XmDropSiteEndUpdate() to update information about multiple drop sites in
the DropSite registry. XmDropSiteStartUpdate() starts the update
processing, XmDropSiteUpdate() is called multiple times to update information about different drop sites, and XmDropSiteEndUpdate() completes the
processing. The DropSite registry stores information about all of the drop sites
for a display. These routines optimize the updating of drop site information by
sending all of the updates at once, rather than processing each one individually.
See Also
XmDropSiteEndUpdate(1), XmDropSiteRegister(1),
XmDropSiteStartUpdate(1), XmDropSiteUnregister(1),
XmDropSite(2).
Motif Reference Manual
111
XmDropTransferAdd
Motif Functions and Macros
Name
XmDropTransferAdd – add drop transfer entries to a drop operation.
Synopsis
#include <Xm/DragDrop.h>
void XmDropTransferAdd ( Widget
XmDropTransferEntryRec
Cardinal
drop_transfer,
*transfers,
num_transfers)
Inputs
drop_transfer
Specifies the ID of the DropTransfer object to which the entries
are being added.
transfers
Specifies the additional drop transfer entries.
num_transfer
Specifies the number of drop transfer entries in transfers.
Availability
In Motif 2.0 and later, the drag and drop mechanisms are rationalized as part of
the Uniform Transfer Model. Motif widget classes do not call XmDropTransferAdd() directly, but call XmTransferValue() to transfer data to a destination.
XmTransferValue() calls XmDropTransferAdd() internally as the need
arises.
Description
XmDropTransferAdd() specifies a list of additional drop transfer entries that
are to be processed during a drop operation. The widget argument specifies the
DropTransfer object associated with the drop operation. transfers is an array of
XmDropTransferEntryRec structures that specifies the targets of the additional
drop transfer operations. XmDropTransferAdd() can be used to modify the
DropTransfer object until the last call to the XmNtransferProc is made. After the
last call, the result of modifying the DropTransfer object is undefined.
Usage
The toolkit uses the DropTransfer object to manage the transfer of data from the
drag source to the drop site during a drag and drop operation. XmDropTransferAdd() provides a way for a drop site to specify additional target formats after
a drop operation has started. The routine adds the entries to the XmNdropTransfers resource. The attributes of a DropTransfer object can also be manipulated
with XtSetValues() and XtGetValues().
112
Motif Reference Manual
Motif Functions and Macros
XmDropTransferAdd
Structures
XmDropTransferEntryRec is defined as follows:
typedef struct {
XtPointer
client_data;
/* data passed to the transfer proc */
Atom
target;
/* target format of the transfer */
} XmDropTransferEntryRec, *XmDropTransferEntry;
See Also
XmDropTransferStart(1), XmTransferValue(1),
XmDragContext(2), XmDropTransfer(2).
Motif Reference Manual
113
XmDropTransferStart
Motif Functions and Macros
Name
XmDropTransferStart – start a drop operation.
Synopsis
#include <Xm/DragDrop.h>
Widget XmDropTransferStart (Widget widget, ArgList arglist, Cardinal argcount)
Inputs
widget
Specifies the ID of the DragContext object associated with the
operation.
arglist
Specifies the resource name/value pairs used in creating the
DropTransfer.
argcount
Specifies the number of name/value pairs in arglist.
Returns
The ID of the DropTransfer object that is created.
Availability
In Motif 2.0 and later, the drag and drop mechanisms are rationalized as part of
the Uniform Transfer Model. XmDropTransferStart() is called on request
internally as the need arises by the destination callback handlers, or through the
XmTransferValue() and XmTransferDone() functions.
Description
XmDropTransferStart() starts a drop operation by creating and returning a
DropTransfer object. The DropTransfer stores information that the toolkit needs
to process a drop transaction. The DropTransfer is widget-like, in that it uses
resources to specify its attributes. The toolkit frees the DropTransfer upon completion of the drag and drop operation.
The widget argument to XmDropTransferStart() is the DragContext object
associated with the drag operation. The arglist and argcount parameters work as
for any creation routine; any DropTransfer resources that are not set by the arguments are retrieved from the resource database or set to their default values.
Usage
Motif 1.2 supports the drag and drop model of selection actions. In a widget that
acts as a drag source, a user can make a selection and then drag the selection,
using BTransfer, to other widgets that are registered as drop sites. These drop
sites can be in the same application or another application. The toolkit uses the
DropTransfer object to manage the transfer of data from the drag source to the
drop site. XmDropTransferStart() is typically called from within the XmNdropProc procedure of the drop site.
114
Motif Reference Manual
Motif Functions and Macros
XmDropTransferStart
The attributes of a DropTransfer object can be manipulated with XtSetValues() and XtGetValues() until the last call to the XmNtransferProc procedure is made. You can also use XmDropTransferAdd() to add drop transfer
entries to be processed. After the last call to XmNtransferProc, the result of using
the DropTransfer object is undefined. For more information about the DropTransfer object, see the manual page in Section 2, Motif and Xt Widget Classes.
Example
The following routine shows the use of XmDropTransferStart() in the
HandleDrop routine, which is the XmNdropProc procedure for a Label widget
that is being used as a drop site. The data transfer procedure TransferProc()
which presumably translates the data in the Label into compound text format, is
not shown.
/* global variable */
Atom COMPOUND_TEXT;
static void HandleDrop(Widget
widget,
XtPointer client_data,
XtPointer call_data)
{
XmDropProcCallback
DropData;
XmDropTransferEntryRec transferEntries[1];
XmDropTransferEntry
transferList;
Arg
args[10];
int
n;
DropData = (XmDropProcCallback) call_data;
n = 0;
if ( (DropData->dropAction != XmDROP) ||
(DropData->operation != XmDROP_COPY)) {
XtSetArg (args[n], XmNtransferStatus,
XmTRANSFER_FAILURE);
n++;
}
else {
transferEntries[0].target = COMPOUND_TEXT;
transferEntries[0].client_data = (XtPointer)
widget;
transferList = transferEntries;
XtSetArg (args[n], XmNdropTransfers, transferEntries); n++;
XtSetArg (args[n], XmNnumDropTransfers,
Motif Reference Manual
115
XmDropTransferStart
Motif Functions and Macros
XtNumber (transferEntries)); n++;
XtSetArg (args[n], XmNtransferProc, TransferProc); n++;
}
XmDropTransferStart (DropData->dragContext,
args, n);
}
See Also
XmDropTransferAdd(1), XmTransferValue(1), XmTransferDone(1),
XmDragContext(2), XmDropTransfer(2).
116
Motif Reference Manual
Motif Functions and Macros
XmFileSelectionBoxGetChild
Name
XmFileSelectionBoxGetChild – get the specified child of a FileSelectionBox
widget.
Synopsis
#include <Xm/FileSB.h>
Widget XmFileSelectionBoxGetChild (Widget widget, unsigned char child)
Inputs
widget
child
Specifies the FileSelectionBox widget.
Specifies the child of the FileSelectionBox widget. Possible values
are defined below.
Returns
The widget ID of the specified child of the FileSelectionBox.
Availability
From Motif 2.0, XmFileSelectionBoxGetChild() is deprecated code.
XtNameToWidget() is the preferred method of accessing children of the
widget.
Description
XmFileSelectionBoxGetChild() returns the widget ID of the specified
child of the FileSelectionBox widget.
Usage
XmDIALOG_APPLY_BUTTON, XmDIALOG_CANCEL_BUTTON,
XmDIALOG_HELP_BUTTON, and XmDIALOG_OK_BUTTON specify the
action buttons in the widget. XmDIALOG_DEFAULT_BUTTON specifies the
current default button. XmDIALOG_DIR_LIST and
XmDIALOG_DIR_LIST_LABEL specify the directory list and its label, while
XmDIALOG_LIST and XmDIALOG_LIST_LABEL specify the file list and its
label. XmDIALOG_FILTER_LABEL and XmDIALOG_FILTER_TEXT specify the filter text entry area and its label, while XmDIALOG_TEXT and
XmDIALOG_SELECTION_LABEL specify the file text entry area and its label.
XmDIALOG_SEPARATOR specifies the separator and
XmDIALOG_WORK_AREA specifies any work area child that has been added
to the FileSelectionBox.
In Motif 2.0 and later, if the resource XmNpathMode is
XmPATH_MODE_RELATIVE, the directory pattern specification is displayed in
two text fields, rather than the single filter text entry area. When this is the case,
the pattern is displayed in the original filter text area, and the directory portion is
displayed in an additional text field called DirText. The Label associated with the
Motif Reference Manual
117
XmFileSelectionBoxGetChild
Motif Functions and Macros
DirText child is called DirL. No corresponding mask has been defined to access
this extra text field or its Label through XmFileSelectionBoxGetChild():
XtNameToWidget() should be used to access the DirText widget ID when
required.
For more information on the different children of the FileSelectionBox, see the
manual page in Section 2, Motif and Xt Widget Classes.
Widget Hierarchy
As of Motif 2.0, most Motif composite child fetch routines are marked as deprecated. However, since it is not possible to fetch the
XmDIALOG_DEFAULT_BUTTON or XmDIALOG_WORK_AREA children
using a public interface except through XmSelectionBoxGetChild()1, the routine
should not be considered truly deprecated. For consistency with the preferred
new style, when fetching all other child values, consider giving preference to the
Intrinsics routine XtNameToWidget(), passing one of the following names as the
second parameter:
“Apply”
“Cancel”
“OK”
“Separator”
“Help”
“Symbol”
“Message”
“*ItemsList”2
“Items”
“Selection”
“Text”
“*DirList“3
“Dir“
“FilterLabel“
“FilterText“
“DirL“
“DirText“
(XmDIALOG_APPLY_BUTTON)
(XmDIALOG_CANCEL_BUTTON)
(XmDIALOG_OK_BUTTON)
(XmDIALOG_SEPARATOR)
(XmDIALOG_HELP_BUTTON)
(XmDIALOG_SYMBOL_LABEL)
(XmDIALOG_MESSAGE_LABEL)
(XmDIALOG_LIST)
(XmDIALOG_LIST_LABEL)
(XmDIALOG_SELECTION_LABEL)
(XmDIALOG_TEXT)
(XmDIALOG_DIR_LIST)
(XmDIALOG_DIR_LIST_LABEL)
(XmDIALOG_FILTER_LABEL)
(XmDIALOG_FILTER_TEXT)
(no macro - must use XtNameToWidget()))
(no macro - must use XtNameToWidget())
1.Called internally by XmFileSelectionBoxGetChild().
2.The “*” is important: the Files List is not a direct child of the SelectionBox, but of a ScrolledList.
3.As above; the Directories list is a child of a ScrolledWindow, not the SelectionBox itself.
118
Motif Reference Manual
Motif Functions and Macros
XmFileSelectionBoxGetChild
CDE variants of the Motif 2.1 toolkit may support a ComboBox in place of the
Directory Text field (DirText). This is known as “DirComboBox”, and also has
no defined public macro1:
“DirComboBox”
(no macro - must use XtNameToWidget())
Structures
The possible values for child are:
XmDIALOG_APPLY_BUTTON
XmDIALOG_CANCEL_BUTTON
XmDIALOG_DEFAULT_BUTTON
XmDIALOG_DIR_LIST
XmDIALOG_SELECTION_LABEL
XmDIALOG_DIR_LIST_LABEL
XmDIALOG_FILTER_LABEL
XmDIALOG_FILTER_TEXT
XmDIALOG_HELP_BUTTON
XmDIALOG_LIST
XmDIALOG_LIST_LABEL
XmDIALOG_OK_BUTTON
XmDIALOG_SEPARATOR
XmDIALOG_TEXT
XmDIALOG_WORK_AREA
See Also
XmFileSelectionBox(2).
1.The ComboBox, containing a List of directories, is enabled if the CDE resource XmNenableFsbPickList is true.
Motif Reference Manual
119
XmFileSelectionDoSearch
Motif Functions and Macros
Name
XmFileSelectionDoSearch – start a directory search.
Synopsis
#include <Xm/FileSB.h>
void XmFileSelectionDoSearch (Widget widget, XmString dirmask)
Inputs
widget
dirmask
Specifies the FileSelectionBox widget.
Specifies the directory mask that is used in the directory search.
Description
XmFileSelectionDoSearch() starts a directory and file search for the
specified FileSelectionBox widget. dirmask is a text pattern that can include
wildcard characters. XmFileSelectionDoSearch() updates the lists of
directories and files that are displayed by the FileSelectionBox. If dirmask is nonNULL, the routine restricts the search to directories that match the dirmask.
Usage
XmFileSelectionDoSearch()1 allows you to force a FileSelectionBox to
reinitialize itself, which is useful if you want to set the directory mask directly.
See Also
XmFileSelectionBox(2).
1.Erroneously given as XmFileSelectionBoxDoSearch() in 1st and 2nd editions.
120
Motif Reference Manual
Motif Functions and Macros
XmFontListAdd
Name
XmFontListAdd – create a new font list.
Synopsis
XmFontList XmFontListAdd (XmFontList oldlist, XFontStruct *font, XmStringCharSet charset)
Inputs
oldlist
font
charset
Specifies the font list to which font is added.
Specifies the font structure.
Specifies a tag that identifies the character set for the font.
Returns
The new font list, oldlist if font or charset is NULL, or NULL if oldlist is NULL.
Availability
In Motif 2.0 and later, the XmFontList and XmFontListEntry are obsolete. They
are superseded by the XmRenderTable type and the XmRendition object respectively. To maintain backwards compatibility, the XmFontList is re-implemented
as a render table.
Description
XmFontListAdd() makes a new font list by adding the font structure specified
by font to the old font list. The routine returns the new font list and deallocates
oldlist. charset specifies the character set that is associated with the font. It can
be XmSTRING_DEFAULT_CHARSET, which takes the character set from the
current language environment, but this value may be removed from future versions of Motif.
XmFontListAdd() searches the font list cache for a font list that matches the
new font list. If the routine finds a matching font list, it returns that font list and
increments its reference count. Otherwise, the routine allocates space for the new
font list and caches it. In either case, the application is responsible for managing
the memory associated with the font list. When the application is done using the
font list, it must be freed using XmFontListFree().
Motif Reference Manual
121
XmFontListAdd
Motif Functions and Macros
Usage
In Motif 1.1 and 1.2, a font list contains entries that describe the fonts that are in
use. In Motif 1.1, each entry associates a font and a character set. In Motif 1.2,
each entry consists of a font or a font set and an associated tag. In Motif 2.0 and
later, the XmFontList is implemented using the XmRenderTable type. XmRendition objects within a render table represent the font entries. XmFontListAdd()
returns a reference counted render table.
XmFontListAdd() is retained for compatibility with Motif 1.2 and should not
be used in newer applications.
See Also
XmFontListAppendEntry(1), XmFontListFree(1),
XmRenderTableAddRenditions(1), XmRenditionCreate(1),
XmRendition(2).
122
Motif Reference Manual
Motif Functions and Macros
XmFontListAppendEntry
Name
XmFontListAppendEntry – append a font entry to a font list.
Synopsis
XmFontList XmFontListAppendEntry (XmFontList oldlist, XmFontListEntry
entry)
Inputs
oldlist
entry
Specifies the font list to which entry is appended.
Specifies the font list entry.
Returns
The new font list or oldlist if entry is NULL.
Availability
Motif 1.2 and later. In Motif 2.0 and later, the XmFontList and XmFontListEntry
are obsolete. They are superseded by the XmRenderTable type and the XmRendition object respectively.
Description
XmFontListAppendEntry() makes a new font list by appending the specified entry to the old font list. If oldlist is NULL, the routine creates a new font list
that contains the single entry. XmFontListAppendEntry() returns the new
font list and deallocates oldlist. The application is responsible for freeing the font
list entry using XmFontListEntryFree().
XmFontListAppendEntry() searches the font list cache for a font list that
matches the new font list. If the routine finds a matching font list, it returns that
font list and increments its reference count. Otherwise, the routine allocates
space for the new font list and caches it. In either case, the application is responsible for managing the memory associated with the font list. When the application is done using the font list, it should be freed using XmFontListEntryFree().
Usage
In Motif 1.2, a font list contains font list entries, where each entry consists of a
font or font set and an associated tag. Before a font list can be added to a font list,
it has to be created with XmFontListEntryCreate() or XmFontListEntryLoad(). In Motif 2.0 and later, the XmFontList is an alias for the
XmRenderTable type. XmRendition objects within a render table represent the
font entries. XmFontListAppendEntry() returns a reference counted render
table.
XmFontListAppendEntry() is retained for compatibility with Motif 1.2 and
should not be used in newer applications.
Motif Reference Manual
123
XmFontListAppendEntry
Motif Functions and Macros
See Also
XmFontListEntryCreate(1), XmFontListEntryFree(1),
XmFontListEntryLoad(1), XmFontListFree(1),
XmFontListRemoveEntry(1), XmRenderTableAddRenditions(1),
XmRenditionCreate(1), XmRendition(2).
124
Motif Reference Manual
Motif Functions and Macros
XmFontListCopy
Name
XmFontListCopy – copy a font list.
Synopsis
XmFontList XmFontListCopy (XmFontList fontlist)
Inputs
fontlist
Specifies the font list to be copied.
Returns
The new font list or NULL if fontlist is NULL.
Availability
In Motif 2.0 and later, the XmFontList and XmFontListEntry are obsolete. They
are superseded by the XmRenderTable type and the XmRendition object respectively.
Description
XmFontListCopy() makes and returns a copy of fontlist.
The routine searches the font list cache for the font list, returns the font list, and
increments its reference count. The application is responsible for managing the
memory associated with the font list. When the application is done using the font
list, it should be freed using XmFontListFree().
Usage
A font list contains entries that describe the fonts that are in use. In Motif 1.1,
each entry associates a font and a character set. In Motif 1.2, each entry consists
of a font or a font set and an associated tag. In Motif 2.0 and later, the
XmFontList is an alias for the XmRenderTable type. XmRendition objects within
a render table represent the font entries. XmFontListCopy() is a convenience
routine which calls XmRenderTableCopy() to copy and return a reference
counted render table.
XmFontListCopy() makes a correct copy of the font list regardless of the type
of entries in the list.
When a font list is assigned to a widget, the widget makes a copy of the font list,
so it is safe to free the font list. When you retrieve a font list from a widget using
XtGetValues(), you should not alter the font list directly. If you need to make
changes to the font list, use XmFontListCopy() to make a copy of the font list
and then change the copy.
XmFontListCopy() is retained for compatibility with Motif 1.2 and should not
be used in newer applications.
Motif Reference Manual
125
XmFontListCopy
Motif Functions and Macros
See Also
XmFontListFree(1), XmRenderTableCopy(1),
XmRenditionCreate(1), XmRendition(2)
126
Motif Reference Manual
Motif Functions and Macros
XmFontListCreate
Name
XmFontListCreate – create a font list.
Synopsis
XmFontList XmFontListCreate (XFontStruct *font, XmStringCharSet charset)
Inputs
font
charset
Specifies the font structure.
Specifies a tag that identifies the character set for the font.
Returns
The new font list or NULL if font or charset is NULL.
Availability
In Motif 2.0 and later, the XmFontList and XmFontListEntry are obsolete. They
are superseded by the XmRenderTable type and the XmRendition object respectively.
Description
XmFontListCreate() creates a new font list that contains a single entry with
the specified font and charset. charset specifies the character set that is associated
with the font. It can be XmSTRING_DEFAULT_CHARSET, which takes the
character set from the current language environment, but this value may be
removed from future versions of Motif.
XmFontListCreate() searches the font list cache for a font list that matches
the new font list. If the routine finds a matching font list, it returns that font list
and increments its reference count. Otherwise, the routine allocates space for the
new font list and caches it. In either case, the application is responsible for managing the memory associated with the font list. When the application is done
using the font list, it should be freed using XmFontListFree().
Usage
A font list contains entries that describe the fonts that are in use. In Motif 1.1,
each entry associates a font and a character set. In Motif 1.2, each entry consists
of a font or a font set and an associated tag. In Motif 2.0 and later, the
XmFontList is an alias for the XmRenderTable type. XmRendition objects within
a render table represent the font entries. XmFontListCreate() is a convenience routine which calls XmRenditionCreate() to create a rendition object for
the font. The rendition object is added to a render table by the XmRenderTableAddRenditions() function. The render table is returned.
XmFontListCreate() is retained for compatibility with Motif 1.2 and should
not be used in newer applications.
Motif Reference Manual
127
XmFontListCreate
Motif Functions and Macros
XmFontListCreate() is not multi-thread safe if the application has multiple
application contexts. In Motif 2.1, the function XmFontListCreate_r() is to
be preferred within multi-threaded applications.
Fonts must not be shared between displays in a multi-threaded environment.
See Also
XmFontListAppendEntry(1), XmRenderTableAddRenditions(1),
XmRenditionCreate(1), XmRendition(2).
128
Motif Reference Manual
Motif Functions and Macros
XmFontListCreate_r
Name
XmFontListCreate_r – create a font list in a thread-safe manner.
Synopsis
XmFontList XmFontListCreate_r (XFontStruct *font, XmStringCharSet charset,
Widget widget)
Inputs
font
charset
widget
Specifies the font structure.
Specifies a tag that identifies the character set for the font.
Specifies a widget.
Returns
The new font list or NULL if font or charset is NULL.
Availability
Motif 2.1 and later.
Description
XmFontListCreate_r() is identical to XmFontListCreate(), except that
it is multi-thread safe. The additional widget parameter is used to obtain a lock
upon the application context associated with widget. The older routine
XmFontListCreate() is not safe in threaded environments which have multiple application contexts.
Usage
The widget does not need to be the widget which uses font. It must be on the
same display. The sharing of fonts or fontlists across multiple displays is not safe
for multi-threaded applications.
Although the XmFontList is obsolete in Motif 2.0 and later,
XmFontListCreate_r() is provided for backwards compatibility with applications, using the XmFontList interface, which are intended to run in multithreaded environments. XmFontListCreate_r() should not be used in applications using the newer XmRendition and XmRenderTable interface.
See Also
XmFontListCreate(1), XmRendition(2).
Motif Reference Manual
129
XmFontListEntryCreate
Motif Functions and Macros
Name
XmFontListEntryCreate – create a font list entry.
Synopsis
XmFontListEntry XmFontListEntryCreate (char *tag, XmFontType type,
XtPointer font)
Inputs
tag
type
font
Specifies the tag for the font list entry.
Specifies the type of the font argument. Pass either
XmFONT_IS_FONT or XmFONT_IS_FONTSET.
Specifies the font or font set.
Returns
A font list entry.
Availability
In Motif 2.0 and later, the XmFontList and XmFontListEntry are obsolete. They
are superseded by the XmRenderTable type and the XmRendition object respectively. To maintain backwards compatibility, the XmFontList is re-implemented
as a render table.
Description
XmFontListEntryCreate() makes a font list entry that contains the specified font, which is identified by tag. type indicates whether font specifies an
XFontSet or a pointer to an XFontStruct. tag is a NULL-terminated string that
identifies the font list entry. It can have the value
XmFONTLIST_DEFAULT_TAG, which identifies the default font list entry in a
font list.
XmFontListEntryCreate() allocates space for the new font list entry. The
application is responsible for managing the memory associated with the font list
entry. When the application is done using the font list entry, it should be freed
using XmFontListEntryFree().
Usage
In Motif 1.2, a font list contains font list entries, where each entry consists of a
font or font set and an associated tag. XmFontListEntryCreate() creates a
font list entry using an XFontStruct returned by XLoadQueryFont() or an
XFontSet returned by XCreateFontSet(). The routine does not copy the font
structure, so the XFontStruct or XFontSet must not be freed until all references to
it have been freed. The font list entry can be added to a font list using
XmFontListAppendEntry().
130
Motif Reference Manual
Motif Functions and Macros
XmFontListEntryCreate
In Motif 2.0 and later, the XmFontList is an alias for the XmRenderTable type.
XmRendition objects within a render table represent the font entries.
XmFontListEntryCreate() returns a rendition object.
XmFontListEntryCreate() is not multi-thread safe if the application has
multiple application contexts. In Motif 2.1, the function
XmFontListEntryCreate_r() is to be preferred within multi-threaded
applications.
Fonts must not be shared between displays in a multi-threaded environment.
XmFontListEntryCreate() is retained for compatibility with Motif 1.2 and
should not be used in newer applications.
Example
The following code fragment shows how to create font list entries using
XmFontListEntryCreate():
Widget
toplevel;
XFontStruct
*font1, *font2; /* Previously loaded
fonts */
XFontSet
fontset3;
/* Previously created
font sets */
XmFontListEntry entry1, entry2, entry3;
XmFontList
fontlist;
entry1 = XmFontListEntryCreate("tag1", XmFONT_IS_FONT,
font1);
entry2 = XmFontListEntryCreate("tag2", XmFONT_IS_FONT,
font2);
entry3 = XmFontListEntryCreate("tag3",
XmFONT_IS_FONTSET, fontset3);
fontlist = XmFontListAppendEntry (NULL, entry1);
fontlist = XmFontListAppendEntry (fontlist, entry2);
fontlist = XmFontListAppendEntry (fontlist, entry3);
/* Bug in Motif 1.2.1: see XmFontListEntryFree() */
#if ((XmVERSION == 1) && (XmREVISION == 2) &&
(XmUPDATE_LEVEL == 1))
XtFree (entry1);
XtFree (entry2);
XtFree (entry3);
#else /* Motif 1.2.1 */
XmFontListEntryFree (entry1);
XmFontListEntryFree (entry2);
Motif Reference Manual
131
XmFontListEntryCreate
Motif Functions and Macros
XmFontListEntryFree (entry3);
#endif /* Motif 1.2.1 */
XtVaCreateManagedWidget ("widget_name", xmLabelWidgetClass, toplevel, XmNfontList,
fontlist, NULL);
XmFontListFree (fontlist);
...
See Also
XmFontListAppendEntry(1), XmFontListEntryFree(1),
XmFontListEntryCreate_r(1), XmFontListEntryGetFont(1),
XmFontListEntryGetTag(1), XmFontListEntryLoad(1),
XmFontListRemoveEntry(1), XmRenditionCreate(1),
XmRendition(2).
132
Motif Reference Manual
Motif Functions and Macros
XmFontListEntryCreate_r
Name
XmFontListEntryCreate_r – create a font list entry in a thread-safe manner.
Synopsis
XmFontListEntry XmFontListEntryCreate_r (
Inputs
tag
type
font
widget
char
XmFontType
XtPointer
Widget
*tag,
type,
font,
widget)
Specifies the tag for the font list entry.
Specifies the type of the font argument. Pass either
XmFONT_IS_FONT or XmFONT_IS_FONTSET.
Specifies the font or font set.
Specifies a widget.
Returns
A font list entry.
Availability
Motif 2.1 and later.
Description
XmFontListEntryCreate_r() is in all respects identical to XmFontListEntryCreate(), except that XmFontListEntryCreate_r() is provided
for multi-threaded applications: the additional widget parameter is used to obtain
a lock upon an application context. The older routine XmFontListEntryCreate() is not safe in threaded environments which have multiple application
contexts.
Usage
The widget does not need to be the widget which uses font. It must be on the
same display. The sharing of fonts or fontlists across multiple displays is not safe
for multi-threaded applications.
Although the XmFontList is obsolete in Motif 2.0 and later,
XmFontListEntryCreate_r() is provided for backwards compatibility
with applications, using the XmFontList interface, which are intended to run in
multi-threaded environments. XmFontListEntryCreate_r() should not be
used in applications using the newer XmRendition and XmRenderTable interface.
See Also
XmFontListEntryCreate(1), XmRendition(2).
Motif Reference Manual
133
XmFontListEntryFree
Motif Functions and Macros
Name
XmFontListEntryFree – free the memory used by a font list entry.
Synopsis
void XmFontListEntryFree (XmFontListEntry *entry)
Inputs
entry
Specifies the address of the font list entry that is to be freed.
Availability
In Motif 2.0 and later, the XmFontList and XmFontListEntry are obsolete. They
are superseded by the XmRenderTable type and the XmRendition object respectively.
Description
XmFontListEntryFree() deallocates storage used by the specified font list
entry. The routine does not free the XFontSet or XFontStruct data structure associated with the font list entry.
Usage
In Motif 1.2, a font list contains font list entries, where each entry consists of a
font or font set and an associated tag. A font list entry can be created using
XmFontListEntryCreate() or XmFontListEntryLoad() and then
appended to a font list with XmFontListAppendEntry(). Once the entry has
been appended to the necessary font lists, it should be freed using XmFontListEntryFree().
In Motif 1.2.1, there is a bug in XmFontListEntryFree() that causes it to
free the font or font set, rather than the font list entry. As a workaround for this
specific version, you can use XtFree() to free the font list entry.
In Motif 2.0 and later, the XmFontList is an alias for the XmRenderTable type.
XmRendition objects within a render table represent the font entries.
XmFontListEntryFree() is a simple convenience routine which calls
XmRenditionFree().
XmFontListEntryFree() is retained for compatibility with Motif 1.2 and
should not be used in newer applications.
See Also
XmFontListAppendEntry(1), XmFontListEntryCreate(1),
XmFontListEntryLoad(1), XmFontListNextEntry(1),
XmFontListRemoveEntry(1), XmRenditionFree(1),
XmRendition(2).
134
Motif Reference Manual
Motif Functions and Macros
XmFontListEntryGetFont
Name
XmFontListEntryGetFont – get the font information from a font list entry.
Synopsis
XtPointer XmFontListEntryGetFont (XmFontListEntry entry, XmFontType
*type_return)
Inputs
entry
Outputs
type_return
Specifies the font list entry.
Returns the type of the font information that is returned. Valid
types are XmFONT_IS_FONT or XmFONT_IS_FONTSET.
Returns
An XFontSet or a pointer to an XFontStruct.
Availability
In Motif 2.0 and later, the XmFontList and XmFontListEntry are obsolete. They
are superseded by the XmRenderTable type and the XmRendition object respectively.
Description
XmFontListEntryGetFont() retrieves the font information for the specified
font list entry. When the font list entry contains a font, type_return is
XmFONT_IS_FONT and the routine returns a pointer to an XFontStruct. When
the font list entry contains a font set, type_return is XmFONT_IS_FONTSET
and the routine returns the XFontSet. The XFontSet or XFontStruct that is
returned is not a copy of the data structure, so it must not be freed by an application.
Usage
The XmFontList and XmFontListEntry types are opaque, so if an application
needs to perform any processing on a font list, it has to use special functions to
cycle through the font list entries and retrieve information about them. These routines use a XmFontContext to maintain an arbitrary position in a font list.
XmFontListEntryGetFont() can be used to get the font structure for a font
list entry once it has been retrieved from the font list using XmFontListNextEntry().
In Motif 2.0 and later, the XmFontList is an alias for the XmRenderTable type.
XmRendition objects within a render table represent the font entries.
XmFontListEntryGetFont() is a convenience routine which fetches the
XmNfont and XmNfontType values of the rendition object represented by entry.
The values are fetched through the function XmRenditionRetrieve().
Motif Reference Manual
135
XmFontListEntryGetFont
Motif Functions and Macros
type_return is set to the value of the XmNfontType resource, and the function
XmFontListEntryGetFont() returns the value of the XmNfont resource of
the rendition object.
XmFontListEntryGetFont()1 is retained for compatibility with Motif 1.2
and should not be used in newer applications.
See Also
XmFontListEntryCreate(1), XmFontListEntryGetTag(1),
XmFontListEntryLoad(1), XmFontListNextEntry(1),
XmRenditionRetrieve(1), XmRendition(2).
1.Erroneously given as XmFontListGetFont() in 2nd edition.
136
Motif Reference Manual
Motif Functions and Macros
XmFontListEntryGetTag
Name
XmFontListEntryGetTag – get the tag of a font list entry.
Synopsis
char* XmFontListEntryGetTag (XmFontListEntry entry)
Inputs
entry
Specifies the font list entry.
Returns
The tag for the font list entry.
Availability
In Motif 2.0 and later, the XmFontList and XmFontListEntry are obsolete. They
are superseded by the XmRenderTable type and the XmRendition object respectively.
Description
XmFontListEntryGetTag() retrieves the tag of the specified font list entry.
The routine allocates storage for the tag string; the application is responsible for
freeing the memory using XtFree().
Usage
The XmFontList and XmFontListEntry types are opaque, so if an application
needs to perform any processing on a font list, it has to use special functions to
cycle through the font list entries and retrieve information about them. These routines use a XmFontContext to maintain an arbitrary position in a font list.
XmFontListEntryGetTag() can be used to get the tag of a font list entry
once it has been retrieved from the font list using XmFontListNextEntry().
In Motif 2.0 and later, the XmFontList is an alias for the XmRenderTable type.
XmRendition objects within a render table represent the font entries.
XmFontListEntryGetTag() is a convenience routine which fetches and
returns a copy of the XmNtag value of the rendition object represented by entry.
The value is fetched through the function XmRenditionRetrieve().
XmFontListEntryGetTag()1 is retained for compatibility with Motif 1.2
and should not be used in newer applications.
See Also
XmFontListEntryCreate(1), XmFontListEntryGetFont(1),
XmFontListEntryLoad(1), XmFontListNextEntry(1),
XmRenditionRetrieve(1), XmRendition(2).
1.Erroneously given as XmFontListGetTag() in 2nd edition.
Motif Reference Manual
137
XmFontListEntryLoad
Motif Functions and Macros
Name
XmFontListEntryLoad – load a font or create a font set and then create a font list
entry.
Synopsis
XmFontListEntry XmFontListEntryLoad ( Display
char
XmFontType
char
*display,
*font_name,
type,
*tag)
Inputs
display
Specifies a connection to an X server; returned from XOpenDisplay() or XtDisplay().
font_name Specifies an X Logical Font Description (XLFD) string.
type
Specifies the type of font_name. Pass either XmFONT_IS_FONT or
XmFONT_IS_FONTSET.
tag
Specifies the tag for the font list entry.
Returns
A font list entry or NULL if the font cannot be found or the font set cannot be
created.
Availability
In Motif 2.0 and later, the XmFontList and XmFontListEntry are obsolete. They
are superseded by the XmRenderTable type and the XmRendition object respectively.
Description
XmFontListEntryLoad() either loads a font or creates a font set depending
on the value of type and then creates a font list entry that contains the font data
and the specified tag. font_name is an XLFD string which is parsed as either a
font name or a base font name list. tag is a NULL-terminated string that identifies
the font list entry. It can have the value XmFONTLIST_DEFAULT_TAG, which
identifies the default font list entry in a font list.
If type is set to XmFONT_IS_FONT, the routine uses the XtCvtStringToFontStruct() converter to load the font struct specified by font_name. If the
value of type is XmFONT_IS_FONTSET, XmFontListEntryLoad uses the
XtCvtStringToFontSet() converter to create a font set in the current
locale.
XmFontListEntryLoad() allocates space for the new font list entry. The
application is responsible for managing the memory associated with the font list
entry. When the application is done using the font list entry, it should be freed
using XmFontListEntryFree().
138
Motif Reference Manual
Motif Functions and Macros
XmFontListEntryLoad
Usage
In Motif 1.2, a font list contains font list entries, where each entry consists of a
font or font set and an associated tag. XmFontListEntryLoad() sets up the
font data and creates a font list entry. The font list entry can be added to a font list
using XmFontListAppendEntry().
In Motif 2.0 and later, the XmFontList is an alias for the XmRenderTable type.
XmRendition objects within a render table represent the font entries.
XmFontListEntryLoad() is a convenience routine which creates and returns
a rendition object whose XmNfontName resource is set to font_name, and XmNfontType value is type. The rendition object is created with an XmNloadModel of
XmLOAD_IMMEDIATE.
XmFontListEntryLoad() is retained for compatibility with Motif 1.2 and
should not be used in newer applications.
See Also
XmFontListAppendEntry(1), XmFontListEntryCreate(1),
XmFontListEntryFree(1), XmFontListEntryGetFont(1),
XmFontListEntryGetTag(1), XmFontListRemoveEntry(1),
XmRenditionCreate(1), XmRendition(2).
Motif Reference Manual
139
XmFontListFree
Motif Functions and Macros
Name
XmFontListFree – free the memory used by a font list.
Synopsis
void XmFontListFree (XmFontList fontlist)
Inputs
fontlist
Specifies the font list that is to be freed.
Availability
In Motif 2.0 and later, the XmFontList and XmFontListEntry are obsolete. They
are superseded by the XmRenderTable type and the XmRendition object respectively.
Description
XmFontListFree() deallocates storage used by the specified fontlist. The routine does not free the XFontSet or XFontStruct data structures associated with the
font list.
Usage
A font list contains entries that describe the fonts that are in use. In Motif 1.1,
each entry associates a font and a character set. In Motif 1.2, each entry consists
of a font or a font set and an associated tag. XmFontListFree() frees the storage used by the font list but does not free the associated font data structures. In
Motif 2.0 and later, the XmFontList is an alias for the XmRenderTable type.
XmRendition objects within a render table represent the font entries.
XmFontListFree() is a convenience function which simply calls
XmRenderTableFree().
It is important to call XmFontListFree() rather than XtFree() because
Motif caches font lists. A call to XmFontListFree() decrements the reference
count for the font list; the font list is not actually freed until the reference count
reaches 0 (zero).
XmFontListFree() is retained for compatibility with Motif 1.2 and should not
be used in newer applications.
See Also
XmFontListAppendEntry(1), XmFontListCopy(1),
XmFontListEntryFree(1), XmFontListRemoveEntry(1),
XmRenderTableFree(1).
140
Motif Reference Manual
Motif Functions and Macros
XmFontListFreeFontContext
Name
XmFontListFreeFontContext – free a font context.
Synopsis
void XmFontListFreeFontContext (XmFontContext context)
Inputs
context
Specifies the font list context that is to be freed.
Availability
In Motif 2.0 and later, the XmFontList and XmFontListEntry are obsolete. They
are superseded by the XmRenderTable type and the XmRendition object respectively.
Description
XmFontListFreeFontContext() deallocates storage used by the specified
font list context.
Usage
The XmFontList type is opaque, so if an application needs to perform any
processing on a font list, it has to use special functions to cycle through the font
list. These routines use a XmFontContext to maintain an arbitrary position in a
font list. XmFontListFreeFontContext() is the last of the three font context routines that an application should call when processing a font list, as it frees
the font context data structure. An application begins by calling XmFontListInitFontContext() to create a font context and then makes repeated calls
to XmFontListNextEntry() or XmFontListGetNextFont() to cycle
through the font list.
XmFontListFreeFontContext() is retained for compatibility with Motif
1.2, and should not be used in newer applications.
See Also
XmFontListGetNextFont(1), XmFontListInitFontContext(1),
XmFontListNextEntry(1), XmRenderTableAddRendition(1),
XmRenditionCreate(1), XmRendition(2).
Motif Reference Manual
141
XmFontListGetNextFont
Motif Functions and Macros
Name
XmFontListGetNextFont – retrieve information about the next font list element.
Synopsis
Boolean XmFontListGetNextFont (
XmFontContext
XmStringCharSet
XFontStruct
context,
*charset,
**font)
Inputs
context
Specifies the font context for the font list.
Outputs
charset
font
Returns the tag that identifies the character set for the font.
Returns the font structure for the current font list element.
Returns
True if the values being returned are valid or False otherwise.
Availability
In Motif 2.0 and later, the XmFontList and XmFontListEntry are obsolete. They
are superseded by the XmRenderTable type and the XmRendition object respectively.
Description
XmFontListGetNextFont() returns the character set and font for the next
element of the font list. context is the font context created by XmFontListInitFontContext(). The first call to XmFontListGetNextFont() returns
the first font list element. Repeated calls to XmFontListGetNextFont()
using the same context access successive font list elements. The routine returns
False when it has reached the end of the font list.
Usage
A font list contains entries that describe the fonts that are in use. In Motif 1.1,
each entry associates a font and a character set. In Motif 1.2, each entry consists
of a font or a font set and an associated tag. In Motif 2.0 and later, the
XmFontList is an alias for the XmRenderTable type. XmRendition objects within
a render table represent the font entries. The XmFontContext is an opaque type
which contains an index into the renditions of a render table.
If the routine is called with a font context that contains a font set, it returns the
first font of the font set.
The XmFontList type is opaque, so if an application needs to perform any
processing on a font list, it has to use special functions to cycle through the font
list. These routines use a XmFontContext to maintain an arbitrary position in a
142
Motif Reference Manual
Motif Functions and Macros
XmFontListGetNextFont
font list. XmFontListGetNextFont() cycles through the fonts in a font list.
XmFontListInitFontContext() is called first to create the font context.
When an application is done processing the font list, it should call
XmFontListFreeFontContext() with the same context to free the allocated data.
XmFontListGetNextFont() is retained for compatibility with Motif 1.2,
and should not be used in newer applications.
See Also
XmFontListFreeFontContext(1),
XmFontListInitFontContext(1),
XmFontListNextEntry(1), XmRendition(2).
Motif Reference Manual
143
XmFontListInitFontContext
Motif Functions and Macros
Name
XmFontListInitFontContext – create a font context.
Synopsis
Boolean XmFontListInitFontContext (XmFontContext *context, XmFontList
fontlist)
Inputs
fontlist
Specifies the font list.
Outputs
context
Returns the allocated font context structure.
Returns
True if the font context is allocated or False otherwise.
Availability
In Motif 2.0 and later, the XmFontList and XmFontListEntry are obsolete. They
are superseded by the XmRenderTable type and the XmRendition object respectively.
Description
XmFontListInitFontContext() creates a font context for the specified
fontlist. This font context allows an application to access the information that is
stored in the font list. XmFontListInitFontContext() allocates space for
the font context. The application is responsible for managing the memory associated with the font context. When the application is done using the font context, it
should be freed using XmFontListFreeFontContext().
Usage
The XmFontList type is opaque, so if an application needs to perform any
processing on a font list, it has to use special functions to cycle through the font
list. These routines use a XmFontContext to maintain an arbitrary position in a
font list. XmFontListInitFontContext() is the first of the three font context routines that an application should call when processing a font list, as it creates the font context data structure. The context is passed to
XmFontListNextEntry() or XmFontListGetNextFont() to cycle
through the font list. When an application is done processing the font list, it
should call XmFontListFreeFontContext() with the same context to free
the allocated data.
144
Motif Reference Manual
Motif Functions and Macros
XmFontListInitFontContext
In Motif 2.0 and later, the XmFontList is an alias for the XmRenderTable type.
XmRendition objects within a render table represent the font entries. The
XmFontContext is an opaque type which contains an index into the renditions of
a render table.
XmFontListInitFontContext() is retained for compatibility with Motif
1.2, and should not be used in newer applications.
See Also
XmFontListFreeFontContext(1), XmFontListGetNextFont(1),
XmFontListInitFontContext(1), XmFontListNextEntry(1),
XmRendition(2).
Motif Reference Manual
145
XmFontListNextEntry
Motif Functions and Macros
Name
XmFontListNextEntry – retrieve the next font list entry in a font list.
Synopsis
XmFontListEntry XmFontListNextEntry (XmFontContext context)
Inputs
context
Specifies the font context for the font list.
Returns
A font list entry or NULL if the context refers to an invalid entry or if it is at the
end of the font list.
Availability
In Motif 2.0 and later, the XmFontList and XmFontListEntry are obsolete. They
are superseded by the XmRenderTable type and the XmRendition object respectively.
Description
XmFontListNextEntry() returns the next font list entry in a font list. context is the font context created by XmFontListInitFontContext(). The
first call to XmFontListNextEntry() returns the first entry in the font list.
Repeated calls to XmFontListNextEntry() using the same context access
successive font list entries. The routine returns NULL when it has reached the
end of the font list.
Usage
In Motif 1.2, a font list contains font list entries, where each entry consists of a
font or font set and an associated tag. In Motif 2.0 and later, the XmFontList is
an alias for the XmRenderTable type. XmRendition objects within a render table
represent the font entries. The XmFontContext is an opaque type which contains
an index into the renditions of a render table.
The XmFontList and XmFontListEntry types are opaque, so if an application
needs to perform any processing on a font list, it has to use special functions to
cycle through the font list entries and retrieve information about them. These routines use a XmFontContext to maintain an arbitrary position in a font list.
XmFontListInitFontContext() is called first to create the font context.
XmFontListNextEntry() cycles through the font entries in a font list.
XmFontListEntryGetFont() and XmFontListEntryGetTag() access
the information in a font list entry. When an application is done processing the
font list, it should call XmFontListFreeFontContext() with the same context to free the allocated data.
146
Motif Reference Manual
Motif Functions and Macros
XmFontListNextEntry
XmFontListNextEntry() is retained for compatibility with Motif 1.2, and should
not be used in newer applications.
See Also
XmFontListEntryFree(1), XmFontListEntryGetFont(1),
XmFontListEntryGetTag(1), XmFontListFreeFontContext(1),
XmFontListInitFontContext(1), XmRendition(2).
Motif Reference Manual
147
XmFontListRemoveEntry
Motif Functions and Macros
Name
XmFontListRemoveEntry – remove a font list entry from a font list.
Synopsis
XmFontList XmFontListRemoveEntry (XmFontList oldlist, XmFontListEntry
entry)
Inputs
oldlist
entry
Specifies the font list from which entry is removed.
Specifies the font list entry.
Returns
The new font list, oldlist if entry is NULL or no entries are removed, or NULL if
oldlist is NULL.
Availability
In Motif 2.0 and later, the XmFontList and XmFontListEntry are obsolete. They
are superseded by the XmRenderTable type and the XmRendition object respectively.
Description
XmFontListRemoveEntry() makes a new font list by removing any entries
in oldlist that match the specified entry. The routine returns the new font list and
deallocates oldlist. XmFontListRemoveEntry() does not deallocate the font
list entry, so the application should free the storage using XmFontListEntryFree().
XmFontListRemoveEntry() searches the font list cache for a font list that
matches the new font list. If the routine finds a matching font list, it returns that
font list and increments its reference count. Otherwise, the routine allocates
space for the new font list and caches it. In either case, the application is responsible for managing the memory associated with the font list. When the application is done using the font list, it should be freed using XmFontListFree().
Usage
In Motif 1.2, a font list contains font list entries, where each entry consists of a
font or font set and an associated tag. In Motif 2.0 and later, the XmFontList is
an alias for the XmRenderTable type. XmRendition objects within a render table
represent the font entries. The XmFontContext is an opaque type which contains
an index into the renditions of a render table.
An application can use XmFontListRemoveEntry() to remove a font list
entry from a font list. If an application needs to process the font list to determine
which entries to remove, it can use XmFontListInitFontContext() and
XmFontListNextEntry() to cycle through the entries in the font list.
148
Motif Reference Manual
Motif Functions and Macros
XmFontListRemoveEntry
XmFontListRemoveEntry() is retained for compatibility with Motif 1.2,
and should not be used in newer applications.
See Also
XmFontListAppendEntry(1), XmFontListEntryCreate(1),
XmFontListEntryFree(1), XmFontListEntryLoad(1),
XmFontListFree(1), XmRendition(2).
Motif Reference Manual
149
XmGetAtomName
Motif Functions and Macros
Name
XmGetAtomName – get the string representation of an atom.
Synopsis
#include <Xm/AtomMgr.h>
String XmGetAtomName (Display *display, Atom atom)
Inputs
display
Specifies a connection to an X server; returned from XOpenDisplay() or XtDisplay().
atom
Specifies the atom for the property name to be returned.
Returns
The string that represents atom.
Availability
In Motif 2.0 and later, XGetAtomName() is preferred.
Description
XmGetAtomName() returns the string that is used to represent a given atom.
This routine works like Xlib’s XGetAtomName() routine, but the Motif routine
provides the added feature of client-side caching. XmGetAtomName() allocates
space for the returned string; the application is responsible for freeing this storage using XtFree() when the atom is no longer needed.
Usage
An Atom is a number that identifies a property. Properties also have string names.
XmGetAtomName() returns the string name specified in the original call to
XmInternAtom() or XInternAtom(), or for predefined atoms, a string version of the symbolic constant without the XA_ attached.
In Motif 2.0 and later, XmGetAtomName() is no more than a convenience routine which calls XGetAtomName(). While XmGetAtomName() is not yet obsolete, XGetAtomName() is to be preferred.
See Also
XmInternAtom(1).
150
Motif Reference Manual
Motif Functions and Macros
XmGetColorCalculation
Name
XmGetColorCalculation – get the procedure that calculates default colors.
Synopsis
XmColorProc XmGetColorCalculation (void)
Returns
The procedure that calculates default colors.
Description
XmGetColorCalculation() returns the procedure that calculates the default
foreground, top and bottom shadow, and select colors. The procedure calculates
these colors based on the background color that is passed to the procedure.
Usage
Motif widgets rely on the use of shadowed borders to achieve their three-dimensional appearance. The top and bottom shadow colors are lighter and darker
shades of the background color; these colors are reversed to make a component
appear raised out of the screen or recessed into the screen. The select color is a
slightly darker shade of the background color that indicates that a component is
selected. The default foreground color is either black or white, depending on
which color provides the most contrast with the background color. XmGetColorCalculation() returns the procedure that calculates these colors. Use
XmSetColorCalculation() to change the calculation procedure.
In Motif 2.0 and later, color calculation procedures can be specified on a perscreen basis by specifying a value for the XmScreen object XmNcolorCalculationProc resource. Where a particular XmScreen does not have an assigned calculator, the procedure specified by XmGetColorCalculation() is used as
the default.
Procedures
The XmColorProc has the following syntax:
typedef void (*XmColorProc) ( XColor
background color */
XColor
ground color */
XColor
color */
XColor
shadow color */
XColor
tom shadow color */
Motif Reference Manual
*bg_color,
/* specifies the
*fg_color,
/* returns the fore-
*sel_color, /* returns the select
*ts_color,
/* returns the top
*bs_color)
/* returns the bot-
151
XmGetColorCalculation
Motif Functions and Macros
An XmColorProc takes five arguments. The first argument, bg_color, is a pointer
to an XColor structure that specifies the background color. The red, green, blue,
and pixel fields in the structure contain valid values. The rest of the arguments are
pointers to XColor structures for the colors that are to be calculated. The procedure fills in the red, green, and blue fields in these structures.
See Also
XmChangeColor(1), XmGetColors(1), XmSetColorCalculation(1).
XmScreen(2).
152
Motif Reference Manual
Motif Functions and Macros
XmGetColors
Name
XmGetColors – update the colors for a widget.
Synopsis
void XmGetColors ( Screen
Colormap
Pixel
Pixel
Pixel
Pixel
Pixel
Inputs
screen
color_map
background
colors.
*screen,
color_map,
background,
*foreground_return,
*top_shadow_return,
*bottom_shadow_return,
*select_return)
Specifies the screen for which colors are to be allocated.
Specifies a Colormap from which the colors are allocated.
Specifies the background from which to calculate allocated
Outputs
foreground_return
is returned.
top_shadow_return
is returned.
bottom_shadow_return
Pixel is returned.
select_return
returned.
Specifies an address into which the foreground Pixel
Specifies an address into which the top shadow Pixel
Specifies an address into which the bottom shadow
Specifies an address into which the select Pixel is
Description
XmGetColors() allocates and returns a set of pixels within a Colormap associated with a given screen for use as the foreground, top shadow, bottom shadow,
and select colors of a widget. The returned values are calculated based upon a
supplied background.
Usage
XmGetColors() allocates a set of pixels from a colormap. The pixels required
are based upon a supplied background pixel. If any return address is specified as
NULL, the relevant pixel is not allocated. In Motif 1.2 and earlier, pixels are allocated using the current color calculation procedure, which can be specified using
XmSetColorCalculation(). In Motif 2.0 and later, per-screen color calculation procedures are supported: if the XmNcolorCalculationProc resource of the
XmScreen object associated with screen is not NULL, the procedure specified by
the resource is used to calculate the pixels. Otherwise, the current color calculation procedure is used.
Motif Reference Manual
153
XmGetColors
Motif Functions and Macros
See Also
XmGetColorCalculation(1), XmSetColorCalculation(1).
XmScreen(2).
154
Motif Reference Manual
Motif Functions and Macros
XmGetDestination
Name
XmGetDestination – get the current destination widget.
Synopsis
Widget XmGetDestination (Display *display)
Inputs
display
Specifies a connection to an X server; returned from XOpenDisplay() or XtDisplay().
Returns
The widget ID of the current destination widget or NULL if there is no current
destination widget.
Description
XmGetDestination() returns the widget ID of the current destination widget
for the specified display. The destination widget is usually the widget most
recently changed by a select, edit, insert, or paste operation. XmGetDestination() identifies the widget that serves as the destination for quick paste operations and some clipboard routines. This routine returns NULL if there is no
current destination, which occurs when no edit operations have been performed
on a widget.
Usage
XmGetDestination() provides a way for an application to retrieve the widget that
would be acted on by various selection operations, so that the application can do
any necessary processing before the operation occurs.
See Also
XmGetFocusWidget(1), XmGetTabGroup(1).
Motif Reference Manual
155
XmGetDragContext
Motif Functions and Macros
Name
XmGetDragContext – get information about a drag and drop operation.
Synopsis
#include <Xm/DragDrop.h>
Widget XmGetDragContext (Widget widget, Time timestamp)
Inputs
widget
Specifies a widget on the display where the drag and drop operation is taking place.
timestamp
Specifies a timestamp that identifies a DragContext.
Returns
The ID of the DragContext object or NULL if no active DragContext is found.
Availability
Motif 1.2 and later.
Description
XmGetDragContext() retrieves the DragContext object associated with the
display of the specified widget that is active at the specified timestamp. When
more that one drag operation has been started on a display, a timestamp can
uniquely identify the active DragContext. If the specified timestamp corresponds
to a timestamp processed between the beginning and end of a single drag and
drop operation, XmGetDragContext() returns the DragContext associated
with the operation. If there is no active DragContext for the time-stamp, the routine returns NULL.
Usage
Motif 1.2 and later supports the drag and drop model of selection actions. Every
drag and drop operation has a DragContext object associated with it that stores
information about the drag operation. Both the initiating and the receiving clients
use information in the DragContext to process the drag transaction. The DragContext object is widget-like, in that it uses resources to specify its attributes.
These resources can be checked using XtGetValues() and modified using
XtSetValues().
XmGetDragContext() provides a way for an application to retrieve a DragContext object. The application can then use XtGetValues() and XtSetValues() to manipulate the DragContext.
See Also
XmDragCancel(1), XmDragStart(1), XmDragContext(2).
156
Motif Reference Manual
Motif Functions and Macros
XmGetFocusWidget
Name
XmGetFocusWidget – get the widget that has the keyboard focus.
Synopsis
Widget XmGetFocusWidget (Widget widget)
Inputs
widget
Specifies the widget whose hierarchy is to be traversed.
Returns
The widget ID of the widget with the keyboard focus or NULL if no widget has
the focus.
Availability
Motif 1.2 and later.
Description
XmGetFocusWidget() returns the widget ID of the widget that has keyboard
focus in the widget hierarchy that contains the specified widget. The routine
searches the widget hierarchy that contains the specified widget up to the nearest
shell ancestor. XmGetFocusWidget() returns the widget in the hierarchy that
currently has the focus, or the widget that last had the focus when the user navigated to another hierarchy. If no widget in the hierarchy has the focus, the routine
returns NULL.
Usage
XmGetFocusWidget() provides a means of determining the widget that currently
has the keyboard focus, which can be useful if you are trying to control keyboard
navigation in an application.
See Also
XmGetTabGroup(1), XmGetVisibility(1), XmIsTraversable(1),
XmProcessTraversal(1).
Motif Reference Manual
157
XmGetMenuCursor
Motif Functions and Macros
Name
XmGetMenuCursor – get the current menu cursor.
Synopsis
Cursor XmGetMenuCursor (Display *display)
Inputs
display
Specifies a connection to an X server; returned from XOpenDisplay() or XtDisplay().
Returns
The cursor ID for the current menu cursor or None if no cursor has been defined.
Availability
In Motif 1.2 and later, XmGetMenuCursor() is obsolete. It has been superseded by getting the Screen resource XmNmenuCursor.
Description
XmGetMenuCursor() returns the cursor ID of the menu cursor currently in use
by the application on the specified display. The routine returns the cursor for the
default screen of the display. If the cursor is not yet defined because the application called the routine before any menus were created, then XmGetMenuCursor()
returns the value None.
Usage
The menu cursor is the pointer shape that is used whenever a menu is posted.
This cursor can be different from the normal pointer shape. In Motif 1.2 and later,
the new Screen object has a resource, XmNmenuCursor, that specifies the menu
cursor. XmGetMenuCursor() is retained for compatibility with Motif 1.1 and
should not be used in newer applications.
See Also
XmSetMenuCursor(1), XmScreen(2).
158
Motif Reference Manual
Motif Functions and Macros
XmGetPixmap
Name
XmGetPixmap – create and return a pixmap.
Synopsis
Pixmap XmGetPixmap (Screen *screen, char *image_name, Pixel foreground,
Pixel background)
Inputs
screen
Specifies the screen on which the pixmap is to be drawn.
image_name Specifies the string name of the image used to make the pixmap.
foreground
Specifies the foreground color that is combined with the image
when it is a bitmap.
background
Specifies the background color that is combined with the image
when it is a bitmap.
Returns
A pixmap on success or XmUNSPECIFIED_PIXMAP when the specified
image_name cannot be found.
Description
XmGetPixmap() generates a pixmap, stores it in the pixmap cache, and returns
its resource ID. Before the routine actually creates the pixmap, it checks the pixmap cache for a pixmap that matches the specified image_name, screen, foreground, and background. If a match is found, the reference count for the pixmap
is incremented and the resource ID for the pixmap is returned. If no pixmap is
found, XmGetPixmap() checks the image cache for a image that matches the
specified image_name. If a matching image is found, it is used to create the pixmap that is returned.
When no matches are found, XmGetPixmap() begins a search for an X10 or
X11 bitmap file, using image_name as the filename. If a file is found, its contents
are read, converted into an image, and cached in the image cache. Then, the
image is used to generate a pixmap that is subsequently cached and returned. The
depth of the pixmap is the default depth of the screen. If image_name specifies a
bitmap, the foreground and background colors are combined with the image. If
no file is found, the routine returns XmUNSPECIFIED_PIXMAP.
Usage
When image_name starts with a slash (/), it specifies a full pathname and
XmGetPixmap() opens the specified file. Otherwise, image_name specifies a
filename which causes XmGetPixmap() to look for the file using a search path.
In Motif 1.2 and earlier, the XBMLANGPATH environment variable specifies the
search path for X bitmap files. In Motif 2.0 and later, the environment variables
XMICONSEARCHPATH and XMICONBMSEARCHPATH specify search
Motif Reference Manual
159
XmGetPixmap
Motif Functions and Macros
paths for pixmap files: XMICONSEARCHPATH is used if a color server is running, XMICONBMSEARCHPATH otherwise, and XBMLANGPATH is used as
a fallback.
The search path can contain the substitution character %B, where image_name is
substituted for %B. The search path can also use the substitution characters
accepted by XtResolvePathname(), where %T is mapped to bitmaps and %S
is mapped to NULL.
If XBMLANGPATH is not set, XmGetPixmap() uses a default search path. If
the XAPPLRESDIR environment variable is set, the routine searches the following paths:
%B
$XAPPLRESDIR/%L/bitmaps/%N/%B
%B
$XAPPLRESDIR/%l_%t/bitmaps/%N/%B
%N/%B
$XAPPLRESDIR/%l/bitmaps/%N/%B
%B
$XAPPLRESDIR/bitmaps/%N/%B
$XAPPLRESDIR/%L/bitmaps/%B
$XAPPLRESDIR/%l_%t/bitmaps/%B
%B
$XAPPLRESDIR/%l/bitmaps/%B
$XAPPLRESDIR/bitmaps/%B
$HOME/bitmaps/%B
/usr/lib/X11/%L/bitmaps/%N/
/usr/lib/X11/%l_%t/bitmaps/
/usr/lib/X11/%l/bitmaps/%N/
/usr/lib/X11/bitmaps/%N/%B
/usr/lib/X11/%L/bitmaps/%B
/usr/lib/X11/%l_%t/bitmaps/
/usr/lib/X11/%l/bitmaps/%B
/usr/lib/X11/bitmaps/%B
/usr/include/X11/bitmaps/%B
$HOME/%B
If XAPPLRESDIR is not set, XmGetPixmap() searches the same paths, except
that XAPPLRESDIR is replaced by HOME. These search paths are vendordependent and a vendor may use different directories for /usr/lib/X11 and /usr/
include/X11. In the search paths, the image name is substituted for %B, the
class name of the application is substituted for %N, the language string of the display is substituted for %L, the language component of the language string is substituted for %l, and the territory string is substituted for %t.
See Also
XmDestroyPixmap(1), XmGetPixmapByDepth(1),
XmInstallImage(1), XmUninstallImage(1).
160
Motif Reference Manual
Motif Functions and Macros
XmGetPixmapByDepth
Name
XmGetPixmapByDepth – create and return a pixmap of the specified depth.
Synopsis
Pixmap XmGetPixmapByDepth (Screen
char
Pixel
Pixel
int
*screen,
*image_name,
foreground,
background,
depth)
Inputs
screen
Specifies the screen on which the pixmap is to be drawn.
image_name Specifies the string name of the image used to make the pixmap.
foreground
Specifies the foreground color that is combined with the image
when it is a bitmap.
background
Specifies the background color that is combined with the image
when it is a bitmap.
depth
Specifies the depth of the pixmap.
Returns
A pixmap on success or XmUNSPECIFIED_PIXMAP when the specified
image_name cannot be found.
Availability
Motif 1.2 and later.
Description
XmGetPixmapByDepth() generates a pixmap, stores it in the pixmap cache,
and returns its resource ID. Before the routine actually creates the pixmap, it
checks the pixmap cache for a pixmap that matches the specified image_name,
screen, foreground, background, and depth. If a match is found, the reference
count for the pixmap is incremented and the resource ID for the pixmap is
returned. If no pixmap is found, XmGetPixmapByDepth() checks the image
cache for a image that matches the specified image_name. If a matching image is
found, it is used to create the pixmap that is returned.
When no matches are found, XmGetPixmapByDepth() begins a search for an
X10 or X11 bitmap file, using image_name as the filename. If a file is found, its
contents are read, converted into an image, and cached in the image cache. Then,
the image is used to generate a pixmap that is subsequently cached and returned.
The depth of the pixmap is the specified depth. If image_name specifies a bitmap,
the foreground and background colors are combined with the image. If no file is
found, the routine returns XmUNSPECIFIED_PIXMAP.
Motif Reference Manual
161
XmGetPixmapByDepth
Motif Functions and Macros
Usage
XmGetPixmapByDepth() works just like XmGetPixmap() except that the
depth of the pixmap can be specified. With XmGetPixmap(), the depth of the
returned pixmap is the default depth of the screen. See XmGetPixmap() for an
explanation of the search path that is used to find the image.
See Also
XmDestroyPixmap(1), XmGetPixmap(1), XmInstallImage(1),
XmUninstallImage(1).
162
Motif Reference Manual
Motif Functions and Macros
XmGetPostedFromWidget
Name
XmGetPostedFromWidget – get the widget that posted a menu.
Synopsis
#include <Xm/RowColumn.h>
Widget XmGetPostedFromWidget (Widget menu)
Inputs
menu
Specifies the menu widget.
Returns
The widget ID of the widget that posted the menu.
Description
XmGetPostedFromWidget() returns the widget from which the specified
menu is posted. The value that is returned depends on the type of menu that is
specified. For a PopupMenu, the routine returns the widget from which menu is
popped up. For a PulldownMenu, the routine returns the RowColumn widget
from which menu is pulled down. For cascading submenus, the returned widget is
the original RowColumn widget at the top of the menu system. For tear-off
menus in Motif 1.2 and later, XmGetPostedFromWidget() returns the widget
from which the menu is torn off.
Usage
If an application uses the same menu in different contexts, it can use XmGetPostedFromWidget() in an activate callback to determine the context in
which the menu callback should be interpreted.
See Also
XmRowColumn(2), XmPopupMenu(2), XmPulldownMenu(2).
Motif Reference Manual
163
XmGetScaledPixmap
Motif Functions and Macros
Name
XmGetScaledPixmap – create and return a scaled pixmap.
Synopsis
Pixmap XmGetScaledPixmap (Widget
char
Pixel
Pixel
int
double
widget,
*image_name,
foreground,
background,
depth,
scaling_ratio)
Inputs
widget
Specifies a widget.
image_name
Specifies the string name of the image used to make the pixmap.
foreground
Specifies the foreground color that is combined with the image
when it is a bitmap.
background
Specifies the background color that is combined with the
image when it is a bitmap.
depth
Specifies the depth of the pixmap.
scaling_ratio
Specifies a scaling ratio applied to the pixmap.
Returns
A pixmap on success or XmUNSPECIFIED_PIXMAP when the specified
image_name cannot be found.
Availability
Motif 2.1 and later.
Description
XmGetScaledPixmap() is similar to XmGetPixmapByDepth() except that
the returned pixmap is scaled.
Usage
widget is used to find a PrintShell by wandering up the widget hierarchy, and secondly to find a Screen on which to create the pixmap. If scaling_ratio is zero
and an ancestral PrintShell is found, the ratio applied is given by
(printer resolution / default pixmap resolution)
where the default pixmap resolution is the XmNdefaultPixmapResolution
resource of the PrintShell, and the printer resolution is fetched by the PrintShell
using Xp extensions to communicate with the XPrint server. The default value of
the PrintShell XmNdefaultPixmapResolution resource is 100.
164
Motif Reference Manual
Motif Functions and Macros
XmGetScaledPixmap
At present, any resolution specified within the pixmap file itself is currently
ignored, although it is intended that this should take precedence over any PrintShell setting.
Although otherwise fully documented, the function does not have a functional
prototype in any of the supplied public headers.
See Also
XmDestroyPixmap(1), XmGetPixmapByDepth(1), XmPrintShell(2).
Motif Reference Manual
165
XmGetSecondaryResourceData
Motif Functions and Macros
Name
XmGetSecondaryResourceData – retrieve secondary widget resource data.
Synopsis
Cardinal XmGetSecondaryResourceData (WidgetClass
widget_class,
XmSecondaryResourceData
**secondary_data_return)
Inputs
widget_class
Specifies the widget class.
Outputs
secondary_data_return
pointers.
Returns an array of XmSecondaryResourceData
Returns
The number of secondary resource data structures associated with the widget
class.
Availability
Motif 1.2 and later.
Description
XmGetSecondaryResourceData() provides access to the secondary widget
resource data associated with a widget class. Some Motif widget classes have
resources that are not accessible with the functions XtGetResourceList()
and XtGetConstraintResourceList(). If the specified widget_class has
secondary resources, XmGetSecondaryResourceData() provides descriptions of the resources in one or more data structures and returns the number such
structures. If the widget_class does not have secondary resources, the routine
returns 0 (zero) and the value of secondary_data_return is undefined.
If the widget_class has secondary resources, XmGetSecondaryResourceData() allocates an array of pointers to the corresponding data structures. The
application is responsible for freeing the allocated memory using XtFree(). The
resource list in each structure (the value of the resources field), the structures, and
the array of pointers to the structures all need to be freed.
166
Motif Reference Manual
Motif Functions and Macros
XmGetSecondaryResourceData
Usage
XmGetSecondaryResourceData()1 only returns the secondary resources
for a widget class if the class has been initialized. You can initialize a widget
class by creating an instance of the class or any of its subclass. VendorShell and
Text are two Motif widget classes that have secondary resources. The two fields
in the XmSecondaryResourceData structure that are of interest to an application
are resources and num_resources. These fields contain a list of the secondary
resources and the number of such resources.
Most applications do not need to query a widget class for the resources it supports. XmGetSecondaryResourceData() is intended to support interface
builders and applications like editres that allow a user to view the available
resources and set them interactively. Use XtGetResourceList() and
XtGetConstraintResourceList() to get the regular and constraint
resources for a widget class.
Example
The following code fragment shows the use of XmGetSecondaryResourceData() to print the names of the secondary resources of the VendorShell widget:
XmSecondaryResourceData *res; Cardinal num_res, i,
j;
if (num_res = XmGetSecondaryResourceData (vendorShellWidgetCl
ass,
&res)) {
for (i = 0; i < num_res; i++) {
for (j = 0; j < res[i]->num_resources; j++) {
printf ("%s\n", res[i]>resources[j].resource_name);
}
XtFree ((char*) res[i]->resources);
XtFree ((char*) res[i]);
}
XtFree ((char*) res);
}
1.Erroneously given as XmGetSecondaryResources() in 1st and 2nd edition.
Motif Reference Manual
167
XmGetSecondaryResourceData
Motif Functions and Macros
Structures
The XmSecondaryResourceData structure is defined as follows:
typedef struct {
XmResourceBaseProc base_proc;
XtPointer
client_data;
String
name;
String
res_class;
XtResourceList
resources;
Cardinal
num_resources;
}XmSecondaryResourceDataRec, *XmSecondaryResourceData;
See Also
VendorShell(2), XmText(2).
168
Motif Reference Manual
Motif Functions and Macros
XmGetTabGroup
Name
XmGetTabGroup – get the tab group for a widget.
Synopsis
Widget XmGetTabGroup (Widget widget)
Inputs
widget
Specifies the widget whose tab group is to be returned.
Returns
The widget ID of the tab group of widget.
Availability
Motif 1.2 and later.
Description
XmGetTabGroup() returns the widget ID of the widget that is the tab group for
the specified widget. If widget is a tab group or a shell, the routine returns widget.
If widget is not a tab group and no ancestor up to the nearest shell ancestor is a
tab group, the routine returns the nearest shell ancestor. Otherwise, XmGetTabGroup() returns the nearest ancestor of widget that is a tab group.
Usage
XmGetTabGroup() provides a way to find out the tab group for a particular
widget in an application. A tab group is a group of widgets that can be traversed
using the keyboard rather than the mouse. Users move from widget to widget
within a single tab group by pressing the arrow keys. Users move between different tab groups by pressing the Tab or Shift-Tab keys. If the tab group widget is a
manager, its children are all members of the tab group (unless they are made into
separate tab groups). If the widget is a primitive, it is its own tab group. Certain
widgets must not be included with other widgets within a tab group. For example,
each List, ScrollBar, OptionMenu, or multi-line Text widget must be placed in a
tab group by itself, since these widgets define special behavior for the arrow or
Tab keys, which prevents the use of these keys for widget traversal.
See Also
XmGetFocusWidget(1), XmGetVisibility(1), XmIsTraversable(1),
XmProcessTraversal(1), XmManager(2), XmPrimitive(2).
Motif Reference Manual
169
XmGetTearOffControl
Motif Functions and Macros
Name
XmGetTearOffControl – get the tear-off control for a menu.
Synopsis
#include <Xm/RowColumn.h>
Widget XmGetTearOffControl (Widget menu)
Inputs
menu
returned.
Specifies the RowColumn widget whose tear-off control is to be
Returns
The widget ID of the tear-off control or NULL if no tear-off control exists.
Availability
Motif 1.2 and later.
Description
XmGetTearOffControl() retrieves the widget ID of the widget that is the
tear-off control for the specified menu. When the XmNtearOffModel resource of
a RowColumn widget is set to XmTEAR_OFF_ENABLED for a PulldownMenu
or a PopupMenu, the RowColumn creates a tear-off button for the menu. The
tear-off button, which contains a dashed line by default, is the first element in the
menu. When the button is activated, the menu is torn off. If the specified menu
does not have a tear-off control, XmGetTearOffControl() returns NULL.
Usage
In Motif 1.2, a RowColumn that is configured as a PopupMenu or a PulldownMenu supports tear-off menus. When a menu is torn off, it remains on the screen
after a selection is made so that additional selections can be made. The tear-off
control is a button that has a Separator-like appearance. Once you retrieve the
widget ID of the tear-off control, you can set resources to specify its appearance.
You can specify values for the following resources: XmNbackground, XmNbackgroundPixmap, XmNbottomShadowColor, XmNforeground, XmNheight, XmNmargin, XmNseparatorType, XmNshadowThickness, and XmNtopShadowColor.
You can also set these resources in a resource file by using the name of the control, which is TearOffControl.
See Also
XmRepTypeInstallTearOffModelConverter(1), XmPopupMenu(2),
XmPulldownMenu(2), XmRowColumn(2), XmSeparator(2).
170
Motif Reference Manual
Motif Functions and Macros
XmGetVisibility
Name
XmGetVisibility – determine whether or not a widget is visible.
Synopsis
XmVisibility XmGetVisibility (Widget widget)
Inputs
widget
Specifies the widget whose visibility state is to be returned.
Returns
XmVISIBILITY_UNOBSCURED
if widget is completely visible, XmVISIBILITY_PARTIALLY_OBSCURED if widget is partially visible,
XmVISIBILITY_FULLY_OBSCURED
or if widget is not visible.
Availability
Motif 1.2 and later.
Description
XmGetVisibility() determines whether or not the specified widget is visible. The routine returns XmVISIBILITY_UNOBSCURED if the entire rectangular area of the widget is visible. It returns
XmVISIBILITY_PARTIALLY_OBSCURED if a part of the rectangular area of
the widget is obscured by its ancestors. XmGetVisibility() returns
XmVISIBILITY_FULLY_OBSCURED if the widget is completely obscured by
its ancestors or if it is not visible for some other reason, such as if it is unmapped
or unrealized.
Usage
XmGetVisibility() provides a way for an application to find out the visibility state
of a particular widget. This information can be used to help determine whether or
not a widget is eligible to receive the keyboard focus. In order for a widget to
receive the keyboard focus, it and all of its ancestors must not be in the process of
being destroyed and they must be sensitive to input. The widget and its ancestors
must also have their XmNtraversalOn resources set to True. If the widget is viewable, which means that it and its ancestors are managed, mapped, and realized
and some part of the widget is visible, then the widget is eligible to receive the
keyboard focus. A fully-obscured widget is not eligible to receive the focus
unless part of it is within the work area of a ScrolledWindow with an XmNscrollingPolicy of XmAUTOMATIC that has an XmNtraverseObscuredCallback.
Motif Reference Manual
171
XmGetVisibility
Motif Functions and Macros
Structures
XmVisibility is defined as follows:
typedef enum {
XmVISIBILITY_UNOBSCURED,
XmVISIBILITY_PARTIALLY_OBSCURED,
XmVISIBILITY_FULLY_OBSCURED
} XmVisibility;
See Also
XmGetFocusWidget(1), XmGetTabGroup(1), XmIsTraversable(1),
XmProcessTraversal(1), XmManager(2), XmScrolledWindow(2).
172
Motif Reference Manual
Motif Functions and Macros
XmGetXmDisplay
Name
XmGetXmDisplay – get the Display object for a display.
Synopsis
#include <Xm/Display.h>
Widget XmGetXmDisplay (Display *display)
Inputs
display
Specifies a connection to an X server; returned from XOpenDisplay() or XtDisplay().
Returns
The Display object for the display.
Availability
Motif 1.2 and later.
Description
XmGetXmDisplay() retrieves the Display object for the specified display.
Usage
In Motif 1.2, the Display object stores display-specific information for use by the
toolkit. An application has a Display object for each display it accesses. When an
application creates its first shell on a display, typically by calling XtAppInitialize() or XtAppCreateShell(), a Display object is created automatically. There is no way to create a Display independently. Use
XmGetXmDisplay() to get the ID of the Display object, so that you can use
XtGetValues() and XtSetValues() to access and modify Display
resources.
See Also
XmDisplay(2), XmScreen(2).
Motif Reference Manual
173
XmGetXmScreen
Motif Functions and Macros
Name
XmGetXmScreen – get the Screen object for a screen.
Synopsis
Widget XmGetXmScreen (Screen *screen)
Inputs
screen
Specifies a screen on a display; returned by XtScreen().
Returns
The Screen object for the screen.
Availability
Motif 1.2 and later.
Description
XmGetXmScreen() retrieves the Screen object for the specified screen.
Usage
In Motif 1.2, the Screen object stores screen-specific information for use by the
toolkit. An application has a Screen object for each screen that it accesses. When
an application creates its first shell on a screen, typically by calling XtAppInitialize() or XtAppCreateShell(), a Screen object is created automatically. There is no way to create a Screen independently. Use
XmGetXmScreen() to get the ID of the Screen object, so that you can use
XtGetValues() and XtSetValues() to access and modify Screen resources.
See Also
XmDisplay(2), XmScreen(2).
174
Motif Reference Manual
Motif Functions and Macros
XmIm
Name
XmIm – introduction to input methods.
Synopsis
Public Header:
<Xm/XmIm.h>
Functions/Macros:
XmImCloseXIM(), XmImFreeXIC(), XmImGetXIC(), XmImGetXIM(),
XmImMbLookupString(), XmImMbResetIC(), XmImRegister(),
XmImSetFocusValues(), XmImSetValues(), XmImSetXIC(),
XmImUnregister(), XmImUnsetFocus(), XmImVaSetFocusValues(),
XmImVaSetValues()
Availability
Motif 1.2 and later.
Description
Many languages are ideographic, and have considerably more characters than
there are keys on the keyboard: the Ascii keyboard was not originally designed
for languages that are not based upon the Latin alphabet. For such languages, in
order to provide a mapping between the alphabet and the keyboard, it is necessary to represent particular characters by a key sequence rather than a single keystroke. An input method is the means by which X maps between the characters of
the language, and the representative key sequences. The most common use of an
input method is in implementing language-independent text widget input. As the
user types the key sequences, the input method displays the actual keystrokes
until the sequence completes a character, when the required character is displayed in the text widget. The process of composing a character from a key
sequence is called pre-editing.
In order to facilitate pre-editing, the input method may maintain several areas on
the screen: a status area, a pre-edit area, and an auxiliary area. The status area is
an output-only window which provides feedback on the interaction with the input
method. The pre-edit area displays the keyboard sequence as it is typed. The auxiliary area is used for popup menus, or for providing customized controls
required by the particular input method. The location of the pre-edit area is determined by the XmNpreeditType resource of VendorShell. The value OnTheSpot
displays the key sequence as it is typed into the destination text widget itself.
OverTheSpot superimposes an editing window over the top of the text widget.
OffTheSpot creates a dedicated editing window, usually at the bottom of the dia-
Motif Reference Manual
175
XmIm
Motif Functions and Macros
log. Root uses a pre-edit window which is a child of the root window of the display.
To control the interaction between the application and the input method, X
defines a structure called an input context, which the programmer can fetch and
manipulate where the need arises. Each widget registered with the input method
has an associated input context, which may or may not be shared amongst the
registered widgets. Motif extends the mechanisms provided by the lower level X
libraries, and provides a caching mechanism whereby input contexts are shared
between widgets.
Usage
Input methods are usually supplied by the vendors of the hardware, and the application generally connects to the input method without the need for any special
coding by the programmer. The Motif widgets are fully capable of connecting to
an input method when required, and although Motif provides a functional interface to enable the programmer to interact with an input method, the interface is
not required for the Motif widgets. The exceptions are where the programmer is
writing new widgets, or where internationalized input is required for the DrawingArea.
XmImRegister() registers a widget with an input method. XmImSetValues() manipulates an input context by registering callbacks which respond to
specific states. XmImSetFocusValues() is similar, except that after the input
context has been modified, the focus is reset to the widget providing the input.
XmImMbLookupString() performs the necessary key sequence to character
translation on behalf of the input widget. XmImUnRegister() unregisters the
widget with the input method. Typically, XmImRegister() is called within the
Initialize method of a widget, XmImUnRegister() is called by the Destroy
method, and XmImMbLookupString() is called within an action or callback
routine of the widget in response to an event. These are the primary functions
which a programmer may need to call, and are all that are required to implement
internationalized input for the Motif text widget.
Note that an input method does not need to support all styles of XmNpreeditType.
See Also
XmImCloseXIM(1), XmImFreeXIC(1), XmImGetXIM(1),
XmImGetXIC(1), XmImMbLookupString(1), XmImMbResetIC(1),
XmImRegister(1), XmImSetFocusValues(1), XmImSetValues(1),
XmImSetXIC(1), XmImUnregister(1), XmImUnsetFocus(1),
XmImVaSetFocusValues(1), XmImVaSetValues(1).
176
Motif Reference Manual
Motif Functions and Macros
XmImCloseXIM
Name
XmImCloseXIM – close all input contexts.
Synopsis
#include <Xm/XmIm.h>
void XmImCloseXIM (Widget widget)
Inputs
widget
Specifies a widget used to determine the display connection.
Availability
Motif 2.0 and later.
Description
XmImCloseXIM() is a convenience function which closes all input contexts
associated with the current input method. The widget parameter is used to identify the XmDisplay object of the application.
Usage
XmImCloseXIM() uses the widget parameter to deduce the input method associated with the XmDisplay object. The application’s connection to the input
method is closed, and all widgets which are registered with any input context
associated with the input method are unregistered. In order to close the input context associated with a single widget, rather than closing down all connections, use
XmImUnregister().
The Motif widgets internally register and unregister themselves with the input
manager using XmImRegister() and XmImUnregister() as required. The VendorShell calls XmImCloseXIM() within its Destroy method once the last VendorShell is destroyed in order to clean up the connection to the input method. An
application which dynamically switches between input methods in a multi-language application may need to invoke XmImCloseXIM() because Motif only
supports a single input method at any given instance. Application programmers
will not normally need to use XmImCloseXIM() directly.
See Also
XmImRegister(1), XmImUnregister(1), XmIm(1).
Motif Reference Manual
177
XmImFreeXIC
Motif Functions and Macros
Name
XmImFreeXIC – free an input context.
Synopsis
#include <Xm/XmIm.h>
void XmImFreeXIC (Widget widget, XIC xic)
Inputs
widget
deduced.
xic
Specifies a widget from which the input context registry is
Specifies the input context which is to be freed.
Availability
Motif 2.0 and later.
Description
XmImFreeXIC() is a convenience function which unregisters all widgets associated with the input context xic, and then frees the input context.
Usage
XmImFreeXIC() uses the widget parameter to deduce an ancestral VendorShell,
from which the X input context registry is found. All widgets associated with the
input context xic within the registry are unregistered, and the input context is
freed.
See Also
XmImGetXIC(1), XmImRegister(1). XmImSetXIC(1),
XmImUnregister(1), XmIm(1).
178
Motif Reference Manual
Motif Functions and Macros
XmImGetXIC
Name
XmImGetXIC – create an input context for a widget.
Synopsis
#include <Xm/XmIm.h>
XIC XmImGetXIC (Widget widget, XmInputPolicy input_policy, ArgList
arglist, Cardinal argcount)
Inputs
widget
input_policy
arglist
argcount
Specifies a widget for which the input context is required.
Specifies the policy for creating input contexts.
Specifies a list of arguments consisting of name/value pairs.
Specifies the number of arguments in arglist.
Returns
The input context associated with widget.
Availability
Motif 2.0 and later.
Description
XmImGetXIC() creates and registers a new input context for a widget, depending upon the input_policy. If input_policy is XmPER_WIDGET, a new input context is created for the widget. If the value is XmPER_SHELL, a new input
context is created only if an input context associated with the ancestral shell of
widget does not already exist, otherwise the widget is registered with the existing
input context. If the policy is XmINHERIT_POLICY, the input policy is inherited by taking the value of the XmNinputPolicy resource from the nearest ancestral VendorShell. The set of attributes for the input context is specified through
the resource list arglist, each element of the list being a structure containing a
name/value pair. The number of elements within the list is given by argcount.
The name/value pairs are passed through to the function XCreateIC() if the
input context is created. XmImGetXIC() returns either the input context which is
newly created if the input policy is XmPER_WIDGET, otherwise it returns the
shared context.
Motif Reference Manual
179
XmImGetXIC
Motif Functions and Macros
Usage
In Motif 1.2, the supported attributes for configuring the created input context are
XmNbackground, XmNforeground, XmNbackgroundPixmap, XmNspotLocation, XmNfontList, and XmNarea.
In Motif 2.0 and later, the list is extended to include XmNpreeditCaretCallback,
XmNpreeditDoneCallback, XmNpreeditDrawCallback, and XmNpreeditStartCallback resources.
You are referred to the XCreateIC() entry within the Xlib Reference Manual
for the interpretation of each of the resource types. The function allocates storage
associated with the created input context, and it is the responsibility of the programmer to reclaim the space at a suitable point by calling XmImFreeXIC().
Structures
The enumerated type XmInputPolicy has the following possible values:
XmINHERIT_POLICY
XmPER_WIDGET
XmPER_SHELL
See Also
XmImFreeXIC(1), XmImSetXIC(1), XmIm(1).
180
Motif Reference Manual
Motif Functions and Macros
XmImGetXIM
Name
XmImGetXIM – retrieve the input method for a widget.
Synopsis
#include <Xm/XmIm.h>
XIM XmImGetXIM (Widget widget)
Inputs
widget
Specifies a widget registered with the input manager.
Returns
The input method associated with widget.
Availability
Motif 1.2 and later.
Description
XmImGetXIM() returns a pointer to an opaque data structure which represents
the input method which the input manager has opened for the specified widget.
Usage
Widgets are normally registered with the input manager through a call to XmImRegister(). If no input method is associated with the widget, the procedure
uses any specified XmNinputMethod resource of the nearest ancestral VendorShell in order to open an input method. If the resource is NULL, the input
method associated with the current locale is opened. If no input method can be
opened, the function returns NULL.
XmImGetXIM() allocates storage for the opaque data structure which is
returned, and it is the responsibility of the programmer to reclaim the space by a
call to XmImCloseXIM() at a suitable point. XmImGetXIM() is not a procedure
which an application programmer needs to use: the routine is of more use to the
programmer of new widgets.
See Also
XmImRegister(1), XmImCloseXIM(1), XmIm(1).
Motif Reference Manual
181
XmImMbLookupString
Motif Functions and Macros
Name
XmImMbLookupString – retrieve a composed string from an input method.
Synopsis
#include <Xm/XmIm.h>
int XmImMbLookupString ( Widget
XKeyPressedEvent
char
int
KeySym
int
widget,
*event,
*buffer,
num_bytes,
*keysym,
*status)
Inputs
widget
event
num_bytes
Specifies a widget registered with the input manager.
Specifies a key press event.
Specifies the length of the buffer array.
Outputs
buffer
keysym
status
Returns the composed string.
Returns any keysym associated with the input keyboard event.
Returns the status of the lookup.
Returns
The length of the composed string in bytes.
Availability
Motif 1.2 and later.
Description
XmImMbLookupString() translates an event into a composed character, and/
or a keysym, using the input context associated with a given widget. Any composed string which can be deduced from the event is placed in buffer; the composed string consists of multi-byte characters in the encoding of the locale of the
input context. If a keysym is associated with the event, this is returned at the
address specified by keysym. The function returns the number of bytes placed
into buffer.
182
Motif Reference Manual
Motif Functions and Macros
XmImMbLookupString
Usage
A widget is registered with an input method through the function XmImRegister(). If no input context is associated with the widget, the function uses
XLookupString() to map the key event into composed text. Otherwise the
function calls XmbLookupString() with the input context as the first parameter. If the programmer is not interested in keysym values, a NULL value can be
passed as the keysym parameter. XmImMbLookupString() places into buffer
any composed character string associated with the key event: if the event at the
given point in the input sequence does not signify a unique character in the language of the current locale, the function returns zero: subsequent key events may
be required before a character is composed.
Structures
The possible values returned in status are the same as those returned from
XmbLookupString(): you are referred to the Xlib Reference Manual for a full
description and interpretation of the values.
XBufferOverflow
XLookupNone
XLookupChars
XLookupKeysym
XLookupBoth
/* buffer size insufficient to hold composed sequence */
/* no character sequence matching the input exists */
/* input characters were composed
*/
/* input is keysym rather than composed character */
/* both a keysym and composed character are returned */
See Also
XmImRegister(1), XmIm(1).
Motif Reference Manual
183
XmImMbResetIC
Motif Functions and Macros
Name
XmImMbResetIC – reset an input context.
Synopsis
#include <Xm/XmIm.h>
void XmImMbResetIC (Widget widget, char **mb_text)
Inputs
widget
Specifies a widget registered with the Input Manager.
Outputs
mb_text
Returns pending input on the input context.
Availability
Motif 2.0 and later.
Description
XmImMbResetIC() resets the input context associated with a widget.
Usage
XmImMbResetIC() is a convenience function which resets an input context to
the initial state. The function is no more than a wrapper onto the function
XmbResetIC(), which clears the pre-edit area and updates the status area of the
input context. The return value of XmbResetIC() is placed into the address
specified by mb_text. This data is implementation dependent, and may be NULL.
If data is returned, the programmer is responsible for freeing it by calling
XFree().
See Also
XmImRegister(1), XmIm(1).
184
Motif Reference Manual
Motif Functions and Macros
XmImRegister
Name
XmImRegister – register a widget with an Input Manager.
Synopsis
#include <Xm/XmIm.h>
void XmImRegister (Widget widget, unsigned int reserved)
Inputs
widget
reserved
Specifies a widget to register with the input manager.
This parameter is current unused.
Availability
Motif 1.2 and later.
Description
XmImRegister() is a convenience function which registers a widget with the
input manager to establish a connection to the current input method. The function
is called when an application needs to specially arrange for internationalized
input to a widget.
Usage
The Motif widgets internally register themselves with the input manager as
required. Only a programmer who is writing a new widget, or who requires internationalized input for the DrawingArea needs to call XmImRegister() directly.
If the VendorShell ancestor containing the widget already has an associated input
context, the function simply returns. Otherwise, the XmNinputPolicy resource of
the nearest VendorShell ancestor is fetched to determine whether to share an
existing input context. The function opens an input method by inspecting the
XmNinputMethod resource of the VendorShell. If the resource is NULL, a
default input method is opened using information from the current locale. XmImRegister() should not be called twice using the same widget parameter without unregistering the widget from the input method first.
The programmer is responsible for closing down the connection to the input
method by calling XmImUnregister(). The Destroy method of the widget is
an appropriate place to call this.
See Also
XmImUnregister(1), XmIm(1).
Motif Reference Manual
185
XmImSetFocusValues
Motif Functions and Macros
Name
XmImSetFocusValues – set the values and focus for an input context.
Synopsis
#include <Xm/XmIm.h>
void XmImSetFocusValues (Widget widget, ArgList arglist, Cardinal argcount)
Inputs
widget
arglist
argcount
Specifies a widget registered with the input manager.
Specifies a list of resources consisting of name/value pairs.
Specifies the number of arguments in arglist.
Availability
Motif 1.2 and later.
Description
XmImSetFocusValues() notifies the input manager that a widget has
received the input focus. If the previous values of the input context associated
with the widget do not allow the context to be reused, the old context is unregistered, and a new one registered with the widget.
Usage
XmImSetFocusValues() is identical in all respects to XmImSetValues(),
except that after the input context has been reset, the focus window attribute of
the input context is set to the window of the input widget.
The Motif widgets invoke XmImSetFocusValues() as and when required.
For example, the Text and TextField widgets automatically invoke XmImSetFocusValues() in response to FocusIn and EnterNotify events. A programmer who
is implementing internationalized input for a DrawingArea or creating a new
widget may need to call this function when the widget receives the input focus.
See Also
XmImRegister(1), XmImSetValues(1), XmIm(1).
186
Motif Reference Manual
Motif Functions and Macros
XmImSetValues
Name
XmImSetValues – set the values for an input context.
Synopsis
#include <Xm/XmIm.h>
void XmImSetValues (Widget widget, ArgList arglist, Cardinal argcount)
Inputs
widget
arglist
argcount
Specifies a widget registered with the Input Manager.
Specifies a list of resources consisting of name/value pairs.
Specifies the number of arguments in arglist.
Availability
Motif 1.2 and later.
Description
XmImSetValues() sets the attributes for the input context associated with the
specified widget. The set of attributes to be modified is specified through the
resource list arglist, each element of the list being a structure containing a name/
value pair. The number of elements within the list is given by argcount.
Usage
XmImSetValues() is a convenience routine which invokes XSetICValues()
in order to configure an input context. You are referred to the Xlib Reference
Manual for the set of attributes supported by XSetICValues(), and for their
interpretation.
The Motif widgets invoke XmImSetValues() as and when required. For example, the Text and TextField widgets automatically invoke XmImSetValues()
when the widget is resized or the font changed. A programmer who is implementing internationalized input for a DrawingArea or creating a new widget may
need to call this function when, for example, the widget needs to reconfigure the
spot location.
See Also
XmImSetFocusValues(1), XmImRegister(1), XmIm(1).
Motif Reference Manual
187
XmImSetXIC
Motif Functions and Macros
Name
XmImSetXIC – register a widget with an existing input context.
Synopsis
#include <Xm/XmIm.h>
XIC XmImSetXIC (Widget widget, XIC xic)
Inputs
widget
xic
Specifies a widget to be registered with the input context.
Specifies an input context where the widget is to be registered.
Returns
The input context where the widget is registered.
Availability
Motif 2.0 and later.
Description
XmImSetXIC() is a convenience function which registers a widget with an input
context. If the widget is registered with another input context, the widget is firstly
unregistered with that context. The widget is then registered with the input context xic. If xic is NULL, the function creates a new input context and registers the
widget with it. The function returns the input context where the widget is registered.
Usage
XmImSetXIC() allocates storage when it creates a new input context, and it is
the responsibility of the programmer to free the space at an appropriate point by
calling XmImFreeXIC().
See Also
XmImFreeXIC(1), XmImRegister(1), XmIm(1).
188
Motif Reference Manual
Motif Functions and Macros
XmImUnregister
Name
XmImUnregister – unregister the input context for a widget.
Synopsis
#include <Xm/XmIm.h>
void XmImUnregister (Widget widget)
Inputs
widget
Specifies a widget whose input context is to be unregistered.
Availability
Motif 1.2 and later.
Description
XmImUnregister() is a convenience function which unregisters the input context associated with a given widget. The function is the inverse of XmImRegister(), which is called when an application needs to specially arrange for
internationalized input to a widget.
Usage
The Motif widgets internally register themselves with the input manager as
required. Only a programmer who is writing a new widget, or who requires internationalized input for the DrawingArea needs to call XmImRegister() directly.
Where XmImRegister() has been called by the application, it is the responsibility of the programmer to also call XmImUnregister(), usually within the
Destroy() method of the widget for which internationalized input is required.
XmImUnregister() uses the widget parameter to deduce the input method
associated with a display connection. Any input context associated with the input
method is unregistered.
See Also
XmImRegister(1), XmIm(1).
Motif Reference Manual
189
XmImUnsetFocus
Motif Functions and Macros
Name
XmImUnsetFocus – unset focus for input context.
Synopsis
#include <Xm/XmIm.h>
void XmImUnsetFocus (Widget widget)
Inputs
widget
Specifies a widget which has lost the input focus.
Availability
Motif 1.2 and later.
Description
XmImUnsetFocus() notifies the input manager that a widget has lost the input
focus.
Usage
XmImUnsetFocus() is a convenience routine which invokes XUnsetICFocus() using the input context associated with the specified widget. The input
method is notified that no more input is expected from the widget.
The Motif widgets invoke XmImUnsetFocus() as and when required. For
example, the Text and TextField widgets automatically invoke XmImUnsetFocus()1 in response to FocusOut and LeaveNotify events. A programmer who is
implementing internationalized input for a DrawingArea or creating a new
widget may need to call this function when the widget loses the input focus.
See Also
XmImSetFocusValues(1), XmImVaSetFocusValues(1), XmIm(1).
1.Erroneously given as XmUnsetFocus() in 2nd edition.
190
Motif Reference Manual
Motif Functions and Macros
XmImVaSetFocusValues
Name
XmImVaSetFocusValues – set the values and focus for an input context.
Synopsis
#include <Xm/XmIm.h>
void XmImVaSetFocusValues (Widget widget,....,NULL)
Inputs
widget
..., NULL
pairs.
Specifies a widget registered with the Input Manager.
A NULL-terminated variable-length list of resource name/value
Availability
Motif 1.2 and later.
Description
XmImVaSetFocusValues() notifies the input manager that a widget has
received the input focus. If the previous values of the input context associated
with the widget do not allow the context to be reused, the old context is unregistered, and a new one registered with the widget.
Usage
XmImVaSetFocusValues() is simply a convenience routine with a variable
length argument list which constructs internal arglist and argcount parameters to
a XmImSetFocusValues() call.
See Also
XmImSetFocusValues(1).
Motif Reference Manual
191
XmImVaSetValues
Motif Functions and Macros
Name
XmImVaSetValues – set the values for an input context.
Synopsis
#include <Xm/XmIm.h>
void XmImVaSetValues (Widget widget,...,NULL)
Inputs
widget
...,NULL
pairs.
Specifies a widget registered with the Input Manager.
A NULL-terminated variable-length list of resource name/value
Availability
Motif 1.2 and later.
Description
XmImVaSetValues()1 sets the attributes for the input context associated with
the specified widget.
Usage
XmImVaSetValues() is simply a convenience routine with a variable length
argument list which constructs internal arglist and argcount parameters to a
XmImSetValues() call.
See Also
XmImSetValues(1).
1.Erroneously given as XmImSetValues() in 2nd edition.
192
Motif Reference Manual
Motif Functions and Macros
XmInstallImage
Name
XmInstallImage – install an image in the image cache.
Synopsis
Boolean XmInstallImage (XImage *image, char *image_name)
Inputs
image
image_name
Specifies the image to be installed.
Specifies the string name of the image.
Returns
True on success or False if image or image_name is NULL or image_name duplicates an image name already in the cache.
Description
XmInstallImage() installs the specified image in the image cache. The image
can later be used to create a pixmap. When the routine installs the image, it does
not make a copy of the image, so an application should not destroy the image
until it has been uninstalled. The routine also expands the resource converter that
handles images so that image_name can be used in a resource file. In order to
allow references from a resource file, XmInstallImage() must be called to
install an image before any widgets that use the image are created.
Usage
An application can use XmInstallImage() to install and cache images, so that
the images can be shared throughout the application. Once an image is installed,
it can be used to create a pixmap with XmGetPixmap(). The toolkit provides the
following pre-installed images that can be referenced in a resource file or used to
create a pixmap:
Image Name
Image Description
background
Solid background tile
25_foreground
A 25% foreground, 75% background tile
50_foreground
A 50% foreground, 50% background tile
75_foreground
A 75% foreground, 25% background tile
horizontal_tile
Horizontal lines tile, in Motif 1.2.3 and later.
vertical_tile
Vertical lines tile, in Motif 1.2.3 and later.
horizontal
As horizontal_tile: maintained for 1.2.2 compatibility.
vertical
As vertical_tile: maintained for 1.2.2 compatibility.
slant_right
Right slanting lines tile
slant_left
Left slanting lines tile
Motif Reference Manual
193
XmInstallImage
Motif Functions and Macros
Image Name
Image Description
menu_cascade
An arrow pointing to the right, in Motif 2.0 and later.
menu_cascade_rtol
An arrow pointing to the left, in Motif 2.0 and later.
menu_checkmark
A tick mark, in Motif 2.0 and later.
menu_dash
A horizontal line, in Motif 2.0 and later.
collapsed
A filled arrow pointing to the right, in Motif 2.0 and later.
collapsed_rtol
A filled arrow pointing to the left, in Motif 2.0 and later.
expanded
A filled arrow pointing downwards, in Motif 2.0 and later.
Example
You might use the following code to define and install an image:
#define bitmap_width 16
#define bitmap_height 16
static char bitmap_bits[] = {
0xFF, 0x00, 0xFF, 0x00, 0xFF, 0x00, 0xFF, 0x00,
0xFF, 0x00, 0xFF, 0x00, 0xFF, 0x00, 0xFF, 0x00,
0x00, 0xFF, 0x00, 0xFF, 0x00, 0xFF, 0x00, 0xFF,
0x00, 0xFF, 0x00, 0xFF, 0x00, 0xFF, 0x00, 0xFF
};
static XImage ximage = {
bitmap_width,
/* width */
bitmap_height,
/* height */
0,
/* xoffset */
XYBitmap,
/* format */
bitmap_bits,
/* data */
MSBFirst,
/* byte_order */
8,
/* bitmap_unit */
LSBFirst,
/* bitmap_bit_order */
8,
/* bitmap_pad */
1,
/* depth */
2,
/* bytes_per_line */
NULL
/* obdata */
};
...
XmInstallImage (&ximage, "image_name");
...
See Also
XmDestroyPixmap(1), XmGetPixmap(1), XmUninstallImage(1).
194
Motif Reference Manual
Motif Functions and Macros
XmInternAtom
Name
XmInternAtom – return an atom for a given property name string.
Synopsis
#include <Xm/AtomMgr.h>
Atom XmInternAtom (Display *display, String name, Boolean only_if_exists)
Inputs
display
name
only_if_exists
Specifies a connection to an X server; returned from XOpenDisplay() or XtDisplay().
Specifies the string name of the property for which you want the
atom.
Specifies a Boolean value that indicates whether or not the atom
is created if it does not exist.
Returns
An atom on success or None.
Availability
In Motif 2.0 and later, XInternAtom() is preferred.
Description
XmInternAtom() returns the atom that corresponds to the given property
name. This routine works like Xlib’s XInternAtom() routine, but the Motif
routine provides the added feature of client-side caching. If no atom exists with
the specified name and only_if_exists is True, XmInternAtom() does not create
a new atom; it simply returns None. If only_if_exists is False, the routine creates
the atom and returns it.
Usage
An atom is a number that identifies a property. Properties also have string names.
XmInternAtom() returns the atom associated with a property if it exists, or it may
create the atom if it does not exist. The atom remains defined even after the client
that defined it has exited. An atom does not become undefined until the last connection to the X server closes. Predefined atoms are defined in <X11/Xatom.h>
and begin with the prefix XA_. Predefined atoms do not need to be interned with
XmInternAtom().
In Motif 2.0 and later, XmInternAtom() is no more than a convenience routine
which calls XInternAtom(). While XmInternAtom() is not yet officially
obsolete, XInternAtom() is to be preferred.
See Also
XmGetAtomName(1).
Motif Reference Manual
195
XmIsMotifWMRunning
Motif Functions and Macros
Name
XmIsMotifWMRunning – check whether the Motif Window Manager (mwm) is
running.
Synopsis
Boolean XmIsMotifWMRunning (Widget shell)
Inputs
shell
Specifies the shell widget whose screen is queried.
Returns
True if mwm is running or False otherwise.
Description
XmIsMotifWMRunning() checks for the presence of the
_MOTIF_WM_INFO property on the root window of the screen of the specified
shell to determine whether the Motif Window Manager (mwm) is running on the
screen.
Usage
mwm defines additional types of communication between itself and client programs. This communication is optional, so an application should not depend on
the communication or the presence of mwm for any functionality. XmIsMotifWMRunning() allows an application to check if mwm is running and act
accordingly.
See Also
mwm(4).
196
Motif Reference Manual
Motif Functions and Macros
XmIs<Emphasis>Object<Default Para Font>
Name
XmIsObject – determine whether a widget is a subclass of a class.
Synopsis
#include <Xm/Gadget.h>
Boolean XmIsGadget (Widget widget)
#include <Xm/Manager.h>
Boolean XmIsManager (Widget widget)
#include <Xm/Primitive.h>
Boolean XmIsPrimitive (Widget widget)
#include <Xm/ArrowB.h>
Boolean XmIsArrowButton (Widget widget)
#include <Xm/ArrowBG.h>
Boolean XmIsArrowButtonGadget (Widget widget)
#include <Xm/BulletinB.h>
Boolean XmIsBulletinBoard (Widget widget)
#include <Xm/CascadeB.h>
Boolean XmIsCascadeButton (Widget widget)
#include <Xm/CascadeBG.h>
Boolean XmIsCascadeButtonGadget (Widget widget)
#include <Xm/ComboBox.h>
Boolean XmIsComboBox (Widget widget)
#include <Xm/Command.h>
Boolean XmIsCommand (Widget widget)
#include <Xm/Container.h>
Boolean XmIsContainer (Widget widget)
#include <Xm/DialogS.h>
Boolean XmIsDialogShell (Widget widget)
#include <Xm/Display.h>
Boolean XmIsDisplay (Widget widget)
#include <Xm/DragC.h>
Boolean XmIsDragContext (Widget widget)
#include <Xm/DragIcon.h>
Boolean XmIsDragIconObjectClass (Widget widget)
Motif Reference Manual
197
XmIs<Emphasis>Object<Default Para Font>
Motif Functions and Macros
#include <Xm/DrawingA.h>
Boolean XmIsDrawingArea (Widget widget)
#include <Xm/DrawnB.h>
Boolean XmIsDrawnButton (Widget widget)
#include <Xm/DropSMgr.h>
Boolean XmIsDropSiteManager (Widget widget)
#include <Xm/DropTrans.h>
Boolean XmIsDropTransfer (Widget widget)
#include <Xm/FileSB.h>
Boolean XmIsFileSelectionBox (Widget widget)
#include <Xm/Form.h>
Boolean XmIsForm (Widget widget)
#include <Xm/Frame.h>
Boolean XmIsFrame (Widget widget)
#include <Xm/GrabShell.h>
Boolean XmIsGrabShell (Widget widget)
#include <Xm/IconG.h>
Boolean XmIsIconGadget (Widget widget)
#include <Xm/Label.h>
Boolean XmIsLabel (Widget widget)
#include <Xm/LabelG.h>
Boolean XmIsLabelGadget (Widget widget)
#include <Xm/List.h>
Boolean XmIsList (Widget widget)
#include <Xm/MainW.h>
Boolean XmIsMainWindow (Widget widget)
#include <Xm/MenuShell.h>
Boolean XmIsMenuShell (Widget widget)
#include <Xm/MessageB.h>
Boolean XmIsMessageBox (Widget widget)
#include <Xm/Notebook.h>
Boolean XmIsNotebook (Widget widget)
#include <Xm/PanedW.h>
Boolean XmIsPanedWindow (Widget widget)
198
Motif Reference Manual
Motif Functions and Macros
XmIs<Emphasis>Object<Default Para Font>
#include <Xm/PrintS.h>
Boolean XmIsPrintShell (Widget widget)
#include <Xm/PushB.h>
Boolean XmIsPushButton (Widget widget)
#include <Xm/PushBG.h>
Boolean XmIsPushButtonGadget (Widget widget)
#include <Xm/RowColumn.h>
Boolean XmIsRowColumn (Widget widget)
#include <Xm/Scale.h>
Boolean XmIsScale (Widget widget)
#include <Xm/Screen.h>
Boolean XmIsScreen (Widget widget)
#include <Xm/ScrollBar.h>
Boolean XmIsScrollBar (Widget widget)
#include <Xm/ScrolledW.h>
Boolean XmIsScrolledWindow (Widget widget)
#include <Xm/SelectioB.h>
Boolean XmIsSelectionBox (Widget widget)
#include <Xm/Separator.h>
Boolean XmIsSeparator (Widget widget)
#include <Xm/SeparatoG.h>
Boolean XmIsSeparatorGadget (Widget widget)
#include <Xm/Text.h>
Boolean XmIsText (Widget widget)
#include <Xm/TextF.h>
Boolean XmIsTextField (Widget widget)
#include <Xm/ToggleB.h>
Boolean XmIsToggleButton (Widget widget)
#include <Xm/ToggleBG.h>
Boolean XmIsToggleButtonGadget (Widget widget)
#include <Xm/VendorS.h>
Boolean XmIsVendorShell (Widget widget)
Inputs
widget
Motif Reference Manual
Specifies the widget ID of the widget whose class is to be checked.
199
XmIs<Emphasis>Object<Default Para Font>
Motif Functions and Macros
Returns
True if widget is of the specified class or False otherwise.
Availability
XmIsDisplay(), XmIsDragContext(), XmIsDragIconObjectClass(), XmIsDropSiteManager(), XmIsDropTransfer(), and
XmIsScreen() are only available in Motif 1.2 and later.
XmIsComboBox(), XmIsContainer(), XmIsNotebook(), XmIsIconGadget(), and XmIsGrabShell() are available in Motif 2.0 and later.
XmIsPrintShell() is available in Motif 2.1. Note that although the SpinBox
class is available in Motif 2.0, and the SimpleSpinBox class in Motif 2.1, neither
XmIsSpinBox() nor XmIsSimpleSpinBox() are defined. 1
Description
The XmIs*() routines are macros that check the class of the specified widget. The
macros returns True if widget is of the specified class or a subclass of the specified class. Otherwise, the macros return False.
Usage
An application can use the XmIs*() macros to check the class of a particular
widget. All of the macros use XtIsSubclass() to determine the class of the
widget.
Example
The missing macro XmIsSpinBox() could be defined as follows:
#include <Xm/SpinB.h>
#ifndef XmIsSpinBox
#define XmIsSpinBox(w) XtIsSubclass(w, xmSpinBoxWidgetClass)
#endif /* XmIsSpinBox */
1.Be warned that certain platforms, although they ship the PrintShell headers, do not compile the component into the
native Motif toolkit. Sun Solaris is a case in point.
200
Motif Reference Manual
Motif Functions and Macros
XmIs<Emphasis>Object<Default Para Font>
See Also
XmCreateObject(1), VendorShell(2), XmArrowButton(2),
XmArrowButtonGadget(2), XmBulletinBoard(2),
XmCascadeButton(2), XmCascadeButtonGadget(2),
XmComboBox(2), XmCommand(2), XmContainer(2),
XmDialogShell(2), XmDisplay(2), XmDragContext(2),
XmDragIcon(2), XmDrawingArea(2), XmDrawnButton(2),
XmDropSite(2), XmDropTransfer(2),
XmFileSelectionBox(2), XmForm(2), XmFrame(2),
XmGadget(2), XmGrabShell(2), XmIconGadget(2),
XmLabel(2), XmLabelGadget(2), XmList(2),
XmMainWindow(2), XmManager(2), XmMenuShell(2),
XmMessageBox(2), XmNotebook(2), XmPanedWindow(2),
XmPrimitive(2), XmPrintShell(2), XmPushButton(2),
XmPushButtonGadget(2), XmRowColumn(2), XmScale(2),
XmScreen(2), XmScrollBar(2), XmScrolledWindow(2),
XmSelectionBox(2), XmSeparator(2),
XmSeparatorGadget(2), XmSpinBox(2),
XmSimpleSpinBox(2), XmText(2), XmTextField(2),
XmToggleButton(2), XmToggleButtonGadget(2).
Motif Reference Manual
201
XmIsTraversable
Motif Functions and Macros
Name
XmIsTraversable – determine whether or not a widget can receive the keyboard
focus.
Synopsis
Boolean XmIsTraversable (Widget widget)
Inputs
widget
Specifies the widget whose traversability state is to be returned.
Returns
True if widget is eligible to receive the keyboard focus or False otherwise.
Availability
Motif 1.2 and later.
Description
XmIsTraversable() determines whether or not the specified widget can
receive the keyboard focus. The routine returns True if the widget is eligible to
receive the keyboard focus; otherwise it returns False.
Usage
In order for a widget to receive the keyboard focus, it and all of its ancestors must
not be in the process of being destroyed and they must be sensitive to input. The
widget and its ancestors must also have their XmNtraversalOn resources set to
True. If the widget is viewable, which means that it and its ancestors are managed, mapped, and realized and some part of the widget is visible, then the
widget is eligible to receive the keyboard focus. A fully-obscured widget is not
eligible to receive the focus unless part of it is within the work area of a ScrolledWindow with an XmNscrollingPolicy of XmAUTOMATIC that has an XmNtraverseObscuredCallback.
Primitive widgets and gadgets can receive the keyboard focus, while most manager widgets cannot, even if they have traversable children. However, some managers may be eligible to receive the keyboard focus under certain conditions. For
example, a DrawingArea can receive the keyboard focus if it meets the conditions above and it does not have any children with the XmNtraversalOn resource
set to True.
See Also
XmGetFocusWidget(1), XmGetTabGroup(1), XmGetVisibility(1),
XmProcessTraversal(1), XmManager(2), XmScrolledWindow(2).
202
Motif Reference Manual
Motif Functions and Macros
XmListAddItem
Name
XmListAddItem, XmListAddItems – add an item/items to a list.
Synopsis
#include <Xm/List.h>
void XmListAddItem (Widget widget, XmString item, int position)
void XmListAddItems (Widget widget, XmString *items, int item_count, int
position)
Inputs
widget
item
items
item_count
position
Specifies the List widget.
Specifies the item that is to be added.
Specifies a list of items that are to be added.
Specifies the number of items to be added.
Specifies the position at which to add the new item(s).
Description
XmListAddItem() inserts the specified item into the list, while XmListAddItems() inserts the specified list of items. If item_count is smaller than the
number of items, only the first item_count items of the array are added. The position argument specifies the location of the new item(s) in the list. A position
value of 1 indicates the first item, a position value of 2 indicates the second item,
and so on. A value of 0 (zero) specifies the last item in the list. An inserted item
appears selected if it matches an item in the XmNselectedItems list.
Usage
XmListAddItem() and XmListAddItems() are convenience routines that
allow you to add items to a list. The routines add items to the list by internally
manipulating the arrays of compound strings specified by the XmNitems,
XmNitemCount, XmNselectedItems, and XmNselectedItemCount resources. If
an item being added to the list duplicates an item that is already selected, the new
item appears as selected. You should only use these routines if the list supports
multiple selections and you want to select the new items whose duplicates are
already selected. In order to add items with these routines, you have to create a
compound string for each item.
See Also
XmListAddItemUnselected(1), XmListReplaceItems(1),
XmListReplaceItemsPos(1),
XmListReplaceItemsPosUnselected(1),
XmListReplacePositions(1), XmList(2).
Motif Reference Manual
203
XmListAddItemUnselected
Motif Functions and Macros
Name
XmListAddItemUnselected, XmListAddItemsUnselected – add an item/items to
a list.
Synopsis
#include <Xm/List.h>
void XmListAddItemUnselected (Widget widget, XmString item, int position)
void XmListAddItemsUnselected (Widget widget, XmString *items, int
item_count, int position)
Inputs
widget
item
items
item_count
position
Specifies the List widget.
Specifies the item that is to be added.
Specifies a list of items that are to be added.
Specifies the number of items to be added.
Specifies the position at which to add the new item(s).
Availability
XmListAddItemsUnselected() is only available in Motif 1.2 and later.
Description
XmListAddItemUnselected() inserts the specified item into the list, while
XmListAddItemsUnselected() inserts the specified list of items. If
item_count is smaller than the number of items, only the first item_count items of
the array are added. The position argument specifies the location of the new
item(s) in the list. A position value of 1 indicates the first item, a position value
of 2 indicates the second item, and so on. A value of 0 (zero) specifies the last
item in the list. An inserted item does not appear selected, even if it matches an
item in the XmNselectedItems list.
Usage
XmListAddItemUnselected() and XmListAddItemsUnselected()
are convenience routines that allow you to add items to a list. These routines add
items to the list by internally manipulating the array of compound strings specified by the XmNitems and XmNitemCount resources. If an item being added to
the list duplicates an item that is already selected, the new item does not appear
as selected. In order to add items with these routines, you have to create a compound string for each item.
Example
The following callback routine shows how to use of XmListAddItemUnselected() to insert an item into a list in alphabetical order:
void add_item (Widget
204
text_w,
Motif Reference Manual
Motif Functions and Macros
XmListAddItemUnselected
XtPointer
XtPointer
client_data,
call_data)
{
char
(text_w);
XmString
int
Widget
*text, *newtext = XmTextFieldGetString
str, *strlist;
u_bound, l_bound = 0;
list_w = (Widget) client_data;
/* newtext is the text typed in the TextField
widget */
if (!newtext || !*newtext) {
XtFree (newtext);
return;
}
/* get the current entries (and number of entries)
from the List */
XtVaGetValues (list_w, XmNitemCount, &u_bound,
XmNitems, &strlist, NULL);
u_bound--;
/* perform binary search */
while (u_bound >= l_bound) {
int i = l_bound + (u_bound - l_bound)/2;
text = (char *) XmStringUnparse (strlist[i],
NULL,
XmCHARSET_TEXT,
XmCHARSET_TEXT,
NULL, 0,
XmOUTPUT_ALL);
if (!text)
break;
if (strcmp (text, newtext) > 0)
u_bound = i-1;
else
l_bound = i+1;
XtFree (text);
}
/* insert item at appropriate location */
Motif Reference Manual
205
XmListAddItemUnselected
Motif Functions and Macros
str = XmStringCreateLocalized (newtext);
XmListAddItemUnselected (list_w, str, l_bound+1);
XmStringFree (str);
XtFree (newtext);
}
See Also
XmListAddItem(1), XmListReplaceItems(1),
XmListReplaceItemsPos(1),
XmListReplaceItemsPosUnselected(1),
XmListReplaceItemsUnselected(1),
XmListReplacePositions(1), XmList(2).
206
Motif Reference Manual
Motif Functions and Macros
XmListDeleteAllItems
Name
XmListDeleteAllItems – delete all of the items from a list.
Synopsis
#include <Xm/List.h>
void XmListDeleteAllItems (Widget widget)
Inputs
widget
Specifies the List widget.
Description
XmListDeleteAllItems() removes all of the items from the specified List
widget.
Usage
XmListDeleteAllItems() is a convenience routine that allows you to
remove all of the items from a list. The routine removes items from the list by
internally manipulating the array of compound strings specified by the
XmNitems and XmNitemCount resources.
See Also
XmListDeleteItem(1), XmListDeleteItemsPos(1),
XmListDeletePos(1), XmListDeletePositions(1), XmList(2).
Motif Reference Manual
207
XmListDeleteItem
Motif Functions and Macros
Name
XmListDeleteItem, XmListDeleteItems – delete an item/items from a list.
Synopsis
#include <Xm/List.h>
void XmListDeleteItem (Widget widget, XmString item)
void XmListDeleteItems (Widget widget, XmString *items, int item_count)
Inputs
widget
item
items
item_count
Specifies the List widget.
Specifies the item that is to be deleted.
Specifies a list of items that are to be deleted.
Specifies the number of items to be deleted.
Description
XmListDeleteItem()1 removes the first occurrence of the specified item
from the list, while XmListDeleteItems() removes the first occurrence of
each of the elements of items. If an item does not exist, a warning message is displayed.
Usage
XmListDeleteItem() and XmListDeleteItems() are convenience routines that allow you to remove items from a list. The routines remove items from
the list by internally manipulating the array of compound strings specified by the
XmNitems and XmNitemCount resources. If there is more than one occurrence
of an item in the list, the routines only remove the first occurrence. In order to
remove items with these routines, you have to create a compound string for each
item. The routines use a linear search to locate the items to be deleted.
See Also
XmListDeleteAllItems(1), XmListDeleteItemsPos(1),
XmListDeletePos(1), XmListDeletePositions(1), XmList(2).
1.Erroneously given as ListDeleteItem() in 1st and 2nd editions.
208
Motif Reference Manual
Motif Functions and Macros
XmListDeleteItemsPos
Name
XmListDeleteItemsPos – delete items starting at a specified position from a list.
Synopsis
#include <Xm/List.h>
void XmListDeleteItemsPos (Widget widget, int item_count, int position)
Inputs
widget
item_count
position
Specifies the List widget.
Specifies the number of items to be deleted.
Specifies the position from which to delete items.
Description
XmListDeleteItemsPos() removes item_count items from the list, starting
at the specified position. A position value of 1 indicates the first item, a position
value of 2 indicates the second item, and so on. If the number of items between
position and the end of the list is less than item_count, the routine deletes all of
the items up through the last item in the list.
Usage
XmListDeleteItemsPos() is a convenience routine that allows you to
remove items from a list. The routine removes items from the list by internally
manipulating the array of compound strings specified by the XmNitems and
XmNitemCount resources. Since you are specifying the position of the items to
be removed, you do not have to create compound strings for the items. The routine does not have to search for the items, so it avoids the linear search that is
used by XmListDeleteItems().
See Also
XmListDeleteAllItems(1), XmListDeleteItem(1),
XmListDeletePos(1), XmListDeletePositions(1), XmList(2).
Motif Reference Manual
209
XmListDeletePos
Motif Functions and Macros
Name
XmListDeletePos – delete an item at the specified position from a list.
Synopsis
#include <Xm/List.h>
void XmListDeletePos (Widget widget, int position)
Inputs
widget
position
Specifies the List widget.
Specifies the position from which to delete an item.
Description
XmListDeletePos() removes the item at the specified position from the list.
A position value of 1 indicates the first item, a position value of 2 indicates the
second item, and so on. A value of 0 (zero) specifies the last item in the list. If the
list does not have the specified position, a warning message is displayed.
Usage
XmListDeletePos() is a convenience routine that allows you to remove an
item from a list. The routine removes items from the list by internally manipulating the array of compound strings specified by the XmNitems and XmNitemCount resources. Since you are specifying the position of the item to be removed,
you do not have to create a compound string for the item. The routine does not
have to search for the item, so it avoids the linear search that is used by
XmListDeleteItem().
See Also
XmListDeleteAllItems(1), XmListDeleteItem(1),
XmListDeleteItemsPos(1), XmListDeletePositions(1),
XmList(2).
210
Motif Reference Manual
Motif Functions and Macros
XmListDeletePositions
Name
XmListDeletePositions – delete items at the specified positions from a list.
Synopsis
#include <Xm/List.h>
void XmListDeletePositions (Widget widget, int *position_list, int
position_count)
Inputs
widget
position_list
position_count
Specifies the List widget.
Specifies a list of positions from which to delete items.
Specifies the number of positions to be deleted.
Availability
Motif 1.2 and later.
Description
XmListDeletePositions() removes the items that appear at the positions
specified in position_list from the list. A position value of 1 indicates the first
item, a value of 2 indicates the second item, and so on. If the list does not have
the specified position, a warning message is displayed. If position_count is
smaller than the number of positions in position_list, only the first position_count
items of the array are deleted.
Usage
XmListDeletePositions() is a convenience routine that allows you to
remove items from a list. The routine remove the items by modifying the
XmNitems and XmNitemCount resources. Since you are specifying the positions
of the items to be removed, you do not have to create compound strings for the
items. The routine does not have to search for the items, so it avoids the linear
search that is used by XmListDeleteItems().
See Also
XmListDeleteAllItems(1), XmListDeleteItem(1),
XmListDeleteItemsPos(1), XmListDeletePos(1), XmList(2).
Motif Reference Manual
211
XmListDeselectAllItems
Motif Functions and Macros
Name
XmListDeselectAllItems – deselect all items in a list.
Synopsis
#include <Xm/List.h>
void XmListDeselectAllItems (Widget widget)
Inputs
widget
Specifies the List widget.
Description
XmListDeselectAllItems() unhighlights all of the selected items in the
specified widget and removes these items from the XmNselectedItems list. If the
list is in normal mode, the item with the keyboard focus remains selected; if the
list is in add mode, all of the items are deselected.
Usage
XmListDeselectAllItems() is a convenience routine that allows you to
deselect all of the items in a list. The routine deselects items in the list by internally manipulating the array of compound strings specified by the XmNselectedItems and XmNselectedItemCount resources. This routine does not invoke any
selection callbacks for the list when the items are deselected.
See Also
XmListDeselectItem(1), XmListDeselectPos(1),
XmListSelectItem(1), XmListSelectPos(1),
XmListUpdateSelectedList(1), XmList(2).
212
Motif Reference Manual
Motif Functions and Macros
XmListDeselectItem
Name
XmListDeselectItem – deselect an item from a list.
Synopsis
#include <Xm/List.h>
void XmListDeselectItem (Widget widget, XmString item)
Inputs
widget
item
Specifies the List widget.
Specifies the item that is to be deselected.
Description
XmListDeselectItem() unhighlights and removes from the XmNselectedItems list the first occurrence of the specified item.
Usage
XmListDeselectItem() is a convenience routine that allows you to deselect
an item in a list. The routine deselects items in the list by internally manipulating
the array of compound strings specified by the XmNselectedItems and XmNselectedItemCount resources. This routine does not invoke any selection callbacks
for the list when the item is deselected. If there is more than one occurrence of an
item in the list, the routine only deselects the first occurrence. In order to deselect
an item with this routine, you have to create a compound string for the item. The
routine uses a linear search to locate the item to be deselected.
See Also
XmListDeselectAllItems(1), XmListDeselectPos(1),
XmListSelectItem(1), XmListSelectPos(1),
XmListUpdateSelectedList(1), XmList(2).
Motif Reference Manual
213
XmListDeselectPos
Motif Functions and Macros
Name
XmListDeselectPos – deselect an item at the specified position from a list.
Synopsis
#include <Xm/List.h>
void XmListDeselectPos (Widget widget, int position)
Inputs
widget
position
Specifies the List widget.
Specifies the position at which to deselect an item.
Description
XmListDeselectPos() unhighlights the item at the specified position in the
list and removes the item from the XmNselectedItems list. A position value of 1
indicates the first item, a position value of 2 indicates the second item, and so on.
A value of 0 (zero) specifies the last item in the list. If the list does not have the
specified position, the routine does nothing.
Usage
XmListDeselectPos() is a convenience routine that allows you to deselect
an item in a list. The routine deselects items in the list by internally manipulating
the array of compound strings specified by the XmNselectedItems and XmNselectedItemCount resources. This routine does not invoke any selection callbacks
for the list when the item is deselected. Since you are specifying the position of
the item to be deselected, you do not have to create a compound string for the
item. The routine does not have to search for the item, so it avoids the linear
search that is used by XmListDeselectItem().
See Also
XmListDeselectAllItems(1), XmListDeselectPos(1),
XmListGetSelectedPos(1), XmListPosSelected(1),
XmListSelectItem(1), XmListSelectPos(1),
XmListUpdateSelectedList(1), XmList(2).
214
Motif Reference Manual
Motif Functions and Macros
XmListGetKbdItemPos
Name
XmListGetKbdItemPos – get the position of the item in a list that has the location
cursor.
Synopsis
#include <Xm/List.h>
int XmListGetKbdItemPos (Widget widget)
Inputs
widget
Specifies the List widget.
Returns
The position of the item that has the location cursor.
Availability
Motif 1.2 and later.
Description
XmListGetKbdItemPos() retrieves the position of the item in the specified
List widget that has the location cursor. A returned value of 1 indicates the first
item, a value of 2 indicates the second item, and so on. The value 0 (zero) specifies that the list is empty.
Usage
XmListGetKbdItemPos() provides a way to determine which item in a list
has the keyboard focus. This information is useful if you need to perform actions
based on the position of the location cursor in the list.
See Also
XmListSetAddMode(1), XmListSetKbdItemPos(1), XmList(2).
Motif Reference Manual
215
XmListGetMatchPos
Motif Functions and Macros
Name
XmListGetMatchPos – get all occurrences of an item in a list.
Synopsis
#include <Xm/List.h>
Boolean XmListGetMatchPos (Widget widget, XmString item, int
**position_list, int *position_count)
Inputs
widget
item
Specifies the List widget.
Specifies the item whose positions are to be retrieved.
Outputs
position_list
position_count
Returns a list of the positions of the item.
Returns the number of items in position_list.
Returns
True if the item is in the list or False otherwise.
Description
XmListGetMatchPos() determines whether the specified item exists in the
list. If the list contains item, the routine returns True and position_list returns a
list of positions that specify the location(s) of the item. A position value of 1 indicates the first item, a position value of 2 indicates the second item, and so on.
XmListGetMatchPos() allocates storage for the position_list array when the
item is found; the application is responsible for freeing this storage using
XtFree(). If the list does not contain item, the routine returns False, and
position_count is set to zero. In Motif 1.2.3 and earlier, the value of position_list
is undefined if item is not within the list. From Motif 1.2.4 and later, position_list
is set to NULL.
Usage
XmListGetMatchPos() is a convenience routine that provides a way to locate
all of the occurrences of an item in a list. Alternatively, you could obtain this
information yourself using the XmNitems resource and XmListItemPos().
Example
The following code fragments show the use of XmListGetMatchPos():
Widget
list_w;
int
*pos_list;
int
pos_cnt, i;
char
*choice = "A Sample Text String";
XmString str
= XmStringCreateLocalized
(choice);
216
Motif Reference Manual
Motif Functions and Macros
XmListGetMatchPos
if (!XmListGetMatchPos (list_w, str, &pos_list,
&pos_cnt))
XtWarning ("Can’t get items in list");
else {
printf ("%s exists at %d positions:", choice,
pos_cnt);
for (i = 0; i < pos_cnt; i++)
printf (" %d", pos_list[i]);
puts ("");
XtFree (pos_list);
}
XmStringFree (str);
See Also
XmListGetSelectedPos(1), XmList(2).
Motif Reference Manual
217
XmListGetSelectedPos
Motif Functions and Macros
Name
XmListGetSelectedPos – get the positions of the selected items in a list.
Synopsis
#include <Xm/List.h>
Boolean XmListGetSelectedPos (Widget widget, int **position_list, int
*position_count)
Inputs
widget
Specifies the List widget.
Outputs
position_list
position_count
Returns a list of the positions of the selected items.
Returns the number of items in position_list.
Returns
True if there are selected items in the list or False otherwise.
Description
XmListGetSelectedPos() determines whether there are any selected items
in the list. If the list has selected items, the routine returns True and position_list
returns a list of positions that specify the location(s) of the items. A position
value of 1 indicates the first item, a position value of 2 indicates the second item,
and so on. XmListGetSelectedPos() allocates storage for the position_list
array when there are selected items; the application is responsible for freeing this
storage using XtFree(). If the list does not contain any selected items, the routine
returns False and position_count is set to zero. In Motif 1.2.3 and earlier, the
value of position_list is undefined if there are no selected items within the list.
From Motif 1.2.4 and later, position_list is set to NULL.
Usage
XmListGetSelectedPos() is a convenience routine that provides a way to
determine the positions of all of the selected items in a list. Alternatively, you
could obtain this information yourself using the XmNselectedItems resource and
XmListItemPos().
See Also
XmListGetMatchPos(1), XmList(2).
218
Motif Reference Manual
Motif Functions and Macros
XmListItemExists
Name
XmListItemExists – determine if a specified item is in a list.
Synopsis
#include <Xm/List.h>
Boolean XmListItemExists (Widget widget, XmString item)
Inputs
widget
item
Specifies the List widget.
Specifies the item whose presence in the list is checked.
Returns
True if the item is in the list or False otherwise.
Description
XmListItemExists() determines whether the list contains the specified item.
The routine returns True if the item is present and False if it is not.
Usage
XmListItemExists() is a convenience routine that determines whether or not
an item is in a list. In order to use the routine, you have to create a compound
string for the item. The routine uses a linear search to locate the item. You may be
able to obtain this information more effectively by searching the XmNitems list
using your own search procedure.
See Also
XmListGetMatchPos(1), XmListItemPos(1), XmList(2).
Motif Reference Manual
219
XmListItemPos
Motif Functions and Macros
Name
XmListItemPos – return the position of an item in a list.
Synopsis
#include <Xm/List.h>
int XmListItemPos (Widget widget, XmString item)
Inputs
widget
item
Specifies the List widget.
Specifies the item whose position is returned.
Returns
The position of the item in the list or 0 (zero) if the item is not in the list.
Description
XmListItemPos() returns the position of the first occurrence of the specified
item in the list. A position value of 1 indicates the first item, a position value of 2
indicates the second item, and so on. If item is not in the list, XmListItemPos() returns 0 (zero).
Usage
XmListItemPos() is a convenience routine that finds the position of an item in
a list. If there is more than one occurrence of the item in the list, the routine only
returns the position of the first occurrence. In order to use the routine, you have
to create a compound string for the item. The routine uses a linear search to
locate the item.
Example
The following routines show how to make sure that a given item in a list is visible:
void MakePosVisible (Widget list_w, int item_no)
{
int top, visible;
XtVaGetValues (list_w,
&top,
XmNtopItemPosition,
XmNvisibleItemCount,
&visible,
NULL);
if (item_no < top)
XmListSetPos (list_w, item_no);
else if (item_no >= top+visible)
XmListSetBottomPos (list_w, item_no);
220
Motif Reference Manual
Motif Functions and Macros
XmListItemPos
}
void MakeItemVisible (Widget list_w, XmString item)
{
int item_no = XmListItemPos (list_w, item);
if (item_no > 0)
MakePosVisible (list_w, item_no);
}
See Also
XmListItemExists(1), XmListPosSelected(1), XmList(2).
Motif Reference Manual
221
XmListPosSelected
Motif Functions and Macros
Name
XmListPosSelected – check if the item at a specified position is selected in a list.
Synopsis
#include <Xm/List.h>
Boolean XmListPosSelected (Widget widget, int position)
Inputs
widget
position
Specifies the List widget.
Specifies the position that is checked.
Returns
True if the item is selected or False if the item is not selected or the position is
invalid.
Availability
Motif 1.2 and later.
Description
XmListPosSelected() determines whether or not the list item at the specified position is selected. A position value of 1 indicates the first item, a position
value of 2 indicates the second item, and so on. The value 0 (zero) specifies the
last item in the list. The routine returns True if the list item is selected. It returns
False if the item is not selected or the list does not have the specified position.
Usage
XmListPosSelected() is a convenience routine that lets you check if an item at a
particular position is selected. Alternatively, you could check the list of positions
returned by XmListGetSelectedPos() to see if the item at a position is
selected.
See Also
XmListDeselectPos(1), XmListGetSelectedPos(1),
XmListSelectPos(1), XmListUpdateSelectedList(1), XmList(2).
222
Motif Reference Manual
Motif Functions and Macros
XmListPosToBounds
Name
XmListPosToBounds – return the bounding box of an item at the specified position in a list.
Synopsis
#include <Xm/List.h>
Boolean XmListPosToBounds ( Widget
int
Position
Position
Dimension
Dimension
widget,
position,
*x,
*y,
*width,
*height)
Inputs
widget
position
box.
Specifies the List widget.
Specifies the position of the item for which to return the bounding
Outputs
x
y
width
height
Returns the x-coordinate of the bounding box for the item.
Returns the y-coordinate of the bounding box for the item.
Returns the width of the bounding box for the item.
Returns the height of the bounding box for the item.
Returns
True if item at the specified position is visible or False otherwise.
Availability
Motif 1.2 and later.
Description
XmListPosToBounds() returns the bounding box of the item at the specified
position in the list. A position value of 1 indicates the first item, a position value
of 2 indicates the second item, and so on. A value of 0 (zero) specifies the last
item in the list. The routine returns the x and y coordinates of the upper left corner
of the bounding box in relation to the upper left corner of the List widget.
XmListPosToBounds() also returns the width and height of the bounding
box. Passing a NULL value for any of the x, y, width, or height parameters indicates that the value for the parameter should not be returned. If the item at the
specified position is not visible, XmListPosToBounds() returns False and the
return values are undefined.
Motif Reference Manual
223
XmListPosToBounds
Motif Functions and Macros
Usage
XmListPosToBounds() provides a way to determine the bounding box of an
item in a list. This information is useful if you want to perform additional event
processing or draw special graphics for the list item.
See Also
XmListYToPos(1), XmList(2).
224
Motif Reference Manual
Motif Functions and Macros
XmListReplaceItems
Name
XmListReplaceItems – replace specified items in a list.
Synopsis
#include <Xm/List.h>
void XmListReplaceItems ( Widget
XmString
int
XmString
Inputs
widget
old_items
item_count
new_items
widget,
*old_items,
item_count,
*new_items)
Specifies the List widget.
Specifies a list of the items that are to be replaced.
Specifies the number of items that are to be replaced.
Specifies a list of the new items.
Description
XmListReplaceItems() replaces the first occurrence of each item in the
old_items list with the corresponding item from the new_items list. If an item in
the old_items list does not exist in the specified List widget, the corresponding
item in new_items1 is skipped. If item_count is smaller than the number of
old_items or new_items, only the first item_count items are replaced. A new item
appears selected if it matches an item in the XmNselectedItems list.
Usage
XmListReplaceItems() is a convenience routine that allows you to replace
particular items in a list. The routine replaces items by manipulating the array of
compound strings specified by the XmNitems and XmNitemCount resources. If a
new item duplicates an item that is already selected, the new item appears as
selected. You should only use this routine if the list supports multiple selections
and you want to select the new items whose duplicates are already selected. In
order to replace items with this routine, you have to create compound strings for
all of the old and new items. The routine uses a linear search to locate the items to
be replaced.
See Also
XmListAddItem(1), XmListAddItemUnselected(1),
XmListReplaceItemsPos(1),
XmListReplaceItemsPosUnselected(1),
XmListReplaceItemsUnselected(1),
XmListReplacePositions(1), XmList(2).
1.Erroneously given as new_list in 1st and 2nd edition.
Motif Reference Manual
225
XmListReplaceItemsPos
Motif Functions and Macros
Name
XmListReplaceItemsPos – replace specified items in a list.
Synopsis
#include <Xm/List.h>
void XmListReplaceItemsPos (Widget widget, XmString *new_items, int
item_count, int position)
Inputs
widget
new_items
item_count
position
Specifies the List widget.
Specifies a list of the new items.
Specifies the number of items that are to be replaced.
Specifies the position at which to replace items.
Description
XmListReplaceItemsPos() replaces a consecutive number of items in the
list with items from the new_items list. The first item that is replaced is located at
the specified position and each subsequent item is replaced by the corresponding
item from new_items. A position value of 1 indicates the first item, a position
value of 2 indicates the second item, and so on. If item_count is smaller than the
number of new_items, only the first item_count items are replaced. If the number
of items between position and the end of the list is less than item_count, the routine replaces all of the items up through the last item in the list. A new item
appears selected if it matches an item in the XmNselectedItems list.
Usage
XmListReplaceItemsPos() is a convenience routine that allows you to
replace a contiguous sequence of items in a list. The routine replaces items by
manipulating the array of compound strings specified by the XmNitems and
XmNitemCount resources. If a new item duplicates an item that is already
selected, the new item appears as selected. You should only use this routine if the
list supports multiple selections and you want to select the new items whose
duplicates are already selected. In order to replace items with this routine, you
have to create compound strings for all of the new items. The routine does not
have to search for the items, so it avoids the linear searches that are used by
XmListReplaceItems().
See Also
XmListAddItem(1), XmListAddItemUnselected(1),
XmListReplaceItems(1),
XmListReplaceItemsPosUnselected(1),
XmListReplaceItemsUnselected(1),
XmListReplacePositions(1), XmList(2).
226
Motif Reference Manual
Motif Functions and Macros
XmListReplaceItemsPosUnselected
Name
XmListReplaceItemsPosUnselected – replace specified items in a list.
Synopsis
#include <Xm/List.h>
void XmListReplaceItemsPosUnselected (
Inputs
widget
new_items
item_count
position
Widget
XmString
int
int
widget,
*new_items,
item_count,
position)
Specifies the List widget.
Specifies a list of the new items.
Specifies the number of items that are to be replaced.
Specifies the position at which to replace items.
Availability
Motif 1.2 and later.
Description
XmListReplaceItemsPosUnselected() replaces a consecutive number
of items in the list with items from the new_items list. The first item that is
replaced is located at the specified position and each subsequent item is replaced
by the corresponding item from new_items. A position value of 1 indicates the
first item, a position value of 2 indicates the second item, and so on. If item_count
is smaller than the number of new_items, only the first item_count items are
replaced. If the number of items between position and the end of the list is less
than item_count, the routine replaces all of the items up through the last item in
the list. A new item does not appear selected, even if it matches an item in the
XmNselectedItems list.
Usage
XmListReplaceItemsPosUnselected() is a convenience routine that
allows you to replace a contiguous sequence of items in a list. The routine
replaces items by modifying the array of compound strings specified through the
XmNitems and XmNitemCount resources. If a new item duplicates an item that
is already selected, the new item does not appear as selected. In order to replace
items with this routine, you have to create compound strings for all of the new
items. The routine does not have to search for the items, so it avoids the linear
searches that are used by XmListReplaceItemsUnselected().
Motif Reference Manual
227
XmListReplaceItemsPosUnselected
Motif Functions and Macros
See Also
XmListAddItem(1), XmListAddItemUnselected(1),
XmListReplaceItems(1), XmListReplaceItemsPos(1),
XmListReplaceItemsUnselected(1),
XmListReplacePositions(1), XmList(2).
228
Motif Reference Manual
Motif Functions and Macros
XmListReplaceItemsUnselected
Name
XmListReplaceItemsUnselected – replace specified items in a list.
Synopsis
#include <Xm/List.h>
void XmListReplaceItemsUnselected ( Widget
XmString
int
XmString
Inputs
widget
old_items
item_count
new_items
widget,
*old_items,
item_count,
*new_items)
Specifies the List widget.
Specifies a list of the items that are to be replaced.
Specifies the number of items that are to be replaced.
Specifies a list of the new items.
Availability
Motif 1.2 and later.
Description
XmListReplaceItemsUnselected() replaces the first occurrence of each
item in the old_items list with the corresponding item from the new_items list. If
an item in the old_items list does not exist in the specified List widget, the corresponding item in new_items1 is skipped. If item_count is smaller than the number
of old_items or new_items, only the first item_count items are replaced. A new
item does not appear selected, even if it matches an item in the XmNselectedItems list.
Usage
XmListReplaceItemsUnselected() is a convenience routine that allows
you to replace particular items in a list. The routine replaces items by modifying
the array of compound strings specified through the XmNitems and XmNitemCount resources. If a new item duplicates an item that is already selected, the new
item does not appear as selected. In order to replace items with this routine, you
have to create compound strings for all of the old and new items. The routine uses
a linear search to locate the items to be replaced.
See Also
XmListAddItem(1), XmListAddItemUnselected(1),
XmListReplaceItems(1), XmListReplaceItemsPos(1),
XmListReplaceItemsPosUnselected(1),
XmListReplacePositions(1), XmList(2).
1.Erroneously given as new_list in 1st and 2nd editions.
Motif Reference Manual
229
XmListReplacePositions
Motif Functions and Macros
Name
XmListReplacePositions – replace items at the specified positions in a list.
Synopsis
#include <Xm/List.h>
void XmListReplacePositions (Widget widget, int *position_list, XmString
*item_list, int item_count)
Inputs
widget
position_list
item_list
item_count
Specifies the List widget.
Specifies a list of positions at which to replace items.
Specifies a list of the new items.
Specifies the number of items that are to be replaced.
Availability
Motif 1.2 and later.
Description
XmListReplacePositions() replaces the items that appear at the positions
specified in position_list with the corresponding items from item_list. A position
value of 1 indicates the first item, a value of 2 indicates the second item, and so
on. If the list does not have the specified position, a warning message is displayed. If item_count is smaller than the number of positions in position_list,
only the first item_count items are replaced. A new item appears selected if it
matches an item in the XmNselectedItems list.
Usage
XmListReplacePositions() is a convenience routine that allows you to
replace items at particular positions in a list. The routine replaces items by modifying the array of compound strings specified through the XmNitems and
XmNitemCount resources. If a new item duplicates an item that is already
selected, the new item appears as selected. You should only use this routine if the
list supports multiple selections and you want to select the new items whose
duplicates are already selected. In order to replace items with this routine, you
have to create compound strings for all of the new items. The routine does not
have to search for the items, so it avoids the linear searches that are used by
XmListReplaceItems().
See Also
XmListAddItem(1), XmListAddItemUnselected(1),
XmListReplaceItems(1), XmListReplaceItemsPos(1),
XmListReplaceItemsPosUnselected(1),
XmListReplaceItemsUnselected(1), XmList(2).
230
Motif Reference Manual
Motif Functions and Macros
XmListSelectItem
Name
XmListSelectItem – select an item from a list.
Synopsis
#include <Xm/List.h>
void XmListSelectItem (Widget widget, XmString item, Boolean notify)
Inputs
widget
item
notify
Specifies the List widget.
Specifies the item that is to be selected.
Specifies whether or not the selection callback is invoked.
Description
XmListSelectItem() highlights and selects the first occurrence of the specified item in the list. If the XmNselectionPolicy resource of the list is
XmMULTIPLE_SELECT, the routine toggles the selection state of item. For any
other selection policy, XmListSelectItem() replaces the currently selected
item(s) with item. The XmNselectedItems resource specifies the current selection
of the list. If notify is True, XmListSelectItem() invokes the selection callback for the current selection policy.
Usage
XmListSelectItem() is a convenience routine that allows you to select an
item in a list. The routine selects the item by modifying the array of compound
strings specified by the XmNselectedItems and XmNselectedItemCount
resources. In order to select an item with this routine, you have to create a compound string for the item. The routine uses a linear search to locate the item to be
selected. XmListSelectItem() only allows you to select a single item; there are no
routines for selecting multiple items. If you need to select more than one item,
use XtSetValues() to set XmNselectedItems and XmNselectedItemCount.
The notify parameter indicates whether or not the selection callbacks for the current selection policy are invoked. You can avoid redundant code by setting this
parameter to True. If you are calling XmListSelectItem() from a selection
callback routine, you probably want to set the parameter to False to avoid the
possibility of an infinite loop. Calling XmListSelectItem() with notify set to
True causes the callback routines to be invoked in a way that is indistinguishable
from a user-initiated selection action.
See Also
XmListDeselectAllItems(1), XmListDeselectItem(1),
XmListDeselectPos(1), XmListSelectPos(1),
XmListUpdateSelectedList(1), XmList(2).
Motif Reference Manual
231
XmListSelectPos
Motif Functions and Macros
Name
XmListSelectPos – select an item at the specified position from a list.
Synopsis
#include <Xm/List.h>
void XmListSelectPos (Widget widget, int position, Boolean notify)
Inputs
widget
position
notify
Specifies the List widget.
Specifies the position of the item that is to be selected.
Specifies whether or not the selection callback is invoked.
Description
XmListSelectPos() highlights and selects the item at the specified position
in the list. A position value of 1 indicates the first item, a position value of 2 indicates the second item, and so on. A value of 0 (zero) specifies the last item in the
list. If the XmNselectionPolicy resource of the list is XmMULTIPLE_SELECT,
the routine toggles the selection state of the item. For any other selection policy,
XmListSelectPos() replaces the currently selected item with the specified
item. The XmNselectedItems resource lists the current selection of the list. If
notify is True, XmListSelectPos() invokes the selection callback for the current selection policy.
Usage
XmListSelectPos() is a convenience routine that allows you to select an item
at a particular position in a list. The routine selects the item by modifying the
array of compound strings specified through the XmNselectedItems and XmNselectedItemCount resources. Since you are specifying the position of the item to
be selected, you do not have to create a compound string for the item. The routine
does not have to search for the item, so it avoids the linear search that is used by
XmListSelectItem(). XmListSelectPos() only allows you to select a
single item; there are no routines for selecting multiple items. If you need to
select more than one item, use XtSetValues() to set XmNselectedItems and
XmNselectedItemCount.
The notify parameter indicates whether or not the selection callbacks for the current selection policy are invoked. You can avoid redundant code by setting this
parameter to True. If you are calling XmListSelectPos() from a selection callback
routine, you probably want to set the parameter to False to avoid the possibility of
an infinite loop. Calling XmListSelectPos() with notify set to True causes
the callback routines to be invoked in a way that is indistinguishable from a userinitiated selection action.
232
Motif Reference Manual
Motif Functions and Macros
XmListSelectPos
See Also
XmListDeselectAllItems(1), XmListDeselectItem(1),
XmListDeselectPos(1), XmListGetSelectedPos(1),
XmListPosSelected(1), XmListSelectItem(1), XmList(2).
Motif Reference Manual
233
XmListSetAddMode
Motif Functions and Macros
Name
XmListSetAddMode – set add mode in a list.
Synopsis
#include <Xm/List.h>
void XmListSetAddMode (Widget widget, Boolean mode)
Inputs
widget
mode
Specifies the List widget.
Specifies whether to set add mode on or off.
Description
XmListSetAddMode() sets the state of add mode when the XmNselectionPolicy is XmEXTENDED_SELECT. If mode is True, add mode is turned on; if
mode is False, add mode is turned off. When a List widget is in add mode, the
user can move the location cursor without disturbing the current selection.
Usage
XmListSetAddMode() provides a way to change the state of add mode in a list.
The distinction between normal mode and add mode is only important for making keyboard-based selections. In normal mode, the location cursor and the selection move together, while in add mode, the location cursor and the selection can
be separate.
See Also
XmListGetKbdItemPos(1), XmListSetKbdItemPos(1), XmList(2).
234
Motif Reference Manual
Motif Functions and Macros
XmListSetBottomItem
Name
XmListSetBottomItem – set the last visible item in a list.
Synopsis
#include <Xm/List.h>
void XmListSetBottomItem (Widget widget, XmString item)
Inputs
widget
item
Specifies the List widget.
Specifies the item that is made the last visible item.
Description
XmListSetBottomItem() scrolls the List widget so that the first occurrence
of the specified item appears as the last visible item in the list.
Usage
XmListSetBottomItem() provides a way to make sure that a particular item
is visible in a list. The routine changes the viewable portion of the list so that the
specified item is displayed at the bottom of the viewport. If there is more than one
occurrence of the item in the list, the routine uses the first occurrence. In order to
use this routine, you have to create a compound string for the item. The routine
uses a linear search to locate the item.
See Also
XmListSetBottomPos(1), XmListSetHorizPos(1),
XmListSetItem(1), XmListSetPos(1), XmList(2).
Motif Reference Manual
235
XmListSetBottomPos
Motif Functions and Macros
Name
XmListSetBottomPos – set the last visible item in a list.
Synopsis
#include <Xm/List.h>
void XmListSetBottomPos (Widget widget, int position)
Inputs
widget
position
Specifies the List widget.
Specifies the position of the item that is made the last visible item.
Description
XmListSetBottomPos() scrolls the List widget so that the item at the specified position appears as the last visible item in the list. A position value of 1 indicates the first item, a position value of 2 indicates the second item, and so on. A
value of 0 (zero) specifies the last item in the list.
Usage
XmListSetBottomPos() provides a way to make sure that an item at a particular position is visible in a list. The routine changes the viewable portion of the
list so that the item at the specified position is displayed at the bottom of the
viewport. Since you are specifying the position of the item, you do not have to
create a compound string for the item. The routine does not have to search for the
item, so it avoids the linear search that is used by XmListSetBottomItem().
Example
The following routine shows how to make sure that an item at a given position in
a list is visible:
void MakePosVisible (Widget list_w, int item_no)
{
int top, visible;
XtVaGetValues (list_w, XmNtopItemPosition, &top, XmNvisibleItemCount, &visible, NULL);
if (item_no < top)
XmListSetPos (list_w, item_no);
else if (item_no >= top+visible)
XmListSetBottomPos (list_w, item_no);
}
See Also
XmListSetBottomItem(1), XmListSetHorizPos(1),
XmListSetItem(1), XmListSetPos(1), XmList(2).
236
Motif Reference Manual
Motif Functions and Macros
XmListSetHorizPos
Name
XmListSetHorizPos – set the horizontal position of a list.
Synopsis
#include <Xm/List.h>
void XmListSetHorizPos (Widget widget, int position)
Inputs
widget
position
Specifies the List widget.
Specifies the horizontal position.
Description
XmListSetHorizPos() scrolls the list to the specified horizontal position. If
XmNlistSizePolicy is set to XmCONSTANT or XmRESIZE_IF_POSSIBLE and
the horizontal scroll bar is visible, XmListSetHorizPos() sets the XmNvalue
resource of the horizontal scroll bar to the specified position and updates the visible area of the list.
Usage
When a list item is too long to fit horizontally inside the viewing area of a List
widget, the widget either expands horizontally or adds a horizontal scroll bar,
depending on the value of the XmNlistSizePolicy resource. Calling XmListSetHorizPos() is equivalent to the user moving the horizontal scroll bar to the
specified location.
See Also
XmListSetBottomItem(1), XmListSetBottomPos(1),
XmListSetItem(1), XmListSetPos(1), XmList(2).
Motif Reference Manual
237
XmListSetItem
Motif Functions and Macros
Name
XmListSetItem – set the first visible item in a list.
Synopsis
#include <Xm/List.h>
void XmListSetItem (Widget widget, XmString item)
Inputs
widget
item
Specifies the List widget.
Specifies the item that is made the first visible item.
Description
XmListSetItem() scrolls the List widget so that the first occurrence of the
specified item appears as the first visible item in the list.
Usage
XmListSetItem() provides a way to make sure that a particular item is visible
in a list. The routine changes the viewable portion of the list so that the specified
item is displayed at the top of the viewport. Using this routine is equivalent to setting the XmNtopItemPosition resource. If there is more than one occurrence of
the item in the list, the routine uses the first occurrence. In order to use this routine, you have to create a compound string for the item. The routine uses a linear
search to locate the item.
See Also
XmListSetBottomItem(1), XmListSetBottomPos(1),
XmListSetHorizPos(1), XmListSetPos(1), XmList(2).
238
Motif Reference Manual
Motif Functions and Macros
XmListSetKbdItemPos
Name
XmListSetKbdItemPos – set the position of the location cursor in a list.
Synopsis
#include <Xm/List.h>
Boolean XmListSetKbdItemPos (Widget widget, int position)
Inputs
widget
position
Specifies the List widget.
Specifies the position where the location cursor is set.
Returns
True on success or False if there is not item at position or the list is empty.
Availability
Motif 1.2 and later.
Description
XmListSetKbdItemPos() sets the location cursor at the specified position. A
position value of 1 indicates the first item, a position value of 2 indicates the second item, and so on. A value of 0 (zero) specifies the last item in the list. The routine does not check the selection state of the item at the specified location.
Usage
XmListSetKbdItemPos() provides a way to change which item in a list has
the keyboard focus. The routine is useful if you need to make sure that particular
item has the keyboard focus at a given time, such as when the list first receives
the keyboard focus.
See Also
XmListGetKbdItemPos(1), XmListSetAddMode(1), XmList(2).
Motif Reference Manual
239
XmListSetPos
Motif Functions and Macros
Name
XmListSetPos – sets the first visible item in a list.
Synopsis
#include <Xm/List.h>
void XmListSetPos (Widget widget, int position)
Inputs
widget
position
Specifies the List widget.
Specifies the position of the item that is made the first visible item.
Description
XmListSetPos() scrolls the List widget so that the item at the specified position appears as the first visible item in the list. A position value of 1 indicates the
first item, a position value of 2 indicates the second item, and so on. A value of 0
(zero) specifies the last item in the list.
Usage
XmListSetPos() provides a way to make sure that an item at a particular location is visible in a list. The routine changes the viewable portion of the list so that
the item at the specified position is displayed at the top of the viewport. Using
this routine is equivalent to setting the XmNtopItemPosition resource. Since you
are specifying the position of the item, you do not have to create a compound
string for the item. The routine does not have to search for the item, so it avoids
the linear search that is used by XmListSetItem().
Example
The following routine shows how to make sure that an item at a given position in
a list is visible:
void MakePosVisible (Widget list_w, int item_no)
{
int top, visible;
XtVaGetValues (list_w, XmNtopItemPosition, &top, XmNvisibleItemCount, &visible, NULL);
if (item_no < top)
XmListSetPos (list_w, item_no);
else if (item_no >= top+visible)
XmListSetBottomPos (list_w, item_no);
}
See Also
XmListSetBottomItem(1), XmListSetBottomPos(1),
XmListSetHorizPos(1), XmListSetItem(1), XmList(2).
240
Motif Reference Manual
Motif Functions and Macros
XmListUpdateSelectedList
Name
XmListUpdateSelectedList – update the list of selected items in a list.
Synopsis
#include <Xm/List.h>
void XmListUpdateSelectedList (Widget widget)
Inputs
widget
Specified the List widget.
Availability
Motif 1.2 and later.
Description
XmListUpdateSelectedList() updates the array of compound strings
specified through the XmNselectedItems resource. The routine frees the current
selected array, and then traverses the array of compound strings specified by the
XmNitems resource, adding each currently selected item to the XmNselectedItems list.
Usage
XmListUpdateSelectedList() provides a way to update the list of
selected items in a list. This routine is useful if the actual items that are selected
are not synchronized with the value of the XmNselectedItems resource. This situation might arise if you are using internal list functions and modifying internal
data structures. If you are using the defined list routines, the situation should
never occur.
See Also
XmListDeselectAllItems(1), XmListDeselectItem(1),
XmListDeselectPos(1), XmListGetSelectedPos(1),
XmListPosSelected(1), XmListSelectItem(1),
XmListSelectPos(1), XmList(2).
Motif Reference Manual
241
XmListYToPos
Motif Functions and Macros
Name
XmListYToPos – get the position of the item at the specified y-coordinate in a
list.
Synopsis
#include <Xm/List.h>
int XmListYToPos (Widget widget, Position y)
Inputs
widget
y
Specifies the List widget.
Specifies the y-coordinate.
Returns
The position of the item at the specified y-coordinate.
Availability
Motif 1.2 and later.
Description
XmListYToPos() retrieves the position of the item at the specified y-coordinate
in the list. The y-coordinate is specified in the coordinate system of the list. A
returned value of 1 indicates the first item, a value of 2 indicates the second item,
and so on. The value 0 (zero) specifies that there is no item at the specified location.
As of Motif 1.2, a return value of 0 (zero) indicates the first item, a value of 1
indicates the second item, and so on. In Motif 1.2.3 and earlier, the value that is
returned may not be a valid position in the list, so an application should check the
value with respect to the value of XmNitemCount before using it. In Motif 1.2.4
and later, the returned position may not exceed the value of XmNitemCount.
Usage
XmListYToPos() provides a way to translate a y-coordinate into a list position.
This routine is useful if you are processing events that report a pointer position
and you need to convert the location of the event into an item position.
See Also
XmListPosToBounds(1), XmList(2).
242
Motif Reference Manual
Motif Functions and Macros
XmMainWindowSep1
Name
XmMainWindowSep1, XmMainWindowSep2, XmMainWindowSep3 – get the
widget ID of a MainWindow Separator.
Synopsis
#include <Xm/MainW.h>
Widget XmMainWindowSep1 (Widget widget)
Widget XmMainWindowSep2 (Widget widget)
Widget XmMainWindowSep3 (Widget widget)
Inputs
widget
Specifies the MainWindow widget.
Returns
The widget ID of the particular MainWindow Separator.
Availability
In Motif 2.0 and later, these routines are marked as deprecated.
Description
XmMainWindowSep1() returns the widget ID of the MainWindow widget’s
first Separator, which is located directly below the MenuBar.
XmMainWindowSep2() returns the widget ID of the second Separator in the
Main Window, which is between the Command and ScrolledWindow widgets.
XmMainWindowSep3() returns the widget ID of the MainWindow’s third Separator, which is located just above the message window. The three Separator
widgets in a MainWindow are visible only when the XmNshowSeparator
resource is set to True.
Usage
XmMainWindowSep1(), XmMainWindowSep2(), and
XmMainWindowSep3() provide access to the three Separator widgets that can
be displayed by a MainWindow widget. With the widget IDs, you can change the
visual attributes of the individual Separators.
In Motif 2.0 and later, the function XtNameToWidget() is the preferred
method of obtaining the MainWindow components. You should pass widget as
the first parameter, and "Separator1", "Separator2", or "Separator3" as the second
parameter to this procedure.
See Also
XmMainWindowSetAreas(1), XmMainWindow(2),
XmScrolledWindow(2).
Motif Reference Manual
243
XmMainWindowSetAreas
Motif Functions and Macros
Name
XmMainWindowSetAreas – specify the children for a MainWindow.
Synopsis
#include <Xm/MainW.h>
void XmMainWindowSetAreas ( Widget
Widget
Widget
Widget
Widget
Widget
Inputs
widget
menu_bar
command_window
horizontal_scrollbar
vertical_scrollbar
work_region
widget,
menu_bar,
command_window,
horizontal_scrollbar,
vertical_scrollbar,
work_region)
Specifies the MainWindow widget.
Specifies the widget ID of the MenuBar.
Specifies the widget ID of the command window.
Specifies the widget ID of the horizontal ScrollBar.
Specifies the widget ID of the vertical ScrollBar.
Specifies the widget ID of the work window.
Availability
In Motif 2.0 and later, the procedure is marked as deprecated.
Description
XmMainWindowSetAreas() sets up the standard regions of the MainWindow
widget for an application. The MainWindow must be created before the routine is
called. XmMainWindowSetAreas() specifies the MenuBar, the work window,
the command window, and the horizontal and vertical ScrollBars for the MainWindow. If an application does not have one of these regions, the corresponding
argument can be specified as NULL. Each region may have child widgets, and
this routine determines which of those children will be actively managed by the
MainWindow.
Usage
Each of the MainWindow regions is associated with a MainWindow resource;
XmMainWindowSetAreas() sets the associated resources. The associated
resources that correspond to the last five arguments to the routine are XmNmenuBar, XmNcommand, XmNhorizontalScrollBar, XmNverticalScrollBar, and
XmNworkWindow. XmMainWindowSetAreas() does not provide a way to
set up the message area; this region must be set up by specifying the XmNmessageWindow resource.
244
Motif Reference Manual
Motif Functions and Macros
XmMainWindowSetAreas
If an application does not call XmMainWindowSetAreas(), the widget may
still set some of the standard regions. When a MenuBar child is added to a MainWindow, if XmNmenuBar has not been set, it is set to the MenuBar child. When
a Command child is added to a MainWindow, if XmNcommand has not been set,
it is set to the Command child. If ScrollBars are added as children, the XmNhorizontalScrollBar and XmNverticalScrollBar resources may be set if they have not
already been specified. Any child that is not one of these types is used for the
XmNworkWindow. If you want to be certain about which widgets are used for
the different regions, it is wise to call XmMainWindowSetAreas() explicitly.
In Motif 2.0 and later, XmMainWindowSetAreas(), is deprecated. The programmer should use XtSetValues() in order to specify the XmNcommandWindow, XmNmenuBar, XmNworkWindow, XmNhorizontalScrollBar, and
XmNverticalScrollBar resources of the MainWindow. XmMainWindowSetAreas() does not handle the XmNmessageWindow resource in any case.
Example
The following code fragment shows how to set some of the regions of a MainWindow:
Widget top, main_w, menubar, command_w, text_w, scrolled_text_w;
Arg
args[4];
main_w = XtVaCreateManagedWidget("main_w", xmMainWindowWidgetClass, top, NULL);
menubar = XmCreateMenuBar (main_w, "menubar", NULL, 0);
XtManageChild (menubar);
XtSetArg (args[0], XmNrows, 24);
XtSetArg (args[1], XmNcolumns, 80);
XtSetArg (args[2], XmNeditable, False);
XtSetArg (args[3], XmNeditMode, XmMULTI_LINE_EDIT);
text_w = XmCreateScrolledText (main_w, "text_w", args, 4);
XtManageChild (text_w);
scrolled_text_w = XtParent (text_w);
command_w = XmCreateText (main_w, "command_w", (Arg *) 0, 0);
XtManageChild (command_w);
#if
(XmVERSION > 1)
XtVaSetValues (main_w,
XmNmenuBar,
XmNcommandWindow,
XmNhorizontalScrollBar,
XmNverticalScrollBar,
Motif Reference Manual
menubar,
command_w,
NULL,
NULL,
245
XmMainWindowSetAreas
Motif Functions and Macros
XmNworkWindow,
scrolled_text_w,
0);
#else /* XmVERSION > 1 */
XmMainWindowSetAreas (main_w, menubar, command_w, NULL, NULL,
scrolled_text_w);
#endif /* XmVERSION > 1 */
See Also
XmMainWindowSep(1), XmMainWindow(2), XmScrolledWindow(2).
246
Motif Reference Manual
Motif Functions and Macros
XmMapSegmentEncoding
Name
XmMapSegmentEncoding – get the compound text encoding format for a font
list element tag.
Synopsis
char * XmMapSegmentEncoding (char *fontlist_tag)
Inputs
fontlist_tag
Specifies the compound string font list element tag.
Returns
A character string that contains a copy of the compound text encoding format or
NULL if the font list element tag is not found in the registry.
Availability
Motif 1.2 and later.
Description
XmMapSegmentEncoding() retrieves the compound text encoding format
associated with the specified fontlist_tag. The toolkit stores the mappings
between compound text encodings and font list elements tags in a registry.
XmMapSegmentEncoding() searches the registry for a compound text encoding format associated with the specified fontlist_tag and returns a copy of the format. If fontlist_tag is not in the registry, the routine returns NULL.
XmMapSegmentEncoding() allocates storage for the returned character
string; the application is responsible for freeing the storage using XtFree().
Usage
Compound text is an encoding that is designed to represent text from any locale.
Compound text strings identify their encoding using embedded escape
sequences. The compound text representation was standardized for X11R4 for
use as a text interchange format for interclient communication.
XmCvtXmStringToCT() converts a compound string into compound text by
using the font list tag of each compound string segment to select a compound text
format from the registry for the segment. XmMapSegmentEncoding() provides a way for an application to determine the compound text format that would
be used for a particular font list element tag.
See Also
XmCvtXmStringToCT(1), XmRegisterSegmentEncoding(1).
Motif Reference Manual
247
XmMenuPosition
Motif Functions and Macros
Name
XmMenuPosition – position a popup menu.
Synopsis
#include <Xm/RowColumn.h>
void XmMenuPosition (Widget menu, XButtonPressedEvent *event)
Inputs
menu
Specifies the PopupMenu.
event
Specifies the event that was passed to the action procedure managing the PopupMenu.
Description
XmMenuPosition() positions a popup menu, using the values of the x_root
and y_root fields from the specified event. An application must call this routine
before managing the popup menu, except when the application is positioning the
menu itself.
Usage
The event parameter for XmMenuPosition() is defined to be of type XButtonPressedEvent *; using another type of event might lead to toolkit problems. The
x_root and y_root fields in the event structure are used to position the menu at the
location of the mouse button press. You can modify these fields to position the
menu at another location.
In Motif 2.0 and later, a menu whose XmNpopupEnabled resource is
XmPOPUP_AUTOMATIC or XmPOPUP_AUTOMATIC_RECURSIVE has an
installed event handler which calls XmMenuPosition() directly without the
need for an application to intervene in posting the menu.
Example
The following routine shows the use of an event handler to post a popup menu.
void PostIt (Widget w, XtPointer client_data, XEvent *event, Boolean *dispatch)
{
Widget
popup = (Widget) client_data;
XButtonPressedEvent *bevent = (XButtonPressedEvent *) event;
if ((bevent->type != ButtonPress) && (bevent->button != 3))
return;
XmMenuPosition (popup, bevent);
XtManageChild (popup);
}
248
Motif Reference Manual
Motif Functions and Macros
...
extern Widget some_widget;
extern Widget my_menu;
XmMenuPosition
/* Where the menu is posted */
/* The menu to post */
XtAddEventHandler(some_widget, ButtonPressMask, False, PostIt, (XtPointer)
my_menu) ;
See Also
XmRowColumn(2), XmPopupMenu(2).
Motif Reference Manual
249
XmMessageBoxGetChild
Motif Functions and Macros
Name
XmMessageBoxGetChild – get the specified child of a MessageBox widget.
Synopsis
#include <Xm/MessageB.h>
Widget XmMessageBoxGetChild (Widget widget, unsigned char child)
Inputs
widget
Specifies the MessageBox widget.
child
Specifies the child of the MessageBox widget. Pass one of the values from the list below.
Returns
The widget ID of the specified child of the MessageBox.
Availability
As of Motif 2.0, the toolkit abstract child fetch routines are marked for deprecation. You should give preference to XtNameToWidget(), except when fetching
the MessageBox default button.
Description
XmMessageBoxGetChild() returns the widget ID of the specified child of the
MessageBox widget.
Usage
The child values XmDIALOG_CANCEL_BUTTON,
XmDIALOG_HELP_BUTTON, and XmDIALOG_OK_BUTTON specify the
action buttons in the widget. A child value of
XmDIALOG_DEFAULT_BUTTON specifies the current default button. The
value XmDIALOG_SYMBOL_LABEL specifies the label used to display the
message symbol, while XmDIALOG_MESSAGE_LABEL specifies the message
label. XmDIALOG_SEPARATOR specifies the separator that is positioned
between the message and the action buttons. For more information on the different children of the MessageBox, see the manual page in Section 2, Motif and Xt
Widget Classes.
Widget Hierarchy
As of Motif 2.0, most Motif composite child fetch routines are marked as deprecated. However, since it is not possible to fetch the
XmDIALOG_DEFAULT_BUTTON child using a public interface except
through XmMessageBoxGetChild(), the routine should not be considered
truly deprecated. For consistency with the preferred new style, when fetching all
other child values, consider giving preference to the Intrinsics routine XtNameToWidget(), passing one of the following names as the second parameter:
250
Motif Reference Manual
Motif Functions and Macros
“Cancel”
“OK”
“Separator”
“Help”
“Symbol”
“Message”
XmMessageBoxGetChild
(XmDIALOG_CANCEL_BUTTON)
(XmDIALOG_OK_BUTTON)
(XmDIALOG_SEPARATOR)
(XmDIALOG_HELP_BUTTON)
(XmDIALOG_SYMBOL_LABEL)
(XmDIALOG_MESSAGE_LABEL)
Structures
The possible values for child are:
XmDIALOG_CANCEL_BUTTON
XmDIALOG_DEFAULT_BUTTON
XmDIALOG_HELP_BUTTON
XmDIALOG_SYMBOL_LABEL
XmDIALOG_MESSAGE_LABEL
XmDIALOG_OK_BUTTON
XmDIALOG_SEPARATOR
See Also
XmBulletinBoard(2), XmBulletinBoardDialog(2), XmErrorDialog(2),
XmInformationDialog(2), XmManager(2), XmMessageBox(2),
XmMessageDialog(2), XmQuestionDialog(2),
XmTemplateDialog(2), XmWarningDialog(2),
XmWorkingDialog(2).
Motif Reference Manual
251
XmNotebookGetPageInfo
Motif Functions and Macros
Name
XmNotebookGetPageInfo – return information about a Notebook page.
Synopsis
#include <Xm/Notebook.h>
XmNotebookPageStatus XmNotebookGetPageInfo ( Widget
widget,
int
page_number,
XmNotebookPageInfo
*page_info)
Inputs
widget
Specifies the Notebook widget.
page_number Specifies a logical page number.
Outputs
page_info
placed.
Returns a structure into which the requested page information is
Returns
The status of the search for the requested information.
Availability
Motif 2.0 and later.
Description
XmNotebookGetPageInfo() returns information associated with a logical
page of the Notebook.
The Notebook searches through the list of its children, looking for those which
are associated with the logical page number specified by page_number. The
Notebook principally searches for page children, but collects data in passing on
any status area child with a matching logical number, or major and minor tab
children whose logical page number does not exceed page_number. The function
returns within the page_info structure the data collected for each of the child
widget types.
If the requested page_number is greater than the value of the Notebook XmNlastPageNumber resource, or less than the Notebook XmNfirstPageNumber value,
the function returns XmPAGE_INVALID.
Otherwise, if exactly one matching page child is found, the function returns
XmPAGE_FOUND. If more than one matching page child is found, the routine
returns XmPAGE_DUPLICATED. For no matching page child, the return value
is XmPAGE_EMPTY.
252
Motif Reference Manual
Motif Functions and Macros
XmNotebookGetPageInfo
Usage
XmNotebookGetPageInfo performs a linear search through the children of the
Notebook for widgets whose XmNpageNumber constraint resource matches the
requested page_number. If a matching child is found with the XmNnotebookChildType resource set to XmPAGE, the widget ID is stored within the
page_widget element of the page_info structure. If a matching child is of type
XmSTATUS_AREA, the widget ID is placed in the status_area_widget element.
If during the search a child widget is found which is of type XmMAJOR_TAB,
and the logical page number of the child does not exceed page_number, the
widget ID is stored within the major_tab_widget element. Again, if a child
widget is found of type XmMINOR_TAB, and the logical page number of the
child does not exceed page_number, the widget ID is stored within the
minor_tab_widget element of page_info.
The page_widget, status_area_widget, major_tab_widget, and minor_tab_widget
elements of the page_info structure are set during the search as each Notebook
child is compared, even if no XmPAGE child is found, or if page_number
exceeds the Notebook first and last page resources. An element of the page_info
structure can be NULL if no child of the associated type is found with a logical
page number which meets the matching criteria.
The Notebook automatically sorts children into ascending logical page order, and
the search is terminated as soon as any child has a logical page number which
exceeds the requested page_number.
Structures
XmNotebookPageInfo is defined as follows:
typedef struct {
int
page_number;
Widget
page_widget;
Widget
status_area_widget;
Widget
major_tab_widget;
Widget
minor_tab_widget;
} XmNotebookPageInfo;
/* the requested page number
*/
/* any matching page widget
*/
/* any matching status area widget */
/* the nearest major tab widget */
/* the nearest minor tab widget */
A XmNotebookPageStatus can have one of the following values:
XmPAGE_FOUND
XmPAGE_EMPTY
XmPAGE_INVALID
XmPAGE_DUPLICATED
See Also
XmNotebook(2).
Motif Reference Manual
253
XmObjectAtPoint
Motif Functions and Macros
Name
XmObjectAtPoint – determine the child nearest to a point.
Synopsis
#include <Xm/Xm.h>
Widget XmObjectAtPoint (Widget widget, Position x, Position y)
Inputs
widget
x
y
Specifies a composite widget.
Specifies an X coordinate relative to the widget left side.
Specifies an Y coordinate relative to the widget top side.
Returns
The widget most closely associated with the coordinate x, y.
Availability
Motif 2.0 or later.
Description
XmObjectAtPoint() searches the list of children of widget, and returns the
widget ID of the child associated with the x, y coordinate. x and y are interpreted
as pixel values, relative to the top left of the Manager widget.
Usage
XmObjectAtPoint() calls the object_at_point method associated with a Manager widget, in order to determine the child of the Manager most closely associated with the coordinate specified by x and y. Each widget class may override the
object_at_point method inherited from Manager, to redefine what is meant by
"associated".
The default Manager class method returns the last managed gadget which contains the coordinate.
The DrawingArea overrides the default method, and performs a simple linear
search for the first managed child, widget or gadget, which contains the coordinate.
The Container overrides the object_at_point method, by searching through the
list of logical child nodes, using any XmQTpointIn trait held by each child to
determine a logical match with the coordinate. If no XmQTpointIn is held by the
child, the Container simply checks whether the coordinate is within the child
dimensions. The IconGadget holds the XmQTpointIn trait, although neither this
fact nor the trait itself is otherwise documented.
See Also
XmContainer(2), XmDrawingArea(2), XmGadget(2),
XmIconGadget(2), XmManager(2).
254
Motif Reference Manual
Motif Functions and Macros
XmOptionButtonGadget
Name
XmOptionButtonGadget – get the CascadeButtonGadget in an option menu
Synopsis
#include <Xm/RowColumn.h>
Widget XmOptionButtonGadget (Widget option_menu)
Inputs
option_menu
Specifies the option menu.
Returns
The widget ID of the internal CascadeButtonGadget.
Description
XmOptionButtonGadget() returns the widget ID for the internal CascadeButtonGadget that is created when the specified option_menu widget is created.
An option menu is a RowColumn widget containing two gadgets: a CascadeButtonGadget that displays the current selection and posts the submenu and a LabelGadget that displays the XmNlabelString resource.
Usage
XmOptionButtonGadget() provides a way for an application to access the
internal CascadeButtonGadget that is part of an option menu. Once you have
retrieved the gadget, you can alter its appearance. In Motif 1.2, you can also specify resources for the gadget using the widget name OptionButton.
See Also
XmOptionLabelGadget(1), XmCascadeButtonGadget(2),
XmLabelGadget(2), XmOptionMenu(2), XmRowColumn(2).
Motif Reference Manual
255
XmOptionLabelGadget
Motif Functions and Macros
Name
XmOptionLabelGadget – get the LabelGadget in an option menu.
Synopsis
#include <Xm/RowColumn.h>
Widget XmOptionLabelGadget (Widget option_menu)
Inputs
option_menu
Specifies the option menu.
Description
XmOptionLabelGadget() returns the widget ID for the internal LabelGadget
that is created when the specified option_menu widget is created. An option
menu is a RowColumn widget containing two gadgets: a LabelGadget that displays the XmNlabelString resource, and a CascadeButtonGadget that displays
the current selection and posts the submenu.
Usage
XmOptionLabelGadget() provides a way for an application to access the
internal LabelGadget that is part of an option menu. Once you have retrieved the
gadget, you can alter its appearance. In Motif 1.2, you can also specify resources
for the gadget using the widget name OptionLabel.
See Also
XmOptionButtonGadget(1), XmCascadeButtonGadget(2),
XmLabelGadget(2), XmOptionMenu(2), XmRowColumn(2).
256
Motif Reference Manual
Motif Functions and Macros
XmParseMappingCreate
Name
XmParseMappingCreate – create a parse mapping.
Synopsis
XmParseMapping XmParseMappingCreate (Arg *arg_list, Cardinal arg_count)
Inputs
arg_list
arg_count
Specifies an argument list, consisting of resource name/value pairs.
Specifies the number of arguments in arg_list.
Returns
An allocated parse mapping.
Availability
Motif 2.0 and later.
Description
XmParseMappingCreate() creates a parse mapping, which is an entry in a
parse table. A parse mapping consists minimally of a match pattern, and a substitution pattern or procedure, which can be used by string parsing functions in
order to compare against and subsequently transform text. A parse mapping is
created through a resource style argument list, where arg_list is an array of
resource name/value pairs, and arg_count is the number of such pairs.
Usage
A parse table is an array of parse mappings. XmParseMappingCreate() creates a parse mapping using a resource style parameter list. The parse table can
subsequently be passed to XmStringParseText() in order to filter or modify
an input string.
XmParseMappingCreate() allocates storage associated with the returned
parse mapping object. It is the responsibility of the programmer to free the allocated memory by a call to XmParseMappingFree() at the appropriate
moment.
Example
The following code fragment creates a parse mapping which performs a simple
swap of occurrences of two characters within an input string:
char *swapover ( char *input,
/* input string */
char *a,
/* only first character in array used */
char *b)
/* only first character in array used */
{
XmString
tmp;
XmParseMapping
parse_mapping;
Motif Reference Manual
257
XmParseMappingCreate
XmParseTable
(XmParseMapping));
Cardinal
Arg
Cardinal
char
Motif Functions and Macros
parse_table = (XmParseTable) XtCalloc (2, sizeof
parse_table_index = 0;
argv[4];
argc = 0;
*output = (char *) 0;
/* create a XmParseMapping object to swap *a with *b */
argc = 0;
tmp = XmStringCreateLocalized (a);
XtSetArg (argv[argc], XmNincludeStatus,
XmINSERT);
argc++;
XtSetArg (argv[argc], XmNsubstitute,
tmp);
argc++;
XtSetArg (argv[argc], XmNpattern,
b);
argc++;
XtSetArg (argv[argc], XmNpatternType,
XmCHARSET_TEXT);
argc++;
parse_mapping = XmParseMappingCreate (argv, argc);
parse_table[parse_table_index++] = parse_mapping;
XmStringFree (tmp);
/* create a XmParseMapping object to swap *b with *a */
argc = 0;
tmp = XmStringCreateLocalized (b);
XtSetArg (argv[argc], XmNincludeStatus,
XmINSERT);
argc++;
XtSetArg (argv[argc], XmNsubstitute,
tmp);
argc++;
XtSetArg (argv[argc], XmNpattern,
a);
argc++;
XtSetArg (argv[argc], XmNpatternType,
XmCHARSET_TEXT);
argc++;
parse_mapping = XmParseMappingCreate (argv, argc);
parse_table[parse_table_index++] = parse_mapping;
XmStringFree (tmp);
/* substitute using the XmParseMapping. */
tmp = XmStringParseText ((XtPointer) input, NULL, NULL,
XmCHARSET_TEXT,
parse_table, parse_table_index, NULL);
XmParseTableFree (parse_table, parse_table_index);
258
Motif Reference Manual
Motif Functions and Macros
XmParseMappingCreate
/* convert XmString to String */
if (tmp != (XmString) 0) {
output = (char *) XmStringUnparse (tmp, NULL,
XmCHARSET_TEXT,
XmCHARSET_TEXT, NULL,
0, XmOUTPUT_ALL);1
XmStringFree (tmp);
}
return output;
}
See Also
XmParseMappingFree(1), XmParseMappingGetValues(1),
XmParseMappingSetValues(1), XmParseTableFree(1),
XmStringParseText(1), XmStringUnparse(1),
XmParseMapping(2).
1.The code sample in the 2nd edition used XmStringGetLtoR() to convert the compound string.
StringGetLtoR() is deprecated as of Motif 2.0.
Motif Reference Manual
Xm-
259
XmParseMappingFree
Motif Functions and Macros
Name
XmParseMappingFree – free the memory used by a parse mapping.
Synopsis
void XmParseMappingFree (XmParseMapping parse_mapping)
Inputs
parse_mapping Specifies a parse mapping.
Availability
Motif 2.0 and later.
Description
XmParseMappingFree() deallocates storage used by the specified parse mapping object.
Usage
The XmParseMapping type is opaque, and represents an entry in a parse table,
which can be used for transforming text. A parse mapping is created by
XmParseMappingCreate(), which allocates storage for the object represented by the type, and it is the responsibility of the programmer to reclaim the
memory when the parse mapping is no longer required.
It is important to call XmParseMappingFree() rather than XtFree() upon
redundant parse mappings, otherwise compound strings internally referenced by
the object are not deallocated.
See Also
XmParseMappingCreate(1), XmParseMappingGetValues(1),
XmParseMappingSetValues(1), XmParseTableFree(1),
XmStringParseText(1), XmParseMapping(2).
260
Motif Reference Manual
Motif Functions and Macros
XmParseMappingGetValues
Name
XmParseMappingGetValues – fetch resources from a parse mapping object.
Synopsis
void XmParseMappingGetValues ( XmParseMapping
Arg
Cardinal
parse_mapping,
*arg_list,
arg_count)
Inputs
parse_mapping Specifies a parse mapping object.
arg_count
Specifies the number of arguments in the list arg_list.
Outputs
arg_list
Specifies the argument list of name/value pairs that contain the
resource names and addresses into which the resource values
are to be stored.
Availability
Motif 2.0 and later.
Description
XmParseMappingGetValues() fetches selected attributes from
parse_mapping. The set of attributes retrieved is specified through the resource
list arg_list, each element of the list being a structure containing a name/value
pair. The number of elements within the list is given by arg_count.
Usage
If the XmNsubstitute attribute of the parse mapping is retrieved, the procedure
returns a copy of the internal value. It is the responsibility of the programmer to
recover the allocated space at a suitable point by calling XmStringFree().
Example
The following code illustrates fetching the values from an XmParseMapping:
XtPointer
XmTextType
XmString
XmParseProc
XtPointer
XmIncludeStatus
Arg
Cardinal
pattern;
pattern_type;
substitute;
parse_proc;
client_data;
include_status;
argv[6];
argc = 0;
/* construct a resource-style argument list for all XmParseMapping values */
XtSetArg (argv[argc], XmNpattern,
&pattern);
argc++;
XtSetArg (argv[argc], XmNpatternType,
&pattern_type);
argc++;
Motif Reference Manual
261
XmParseMappingGetValues
XtSetArg (argv[argc], XmNsubstitute,
XtSetArg (argv[argc], XmNinvokeParseProc,
XtSetArg (argv[argc], XmNclientData,
XtSetArg (argv[argc], XmNincludeStatus,
Motif Functions and Macros
&substitute);
&parse_proc);
&client_data);
&include_status);
argc++;
argc++;
argc++;
argc++;
/* fetch the values. parse_mapping here is an unspecified XmParseMapping */
XmParseMappingGetValues (parse_mapping, argv, argc);
...
/* XmParseMappingGetValues returns a copy of the XmNsubstitute value */
/* which must be freed when no longer required by the application */
XmStringFree (substitute);
See Also
XmParseMappingCreate(1), XmParseMappingFree(1),
XmParseMappingSetValues(1), XmParseTableFree(1),
XmParseMapping(2).
262
Motif Reference Manual
Motif Functions and Macros
XmParseMappingSetValues
Name
XmParseMappingSetValues – sets resources for a parse mapping object.
Synopsis
void XmParseMappingSetValues ( XmParseMapping
Arg
Cardinal
Inputs
parse_mapping
arg_list
arg_count
parse_mapping,
*arg_list,
arg_count)
Specifies a parse mapping object.
Specifies the list of name/value pairs containing resources to
be modified.
Specifies the number of arguments in the list arg_list.
Availability
Motif 2.0 and later.
Description
XmParseMappingSetValues() sets selected attributes within
parse_mapping. The set of attributes which is modified is specified through the
resource list arg_list, each element of the list being a structure containing a
name/value pair. The number of elements within the list is given by arg_count.
Usage
If the XmNsubstitute attribute of the parse mapping is set, the procedure internally takes a copy of the supplied value. It is the responsibility of the programmer
to recover the allocated space at a suitable point by calling XmStringFree().
Example
The following skeleton code illustrates changing the values of a parse mapping:
XmIncludeStatus map_tab ( XtPointer
XtPointer
*/
XmTextType
*/
XmStringTag
*/
XmParseMapping
*/
int
*/
XmString
Motif Reference Manual
*in_out,
text_end,
/* unused
type,
/* unused
tag,
/* unused
entry,
/* unused
pattern_length,
/* unused
*str_out,
263
XmParseMappingSetValues
Motif Functions and Macros
XtPointer
call_data)
/* unused
*/
{
/* Insert an XmString Tab component into the output stream */
*str_out = XmStringComponentCreate (XmSTRING_COMPONENT_TAB,
0, NULL);
*in_out = (*in_out + 1);
return XmINSERT;
}
/* change a parse mapping to invoke the above parse procedure */
void set_parse_tab_mapping (XmParseMapping parse_mapping)
{
Arg
argv[4];
Cardinal argc = 0;
/* construct resource-style argument list for XmParseMapping values */
XtSetArg (argv[argc], XmNpattern,
"\t");
argc++;
XtSetArg (argv[argc], XmNpatternType,
XmCHARSET_TEXT);
argc++;
XtSetArg (argv[argc], XmNincludeStatus,
XmINVOKE);
argc++;
XtSetArg (argv[argc], XmNinvokeParseProc,
map_tab);
argc++;
/* change the values */
XmParseMappingSetValues (parse_mapping, argv, argc);
}
See Also
XmParseMappingCreate(1), XmParseMappingFree(1),
XmParseMappingGetValues(1), XmParseTableFree(1),
XmParseMapping(2),
264
Motif Reference Manual
Motif Functions and Macros
XmParseTableFree
Name
XmParseTableFree – free the memory used by a parse table.
Synopsis
void XmParseTableFree (XmParseTable parse_table, Cardinal parse_count)
Inputs
parse_table
parse_count
Specifies a parse table.
Specifies the number of entries in the parse table.
Availability
Motif 2.0 and later.
Description
XmParseTableFree() deallocates storage used by the specified parse_table.
In addition, the function deallocates storage used by any parse mapping elements
of the table. parse_count indicates the number of mapping elements within the
table.
Usage
A parse table is an array of XmParseMapping objects. The XmParseMapping is
an opaque type, which is used when transforming text. Each parse mapping
object allocates memory in addition to any memory allocated by the parse table
array. It is important to call XmParseTableFree() rather than XtFree()
when deallocating storage associated with a parse table, otherwise objects constituent within the array, and compound strings internally referenced by the parse
mapping objects, are not deallocated. The function should be called when a parse
table is no longer needed.
Example
/* Allocate a parse table */
XmParseTable
parse_table = (XmParseTable) XtCalloc (2, sizeof
(XmParseMapping));
Cardinal
parse_table_index = 0;
XmParseMapping
parse_mapping;
Arg
argv[MAX_ARGS];
Cardinal
argc = 0;
/* Create a XmParseMapping object */
argc = 0;
...
parse_mapping = XmParseMappingCreate (argv, argc);
/* Insert into parse table */
parse_table[parse_table_index++] = parse_mapping;
Motif Reference Manual
265
XmParseTableFree
Motif Functions and Macros
/* Create another XmParseMapping object */
argc = 0;
...
parse_mapping = XmParseMappingCreate (argv, argc);
/* Insert into parse table */
parse_table[parse_table_index++] = parse_mapping;
/* Use the XmParseTable. */
tmp = XmStringParseText ((XtPointer) input, NULL, NULL,
XmCHARSET_TEXT, parse_table,
parse_table_index, NULL);
/* Free the parse table: this also frees the parse mappings */
XmParseTableFree (parse_table, parse_table_index);
See Also
XmParseMappingCreate(1), XmParseMappingFree(1),
XmParseMappingGetValues(1), XmParseMappingSetValues(1),
XmParseMapping(2).
266
Motif Reference Manual
Motif Functions and Macros
XmPrintPopupPDM
Name
XmPrintPopupPDM – notify the Print Display Manager.
Synopsis
#include <Xm/Print.h>
XtEnum XmPrintPopupPDM (Widget print_shell, Widget video_shell)
Inputs
print_shell
video_shell
required.
Specifies a PrintShell widget.
Specifies the widget on whose behalf the PDM dialog is
Returns
Returns XmPDM_NOTIFY_SUCCESS if the PDM was notified,
XmPDM_NOTIFY_FAIL otherwise.
Availability
Motif 2.1 and later.
Note that not all operating system vendors incorporate the XmPrintShell within
the native Motif toolkit.1
Description
XmPrintPopupPDM() sends a notification to start a Print Display Manager for
the application. The notification is issued to either the display associated with
print_shell, or the display of video_shell, depending upon the value of the environment variable XPDMDISPLAY. XPDMDISPLAY can only be set to "print"
or "video". If the value is "print", the notification is sent to the display of
print_shell, and similarly the value "video" sends the notification to the display
of video_shell. If the notification could be sent, the function returns
XmPDM_NOTIFY_SUCCESS, otherwise the return value is
XmPDM_NOTIFY_FAIL.
Usage
XmPrintPopupPDM() is a convenience function which issues a notification
through the X selection mechanisms in order to start a Print Dialog Manager. The
notification is issued asynchronously: the return value
XmPDM_NOTIFY_SUCCESS indicates that the message has successfully been
issued, not that any PDM is now initialized. In order to track the status of the
PDM, the programmer registers an XmNpdmNotificationCallback with the
widget print_shell, which must be an instance of the PrintShell widget class. To
ensure that the contents of the video_shell is not modified whilst the PDM is ini1.Sun Solaris being a case in point.
Motif Reference Manual
267
XmPrintPopupPDM
Motif Functions and Macros
tializing, XmPrintPopupPDM() creates an input-only window over the top of
video_shell, and the window is only removed when the PDM indicates that it is
present, or if the selection XmIPDM_START times out. The timeout period is set
at two minutes.
See Also
XmPrintSetup(1), XmPrintToFile(1), XmRedisplayWidget(1),
XmPrintShell(2).
268
Motif Reference Manual
Motif Functions and Macros
XmPrintSetup
Name
XmPrintSetup – create a Print Shell widget.
Synopsis
#include <Xm/Print.h>
Widget XmPrintSetup ( Widget
Screen
String
ArgList
Cardinal
Inputs
video_widget
print_screen
name
arg_list
arg_count
video_widget,
*print_screen,
name
arg_list,
arg_count)
Specifies a widget from which video application data is
fetched.
Specifies the screen on which the PrintShell is created.
Specifies the name of the created PrintShell.
Specifies an argument list of name/value pairs that contain
resources for the PrintShell.
Specifies the number of arguments in the list arg_list.
Returns
The created PrintShell, or NULL if no ApplicationShell can be found from
video_widget,
Availability
Motif 2.1 and later.
Note that not all operating system vendors incorporate the PrintShell in their
native toolkit.1
Description
XmPrintSetup() creates a PrintShell widget with the given name on the
screen print_screen. The new PrintShell is returned to the application. Resources
which configure the new print shell are supplied through an array of structures
which contain name/value pairs. The array of resources is arg_list, and the
number of items in the array is arg_count.
Usage
XmPrintSetup() creates a new ApplicationShell on the screen specified by
print_screen, and thereafter creates a PrintShell as a popup child. The new ApplicationShell is created with the same name and class as the ApplicationShell from
which video_widget is descended. The XmNmappedWhenManaged resource of
1.For example, Sun Solaris includes the headers, but does not compile the widget into the Motif library.
Motif Reference Manual
269
XmPrintSetup
Motif Functions and Macros
the PrintShell is set to False under the assumption that subsequent notification of
the start of a job or page is the correct time to map the widget. The print shell is
finally realized, and returned.
See Also
XmPrintPopupPDM(1), XmPrintToFile(1), XmRedisplayWidget(1),
XmPrintShell(2).
270
Motif Reference Manual
Motif Functions and Macros
XmPrintToFile
Name
XmPrintToFile – save X Print Server data to file.
Synopsis
#include <Xm/Print.h>
XtEnum XmPrintToFile ( Display
String
XPFinishProc
XPointer
Inputs
display
file_name
finish_proc
client_data
*display,
file_name,
finish_proc,
client_data)
Specifies the print connection to the X server.
Specifies the name of the file to contain the print output.
Specifies a procedure called when printing is finished.
Specifies application data to be passed to finish_proc.
Returns
True if printing can be initiated, otherwise False.
Availability
Motif 2.1 and later.
Note that not all operating system vendors incorporate the XmPrintShell in their
native toolkits.1
Description
XmPrintToFile() is a convenience function which provides a simple interface
onto the X Print mechanisms, in order to save print data to the file file_name.
Printing takes place asynchronously, and the programmer receives notification of
the status of the printing task by supplying finish_proc, which is called when the
task is finished. The display parameter is the print connection to the X server, and
is used to deduce an application name and class.
Usage
If XmPrintToFile() cannot open the file file_name for writing, create a pipe,
or fork off a child process, the procedure returns False. An application name and
class is deduced using the display parameter, and these are used by the child
process, which creates a new application context, and opens a new display connection using the same name and class as the application process. Data is
retrieved from the X server through a call to XpGetDocumentData(). The parent process does not wait for the child to complete, but returns immediately after
1.For example, Sun Solaris supply the widget headers, but do not compile the component into the Motif library.
Motif Reference Manual
271
XmPrintToFile
Motif Functions and Macros
initiating the child process. The return value True therefore does not mean that
the print task is complete, merely that the task is initiated.
The application is notified of task completion by supplying an XPFinishProc.
The status parameter passed to the finish procedure when the task is completed is
set to XPGetDocFinished on successful completion. If for any reason the child
process fails to print the data, the file file_name is both closed and removed. The
file is closed in any case prior to calling the XPFinishProc.
XpStartJob() must be called by the application before XmPrintToFile()
can be called.
Structures
An XPFinishProc is specified as follows:
typedef void (*XPFinishProc)( Display
XPContext
XPGetDocStatus
XPointer
*display,
context,
status,
client_data);
If status is XPGetDocFinished, the print task has completed successfully.
See Also
XmPrintPopupPDM(1), XmPrintSetup(1), XmRedisplayWidget(1),
XmPrintShell(2).
272
Motif Reference Manual
Motif Functions and Macros
XmProcessTraversal
Name
XmProcessTraversal – set the widget that has the keyboard focus.
Synopsis
Boolean XmProcessTraversal (Widget widget, XmTraversalDirection direction)
Inputs
widget
direction
Specifies the widget whose hierarchy is to be traversed.
Specifies the direction in which to traverse the hierarchy. Pass one
of the values from the list below.
Returns
True on success or False otherwise.
Description
XmProcessTraversal() causes the input focus to change to another widget
under application control, rather than as a result of keyboard traversal events
from a user. widget specifies the widget whose hierarchy is traversed up to the
shell widget. If that shell has the keyboard focus, XmProcessTraversal()
changes the keyboard focus immediately. If that shell does not have the focus, the
routine does not have an effect until the shell receives the focus.
The direction argument specifies the nature of the traversal to be made. In each
case, the routine locates the hierarchy that contains the specified widget and then
performs the action that is particular to the direction. If the new setting succeeds,
XmProcessTraversal() returns True. The routine returns False if the keyboard focus policy is not XmEXPLICIT, if no traversable items exist, or if the
arguments are invalid.
Usage
For XmTRAVERSE_CURRENT, if the tab group that contains widget is inactive, it is made the active tab group. If widget is in the active tab group, it is given
the keyboard focus; if widget is the active tab group, the first traversable item in it
is given the keyboard focus. For XmTRAVERSE_UP, XmTRAVERSE_DOWN,
XmTRAVERSE_LEFT, and XmTRAVERSE_RIGHT, in the hierarchy that contains widget, the item in the specified direction from the active item is given the
keyboard focus. For XmTRAVERSE_NEXT and XmTRAVERSE_PREV, in the
hierarchy that contains widget, the next and previous items in child order from
the active item are given keyboard focus. For XmTRAVERSE_HOME, in the
hierarchy that contains widget, the first traversable item is given the keyboard
focus. For XmTRAVERSE_NEXT_TAB_GROUP and
XmTRAVERSE_PREV_TAB_GROUP, in the hierarchy that contains widget, the
next and previous tab groups from the active tab group are given the keyboard
focus.
Motif Reference Manual
273
XmProcessTraversal
Motif Functions and Macros
In Motif 2.0 and later, new XmTraversalDirection values
XmTRAVERSE_GLOBALLY_FORWARD and
XmTRAVERSE_GLOBALLY_BACKWARD are provided in order to implement the XmDisplay resource XmNenableButtonTab. If enabled, for
XmTRAVERSE_GLOBALLY_FORWARD navigation proceeds to the next (or
downwards, depending upon orientation) item within the current tab group,
unless the current location is the last item in the group, when navigation is into
the next tab group. Similarly, for XmTRAVERSE_GLOBALLY_BACKWARD
navigation proceeds to the previous (or upwards) item in the current tab group,
unless the current location is the first item in the group, when navigation is into
the previous tab group. The interpretation of the direction values
XmTRAVERSE_GLOBALLY_FORWARD and
XmTRAVERSE_GLOBALLY_BACKWARD is reversed where XmNlayoutDirection is XmRIGHT_TO_LEFT.
XmProcessTraversal() does not allow traversal to widgets in different
shells or widgets that are not mapped. Calling XmProcessTraversal()
inside a XmNfocusCallback causes a segmentation fault.
Example
The following code fragments shows the use of XmProcessTraversal() as a
callback routine for a text widget. When the user presses the Return key, the keyboard focus is advanced to the next input area:
Widget form, label, text;
form = XtVaCreateWidget ("form", xmFormWidgetClass, parent,
XmNorientation, XmHORIZONTAL,
NULL);
label = XtVaCreateManagedWidget ("label", xmLabelGadgetClass, form,
XmNleftAttachment,
XmATTACH_FORM,
XmNtopAttachment,
XmATTACH_FORM,
XmNbottomAttachment,
XmATTACH_FORM,
NULL);
text = XtVaCreateManagedWidget ("text", xmTextWidgetClass, form,
XmNleftAttachment,
XmATTACH_WIDGET,
XmNleftWidget,
label,
XmNtopAttachment,
XmATTACH_FORM,
XmNrightAttachment,
XmATTACH_FORM,
XmNbottomAttachment,
XmATTACH_FORM,
NULL);
XtAddCallback (text, XmNactivateCallback,
274
Motif Reference Manual
Motif Functions and Macros
XmProcessTraversal
XmProcessTraversal, (XtPointer)
XmTRAVERSE_NEXT_TAB_GROUP);
XtManageChild (form);
Structures
The possible values for direction are:
XmTRAVERSE_CURRENT
XmTRAVERSE_UP
XmTRAVERSE_DOWN
XmTRAVERSE_LEFT
XmTRAVERSE_NEXT_TAB_GROUP
XmTRAVERSE_RIGHT
XmTRAVERSE_PREV_TAB_GROUP
XmTRAVERSE_GLOBALLY_FORWARD
XmTRAVERSE_GLOBALLY_BACKWARD
XmTRAVERSE_NEXT
XmTRAVERSE_PREV
XmTRAVERSE_HOME
See Also
XmGetFocusWidget(1), XmGetTabGroup(1), XmGetVisibility(1),
XmIsTraversable(1).
Motif Reference Manual
275
XmRedisplayWidget
Motif Functions and Macros
Name
XmRedisplayWidget – force widget exposure for printing.
Synopsis
#include <Xm/Print.h>
void XmRedisplayWidget (Widget widget)
Inputs
widget
Specifies the widget to redisplay.
Availability
Motif 2.1 and later.
Note that not all operating system vendors compile the XmPrintShell into their
native Motif toolkits.1
Description
XmRedisplayWidget() forces widget to redisplay itself by invoking the
expose method of the widget. The routine is a convenience function which hides
the internals of the X11R6 Xp mechanisms, which use widget exposure in order
to implement printing.
Usage
XmRedisplayWidget() constructs a region which corresponds precisely to
the location and area occupied by a widget. The expose method of the widget is
called directly using the region in order to redisplay the widget. XmRedisplayWidget() is synchronous in effect. Asynchronous printing is performed
by creating a PrintShell, and specifying XmNstartJobCallback, XmNendJobCallback, and XmNpageSetupCallback procedures which are invoked in response to
X Print events as they arrive.
XmRedisplayWidget() is not multi-thread safe, nor is the widget parameter
fully validated: it is implicitly assumed to be the descendant of a PrintShell.
1.Sun Solaris supplied the widget headers, but the widget itself is compiled out of the Motif library.
276
Motif Reference Manual
Motif Functions and Macros
XmRedisplayWidget
Example
The following code synchronously prints the contents of a text widget:
Widget
app_shell, app_text;
Screen
print_screen;
Display print_display;
Widget
print_shell, print_form, print_text;
short
rows;
int
lines, pages, page;
char
*data;
...
/* create a connection to the X Print server */
print_shell = XmPrintSetup (app_shell, print_screen, "PrintShell", NULL, 0);
/* create a suitable print hierarchy */
print_form = XmCreateForm (print_shell,...);
print_text = XmCreateText (print_form,...);
/* configure and manage the print hierarchy */
...
/* copy the video text to the print text */
/* what is copied depends upon whether it is */
/* contents and/or visuals that are printed */
...
data = XmTextGetString (app_text);
XmTextSetString (print_text, data);
XtFree (data);
...
/* start a print job */
print_display = XtDisplay (print_shell);
XpStartJob (print_display, XPSpool);
/* deduce number of logical pages in the print text widget */
XtVaGetValues (print_text, XmNrows, &rows, XmNtotalLines, &lines, 0);
for (page = 0, pages = lines / rows; page < pages; page++) {
/* start of page notification */
XpStartPage (print_display, XtWindow (print_shell), False);
/* force the print text to expose itself */
XmRedisplayWidget (print_text);
/* end of page notification */
XpEndPage (print_display);
/* scroll to next page */
Motif Reference Manual
277
XmRedisplayWidget
Motif Functions and Macros
XmTextScroll (print_text, rows);
}
/* end of print job notification */
XpEndJob (print_display);
...
See Also
XmPrintPopupPDM(1), XmPrintSetup(1), XmPrintToFile(1),
XmPrintShell(2).
278
Motif Reference Manual
Motif Functions and Macros
XmRegisterSegmentEncoding
Name
XmRegisterSegmentEncoding – register a compound text encoding format for a
font list element tag.
Synopsis
char *XmRegisterSegmentEncoding (char *fontlist_tag, char *ct_encoding)
Inputs
fontlist_tag
ct_encoding
Specifies the compound string font list element tag.
Specifies the compound text character set.
Returns
The old compound text encoding format for a previously-registered font list element tag or NULL for a new font list element tag.
Availability
Motif 1.2 and later.
Description
XmRegisterSegmentEncoding() registers the specified compound text
encoding format ct_encoding for the specified fontlist_tag. Both fontlist_tag and
ct_encoding must be NULL-terminated ISO8859-1 strings. If the font list tag is
already associated with a compound text encoding format, registering the font list
tag again overwrites the previous entry and the routine returns the previous compound text format. If the font list tag is has not been registered before, the routine
returns NULL. If ct_encoding is NULL, the font list tag is unregistered. If
ct_encoding is the reserved value XmFONTLIST_DEFAULT_TAG, the font list
tag is mapped to the code set of the current locale. XmRegisterSegmentEncoding() allocates storage if the routine returns a character string; the application is responsible for freeing the storage using XtFree().
Usage
Compound text is an encoding that is designed to represent text from any locale.
Compound text strings identify their encoding using embedded escape
sequences. The compound text representation was standardized for X11R4 for
use as a text interchange format for interclient communication.
XmCvtXmStringToCT() converts a compound string into compound text. The
routine uses the font list tag of each compound string segment to select a compound text format for the segment. A mapping between font list tags and compound text encoding formats is stored in a registry.
XmRegisterSegmentEncoding() provides a way for an application to map
particular font list element tags to compound text encoding formats.
See Also
XmCvtXmStringToCT(1), XmMapSegmentEncoding(1).
Motif Reference Manual
279
XmRemoveFromPostFromList
Motif Functions and Macros
Name
XmRemoveFromPostFromList – make a menu inaccessible from a widget.
Synopsis
#include <Xm/RowColumn.h>
void XmRemoveFromPostFromList (Widget menu, Widget widget)
Inputs
menu
widget
Specifies a menu widget
Specifies the widget which no longer posts menu.
Availability
In Motif 2.0 and later, the functional prototype is removed from RowColumn.h,
although there is otherwise no indication that the procedure is obsolete. 1
Description
XmRemoveFromPostFromList() is the inverse of the procedure XmAddToPostFromWidget(). The menu hierarchy associated with menu is made inaccessible from widget.
Usage
If the type of menu is XmMENU_PULLDOWN, the XmNsubMenuId resource
of widget is set to NULL. If the type of menu is XmMENU_POPUP, event handlers presumably added to widget by XmAddToPostFromWidget() in order to
post the menu are removed.
No check is made to ensure that the XmNsubMenuId resource of widget is originally set to menu before clearing the value. Passing the wrong menu into the procedure can therefore have unwanted effects. There are implicit assumptions that
widget is a CascadeButton or CascadeButtonGadget when menu is
XmMENU_PULLDOWN, and that widget is not a Gadget when menu is
XmMENU_POPUP. These are not checked by the procedure.
See Also
XmAddToPostFromList(1), XmGetPostedFromWidget(1),
XmPopupMenu(2), XmPulldownMenu(2), XmRowColumn(2).
1.This is true of Motif 2.1.10, although the header reference is restored in the OpenMotif 2.1.30.
280
Motif Reference Manual
Motif Functions and Macros
XmRemoveProtocolCallback
Name
XmRemoveProtocolCallback – remove client callback from a protocol.
Synopsis
#include <Xm/Protocols.h>
void XmRemoveProtocolCallback ( Widget
Atom
Atom
XtCallbackProc
XtPointer
Inputs
shell
property
protocol
callback
closure
shell,
property,
protocol,
callback,
closure)
Specifies the widget associated with the protocol property.
Specifies the property that holds the protocol data.
Specifies the protocol atom.
Specifies the procedure that is to be removed.
Specifies any client data that is passed to the callback.
Description
XmRemoveProtocolCallback() removes the specified callback from the
list of callback procedures that are invoked when the client message corresponding to protocol is received.
Usage
A protocol is a communication channel between applications. Protocols are simply atoms, stored in a property on the top-level shell window for the application.
To communicate using a protocol, a client sends a ClientMessage event containing a property and protocol, and the receiving client responds by calling the associated protocol callback routine. XmRemoveProtocolCallback() allows
you to unregister one of these callback routines. The inverse routine is XmAddProtocolCallback().
See Also
XmAddProtocolCallback(1), XmInternAtom(1),
XmRemoveWMProtocolCallback(1), VendorShell(2).
Motif Reference Manual
281
XmRemoveProtocols
Motif Functions and Macros
Name
XmRemoveProtocols – remove protocols from the protocol manager.
Synopsis
#include <Xm/Protocols.h>
void XmRemoveProtocols (Widget shell, Atom property, Atom *protocols, Cardinal num_protocols)
Inputs
shell
property
protocols
num_protocols
Specifies the widget associated with the protocol property.
Specifies the property that holds the protocol data.
Specifies a list of protocol atoms.
Specifies the number of atoms in protocols.
Description
XmRemoveProtocols() removes the specified protocols from the protocol
manager and deallocates the internal tables for the protocols. If the specified shell
is realized and at least one of the protocols is active, the routine also updates the
handlers and the property. The inverse routine is XmAddProtocols().
Usage
A protocol is a communication channel between applications. Protocols are simply atoms, stored in a property on the top-level shell window for the application.
XmRemoveProtocols() allows you eliminate protocols that can be understood by your application. The inverse routine is XmAddProtocols().
See Also
XmAddProtocols(1), XmInternAtom(1), XmRemoveWMProtocols(1),
VendorShell(2).
282
Motif Reference Manual
Motif Functions and Macros
XmRemoveTabGroup
Name
XmRemoveTabGroup – remove a widget from a list of tab groups.
Synopsis
void XmRemoveTabGroup (Widget tab_group)
Inputs
tab_group
Specifies the widget to be removed.
Availability
In Motif 1.1, XmRemoveTabGroup() is obsolete. It has been superseded by setting XmNnavigationType to XmNONE.
Description
XmRemoveTabGroup() removes the specified tab_group widget from the list
of tab groups associated with the widget hierarchy. This routine is retained for
compatibility with Motif 1.0 and should not be used in newer applications. If
traversal behavior needs to be changed, this should be done by setting the XmNnavigationType resource directly.
Usage
A tab group is a group of widgets that can be traversed using the keyboard rather
than the mouse. Users move from widget to widget within a single tab group by
pressing the arrow keys. Users move between different tab groups by pressing the
Tab or Shift-Tab keys. The inverse routine is XmAddTabGroup().
See Also
XmAddTabGroup(1), XmGetTabGroup(1), XmManager(2),
XmPrimitive(2).
Motif Reference Manual
283
XmRemoveWMProtocolCallback
Motif Functions and Macros
Name
XmRemoveWMProtocolCallback – remove client callbacks from a
XA_WM_PROTOCOLS protocol.
Synopsis
#include <Xm/Protocols.h>
void XmRemoveWMProtocolCallback ( Widget
Atom
XtCallbackProc
XtPointer
Inputs
shell
protocol
callback
closure
shell,
protocol,
callback,
closure)
Specifies the widget associated with the protocol property.
Specifies the protocol atom.
Specifies the procedure that is to be removed.
Specifies any client data that is passed to the callback.
Description
XmRemoveWMProtocolCallback() is a convenience routine that calls
XmRemoveProtocolCallback() with property set to
XA_WM_PROTOCOL, the window manager protocol property.
Usage
The property XA_WM_PROTOCOLS is a set of predefined protocols for communication between clients and window managers. To communicate using a protocol, a client sends a ClientMessage event containing a property and protocol,
and the receiving client responds by calling the associated protocol callback routine. XmRemoveWMProtocolCallback() allows you to unregister one of
these callback routines with the window manager protocol property. The inverse
routine is XmAddWMProtocolCallback().
See Also
XmAddProtocolCallback(1), XmAddWMProtocolCallback(1),
XmInternAtom(1), XmRemoveProtocolCallback(1),
VendorShell(2).
284
Motif Reference Manual
Motif Functions and Macros
XmRemoveWMProtocols
Name
XmRemoveWMProtocols – remove the XA_WM_PROTOCOLS protocols from
the protocol manager.
Synopsis
#include <Xm/Protocols.h>
void XmRemoveWMProtocols (Widget shell, Atom *protocols, Cardinal
num_protocols)
Inputs
shell
protocols
num_protocols
Specifies the widget associated with the protocol property.
Specifies a list of protocol atoms.
Specifies the number of atoms in protocols.
Description
XmRemoveWMProtocols() is a convenience routine that calls XmRemoveProtocols() with property set to XA_WM_PROTOCOL, the window manager protocol property. The inverse routine is XmAddWMProtocols().
Usage
The property XA_WM_PROTOCOLS is a set of predefined protocols for communication between clients and window managers. XmRemoveWMProtocols() allows you to remove this protocol so that it is no longer understood by
your application. The inverse routine is XmAddWMProtocols().
See Also
XmAddProtocols(1), XmAddWMProtocols(1), XmInternAtom(1),
XmRemoveProtocols(1), VendorShell(2).
Motif Reference Manual
285
XmRenderTableAddRenditions
Motif Functions and Macros
Name
XmRenderTableAddRenditions – add renditions to a render table.
Synopsis
XmRenderTable XmRenderTableAddRenditions ( XmRenderTable
old_table,
XmRendition
*new_renditions,
Cardinal
new_rendition_count,
XmMergeMode
merge_mode)
Inputs
old_table
new_renditions
render table.
new_rendition_count
merge_mode
tag.
Specifies a render table.
Specifies an array of renditions to merge with the
Specifies the number of renditions in the array.
Specifies the action to take if entries have the same
Returns
The newly allocated merged render table.
Availability
Motif 2.0 and later.
Description
A render table is a set of renditions which can be used to specify the way in
which XmStrings are drawn. XmRenderTableAddRenditions() creates a
new render table by merging the list of renditions specified by new_renditions
into the renditions contained within old_table. If a rendition with the same tag is
found in both old_table and new_renditions, merge_mode is used to give precedence. The new render table is returned.
If old_table is NULL, a new render table is allocated which contains only the
renditions of new_renditions. If new_renditions is NULL or new_rendition_count
is zero, the old_table is returned unmodified. If a rendition within old_table has
the same tag as one within new_renditions, merge_mode determines how to
resolve the conflict. If merge_mode is XmMERGE_REPLACE, the rendition
within old_table is ignored, and the rendition within new_renditions is added to
the new table. If the mode is XmMERGE_SKIP, the new table contains the rendition from old_table, and that from new_renditions is ignored. If the mode is
XmMERGE_NEW, the rendition within new_renditions is used, except that
286
Motif Reference Manual
Motif Functions and Macros
XmRenderTableAddRenditions
where any resources of the rendition are unspecified, the value is copied from the
matching rendition from the old_table. A resource is unspecified if the value is
XmAS_IS or NULL. Lastly, if the mode is XmMERGE_OLD, it is the old_table
rendition which is added to the new table, and any unspecified resources are
taken from the new rendition.
Usage
The reference count for the original table is decremented and deallocated where
necessary, and a newly allocated render table containing the merged data is
returned. It is the responsibility of the programmer to reclaim the allocated memory for the returned render table by calling XmRenderTableFree() at a suitable point.
Example
The following specimen code creates a set of renditions and merges them into an
unspecified render table:
XmRendition
XmRenderTable
Arg
Cardinal
Pixel
Pixel
new_renditions[2];
new_table;
argv[4];
argc = 0;
fg =...;
bg =...;
XtSetArg (argv[argc], XmNfontName,
"fixed");
argc++;
XtSetArg (argv[argc], XmNfontType,
XmFONT_IS_FONT);
argc++;
XtSetArg (argv[argc], XmNloadModel,
XmLOAD_DEFERRED);
argc++;
new_renditions[0] = XmRenditionCreate (widget,
XmFONTLIST_DEFAULT_TAG, argv, argc);
argc = 0;
XtSetArg (argv[argc], XmNrenditionBackground, bg); argc++;
XtSetArg (argv[argc], XmNrenditionForeground, fg); argc++;
new_renditions[1] = XmRenditionCreate (widget, "colors", argv, argc);
new_table = XmRenderTableAddRenditions (old_table, new_renditions, 2,
XmMERGE_REPLACE);)
Motif Reference Manual
287
XmRenderTableAddRenditions
Motif Functions and Macros
See Also
XmRenderTableCopy(1), XmRenderTableFree(1),
XmRenderTableGetRendition(1),
XmRenderTableGetRenditions(1), XmRenderTableGetTags(1),
XmRenderTableRemoveRenditions(1), XmRenditionCreate(1),
XmRenditionFree(1), XmRenditionRetrieve(1),
XmRenditionUpdate(1), XmRendition(2).
288
Motif Reference Manual
Motif Functions and Macros
XmRenderTableCopy
Name
XmRenderTableCopy – copy a render table.
Synopsis
XmRenderTable XmRenderTableCopy (XmRenderTable old_table, XmStringTag *tags, int tag_count)
Inputs
old_table
tags
copied.
tag_count
Specifies the table containing the renditions to be copied.
Specifies an array of tags. Renditions with matching tags are
Specifies the number of items within the tags array.
Returns
A new render table containing renditions with matching tags, or NULL.
Availability
Motif 2.0 and later.
Description
An XmRenderTable is an array of XmRendition objects, which are used to render
compound strings. XmRenderTableCopy() creates a newly allocated render
table by copying renditions from an existing table, old_table. An array of tags
can be supplied which acts as a filter: only those renditions from old_table which
have a matching XmNtag resource are copied. The number of items within any
tags array is specified through tag_count. If tags is NULL, all of the renditions
within old_table are copied. If old_table is NULL, the function returns NULL.
Usage
The function allocates storage for the returned render table, including storage for
each of the newly copied renditions. It is the responsibility of the programmer to
reclaim the memory at an appropriate point by calling XmRenderTableFree().
In Motif 2.0 and later, the XmRenderTable supersedes the XmFontList, which is
now considered obsolete. For backwards compatibility, the XmFontList opaque
type is implemented through the render table.
See Also
XmRenderTableAddRenditions(1), XmRenderTableFree(1),
XmRenderTableGetRendition(1),
XmRenderTableGetRenditions(1), XmRenderTableGetTags(1),
XmRenderTableRemoveRenditions(1), XmRenditionCreate(1),
XmRenditionFree(1), XmRenditionRetrieve(1),
XmRenditionUpdate(1), XmRendition(2).
Motif Reference Manual
289
XmRenderTableCvtFromProp
Motif Functions and Macros
Name
XmRenderTableCvtFromProp – convert from a string representation into a
render table.
Synopsis
XmRenderTable XmRenderTableCvtFromProp (Widget widget, char *property,
unsigned int length)
Inputs
widget
property
length
Specifies a destination widget in a data transfer.
Specifies the render table in string representation format.
Specifies the number of bytes in the property string.
Returns
The converted render table.
Availability
Motif 2.0 and later.
Description
XmRenderTableCvtFromProp() converts a string representation of a render
table into an XmRenderTable. The string representation to be converted is given
by property, and the size of the string in bytes is length.
Usage
Typically, the procedure is used within the destination callback of widget when it
is the target of a data transfer. The inverse function XmRenderTableCvtToProp() is called by the convert procedures of the source of the data transfer.
XmRenderTableCvtFromProp() returns allocated memory, and it is the
responsibility of the programmer to reclaim the space at a suitable point by calling XmRenderTableFree().
See Also
XmRenderTableCvtToProp(1), XmRenderTableFree(1),
XmRendition(2).
290
Motif Reference Manual
Motif Functions and Macros
XmRenderTableCvtToProp
Name
XmRenderTableCvtToProp – convert a render table into a string representation.
Synopsis
unsigned int XmRenderTableCvtToProp ( Widget
XmRenderTable
char
**property_return)
widget,
render_table,
Inputs
widget
render_table
Specifies a source widget for the render table.
Specifies the render table to convert.
Outputs
property_return
table.
Returns the string representation of the converted render
Returns
The number of bytes in the converted string representation.
Availability
Motif 2.0 and later.
Description
XmRenderTableCvtToProp() converts an XmRenderTable render_table
into a string representation at the address specified by property_return. The
length of the converted string is returned.
Usage
Typically, the procedure is used within the convert callback of widget when it is
the source of a data transfer. The procedure returns allocated memory within
property_return, and it is the responsibility of the programmer to reclaim the
space at a suitable point by calling XtFree().
The standard built-in conversion routines within the Uniform Transfer Model
internally call XmRenderTableCvtToProp() when asked to convert the
_MOTIF_RENDER_TABLE selection.
See Also
XmRenderTableCvtFromProp(1), XmRendition(2).
Motif Reference Manual
291
XmRenderTableFree
Motif Functions and Macros
Name
XmRenderTableFree – free the memory used by a render table.
Synopsis
void XmRenderTableFree (XmRenderTable table)
Inputs
table
Specifies the render table to free.
Availability
Motif 2.0 and later.
Description
XmRenderTableFree() is a convenience function which deallocates space
used by the render table table.
Usage
Render tables, and the renditions which they contain, are reference counted. It is
important to call XmRenderTableFree() on a render table rather than
XtFree() so that each rendition in the table is properly deallocated. Motif
caches and shares render tables and the renditions which they contain, and so an
improper XtFree() would not respect any sharing currently in place.
XmRenderTableFree() does not actually free the render table until the reference count is zero.
See Also
XmRenderTableAddRenditions(1), XmRenderTableCopy(1),
XmRenderTableRemoveRenditions(1), XmRenditionCreate(1),
XmRenditionFree(1), XmRendition(2).
292
Motif Reference Manual
Motif Functions and Macros
XmRenderTableGetRendition
Name
XmRenderTableGetRendition – search a render table for a matching rendition.
Synopsis
XmRendition XmRenderTableGetRendition (XmRenderTable table, XmStringTag tag)
Inputs
table
tag
Specifies the render table to search.
Specifies the tag with which to find a rendition.
Returns
A Rendition which matches tag, otherwise NULL.
Availability
Motif 2.0 and later.
Description
XmRenderTableGetRendition() is a convenience function which searches
table, and returns the rendition which matches tag.
Usage
XmRenderTableGetRendition() performs a linear search through the renditions contained within table, comparing the XmNtag resource value with the
search string given by tag. If no match is found, any XmNnoRenditionCallback1
callbacks registered with the XmDisplay object are invoked, supplying the table
as the render_table element of the XmDisplayCallbackStruct passed to the callbacks. If the callbacks modify the render_table element, the linear search is
restarted. A copy of any matching rendition is returned, otherwise NULL.
XmRenderTableGetRendition() allocates space for the returned rendition,
and it is the responsibility of the programmer to reclaim the space at a suitable
point by calling XmRenditionFree().
See Also
XmRenderTableAddRenditions(1),
XmRenderTableGetRenditions(1),
XmRenderTableRemoveRenditions(1), XmRenditionFree(1),
XmRendition(2).
1.Erroneously given as XmNnoRendition in 2nd edition.
Motif Reference Manual
293
XmRenderTableGetRenditions
Motif Functions and Macros
Name
XmRenderTableGetRenditions – search a render table for matching renditions.
Synopsis
XmRendition *XmRenderTableGetRenditions ( XmRenderTable
XmStringTag
Cardinal
Inputs
table
tags
required.
tag_count
table,
*tags,
tag_count)
Specifies the render table to search.
Specifies an array of tags for which matching renditions are
Specifies the number of items in tags.
Returns
The array of renditions which have matching tags.
Availability
Motif 2.0 and later.
Description
XmRenderTableGetRenditions() searches table for all renditions which
have a tag that matches an entry within the list tags. If the table is NULL, or if
tags is NULL, or if tag_count is zero, the function returns NULL. Otherwise,
the function returns an allocated array of matching rendition objects.
Usage
XmRenderTableGetRenditions() iterates through a set of tags, comparing in turn each tag with the group of renditions contained within a render table.
If no match is found when comparing a tag, any XmNnoRenditionCallback1 callbacks registered with the XmDisplay object are invoked, supplying the table as
the render_table element of the XmDisplayCallbackStruct passed to the callbacks. If the callbacks modify the render_table element, the linear search is
restarted for that tag.
The documentation states that the function returns an allocated array, renditions
being copied into the array at the same index of the matching tag within the tags
array. For example, if the third tag in tags matches a rendition, that rendition is
copied into the third element of the returned array. If any tag in the tags list does
not match any rendition in the table, that slot in the returned array is set to NULL.
The sources, however, do not match the documentation: renditions are copied
into the array in the order which they are matched, ignoring any slots which do
1.Erroneously given as XmNnoRendition in 2nd edition.
294
Motif Reference Manual
Motif Functions and Macros
XmRenderTableGetRenditions
not match. Thus if the first tag in tags results in a NULL match, any rendition
found from the second tag is placed into the first slot. If the number of matched
renditions is less than the number of supplied tags, then memory for the returned
array is reallocated to match the number of found renditions. In the absence of a
XmNnoRenditionCallback callback, it is not possible to deduce the size of the
returned rendition array.
The function allocates space for both the returned rendition array and the constituent renditions, and it is the responsibility of the programmer to reclaim the
space at a suitable point by calling XmRenditionFree() on each of the elements in the returned array, and subsequently XtFree() on the array itself.
Example
The following specimen code illustrates the basic outline of a call to
XmRenderTableGetRenditions():
XmRendition
XmStringTag
int
*match_renditions;
tags[MAX_TAGS];
i;
tags[0] = XmFONTLIST_DEFAULT_TAG;
tags[1] = XmS; /* "" */
...
/* search an unspecified render table */
match_renditions = XmRenderTableGetRenditions (render_table, tags,
MAX_TAGS);
/* use the matched set of renditions */
...
/* free the returned space */
if (match_renditions != NULL) {
/* ASSUMPTION: XtNumber (match_renditions) == MAX_TAGS */
/* Not a valid assumption if a tag does not match */
for (i = 0; i < MAX_TAGS; i++) {
XmRenditionFree (match_renditions[i]);
}
XtFree (match_renditions);
}
See Also
XmRenderTableAddRenditions(1), XmRenderTableGetRendition(1),
XmRenderTableRemoveRenditions(1), XmRenditionFree(1),
XmRendition(2).
Motif Reference Manual
295
XmRenderTableGetTags
Motif Functions and Macros
Name
XmRenderTableGetTags – fetch the list of rendition tags from a render table.
Synopsis
int XmRenderTableGetTags (XmRenderTable table, XmStringTag **tag_list)
Inputs
table
Specifies the render table.
Outputs
tag_list
Returns the list of rendition tags.
Returns
The number of tags within the returned tag_list.
Availability
Motif 2.0 and later.
Description
XmRenderTableGetTags() is a convenience function which iterates through
a render table, collecting all the tags from the individual renditions within the
table, and returning them to the programmer. The number of tags placed at the
address tag_list by the function is returned.
Usage
XmRenderTableGetTags() allocates an array, and places in the array a copy
of the XmNtag resource for each rendition within the table. The array is returned
at the address specified by the tag_list parameter. If the table is NULL, tag_list is
initialized to NULL, and the function returns zero. It is the responsibility of the
programmer to reclaim the space by calling XtFree() on each of the items
within the allocated array, and then subsequently calling XtFree() on the array
itself.
Example
The following specimen code illustrates the basic outline of a call to
XmRenderTableGetTags():
XmStringTag *tags;
int
count, i;
/* fetch the tags from an unspecified render table */
count = XmRenderTableGetTags (render_table, &tags);
/* use the tags */
...
/* free the returned space */
296
Motif Reference Manual
Motif Functions and Macros
XmRenderTableGetTags
if (tags != (XmStringTag *) 0) {
for (i = 0; i < count; i++) {
XtFree (tags[i]);
}
XtFree (tags);
}
See Also
XmRenditionFree(1), XmRendition(2).
Motif Reference Manual
297
XmRenderTableRemoveRenditions
Motif Functions and Macros
Name
XmRenderTableRemoveRenditions – copy a render table, excluding specified
renditions.
Synopsis
XmRenderTable XmRenderTableRemoveRenditions (XmRenderTable
old_table,
XmStringTag
int
tag_count)
Inputs
old_table
tags
tag_count
*tags,
Specifies a render table.
Specifies an array of rendition tags. Any rendition which
matches an item in the array is not copied from old_table.
Specifies the number of items in the tags array.
Returns
A new render table with matching renditions removed.
Availability
Motif 2.0 and later.
Description
XmRenderTableRemoveRenditions() creates a new render table by copying from old_table only those renditions which do not have a tag matching items
within the array tags. If tags is NULL, or if tag_count is zero, or if no renditions
are removed, the function returns the old_table unmodified. Otherwise,
old_table is deallocated, and the reference counts for any excluded renditions are
decremented, before the function returns the newly allocated render table.
Usage
A rendition is not copied into the returned table if it has a XmNtag resource value
the same as any item within the tags list. When the returned render table differs
from the original old_table parameter, the function allocates space for the new
table, and it is the responsibility of the programmer to reclaim the space by calling XmRenderTableFree().
See Also
XmRenderTableAddRenditions(1), XmRenderTableFree(1),
XmRendition(2).
298
Motif Reference Manual
Motif Functions and Macros
XmRenditionCreate
Name
XmRenditionCreate – create a rendition object.
Synopsis
XmRendition XmRenditionCreate (Widget widget, XmStringTag tag, Arg
*arglist, Cardinal argcount)
Inputs
widget
tag
arglist
argcount
Specifies a widget.
Specifies a tag for the rendition object.
Specifies an argument list, consisting of resource name/value pairs.
Specifies the number of arguments in arglist.
Returns
The new rendition object.
Availability
Motif 2.0 and later.
Description
XmRenditionCreate() creates a new rendition object, which can be used as
an entry in a render table used for rendering XmStrings. widget is used to find a
connection to the X server and an application context. tag is used as the XmNtag
resource of the new rendition object. Resources for the new object are supplied in
the arglist array.
Usage
The implementation of XmRendition is through a pseudo widget: although not a
true widget, the object has resources and a resource style interface for setting and
fetching values of the rendition. Typically, a rendition is merged into an existing
render table through the function XmRenderTableAddRenditions(). Compound strings are rendered by successively matching tags within the compound
string with the XmNtag resources of renditions in the table, and then using the
resources of matched renditions to display the string components.
XmRenditionCreate() allocates storage for the returned rendition object. It
is the responsibility of the programmer to reclaim the storage at a suitable point
by calling XmRenditionFree(). Renditions are reference counted, and it is
important to call XmRenditionFree() rather than XtFree() in order to maintain the references.
Example
The following specimen code creates a pair of renditions and merges them into
an unspecified render table:
XmRendition
Motif Reference Manual
new_renditions[2];
299
XmRenditionCreate
XmRenderTable
Arg
Cardinal
Pixel
Pixel
Motif Functions and Macros
new_table;
argv[4];
argc = 0;
fg =...;
bg =...;
/* create a rendition with fonts specified */
argc = 0;
XtSetArg (argv[argc], XmNfontName,
"fixed");
argc++;
XtSetArg (argv[argc], XmNfontType,
XmFONT_IS_FONT);
argc++;
XtSetArg (argv[argc], XmNloadModel,
XmLOAD_DEFERRED);
argc++;
new_renditions[0] = XmRenditionCreate (widget,
XmFONTLIST_DEFAULT_TAG, argv, argc);
/* create a rendition with line style specified */
argc = 0;
XtSetArg (argv[argc], XmNrenditionBackground,
bg);
argc++;
XtSetArg (argv[argc], XmNrenditionForeground,
fg);
argc++;
XtSetArg (argv[argc], XmNunderlineType,
XmSINGLE_LINE);
argc++;
XtSetArg (argv[argc], XmNstrikethruType,
XmSINGLE_LINE);
argc++;
new_renditions[1] = XmRenditionCreate (widget, "lineStyle", argv, argc);
/* merge into an unspecified render table */
new_table = XmRenderTableAddRenditions (old_table, new_renditions, 2,
XmMERGE_REPLACE);
See Also
XmRenderTableAddRenditions(1), XmRenditionFree(1),
XmRenditionRetrieve(1), XmRenditionUpdate(1),
XmRendition(2).
300
Motif Reference Manual
Motif Functions and Macros
XmRenditionFree
Name
XmRenditionFree – free the memory used by a rendition.
Synopsis
void XmRenditionFree (XmRendition rendition)
Inputs
rendition
Specifies the rendition that is to be freed.
Availability
Motif 2.0 and later.
Description
XmRenditionFree() deallocates storage used by the specified rendition. The
routine does not free any XFontSet or XFontStruct data structures associated
with the rendition object.
Usage
XmRenditionFree() frees the storage used by the rendition object, but does
not free font data structures associated with the XmNfont resource of the object.
It is important to call XmRenditionFree() rather than XtFree() because
Motif reference counts rendition objects. XmRenditionFree() decrements the
reference count for the rendition; the rendition is not actually freed until the reference count reaches 0 (zero).
See Also
XmRenditionCreate(1), XmRendition(2).
Motif Reference Manual
301
XmRenditionRetrieve
Motif Functions and Macros
Name
XmRenditionRetrieve – fetch rendition object resources.
Synopsis
void XmRenditionRetrieve (XmRendition rendition, Arg *arg_list, Cardinal
arg_count)
Inputs
rendition
arg_count
Specifies the rendition whose resources are fetched.
Specifies the number of arguments in arg_list.
Outputs
arg_list
Specifies an argument list, consisting of resource name/value pairs.
Availability
Motif 2.0 and later.
Description
XmRenditionRetrieve() fetches selective resource values of a rendition
object. The set of resources retrieved is specified through the resource list
arg_list, each element of the list being a structure containing a name/value pair.
The number of elements within the list is given by arg_count.
Usage
XmRenditionRetrieve() directly returns the values of the rendition
resources, and not copies of them. The programmer should not inadvertently
modify a returned value, but should take a copy of any pointer-valued resource
which is to be changed. For example, the XmNtag and XmNfontName resources
should be copied into a separate address space before modifying or manipulating
the values.
If the XmNloadModel of the rendition object is XmLOAD_DEFERRED, and the
font specified by the XmNfont resource is NULL, but the XmNfontName value is
not NULL, and if the programmer has specified that the font is to be retrieved
within arg_list, then XmRenditionRetrieve() automatically changes the
load model to XmLOAD_IMMEDIATE and directly calls a procedure to load the
font indicated by XmNfontName before returning the requested resource values.
Example
The following specimen code illustrates fetching resources from an unspecified
rendition object:
Pixel
Pixel
XtPointer
String
302
bg;
fg;
font;
font_name;
Motif Reference Manual
Motif Functions and Macros
XmFontType
unsigned char
unsigned char
XmTabList
XmStringTag
unsigned char
Arg
Cardinal
XmRenditionRetrieve
font_type;
load_model;
strike_type;
tab_list;
tag;
ul_type;
av[10];
ac = 0;
XtSetArg (av[ac], XmNrenditionForeground,
XtSetArg (av[ac], XmNrenditionBackground,
XtSetArg (av[ac], XmNfont,
XtSetArg (av[ac], XmNfontName,
XtSetArg (av[ac], XmNfontType,
XtSetArg (av[ac], XmNloadModel,
XtSetArg (av[ac], XmNstrikethruType,
XtSetArg (av[ac], XmNtabList,
XtSetArg (av[ac], XmNtag,
XtSetArg (av[ac], XmNunderlineType,
&fg);
&bg);
&font);
&font_name);
&font_type);
&load_model);
&strike_type);
&tab_list);
&tag);
&ul_type);
ac++;
ac++;
ac++;
ac++;
ac++;
ac++;
ac++;
ac++;
ac++;
ac++;
XmRenditionRetrieve (rendition, av, ac);
See Also
XmRenditionCreate(1), XmRenditionFree(1),
XmRenditionUpdate(1), XmRendition(2).
Motif Reference Manual
303
XmRenditionRetrieve
Motif Functions and Macros
Name
XmRenditionUpdate – set rendition object resources.
Synopsis
void XmRenditionUpdate (XmRendition rendition, Arg *arg_list, Cardinal
arg_count)
Inputs
rendition
arg_list
arg_count
Specifies the rendition whose resources are to be changed.
Specifies an argument list, consisting of resource name/value pairs.
Specifies the number of arguments within arg_list.
Availability
Motif 2.0 and later.
Description
XmRenditionUpdate() is a convenience function which sets the resources for
a rendition object. The attributes to change are specified through an array of
name/value pairs, similar to the resource-style interface of XtSetValues().
Usage
Modifying the value of the XmNfontName resource initially resets the XmNfont
resource to NULL, irrespective of whether the load model for the new font is
XmLOAD_IMMEDIATE or XmLOAD_DEFERRED.
Example
The following specimen code illustrates setting resources for an unspecified rendition object:
Pixel
Pixel
Arg
Cardinal
bg =...;
fg =...;
av[10];
ac = 0;
XtSetArg (av[ac], XmNrenditionForeground,
ac++;
XtSetArg (av[ac], XmNrenditionBackground,
ac++;
XtSetArg (av[ac], XmNfontType,
ac++;
XtSetArg (av[ac], XmNfontName,
ac++;
XtSetArg (av[ac], XmNloadModel,
ac++;
304
fg);
bg);
XmFONT_IS_FONT);
"fixed");
XmLOAD_DEFERRED);
Motif Reference Manual
Motif Functions and Macros
XtSetArg (av[ac], XmNstrikethruType,
ac++;
XtSetArg (av[ac], XmNunderlineType,
ac++;
XmRenditionRetrieve
XmSINGLE_LINE);
XmSINGLE_LINE);
XmRenditionUpdate (rendition, av, ac);
See Also
XmRenditionCreate(1), XmRenditionFree(1),
XmRenditionRetrieve(1), XmRendition(2).
Motif Reference Manual
305
XmRepTypeAddReverse
Motif Functions and Macros
Name
XmRepTypeAddReverse – install the reverse converter for a representation type.
Synopsis
#include <Xm/RepType.h>
void XmRepTypeAddReverse (XmRepTypeId rep_type_id)
Inputs
rep_type_id
Specifies the ID number of the representation type.
Availability
Motif 1.2 and later.
Description
XmRepTypeAddReverse() installs a reverse converter for a previously registered representation type. The reverse converter converts numerical representation type values to string values. The rep_type_id argument specifies the ID
number of the representation type. If the representation type contains duplicate
values, the reverse converter uses the first name in the value_names list that
matches the specified numeric value.
Usage
In Motif 1.2 and later, the representation type manager provides support for handling many of the tasks related to enumerated values. This facility installs
resource converters that convert a string value to its numerical representation.
The representation type manager can also be queried to get information about the
registered types. This facility is especially useful for interface builders and applications like editres that allow a user to set resources interactively. XmRepTypeAddReverse() provides a way for an application to install a converter
that converts numeric values to their string values.
See Also
XmRepTypeGetId(1), XmRepTypeRegister(1).
306
Motif Reference Manual
Motif Functions and Macros
XmRepTypeGetId
Name
XmRepTypeGetId – get the ID number of a representation type.
Synopsis
#include <Xm/RepType.h>
XmRepTypeId XmRepTypeGetId (String rep_type)
Inputs
rep_type
Specifies the string name of a representation type.
Returns
The ID number of the representation type or XmREP_TYPE_INVALID if the
representation type is not registered.
Availability
Motif 1.2 and later.
Description
XmRepTypeGetId() retrieves the ID number of the specified representation
type rep_type from the representation type manager. The rep_type string is the
string name of a representation type that has been registered with XmRepTypeRegister(). XmRepTypeGetId() returns the ID number if the representation type has been registered. This value is used in other representation type
manager routines to identify a particular type. Otherwise, the routine returns
XmREP_TYPE_INVALID.
Usage
In Motif 1.2 and later, the representation type manager provides support for handling many of the tasks related to enumerated values. This facility installs
resource converters that convert a string value to its numerical representation.
The representation type manager can also be queried to get information about the
registered types. This facility is especially useful for interface builders and applications like editres that allow a user to set resources interactively. XmRepTypeGetId() provides a way for an application get the ID of a representation
type, which can be used to identify the type to other representation manager routine.
See Also
XmRepTypeGetNameList(1), XmRepTypeGetRecord(1),
XmRepTypeGetRegistered(1), XmRepTypeRegister(1).
Motif Reference Manual
307
XmRepTypeGetNameList
Motif Functions and Macros
Name
XmRepTypeGetNameList – get the list of value names for a representation type.
Synopsis
#include <Xm/RepType.h>
String * XmRepTypeGetNameList (XmRepTypeId rep_type_id, Boolean
use_uppercase_format)
Inputs
rep_type_id
Specifies the ID number of the representation type.
use_uppercase_format Specifies whether or not the names are in uppercase characters.
Returns
A pointer to an array of value names.
Availability
Motif 1.2 and later.
Description
XmRepTypeGetNameList() retrieves the list of value names associated with
the specified rep_type_id. The routine returns a pointer to a NULL-terminated
list of value names for the representation type, where each value name is a
NULL-terminated string. If use_uppercase_format is True, the value names are
in uppercase characters with Xm prefixes. Otherwise, the value names are in lowercase characters without Xm prefixes. XmRepTypeGetNameList() allocates
storage for the returned data. The application is responsible for freeing the storage using XtFree() on each of the elements in the returned array, and subsequently upon the array pointer itself.
Usage
In Motif 1.2 and later, the representation type manager provides support for handling many of the tasks related to enumerated values. This facility installs
resource converters that convert a string value to its numerical representation.
The representation type manager can also be queried to get information about the
registered types. This facility is especially useful for interface builders and applications like editres that allow a user to set resources interactively. XmRepTypeGetNameList() provides a way for an application to get the named
values for a particular representation type.
See Also
XmRepTypeGetId(1), XmRepTypeGetRecord(1),
XmRepTypeGetRegistered(1), XmRepTypeRegister(1).
308
Motif Reference Manual
Motif Functions and Macros
XmRepTypeGetRecord
Name
XmRepTypeGetRecord – get information about a representation type.
Synopsis
#include <Xm/RepType.h>
XmRepTypeEntry XmRepTypeGetRecord (XmRepTypeId rep_type_id)
Inputs
rep_type_id
Specifies the ID number of the representation type.
Returns
A pointer to a representation type entry structure.
Availability
Motif 1.2 and later.
Description
XmRepTypeGetRecord() retrieves information about the representation type
specified by rep_type_id. The routine returns a XmRepTypeEntry, which is a
pointer to a representation type entry structure. This structure contains information about the value names and values for the enumerated type. XmRepTypeGetRecord() allocates storage for the returned data. The application is
responsible for freeing the storage using XtFree().
Usage
In Motif 1.2 and later, the representation type manager provides support for handling many of the tasks related to enumerated values. This facility installs
resource converters that convert a string value to its numerical representation.
The representation type manager can also be queried to get information about the
registered types. This facility is especially useful for interface builders and applications like editres that allow a user to set resources interactively. XmRepTypeGetRecord() provides a way for an application to retrieve information
about a particular representation type.
Structures
The XmRepTypeEntry is defined as follows:
typedef struct {
String
String
unsigned char
unsigned char
Boolean
XmRepTypeId
Motif Reference Manual
rep_type_name;
*value_names;
*values;
num_values;
reverse_installed;
rep_type_id;
/* name of representation type */
/* array of value names
*/
/* array of numeric values
*/
/* number of values
*/
/* reverse converter installed flag */
/* representation type ID
*/
309
XmRepTypeGetRecord
Motif Functions and Macros
} XmRepTypeEntryRec, *XmRepTypeEntry, XmRepTypeListRec, *XmRepTypeList;
See Also
XmRepTypeGetId(1), XmRepTypeGetNameList(1),
XmRepTypeGetRegistered(1), XmRepTypeRegister(1).
310
Motif Reference Manual
Motif Functions and Macros
XmRepTypeGetRegistered
Name
XmRepTypeGetRegistered – get the registered representation types.
Synopsis
#include <Xm/RepType.h>
XmRepTypeList XmRepTypeGetRegistered (void)
Returns
A pointer to the registration list of representation types.
Availability
Motif 1.2 and later.
Description
XmRepTypeGetRegistered() retrieves the whole registration list for the
representation type manager. The routine returns a copy of the registration list,
which contains information about all of the registered representation types. The
registration list is an array of XmRepTypeList structures, where each structure
contains information about the value names and values for a single representation
type. The end of the registration list is indicated by a NULL pointer in the
rep_type_name field. XmRepTypeGetRegistered allocates storage for the
returned data. The application is responsible for freeing this storage using
XtFree(). The list of value names (the value of the value_names field), the list
of values (the value of the values field), and the array of structures all need to be
freed.
Usage
In Motif 1.2 and later, the representation type manager provides support for handling many of the tasks related to enumerated values. This facility installs
resource converters that convert a string value to its numerical representation.
The representation type manager can also be queried to get information about the
registered types. This facility is especially useful for interface builders and applications like editres that allow a user to set resources interactively. XmRepTypeGetRegistered() provides a way for an application to get information
about all of the registered representation types.
Example
The following code fragment shows the use of XmRepTypeGetRegistered() to print the value names and values of all of the registered representation types:
XmRepTypeList replist; int i;
replist = XmRepTypeGetRegistered();
Motif Reference Manual
311
XmRepTypeGetRegistered
Motif Functions and Macros
while (replist->rep_type_name != NULL) {
printf ("Representation type name: %s\n", replist->rep_type_name);
printf ("Value names and associated values: \n");
for (i = 0; i < replist->num_values; i++) {
printf ("%s: ", replist->value_names[i]);
printf ("%d\n", replist->values[i]);
}
replist++;
XtFree ((char *)replist->values);
XtFree ((char *)replist->value_names);
}
XtFree ((char *)replist);
Structures
The XmRepTypeList is defined as follows:
typedef struct {
String
rep_type_name;
/* name of representation type
*/
String
*value_names;
/* array of value names
*/
unsigned char
*values;
/* array of numeric values
*/
unsigned char
num_values;
/* number of values
*/
Boolean
reverse_installed;
/* reverse converter installed flag
*/
XmRepTypeId
rep_type_id;
/* representation type ID
*/
} XmRepTypeEntryRec, *XmRepTypeEntry, XmRepTypeListRec, *XmRepTypeList;
See Also
XmRepTypeGetRecord(1), XmRepTypeGetNameList(1),
XmRepTypeRegister(1).
312
Motif Reference Manual
Motif Functions and Macros
XmRepTypeInstallTearOffModelConverter
Name
XmRepTypeInstallTearOffModelConverter – install the resource converter for
the RowColumn XmNtearOffModel resource.
Synopsis
#include <Xm/RepType.h>
void XmRepTypeInstallTearOffModelConverter (void)
Availability
Motif 1.2 and later. In Motif 2.0 and later, the converter for the XmNtearOffModel resource is internally installed, and this function is obsolete.
Description
XmRepTypeInstallTearOffModelConverter() installs the resource
converter for the RowColumn XmNtearOffModel resource. This resource controls whether or not PulldownMenus and PopupMenus in an application can be
torn off. Once the converter is installed, the value of XmNtearOffModel can be
specified in a resource file.
Usage
In Motif 1.2, a RowColumn that is configured as a PopupMenu or a PulldownMenu supports tear-off menus. When a menu is torn off, it remains on the screen
after a selection is made so that additional selections can be made. A menu pane
that can be torn off contains a tear-off button at the top of the menu. The
XmNtearOffModel resource controls whether or not tear-off functionality is
available for a menu. This resource can take the values
XmTEAR_OFF_ENABLED or XmTEAR_OFF_DISABLED.
In Motif 1.2, the resource converter for XmNtearOffModel is not installed by
default. Some existing applications depend on receiving a callback when a menu
is mapped; since torn-off menus are always mapped, these applications might fail
if a user is allowed to enable tear-off menus from a resource file. XmRepTypeInstallTearOffModelConverter() registers the converter that allows
the resource to be set from a resource file.
See Also
XmRowColumn(2).
Motif Reference Manual
313
XmRepTypeRegister
Motif Functions and Macros
Name
XmRepTypeRegister – register a representation type resource.
Synopsis
#include <Xm/RepType.h>
XmRepTypeId XmRepTypeRegister (
Inputs
rep_type
value_names
num_values
String
String
unsigned char
unsigned char
rep_type,
*value_names,
*values,
num_values)
Specifies the string name for the representation type.
Specifies an array of value names for the representation type.
IP values 1i Specifies an array of values for the representation type.
Specifies the number of items in value_names and values.
Returns
The ID number of the representation type.
Availability
Motif 1.2 and later.
Description
XmRepTypeRegister() registers a representation type with the representation
type manager. The representation type manager provides resource conversion
facilities for enumerated values. XmRepTypeRegister() installs a resource
converter that converts string values to numerical representation type values. The
strings in the value_names array specify the value names for the representation
type. The strings are specified in lowercase characters, with underscore characters separating words and without Xm prefixes.
If the values argument is NULL, the order of the strings in the value_names array
determines the numerical values for the enumerated type. In this case, the names
are assigned consecutive values starting with 0 (zero). If values is non-NULL, it
is used to assign values to the names. Each name in the value_names array is
assigned the corresponding value in the values array, so it is possible to have nonconsecutive values or duplicate names for the same value.
XmRepTypeRegister() returns the ID number that is assigned to the representation type. This value is used in other representation type manager routines to
identify a particular type. A representation type can only be registered once. If a
type is registered more than once, the behavior of the representation type manager is undefined.
314
Motif Reference Manual
Motif Functions and Macros
XmRepTypeRegister
Usage
In Motif 1.2 and later, the representation type manager provides support for handling many of the tasks related to enumerated values. This facility installs
resource converters that convert a string value to its numerical representation.
The representation type manager can also be queried to get information about the
registered types. This facility is especially useful for interface builders and applications like editres that allow a user to set resources interactively. XmRepTypeRegister() provides a way for an application to register representation
types for application-specific resources or for new widget classes.
See Also
XmRepTypeAddReverse(1), XmRepTypeGetId(1),
XmRepTypeGetNameList(1), XmRepTypeGetRecord(1),
XmRepTypeGetRegistered(1), XmRepTypeValidValue(1).
Motif Reference Manual
315
XmRepTypeValidValue
Motif Functions and Macros
Name
XmRepTypeValidValue – determine the validity of a numerical value for a representation type.
Synopsis
#include <Xm/RepType.h>
Boolean XmRepTypeValidValue ( XmRepTypeId
unsigned char
Widget
Inputs
rep_type_id
test_value
enable_default_warning
warning message.
rep_type_id,
test_value,
enable_default_warning)
Specifies the ID number of the representation type.
Specifies the value that is to be tested.
Specifies a widget that is used to generate a default
Returns
True if the specified value is valid or False otherwise.
Availability
Motif 1.2 and later.
Description
XmRepTypeValidValue() checks the validity of the specified test_value for
the representation type specified by rep_type_id. The routine returns True if the
value is valid. Otherwise, it returns False. If the enable_default_warning parameter is non-NULL, XmRepTypeValidValue() uses the specified widget to generate a default warning message if the value is invalid. If enable_default_warning
is NULL, no default warning message is provided.
Usage
In Motif 1.2 and later, the representation type manager provides support for handling many of the tasks related to enumerated values. This facility installs
resource converters that convert a string value to its numerical representation.
The representation type manager can also be queried to get information about the
registered types. This facility is especially useful for interface builders and applications like editres that allow a user to set resources interactively. XmRepTypeValidValue() provides a way for an application to check if a value is valid for
a particular representation type.
See Also
XmRepTypeGetId(1), XmRepTypeRegister(1).
316
Motif Reference Manual
Motif Functions and Macros
XmResolveAllPartOffsets
Name
XmResolveAllPartOffsets – ensure upward-compatible widgets and applications.
Synopsis
void XmResolveAllPartOffsets (
WidgetClass
XmOffsetPtr
XmOffsetPtr
widget_class,
*offset,
*constraint_offset)
Inputs
widget_class
Specifies the widget class pointer.
Outputs
offset
constraint_offset
Returns the widget offset record.
Returns the constraint offset record.
Description
XmResolveAllPartOffsets() ensures that an application or a widget will
be upwardly compatible with the records in a widget structure. In other words, if
the size of a widget structure changes in the future, this routine can be used to
calculate the locations of the new offsets. This routine and XmResolvePartOffsets() are similar. During the creation of a widget, both routines modify the
widget structure by allocating an array of offset values. XmResolvePartOffsets()
affects only the widget instance record, while XmResolveAllPartOffsets() affects the widget instance and constraint records.
Usage
If you are subclassing a Motif widget, you should use XmResolveAllPartOffsets() and XmResolvePartOffsets() to ensure that your widget will
be compatible with future releases of the toolkit.
See Also
XmResolvePartOffsets(1).
Motif Reference Manual
317
XmResolvePartOffsets
Motif Functions and Macros
Name
XmResolvePartOffsets – ensure upward-compatible widgets and applications.
Synopsis
void XmResolvePartOffsets (WidgetClass widget_class, XmOffsetPtr *offset)
Inputs
widget_class
Specifies the widget class pointer.
Outputs
offset
Returns the widget offset record.
Description
XmResolvePartOffsets() ensures that an application or a widget will be
upwardly compatible with the records in a widget structure. In other words, if the
size of a widget structure changes in the future, this routine can be used to calculate the locations of the new offsets. This routine and XmResolveAllPartOffsets() are similar. During the creation of a widget, both routines modify the
widget structure by allocating an array of offset values. XmResolvePartOffsets() affects only the widget instance record, while XmResolveAllPartOffsets() affects the widget instance and constraint records.
Usage
If you are subclassing a Motif widget, you should use XmResolvePartOffsets() and XmResolveAllPartOffsets() to ensure that your widget will
be compatible with future releases of the toolkit.
See Also
XmResolveAllPartOffsets(1).
318
Motif Reference Manual
Motif Functions and Macros
XmScaleGetValue
Name
XmScaleGetValue – get the slider value for a Scale widget.
Synopsis
#include <Xm/Scale.h>
void XmScaleGetValue (Widget widget, int *value_return)
Inputs
widget
Specifies the Scale widget.
Outputs
value_return
Returns the current slider position for the Scale.
Description
XmScaleGetValue() returns the current position of the slider within the specified Scale widget.
Usage
XmScaleGetValue() is a convenience routine that returns the value of the
XmNvalue resource for the Scale widget. Calling the routine is equivalent to calling XtGetValues() for that resource, although XmScaleGetValue()
accesses the value through the widget instance structure rather than through
XtGetValues().
See Also
XmScaleSetValue(1), XmScale(2).
Motif Reference Manual
319
XmScaleSetTicks
Motif Functions and Macros
Name
XmScaleSetTicks – set tick marks for a Scale widget.
Synopsis
#include <Xm/Scale.h>
void XmScaleSetTicks ( Widget
int
Cardinal
Cardinal
Dimension
Dimension
Dimension
widget,
big_every,
num_med,
num_small,
size_big,
size_med,
size_small)
Inputs
widget
Specifies a scale widget.
big_every
Specifies the number of scale values between large ticks.
num_med
Specifies the number of medium-sized ticks between the large
tick marks.
num_small
Specifies the number of small-sized ticks between the
medium-sized tick marks.
size_big
Specifies the size of the large ticks.
size_med
Specifies the size of the medium ticks.
size_small
Specifies the size of the small ticks.
Availability
Motif 2.0 and later.
Description
XmScaleSetTicks() places tick marks along the edges of a Scale widget. Ticks
may be of three types: big, medium, and small, and the size (in pixels) of each
type is specified by size_big, size_med, and size_small respectively. The location
of each big tick is given by big_every, which simply specifies the number of scale
values between each big tick. The number of medium-sized ticks between each
big tick is given by num_med, and the number of small-sized ticks between each
medium-sized tick is num_small.
Usage
XmScaleSetTicks() is a convenience function which places tick marks along the
edge of a Scale by creating a series of SeparatorGadget children at evenly spaced
intervals. If size_big is zero, XmScaleSetTicks() simply returns. If size_med or
size_small is zero, num_med and num_small are forced to zero respectively. The
number of medium and small tick marks required may be zero, but the number of
large tick marks must not be less than 2.
320
Motif Reference Manual
Motif Functions and Macros
XmScaleSetTicks
SeparatorGadgets are created with the names "BigTic", "MedTic", and "SmallTic", the XmNseparatorType resource of each is forced to XmSINGLE_LINE.
XmScaleSetTicks() does not delete any existing ticks when invoked on any particular Scale, neither does the Scale recalculate proper positions for the tick
marks if the scale orientation is changed after tick marks are added. In each case,
existing tick marks must be erased and subsequently redrawn or re-specified.
Example
The following code ensures that any tick marks are erased before adding new
ticks to a Scale:
#include <Xm/Scale.h>
#include <Xm/SeparatoG.h>
void ScaleEraseSetTicks ( Widget
scale,
int
big_every,
Cardinal
num_med,
Cardinal
num_small,
Dimension size_big,
Dimension size_med,
Dimension size_med)
{
WidgetList
children = (WidgetList) 0;
Cardinal
num_children = (Cardinal) 0;
int
i;
String
name;
/* fetch scale children. */
XtVaGetValues (scale, XmNchildren, &children, XmNnumChildren,
&num_children, 0)
/* destroy old ticks.
*/
/* some optimization to reuse correctly */
/* placed ticks might be in order here... */
for (i = 0; i < num_children; i++) {
if (XmIsSeparatorGadget (children[i])) {
if ((name = XtName (children[i])) != (String) 0) {
if ((strcmp (name, "BigTic") == 0) ||
(strcmp (name, "MedTic") == 0) ||
(strcmp (name, "SmallTic") == 0)) {
XtDestroyWidget (children[i]);}
}
}
}
Motif Reference Manual
321
XmScaleSetTicks
Motif Functions and Macros
/* create new ticks. */
XmScaleSetTicks (scale, big_every, num_med, num_small, size_big,
size_med, size_small);
}
See Also
XmScaleSetValues(1). XmScale(2), XmSeparatorGadget(2).
322
Motif Reference Manual
Motif Functions and Macros
XmScaleSetValue
Name
XmScaleSetValue – set the slider value for a Scale widget.
Synopsis
#include <Xm/Scale.h>
void XmScaleSetValue (Widget widget, int value)
Inputs
widget
value
Specifies the Scale widget.
Specifies the value of the slider.
Description
XmScaleSetValue() sets the current position of the slider to value in the
specified Scale widget. The value must be in the range XmNminimum to XmNmaximum.
Usage
XmScaleSetValue() is a convenience routine that sets the value of the XmNvalue resource for the Scale widget. Calling the routine is equivalent to calling
XtSetValues() for that resource, although XmScaleSetValue() accesses
the value through the widget instance structure rather than through XtSetValues().
See Also
XmScaleGetValue(1), XmScale(2).
Motif Reference Manual
323
XmScrollBarGetValues
Motif Functions and Macros
Name
XmScrollBarGetValues – get information about the current state of a ScrollBar
widget.
Synopsis
#include <Xm/ScrollBar.h>
void XmScrollBarGetValues ( Widget
int
int
int
int
widget,
*value_return,
*slider_size_return,
*increment_return,
*page_increment_return)
Inputs
widget
Specifies the ScrollBar widget.
Outputs
value_return
slider_size_return
increment_return
page_increment_return
level.
Returns the current slider position.
Returns the current size of the slider.
Returns the current increment and decrement level.
Returns the current page increment and decrement
Description
XmScrollBarGetValues() returns the current state information for the specified ScrollBar widget. This information consists of the position and size of the
slider, as well as the increment and page increment values.
Usage
XmScrollBarGetValues() is a convenience routine that returns the values
of the XmNvalue, XmNsliderSize, XmNincrement, and XmNpageIncrement
resources for the ScrollBar widget. Calling the routine is equivalent to calling
XtGetValues() for those resources, although XmScrollBarGetValues()
accesses the values through the widget instance structure rather than through
XtGetValues().
See Also
XmScrollBarSetValues(1), XmScrollBar(2).
324
Motif Reference Manual
Motif Functions and Macros
XmScrollBarSetValues
Name
XmScrollBarSetValues – set the current state of a ScrollBar widget.
Synopsis
#include <Xm/ScrollBar.h>
void XmScrollBarSetValues ( Widget
int
int
int
int
Boolean
Inputs
widget
value
slider_size
increment
page_increment
notify
invoked.
widget,
value,
slider_size,
increment,
page_increment,
notify)
Specifies the ScrollBar widget.
Specifies the slider position.
Specifies the size of the slider.
Specifies the increment and decrement level.
Specifies the page increment and decrement level.
Specifies whether or not the value changed callback is
Description
XmScrollBarSetValues() sets the current state of the specified ScrollBar
widget. The position of the slider is set to value, which must be in the range
XmNminimum to XmNmaximum minus XmNsliderSize. The size of the slider is
set to slider_size, which must be between 1 and the size of the scroll region. The
increment and page increment values are set to increment and page_increment,
respectively.
If notify is True, XmScrollBarSetValues() invokes the XmNvalueChangedCallback for the ScrollBar when the state is set.
Usage
XmScrollBarSetValues() is a convenience routine that sets the values of
the XmNvalue, XmNsliderSize, XmNincrement, and XmNpageIncrement
resources for the ScrollBar widget. Calling the routine is equivalent to calling
XtSetValues() for those resources, although XmScrollBarSetValues()
accesses the values through the widget instance structure rather than through
XtSetValues().
The notify parameter indicates whether or not the value changed callbacks for the
ScrollBar are invoked. You can avoid redundant code by setting this parameter to
True. If you are calling XmScrollBarSetValues() from a value changed
Motif Reference Manual
325
XmScrollBarSetValues
Motif Functions and Macros
callback routine, you probably want to set the parameter to False to avoid the
possibility of an infinite loop. Calling XmScrollBarSetValues() with notify
set to True causes the callback routines to be invoked in a way that is indistinguishable from a user-initiated adjustment to the ScrollBar.
See Also
XmScrollBarGetValues(1), XmScrollBar(2).
326
Motif Reference Manual
Motif Functions and Macros
XmScrolledWindowSetAreas
Name
XmScrolledWindowSetAreas – specify the children for a scrolled window.
Synopsis
#include <Xm/ScrolledW.h>
void XmScrolledWindowSetAreas (Widget
Widget
Widget
Widget
Inputs
widget
horizontal_scrollbar
vertical_scrollbar
work_region
widget,
horizontal_scrollbar,
vertical_scrollbar,
work_region)
Specifies the ScrolledWindow widget.
Specifies the widget ID of the horizontal ScrollBar.
Specifies the widget ID of the vertical ScrollBar.
Specifies the widget ID of the work window.
Availability
In Motif 2.0 and later, XmScrolledWindowSetAreas() is obsolete.
Description
XmScrolledWindowSetAreas() sets up the standard regions of a ScrolledWindow widget for an application. The ScrolledWindow must be created before
the routine is called. XmScrolledWindowSetAreas() specifies the horizontal and vertical ScrollBars and the work window region. If a particular ScrolledWindow does not have one of these regions, the corresponding argument can be
specified as NULL.
Usage
Each of the ScrolledWindow regions is associated with a ScrolledWindow
resource; XmScrolledWindowSetAreas() sets the associated resources.
The resources that correspond to the last three arguments to the routine are XmNhorizontalScrollBar, XmNverticalScrollBar, and XmNworkWindow, respectively.
If an application does not call XmScrolledWindowSetAreas(), the widget
may still set some of the standard regions. If ScrollBars are added as children,
the XmNhorizontalScrollBar and XmNverticalScrollBar resources may be set if
they have not already been specified. Any child that is not a ScrollBar is used for
the XmNworkWindow. If you want to be certain about which widgets are used
for the different regions, it is wise to call XmScrolledWindowSetAreas()
explicitly.
In Motif 2.0 and later, the function is obsolete, and the programmer should specify the XmNhorizontalScrollBar, XmNverticalScrollBar, and XmNworkWindow
Motif Reference Manual
327
XmScrolledWindowSetAreas
Motif Functions and Macros
resources directly through a call to XtSetValues(). Although ostensibly maintained for backwards compatibility, the implementation of XmScrolledWindowSetAreas() in Motif 2.0 and later is not Motif 1.2 compatible. In Motif
1.2, supplying a NULL value for any of the scrollbar or work window parameters
directly sets the internal component to NULL. In Motif 2.0 and later, supplying a
NULL value causes that parameter to be ignored, leaving the internal component
intact.
Example
The following code fragment shows how to set the regions of a ScrolledWindow:
Widget
int
toplevel, scrolled_w, drawing_a, vsb, hsb;
view_width, view_height;
scrolled_w = XtVaCreateManagedWidget ("scrolled_w", xmScrolledWindowWidgetClass, toplevel,
XmNscrollingPolicy,
XmAPPLICATION_DEFINED,
XmNvisualPolicy, XmVARIABLE,
NULL);
drawing_a = XtVaCreateManagedWidget ("drawing_a", xmDrawingAreaWidgetClass, scrolled_w,
XmNwidth, view_width,
XmNheight, view_height,
NULL);
vsb = XtVaCreateManagedWidget ("vsb", xmScrollBarWidgetClass, scrolled_w,
XmNorientation, XmVERTICAL,
NULL);
hsb = XtVaCreateManagedWidget ("hsb", xmScrollBarWidgetClass, scrolled_w,
XmNorientation, XmHORIZONTAL,
NULL);
XmScrolledWindowSetAreas (scrolled_w, hsb, vsb, drawing_a);
See Also
XmScrolledWindow(2).
328
Motif Reference Manual
Motif Functions and Macros
XmScrollVisible
Name
XmScrollVisible – make an obscured child of a ScrolledWindow visible.
Synopsis
#include <Xm/ScrolledW.h>
void XmScrollVisible ( Widget
Widget
Dimension
Dimension
Inputs
scrollw_widget
widget
left_right_margin
top_bottom_margin
scrollw_widget,
widget,
left_right_margin,
top_bottom_margin)
Specifies the ScrolledWindow widget.
Specifies the widget ID of the widget that is to be made
visible.
Specifies the distance between the widget and the left or
right edge of the viewport if the ScrolledWindow is
scrolled horizontally.
Specifies the distance between the widget and the top or
bottom edge of the viewport if the ScrolledWindow is
scrolled vertically.
Availability
Motif 1.2 and later.
Description
XmScrollVisible() scrolls the specified ScrolledWindow scrollw_widget so
that the obscured or partially obscured widget becomes visible in the work area
viewport. widget must be a descendent of scrollw_widget. The routine repositions
the work area of the ScrolledWindow and sets the margins between the widget
and the viewport boundaries based on left_right_margin and top_bottom_margin
if necessary.
Usage
XmScrollVisible() provides a way for an application to ensure that a particular child of a ScrolledWindow is visible. In order for the routine to work, the
XmNscrollingPolicy of the ScrolledWindow widget must be set to XmAUTOMATIC. This routine is designed to be used in the XmNtraverseObscureCallback
for a ScrolledWindow.
See Also
XmScrolledWindow(2).
Motif Reference Manual
329
XmSelectionBoxGetChild
Motif Functions and Macros
Name
XmSelectionBoxGetChild – get the specified child of a SelectionBox widget.
Synopsis
#include <Xm/SelectioB.h>
Widget XmSelectionBoxGetChild (Widget widget, unsigned char child)
Inputs
widget
Specifies the SelectionBox widget.
child
Specifies the child of the SelectionBox widget. Pass one of the values from the list below.
Returns
The widget ID of the specified child of the SelectionBox.
Availability
As of Motif 2.0, the toolkit abstract child fetch routines are marked for deprecation. You should give preference to XtNameToWidget(), except when fetching
the SelectionBox default button or work area.
Description
XmSelectionBoxGetChild() returns the widget ID of the specified child of
the SelectionBox widget.
Usage
XmDIALOG_APPLY_BUTTON, XmDIALOG_CANCEL_BUTTON,
XmDIALOG_HELP_BUTTON, and XmDIALOG_OK_BUTTON specify the
action buttons in the widget. XmDIALOG_DEFAULT_BUTTON specifies the
current default button. XmDIALOG_LIST and XmDIALOG_LIST_LABEL
specify the list and its label. XmDIALOG_TEXT and
XmDIALOG_SELECTION_LABEL specify the selection text entry area and its
label. XmDIALOG_SEPARATOR specifies the separator and
XmDIALOG_WORK_AREA specifies any work area child that has been added
to the SelectionBox. For more information on the different children of the SelectionBox, see the manual page in Section 2, Motif and Xt Widget Classes.
Widget Hierarchy
As of Motif 2.0, most Motif composite child fetch routines are marked as deprecated. However, since it is not possible to fetch the
XmDIALOG_DEFAULT_BUTTON or XmDIALOG_WORK_AREA children
using a public interface except through XmSelectionBoxGetChild(), the routine
should not be considered truly deprecated. For consistency with the preferred
new style, when fetching all other child values, consider giving preference to the
330
Motif Reference Manual
Motif Functions and Macros
XmSelectionBoxGetChild
Intrinsics routine XtNameToWidget(), passing one of the following names as the
second parameter:
“Apply”
“Cancel”
“OK”
“Separator”
“Help”
“Symbol”
“Message”
“*ItemsList”1
“Items”
“Selection”
“Text”
(XmDIALOG_APPLY_BUTTON)
(XmDIALOG_CANCEL_BUTTON)
(XmDIALOG_OK_BUTTON)
(XmDIALOG_SEPARATOR)
(XmDIALOG_HELP_BUTTON)
(XmDIALOG_SYMBOL_LABEL)
(XmDIALOG_MESSAGE_LABEL)
(XmDIALOG_LIST)
(XmDIALOG_LIST_LABEL)
(XmDIALOG_SELECTION_LABEL)
(XmDIALOG_TEXT)
Structures
The possible values for child are:
XmDIALOG_APPLY_BUTTON
XmDIALOG_OK_BUTTON
XmDIALOG_CANCEL_BUTTON
XmDIALOG_SELECTION_LABEL
XmDIALOG_DEFAULT_BUTTON
XmDIALOG_HELP_BUTTON
XmDIALOG_LIST
XmDIALOG_WORK_AREA
XmDIALOG_LIST_LABEL
XmDIALOG_SEPARATOR
XmDIALOG_TEXT
See Also
XmPromptDialog(2), XmSelectionBox(2).
1.The “*” is important: the List is not a direct child of the SelectionBox, but of a ScrolledList.
Motif Reference Manual
331
XmSetColorCalculation
Motif Functions and Macros
Name
XmSetColorCalculation – set the procedure that calculates default colors.
Synopsis
XmColorProc XmSetColorCalculation (XmColorProc color_proc)
Inputs
color_proc
Specifies the procedure that is used for color calculation.
Returns
The previous color calculation procedure.
Description
XmSetColorCalculation() sets the procedure called by XmGetColors()1
that calculates the default foreground, top and bottom shadow, and selection
colors. The procedure calculates these colors based on the background color that
has been passed to the procedure. If color_proc is NULL, this routine restores the
default color calculation procedure. XmSetColorCalculation() returns the
color calculation procedure that was in use when the routine was called. Both
XmGetColors() and XmChangeColor() use the color calculation procedure.
Usage
Motif widgets rely on the use of shadowed borders to create their three-dimensional appearance. The top and bottom shadow colors are lighter and darker
shades of the background color; these colors are reversed to make a component
appear raised out of the screen or recessed into the screen. The select color is a
slightly darker shade of the background color that indicates that a component is
selected. The foreground color is either black or white, depending on which color
provides the most contrast with the background color. XmSetColorCalculation() sets the procedure that calculates these colors. Use XmGetColorCalculation() to get the default color calculation procedure.
In Motif 2.0 and later, per-screen color calculation procedures are supported: if
the XmNcolorCalculationProc resource of the XmScreen object associated with
a given widget is not NULL, the procedure specified by the resource is used to
calculate color in preference to any procedure which may have been specified by
XmSetColorCalculation().
Procedures
The XmColorProc has the following syntax:
typedef void (*XmColorProc) ( XColor
ground color */
*bg_color,
/* specifies the back-
1.Erroneously missing from 1st and 2nd editions.
332
Motif Reference Manual
Motif Functions and Macros
XmSetColorCalculation
XColor
*fg_color,
/* returns the fore-
XColor
*sel_color,
/* returns the select
XColor
*ts_color,
/* returns the top
XColor
*bs_color)
/* returns the bottom
ground color */
color */
shadow color */
shadow color */
An XmColorProc takes five arguments. The first argument, bg_color, is a pointer
to an XColor structure that specifies the background color. The red, green, blue,
and pixel fields in the structure contain valid values. The rest of the arguments are
pointers to XColor structures for the colors that are to be calculated. The procedure fills in the red, green, and blue fields in these structures.
See Also
XmChangeColor(1), XmGetColorCalculation(1), XmGetColors(1).
XmScreen(2).
Motif Reference Manual
333
XmSetFontUnit
Motif Functions and Macros
Name
XmSetFontUnit – set the font unit values.
Synopsis
void XmSetFontUnit (Display *display, int font_unit_value)
Inputs
display
Specifies a connection to an X server; returned from XOpenDisplay() or XtDisplay().
font_unit_value Specifies the value for both horizontal and vertical font units.
Availability
In Motif 1.2 and later, XmSetFontUnit() is obsolete. It has been superseded
by setting the Screen resources XmNhorizontalFontUnit and XmNverticalFontUnit.
Description
XmSetFontUnit() sets the value of the horizontal and vertical font units for all
of the screens on the display. This routine is retained for compatibility with Motif
1.1 and should not be used in newer applications.
Usage
Font units are a resolution-independent unit of measurement that are based on the
width and height characteristics of a particular font. The default horizontal and
vertical font unit values are based on the XmNfont resource, which in Motif 1.2,
is a resource of the Screen object. An application can override these default values by calling XmSetFontUnit(). The values should be set before any widgets
that use resolution-independent data are created.
See Also
XmConvertUnits(1), XmSetFontUnits(1), XmGadget(2),
XmManager(2), XmPrimitive(2), XmScreen(2).
334
Motif Reference Manual
Motif Functions and Macros
XmSetFontUnits
Name
XmSetFontUnits – set the font unit values.
Synopsis
void XmSetFontUnits (Display *display, int h_value, int v_value)
Inputs
display
Specifies a connection to an X server; returned from XOpenDisplay() or XtDisplay().
h_value
Specifies the value for horizontal font units.
v_value
Specifies the value for vertical font units.
Availability
In Motif 1.2 and later, XmSetFontUnits() is obsolete. It has been superseded
by setting the Screen resources XmNhorizontalFontUnit and XmNverticalFontUnit.
Description
XmSetFontUnits() sets the value of the horizontal and vertical font units to
h_value and v_value respectively. The routine sets the font units for all of the
screens on the display. This routine is retained for compatibility with Motif 1.1
and should not be used in newer applications.
Usage
Font units are a resolution-independent unit of measurement that are based on the
width and height characteristics of a particular font. The default horizontal and
vertical font unit values are based on the XmNfont resource, which in Motif 1.2
and later, is a resource of the Screen object. An application can override these
default values by calling XmSetFontUnits(). The values should be set before
any widgets that use resolution-independent data are created.
See Also
XmConvertUnits(1), XmSetFontUnit(1), XmGadget(2),
XmManager(2), XmPrimitive(2), XmScreen(2).
Motif Reference Manual
335
XmSetMenuCursor
Motif Functions and Macros
Name
XmSetMenuCursor – set the current menu cursor.
Synopsis
void XmSetMenuCursor (Display *display, Cursor cursorId)
Inputs
display
Specifies a connection to an X server; returned from XOpenDisplay() or XtDisplay().
cursorId
Specifies the cursor ID for the menu cursor.
Availability
In Motif 1.2 and later, XmSetMenuCursor() is obsolete. It has been superseded by setting the Screen resource XmNmenuCursor.
Description
XmSetMenuCursor() sets the menu cursor for an application. The routine sets
the cursor for all screens on the specified display. The specified cursor is shown
whenever the application is using a Motif menu on the specified display. This
routine is retained for compatibility with Motif 1.1 and should not be used in
newer applications.
Usage
The menu cursor is the pointer shape that is used whenever a menu is posted.
This cursor can be different from the normal pointer shape. In Motif 1.2 and later,
the new Screen object has a resource, XmNmenuCursor, that specifies the menu
cursor. XmSetMenuCursor() is retained for compatibility with Motif 1.1 and
should not be used in newer applications.
See Also
XmGetMenuCursor(1), XmScreen(2).
336
Motif Reference Manual
Motif Functions and Macros
XmSetProtocolHooks
Name
XmSetProtocolHooks – set prehooks and posthooks for a protocol.
Synopsis
#include <Xm/Protocols.h>
void XmSetProtocolHooks ( Widget
Atom
Atom
XtCallbackProc
XtPointer
XtCallbackProc
XtPointer
Inputs
shell
property
protocol
prehook
pre_closure
posthook
post_closure
shell,
property,
protocol,
prehook,
pre_closure,
posthook,
post_closure)
Specifies the widget associated with the protocol property.
Specifies the property that holds the protocol data.
Specifies the protocol atom.
Specifies the procedure to invoke before the client callbacks.
Specifies any client data that is passed to the prehook.
Specifies the procedure to invoke after the client callbacks.
Specifies any client data that is passed to the posthook.
Description
XmSetProtocolHooks() allows pre- and post-procedures to be invoked in
addition to the regular callback procedures that are performed when the Motif
window manager sends a protocol message. The prehook procedure is invoked
before calling the procedures on the client’s callback list, whereas the posthook
procedure is invoked after calling the procedures on the client’s callback list. This
routine gives shells more control flow, since callback procedures aren’t necessarily executed in any particular order.
Usage
A protocol is a communication channel between applications. Protocols are simply atoms, stored in a property on the top-level shell window for the application.
To communicate using a protocol, a client sends a ClientMessage event containing a property and protocol, and the receiving client responds by calling the associated protocol callback routine. XmSetProtocolHooks() gives an
application more control over the flow of callback procedures, since callbacks are
not necessarily invoked in any particular order.
See Also
XmAddProtocolCallback(1), XmRemoveProtocolCallback(1),
XmSetWMProtocolHooks(1), VendorShell(2).
Motif Reference Manual
337
XmSetWMProtocolHooks
Motif Functions and Macros
Name
XmSetWMProtocolHooks – set prehooks and posthooks for the
XA_WM_PROTOCOLS protocol.
Synopsis
#include <Xm/Protocols.h>
void XmSetWMProtocolHooks ( Widget
Atom
XtCallbackProc
XtPointer
XtCallbackProc
XtPointer
Inputs
shell
protocol
prehook
pre_closure
posthook
post_closure
shell,
protocol,
prehook,
pre_closure,
posthook,
post_closure)
Specifies the widget associated with the protocol property.
Specifies the protocol atom.
Specifies the procedure to invoke before the client callbacks.
Specifies any client data that is passed to the prehook.
Specifies the procedure to invoke after the client callbacks.
Specifies any client data that is passed to the posthook.
Description
XmSetWMProtocolHooks()1 is a convenience routine that calls XmSetProtocolHooks() with property set to XA_WM_PROTOCOL, the window manager protocol property.
Usage
The property XA_WM_PROTOCOLS is a set of predefined protocols for communication between clients and window managers. To communicate using a
protocol, a client sends a ClientMessage event containing a property and protocol, and the receiving client responds by calling the associated protocol callback
routine. XmSetWMProtocolHooks() gives an application more control over
the flow of callback procedures, since callbacks are not necessarily invoked in
any particular order.
See Also
XmAddWMProtocolCallback(1), XmInternAtom(1),
XmRemoveWMProtocolCallback(1), XmSetProtocolHooks(1),
VendorShell(2).
1.Erroneously given as XmSetXmProtocolHooks() in 1st and 2nd editions.
338
Motif Reference Manual
Motif Functions and Macros
XmSimpleSpinBoxAddItem
Name
XmSimpleSpinBoxAddItem – add an item to a SimpleSpinBox.
Synopsis
#include <Xm/SSpinB.h>
void XmSimpleSpinBoxAddItem (Widget widget, XmString item, int position)
Inputs
widget
item
position
Specifies a SimpleSpinBox widget.
Specifies an item to add.
Specifies the position at which to add the new item.
Availability
Motif 2.1 and later.
Description
XmSimpleSpinBoxAddItem() adds an item to a SimpleSpinBox widget at a
given position within the list of values which the widget may display. If position
is zero, or if position is greater than the number of items in the list, the item is
appended to the list of values.
Usage
XmSimpleSpinBoxAddItem() is a convenience routine that adds an item to
the list of items which a SimpleSpinBox may display. In order to add an item to
the SimpleSpinBox, a compound string must be created. XmSimpleSpinBoxAddItem() adds the item to the SimpleSpinBox by manipulating the XmNvalues, XmNnumValues, and XmNposition resources of the widget. If the
XmNspinBoxChildType resource of the widget is not XmSTRING, or if the item
is NULL, the procedure simply returns without modifying the array of values.
The SimpleSpinBox widget takes a copy of the supplied item; the programmer is
responsible for freeing the compound string at an appropriate point by calling
XmStringFree().
Example
The following procedure simply appends an item onto the end of a SimpleSpinBox list:
void SimpleSpinBoxAppend (Widget spinb, char *item)
{
XmString xms = XmStringGenerate ((XtPointer)
value,
XmFONTLIST_DEF
AULT_TAG,
Motif Reference Manual
339
XmSimpleSpinBoxAddItem
Motif Functions and Macros
XmCHARSET_TEXT,
NULL);
XmSimpleSpinBoxAddItem (spinb, xms, 0);
XmStringFree (xms);
}
See Also
XmSimpleSpinBoxDeletePos(1), XmSimpleSpinBoxSetItem(1),
XmStringFree(1), XmSimpleSpinBox(2).
340
Motif Reference Manual
Motif Functions and Macros
XmSimpleSpinBoxDeletePos
Name
XmSimpleSpinBoxDeletePos – delete an item at the specified position from a
SimpleSpinBox.
Synopsis
#include <Xm/SSpinB.h>
void XmSimpleSpinBoxDeletePos (Widget widget, int position)
Inputs
widget
position
Specifies a SimpleSpinBox widget.
Specifies the position at which to delete an item.
Availability
Motif 2.1 and later.
Description
XmSimpleSpinBoxDeletePos() deletes an item at a given position from a
SimpleSpinBox widget. A value of 1 indicates the first item, 2 is the second item,
and so on. The last item in the list can be specified by passing a position of zero.
Usage
XmSimpleSpinBoxDeletePos() is a convenience function which deletes an
item from the set of values associated with a SimpleSpinBox. The function
directly manipulates the XmNvalues, XmNnumValues, and XmNposition
resources of the widget. If the XmNspinBoxChildType resource of the widget is
not XmSTRING, the function simply returns without modifying the array of values.
See Also
XmSimpleSpinBoxAddItem(1), XmSimpleSpinBoxSetItem(1),
XmSimpleSpinBox(2).
Motif Reference Manual
341
XmSimpleSpinBoxSetItem
Motif Functions and Macros
Name
XmSimpleSpinBoxSetItem – set an item in a SimpleSpinBox.
Synopsis
#include <Xm/SSpinB.h>
void XmSimpleSpinBoxSetItem (Widget widget, XmString item)
Inputs
widget
item
Specifies a SimpleSpinBox widget.
Specifies the item to set.
Availability
Motif 2.1 and later.
Description
XmSimpleSpinBoxSetItem() makes an item in a SimpleSpinBox widget
the current value.
Usage
XmSimpleSpinBoxSetItem() is a convenience routine that selects one of
the SimpleSpinBox values. The item must exist within the XmNvalues array of
the widget, otherwise a warning message is displayed. The function modifies the
XmNposition resource of the widget if the item is found. No check is performed
to ensure that the XmNspinBoxChildType resource of the SimpleSpinBox is
XmSTRING.
See Also
XmSimpleSpinBoxAddItem(1), XmSimpleSpinBoxDeletePos(1),
XmSimpleSpinBox(2).
342
Motif Reference Manual
Motif Functions and Macros
XmSpinBoxValidatePosition
Name
XmSpinBoxValidatePosition – validate the current value of a SpinBox.
Synopsis
#include <Xm/SpinB.h>
int XmSpinBoxValidatePosition (Widget text_field, int *position_value)
Inputs
text_field
Specifies a text field child of a SpinBox widget.
Outputs
position_value
Returns the position of the current value.
Returns
The status of the validation.
Availability
Motif 2.1 and later.
Description
XmSpinBoxValidatePosition() checks that the text_field child of a SpinBox has a valid position value, and places the validated value of the text_field at
the address position_value. If the position is valid, the function returns
XmVALID_VALUE. Otherwise the function returns XmCURRENT_VALUE,
XmMAXIMUM_VALUE, XmMINIMUM_VALUE, or
XmINCREMENT_VALUE, depending upon a comparison of the current position and other constraint resources of the text_field.
Usage
XmSpinBoxValidatePosition() can be used to ensure that the user has
entered a valid value into an editable textual child of a SpinBox. If text_field is
NULL, or if text_field does not hold the XmQTaccessTextual trait, or if the
XmNspinBoxChildType of this widget is not XmNUMERIC the function returns
XmCURRENT_VALUE. The current value of the text field is fetched as a floating point number, then converted into an integer using the XmNdecimalPoints
resource: digits after the decimal place are simply truncated. The current value is
subsequently compared against the XmNminimumValue and XmNmaximumValue resources: if less than XmNminimumValue, position_value is set to the
value of XmNminimumValue, and the function returns XmMINIMUM_VALUE,
or if the current value is more than XmNmaximumValue, position_value is set to
the value of XmNmaximumValue, and the function returns
XmMAXIMUM_VALUE. Lastly, the function checks that the current value falls
between XmNminimumValue and XmNmaximumValue on an interval specified
Motif Reference Manual
343
XmSpinBoxValidatePosition
Motif Functions and Macros
by the XmNincrementValue resource. That is, the current value is a member of
the set:
{
XmNminimumValue,
XmNminimumValue + XmNincrementValue,
XmNminimumValue + (2 * XmNincrementValue),
XmNminimumValue + (3 * XmNincrementValue),
...
XmNminimumValue + (n * XmNincrementValue),
...
XmNmaximumValue
}
If the current value does not fall within the set, the position_value is set to the
nearest item in the set which is not more than the current value, and the function
returns XmINCREMENT_VALUE. If all checks pass, the position_value is set to
the current value, and the function returns XmVALID_VALUE.
The SpinBox does not modify the contents of text_field when performing the validation.
Structures
The returned status has the following values:
XmCURRENT_VALUE
XmMAXIMUM_VALUE
XmVALID_VALUE
XmINCREMENT_VALUE
XmMINIMUM_VALUE
See Also
XmSpinBox(2).
344
Motif Reference Manual
Motif Functions and Macros
XmStringBaseline
Name
XmStringBaseline – get the baseline spacing for a compound string.
Synopsis
Dimension XmStringBaseline (XmFontList fontlist, XmString string)
Inputs
fontlist
string
Specifies the font list for the compound string.
Specifies the compound string.
Returns
The distance, in pixels, from the top of the character box to the baseline of the
first line of text.
Availability
In Motif 2.0 and later, the XmFontList is obsolete. It is superseded by the
XmRenderTable, to which it has become an alias.
Description
XmStringBaseline() returns the distance, in pixels, from the top of the character box to the baseline of the first line of text in string. If string is created with
XmStringCreateSimple(), then fontlist must begin with the font associated
with the character set from the current language environment, otherwise the
result is undefined.
Usage
In Motif 1.2, a compound string is composed of one or more segments, where
each segment can contain a font list element tag, a string direction, and a text
component. In Motif 2.0 and later, the set of available segments is extended to
include, amongst other items, tab, rendition, direction, locale components.
XmStringBaseline() provides information that is useful if you need to
render a compound string. Motif widgets render compound string automatically,
so you only need to worry about rendering them yourself if you are writing your
own widget. The routine is also useful if you want to get the dimensions of a
compound string rendered with a particular font.
See Also
XmStringComponentCreate(1), XmStringExtent(1),
XmStringHeight(1), XmStringWidth(1), XmRendition(2).
Motif Reference Manual
345
XmStringByteCompare
Motif Functions and Macros
Name
XmStringByteCompare – compare two compound strings byte-by-byte.
Synopsis
Boolean XmStringByteCompare (XmString string1, XmString string2)
Inputs
string1
string2
Specifies a compound string.
Specifies another compound string.
Returns
True if the two compound strings are byte-by-byte identical or False otherwise.
Description
XmStringByteCompare() compares the compound strings string1 and
string2 byte by byte. If the strings are equivalent, it returns True; otherwise it
returns False. If two compound strings are created with XmStringCreateLocalized() in the same language environment, using the same character string,
the strings are byte-for-byte equal. Similarly, if two compound strings are created
with XmStringCreate() using the same font list element tag and character
string, the strings are equal.
Usage
In Motif 1.2, a compound string is composed of one or more segments, where
each segment can contain a font list element tag, a string direction, and a text
component. In Motif 2.0 and later, the set of available segments is extended to
include, amongst other items, tab, rendition, direction, locale components.
XmStringByteCompare() is one of a number of routines that allow an application to manipulate compound strings as it would regular character strings.
When a compound string is placed into a widget, the string is sometimes converted to an internal format, which provides faster processing but strips out
redundant information. As a result, when an application retrieves the compound
string from the widget by calling XtGetValues(), the returned string does not
necessarily match the original string byte-for-byte. This situation occurs most
often with Label widgets and its subclasses.
See Also
XmStringComponentCreate(1), XmStringCompare(1).
346
Motif Reference Manual
Motif Functions and Macros
XmStringByteStreamLength
Name
XmStringByteStreamLength – calculates the length of a byte stream.
Synopsis
unsigned int XmStringByteStreamLength (unsigned char *string)
Inputs
string
Specifies a string in byte stream format.
Returns
The length, in bytes, of the string.
Availability
Motif 2.0 and later.
Description
XmStringByteStreamLength() calculates and returns the length of a byte
stream string in bytes, including any header information. The string is presumed
to be a compound string which has been converted into byte stream format.
Usage
Since the returned value includes the size of the stream header, the function
returns a non-zero value even if string is NULL. The function is primarily used as
part of data transfer operations, for example in transferring compound string
tables to and from the clipboard or other widgets.
See Also
XmCvtXmStringToByteStream(1),
XmCvtByteStreamToXmString(1).
Motif Reference Manual
347
XmStringCompare
Motif Functions and Macros
Name
XmStringCompare – compare two compound strings.
Synopsis
Boolean XmStringCompare (XmString string1, XmString string2)
Inputs
string1
string2
Specifies a compound string.
Specifies another compound string.
Returns
True if the two compound strings are semantically equivalent or False otherwise.
Description
XmStringCompare() compares the compound strings string1 and string2
semantically. If the strings are equivalent, it returns True; otherwise it returns
False. XmStringCompare() is similar to XmStringByteCompare() but
less restrictive. Two compound string are semantically equivalent if they have the
same text components, font list element tags, directions, and separators.
Usage
In Motif 1.2, a compound string is composed of one or more segments, where
each segment can contain a font list element tag, a string direction, and a text
component. In Motif 2.0 and later, the set of available segments is extended to
include, amongst other items, tab, rendition, direction, locale components.
XmStringCompare() is one of a number of routines that allow an application
to manipulate compound strings as it would regular character strings.
See Also
XmStringcomponentCreate(1), XmStringByteCompare(1).
348
Motif Reference Manual
Motif Functions and Macros
XmStringComponentCreate
Name
XmStringComponentCreate – create a compound string consisting of a single
component.
Synopsis
XmString XmStringComponentCreate (
Inputs
type
length
value
XmStringComponentType
unsigned int
XtPointer
type,
length,
value)
Specifies the type of component to create.
Specifies the length, in bytes, of value.
Specifies the value of the component.
Returns
A new compound string, or NULL.
Availability
Motif 2.0 and later.
Description
XmStringComponentCreate() creates a new compound string consisting of
a component of the type specified by type, which contains the given value.
Usage
If type is not a valid component type, or if length is greater than zero and value is
NULL, then the function returns NULL. Otherwise, the function returns an allocated compound string. It is the responsibility of the programmer to reclaim the
utilized space at an appropriate point by calling XmStringFree().
Structures
The string component type can have one of the following values:
XmSTRING_COMPONENT_CHARSET
XmSTRING_COMPONENT_TEXT
XmSTRING_COMPONENT_LOCALE_TEXT
XmSTRING_COMPONENT_DIRECTION
XmSTRING_COMPONENT_SEPARATOR
XmSTRING_COMPONENT_TAB
XmSTRING_COMPONENT_END
XmSTRING_COMPONENT_UNKNOWN
XmSTRING_COMPONENT_FONTLIST_ELEMENT_TAG
XmSTRING_COMPONENT_WIDECHAR_TEXT
XmSTRING_COMPONENT_LAYOUT_PUSH
XmSTRING_COMPONENT_LAYOUT_POP
Motif Reference Manual
349
XmStringComponentCreate
Motif Functions and Macros
XmSTRING_COMPONENT_RENDITION_BEGIN
XmSTRING_COMPONENT_RENDITION_END
Example
The following code illustrates basic compound string creation by concatenating
elements from an array of strings:
XmString create_xmstring_from_array (char **array, int count, Boolean tab)
{
XmString
txt, sep;
XmString
xms = (XmString) 0;
XmStringComponentType
sep_type;
int
i;
if (tab) {
sep_type = XmSTRING_COMPONENT_TAB;
}
else {
sep_type = XmSTRING_COMPONENT_SEPARATOR;
}
for (i = 0; i < count; i++) {
txt = XmStringComponentCreate
(XmSTRING_COMPONENT_TE
XT, strlen (array[i]), (XtPointer)
array[i]);
xms = XmStringConcatAndFree (xms, txt);
if (i < count) {
/* another item after this... */
sep = XmStringComponentCreate (sep_type, 0, NULL);
xms = XmStringConcatAndFree (xms, sep);
}
}
/* caller must free this */
return xms;
}
See Also
XmStringConcatAndFree(1), XmStringFree(1).
350
Motif Reference Manual
Motif Functions and Macros
XmStringConcat
Name
XmStringConcat – concatenate two compound strings.
Synopsis
XmString XmStringConcat (XmString string1, XmString string2)
Inputs
string1
string2
Specifies a compound string.
Specifies another compound string.
Returns
A new compound string.
Description
XmStringConcat() returns the compound string formed by appending string2
to string1, leaving the original compound strings unchanged. Storage for the
result is allocated within the routine and should be freed by calling XmStringFree(). Management of the allocated memory is the responsibility of the application.
Usage
In Motif 1.2, a compound string is composed of one or more segments, where
each segment can contain a font list element tag, a string direction, and a text
component. In Motif 2.0 and later, the set of available segments is extended to
include, amongst other items, tab, rendition, direction, locale components.
XmStringConcat() is one of a number of routines that allow an application to
manipulate compound strings as it would regular character strings.
See Also
XmStringComponentCreate(1), XmStringCopy(1),
XmStringNConcat(1), XmStringNCopy(1).
Motif Reference Manual
351
XmStringConcatAndFree
Motif Functions and Macros
Name
XmStringConcatAndFree – concatenate two compound strings.
Synopsis
XmString XmStringConcatAndFree (XmString string1, XmString string2)
Inputs
string1
string2
Specifies a compound string.
Specifies another compound string.
Returns
A new compound string.
Availability
Motif 2.0 and later.
Description
XmStringConcatAndFree() is similar to XmStringConcat() in that each
returns a compound string formed by appending string2 to string1. XmStringConcatAndFree() differs from XmStringConcat() by freeing the original
compound strings. Storage for the result is allocated within the routine and
should be freed by calling XmStringFree(). Management of the allocated
memory is the responsibility of the application.
Usage
In Motif 1.2, a compound string is composed of one or more segments, where
each segment can contain a font list element tag, a string direction, and a text
component. In Motif 2.0 and later, the set of available segments is extended to
include, amongst other items, tab, rendition, direction, and locale components.
Example
The following code constructs a simple compound string out of piecemeal subcomponents:
XmString xms;
XmString xms_temp;
xms = XmStringGenerate((XtPointer) “Multiple”,
XmFONTLIST_DEFAULT_TAG,
XmCHARSET_TEXT,
NULL);
xms_temp = XmStringComponentCreate
(XmSTRING_COMP
ONENT_TAB, 0,
NULL);
xms = XmStringConcatAndFree(xms, xms_temp);
352
Motif Reference Manual
Motif Functions and Macros
XmStringConcatAndFree
xms_temp = XmStringGenerate((XtPointer) “Column”,
XmFONTLIST_DEFAULT_TAG
,
XmCHARSET_TEXT,
NULL);
xms = XmStringConcatAndFree (xms, xms_temp);
xms_temp = XmStringComponentCreate
(XmSTRING_COMP
ONENT_TAB, 0,
NULL);
xms = XmStringConcatAndFree (xms, xms_temp);
xms_temp = XmStringGenerate((XtPointer) “Format”,
XmFONTLIST_DEFAULT_TAG
,
XmCHARSET_TEXT,
NULL);
xms = XmStringConcatAndFree (xms, xms_temp);
See Also
XmStringComponentCreate(1), XmStringCopy(1),
XmStringConcat(1), XmStringNConcat(1), XmStringNCopy(1).
Motif Reference Manual
353
XmStringCopy
Motif Functions and Macros
Name
XmStringCopy – copy a compound string.
Synopsis
XmString XmStringCopy (XmString string)
Inputs
string
Specifies a compound string.
Returns
A new compound string.
Description
XmStringCopy() copies the compound string string and returns the copy, leaving the original compound string unchanged. Storage for the result is allocated by
the routine and should be freed by calling XmStringFree(). Management of
the allocated memory is the responsibility of the application.
Usage
In Motif 1.2, a compound string is composed of one or more segments, where
each segment can contain a font list element tag, a string direction, and a text
component. In Motif 2.0 and later, the set of available segments is extended to
include, amongst other items, tab, rendition, direction, locale components.
XmStringCopy() is one of a number of routines that allow an application to
manipulate compound strings as it would regular character strings.
See Also
XmStringComponentCreate(1), XmStringConcat(1),
XmStringNConcat(1), XmStringNCopy(1).
354
Motif Reference Manual
Motif Functions and Macros
XmStringCreate
Name
XmStringCreate – create a compound string.
Synopsis
XmString XmStringCreate (char *text, XmStringCharSet tag)
Inputs
text
tag
Specifies the text component of the compound string.
Specifies the font list element tag.
Returns
A new compound string.
Description
XmStringCreate() creates a compound string containing two components: a
text component composed of text and the font list element tag specified by tag.
text must be a NULL-terminated string. tag can have the value
XmFONTLIST_DEFAULT_TAG, which identifies a locale-encoded text segment. Storage for the returned compound string is allocated by the routine and
should be freed by calling XmStringFree(). Management of the allocated
memory is the responsibility of the application.
Usage
In Motif 1.2, a compound string is composed of one or more segments, where
each segment can contain a font list element tag, a string direction, and a text
component. In Motif 2.0 and later, the set of available segments is extended to
include, amongst other items, tab, rendition, direction, locale components.
XmStringCreate() allows you to create a compound string composed of a
font list element tag and a text component.
In Motif 1.1, compound strings use character set identifiers rather than font list
element tags. The character set identifier for a compound string can have the
value XmSTRING_DEFAULT_CHARSET, which takes the character set from
the current language environment, but this value may be removed from future
versions of Motif.
XmStringCreate() creates a compound string with no specified direction.
The default direction may be taken from the XmNstringDirection resource of the
parent of the widget that contains the compound string. If you need a string with
a direction other than the default direction, use XmStringDirectionCreate() to create a direction string and concatenate it with the compound string
containing the text.
Motif Reference Manual
355
XmStringCreate
Motif Functions and Macros
Example
The following code fragment shows how to create compound strings using
XmStringCreate():
Widget
toplevel;
XmString s1, s2, s3, text, tmp;
String
string1 = "This is a string", string2 = "that contains three", string3 =
"separate fonts.";
s1 = XmStringCreate (string1, "tag1");
s2 = XmStringCreate (string2, "tag2");
s3 = XmStringCreate (string3, XmFONTLIST_DEFAULT_TAG);
tmp = XmStringConcatAndFree (s1, s2);
text = XmStringConcatAndFree (tmp, s3);
XtVaCreateManagedWidget ("widget_name", xmLabelWidgetClass, toplevel,
XmNlabelString, text, NULL);
XmStringFree (text);
See Also
XmStringBaseline(1), XmStringByteCompare(1),
XmStringCompare(1), XmStringConcat(1),
XmStringComponentCreate(1), XmStringCopy(1),
XmStringCreateLocalized(1), XmStringCreateLtoR(1),
XmStringCreateSimple(1), XmStringDirectionCreate(1),
XmStringDraw(1), XmStringDrawImage(1),
XmStringDrawUnderline(1), XmStringEmpty(1),
XmStringExtent(1), XmStringFree(1), XmStringFreeContext(1),
XmStringGetLtoR(1), XmStringGetNextComponent(1),
XmStringGetNextSegment(1), XmStringHasSubstring(1),
XmStringHeight(1), XmStringInitContext(1),
XmStringLength(1), XmStringLineCount(1),
XmStringNConcat(1), XmStringNCopy(1),
XmStringPeekNextComponent(1), XmStringSegmentCreate(1),
XmStringSeparatorCreate(1), XmStringWidth(1).
356
Motif Reference Manual
Motif Functions and Macros
XmStringCreateLocalized
Name
XmStringCreateLocalized – create a compound string in the current locale.
Synopsis
XmString XmStringCreateLocalized (String text)
Inputs
text
Specifies the text component of the compound string.
Returns
A new compound string.
Availability
Motif 1.2 and later.
Description
XmStringCreateLocalized() creates a compound string containing two
components: a text component composed of text and the font list element tag
XmFONTLIST_DEFAULT_TAG, which identifies a locale-encoded text segment. text must be a NULL-terminated string. Storage for the returned compound
string is allocated by the routine and should be freed by calling XmStringFree(). Management of the allocated memory is the responsibility of the application.
Usage
In Motif 1.2, a compound string is composed of one or more segments, where
each segment can contain a font list element tag, a string direction, and a text
component. In Motif 2.0 and later, the set of available segments is extended to
include, amongst other items, tab, rendition, direction, locale components.
XmStringCreateLocalized() creates the identical compound string that
would result from calling XmStringCreate with
XmFONTLIST_DEFAULT_TAG as the font list entry tag.
Example
The following program shows how to create a compound string in the current
locale and use it as the label for a PushButton:
#include <Xm/RowColumn.h>
#include <Xm/PushB.h>
String fallbacks[] = { "*fontList:9x15=tag", NULL };
main (int argc, char *argv[])
{
Widget
toplevel, rowcol;
XtAppContext app;
Motif Reference Manual
357
XmStringCreateLocalized
XmString
Motif Functions and Macros
text;
XtSetLanguageProc (NULL, (XtLanguageProc) NULL, NULL);
toplevel = XtVaAppInitialize (&app, argv[0], NULL, 0, &argc, argv, fallbacks, NULL);
rowcol = XtVaCreateWidget ("rowcol", xmRowColumnWidgetClass,
toplevel, NULL);
text = XmStringCreateLocalized ("Testing, testing...");
XtVaCreateManagedWidget ("pb", xmPushButtonWidgetClass, rowcol,
XmNlabelString, text, NULL);
XmStringFree (text);
XtManageChild (rowcol);
XtRealizeWidget (toplevel);
XtAppMainLoop (app);
}
See Also
XmStringComponentCreate(1), XmStringCreate(1),
XmStringFree(1).
358
Motif Reference Manual
Motif Functions and Macros
XmStringCreateLtoR
Name
XmStringCreateLtoR – create a compound string.
Synopsis
XmString XmStringCreateLtoR (char *text, XmStringCharSet tag)
Inputs
text
tag
Specifies the text component of the compound string.
Specifies the font list element tag.
Returns
A new compound string.
Availability
In Motif 2.0 and later, this function is obsolete, and is replaced by the function
XmStringGenerate().
Description
XmStringCreateLtoR() creates a compound string containing two components: a text component composed of text and the font list element tag specified
by tag. text must be a NULL-terminated string. In addition, XmStringCreateLtoR() searches for newline characters (\n) in text. Each time a newline is
found, the characters up to the newline are placed into a compound string segment followed by a separator component. The routine does not add a separator
component to the end of the compound string. The default direction of the string
is left to right and the assumed encoding is 8-bit characters rather than 16-bit
characters.
tag can have the value XmFONTLIST_DEFAULT_TAG, which identifies a
locale-encoded text segment. Storage for the returned compound string is allocated by the routine and should be freed by calling XmStringFree(). Management of the allocated memory is the responsibility of the application.
Usage
In Motif 1.2, a compound string is composed of one or more segments, where
each segment can contain a font list element tag, a string direction, and a text
component. In Motif 2.0 and later, the set of available segments is extended to
include, amongst other items, tab, rendition, direction, locale components.
XmStringCreateLtoR() allows you to create a compound string composed
of a font list element tag and a multi-line text component.
Motif Reference Manual
359
XmStringCreateLtoR
Motif Functions and Macros
In Motif 1.1, compound strings use character set identifiers rather than font list
element tags. The character set identifier for a compound string can have the
value XmSTRING_DEFAULT_CHARSET, which takes the character set from
the current language environment, but this value may be removed from future
versions of Motif.
See Also
XmStringComponentCreate(1), XmStringCreate(1),
XmStringFree(1). XmStringGenerate(1).
360
Motif Reference Manual
Motif Functions and Macros
XmStringCreateSimple
Name
XmStringCreateSimple – create a compound string in the current language environment.
Synopsis
XmString XmStringCreateSimple (char *text)
Inputs
text
Specifies the text component of the compound string.
Returns
A new compound string.
Availability
In Motif 1.2, XmStringCreateSimple() is obsolete. It has been superseded
by XmStringCreateLocalized().
Description
XmStringCreateSimple() creates a compound string containing two components: a text component composed of text and a character set identifier derived
from the LANG environment variable or from a vendor-specific default, which is
usually ISO8859-1. text must be a NULL-terminated string. Storage for the
returned compound string is allocated by the routine and should be freed by calling XmStringFree(). Management of the allocated memory is the responsibility of the application.
Usage
In Motif 1.2, a compound string is composed of one or more segments, where
each segment can contain a font list element tag, a string direction, and a text
component. In Motif 2.0 and later, the set of available segments is extended to
include, amongst other items, tab, rendition, direction, locale components. In
Motif 1.1, compound strings use character set identifiers rather than font list element tags. XmStringCreateSimple() is retained for compatibility with
Motif 1.1 and should not be used in newer applications.
See Also
XmStringComponentCreate(1), XmStringCreate(1),
XmStringCreateLocalized(1), XmStringFree(1).
Motif Reference Manual
361
XmStringDirectionCreate
Motif Functions and Macros
Name
XmStringDirectionCreate – create a compound string containing a direction
component.
Synopsis
XmString XmStringDirectionCreate (XmStringDirection direction)
Inputs
direction
Specifies the value of the direction component. Pass either
XmSTRING_DIRECTION_L_TO_R,
XmSTRING_DIRECTION_R_TO_L or
XmSTRING_DIRECTION_DEFAULT.
Returns
A new compound string.
Description
XmStringDirectionCreate() creates a compound string containing a single component, which is a direction component with the specified direction
value. If the direction is XmSTRING_DIRECTION_DEFAULT, the widget
where the compound string is rendered controls the direction. Storage for the
returned compound string is allocated by the routine and should be freed by calling XmStringFree(). Management of the allocated memory is the responsibility of the application.
Usage
In Motif 1.2, a compound string is composed of one or more segments, where
each segment can contain a font list element tag, a string direction, and a text
component. In Motif 2.0 and later, the set of available segments is extended to
include, amongst other items, tab, rendition, direction, locale components.
XmStringDirectionCreate() allows you to create a string direction component that can be concatenated with a compound string containing other components.
See Also
XmStringComponentCreate(1), XmStringCreate(1),
XmStringFree(1).
362
Motif Reference Manual
Motif Functions and Macros
XmStringDirectionToDirection
Name
XmStringDirectionToDirection – converts a string direction to a direction.
Synopsis
XmDirection XmStringDirectionToDirection (XmStringDirection
string_direction)
Inputs
string_direction
Specifies the string direction to be converted.
Returns
The converted direction.
Availability
Motif 2.0 and later.
Description
XmStringDirectionToDirection() converts an XmStringDirection
value specified by string_direction into an XmDirection value.
Usage
XmStringDirectionToDirection() converts between the XmStringDirection and XmDirection data types. If string_direction is
XmSTRING_DIRECTION_LEFT_TO_RIGHT, the function returns
XmLEFT_TO_RIGHT. If string_direction is
XmSTRING_DIRECTION_RIGHT_TO_LEFT, the function returns
XmRIGHT_TO_LEFT. Otherwise, the function returns
XmDIRECTION_DEFAULT.
See Also
XmStringDirectionCreate(1).
Motif Reference Manual
363
XmStringDraw
Motif Functions and Macros
Name
XmStringDraw – draw a compound string.
Synopsis
void XmStringDraw ( Display
Window
XmFontList
XmString
GC
Position
Position
Dimension
unsigned char
unsigned char
XRectangle
Inputs
display
window
fontlist
string
gc
x
y
width
alignment
layout_direction
clip
364
*display,
window,
fontlist,
string,
gc,
x,
y,
width,
alignment,
layout_direction,
*clip)
Specifies a connection to an X server; returned from
XOpenDisplay() or XtDisplay().
Specifies the window where the string is drawn.
Specifies the font list for drawing the string.
Specifies a compound string.
Specifies the graphics context that is used to draw the string.
Specifies the x-coordinate of the rectangle that will contain
the string.
Specifies the y-coordinate of the rectangle that will contain
the string.
Specifies the width of the rectangle that will contain the
string.
Specifies the alignment of the string in the rectangle. Pass
one of the following values:
XmALIGNMENT_BEGINNING,
XmALIGNMENT_CENTER, or
XmALIGNMENT_END.
Specifies the layout direction of the string segments. Pass
XmSTRING_DIRECTION_L_TO_R,
XmSTRING_DIRECTION_R_TO_L, or
XmSTRING_DIRECTION_DEFAULT.
Specifies an clip rectangle that restricts the area where the
string will be drawn.
Motif Reference Manual
Motif Functions and Macros
XmStringDraw
Availability
In Motif 2.0 and later, the XmFontList is obsolete, and is replaced by the
XmRenderTable, to which it is an alias.
Description
XmStringDraw() draws the compound string specified by string by rendering
the foreground pixels for each character. If string is created with
XmStringCreateSimple(), then fontlist must begin with the font associated
with the character set from the current language environment, otherwise the
result is undefined.
Usage
In Motif 1.2, a compound string is composed of one or more segments, where
each segment can contain a font list element tag, a string direction, and a text
component. In Motif 2.0 and later, the set of available segments is extended to
include, amongst other items, tab, rendition, direction, locale components.
XmStringDraw() provides a means of rendering a compound string that is
analogous to the Xlib string rendering routines. Motif widgets render compound
string automatically, so you only need to worry about rendering them yourself if
you are writing your own widget.
In Motif 1.2 or later, if a segment of a compound string is associated with a font
list entry that is a font set, the font member of the gc is left in an undefined state
by the underlying call to XmbDrawString(). If a segment of the compound
string is not associated with a font set, the gc must contain a valid font member.
The gc must be created using XtAllocateGC(); graphics contexts created with
XtGetGC() are not valid.
See Also
XmStringDrawImage(1), XmStringDrawUnderline(1),
XmRendition(2).
Motif Reference Manual
365
XmStringDrawImage
Motif Functions and Macros
Name
XmStringDrawImage – draw a compound string.
Synopsis
void XmStringDrawImage ( Display
Window
XmFontList
XmString
GC
Position
Position
Dimension
unsigned char
unsigned char
XRectangle
Inputs
display
window
fontlist
string
gc
x
y
width
alignment
layout_direction
clip
366
*display,
window,
fontlist,
string,
gc,
x,
y,
width,
alignment,
layout_direction,
*clip)
Specifies a connection to an X server; returned from
XOpenDisplay() or XtDisplay().
Specifies the window where the string is drawn.
Specifies the font list for drawing the string.
Specifies a compound string.
Specifies the graphics context that is used to draw the
string.
Specifies the x-coordinate of the rectangle that will contain the string.
Specifies the y-coordinate of the rectangle that will contain the string.
Specifies the width of the rectangle that will contain the
string.
Specifies the alignment of the string in the rectangle. Pass
one of the following values:
XmALIGNMENT_BEGINNING,
XmALIGNMENT_CENTER, or
XmALIGNMENT_END.
Specifies the layout direction of the string segments. Pass
XmSTRING_DIRECTION_L_TO_R,
XmSTRING_DIRECTION_R_TO_L, or
XmSTRING_DIRECTION_DEFAULT.
Specifies an clip rectangle that restricts the area where the
string will be drawn.
Motif Reference Manual
Motif Functions and Macros
XmStringDrawImage
Availability
In Motif 2.0 and later, the XmFontList is obsolete, and is replaced by the
XmRenderTable, to which it is an alias.
Description
XmStringDrawImage() draws the compound string specified by string by
painting the foreground and background pixels for each character. If string is created with XmStringCreateSimple(), then fontlist must begin with the font
associated with the character set from the current language environment, otherwise the result is undefined.
Usage
In Motif 1.2, a compound string is composed of one or more segments, where
each segment can contain a font list element tag, a string direction, and a text
component. In Motif 2.0 and later, the set of available segments is extended to
include, amongst other items, tab, rendition, direction, locale components.
XmStringDrawImage() provides a means of rendering a compound string
that is analogous to the Xlib string rendering routines. Motif widgets render compound string automatically, so you only need to worry about rendering them
yourself if you are writing your own widget.
In Motif 1.2 or later, if a segment of a compound string is associated with a font
list entry that is a font set, the font member of the gc is left in an undefined state
by the underlying call to XmbDrawImageString(). If a segment of the compound string is not associated with a font set, the gc must contain a valid font
member. The gc must be created using XtAllocateGC(); graphics contexts
created with XtGetGC() are not valid.
See Also
XmStringDraw(1), XmStringDrawUnderline(1), XmRendition(2).
Motif Reference Manual
367
XmStringDrawUnderline
Motif Functions and Macros
Name
XmStringDrawUnderline – draw a compound string with an underlined substring.
Synopsis
void XmStringDrawUnderline ( Display
Window
XmFontList
XmString
GC
Position
Position
Dimension
unsigned char
unsigned char
XRectangle
XmString
Inputs
display
window
fontlist
string
gc
x
y
width
alignment
layout_direction
clip
368
*display,
window,
fontlist,
string,
gc,
x,
y,
width,
alignment,
layout_direction,
*clip,
underline)
Specifies a connection to an X server; returned from
XOpenDisplay() or XtDisplay().
Specifies the window where the string is drawn.
Specifies the font list for drawing the string.
Specifies a compound string.
Specifies the graphics context that is used to draw the string.
Specifies the x-coordinate of the rectangle that will contain
the string.
Specifies the y-coordinate of the rectangle that will contain
the string.
Specifies the width of the rectangle that will contain the
string.
Specifies the alignment of the string in the rectangle. Pass
one of the following values:
XmALIGNMENT_BEGINNING,
XmALIGNMENT_CENTER, or
XmALIGNMENT_END.
Specifies the layout direction of the string segments. Pass
XmSTRING_DIRECTION_L_TO_R,
XmSTRING_DIRECTION_R_TO_L, or
XmSTRING_DIRECTION_DEFAULT.
Specifies an clip rectangle that restricts the area where the
string will be drawn.
Motif Reference Manual
Motif Functions and Macros
underline
XmStringDrawUnderline
Specifies the substring that is to be underlined.
Availability
In Motif 2.0 and later, the XmFontList is obsolete, and is replaced by the
XmRenderTable, to which it is an alias.
Description
XmStringDrawUnderline() is similar to XmStringDraw(), but it also
draws an underline beneath the first matching substring underline that is contained within string. If string is created with XmStringCreateSimple(),
then fontlist must begin with the font associated with the character set from the
current language environment, otherwise the result is undefined.
Usage
In Motif 1.2, a compound string is composed of one or more segments, where
each segment can contain a font list element tag, a string direction, and a text
component. In Motif 2.0 and later, the set of available segments is extended to
include, amongst other items, tab, rendition, direction, locale components.
XmStringDrawUnderline() provides a means of rendering a compound
string and underlining a substring within it. Motif widgets render compound
string automatically, so you only need to worry about rendering them yourself if
you are writing your own widget.
In Motif 1.2 and later, if a segment of a compound string is associated with a font
list entry that is a font set, the font member of the gc is left in an undefined state
by the underlying call to XmbDrawString(). If a segment of the compound
string is not associated with a font set, the gc must contain a valid font member.
The gc must be created using XtAllocateGC(); graphics contexts created with
XtGetGC() are not valid.
See Also
XmStringDraw(1), XmStringDrawImage(1), XmRendition(2).
Motif Reference Manual
369
XmStringEmpty
Motif Functions and Macros
Name
XmStringEmpty – determine whether there are text segments in a compound
string.
Synopsis
Boolean XmStringEmpty (XmString string)
Inputs
string
Specifies a compound string.
Returns
True if there are no text segments in the string or False otherwise.
Description
XmStringEmpty() returns True if no text segments exist in the specified string
and False otherwise. If the routine is passed NULL, it returns True.
Usage
In Motif 1.2, a compound string is composed of one or more segments, where
each segment can contain a font list element tag, a string direction, and a text
component. In Motif 2.0 and later, the set of available segments is extended to
include, amongst other items, tab, rendition, direction, locale components.
XmStringEmpty() is one of a number of routines that allow an application to
manipulate compound strings as it would regular character strings.
See Also
XmStringLength(1), XmStringLineCount(1).
370
Motif Reference Manual
Motif Functions and Macros
XmStringExtent
Name
XmStringExtent – get the smallest rectangle that contains a compound string.
Synopsis
void XmStringExtent (XmFontList fontlist, XmString string, Dimension *width,
Dimension *height)
Inputs
fontlist
string
Specifies the font list for the compound string.
Specifies the compound string.
Outputs
width
height
Returns the width of the containing rectangle.
Returns the height of the containing rectangle.
Availability
In Motif 2.0 and later, the XmFontList is obsolete, and is replaced by the
XmRenderTable, to which it is an alias.
Description
XmStringExtent() calculates the size of the smallest rectangle that can
enclose the specified compound string and returns the width and height of the
rectangle in pixels. If string is created with XmStringCreateSimple(), then
fontlist must begin with the font from the character set of the current language
environment, otherwise the result is undefined.
Usage
In Motif 1.2, a compound string is composed of one or more segments, where
each segment can contain a font list element tag, a string direction, and a text
component. In Motif 2.0 and later, the set of available segments is extended to
include, amongst other items, tab, rendition, direction, locale components.
XmStringExtent() provides information that is useful if you need to render a
compound string. Motif widgets render compound string automatically, so you
only need to worry about rendering them yourself if you are writing your own
widget. The routine is also useful if you want to get the dimensions of a compound string rendered with a particular font.
See Also
XmStringBaseline(1), XmStringHeight(1), XmStringWidth(1),
XmRendition(2).
Motif Reference Manual
371
XmStringFree
Motif Functions and Macros
Name
XmStringFree – free the memory used by a compound string.
Synopsis
void XmStringFree (XmString string)
Inputs
string
Specifies the compound string.
Description
XmStringFree() frees the memory used by the specified compound string.
Usage
In Motif 1.2, a compound string is composed of one or more segments, where
each segment can contain a font list element tag, a string direction, and a text
component. In Motif 2.0 and later, the set of available segments is extended to
include, amongst other items, tab, rendition, direction, locale components. All of
the routines that return a compound string allocate memory for the string. An
application is responsible for this storage; XmStringFree() provides a way to
free the memory.
When XtGetValues() is called for a resource that contains an XmString, a
copy of the compound string is returned. The allocated storage is again the
responsibility of the application and can be freed using XmStringFree().
Example
The following code fragment shows the use of XmStringFree():
Widget
XmString
char
toplevel, rowcol, pb;
str;
*text;
rowcol = XtVaCreateWidget ("rowcol", xmRowColumnWidgetClass, toplevel,
NULL);
str = XmStringCreateLocalized ("Testing, testing...");
pb = XtVaCreateManagedWidget ("pb", xmPushButtonWidgetClass, rowcol,
XmNlabelString, str, NULL);
XmStringFree (str);
...
XtVaGetValues (pb, XmNlabelString, &str, NULL);
text = (char *) XmStringUnparse (str, NULL,
XmCHARSET_TEXT,
XmCHARSET_TEXT,
NULL, 0, XmOUTPUT_ALL)1;
372
Motif Reference Manual
Motif Functions and Macros
XmStringFree
printf ("PushButton’s label is %s\n", text);
XmStringFree (str);
XtFree (text);
See Also
XmStringCreate(1), XmStringCreateLocalized(1),
XmStringCreateLtoR(1), XmStringCreateSimple(1),
XmStringDirectionCreate(1), XmStringSegmentCreate(1),
XmStringSeparatorCreate(1).
1.Erroneously given as XmStringGetLtoR() in 2nd edition. XmStringGetLtoR() is deprecated from Motif 2.0 onwards.
Motif Reference Manual
373
XmStringFreeContext
Motif Functions and Macros
Name
XmStringFreeContext – free a string context.
Synopsis
void XmStringFreeContext (XmStringContext context)
Inputs
context
Specifies the string context that is to be freed.
Description
XmStringFreeContext() deallocates the string context structure specified
by context.
Usage
The XmString type is opaque, so if an application needs to perform any processing on a compound string, it has to use special functions to cycle through the
string. These routines use a XmStringContext to maintain an arbitrary position in
a compound string. XmStringFreeContext() is the last of the string context routines that an application should call when processing a compound string, as it
frees the string context data structure. An application begins by calling
XmStringInitContext() to create a string context and then makes repeated calls to
either XmStringGetNextComponent() or XmStringGetNextSegment() to cycle
through the compound string.
The most common use of these routines is in converting a compound string to a
regular character string when the compound string uses multiple fontlist element
tags or it has a right-to-left orientation.
Example
The following code fragment shows how to convert a compound string into a
character string:
XmString
XmStringContext
char
XmStringCharSet
XmStringDirection
Boolean
str;
context;
*text, buf[128], *p;
tag;
direction;
separator;
XtVaGetValues (widget, XmNlabelString, &str, NULL);
if (!XmStringInitContext (&context, str)) {
XmStringFree (str);
XtWarning ("Can’t convert compound string.");
return;
374
Motif Reference Manual
Motif Functions and Macros
XmStringFreeContext
}
/* p keeps a running pointer thru buf as text is read */ p = buf;
while (XmStringGetNextSegment (context, &text, &tag, &direction, &separator)) {
/* copy text into p and advance to the end of the string */
p += (strlen (strcpy (p, text)));
if (separator == True) {
/* if there’s a separator... */
*p++ = ’\n’;
*p = 0; /* add newline and null-terminate */
}
XtFree (text); /* we’re done with the text; free it */
}
XmStringFreeContext (context);
XmStringFree (str);
printf ("Compound string:\n%s\n", buf);
See Also
XmStringInitContext(1), XmStringGetNextSegment(1),
XmStringGetNextComponent(1),
XmStringPeekNextComponent(1).
Motif Reference Manual
375
XmStringGenerate
Motif Functions and Macros
Name
XmStringGenerate – generate a compound string.
Synopsis
XmString XmStringGenerate ( XtPointer
XmStringTag
XmTextType
XmStringTag
Inputs
text
tag
type
rendition
text,
tag,
type,
rendition)
Specifies the data forming the value of the compound string.
Specifies the tag used in creating the compound string.
Specifies the type of text.
Specifies a rendition tag.
Returns
A new compound string.
Availability
Motif 2.0 and later.
Description
XmStringGenerate() is a convenience function which invokes XmStringParseText() using a default parse table in order to convert text into a compound string. The default parse table maps tab characters to
XmSTRING_COMPONENT_TAB, and newline characters to
XmSTRING_COMPONENT_SEPARATOR components of the compound
string. If a rendition tag is specified, the resulting compound string is placed
within matching components of type XmSTRING_RENDITION_BEGIN and
XmSTRING_RENDITION_END which contain the rendition. The type of the
input text is specified by type, and is one of XmCHARSET_TEXT,
XmWIDECHAR_TEXT, or XmMULTIBYTE_TEXT. type also specifies the
type of the tag which is used in creating the compound string. If tag is NULL
and the input text is of type XmCHARSET_TEXT, then the compound string is
created with the tag set to XmFONTLIST_DEFAULT_TAG. If tag is NULL and
the input text is of type XmWIDECHAR_TEXT or XmMULTIBYTE_TEXT,
then the tag used is constructed from the value of
_MOTIF_DEFAULT_LOCALE.
Usage
The function returns allocated storage, and it is the responsibility of the programmer to reclaim the space by calling XmStringFree() at an appropriate point.
376
Motif Reference Manual
Motif Functions and Macros
XmStringGenerate
In Motif 2.0 and later, in common with other objects, the compound string is
manipulated as a reference counted data structure. XmString functions prior to
Motif 2.0 handle ASN.1 strings, and the data structures are only used internally.
Example
The following code converts data taken from a Text widget into a compound
string:
XmString convert_text (Widget text)
{
/* ignoring widechar text values */
char
*value = XmTextGetString (text);
XmString xms = (XmString) 0;
if (value) {
xms = XmStringGenerate ((XtPointer) value,
XmFONTLIST_DEFAULT_TAG,
XmCHARSET_TEXT, NULL);
XtFree (value);
}
/* caller must free this */
return xms;
}
See Also
XmStringFree(1), XmStringPutRendition(1), XmRendition(2).
Motif Reference Manual
377
XmStringGetLtoR
Motif Functions and Macros
Name
XmStringGetLtoR – get a text segment from a compound string.
Synopsis
Boolean XmStringGetLtoR (XmString string, XmStringCharSet tag, char **text)
Inputs
string
tag
Specifies the compound string.
Specifies the font list element tag.
Outputs
text
Returns the NULL-terminated character string.
Returns
True if there is a matching text segment or False otherwise.
Availability
In Motif 2.0 and later, the function is obsolete, and is replaced by XmStringUnparse().
Description
XmStringGetLtoR() looks for a text segment in string that matches the font
list element tag specified by tag. tag can have the value
XmFONTLIST_DEFAULT_TAG, which identifies a locale-encoded text segment. The routine returns True if a text segment is found. text returns a pointer to
the NULL-terminated character string that contains the text from the segment.
Storage for the returned character string is allocated by the routine and should be
freed by calling XtFree(). Management of the allocated memory is the responsibility of the application.
Usage
In Motif 1.2, a compound string is composed of one or more segments, where
each segment can contain a font list element tag, a string direction, and a text
component. In Motif 2.0 and later, the set of available segments is extended to
include, amongst other items, tab, rendition, direction, locale components.
XmStringGetLtoR() allows you to retrieve a character string from a compound string, so that you can use the string with the standard C string manipulation functions.
In Motif 1.1, compound strings use character set identifiers rather than font list
element tags. The character set identifier for a compound string can have the
value XmSTRING_DEFAULT_CHARSET, which takes the character set from
the current language environment, but this value may be removed from future
versions of Motif.
378
Motif Reference Manual
Motif Functions and Macros
XmStringGetLtoR
XmStringGetLtoR() gets the first text segment from the compound string that
is associated with the specified tag. If the string contains multiple font list element tags, you must cycle through the compound string and retrieve each segment individually in order to retrieve the entire string. The routine only gets
strings with a left-to-right orientation.
See Also
XmStringCreate(1), XmStringCreateLtoR(1),
XmStringGetNextSegment(1), XmStringUnparse(1).
Motif Reference Manual
379
XmStringGetNextComponent
Motif Functions and Macros
Name
XmStringGetNextComponent – retrieves information about the next compound
string
component.
Synopsis
XmStringComponentType
XmStringGetNextComponent ( XmStringContext
char
XmStringCharSet
XmStringDirection
XmStringComponentType
unsigned short
*unknown_length,
unsigned char
**unknown_value)
context,
**text,
*tag,
*direction,
*unknown_tag,
Inputs
context
Specifies the string context for the compound string.
Outputs
text
tag
direction
unknown_tag
unknown_length
unknown_value
Returns the NULL-terminated string for a text component.
Returns the font list element tag for a tag component.
Returns the string direction for a direction component.
Returns the tag of an unknown component.
Returns the length of an unknown component.
Returns the value of an unknown component.
Returns
The type of the compound string component. The type is one of the values
described below.
Availability
In Motif 2.0 and later, XmStringGetNextComponent() is obsolete, and is
replaced by XmStringGetNextTriple().
Description
XmStringGetNextComponent() reads the next component in the compound
string specified by context and returns the type of component found. The return
value indicates which, if any, of the output parameters are valid. Storage for the
returned values is allocated by the routine and must be freed by the application
using XtFree().
For the type XmSTRING_COMPONENT_FONTLIST_ELEMENT_TAG, the
font list element tag is returned in tag. In Motif 2.0 and later, the type
380
Motif Reference Manual
Motif Functions and Macros
XmStringGetNextComponent
XmSTRING_COMPONENT_CHARSET is obsolete and is retained for compatibility with Motif 1.2. The type indicates that the character set identifier is
returned in tag. XmSTRING_COMPONENT_FONTLIST_ELEMENT_TAG
replaces XmSTRING_COMPONENT_CHARSET.
For the string component types XmSTRING_COMPONENT_TEXT and
XmSTRING_COMPONENT_LOCALE_TEXT, the text string is returned in
text. For XmSTRING_COMPONENT_DIRECTION, the direction is returned in
direction. Only one of tag, text, and direction can be valid at any one time.
The type XmSTRING_COMPONENT_SEPARATOR indicates that the next
component is a separator, while XmSTRING_COMPONENT_END specifies the
end of the compound string. For type
XmSTRING_COMPONENT_UNKNOWN, the tag, length, and value of the
unknown component are returned in the corresponding arguments.
Usage
The XmString type is opaque, so if an application needs to perform any processing on a compound string, it has to use special functions to cycle through the
string. These routines use a XmStringContext to maintain an arbitrary position in
a compound string. XmStringInitContext() is called first to create the
string context. XmStringGetNextComponent() cycles through the components in the compound string. When an application is done processing the string,
it should call XmStringFreeContext() with the same context to free the
allocated data.
Structures
A XmStringComponentType can have one of the following values:
XmSTRING_COMPONENT_CHARSET
XmSTRING_COMPONENT_TEXT
XmSTRING_COMPONENT_LOCALE_TEXT
XmSTRING_COMPONENT_DIRECTION
XmSTRING_COMPONENT_SEPARATOR
XmSTRING_COMPONENT_END
XmSTRING_COMPONENT_UNKNOWN
In Motif 2.0 and later, the following additional types are defined:
XmSTRING_COMPONENT_FONTLIST_ELEMENT_TAG
XmSTRING_COMPONENT_WIDECHAR_TEXT
XmSTRING_COMPONENT_LAYOUT_PUSH
XmSTRING_COMPONENT_LAYOUT_POP
XmSTRING_COMPONENT_RENDITION_BEGIN
XmSTRING_COMPONENT_RENDITION_END
Motif Reference Manual
381
XmStringGetNextComponent
Motif Functions and Macros
See Also
XmStringFreeContext(1), XmStringGetNextTriple(1),
XmStringGetNextSegment(1), XmStringInitContext(1),
XmStringPeekNextComponent(1).
382
Motif Reference Manual
Motif Functions and Macros
XmStringGetNextSegment
Name
XmStringGetNextSegment – retrieves information about the next compound
string segment.
Synopsis
Boolean XmStringGetNextSegment (
XmStringContext
char
XmStringCharSet
XmStringDirection
Boolean
context,
**text,
*charset,
*direction,
*separator)
Inputs
context
Specifies the string context for the compound string.
Outputs
text
tag
direction
separator
Returns the NULL-terminated string for the segment.
Returns the font list element tag for the segment.
Returns the string direction for the segment.
Returns whether or not the next component is a separator.
Returns
True if a valid segment is located or False otherwise.
Availability
In Motif 2.0 and later, the function is obsolete, and is replaced by
XmStringGetNextTriple().
Description
XmStringGetNextSegment() retrieves the text string, font list element tag,
and direction for the next segment of the compound string specified by context.
The routine returns True if a valid segment is retrieved; otherwise, it returns
False. Storage for the returned text is allocated by the routine and must be freed
by the application using XtFree().
Usage
The XmString type is opaque, so if an application needs to perform any processing on a compound string, it has to use special functions to cycle through the
string. These routines use a XmStringContext to maintain an arbitrary position in
a compound string. XmStringInitContext() is called first to create the
string context. XmStringGetNextSegment() cycles through the segments
in the compound string. The Boolean separator can be used to determine whether
or not the next component in the compound string is a separator. When an application is done processing the string, it should call XmStringFreeContext()
with the same context to free the allocated data.
Motif Reference Manual
383
XmStringGetNextSegment
Motif Functions and Macros
The most common use of these routines is in converting a compound string to a
regular character string when the compound string uses multiple fontlist element
tags or it has a right-to-left orientation.
See Also
XmStringFreeContext(1), XmStringGetLtoR(1),
XmStringGetNextComponent(1), XmStringGetNextTriple(1),
XmStringInitContext(1), XmStringPeekNextComponent(1),
XmStringPeekNextTriple(1).
384
Motif Reference Manual
Motif Functions and Macros
XmStringGetNextTriple
Name
XmStringGetNextTriple – retrieve information about the next component.
Synopsis
XmStringComponentType
XmStringGetNextTriple (XmStringContext context, unsigned int *length,
XtPointer *value)
Inputs
context
Specifies the string context for the compound string.
Outputs
length
value
Returns the length of the value of the component.
Returns the value of the component.
Returns
The type of the component.
Availability
Motif 2.0 and later.
Description
XmStringGetNextTriple() is a convenience function which returns the type,
length, and value of the next component within the compound string associated with
context. The context is an opaque structure used for walking along compound strings
one component at a time, and is initialized through a call to
XmStringInitContext().
Usage
If either of value or length are NULL pointers, the function immediately returns
XmSTRING_COMPONENT_END without fetching the next string segment.
Otherwise, value is initially set to point to NULL, and length is reset to zero, and
the next segment is processed. The function allocates memory for the returned
value, which should be reclaimed at an appropriate point by calling XtFree().
Structures
An XmStringComponentType can have one of the following values:
XmSTRING_COMPONENT_CHARSET
XmSTRING_COMPONENT_TEXT
XmSTRING_COMPONENT_LOCALE_TEXT
XmSTRING_COMPONENT_DIRECTION
XmSTRING_COMPONENT_SEPARATOR
XmSTRING_COMPONENT_END
XmSTRING_COMPONENT_UNKNOWN
Motif Reference Manual
385
XmStringGetNextTriple
Motif Functions and Macros
In Motif 2.0 and later, the following additional types are defined:
XmSTRING_COMPONENT_FONTLIST_ELEMENT_TAG
XmSTRING_COMPONENT_WIDECHAR_TEXT
XmSTRING_COMPONENT_LAYOUT_PUSH
XmSTRING_COMPONENT_LAYOUT_POP
XmSTRING_COMPONENT_RENDITION_BEGIN
XmSTRING_COMPONENT_RENDITION_END
Example
The following code fragment shows how to convert a compound string into a
character string:
XmString
XmStringContext
char
XmStringComponentType
unsigned int
str;
context;
*text, buf[128], *p;
type;
len;
/* Fetch the Compound String from somewhere */
XtVaGetValues (widget, XmNlabelString, &str, NULL);
if (!XmStringInitContext (&context, str)) {
XmStringFree (str);
XtWarning ("Can’t convert compound string.");
return;
}
/* p keeps a running pointer through buf as text is read */
p = buf;
/* Ignoring locale or widechar text for simplicity */
while ((type = XmStringGetNextTriple (context, &len, &text)) !=
XmSTRING_COMPONENT_END)
{
switch (type) {
case XmSTRING_COMPONENT_TAB
:
*p++ = ’\t’;
break;
case XmSTRING_COMPONENT_SEPARATOR
:
*p++ = ’\n’;
*p = ’\0’;
break;
case XmSTRING_COMPONENT_TEXT
:
(void) strcpy (p, text);
386
Motif Reference Manual
Motif Functions and Macros
XmStringGetNextTriple
p += len;
break;
}
XtFree (text);
}
XmStringFreeContext (context);
XmStringFree (str);
printf ("Compound string:\n%s\n", buf);
See Also
XmStringFreeContext(1), XmStringGetNextComponent(1),
XmStringGetNextSegment(1), XmStringInitContext(1),
XmStringPeekNextComponent(1), XmStringPeekNextTriple(1).
Motif Reference Manual
387
XmStringHasSubstring
Motif Functions and Macros
Name
XmStringHasSubstring – determine whether a compound string contains a substring.
Synopsis
Boolean XmStringHasSubstring (XmString string, XmString substring)
Inputs
string
substring
Specifies the compound string.
Specifies the substring.
Returns
True if string contains substring or False otherwise.
Description
XmStringHasSubstring() determines whether the compound string substring is contained within any single segment of the compound string string. substring must have only a single segment. The routine returns True if the string
contains the substring and False otherwise.
If two compound strings are created with XmStringCreateLocalized() in
the same language environment and they satisfy the above condition,
XmStringHasSubstring() returns True. If two strings are created with
XmStringCreate() using the same character set and they satisfy the condition, the routine also returns True. When comparing a compound string created
by XmStringCreate() with a compound string created by XmStringCreateSimple() the result is undefined.
Usage
In Motif 1.2, a compound string is composed of one or more segments, where
each segment can contain a font list element tag, a string direction, and a text
component. In Motif 2.0 and later, the set of available segments is extended to
include, amongst other items, tab, rendition, direction, locale components.
XmStringHasSubstring() is one of a number of routines that allow an
application to manipulate compound strings as it would regular character strings.
See Also
XmStringEmpty(1), XmStringLength(1), XmStringLineCount(1).
388
Motif Reference Manual
Motif Functions and Macros
XmStringHeight
Name
XmStringHeight – get the line height of a compound string.
Synopsis
Dimension XmStringHeight (XmFontList fontlist, XmString string)
Inputs
fontlist
string
Specifies the font list for the compound string.
Specifies the compound string.
Returns
The height of the compound string.
Availability
In Motif 2.0 and later, the XmFontList is obsolete, and is replaced by the
XmRenderTable, to which it is an alias.
Description
XmStringHeight() returns the height, in pixels, of the specified compound
string. If string contains multiple lines, where a separator component delimits
each line, then the total height of all of the lines is returned. If string is created
with XmStringCreateSimple(), then fontlist must begin with the font from
the character set of the current language environment, otherwise the result is
undefined.
Usage
In Motif 1.2, a compound string is composed of one or more segments, where
each segment can contain a font list element tag, a string direction, and a text
component. In Motif 2.0 and later, the set of available segments is extended to
include, amongst other items, tab, rendition, direction, locale components.
XmStringHeight() provides information that is useful if you need to render a
compound string. Motif widgets render compound string automatically, so you
only need to worry about rendering them yourself if you are writing your own
widget. The routine is also useful if you want to get the dimensions of a compound string rendered with a particular font.
See Also
XmStringBaseline(1), XmStringExtent(1), XmStringWidth(1),
XmRendition(2).
Motif Reference Manual
389
XmStringInitContext
Motif Functions and Macros
Name
XmStringInitContext – create a string context.
Synopsis
Boolean XmStringInitContext (XmStringContext *context, XmString string)
Inputs
string
Specifies the compound string.
Outputs
context
Returns the allocated string context structure.
Returns
True if the string context is allocated or False otherwise.
Description
XmStringInitContext() creates a string context for the specified compound string. This string context allows an application to access the contents of a
compound string.
Usage
The XmString type is opaque, so if an application needs to perform any processing on a compound string, it has to use special functions to cycle through the
string. These routines use a XmStringContext to maintain an arbitrary position in
a compound string. XmStringInitContext() is the first of the three string
context routines that an application should call when processing a compound
string, as it creates the string context data structure. The context is passed to
XmStringGetNextTriple() to cycle through the compound string. When an
application is done processing the string, it should call XmStringFreeContext() with the same context to free the allocated data.
The most common use of these routines is in converting a compound string to a
regular character string when the compound string uses multiple fontlist element
tags or it has a right-to-left orientation.
Example
The following code fragment shows how to convert a compound string into a
character string:
XmString
XmStringContext
char
XmStringComponentType
unsigned int
str;
context;
*text, buf[128], *p;
type;
len;
/* Fetch the Compound String from somewhere */
390
Motif Reference Manual
Motif Functions and Macros
XmStringInitContext
XtVaGetValues (widget, XmNlabelString, &str, NULL);
if (!XmStringInitContext (&context, str)) {
XmStringFree (str);
XtWarning ("Can’t convert compound string.");
return;
}
/* p keeps a running pointer through buf as text is read */
p = buf;
/* Ignoring locale or widechar text for simplicity */
while ((type = XmStringGetNextTriple (context, &len, &text)) !=
XmSTRING_COMPONENT_END)
{
switch (type) {
case XmSTRING_COMPONENT_TAB
:
*p++ = ’\t’;
break;
case XmSTRING_COMPONENT_SEPARATOR
:
*p++ = ’\n’;
*p = ’\0’;
break;
case XmSTRING_COMPONENT_TEXT
:
(void) strcpy (p, text);
p += len;
break;
}
XtFree (text);
}
XmStringFreeContext (context);
XmStringFree (str);
printf ("Compound string:\n%s\n", buf);
See Also
XmStringFreeContext(1), XmStringGetNextComponent(1),
XmStringGetNextTriple(1), XmStringGetNextSegment(1),
XmStringPeekNextComponent(1), XmStringPeekNextTriple(1).
Motif Reference Manual
391
XmStringIsVoid
Motif Functions and Macros
Name
XmStringIsVoid – determine whether there are valid segments in a compound
string.
Synopsis
Boolean XmStringIsVoid (XmString string)
Inputs
string
Specifies a compound string.
Returns
True if there are no segments in the string or False otherwise.
Availability
XmStringIsVoid() is available from Motif 2.0 or later.
Description
XmStringIsVoid() checks to see whether there any text, tab, or separator segments within the specified string. If the routine is passed NULL, it returns True.
If the string contains text, tab or separator components, it returns False. Otherwise, it returns True.
Usage
In Motif 1.2, a compound string is composed of one or more segments, where
each segment can contain a font list element tag, a string direction, and a text
component. In Motif 2.0 and later, the set of available segments is extended to
include, amongst other items, tab, rendition, direction, and locale components.
See Also
XmStringEmpty(1), XmStringLength(1), XmStringLineCount(1).
392
Motif Reference Manual
Motif Functions and Macros
XmStringLength
Name
XmStringLength – get the length of a compound string.
Synopsis
int XmStringLength (XmString string)
Inputs
string
Specifies the compound string.
Returns
The length of the compound string.
Availability
In Motif 2.0 and later, the function is obsolete, and is replaced by XmStringByteStreamLength().
Description
XmStringLength() returns the length, in bytes, of the specified compound
string. The calculation includes the length of all tags, direction indicators, and
separators. The routine returns 0 (zero) if the structure of string is invalid.
Usage
In Motif 1.2, a compound string is composed of one or more segments, where
each segment can contain a font list element tag, a string direction, and a text
component. In Motif 2.0 and later, the set of available segments is extended to
include, amongst other items, tab, rendition, direction, locale components.
XmStringLength() is one of a number of routines that allow an application to
manipulate compound strings as it would regular character strings. However, this
routine cannot be used to get the length of the text represented by the compound
string; it is not the same as strlen().
See Also
XmStringByteStreamLength(1), XmStringEmpty(1),
XmStringLineCount(1).
Motif Reference Manual
393
XmStringLineCount
Motif Functions and Macros
Name
XmStringLineCount – get the number of lines in a compound string.
Synopsis
int XmStringLineCount (XmString string)
Inputs
string
Specifies the compound string.
Returns
The number of lines in the compound string.
Description
XmStringLineCount() returns the number of lines in the specified compound
string. The line count is determined by adding 1 to the number of separators in
the string.
Usage
In Motif 1.2 and later, a compound string is composed of one or more segments,
where each segment can contain a font list element tag, a string direction, and a
text component. In Motif 2.0 and later, the set of available segments is extended
to include, amongst other items, tab, rendition, direction, locale components.
XmStringLineCount() provides information that is useful in laying out components that display compound strings.
Example
The following routine shows how to read the contents of a file into a buffer and
then convert the buffer into a compound string. The routine also returns the
number of lines in the compound string:
XmString ConvertFileToXmString (char *filename, int *lines)
{
struct stat
statb;
int
fd, len, lines;
char
*text;
XmString str;
*lines = 0;
if ((fd = open (filename, O_RDONLY)) < 0) {
XtWarning ("internal error -- can’t open file");
return (XmString) 0;
}
if ((fstat (fd, &statb) == -1) || !(text = XtMalloc ((len = statb.st_size) + 1))) {
XtWarning("internal error -- can’t show text");
394
Motif Reference Manual
Motif Functions and Macros
XmStringLineCount
(void) close (fd);
return (XmString) 0;
}
(void) read (fd, text, len);
text[len] = ‘\0’;
str = XmStringGenerate ((XtPointer) text, XmFONTLIST_DEFAULT_TAG,
XmCHARSET_TEXT, NULL);1
XtFree (text);
(void) close (fd);
*lines = XmStringLineCount (str);
return str;
}
See Also
XmStringEmpty(1), XmStringLength(1).
1.Erroneously given as XmStringCreateLtoR() in 2nd edition. XmStringCreateLtoR() is deprecated from Motif 2.0 onwards.
Motif Reference Manual
395
XmStringNConcat
Motif Functions and Macros
Name
XmStringNConcat – concatenate a specified portion of a compound string to
another compound string.
Synopsis
XmString XmStringNConcat (XmString string1, XmString string2, int
num_bytes)
Inputs
string1
string2
num_bytes
Specifies a compound string.
Specifies the compound string that is appended.
Specifies the number of bytes of string2 that are appended.
Returns
A new compound string.
Availability
In Motif 2.0 and later, the function is obsolete, and is only maintained for backwards compatibility.
Description
XmStringNConcat() returns the compound string formed by appending bytes
from string2 to the end of string1, leaving the original compound strings
unchanged. num_bytes of string are appended, which includes tags, directional
indicators, and separators. Storage for the result is allocated within this routine
and should be freed by calling XmStringFree(). Management of the allocated
memory is the responsibility of the application.
If num_bytes is less than the length of string2, the resulting string could be
invalid. In this case, XmStringNConcat() appends as many bytes as possible,
up to a maximum of num_bytes, to ensure the creation of a valid string.
Usage
In Motif 1.2, a compound string is composed of one or more segments, where
each segment can contain a font list element tag, a string direction, and a text
component. In Motif 2.0 and later, the set of available segments is extended to
include, amongst other items, tab, rendition, direction, locale components.
XmStringNConcat() is one of a number of routines that allow an application
to manipulate compound strings as it would regular character strings.
See Also
XmStringConcat(1), XmStringCopy(1), XmStringNCopy(1).
396
Motif Reference Manual
Motif Functions and Macros
XmStringNCopy
Name
XmStringNCopy – copy a specified portion of a compound string.
Synopsis
XmString XmStringNCopy (XmString string, int num_bytes)
Inputs
string
num_bytes
Specifies a compound string.
Specifies the number of bytes of string that are copied.
Returns
A new compound string.
Availability
In Motif 2.0 and later, the function is obsolete, and is only maintained for backwards compatibility.
Description
XmStringNCopy() copies num_bytes bytes from the compound string string
and returns the resulting copy, leaving the original string unchanged. The number
of bytes copied includes tags, directional indicators, and separators. Storage for
the result is allocated within this routine and should be freed by calling
XmStringFree(). Management of the allocated memory is the responsibility
of the application.
If num_bytes is less than the length of string, the resulting string could be invalid.
In this case, XmStringNCopy() copies as many bytes as possible, up to a maximum of num_bytes to ensure the creation of a valid string.
Usage
In Motif 1.2, a compound string is composed of one or more segments, where
each segment can contain a font list element tag, a string direction, and a text
component. In Motif 2.0 and later, the set of available segments is extended to
include, amongst other items, tab, rendition, direction, locale components.
XmStringNCopy() is one of a number of routines that allow an application to
manipulate compound strings as it would regular character strings.
See Also
XmStringConcat(1), XmStringCopy(1), XmStringNConcat(1).
Motif Reference Manual
397
XmStringParseText
Motif Functions and Macros
Name
XmStringParseText – convert a string to a compound string.
Synopsis
XmString XmStringParseText ( XtPointer
XtPointer
XmStringTag
XmTextType
XmParseTable
Cardinal
XtPointer
text,
*text_end,
tag,
type,
parse_table,
parse_count,
client_data)
Inputs
text
Specifies a string to be converted.
text_end
Specifies a pointer into text where parsing is to finish.
tag
Specifies the tag to be used in creating the compound string.
type
Specifies the type of the text and the tag.
parse_table
Specifies a table used for matching characters in the input text.
parse_count
Specifies the number of items in the parse_table.
client_data
Specifies application data to pass to any parse procedures
within the parse_table.
Outputs
text_end
Returns a location within the text where parsing finished.
Returns
The converted compound string.
Availability
Motif 2.0 and later.
Description
XmStringParseText() converts the string specified by text into a compound
string. A parse_table can be specified which consists of a set of mappings to control the conversion process. The contents of the string to be converted can be in
one of a number of formats: simple characters, multibyte, or wide characters. The
type parameter specifies the type of the input text, and is also used to interpret the
tag which is used in creating text components within the returned compound
string. text_end is both an input and an output parameter: as an input parameter, it
specifies a location within text where parsing is to terminate; as an output parameter, it points to a location within text where parsing actually finished. Supplying
NULL for text_end is interpreted to mean that parsing should stop at the occurrence of a null byte.
398
Motif Reference Manual
Motif Functions and Macros
XmStringParseText
Usage
If type is XmCHARSET_TEXT, the input text is assumed to consist of a simple
array of characters, and the tag is interpreted as the name of a charset to use in
constructing the returned compound string. If tag is NULL, a default charset
using XmFONTLIST_DEFAULT_TAG is used.
If the type is XmMULTIBYTE_TEXT or XmWIDECHAR_TEXT, the input text
is assumed to be in multibyte or widechar text format respectively, and the tag is
interpreted as a locale specifier. The tag should either be specified as NULL or
_MOTIF_DEFAULT_LOCALE: if NULL, a locale component with a value of
_MOTIF_DEFAULT_LOCALE is created in any case.
A parse table can be specified for controlling the conversion process. A parse
table consists of a set of XmParseMapping objects, which have match pattern,
substitution pattern and parse procedure components. The head of the input
stream is compared against elements within the parse table, and if there is a correspondence between the input and a parse mapping match pattern, the parse
mapping object is used to construct the output compound string at that point in
the conversion, either by directly inserting the substitution pattern, or by invoking
the parse procedure of the mapping object. The parse mapping specifies how the
input pointer is advanced, and the process is repeated, comparing the head of the
input against the parse table. At the end of the conversion, the text_end parameter
is set to point to the location within the input text where parsing actually terminated. Depending upon the way in which the parse table interacts with the input
text, the returned text_end may not be the same location which the programmer
specified if more or less of the input text is consumed.
An implicit automatic conversion takes place where there is no matching parse
mapping object for the head of the input. In other words, it is not necessary to
provide a parse table to convert everything: parse tables are only required where
specific inputs need to be handled specially. XmStringParseText() uses an
internal parse mapping which handles changes in string direction in the absence
of a supplied mapping for the task. A parse mapping handles string direction
changes if the XmNpattern resource of the object is equal to
XmDIRECTION_CHANGE.
XmStringParseText() allocates memory for the returned compound string.
It is the responsibility of the programmer to reclaim the space through a call to
XmStringFree() at an appropriate point.
Motif Reference Manual
399
XmStringParseText
Motif Functions and Macros
Example
The following specimen code converts an input string containing tab and newline
characters into a compound string:
XmParseTable parse_table = (XmParseTable) XtCalloc (2, sizeof
(XmParseMapping));
XmString
tmp;
XmString
output;
Arg
av[4];
Cardinal
ac;
/* map \t to a tab component */
tmp = XmStringComponentCreate (XmSTRING_COMPONENT_TAB, 0,
NULL);
ac = 0;
XtSetArg (av[ac], XmNincludeStatus,
XmINSERT);
ac++;
XtSetArg (av[ac], XmNsubstitute,
tmp);
ac++;
XtSetArg (av[ac], XmNpattern,
"\t");
ac++;
parse_table[0] = XmParseMappingCreate (av, ac);
XmStringFree (tmp);
/* map \n to a separator component */
tmp = XmStringSeparatorCreate();
ac = 0;
XtSetArg (av[ac], XmNincludeStatus,
XmINSERT);
XtSetArg (av[ac], XmNsubstitute,
tmp);
XtSetArg (av[ac], XmNpattern,
"\n");
parse_table[1] = XmParseMappingCreate (av, ac);
XmStringFree (tmp);
ac++;
ac++;
ac++;
/* convert the (unspecified) input string into a compound string *
output = XmStringParseText (input, NULL, NULL, XmCHARSET_TEXT,
parse_table, 2, NULL);
XmParseTableFree (parse_table);
See Also
XmStringFree(1), XmStringGenerate(1), XmStringUnparse(1).
XmParseMapping(2).
400
Motif Reference Manual
Motif Functions and Macros
XmStringPeekNextComponent
Name
XmStringPeekNextComponent – returns the type of the next compound string
component.
Synopsis
XmStringComponentType XmStringPeekNextComponent (XmStringContext
context)
Inputs
context
Specifies the string context for the compound string.
Returns
The type of the compound string component. The type is one of the values
described below.
Availability
In Motif 2.0 and later, the function is obsolete, and XmStringPeekNextTriple() is preferred.
Description
XmStringPeekNextComponent() checks the next component in the compound string specified by context and returns the type of the component found.
The routine shows what would be returned by a call to XmStringGetNextComponent(), without actually updating context.
The returned type XmSTRING_COMPONENT_FONTLIST_ELEMENT_TAG
indicates that the next component is a font list element tag. In Motif 1.2, the type
XmSTRING_COMPONENT_-CHARSET is obsolete and is retained for compatibility with Motif 1.1. The type indicates that the next component is a character
set identifier. XmSTRING_COMPONENT_FONTLIST_ELEMENT_TAG
replaces XmSTRING_COMPONENT_CHARSET.
The types XmSTRING_COMPONENT_TEXT and
XmSTRING_COMPONENT_LOCALE_TEXT specify that the next component
is text. XmSTRING_COMPONENT_DIRECTION indicates that the next component is a string direction component.
The type XmSTRING_COMPONENT_SEPARATOR indicates that the next
component is a separator, while XmSTRING_COMPONENT_END specifies the
end of the compound string. The type
XmSTRING_COMPONENT_UNKNOWN, indicates that the type of the next
component is unknown.
Motif Reference Manual
401
XmStringPeekNextComponent
Motif Functions and Macros
Usage
The XmString type is opaque, so if an application needs to perform any processing on a compound string, it has to use special functions to cycle through the
string. These routines use a XmStringContext to maintain an arbitrary position in
a compound string. XmStringInitContext() is called first to create the
string context. XmStringPeekNextComponent() peeks at the next component in the compound string without cycling through the component. When an
application is done processing the string, it should call XmStringFreeContext() with the same context to free the allocated data.
Structures
A XmStringComponentType can have one of the following values:
XmSTRING_COMPONENT_CHARSET
XmSTRING_COMPONENT_TEXT
XmSTRING_COMPONENT_LOCALE_TEXT
XmSTRING_COMPONENT_DIRECTION
XmSTRING_COMPONENT_SEPARATOR
XmSTRING_COMPONENT_END
XmSTRING_COMPONENT_UNKNOWN
In Motif 2.0 and later, the following additional types are defined:
XmSTRING_COMPONENT_FONTLIST_ELEMENT_TAG
XmSTRING_COMPONENT_WIDECHAR_TEXT
XmSTRING_COMPONENT_LAYOUT_PUSH
XmSTRING_COMPONENT_LAYOUT_POP
XmSTRING_COMPONENT_RENDITION_BEGIN
XmSTRING_COMPONENT_RENDITION_END
See Also
XmStringFreeContext(1), XmStringGetNextComponent(1),
XmStringGetNextSegment(1), XmStringPeekNextTriple(1),
XmStringInitContext(1).
402
Motif Reference Manual
Motif Functions and Macros
XmStringPeekNextTriple
Name
XmStringPeekNextTriple – retrieve the type of the next component.
Synopsis
XmStringComponentType XmStringPeekNextTriple (XmStringContext context)
Inputs
context
Specifies the string context for the compound string.
Returns
The type of the next component.
Availability
Motif 2.0 and later.
Description
XmStringPeekNextTriple() returns the type of the next component without updating the compound string context.
Usage
An XmStringContext is an opaque data type which is used for walking along a
compound string one component at a time. It is initialized by a call to XmStringInitContext. Each successive call to XmStringGetNextComponent() adjusts
the string context to point to the next component. XmStringPeekNextTriple() returns the type of the next component without adjusting the context, and
thus it can be used to look ahead into the compound string.
Structures
The string component type can have one of the following values:
XmSTRING_COMPONENT_CHARSET
XmSTRING_COMPONENT_TEXT
XmSTRING_COMPONENT_LOCALE_TEXT
XmSTRING_COMPONENT_DIRECTION
XmSTRING_COMPONENT_SEPARATOR
XmSTRING_COMPONENT_END
XmSTRING_COMPONENT_UNKNOWN
XmSTRING_COMPONENT_FONTLIST_ELEMENT_TAG
XmSTRING_COMPONENT_WIDECHAR_TEXT
XmSTRING_COMPONENT_LAYOUT_PUSH
XmSTRING_COMPONENT_LAYOUT_POP
XmSTRING_COMPONENT_RENDITION_BEGIN
XmSTRING_COMPONENT_RENDITION_END
Motif Reference Manual
403
XmStringPeekNextTriple
Motif Functions and Macros
See Also
XmStringFreeContext(1), XmStringGetNextComponent(1),
XmStringGetNextSegment(1), XmStringInitContext(1),
XmStringPeekNextComponent(1).
404
Motif Reference Manual
Motif Functions and Macros
XmStringPutRendition
Name
XmStringPutRendition – add rendition components to a compound string.
Synopsis
XmString XmStringPutRendition (XmString string, XmStringTag rendition)
Inputs
string
rendition
Specifies a compound string which requires rendition components.
Specifies a tag used to create the rendition components.
Returns
A newly allocated compound string with rendition components.
Availability
Motif 2.0 and later.
Description
XmStringPutRendition() is a convenience function which places
XmSTRING_COMPONENT_RENDITION_BEGIN and
XmSTRING_COMPONENT_RENDITION_END components containing rendition around a compound string. The string is not modified by the procedure,
which takes a copy.
Usage
XmStringPutRendition() allocates space for the returned compound
string, and it is the responsibility of the programmer to reclaim the space at an
appropriate point by calling XmStringFree().
See Also
XmStringFree(1).
Motif Reference Manual
405
XmStringSegmentCreate
Motif Functions and Macros
Name
XmStringSegmentCreate – create a compound string segment.
Synopsis
XmString XmStringSegmentCreate ( char
XmStringCharSet
XmStringDirection
Boolean
Inputs
text
tag
direction
separator
*text,
tag,
direction,
separator)
Specifies the text component of the compound string segment.
Specifies the font list element tag.
Specifies the value of the direction component. Pass either
XmSTRING_DIRECTION_L_TO_R or
XmSTRING_DIRECTION_R_TO_L.
Specifies whether or not a separator is added to the compound
string.
Returns
A new compound string.
Availability
In Motif 2.0 and later, the function is deprecated. A combination of XmStringComponentCreate() and XmStringConcat() is preferred.
Description
XmStringSegmentCreate() creates a compound string segment that contains the specified text, tag, and direction. If separator is True, a separator is
added to the segment, following the text. If separator is False, the compound
string segment does not contain a separator. Storage for the returned compound
string is allocated by the routine and should be freed by calling XmStringFree(). Management of the allocated memory is the responsibility of the application.
Usage
In Motif 1.2, a compound string is composed of one or more segments, where
each segment can contain a font list element tag, a string direction, and a text
component. In Motif 2.0 and later, the set of available segments is extended to
include, amongst other items, tab, rendition, direction, locale components.
XmStringSegmentCreate() allows you to create a single segment that can
be concatenated with a compound string containing other segments.
See Also
XmStringCreate(1), XmStringFree(1).
406
Motif Reference Manual
Motif Functions and Macros
XmStringSeparatorCreate
Name
XmStringSeparatorCreate – create a compound string containing a separator
component.
Synopsis
XmString XmStringSeparatorCreate (void)
Returns
A new compound string.
Description
XmStringSeparatorCreate() creates and returns a compound string containing a separator as its only component.
Usage
In Motif 1.2, a compound string is composed of one or more segments, where
each segment can contain a font list element tag, a string direction, and a text
component. In Motif 2.0 and later, the set of available segments is extended to
include, amongst other items, tab, rendition, direction, locale components.
XmStringSeparatorCreate() allows you to create a separator component
that can be concatenated with a compound string containing other components.
See Also
XmStringCreate(1), XmStringFree(1),
XmStringSegmentCreate(1).
Motif Reference Manual
407
XmStringTableParseStringArray
Motif Functions and Macros
Name
XmStringTableParseStringArray – convert an array of strings into a compound
string table.
Synopsis
XmStringTable XmStringTableParseStringArray ( XtPointer
Cardinal
XmStringTag
XmTextType
XmParseTable
parse_table,
Cardinal
parse_count,
XtPointer
client_data)
Inputs
strings
count
tag
table.
type
parse_table
parse_count
client_data
parse_table.
*strings,
count,
tag,
type,
Specifies an array of strings.
Specifies the number of items in strings.
Specifies the tag used to create the resulting compound string
Specifies the type of each input string, and the tag.
Specifies a parse table to control the conversion process.
Specifies the number of parse mappings in parse_table.
Specifies application data to pass to parse procedures within the
Returns
An array of compound strings.
Availability
Motif 2.0 and later.
Description
XmStringTableParseStringArray() converts an array of strings into an
array of compound strings. XmStringTableParseStringArray() is no
more than a convenience function which allocates space for an table of compound strings, and subsequently calls XmStringParseText() iteratively on
each item within the strings array to convert the item into a compound string.
Each converted item is placed within the allocated table at a corresponding location to its position in the strings array. A parse_table can be specified which
consists of a set of mappings to control the conversion process. The contents of
each of the strings to be converted can be in one of a number of formats: simple
characters, multibyte, or wide characters. The type parameter specifies the type of
408
Motif Reference Manual
Motif Functions and Macros
XmStringTableParseStringArray
the input strings, and is also used to interpret the tag which is used in creating
text components within the returned compound string array.
Usage
The function calls XmStringParseText() passing NULL as the text_end
(second) parameter: each item within the array of strings is converted until the
occurrence of a terminating null byte. XmStringTableParseStringArray() returns allocated storage: the elements within the returned table are compound strings allocated by the internal call to XmStringParseText(), and
these should each be freed at an appropriate point through XmStringFree().
XmStringTableParseStringArray() also allocates space for the table
itself, and this should subsequently be freed using XtFree().
Structures
The XmTextType type parameter can take one of the following values:
XmCHARSET_TEXT
XmMULTIBYTE_TEXT
XmWIDECHAR_TEXT
See Also
XmStringFree(1), XmStringGenerate(1), XmStringParseText(1),
XmStringTableUnparse(1), XmParseMapping(2).
Motif Reference Manual
409
XmStringTableProposeTablist
Motif Functions and Macros
Name
XmStringTableProposeTablist – create a tab list for a compound string table.
Synopsis
XmTabList XmStringTableProposeTablist (
XmStringTable
Cardinal
Widget
float
XmOffsetModel
strings,
string_count,
widget,
padding,
offset_model)
Inputs
strings
string_count
widget
lated.
padding
offset_model
sets.
Specifies an array of compound strings.
Specifies the number of items in strings.
Specifies a widget from which rendition information is calcuSpecifies a separation between columns.
Specifies whether tabs are created at absolute or relative off-
Returns
A new XmTabList.
Availability
Motif 2.0 and later.
Description
XmStringTableProposeTablist() creates an XmTabList value which
can be used to specify how an array of tabbed compound strings is aligned into
columns.
A compound string is tabbed if it contains an XmSTRING_COMPONENT_TAB
component between textual components: each text component forms an individual column entry. The strings are rendered with respect to a tab list: each tab contains a floating point offset which specifies the starting location of a column.
XmStringTableProposeTablist() creates a tab list appropriate for laying
out the given strings in a multi-column format.
The XmNunitType resource of widget is used to calculate the units in which the
tab calculation is performed. Extra spacing between each column is specified by
the padding parameter, and this is also interpreted in terms of the unit type of
widget. The offset_model determines whether the floating point positions calculated for each tab in the returned XmTabList are at absolute locations (XmABSOLUTE), or relative to the previous tab (XmRELATIVE).
410
Motif Reference Manual
Motif Functions and Macros
XmStringTableProposeTablist
Usage
The tab list created by XmStringTableProposeTablist() can be applied
to the render table of the widget where the strings are to be displayed by modifying the XmNtabList resource of an existing rendition through the procedure
XmRenditionUpdate(). Alternatively, a new rendition can be created using
XmRenditionCreate(), and thereafter merged into the widget render table
using XmRenderTableAddRenditions().
XmStringTableProposeTablist() returns allocated storage, and it is the
responsibility of the programmer to reclaim the allocated space at a suitable point
by calling XmTabListFree().
If no render table is associated with widget, XmStringTableProposeTablist() invokes internal routines to deduce a default render table: these routines
are not multi-thread safe.
See Also
XmTabCreate(1), XmTabFree(1), XmTabListCopy(1),
XmTabListFree(1), XmRenderTableAddRenditions(1),
XmRenditionCreate(1), XmRenditionUpdate(1), XmRendition(2).
Motif Reference Manual
411
XmStringTableToXmString
Motif Functions and Macros
Name
XmStringTableToXmString – convert compound string table to compound string.
Synopsis
XmString
XmStringTableToXmString (XmStringTable table, Cardinal count, XmString
break_component)
Inputs
table
count
break_component
items.
Specifies an array of compound strings.
Specified the number of items in the table.
Specifies a compound string used to separate converted table
Returns
A compound string.
Availability
Motif 2.0 and later.
Description
XmStringTableToXmString() is a convenience function which converts a
table of compound strings into a single compound string. A
break_component can be inserted between each component converted from
the table in order to separate each.
Usage
XmStringTableToXmString() simply walks along the array of items within
the table, concatenating a copy of each item to the result, along with a copy of the
break_component. The break_component can be NULL, although a component
of type XmSTRING_COMPONENT_TAB or
XmSTRING_COMPONENT_SEPARATOR is a suitable choice. The function
returns allocated storage, and it is the responsibility of the programmer to reclaim
the space by calling XmStringFree() at a suitable point.
Example
The following code illustrates a basic call to XmStringTableToXmString():
extern XmString
extern int
XmString
XmString
table table ;
table_count ;
xms;
break_component;
/* create a break component */
412
Motif Reference Manual
Motif Functions and Macros
XmStringTableToXmString
break_component = XmStringComponentCreate
(XmSTRING_COMPONEN
T_SEPARATOR, 0,
NULL)1;
/* convert an (unspecified) compound string table */
xms = XmStringTableToXmString (table, table_count, break_component);
/* use the compound string */
...
/* free the allocated space */
XmStringFree (xms);
See Also
XmStringConcat(1), XmStringCopy(1), XmStringFree(1),
XmStringToXmStringTable(1).
1.Erroneously given as XmComponentCreate() in 2nd edition. XmStringSeparatorCreate() would do here equally well.
Motif Reference Manual
413
XmStringTableUnparse
Motif Functions and Macros
Name
XmStringTableUnparse – convert a compound string table to an array of strings.
Synopsis
XtPointer *XmStringTableUnparse ( XmStringTable
Cardinal
XmStringTag
XmTextType
XmTextType
XmParseTable
Cardinal
XmParseModel
Inputs
table
count
tag
tag_type
output_type
parse_table
parse_count
parse_model
table,
count,
tag,
tag_type,
output_type,
parse_table,
parse_count,
parse_model)
Specifies the compound string table to unparse.
Specifies the number of compound strings in table.
Specifies which text segments to unparse.
Specifies the type of tag.
Specifies the type of conversion required.
Specifies a parse table to control the conversion.
Specifies the number of parse mappings in parse_table.
Specifies how non-text components are converted.
Returns
An allocated string array containing the unparsed contents of the compound
strings.
Availability
Motif 2.0 and later.
Description
XmStringTableUnparse() is a convenience function which unparses an
array of compound strings. The XmStringTable table is converted into a string
array, whose contents is determined by output_type, which can be
XmCHARSET_TEXT, XmWIDECHAR_TEXT, or XmMULTIBYTE_TEXT.
Only those text components within the table which match tag are converted:
NULL converts all text components. An XmParseTable can be supplied which
acts as a filter: each parse mapping in the table contains a pattern which must
match a text component of the compound string if that component is to be converted.
parse_model determines how non-text components of string are handled when
matching against parse_table. If the value is XmOUTPUT_ALL, all components
are taken into account in the conversion process. If the value is
414
Motif Reference Manual
Motif Functions and Macros
XmStringTableUnparse
XmOUTPUT_BETWEEN, any non-text components which are not between two
text components are ignored. If the value is XmOUTPUT_BEGINNING, any
non-text components which do not precede a text component are ignored. Similarly, the value XmOUTPUT_END specifies that any non-text components which
do not follow a text component are ignored. XmOUTPUT_BOTH is a combination of XmOUTPUT_BEGINNING and XmOUTPUT_END. The number of
items within the returned string array is identical to the supplied number of compound strings. Each converted string occupies the same index in the returned
array as the index of the source compound string in table.
Usage
XmStringTableUnparse() is the logical inverse of the routine XmStringTableParseStringArray(). It simply invokes XmStringUnparse() on
each of the elements in the supplied table. The function returns allocated storage,
both for the returned array, and for each element within the array. It is the responsibility of the programmer to reclaim the storage at an appropriate point by calling XtFree() on each element in the array and upon the array itself.
Structures
An XmParseModel has the following possible values:
XmOUTPUT_ALL
XmOUTPUT_BEGINNING
XmOUTPUT_BETWEEN
XmOUTPUT_BOTH
XmOUTPUT_END
See Also
XmStringFree(1), XmStringParseText(1), XmStringUnparse(1),
XmParseMapping(2).
Motif Reference Manual
415
XmStringToXmStringTable
Motif Functions and Macros
Name
XmStringToXmStringTable – convert a compound string to a compound string
table.
Synopsis
Cardinal XmStringToXmStringTable (XmString string, XmString break_comp,
XmStringTable *table)
Inputs
string
break_comp
Outputs
table
Specifies a compound string.
Specifies a component which indicates where to split string into
an individual table element.
Returns the converted compound string table.
Returns
The number of elements in the converted compound string table.
Availability
Motif 2.0 and later.
Description
XmStringToXmStringTable() is a convenience function which converts an
XmString string into an array of compound strings. break_comp is a component
which is used to determine how to split the string into individual items: components in string are considered to form contiguous sequences delimited by
break_comp, each sequence forming a separate entry in the converted string
table. Any component from string which matches the delimiting break_comp is
not copied into the converted table. If break_comp is NULL, the returned compound string table contains a single entry: a copy of the original string.
Usage
XmStringToXmStringTable() is the inverse function to XmStringTableToXmString(). A break_comp component of type
XmSTRING_COMPONENT_TAB or
XmSTRING_COMPONENT_SEPARATOR is the most useful choice. The function returns allocated storage, and it is the responsibility of the programmer to
reclaim the space by calling XmStringFree() on each element in the table, and
then XtFree() on the table itself.
Example
The following code illustrates a basic call to XmStringToXmStringTable():
extern XmString
416
xms;
Motif Reference Manual
Motif Functions and Macros
Cardinal
XmStringTable
XmString
int
XmStringToXmStringTable
count;
table;
break_component;
i;
/* create a break component */
break_component = XmStringComponentCreate
(XmSTRING_COMPONEN
T_SEPARATOR, 0,
NULL)1;
/* convert an (unspecified) compound string */
count = XmStringToXmStringTable (xms, break_component, &table);
/* use the table */
...
/* free the allocated space */
for (i = 0; i < count; i++) {
XmStringFree (table[i]);
}
XtFree ((char *) table);
See Also
XmStringFree(1), XmStringTableToXmString(1).
1.Erroneously given as XmComponentCreate() in 2nd edition. XmStringSeparatorCreate() could be used equally well.
Motif Reference Manual
417
XmStringUnparse
Motif Functions and Macros
Name
XmStringUnparse – convert a compound string into a string.
Synopsis
XtPointer XmStringUnparse ( XmString
XmStringTag
XmTextType
XmTextType
XmParseTable
Cardinal
XmParseModel
Inputs
string
tag
tag_type
output_type
parse_table
parse_count
parse_model
string,
tag,
tag_type,
output_type,
parse_table,
parse_count,
parse_model)
Specifies the compound string to unparse.
Specifies which text segments of string to unparse.
Specifies the type of tag.
Specifies the type of conversion required.
Specifies a parse table to control the conversion.
Specifies the number of parse mappings in parse_table.
Specifies how non-text components are converted.
Returns
An allocated string containing the unparsed contents of a compound string.
Availability
Motif 2.0 and later.
Description
XmStringUnparse() is a convenience function which unparses a compound
string. The XmString string is converted into a string, whose contents is determined by output_type, which can be XmCHARSET_TEXT,
XmWIDECHAR_TEXT, or XmMULTIBYTE_TEXT. Only those text components within the string which match tag are converted: NULL converts all text
components. An XmParseTable can be supplied which acts as a filter: each parse
mapping in the table contains a pattern which must match a text component of
the compound string if that component is to be converted. parse_model determines how non-text components of string are handled when matching against
parse_table. If the value is XmOUTPUT_ALL, all non-text components are used
in the conversion process. If the value is XmOUTPUT_BETWEEN, any non-text
components which fall between text components are used. If the value is
XmOUTPUT_BEGINNING, non-text components which precede a text component are utilized. Similarly, XmOUTPUT_END uses non-text components which
follow a text component. XmOUTPUT_BOTH is a combination of
XmOUTPUT_BEGINNING and XmOUTPUT_END.
418
Motif Reference Manual
Motif Functions and Macros
XmStringUnparse
Usage
XmStringUnparse() is the logical inverse of the routine XmStringParseText(). The function returns allocated storage, and it is the responsibility of the
programmer to reclaim the storage by calling XtFree() at an appropriate point.
Structures
An XmParseModel has the following possible values:
XmOUTPUT_ALL
XmOUTPUT_BEGINNING
XmOUTPUT_BETWEEN
XmOUTPUT_BOTH
XmOUTPUT_END
Example
The following specimen code outlines a basic call to XmStringUnparse(),
which converts separator and tab components into the output:
XmParseTable parse_table = (XmParseTable) XtCalloc (2, sizeof
(XmParseMapping));
XmString
tmp;
XmString
output;
char
*string;
Arg
av[4];
Cardinal
ac;
/* map tab component to \t */
tmp = XmStringComponentCreate (XmSTRING_COMPONENT_TAB, 0,
NULL);
ac = 0;
XtSetArg (av[ac], XmNincludeStatus,
XmINSERT);
ac++;
XtSetArg (av[ac], XmNsubstitute,
tmp);
ac++;
XtSetArg (av[ac], XmNpattern,
"\t");
ac++;
parse_table[0] = XmParseMappingCreate (av, ac);
XmStringFree (tmp);
/* map separator component to \n */
tmp = XmStringSeparatorCreate();
ac = 0;
XtSetArg (av[ac], XmNincludeStatus,
XmINSERT);
XtSetArg (av[ac], XmNsubstitute,
tmp);
XtSetArg (av[ac], XmNpattern,
"\n");
parse_table[1] = XmParseMappingCreate (av, ac);
XmStringFree (tmp);
Motif Reference Manual
ac++;
ac++;
ac++;
419
XmStringUnparse
Motif Functions and Macros
/* convert the (unspecified) compound string */
string = (char *) XmStringUnparse (xms, NULL, XmCHARSET_TEXT,
XmCHARSET_TEXT, parse_table, 2,
XmOUTPUT_ALL);
/* use the converted string */
....
/* free the allocated space */
XtFree (string);
/* Free the parse table: this also frees the parse mappings */
XmParseTableFree (parse_table, 2);
See Also
XmStringFree(1), XmStringParseText(1),
XmStringTableUnparse(1), XmParseMapping(2).
420
Motif Reference Manual
Motif Functions and Macros
XmStringWidth
Name
XmStringWidth – get the width of the longest line of text in a compound string.
Synopsis
Dimension XmStringWidth (XmFontList fontlist, XmString string)
Inputs
fontlist
string
Specifies the font list for the compound string.
Specifies the compound string.
Returns
The width of the compound string.
Availability
In Motif 2.0 and later, the XmFontList is obsolete, and is replaced by the
XmRenderTable, to which it is an alias.
Description
XmStringWidth() returns the width, in pixels, of the longest line of text in the
specified compound string. Lines in the compound string are delimited by separator components. If string is created with XmStringCreateSimple(), then
fontlist must begin with the font from the character set of the current language
environment, otherwise the result is undefined.
Usage
In Motif 1.2, a compound string is composed of one or more segments, where
each segment can contain a font list element tag, a string direction, and a text
component. In Motif 2.0 and later, the set of available segments is extended to
include, amongst other items, tab, rendition, direction, locale components.
XmStringWidth() provides information that is useful if you need to render a
compound string. Motif widgets render compound strings automatically, so you
only need to worry about rendering them yourself if you are writing your own
widget. The routine is also useful if you want to get the dimensions of a compound string rendered with a particular font.
See Also
XmStringBaseline(1), XmStringExtent(1), XmStringHeight(1).
Motif Reference Manual
421
XmTabCreate
Motif Functions and Macros
Name
XmTabCreate – create a tab stop.
Synopsis
XmTab XmTabCreate ( float
unsigned char
XmOffsetModel
unsigned char
char
value,
units,
offset_model,
alignment,
*decimal)
Inputs
value
Specifies the value to be used in calculating the location of a tab
stop.
units
Specifies the units in which value is expressed.
offset_model Specifies whether the tab is at an absolute position, or relative to
the previous tab.
alignment
Specifies how text should be aligned to this tab stop.
decimal
Specifies the multibyte character in the current locale to be used
as a decimal point.
Returns
An XmTab object.
Availability
Motif 2.0 and later.
Description
XmTabCreate() creates a tab stop at the position specified by value, which is
expressed in terms of units. If value is less than 0 (zero), a warning is displayed,
and value is reset to 0.0. The offset_model determines whether the tab position is
an absolute location (XmABSOLUTE) calculated from the start of any rendering, or relative to the previous tab stop (XmRELATIVE). alignment specifies
how text is aligned with respect to the tab location: at present only
XmALIGNMENT_BEGINNING is supported. decimal is a multibyte character
which describes the decimal point character in the current locale.
Usage
A tab stop can be created, and inserted into an XmTabList through the function
XmTabListInsertTabs(). The tab list is used to render a multi-column layout of compound strings by specifying the list as the XmNtabList resource of a
rendition object within a render table associated with a widget. The decimal
parameter is currently unused.
422
Motif Reference Manual
Motif Functions and Macros
XmTabCreate
XmTabCreate() allocates storage for the object which it returns. It is the
responsibility of the programmer to free the memory at an appropriate point by a
call to XmTabFree().
Structures
The XmOffsetModel type has the following possible values:
XmABSOLUTE
XmRELATIVE
Valid values for the units parameter are:
XmPIXELS
Xm100TH_MILLIMETERS
Xm1000TH_INCHES
Xm100TH_FONT_UNITS
Xm100TH_POINTS
XmCENTIMETERS
XmMILLIMETERS
XmINCHES
XmFONT_UNITS
XmPOINTS
Example
The following code creates a multi-column arrangement of compound strings; it
creates a set of XmTab objects, which are then inserted into an XmRendition
object. The XmRendition object is added to a render table:
extern Widget widget;
int
i;
Arg
argv[3];
XmTab
tabs[MAX_COLUMNS];
XmTabList
tab_list = (XmTabList) 0;
XmRendition
rendition;
XmRenderTable render_table;
/* Create the XmTab objects */
for (i = 0 ; i < MAX_COLUMNS ; i++) {
tabs[i] = XmTabCreate ((float) 1.5,
XmINCHES,
((i == 0) ? XmABSOLUTE :
XmRELATIVE),
XmALIGNMENT_BEGINNING,
“.”);
}
/* Add them to an XmTabList */
tab_list = XmTabListInsertTabs (NULL, tabs,
MAX_COLUMNS, 0);
/* Put the XmTabList into an XmRendition object */
Motif Reference Manual
423
XmTabCreate
Motif Functions and Macros
i = 0;
XtSetArg (argv[i], XmNtabList, tab_list); i++;
XtSetArg (argv[i], XmNfontName, “fixed”); i++;
XtSetArg (argv[i], XmNfontType, XmFONT_IS_FONT);
i++;
rendition = XmRenditionCreate (widget,NULL,argv,
i);
/* Add the XmRendition object into an XmRenderTable
*/
render_table = XmRenderTableAddRenditions (NULL,
&rendition,
1,
XmMERGE
_NEW);
/* Apply to the widget */
XtVaSetValues (widget, XmNrenderTable,
render_table, NULL);
...
/* Free Up - render table applied to widget takes a
reference
** counted copy of everything
*/
for (i = 0 ; i < MAX_COLUMNS ; i++) {
XmTabFree (tabs[i]);
}
XmTabListFree (tab_list);
XmRenditionFree (rendition);
XmRenderTableFree (render_table);
See Also
XmTabFree(1), XmTabGetValues(1), XmTabListInsertTabs(1),
XmTabSetValue(1), XmRenditionCreate(1),
XmRenderTableAddRenditions(1), XmRendition(2).
424
Motif Reference Manual
Motif Functions and Macros
XmTabFree
Name
XmTabFree – free the memory used by an XmTab object.
Synopsis
void XmTabFree (XmTab tab)
Inputs
tab
Specifies an XmTab object.
Availability
Motif 2.0 and later.
Description
XmTabFree() reclaims the memory associated with tab, previously allocated by
a call to XmTabCreate().
Usage
A tab stop can be created using XmTabCreate(), and inserted into an XmTabList through the function XmTabListInsertTabs(). The tab list is used to
render a multi-column layout of compound strings by specifying the list as the
XmNtabList resource of a rendition object within a render table associated with
a widget.
See Also
XmTabCreate(1), XmRendition(2).
Motif Reference Manual
425
XmTabGetValues
Motif Functions and Macros
Name
XmTabGetValues – fetch the value of an XmTab object.
Synopsis
float XmTabGetValues (
XmTab
unsigned char
XmOffsetModel
unsigned char
char
tab,
*units,
*offset_model,
*alignment,
**decimal)
Inputs
tab
Specifies an XmTab object.
Outputs
units
offset_model
alignment
decimal
point.
Returns the units in which the tab stop is calculated.
Returns the offset model.
Returns the text alignment with respect to the tab stop.
Returns the multibyte character used to represent the decimal
Returns
The distance, expressed in units, which the tab is offset.
Availability
Motif 2.0 and later.
Description
XmTabGetValues() retrieves the data associated with a tab stop object. The
function returns the position value of a tab stop, which is expressed in terms of
units. The offset_model determines whether the tab position is an absolute location (XmABSOLUTE) calculated from the start of any rendering, or relative to
the previous tab stop (XmRELATIVE). alignment specifies how text is aligned
with respect to the tab location: at present only XmALIGNMENT_BEGINNING
is supported. decimal is a multibyte character which describes the decimal point
character in the current locale.
Usage
A tab stop can be created using the function XmTabCreate(), and inserted into
an XmTabList through the function XmTabListInsertTabs(). The tab list is
used to render a multi-column layout of compound strings by specifying the list
as the XmNtabList resource of a rendition object within a render table associated
with a widget. The decimal value is currently unused.
Structures
The XmOffsetModel type has the following possible values:
426
Motif Reference Manual
Motif Functions and Macros
XmABSOLUTE
XmTabGetValues
XmRELATIVE
Valid values for units are:
XmPIXELS
Xm100TH_MILLIMETERS
Xm1000TH_INCHES
Xm100TH_FONT_UNITS
Xm100TH_POINTS
XmCENTIMETERS
XmMILLIMETERS
XmINCHES
XmFONT_UNITS
XmPOINTS
See Also
XmTabCreate(1), XmTabSetValue(1), XmRendition(2).
Motif Reference Manual
427
XmTabListCopy
Motif Functions and Macros
Name
XmTabListCopy – copy an XmTabList object.
Synopsis
XmTabList XmTabListCopy (XmTabList tab_list, int offset, Cardinal count)1
Inputs
tab_list
offset
count
Specifies the tab list to copy.
Specifies an index into the tab list from which to start copying.
Specifies the number of tab stops to copy.
Returns
A new tab list containing tabs copied from tab_list.
Availability
Motif 2.0 and later.
Description
XmTabListCopy() is a convenience function which creates a new XmTabList
by copying portions of an existing tab_list. If tab_list is NULL, the function simply returns NULL. Otherwise, a new tab list is allocated, and selected tabs are
copied, depending on the offset and count parameters. count specifies the number
of tabs to copy, and offset determines where in the original list to start. If offset is
zero, tabs are copied from the beginning of tab_list. If offset is negative, tabs are
copied in reverse order from the end of tab_list. If count is zero, all tabs from offset to the end of tab_list are copied.
Usage
A tab stop can be created using the function XmTabCreate(), and inserted into
an XmTabList through the function XmTabListInsertTabs(). The tab list is
used to render a multi-column layout of compound strings by specifying the list
as the XmNtabList resource of a rendition object within a render table associated
with a widget.
XmTabListCopy() allocates storage for the object which it returns. It is the
responsibility of the programmer to free the memory at an appropriate point by a
call to XmTabListFree().
See Also
XmTabCreate(1), XmTabListFree(1), XmTabListInsertTabs(1),
XmRendition(2).
1.Erroneously given as XmTabListTabCopy() in 2nd edition.
428
Motif Reference Manual
Motif Functions and Macros
XmTabListFree
Name
XmTabListFree – free the memory used by a tab list.
Synopsis
void XmTabListFree (XmTabList tab_list)
Inputs
tab_list
Specified the tab list to free.
Availability
Motif 2.0 and later.
Description
XmTabListFree() reclaims the space used by an XmTabList object, tab_list.
Usage
In common with other objects in Motif 2.0 and later, the tab (XmTab) and tab list
(XmTabList) are dynamically allocated data structures which must be freed when
no longer required. For example, XmStringTableProposeTablist()
dynamically creates a tab list for rendering a multi-column compound string
table which must be subsequently deallocated.
It is important to call XmTabListFree() instead of XtFree() because
XmTabListFree() also reclaims storage for each of the elements in the tab list.
See Also
XmStringTableProposeTablist(1), XmTabCreate(1),
XmTabListInsertTabs(1), XmRendition(2).
Motif Reference Manual
429
XmTabListGetTab
Motif Functions and Macros
Name
XmTabListGetTab – retrieve a tab from a tab list
Synopsis
XmTab XmTabListGetTab (XmTabList tab_list, Cardinal position)
Inputs
tab_list
position
Specifies a tab list.
Specifies the position of the required tab within the tab_list.
Returns
A copy of the required tab.
Availability
Motif 2.0 and later.
Description
XmTabListGetTab() returns a copy of a tab from the XmTabList specified by
tab_list. position determines where in the list of tabs the required tab is copied
from. The first tab within tab_list is at position zero, the second tab at position 1,
and so on. If position is not less than the number of tabs within the list, XmTabListGetTab() returns NULL.
Usage
A tab stop can be created using the function XmTabCreate(), and inserted into
an XmTabList through the function XmTabListInsertTabs(). The tab list is
used to render a multi-column layout of compound strings by specifying the list
as the XmNtabList resource of a rendition object within a render table associated
with a widget.
XmTabListGetTab() returns a copy of the tab within the original tab list, and
it is the responsibility of the programmer to reclaim the space at a suitable point
by calling XmTabFree().
See Also
XmTabCreate(1), XmTabFree(1), XmTabListInsertTabs(1),
XmRendition(2).
430
Motif Reference Manual
Motif Functions and Macros
XmTabListInsertTabs
Name
XmTabListInsertTabs – insert tabs into a tab list.
Synopsis
XmTabList XmTabListInsertTabs (XmTabList tab_list, XmTab *tabs, Cardinal
tab_count, int position)
Inputs
tab_list
tabs
tab_count
position
Specifies the tab list into which tabs are added.
Specifies an array of tabs to add.
Specifies the number of tabs within the tabs array.
Specifies an index into tab_list at which to insert the tabs.
Returns
A newly allocated tab list.
Availability
Motif 2.0 and later.
Description
XmTabListInsertTabs() creates a new tab list by merging a set of tabs into
a tab_list at a given position. If tabs is NULL, or tab_count is zero, the function
returns the original tab_list. If position is zero, the new tabs are inserted at the
head of the new tab list, if position is 1, they are inserted after the first tab, and so
forth. If position is greater than the number of tabs in tab_list, the new tabs are
appended. If position is negative, the new tabs are inserted in reverse order at the
end of the original list, so that the first new tab becomes the last tab in the new
list.
Usage
A tab stop can be created using the function XmTabCreate(), and inserted into
an XmTabList through the function XmTabListInsertTabs(). The tab list is
used to render a multi-column layout of compound strings by specifying the list
as the XmNtabList resource of a rendition object within a render table associated
with a widget.
XmTabListInsertTabs() returns allocated storage, and it is the responsibility of the programmer to reclaim the space at a suitable point by calling XmTabListFree().
See Also
XmTabCreate(1), XmTabFree(1), XmTabListFree(1),
XmTabListInsertTabs(1), XmRendition(2).
Motif Reference Manual
431
XmTabListRemoveTabs
Motif Functions and Macros
Name
XmTabListRemoveTabs – copy a tab list, excluding specified tabs.
Synopsis
XmTabList XmTabListRemoveTabs ( XmTabList old_list,
Cardinal
*position_list,
Cardinal
position_count)
Inputs
old_list
position_list
position_count
Specifies the tab list to copy.
Specifies an array of tab positions to exclude.
Specifies the length of position_list.
Returns
A copy of old_list, with the specified positions excluded.
Availability
Motif 2.0 and later.
Description
XmTabListRemoveTabs() removes tabs from a old_list by allocating a new
tab list which contains all the tabs of the original list except for those at specific
positions within a position_list. The first tab within a tab list is at position zero,
the second tab at position 1, and so on. If old_list is NULL, or if position_list is
NULL, or if position_count is zero, the function returns old_list unmodified. Otherwise old_list is freed, as are any excluded tab elements, before the newly allocated tab list is returned.
Usage
A tab stop can be created using the function XmTabCreate(), and inserted into
an XmTabList through the function XmTabListInsertTabs(). The tab list is
used to render a multi-column layout of compound strings by specifying the list
as the XmNtabList resource of a rendition object within a render table associated
with a widget.
When the returned tab list differs from the original old_list parameter, XmTabListRemoveTabs() returns allocated storage, and it is the responsibility of the
programmer to reclaim the space at a suitable point by calling XmTabListFree().
See Also
XmTabCreate(1), XmTabFree(1), XmTabListFree(1),
XmTabListInsertTabs(1), XmRendition(2).
432
Motif Reference Manual
Motif Functions and Macros
XmTabListReplacePositions
Name
XmTabListReplacePositions – copy a tab list, replacing tabs at specified positions.
Synopsis
XmTabList XmTabListReplacePositions ( XmTabList
Cardinal
XmTab
Cardinal
Inputs
old_list
position_list
tabs
tab_count
old_list,
*position_list,
*tabs,
tab_count)
Specifies the tab list to modify.
Specifies an array of positions at which to replace the tabs.
Specifies the tabs which replace those in old_list.
Specifies the number of tabs and positions.
Returns
A new tab list with tabs replaced at specified positions.
Availability
Motif 2.0 and later.
Description
XmTabListReplacePositions() creates a newly allocated tab list which
contains all the original tabs in old_list, except that at any position contained
within position_list, the corresponding tab from tabs is used instead of the original. That is, at the first position specified within position_list, the original tab is
replaced by the first tab within tabs. The first tab within a tab list is at position
zero, the second tab at position 1, and so on. If old_list is NULL, or if tabs is
NULL, or if position_list is NULL, or if tab_count is zero, the function returns
old_list unmodified. Otherwise old_list is freed, as are any replaced tab elements,
before the newly allocated tab list is returned.
Usage
A tab stop can be created using the function XmTabCreate(), and inserted into
an XmTabList through the function XmTabListInsertTabs(). The tab list is
used to render a multi-column layout of compound strings by specifying the list
as the XmNtabList resource of a rendition object within a render table associated
with a widget.
When the returned tab list differs from the original old_list parameter, XmTabListReplacePositions() returns allocated storage, and it is the responsibility of the programmer to reclaim the space at a suitable point by calling
XmTabListFree()
Motif Reference Manual
433
XmTabListReplacePositions
Motif Functions and Macros
See Also
XmTabCreate(1), XmTabFree(1), XmTabListFree(1),
XmTabListInsertTabs(1), XmTabListRemoveTabs(1),
XmRendition(2).
434
Motif Reference Manual
Motif Functions and Macros
XmTabListTabCount
Name
XmTabListTabCount – count the number of tabs in a tab list.
Synopsis
Cardinal XmTabListTabCount (XmTabList tab_list)
Inputs
tab_list
The tab list to count.
Returns
The number of tab stops in tab_list.
Availability
Motif 2.0 and later.
Description
XmTabListTabCount()1 is a convenience function which counts the number
of XmTab objects contained within tab_list. If tab_list is NULL, the function
returns zero.
Usage
A tab stop can be created using the function XmTabCreate(), and inserted into
an XmTabList through the function XmTabListInsertTabs(). The tab list is
used to render a multi-column layout of compound strings by specifying the list
as the XmNtabList resource of a rendition object within a render table associated
with a widget.
See Also
XmTabCreate(1), XmTabFree(1), XmTabListFree(1),
XmTabListInsertTabs(1), XmTabListRemoveTabs(1),
XmRendition\*(s2.
1.Erroneously given as XmTabListCount() in 2nd edition.
Motif Reference Manual
435
XmTabSetValue
Motif Functions and Macros
Name
XmTabSetValue – set the value of a tab stop.
Synopsis
void XmTabSetValue (XmTab tab, float value)
Inputs
tab
value
Specifies the tab to modify.
Specifies the new value for the tab stop.
Availability
Motif 2.0 and later.
Description
XmTabSetValue() sets the value associated with an XmTab object. The value
is a floating point quantity which either represents an absolute distance from the
start of the current rendition, or a value relative to the previous tab stop. The offset model specified when the tab is created determines whether value is relative
or absolute. If value is less than 0 (zero), a warning message is displayed and the
function returns without modifying the tab.
Usage
A tab stop can be created using the function XmTabCreate(), and inserted into
an XmTabList through the function XmTabListInsertTabs(). The tab list is
used to render a multi-column layout of compound strings by specifying the list
as the XmNtabList resource of a rendition object within a render table associated
with a widget.
See Also
XmTabCreate(1), XmTabListInsertTabs(1), XmRendition(2).
436
Motif Reference Manual
Motif Functions and Macros
XmTargetsAreCompatible
Name
XmTargetsAreCompatible – determine whether or not the target types of a drag
source and a drop site match.
Synopsis
#include <Xm/DragDrop.h>
Boolean XmTargetsAreCompatible ( Display
Atom
Cardinal
Atom
Cardinal
Inputs
display
export_targets
num_export_targets
import_targets
num_import_targets
*display,
*export_targets,
num_export_targets,
*import_targets,
num_import_targets)
Specifies a connection to an X server; returned from
XOpenDisplay() or XtDisplay().
Specifies the list of target atoms to which the drag
source can convert the data.
Specifies the number of items in export_targets.
Specifies the list of target atoms that are accepted by the
drop site.
Specifies the number of items in import_targets.
Returns
True if there is a compatible target or False otherwise.
Availability
Motif 1.2 and later.
Description
XmTargetsAreCompatible() determines whether or not the import targets
of a drop site match any of the export targets of a drag source. The routine returns
True if the two objects have at least one target in common; otherwise it returns
False.
Usage
Motif 1.2 and later supports the drag and drop model of selection actions. In a
widget that acts as a drag source, a user can make a selection and then drag the
selection, using BTransfer, to other widgets that are registered as drop sites.
These drop sites can be in the same application or another application. In order
for a drag and drop operation to succeed, the drag source and the drop site must
both be able to handle data in the same format. XmTargetsAreCompatible() provides a way for an application to check if a drag source and a drop site
support compatible formats.
See Also
XmDragContext(1), XmDropSite(1).
Motif Reference Manual
437
XmTextClearSelection
Motif Functions and Macros
Name
XmTextClearSelection, XmTextFieldClearSelection – clear the primary selection.
Synopsis
#include <Xm/Text.h>
void XmTextClearSelection (Widget widget, Time time)
#include <Xm/TextF.h>
void XmTextFieldClearSelection (Widget widget, Time time)
Inputs
widget
time
Specifies the Text or TextField widget.
Specifies the time of the event that caused the request.
Description
XmTextClearSelection() and XmTextFieldClearSelection() clear
the primary selection in the specified widget. XmTextClearSelection()
works when widget is a Text widget or a TextField widget, while XmTextFieldClearSelection() only works for a TextField widget. For each routine, time specifies the server time of the event that caused the request to clear the
selection.
Usage
XmTextClearSelection() and XmTextFieldClearSelection() provide a convenient way to deselect the text selection in a Text or TextField widget.
If no text is selected, the routines do nothing. Any text that is stored in the clipboard or selection properties remains; the routines affect the selected text in the
widget only. If you are calling one of these routines from a callback routine, you
probably want to use the time field from the event pointer in the callback structure as the value of the time parameter. You can also use the value CurrentTime,
but there is no guarantee that using this time prevents race conditions between
multiple clients that are trying to use the clipboard.
Example
The following callback routine for the items on an Edit menu (Cut, Copy, Link,
Paste, and Clear) shows the use of XmTextClearSelection():
Widget text_w, status;
void cut_paste (Widget widget, XtPointer client_data, XtPointer call_data)
{
int
num = (int) client_data;
XmAnyCallbackStruct
*cbs = (XmAnyCallbackStruct *) call_data;
438
Motif Reference Manual
Motif Functions and Macros
Boolean
XmTextClearSelection
result = True;
switch (num) {
case 0: result = XmTextCut (text_w, cbs->event->xbutton.time);break;
case 1: result = XmTextCopy (text_w, cbs->event->xbutton.time);
break;
case 2: result = XmTextCopyLink (text_w, cbs->event->xbutton.time);
break;
case 3: result = XmTextPaste (text_w);break
case 4: XmTextClearSelection (text_w, cbs->event->xbutton.time);
break;
}
if (result == False)
XmTextSetString (status, "There is no selection.");
else
XmTextSetString (status, NULL);
}
See Also
XmTextCopy(1), XmTextCopyLink(1), XmTextCut(1),
XmTextGetSelection(1), XmTextGetSelectionPosition(1),
XmTextGetSelectionWcs(1), XmTextSetSelection(1), XmText(2),
XmTextField(2).
Motif Reference Manual
439
XmTextCopy
Motif Functions and Macros
Name
XmTextCopy, XmTextFieldCopy – copy the primary selection to the clipboard.
Synopsis
#include <Xm/Text.h>
Boolean XmTextCopy (Widget widget, Time time)
#include <Xm/TextF.h>
Boolean XmTextFieldCopy (Widget widget, Time time)
Inputs
widget
time
Specifies the Text or TextField widget.
Specifies the time of the event that caused the request.
Returns
True on success or False otherwise.
Description
XmTextCopy() and XmTextFieldCopy() copy the primary selection in the
specified widget to the clipboard. XmTextCopy() works when widget is a Text
widget or a TextField widget, while XmTextFieldCopy() only works for a
TextField widget. For each routine, time specifies the server time of the event that
caused the request to copy the selection. Both routines return True if successful.
If the primary selection is NULL, if it is not owned by the specified widget, or if
the function cannot obtain ownership of the clipboard selection, the routines
return False.
In Motif 2.0 and later, XmTextCopy() interfaces with the Uniform Transfer
Model by indirectly invoking the XmNconvertCallback procedures of the widget.
Usage
XmTextCopy() and XmTextFieldCopy() copy the text that is selected in a
Text or TextField widget and place it on the clipboard. If you are calling one of
these routines from a callback routine, you probably want to use the time field
from the event pointer in the callback structure as the value of the time parameter.
You can also use the value CurrentTime, but there is no guarantee that using this
time prevents race conditions between multiple clients that are trying to use the
clipboard.
Example
The following callback routine for the items on an Edit menu (Cut, Copy, Link,
Paste, PasteLink, and Clear) shows the use of XmTextCopy():
Widget text_w, status;
440
Motif Reference Manual
Motif Functions and Macros
XmTextCopy
void cut_paste (Widget widget, XtPointer client_data, XtPointer call_data)
{
int
num = (int) client_data;
XmAnyCallbackStruct*cbs = (XmAnyCallbackStruct *) call_data;
Boolean
result = True;
switch (num) {
case 0: result = XmTextCut (text_w, cbs->event->xbutton.time);break;
case 1: result = XmTextCopy (text_w, cbs->event->xbutton.time);
break;
case 2: result = XmTextCopyLink (text_w, cbs->event->xbutton.time);
break;
case 3: result = XmTextPaste (text_w);break;
case 4: result = XmTextPasteLink (text_w);break;
case 5: XmTextClearSelection (text_w, cbs->event->xbutton.time);
break;
}
if (result == False)
XmTextSetString (status, "There is no selection.");
else
XmTextSetString (status, NULL);
}
See Also
XmTextClearSelection(1), XmTextCopyLink(1), XmTextCut(1),
XmTextGetSelection(1), XmTextGetSelectionWcs(1),
XmTextPaste(1), XmTextPasteLink(1), XmTextRemove(1),
XmTextSetSelection(1), XmText(2), XmTextField(2).
Motif Reference Manual
441
XmTextCopyLink
Motif Functions and Macros
Name
XmTextCopyLink, XmTextFieldCopyLink – copy the primary selection to the
clipboard.
Synopsis
#include <Xm/Text.h>
Boolean XmTextCopyLink (Widget widget, Time time)
#include <Xm/TextF.h>
Boolean XmTextFieldCopyLink (Widget widget, Time time)
Inputs
widget
time
Specifies the Text or TextField widget.
Specifies the time of the event that caused the request.
Returns
True on success or False otherwise.
Availability
Motif 2.0 and later.
Description
XmTextCopyLink() and XmTextFieldCopyLink() copy a link to the primary selection in the specified widget to the clipboard. XmTextCopyLink()
works when widget is a Text widget or a TextField widget, while XmTextFieldCopyLink() only works for a TextField widget. For each routine, time
specifies the server time of the event that caused the request to copy the selection.
Both routines return True if successful. If the primary selection is NULL, if it is
not owned by the specified widget, or if the function cannot obtain ownership of
the clipboard selection, the routines return False.
XmTextCopyLink() and XmTextFieldCopyLink() interface with the Uniform Transfer Model by indirectly invoking XmNconvertCallback procedures for
the widget. The Text widget itself does not copy links: convert procedures which
the programmer provides are responsible for copying the link to the clipboard.
Usage
XmTextCopyLink() and XmTextFieldCopyLink() copy links to the text
that is selected in a Text or TextField widget and place it on the clipboard. If you
are calling one of these routines from a callback routine, you probably want to
use the time field from the event pointer in the callback structure as the value of
the time parameter. You can also use the value CurrentTime, but there is no guarantee that using this time prevents race conditions between multiple clients that
are trying to use the clipboard.
442
Motif Reference Manual
Motif Functions and Macros
XmTextCopyLink
Example
The following callback routine for the items on an Edit menu (Cut, Copy, Link,
Paste, PasteLink, and Clear) shows the use of XmTextCopyLink():
Widget text_w, status;
void cut_paste (Widget widget, XtPointer client_data, XtPointer call_data)
{
int
num = (int) client_data;
XmAnyCallbackStruct
*cbs = (XmAnyCallbackStruct *) call_data;
Boolean
result = True;
switch (num) {
case 0: result = XmTextCut (text_w, cbs->event->xbutton.time);break;
case 1: result = XmTextCopy (text_w, cbs->event->xbutton.time);
break;
case 2: result = XmTextCopyLink (text_w, cbs->event->xbutton.time);
break;
case 3: result = XmTextPaste (text_w);break;
case 4: result = XmTextPasteLink (text_w);break;
case 5: XmTextClearSelection (text_w, cbs->event->xbutton.time);
break;
}
if (result == False)
XmTextSetString (status, "There is no selection.");
else
XmTextSetString (status, NULL);
}
See Also
XmTextClearSelection(1), XmTextCopy(1), XmTextCut(1),
XmTextGetSelection(1), XmTextGetSelectionWcs(1),
XmTextPaste(1), XmTextPasteLink(1), XmTextRemove(1),
XmTextSetSelection(1), XmText(2), XmTextField(2).
Motif Reference Manual
443
XmTextCut
Motif Functions and Macros
Name
XmTextCut, XmTextFieldCut – copy the primary selection to the clipboard and
remove the selected text.
Synopsis
#include <Xm/Text.h>
Boolean XmTextCut (Widget widget, Time time)
#include <Xm/TextF.h>
Boolean XmTextFieldCut (Widget widget, Time time)
Inputs
widget
time
Specifies the Text or TextField widget.
Specifies the time of the event that caused the request.
Returns
True on success or False otherwise.
Description
XmTextCut() and XmTextFieldCut() copy the primary selection in the
specified widget to the clipboard and then delete the primary selection.
XmTextCut() works when widget is a Text widget or a TextField widget, while
XmTextFieldCut() only works for a TextField widget. For each routine, time
specifies the server time of the event that caused the request to cut the selection.
Both routines return True if successful. If the widget is not editable, if the primary selection is NULL or if it is not owned by the specified widget, or if the
function cannot obtain ownership of the clipboard selection, the routines return
False.
XmTextCut() and XmTextFieldCut() also invoke the callback routines for
the XmNvalueChangedCallback, the XmNmodifyVerifyCallback, and the XmNmodifyVerifyCallbackWcs callbacks for the specified widget. If both verification
callbacks are present, the XmNmodifyVerifyCallback procedures are invoked
first and the results are passed to the XmNmodifyVerifyCallbackWcs procedures.
In Motif 2.0 and later, XmTextCut() interfaces with the Uniform Transfer
Model by indirectly invoking the XmNconvertCallback procedures of the widget,
firstly to transfer the selection to the clipboard, and secondly to delete the selection.
Usage
XmTextCut() and XmTextFieldCut() copy the text that is selected in a Text
or TextField widget, place it on the clipboard, and then delete the selected text. If
you are calling one of these routines from a callback routine, you probably want
444
Motif Reference Manual
Motif Functions and Macros
XmTextCut
to use the time field from the event pointer in the callback structure as the value
of the time parameter. You can also use the value CurrentTime, but there is no
guarantee that using this time prevents race conditions between multiple clients
that are trying to use the clipboard.
Example
The following callback routine for the items on an Edit menu (Cut, Copy, Link,
Paste, and PasteLink, Clear) shows the use of XmTextCut():
Widget text_w, status;
void cut_paste (Widget widget, XtPointer client_data, XtPointer call_data)
{
int
num = (int) client_data;
XmAnyCallbackStruct*cbs = (XmAnyCallbackStruct *) call_data;
Boolean
result = True;
switch (num) {
case 0: result = XmTextCut (text_w, cbs->event->xbutton.time);break;
case 1: result = XmTextCopy (text_w, cbs->event->xbutton.time);
break;
case 2: result = XmTextCopyLink (text_w, cbs->event->xbutton.time);
break;
case 3: result = XmTextPaste (text_w);break;
case 4: result = XmTextPasteLink (text_w);break;
case 5: XmTextClearSelection (text_w, cbs->event->xbutton.time);
break;
}
if (result == False)
XmTextSetString (status, "There is no selection.");
else
XmTextSetString (status, NULL);
}
See Also
XmTextClearSelection(1), XmTextCopy(1), XmTextCopyLink(1),
XmTextGetSelection(1), XmTextGetSelectionWcs(1),
XmTextPaste(1), XmTextPasteLink(1), XmTextRemove(1),
XmTextSetSelection(1), XmText(2), XmTextField(2).
Motif Reference Manual
445
XmTextDisableRedisplay
Motif Functions and Macros
Name
XmTextDisableRedisplay – prevent visual update of a Text widget.
Synopsis
#include <Xm/Text.h>
void XmTextDisableRedisplay (Widget widget)
Inputs
widget
Specifies the Text widget.
Availability
Motif 1.2 and later.
Description
XmTextDisableRedisplay() temporarily inhibits visual update of the specified Text widget. Even if the visual attributes of the widget have been modified,
the appearance remains unchanged until XmTextEnableRedisplay() is
called.
Usage
XmTextDisableRedisplay() and XmTextEnableRedisplay() allow
an application to make multiple changes to a Text widget without immediate visual updates. When multiple changes are made with redisplay enabled, visual
flashing often occurs. These routines eliminate this problem.
See Also
XmTextEnableRedisplay(1), XmUpdateDisplay(1), XmText(2).
446
Motif Reference Manual
Motif Functions and Macros
XmTextEnableRedisplay
Name
XmTextEnableRedisplay – allow visual update of a Text widget.
Synopsis
#include <Xm/Text.h>
void XmTextEnableRedisplay (Widget widget)
Inputs
widget
Specifies the Text widget.
Availability
Motif 1.2 and later.
Description
XmTextEnableRedisplay() allows the specified Text widget to update its
visual appearance. This routine is used in conjunction with XmTextDisableRedisplay(), which prevents visual update of the Text widget. When XmTextEnableRedisplay() is called, the widget modifies its visuals to reflect all of
the changes since the last call to XmTextDisableRedisplay(). All future
changes that affect the visual appearance are displayed immediately.
Usage
XmTextDisableRedisplay() and XmTextEnableRedisplay() allow
an application to make multiple changes to a Text widget without immediate visual updates. When multiple changes are made with redisplay enabled, visual
flashing often occurs. These routines eliminate this problem.
See Also
XmTextDisableRedisplay(1), XmUpdateDisplay(1), XmText\*(s2.
Motif Reference Manual
447
XmTextFindString
Motif Functions and Macros
Name
XmTextFindString – find the beginning position of a text string.
Synopsis
#include <Xm/Xm.h>
Boolean XmTextFindString ( Widget
XmTextPosition
char
XmTextDirection
XmTextPosition
Inputs
widget
start
string
direction
Outputs
position
widget,
start,
*string,
direction,
*position)
Specifies the Text widget.
Specifies the position from which the search begins.
Specifies the string for which to search.
Specifies the direction of the search. Pass either
XmTEXT_FORWARD or XmTEXT_BACKWARD.
Returns the position where the search string starts.
Returns
True if the string is found or False otherwise.
Availability
Motif 1.2 and later.
Description
XmTextFindString() finds the beginning position of the specified string in
the Text widget. Depending on the value of direction, the routine searches forward or backward from the specified start position for the first occurrence of
string. If XmTextFindString() finds a match, it returns True and position
specifies the position of the first character of the string as the number of characters from the beginning of the text, where the first character position is 0 (zero). If
a match is not found, the routine returns False and the value of position is undefined.
Usage
XmTextFindString() is a convenience routine that searches the text in a Text
widget for a particular string. Without the routine, the search must be performed
using the standard string manipulation routines.
448
Motif Reference Manual
Motif Functions and Macros
XmTextFindString
Example
The following routine shows the use of XmTextFindString() to locate a
string in a text editing window. The search string is specified by the user in a single-line Text widget:
Widget text_w, search_w;
void search_text (void)
{
char
*search_pat = (char *) 0;
XmTextPosition
pos, search_pos;
Boolean
found = False;
if (!(search_pat = XmTextGetString (search_w)) || !*search_pat) {
XtFree (search_pat);
return;
}
/* find next occurrence from current position -- wrap if necessary */
pos = XmTextGetCursorPosition (text_w);
found = XmTextFindString (text_w, pos, search_pat,
XmTEXT_FORWARD, &search_pos);
if (!found)
found = XmTextFindString (text_w, 0, search_pat,
XmTEXT_FORWARD, &search_pos);
if (found)
XmTextSetInsertionPosition (text_w, search_pos);
XtFree (search_pat);
}
See Also
XmTextFindStringWcs(1), XmTextGetSubstring(1),
XmTextGetSubstringWcs(1), XmText(2).
Motif Reference Manual
449
Motif Functions and Macros
Name
XmTextFindStringWcs – find the beginning position of a wide-character string in
a Text widget.
Synopsis
#include <Xm/Text.h>
Boolean XmTextFindStringWcs ( Widget
XmTextPosition
wchar_t
XmTextDirection
XmTextPosition
Inputs
widget
start
wcstring
direction
Outputs
position
widget,
start,
*wcstring,
direction,
*position)
Specifies the Text widget.
Specifies the position from which the search begins.
Specifies the wide-character string for which to search.
Specifies the direction of the search. Pass either
XmTEXT_FORWARD or XmTEXT_BACKWARD.
Returns the position where the search string starts.
Returns
True if the string is found or False otherwise.
Availability
Motif 1.2 and later.
Description
XmTextFindStringWcs() finds the beginning position of the specified widecharacter wcstring in the Text widget. Depending on the value of direction, the
routine searches forward or backward from the specified start position for the
first occurrence of wcstring. If XmTextFindStringWcs() finds a match, it
returns True and position specifies the position of the first character of the string
as the number of characters from the beginning of the text, where the first character position is 0 (zero). If a match is not found, the routine returns False and the
value of position is undefined.
Usage
In Motif 1.2, the Text widget supports wide-character strings. XmTextFindStringWcs() is a convenience routine that searches the text in a Text widget for
a particular wide-character string. The routine converts the wide-character string
into a multi-byte string and then performs the search. Without the routine, the
search must be performed using the standard string manipulation routines.
Motif Reference Manual
450
Motif Functions and Macros
See Also
XmTextFindString(1), XmTextGetSubstring(1),
XmTextGetSubstringWcs(1), XmText(2).
Motif Reference Manual
451
Motif Functions and Macros
Name
XmTextGetBaseline, XmTextFieldGetBaseline – get the position of the baseline.
Synopsis
#include <Xm/Text.h>
int XmTextGetBaseline (Widget widget)
#include <Xm/TextF.h>
int XmTextFieldGetBaseline (Widget widget)
Inputs
widget
Specifies the Text or TextField widget.
Returns
The baseline position.
Description
XmTextGetBaseline() returns the y coordinate of the baseline of the first
line of text in the specified Text widget, while XmTextFieldGetBaseline()
returns the y coordinate of the baseline for the text in the specified TextField
widget. XmTextGetBaseline() works when widget is a Text widget or a
TextField widget, while XmTextFieldGetBaseline() only works for a TextField widget. For each routine, the returned value is relative to the top of the
widget and it accounts for the margin height, shadow thickness, highlight thickness, and font ascent of the first font in the font list.
Usage
XmTextGetBaseline() and XmTextFieldGetBaseline() provide information that is useful when you are laying out an application and trying to align
different components.
See Also
XmTextGetCenterline(1), XmWidgetGetBaselines(1),
XmWidgetGetDisplayRect(1), XmText(2), XmTextField(2).
Motif Reference Manual
452
Motif Functions and Macros
Name
XmTextGetCenterline – get the height of vertical text.
Synopsis
#include <Xm/Text.h>
int XmTextGetCenterline (Widget widget)
Inputs
widget
Specifies the Text widget.
Returns
The center line x position.
Availability
Motif 2.1 and later.
Description
XmTextGetCenterline() calculates the x coordinate of the centerline in a
Text widget containing vertical text. If the layout direction of the Text widget
does not match XmTOP_TO_BOTTOM_RIGHT_TO_LEFT the function returns
zero. Otherwise the procedure calculates the x position of the centerline relative
to the left of the Text. The margin width, shadow thickness, and the width of the
font are taken into consideration when performing the calculation.
Usage
XmTextGetCenterline() provides information that is useful when you are
laying out an application and trying to align different components.
See Also
XmTextGetBaseline(1), XmWidgetGetCenterlines(1),
XmWidgetGetDisplayRect(1), XmText(2), XmTextField(2).
Motif Reference Manual
453
Motif Functions and Macros
Name
XmTextGetCursorPosition, XmTextFieldGetCursorPosition – get the position of
the insertion cursor.
Synopsis
#include <Xm/Text.h>
XmTextPosition XmTextGetCursorPosition (Widget widget)
#include <Xm/TextF.h>
XmTextPosition XmTextFieldGetCursorPosition (Widget widget)
Inputs
widget
Specifies the Text or TextField widget.
Returns
The value of the XmNcursorPosition resource.
Description
XmTextGetCursorPosition() and XmTextFieldGetCursorPosition() return the value of the XmNcursorPosition resource for the specified
widget. XmTextGetCursorPosition() works when widget is a Text
widget or a TextField widget, while XmTextFieldGetCursorPosition()
only works for a TextField widget. For each routine, the value specifies the location of the insertion cursor as the number of characters from the beginning of the
text, where the first character position is 0 (zero).
Usage
XmTextGetCursorPosition() and XmTextFieldGetCursorPosition() are convenience routines that return the value of the XmNcursorPosition
resource for a Text or TextField widget. Calling one of the routines is equivalent
to calling XtGetValues() for the resource, although the routines access the
value through the widget instance structures rather than through XtGetValues().
See Also
XmTextGetInsertionPosition(1),
XmTextSetCursorPosition(1),
XmTextSetInsertionPosition(1), XmTextShowPosition(1),
XmText(2), XmTextField(2).
Motif Reference Manual
454
Motif Functions and Macros
Name
XmTextGetEditable, XmTextFieldGetEditable – get the edit permission state.
Synopsis
#include <Xm/Text.h>
Boolean XmTextGetEditable (Widget widget)
#include <Xm/TextF.h>
Boolean XmTextFieldGetEditable (Widget widget)
Inputs
widget
Specifies the Text or TextField widget.
Returns
The state of the XmNeditable resource.
Description
XmTextGetEditable() and XmTextFieldGetEditable() return the
value of the XmNeditable resource for the specified Text or TextField widget.
XmTextGetEditable() works when widget is a Text widget or a TextField
widget, while XmTextFieldGetEditable() only works for a TextField
widget.
Usage
By default, the XmNeditable resource is True, which means that a user can edit
the text string. Setting the resource to False makes a text area read-only.
XmTextGetEditable() and XmTextFieldGetEditable() are convenience routines that return the value of the XmNeditable resource for a Text or
TextField widget. Calling one of the routines is equivalent to calling XtGetValues() for the resource, although the routines access the value through the
widget instance structures rather than through XtGetValues().
See Also
XmTextSetEditable(1), XmText(2), XmTextField(2).
Motif Reference Manual
455
Motif Functions and Macros
Name
XmTextGetInsertionPosition, XmTextFieldGetInsertionPosition – get the position of the insertion cursor.
Synopsis
#include <Xm/Text.h>
XmTextPosition XmTextGetInsertionPosition (Widget widget)
#include <Xm/TextF.h>
XmTextPosition XmTextFieldGetInsertionPosition (Widget widget)
Inputs
widget
Specifies the Text or TextField widget.
Returns
The value of the XmNcursorPosition resource.
Description
The functions, XmTextGetInsertionPosition() and XmTextFieldGetInsertionPosition(), return the value of the XmNcursorPosition
resource for the specified widget. XmTextGetInsertionPosition() works
when widget is a Text widget or a TextField widget, while XmTextFieldGetInsertionPosition() only works for a TextField widget. For each routine,
the value specifies the location of the insertion cursor as the number of characters
from the beginning of the text, where the first character position is 0 (zero).
Usage
The functions, XmTextGetInsertionPosition() and XmTextFieldGetInsertionPosition(), are convenience routines that return the value of
the XmNcursorPosition resource for a Text or TextField widget. Calling one of
the routines is equivalent to calling XtGetValues() for the resource, although
the routines access the value through the widget instance structures rather than
through XtGetValues().
See Also
XmTextGetCursorPosition(1),
XmTextSetInsertionPosition(1),
XmTextSetCursorPosition(1), XmTextShowPosition(1),
XmText(2), XmTextField(2).
Motif Reference Manual
456
Motif Functions and Macros
Name
XmTextGetLastPosition, XmTextFieldGetLastPosition – get the position of the
last character of text.
Synopsis
#include <Xm/Text.h>
XmTextPosition XmTextGetLastPosition (Widget widget)
#include <Xm/TextF.h>
XmTextPosition XmTextFieldGetLastPosition (Widget widget)
Inputs
widget
Specifies the Text or TextField widget.
Returns
The position of the last text character.
Description
XmTextGetLastPosition() and XmTextFieldGetLastPosition()
return the position of the last character of text in the specified widget. XmTextGetLastPosition() works when widget is a Text widget or a TextField
widget, while XmTextFieldGetLastPosition() only works for a TextField widget. For each routine, the returned value specifies the position as the
number of characters from the beginning of the text, where the first character
position is 0 (zero).
Usage
XmTextGetLastPosition() and XmTextFieldGetLastPosition()
are convenience routines that return the number of characters of text in a Text or
TextField widget.
See Also
XmTextGetCursorPosition(1),
XmTextGetInsertionPosition(1), XmTextGetTopCharacter(1),
XmTextScroll(1), XmTextSetCursorPosition(1),
XmTextSetInsertionPosition(1), XmTextSetTopCharacter(1),
XmTextShowPosition(1), XmText(2), XmTextField(2).
Motif Reference Manual
457
Motif Functions and Macros
Name
XmTextGetMaxLength, XmTextFieldGetMaxLength – get the maximum possible length of a text string.
Synopsis
#include <Xm/Text.h>
int XmTextGetMaxLength (Widget widget)
#include <Xm/TextF.h>
int XmTextFieldGetMaxLength (Widget widget)
Inputs
widget
Specifies the Text or TextField widget.
Returns
The value of the XmNmaxLength resource.
Description
XmTextGetMaxLength() and XmTextFieldGetMaxLength() return the
value of the XmNmaxLength resource for the specified Text or TextField widget.
XmTextGetMaxLength() works when widget is a Text widget or a TextField
widget, while XmTextFieldGetMaxLength() only works for a TextField
widget. For each routine, the returned value specifies the maximum allowable
length of a text string that a user can enter from the keyboard.
Usage
XmTextGetMaxLength() and XmTextFieldGetMaxLength() are convenience routines that return the value of the XmNmaxLength resource for a Text
or TextField widget. Calling one of the routines is equivalent to calling XtGetValues() for the resource, although the routines access the value through the
widget instance structures rather than through XtGetValues().
See Also
XmTextSetMaxLength(1), XmText(2), XmTextField(2).
Motif Reference Manual
458
Motif Functions and Macros
Name
XmTextGetSelection, XmTextFieldGetSelection – get the value of the primary
selection.
Synopsis
#include <Xm/Text.h>
char * XmTextGetSelection (Widget widget)
#include <Xm/TextF.h>
char * XmTextFieldGetSelection (Widget widget)
Inputs
widget
Specifies the Text or TextField widget.
Returns
A string containing the primary selection.
Description
XmTextGetSelection() and XmTextFieldGetSelection() return a
pointer to a character string containing the primary selection in the specified
widget. XmTextGetSelection() works when widget is a Text widget or a
TextField widget, while XmTextFieldGetSelection() only works for a
TextField widget. For each routine, if no text is selected in the widget, the
returned value is NULL. Storage for the returned string is allocated by the routine
and should be freed by calling XtFree(). Management of the allocated memory
is the responsibility of the application.
Usage
XmTextGetSelection() and XmTextFieldGetSelection() provide a
convenient way to get the current selection from a Text or TextField widget.
See Also
XmTextGetSelectionPosition(1), XmTextGetSelectionWcs(1),
XmTextSetSelection(1), XmText(2), XmTextField(2).
Motif Reference Manual
459
Motif Functions and Macros
Name
XmTextGetSelectionPosition, XmTextFieldGetSelectionPosition – get the position of the primary selection.
Synopsis
#include <Xm/Text.h>
Boolean XmTextGetSelectionPosition (
Widget
XmTextPosition
XmTextPosition
widget,
*left,
*right)
#include <Xm/TextF.h>
Boolean XmTextFieldGetSelectionPosition ( Widget
XmTextPosition
XmTextPosition
widget,
*left,
*right)
Inputs
widget
Specifies the Text or TextField widget.
Outputs
left
right
Returns the position of the left boundary of the primary selection.
Returns the position of the right boundary of the primary selection.
Returns
True if widget owns the primary selection or False otherwise.
Description
The functions, XmTextGetSelectionPosition() and XmTextFieldGetSelectionPosition() return the left and right boundaries of the primary
selection for the specified widget. XmTextGetSelectionPosition()
works when widget is a Text widget or a TextField widget, while XmTextFieldGetSelectionPosition() only works for a TextField widget. Each
boundary value specifies the position as the number of characters from the beginning of the text, where the first character position is 0 (zero). Each routine returns
True if the specified Text or TextField widget owns the primary selection; otherwise, the routine returns False and the values of left and right are undefined.
Usage
The functions, XmTextGetSelectionPosition() and XmTextFieldGetSelectionPosition(), provide a convenient way to get the position of
the current selection from a Text or TextField widget.
See Also
XmTextGetSelection(1), XmTextGetSelectionWcs(1),
XmTextSetSelection(1), XmText(2), XmTextField(2).
Motif Reference Manual
460
Motif Functions and Macros
Name
XmTextGetSelectionWcs, XmTextFieldGetSelectionWcs – get the wide-character value of the primary selection.
Synopsis
#include <Xm/Text.h>
wchar_t * XmTextGetSelectionWcs (Widget widget)
#include <Xm/TextF.h>
wchar_t * XmTextFieldGetSelectionWcs (Widget widget)
Inputs
widget
Specifies the Text or TextField widget.
Returns
A wide-character string containing the primary selection.
Availability
Motif 1.2 and later.
Description
XmTextGetSelectionWcs() and XmTextFieldGetSelectionWcs()
return a pointer to a wide-character string containing the primary selection in the
specified widget. XmTextGetSelectionWcs() works when widget is a Text
widget or a TextField widget, while XmTextFieldGetSelectionWcs()
only works for a TextField widget. For each routine, if no text is selected in the
widget, the returned value is NULL. Storage for the returned wide-character
string is allocated by the routine and should be freed by calling XtFree(). Management of the allocated memory is the responsibility of the application.
Usage
In Motif 1.2, the Text and TextField widgets support wide-character strings.
XmTextGetSelectionWcs() and XmTextFieldGetSelectionWcs()
provide a convenient way to get the current selection in wide-character format
from a Text or TextField widget.
See Also
XmTextGetSelection(1), XmTextGetSelectionPosition(1),
XmTextSetSelection(1), XmText(2), XmTextField(2).
Motif Reference Manual
461
Motif Functions and Macros
Name
XmTextGetSource – get the text source.
Synopsis
#include <Xm/Text.h>
XmTextSource XmTextGetSource (Widget widget)
Inputs
widget
Specifies the Text widget.
Returns
The source of the Text widget.
Description
XmTextGetSource() returns the source of the specified Text widget. Every
Text widget has an XmTextSource data structure associated with it that functions
as the text source and sink.
Usage
Multiple text widgets can share the same text source, which means that editing in
one of the widgets is reflected in all of the others. XmTextGetSource()
retrieves the source for a widget; this source can then be used to set the source of
another Text widget using XmTextSetSource(). XmTextGetSource() is a
convenience routine that returns the value of the XmNsource resource for the
Text widget. Calling the routine is equivalent to calling XtGetValues() for the
resource, although the routine accesses the value through the widget instance
structures rather than through XtGetValues().
See Also
XmTextSetSource(1), XmText(2).
Motif Reference Manual
462
Motif Functions and Macros
Name
XmTextGetString, XmTextFieldGetString – get the text string.
Synopsis
#include <Xm/Text.h>
char * XmTextGetString (Widget widget)
#include <Xm/TextF.h>
char * XmTextFieldGetString (Widget widget)
Inputs
widget Specifies the Text or TextField widget.
Returns
A string containing the value of the Text or TextField widget.
Description
XmTextGetString() and XmTextFieldGetString() return a pointer to a
character string containing the value of the specified widget. XmTextGetString() works when widget is a Text widget or a TextField widget, while
XmTextFieldGetString() only works for a TextField widget. For each
routine, if the string has a length of 0 (zero), the returned value is the empty
string. Storage for the returned string is allocated by the routine and should be
freed by calling XtFree(). Management of the allocated memory is the responsibility of the application.
Usage
XmTextGetString() and XmTextFieldGetString() are convenience
routines that return the value of the XmNvalue resource for a Text or TextField
widget. Calling one of the routines is equivalent to calling XtGetValues() for
the resource, although the routines access the value through the widget instance
structures rather than through XtGetValues().
In Motif 1.2, the Text and TextField widgets support wide-character strings. The
resource XmNvalueWcs can be used to set the value of a Text or TextField
widget to a wide-character string. Even if you set the XmNvalueWcs resource,
you can still use XmTextGetString() or XmTextFieldGetString() to
retrieve the value of the widget, since the value is stored internally as a multi-byte
string.
Motif Reference Manual
463
Motif Functions and Macros
Example
The following routine shows the use of XmTextGetString() to retrieve the
text from one Text widget and use the text to search for the string in another Text
widget:
Widget text_w, search_w;
void search_text (void)
{
char
*search_pat;
XmTextPosition
pos, search_pos;
Boolean
found = False;
if (!(search_pat = XmTextGetString (search_w)) || !*search_pat) {
XtFree (search_pat);
return;
}
/* find next occurrence from current position -- wrap if necessary */
pos = XmTextGetCursorPosition (text_w);
found = XmTextFindString (text_w, pos, search_pat,
XmTEXT_FORWARD, &search_pos);
if (!found)
found = XmTextFindString (text_w, 0, search_pat,
XmTEXT_FORWARD, &search_pos);
if (found)
XmTextSetInsertionPosition (text_w, search_pos);
XtFree (search_pat);
}
See Also
XmTextGetStringWcs(1), XmTextGetSubstring(1),
XmTextGetSubstringWcs(1), XmTextSetString(1),
XmTextSetStringWcs(1), XmText(2), XmTextField(2).
Motif Reference Manual
464
Motif Functions and Macros
Name
XmTextGetStringWcs, XmTextFieldGetStringWcs – get the wide-character text
string.
Synopsis
#include <Xm/Text.h>
wchar_t * XmTextGetStringWcs (Widget widget)
#include <Xm/TextF.h>
wchar_t * XmTextFieldGetStringWcs (Widget widget)
Inputs
widget
Specifies the Text or TextField widget.
Returns
A wide-character string containing the value of the Text or TextField widget.
Availability
Motif 1.2 and later.
Description
XmTextGetStringWcs() and XmTextFieldGetStringWcs() return a
pointer to a wide-character string containing the value of the specified widget.
XmTextGetStringWcs() works when widget is a Text widget or a TextField
widget, while XmTextFieldGetStringWcs() only works for a TextField
widget. For each routine, if the string has a length of 0 (zero), the returned value
is the empty string. Storage for the returned wide-character string is allocated by
the routine and should be freed by calling XtFree(). Management of the allocated memory is the responsibility of the application.
Usage
XmTextGetStringWcs() and XmTextFieldGetStringWcs() are convenience routines that return the value of the XmNvalueWcs resource for a Text
or TextField widget. Calling one of the routines is equivalent to calling XtGetValues() for the resource, although the routines access the value through the
widget instance structures rather than through XtGetValues().
In Motif 1.2, the Text and TextField widgets support wide-character strings. The
resource XmNvalueWcs can be used to set the value of a Text or TextField
widget to a wide-character string. Even if you use the XmNvalue resource to set
the value of a widget, you can still use XmTextGetStringWcs() or XmTextFieldGetStringWcs() to retrieve the value of the widget, since the value can
be converted to a wide-character string.
Motif Reference Manual
465
Motif Functions and Macros
See Also
XmTextGetString(1), XmTextGetSubstring(1),
XmTextGetSubstringWcs(1), XmTextSetString(1),
XmTextSetStringWcs(1), XmText(2), XmTextField(2).
Motif Reference Manual
466
Motif Functions and Macros
Name
XmTextGetSubstring, XmTextFieldGetSubstring – get a copy of part of the text
string.
Synopsis
#include <Xm/Text.h>
int XmTextGetSubstring ( Widget
XmTextPosition
int
int
char
widget,
start,
num_chars,
buffer_size,
*buffer)
#include <Xm/TextF.h>
int XmTextFieldGetSubstring
Inputs
widget
start
num_chars
buffer_size
buffer
(Widget
XmTextPosition
int
int
char
widget,
start,
num_chars,
buffer_size,
*buffer)
Specifies the Text or TextField widget.
Specifies the starting character position from which data is copied.
Specifies the number of characters that are copied.
Specifies the size of buffer.
Specifies the character buffer where the copy is stored.
Returns
XmCOPY_SUCCEEDED on success, XmCOPY_TRUNCATED if fewer than
num_chars are copied, or XmCOPY_FAILED on failure.
Availability
Motif 1.2 and later.
Description
XmTextGetSubstring() and XmTextFieldGetSubstring() get a copy
of part of the internal text buffer for the specified widget. XmTextGetSubstring()1 works when widget is a Text widget or a TextField widget, while
XmTextFieldGetSubstring()2 only works for a TextField widget. The
routines copy num_chars characters starting at start position, which specifies the
1.Erroneously given as XmTextGetString() in 1st and 2nd editions.
2.Erroneously given as XmTextFieldGetString() in 1st and 2nd editions.
Motif Reference Manual
467
Motif Functions and Macros
position as the number of characters from the beginning of the text, where the
first character position is 0 (zero). The characters are copied into the provided
buffer and are NULL-terminated.
XmTextGetSubstring() and XmTextFieldGetSubstring() return
XmCOPY_SUCCEEDED on success. If the specified num_chars does not fit in
the provided buffer, the routines return XmCOPY_TRUNCATED. In this case,
buffer contains as many characters as would fit plus a NULL terminator. If either
of the routines fails to make the copy, it returns XmCOPY_FAILED and the contents of buffer are undefined.
Usage
XmTextGetSubstring() and XmTextFieldGetSubstring() provide a
convenient way to retrieve a portion of the text string in a Text or TextField
widget. The routines return the specified part of the XmNvalue resource for the
widget.
In Motif 1.2, the Text and TextField widgets support wide-character strings. The
resource XmNvalueWcs can be used to set the value of a Text or TextField
widget to a wide-character string. Even if you set the XmNvalueWcs resource,
you can still use XmTextGetSubstring() or XmTextFieldGetSubstring() to retrieve part of the value of the widget, since the value is stored
internally as a multi-byte string.
The necessary buffer_size for XmTextGetSubstring() and XmTextFieldGetSubstring() depends on the maximum number of bytes per character for the current locale. This information is stored in MB_CUR_MAX, a
macro defined in <stdlib.h>. The buffer needs to be large enough to store the substring and a NULL terminator. You can use the following equation to calculate
the necessary buffer_size:
buffer_size = (num_chars * MB_CUR_MAX) + 1
See Also
XmTextGetString(1), XmTextGetStringWcs(1),
XmTextGetSubstringWcs(1), XmTextSetString(1),
XmTextSetStringWcs(1), XmText(2), XmTextField(2).
Motif Reference Manual
468
Motif Functions and Macros
Name
XmTextGetSubstringWcs, XmTextFieldGetSubstringWcs – get a copy of part of
the wide-character text string.
Synopsis
#include <Xm/Text.h>
int XmTextGetSubstringWcs ( Widget
XmTextPosition
int
int
wchar_t
widget,
start,
num_chars,
buffer_size,
*buffer)
#include <Xm/TextF.h>
int XmTextFieldGetSubstringWcs (
Inputs
widget
start
num_chars
buffer_size
buffer
Widget
XmTextPosition
int
int
wchar_t
widget,
start,
num_chars,
buffer_size,
*buffer)
Specifies the Text or TextField widget.
Specifies the starting character position from which data is copied.
Specifies the number of wide-characters that are copied.
Specifies the size of buffer.
Specifies the wide-character buffer where the copy is stored.
Returns
XmCOPY_SUCCEEDED on success, XmCOPY_TRUNCATED if fewer than
num_chars are copied, or XmCOPY_FAILED on failure.
Availability
Motif 1.2 and later.
Description
XmTextGetSubstringWcs() and XmTextFieldGetSubstringWcs()
get a copy of part of the internal wide-character text buffer for the specified
widget. XmTextGetSubstringWcs() works when widget is a Text widget or
a TextField widget, while XmTextFieldGetSubstringWcs() only works
for a TextField widget. The routines copy num_chars wide-characters starting at
start position, which specifies the position as the number of characters from the
beginning of the text, where the first character position is 0 (zero). The widecharacters are copied into the provided buffer and are NULL-terminated.
Motif Reference Manual
469
Motif Functions and Macros
XmTextGetSubstringWcs() and XmTextFieldGetSubstringWcs()
return XmCOPY_SUCCEEDED on success. If the specified num_chars does not
fit in the provided buffer, the routines return XmCOPY_TRUNCATED. In this
case, buffer contains as many wide-characters as would fit plus a NULL terminator. If either of the routines fails to make the copy, it returns XmCOPY_FAILED
and the contents of buffer are undefined.
Usage
XmTextGetSubstringWcs() and XmTextFieldGetSubstringWcs()
provide a convenient way to retrieve a portion of the wide-character text string in
a Text or TextField widget. The routines return the specified part of the XmNvalueWcs resource for the widget.
In Motif 1.2, the Text and TextField widgets support wide-character strings. The
resource XmNvalueWcs can be used to set the value of a Text or TextField
widget to a wide-character string. Even if you use the XmNvalue resource to set
the value of a widget, you can still use XmTextGetSubstringWcs() or XmTextFieldGetSubstringWcs() to retrieve part of the value of the widget, since
the value can be converted to a wide-character string.
The necessary buffer_size for XmTextGetSubstringWcs() and XmTextFieldGetSubstringWcs() is num_chars + 1.
See Also
XmTextGetString(1), XmTextGetStringWcs(1),
XmTextGetSubstring(1), XmTextSetString(1),
XmTextSetStringWcs(1), XmText(2), XmTextField(2).
Motif Reference Manual
470
Motif Functions and Macros
Name
XmTextGetTopCharacter – get the position of the first character of text that is
displayed.
Synopsis
#include <Xm/Text.h>
XmTextPosition XmTextGetTopCharacter (Widget widget)
Inputs
widget
Specifies the Text widget.
Returns
The position of the first visible character.
Description
XmTextGetTopCharacter() returns the value of the XmNtopCharacter
resource for the specified Text widget. The returned value specifies the position
of the first visible character of text as the number of characters from the beginning of the text, where the first character position in 0 (zero).
Usage
XmTextGetTopCharacter() is a convenience routine that returns the value
of the XmNtopCharacter resource for a Text widget. Calling the routines is
equivalent to calling XtGetValues() for the resource, although the routines
accesses the value through the widget instance structures rather than through
XtGetValues().
See Also
XmTextGetCursorPosition(1),
XmTextGetInsertionPosition(1), XmTextGetLastPosition(1),
XmTextScroll(1), XmTextSetCursorPosition(1),
XmTextSetInsertionPosition(1), XmTextSetTopCharacter(1),
XmTextShowPosition(1), XmText(2).
Motif Reference Manual
471
Motif Functions and Macros
Name
XmTextInsert, XmTextFieldInsert – insert a string into the text string.
Synopsis
#include <Xm/Text.h>
void XmTextInsert (Widget widget, XmTextPosition position, char *value)
#include <Xm/TextF.h>
void XmTextFieldInsert (Widget widget, XmTextPosition position, char *string)
Inputs
widget
position
string
Specifies the Text or TextField widget.
Specifies the position at which the string is inserted.
Specifies the string to be inserted.
Description
XmTextInsert() and XmTextFieldInsert() insert a text string in the
specified Text or TextField widget. XmTextInsert() works when widget is a
Text widget or a TextField widget, while XmTextFieldInsert() only works
for a TextField widget. The specified string is inserted at position, where character positions are numbered sequentially, starting with 0 (zero) at the beginning of
the text. To insert a string after the nth character, use a position value of n.
XmTextInsert() and XmTextFieldInsert() also invoke the callback routines for the XmNvalueChangedCallback, the XmNmodifyVerifyCallback, and
the XmNmodifyVerifyCallbackWcs callbacks for the specified widget. If both
verification callbacks are present, the XmNmodifyVerifyCallback procedures are
invoked first and the results are passed to the XmNmodifyVerifyCallbackWcs
procedures.
Usage
XmTextInsert() and XmTextFieldInsert() provide a convenient means
of inserting text in a Text or TextField widget. The routines insert text by modifying the value of the XmNvalue resource of the widget.
Example
The following routine shows the use of XmTextInsert() to insert a message
into a status Text widget:
Widget status;
void insert_text (char *message)
{
XmTextPosition curpos = XmTextGetInsertionPosition (status);
Motif Reference Manual
472
Motif Functions and Macros
XmTextInsert (status, curpos, message);
curpos = curpos + strlen (message);
XmTextShowPosition (status, curpos);
XmTextSetInsertionPosition (status, curpos);
}
See Also
XmTextInsertWcs(1), XmTextReplace(1), XmTextReplaceWcs(1),
XmText(2), XmTextField(2).
Motif Reference Manual
473
Motif Functions and Macros
Name
XmTextInsertWcs, XmTextFieldInsertWcs – insert a wide-character string into
the text string.
Synopsis
#include <Xm/Text.h>
void XmTextInsertWcs (Widget widget, XmTextPosition position, wchar_t
*wcstring)1
#include <Xm/TextF.h>
void XmTextFieldInsertWcs (Widget widget, XmTextPosition position, wchar_t
* wcstring)
Inputs
widget
position
wcstring
Specifies the Text or TextField widget.
Specifies the position at which the string is inserted.
Specifies the wide-character string to be inserted.
Availability
Motif 1.2 and later.
Description
XmTextInsertWcs() and XmTextFieldInsertWcs() insert a wide-character text wcstring in the specified widget. XmTextInsertWcs() works when
widget is a Text widget or a TextField widget, while XmTextFieldInsertWcs() only works for a TextField widget. The specified wcstring2 is inserted at
position, where character positions are numbered sequentially, starting with 0
(zero) at the beginning of the text. To insert a string after the nth character, use a
position value of n.
XmTextInsertWcs() and XmTextFieldInsertWcs() also invoke the callback routines for the XmNvalueChangedCallback, the XmNmodifyVerifyCallback, and the XmNmodifyVerifyCallbackWcs callbacks for the specified widget.
If both verification callbacks are present, the XmNmodifyVerifyCallback procedures are invoked first and the results are passed to the XmNmodifyVerifyCallbackWcs procedures.
1.Erroneously given as XmTextInsert() in 1st and 2nd editions.
2.Erroneously given as string in 1st and 2nd editions.
Motif Reference Manual
474
Motif Functions and Macros
Usage
In Motif 1.2, the Text and TextField widgets support wide-character strings.
XmTextInsertWcs() and XmTextFieldInsertWcs() provide a convenient means of inserting a wide-character string in a Text or TextField widget. The
routines insert text by converting the wide-character string to a multi-byte string
and then modifying the value of the XmNvalue resource of the widget.
See Also
XmTextInsert(1), XmTextReplace(1), XmTextReplaceWcs(1),
XmText(2), XmTextField(2).
Motif Reference Manual
475
Motif Functions and Macros
Name
XmTextPaste, XmTextFieldPaste – insert the clipboard selection.
Synopsis
#include <Xm/Text.h>
Boolean XmTextPaste (Widget widget)
#include <Xm/TextF.h>
Boolean XmTextFieldPaste (Widget widget)
Inputs
widget
Specifies the Text or TextField widget.
Returns
True on success or False otherwise.
Description
XmTextPaste() and XmTextFieldPaste() insert the clipboard selection at
the current position of the insertion cursor in the specified widget. XmTextPaste() works when widget is a Text widget or a TextField widget, while
XmTextFieldPaste() only works for a TextField widget. If the insertion
cursor is within the current selection and the value of XmNpendingDelete is
True, the current selection is replaced by the clipboard selection. Both routines
return True if successful. If the widget is not editable or if the function cannot
obtain ownership of the clipboard selection, the routines return False.
In Motif 2.0 and later, XmTextPaste() interfaces with the Uniform Transfer
Model by indirectly invoking the XmNdestinationCallback procedures of the
widget.
XmTextPaste() and XmTextFieldPaste() also invoke the callback routines for the XmNvalueChangedCallback, the XmNmodifyVerifyCallback, and
the XmNmodifyVerifyCallbackWcs callbacks for the specified widget. If both
verification callbacks are present, the XmNmodifyVerifyCallback procedures are
invoked first and the results are passed to the XmNmodifyVerifyCallbackWcs
procedures.
Usage
XmTextPaste() and XmTextFieldPaste() get the current selection from
the clipboard and insert it at the location of the insertion cursor in the Text or
TextField widget.
Motif Reference Manual
476
Motif Functions and Macros
Example
The following callback routine for the items on an Edit menu (Cut, Copy, Link,
Paste, PasteLink, and Clear) shows the use of XmTextPaste():
Widget text_w, status;
void cut_paste (Widget widget, XtPointer client_data, XtPointer call_data)
{
int
num = (int) client_data;
XmAnyCallbackStruct
*cbs = (XmAnyCallbackStruct *) call_data;
Boolean
result = True;
switch (num) {
case 0: result = XmTextCut (text_w, cbs->event->xbutton.time);break;
case 1: result = XmTextCopy (text_w, cbs->event->xbutton.time);
break;
case 2: result = XmTextCopyLink (text_w, cbs->event->xbutton.time);
break;
case 3: result = XmTextPaste (text_w);break;
case 4: result = XmTextPasteLink (text_w);break;
case 5: XmTextClearSelection (text_w, cbs->event->xbutton.time);
break;
}
if (result == False)
XmTextSetString (status, "There is no selection.");
else
XmTextSetString (status, NULL);
}
See Also
XmTextCopy(1), XmTextCopyLink(1), XmTextCut(1),
XmTextPasteLink(1), XmText(2), XmTextField(2).
Motif Reference Manual
477
Motif Functions and Macros
Name
XmTextPasteLink, XmTextFieldPasteLink – insert the clipboard selection.
Synopsis
#include <Xm/Text.h>
Boolean XmTextPasteLink (Widget widget)
#include <Xm/TextF.h>
Boolean XmTextFieldPasteLink (Widget widget)
Inputs
widget
Specifies the Text or TextField widget.
Returns
True on success or False otherwise.
Availability
Motif 2.0 and later.
Description
XmTextPasteLink() and XmTextFieldPasteLink() insert the clipboard
selection at the current position of the insertion cursor in the specified widget.
XmTextPasteLink() works when widget is a Text widget or a TextField
widget, while XmTextFieldPasteLink() only works for a TextField widget.
If the insertion cursor is within the current selection and the value of XmNpendingDelete is True, the current selection is replaced by the clipboard selection. Both routines return True if successful. If the widget is not editable or if the
function cannot obtain ownership of the clipboard selection, the routines return
False.
XmTextPasteLink() and XmTextFieldPasteLink() interface with the
Uniform Transfer Model by indirectly invoking the XmNdestinationCallback
procedures of the widget. The Text widget itself does not create links to the primary selection: destination callbacks provided by the programmer are responsible for performing any data transfer required.
XmTextPasteLink() and XmTextFieldPasteLink() also invoke the callback routines for the XmNvalueChangedCallback, the XmNmodifyVerifyCallback, and the XmNmodifyVerifyCallbackWcs callbacks for the specified widget.
If both verification callbacks are present, the XmNmodifyVerifyCallback procedures are invoked first and the results are passed to the XmNmodifyVerifyCallbackWcs procedures.
Motif Reference Manual
478
Motif Functions and Macros
Usage
XmTextPasteLink() and XmTextFieldPasteLink() get the current
selection from the clipboard and insert a link to it at the location of the insertion
cursor in the Text or TextField widget.
Example
The following callback routine for the items on an Edit menu (Cut, Copy, Link,
Paste, PasteLink, and Clear) shows the use of XmTextPasteLink()1:
Widget text_w, status;
void cut_paste (Widget widget, XtPointer client_data, XtPointer call_data)
{
int
num = (int) client_data;
XmAnyCallbackStruct
*cbs = (XmAnyCallbackStruct *) call_data;
Boolean
result = True;
switch (num) {
case 0: result = XmTextCut (text_w, cbs->event->xbutton.time);break;
case 1: result = XmTextCopy (text_w, cbs->event->xbutton.time);
break;
case 2: result = XmTextCopyLink (text_w, cbs->event->xbutton.time);
break;
case 3: result = XmTextPaste (text_w);break;
case 4: result = XmTextPasteLink (text_w);break;
case 5: XmTextClearSelection (text_w, cbs->event->xbutton.time);
break;
}
if (result == False)
XmTextSetString (status, "There is no selection.");
else
XmTextSetString (status, NULL);
}
See Also
XmTextCopy(1), XmTextCopyLink(1), XmTextCut(1),
XmTextPaste(1), XmText(2), XmTextField(2).
1.Erroneously given as XmTextPaste() in 1st and 2nd editions.
Motif Reference Manual
479
Motif Functions and Macros
Name
XmTextPosToXY, XmTextFieldPosToXY – get the x, y position of a character
position.
Synopsis
#include <Xm/Text.h>
Boolean XmTextPosToXY (Widget widget, XmTextPosition position, Position
*x, Position *y)
#include <Xm/TextF.h>
Boolean XmTextFieldPosToXY (Widget widget, XmTextPosition position, Position *x, Position *y)
Inputs
widget
position
Specifies the Text or TextField widget.
Specifies the character position.
Outputs
x
y
Returns the x-coordinate of the character position.
Returns the y-coordinate of the character position.
Returns
True if the character position is displayed in the widget or False otherwise.
Description
XmTextPosToXY() and XmTextFieldPosToXY() return the x and y coordinates of the character at the specified position within the specified widget.
XmTextPosToXY() works when widget is a Text widget or a TextField widget,
while XmTextFieldPosToXY() only works for a TextField widget. Character positions are numbered sequentially, starting with 0 (zero) at the beginning of
the text. The returned coordinate values are specified relative to the upper-left
corner of widget. Both routines return True if the character at position is currently displayed in the widget. Otherwise, the routines return False and no values
are returned in the x and y arguments.
Usage
XmTextPosToXY() and XmTextFieldPosToXY() provide a way to determine the actual position of a character in a Text or TextField widget. This information is useful if you need to perform additional event processing or draw
special graphics in the widget.
See Also
XmTextXYToPos(1), XmText(2), XmTextField(2).
Motif Reference Manual
480
Motif Functions and Macros
Name
XmTextRemove, XmTextFieldRemove – delete the primary selection.
Synopsis
#include <Xm/Text.h>
Boolean XmTextRemove (Widget widget)
#include <Xm/TextF.h>
Boolean XmTextFieldRemove (Widget widget)
Inputs
widget
Specifies the Text or TextField widget.
Returns
True on success or False otherwise.
Description
XmTextRemove() and XmTextFieldRemove() delete the primary selected
text from the specified widget. XmTextRemove() works when widget is a Text
widget or a TextField widget, while XmTextFieldRemove() only works for a
TextField widget. Both routines return True if successful. If the widget is not
editable, if the primary selection is NULL, or if it is not owned by the specified
widget, the routines return False.
XmTextRemove() and XmTextFieldRemove() also invoke the callback routines for the XmNvalueChangedCallback, the XmNmodifyVerifyCallback, and
the XmNmodifyVerifyCallbackWcs callbacks for the specified widget. If both
verification callbacks are present, the XmNmodifyVerifyCallback procedures are
invoked first and the results are passed to the XmNmodifyVerifyCallbackWcs
procedures.
Usage
XmTextRemove() and XmTextFieldRemove() are like XmTextCut() and
XmTextFieldCut(), in that they remove selected text from a Text or TextField
widget. However, the routines do not copy the selected text to the clipboard
before removing it.
See Also
XmTextClearSelection(1), XmTextCut(1),
XmTextGetSelection(1), XmTextGetSelectionPosition(1),
XmTextGetSelectionWcs(1), XmTextSetSelection(1),
XmText(2), XmTextField(2).
Motif Reference Manual
481
Motif Functions and Macros
Name
XmTextReplace, XmTextFieldReplace – replace part of the text string.
Synopsis
#include <Xm/Text.h>
void XmTextReplace (Widget
XmTextPosition
XmTextPosition
char
widget,
from_pos,
to_pos,
*value)
#include <Xm/TextF.h>
void XmTextFieldReplace ( Widget
XmTextPosition
XmTextPosition
char
Inputs
widget
from
to
value
widget,
from_pos,
to_pos,
*value)
Specifies the Text or TextField widget.
Specifies the starting position of the text that is to be replaced.
Specifies the ending position of the text that is to be replaced.
Specifies the replacement string.
Description
XmTextReplace() and XmTextFieldReplace() replace a portion of the
text string in the specified widget. XmTextReplace() works when widget is a
Text widget or a TextField widget, while XmTextFieldReplace() only
works for a TextField widget. The specified value replaces the text starting at
from_pos and continuing up to, but not including, to_pos, where character positions are numbered sequentially, starting with 0 (zero) at the beginning of the
text. To replace the characters after the nth character up to the mth character, use
a from_pos value of n and a to_pos value of m.
XmTextReplace() and XmTextFieldReplace() also invoke the callback
routines for the XmNvalueChangedCallback, the XmNmodifyVerifyCallback,
and the XmNmodifyVerifyCallbackWcs callbacks for the specified widget. If
both verification callbacks are present, the XmNmodifyVerifyCallback procedures are invoked first and the results are passed to the XmNmodifyVerifyCallbackWcs procedures.
Usage
XmTextReplace() and XmTextFieldReplace() provide a convenient
means of replacing text in a Text or TextField widget. The routines replace text
by modifying the value of the XmNvalue resource of the widget.
Motif Reference Manual
482
Motif Functions and Macros
Example
The following routine shows the use of XmTextReplace() to replace all of the
occurrences of a string in a Text widget. The search and replacement strings are
specified by the user in single-line Text widgets:
Widget text_w, search_w, replace_w;
void search_and_replace (void)
{
char
*search_pat, *new_pat;
XmTextPosition
curpos, searchpos;
int
search_len, pattern_len;
Boolean
found = False;
search_len = XmTextGetLastPosition (search_w);
if (!(search_pat = XmTextGetString (search_w)) || !*search_pat) {
XtFree (search_pat);
return;
}
pattern_len = XmTextGetLastPosition (replace_w);
if (!(new_pat = XmTextGetString (replace_w)) || !*new_pat) {
XtFree (search_pat);
XtFree (new_pat);
return;
}
curpos = 0;
found = XmTextFindString (text_w, curpos, search_pat,
XmTEXT_FORWARD, &searchpos);
while (found) {
XmTextReplace (text_w, searchpos, searchpos + search_len, new_pat);
curpos = searchpos + 1;
found = XmTextFindString (text_w, curpos, search_pat,
XmTEXT_FORWARD, &searchpos);
}
XtFree (search_pat);
XtFree (new_pat);
}
See Also
XmTextInsert(1), XmTextInsertWcs(1), XmTextReplaceWcs(1),
XmText(2), XmTextField(2).
Motif Reference Manual
483
Motif Functions and Macros
Name
XmTextReplaceWcs, XmTextFieldReplaceWcs – replace part of the wide-character text string.
Synopsis
#include <Xm/Text.h>
void XmTextReplaceWcs (Widget
XmTextPosition
XmTextPosition
wchar_t
widget,
from_pos,
to_pos,
*wcstring)
#include <Xm/TextF.h>
void XmTextFieldReplaceWcs ( Widget
XmTextPosition
XmTextPosition
wchar_t
Inputs
widget
from_pos
to_pos
wcstring
widget,
from_pos,
to_pos,
*wcstring)
Specifies the Text or TextField widget.
Specifies the starting position of the text that is to be replaced.
Specifies the ending position of the text that is to be replaced.
Specifies the replacement wide-character string.
Availability
Motif 1.2 and later.
Description
XmTextReplaceWcs() and XmTextFieldReplaceWcs() replace a portion
of the text string in the specified widget with the specified wide-character string
wcstring. XmTextReplaceWcs() works when widget is a Text widget or a TextField widget, while XmTextFieldReplaceWcs() only works for a TextField
widget. The specified wcstring replaces the text starting at from_pos and continuing up to, but not including, to_pos, where character positions are numbered
sequentially, starting with 0 (zero) at the beginning of the text. To replace the
characters after the nth character up to the mth character, use a from_pos value of
n and a to_pos value of m.
XmTextReplaceWcs() and XmTextFieldReplaceWcs() also invoke the
callback routines for the XmNvalueChangedCallback, the XmNmodifyVerifyCallback, and the XmNmodifyVerifyCallbackWcs callbacks for the specified
widget. If both verification callbacks are present, the XmNmodifyVerifyCallback
procedures are invoked first and the results are passed to the XmNmodifyVerifyCallbackWcs procedures.
Motif Reference Manual
484
Motif Functions and Macros
Usage
In Motif 1.2, the Text and TextField widgets support wide-character strings.
XmTextReplaceWcs() and XmTextFieldReplaceWcs() provide a convenient means of replacing a string in a Text or TextField widget with a widecharacter string. The routines convert the wide-character string to a multi-byte
string and then replace the text by modifying the value of the XmNvalue resource
of the widget.
See Also
XmTextInsert(1), XmTextInsertWcs(1), XmTextReplace(1),
XmText(2), XmTextField(2).
Motif Reference Manual
485
Motif Functions and Macros
Name
XmTextScroll – scroll the text.
Synopsis
#include <Xm/Text.h>
void XmTextScroll (Widget widget, int lines)
Inputs
widget
lines
Specifies the Text widget.
Specifies the number of lines.
Description
XmTextScroll() scrolls the text in the specified Text widget by the specified
number of lines. The text is scrolled upward if lines is positive and downward if
lines is negative. In the case of vertical text, a positive value scrolls the text forwards, and a negative value scrolls backwards.
Usage
XmTextScroll() provides a way to perform relative scrolling in a Text widget.
The Text widget does not have to be the child of a ScrolledWindow for the scrolling to occur. The routine simply changes the currently viewable region of text.
See Also
XmTextGetCursorPosition(1),
XmTextGetInsertionPosition(1), XmTextGetLastPosition(1),
XmTextGetTopCharacter(1), XmTextSetCursorPosition(1),
XmTextSetInsertionPosition(1), XmTextSetTopCharacter(1),
XmText(2).
Motif Reference Manual
486
Motif Functions and Macros
Name
XmTextSetAddMode, XmTextFieldSetAddMode – set the add mode state.
Synopsis
#include <Xm/Text.h>
void XmTextSetAddMode (Widget widget, Boolean state)
#include <Xm/TextF.h>
void XmTextFieldSetAddMode (Widget widget, Boolean state)
Inputs
widget
state
Specifies the Text or TextField widget.
Specifies the state of add mode.
Description
XmTextSetAddMode() and XmTextFieldSetAddMode() set the state of
add mode for the specified widget. XmTextSetAddMode() works when widget
is a Text widget or a TextField widget, while XmTextFieldSetAddMode()
only works for a TextField widget. If state is True add mode is turned on; if state
is False, add mode is turned off. When a Text or TextField widget is in add mode,
the user can move the insertion cursor without altering the primary selection.
Usage
XmTextSetAddMode() and XmTextFieldSetAddMode() provide a way to
change the state of add mode in a Text or TextField widget. The distinction
between normal mode and add mode is only important for making keyboardbased selections. In normal mode, the location cursor and the selection move
together, while in add mode, the location cursor and the selection can be separate.
See Also
XmTextSetCursorPosition(1),
XmTextSetInsertionPosition(1), XmText(2), XmTextField(2).
Motif Reference Manual
487
Motif Functions and Macros
Name
XmTextSetCursorPosition, XmTextFieldSetCursorPosition – set the position of
the insertion cursor.
Synopsis
#include <Xm/Text.h>
void XmTextSetCursorPosition (Widget widget, XmTextPosition position)
#include <Xm/TextF.h>
void XmTextFieldSetCursorPosition (Widget widget, XmTextPosition position)
Inputs
widget
position
Specifies the Text or TextField widget.
Specifies the position of the insertion cursor.
Description
XmTextSetCursorPosition() and XmTextFieldSetCursorPosition() set the value of the XmNcursorPosition resource to position for the specified widget. XmTextSetCursorPosition() works when widget is a Text
widget or a TextField widget, while XmTextFieldSetCursorPosition()
only works for a TextField widget. This resource specifies the location of the
insertion cursor as the number of characters from the beginning of the text, where
the first character position is 0 (zero).
XmTextSetCursorPosition() and XmTextFieldSetCursorPosition() also invoke the callback routines for the XmNmotionVerifyCallback for
the specified widget if the position of the insertion cursor changes.
Usage
XmTextSetCursorPosition() and XmTextFieldSetCursorPosition() are convenience routines that set the value of the XmNcursorPosition
resource for a Text or TextField widget. Calling one of the routines is equivalent
to calling XtSetValues() for the resource, although the routines access the
value through the widget instance structures rather than through XtSetValues().
See Also
XmTextGetCursorPosition(1),
XmTextGetInsertionPosition(1),
XmTextSetInsertionPosition(1), XmTextShowPosition(1),
XmText(2), XmTextField(2).
Motif Reference Manual
488
Motif Functions and Macros
Name
XmTextSetEditable, XmTextFieldSetEditable – set the edit permission state.
Synopsis
#include <Xm/Text.h>
void XmTextSetEditable (Widget widget, Boolean editable)
#include <Xm/TextF.h>
void XmTextFieldSetEditable (Widget widget, Boolean editable)
Inputs
widget
editable
Specifies the Text or TextField widget.
Specifies whether or not the text can be edited.
Description
XmTextSetEditable() and XmTextFieldSetEditable() set the value
of the XmNeditable resource to editable for the specified widget. XmTextSetEditable() works when widget is a Text widget or a TextField widget, while
XmTextFieldSetEditable() only works for a TextField widget.
Usage
By default, the XmNeditable resource is True, which means that a user can edit
the text string. Setting the resource to False makes a text area read-only.
XmTextSetEditable() and XmTextFieldSetEditable() are convenience routines that set the value of the XmNeditable resource for a Text or TextField widget. Calling one of the routines is equivalent to calling
XtSetValues() for the resource, although the routines access the value
through the widget instance structures rather than through XtSetValues().
See Also
XmTextGetEditable(1), XmText(2), XmTextField(2).
Motif Reference Manual
489
Motif Functions and Macros
Name
XmTextSetHighlight, XmTextFieldSetHighlight – highlight text.
Synopsis
#include <Xm/Text.h>
void XmTextSetHighlight ( Widget
XmTextPosition
XmTextPosition
XmHighlightMode
widget,
left,
right,
mode)
#include <Xm/TextF.h>
void XmTextFieldSetHighlight (
Inputs
widget
left
right
mode
Widget
XmTextPosition
XmTextPosition
XmHighlightMode
widget,
left,
right,
mode)
Specifies the Text or TextField widget.
Specifies the left boundary position of the text to be highlighted.
Specifies the right boundary position of the text to be highlighted.
Specifies the highlighting mode. Pass one of the following values:
XmHIGHLIGHT_NORMAL, XmHIGHLIGHT_SELECTED,
or
XmHIGHLIGHT_SECONDARY_SELECTED1.
Description
XmTextSetHighlight() and XmTextFieldSetHighlight() highlight
text in the specified widget without selecting the text. XmTextSetHighlight() works when widget is a Text widget or a TextField widget, while
XmTextFieldSetHighlight() only works for a TextField widget. The left
and right arguments specify the boundary positions of the text that is to be highlighted. Each boundary value specifies the position as the number of characters
from the beginning of the text, where the first character position is 0 (zero). The
mode parameter indicates the type of highlighting that is done.
XmHIGHLIGHT_NORMAL removes any highlighting,
XmHIGHLIGHT_SELECTED uses reverse video highlighting, and
XmHIGHLIGHT_SECONDARY_SELECTED uses underline highlighting.
1.Motif 2.0 defines the additional value XmSEE_DETAIL for the enumerated type, but does not use it for the Text components. The Compound String Text, CSText, supports the notion, but this widget is abortive, and has been removed
from the 2.1 distribution. XmSEE_DETAIL is therefore redundant.
Motif Reference Manual
490
Motif Functions and Macros
Usage
XmTextSetHighlight() and XmTextFieldSetHighlight() provide a
way to highlight text in a Text or TextField widget. These routines are useful if
you need to emphasize certain text in a widget. These routine only highlight text;
they do not select the specified text.
Example
The following routine shows the use of XmTextSetHighlight() to highlight
all of the occurrences of a string in a Text widget. The search string is specified
by the user in a single-line Text widget:
Widget text_w, search_w;
void search_text (void)
{
char
XmTextPosition
int
Boolean
*search_pat;
curpos, searchpos;
len;
found = False;
len = XmTextGetLastPosition (search_w);
if (!(search_pat = XmTextGetString (search_w)) || !*search_pat) {
XtFree (search_pat);
return;
}
curpos = 0;
found = XmTextFindString (text_w, curpos, search_pat,
XmTEXT_FORWARD, &searchpos);
while (found) {
XmTextSetHighlight (text_w, searchpos, searchpos + len,
XmHIGHLIGHT_SECONDARY_SELECTE
D);
curpos = searchpos + 1;
found = XmTextFindString (text_w, curpos, search_pat,
XmTEXT_FORWARD, &searchpos);
}
XtFree (search_pat);
}
See Also
XmTextSetSelection(1), XmText(2), XmTextField(2).
Motif Reference Manual
491
Motif Functions and Macros
Name
XmTextSetInsertionPosition, XmTextFieldSetInsertionPosition – set the position
of the insertion cursor.
Synopsis
#include <Xm/Text.h>
void XmTextSetInsertionPosition (Widget widget, XmTextPosition position)
#include <Xm/TextF.h>
void XmTextFieldSetInsertionPosition (Widget widget, XmTextPosition position)
Inputs
widget
position
Specifies the Text or TextField widget.
Specifies the position of the insertion cursor.
Description
The functions, XmTextSetInsertionPosition() and XmTextFieldSetInsertionPosition(), set the value of the XmNcursorPosition resource to
position for the specified widget. XmTextSetInsertionPosition()
works when widget is a Text widget or a TextField widget, while XmTextFieldSetInsertionPosition() only works for a TextField widget. This
resource specifies the location of the insertion cursor as the number of characters
from the beginning of the text, where the first character position is 0 (zero).
XmTextSetInsertionPosition() and XmTextFieldSetInsertionPosition() also invoke the callback routines for the XmNmotionVerifyCallback for the specified widget if the position of the insertion cursor changes.
Usage
The functions, XmTextSetInsertionPosition() and XmTextFieldSetInsertionPosition(), are convenience routines that set the value of the
XmNcursorPosition resource for a Text or TextField widget. Calling one of the
routines is equivalent to calling XtSetValues() for the resource, although the
routines access the value through the widget instance structures rather than
through XtSetValues().
Example
The following code shows the use of XmTextSetInsertionPosition() in
a routine that searches for a string in a Text widget and moves the insertion cursor
to the string if it is found:
Widget text_w, search_w;
Motif Reference Manual
492
Motif Functions and Macros
void search_text (void)
{
char
*search_pat;
XmTextPosition
pos, searchpos;
Boolean
found = False;
if (!(search_pat = XmTextGetString (search_w)) || !*search_pat) {
XtFree (search_pat);
return;
}
pos = XmTextGetCursorPosition (text_w);
found = XmTextFindString (text_w, pos, search_pat,
XmTEXT_FORWARD, &searchpos);
if (!found) {
found = XmTextFindString (text_w, 0, search_pat,
XmTEXT_FORWARD, &searchpos);
}
if (found)
XmTextSetInsertionPosition (text_w, searchpos);
XtFree (search_pat);
}
See Also
XmTextGetCursorPosition(1),
XmTextGetInsertionPosition(1),
XmTextSetCursorPosition(1), XmTextShowPosition(1),
XmText(2), XmTextField(2).
Motif Reference Manual
493
Motif Functions and Macros
Name
XmTextSetMaxLength, XmTextFieldSetMaxLength – set the maximum possible
length of a text string.
Synopsis
#include <Xm/Text.h>
void XmTextSetMaxLength (Widget widget, int max_length)
#include <Xm/TextF.h>
void XmTextFieldSetMaxLength (Widget widget, int max_length)
Inputs
widget
Specifies the Text or TextField widget.
max_length Specifies the maximum allowable length of the text string.
Description
XmTextSetMaxLength() and XmTextFieldSetMaxLength() set the
value of the XmNmaxLength resource to max_length for the specified widget.
XmTextSetMaxLength() works when widget is a Text widget or a TextField
widget, while XmTextFieldSetMaxLength() only works for a TextField
widget. This resource specifies the maximum allowable length of a text string
that a user can enter from the keyboard.
Usage
XmTextSetMaxLength() and XmTextFieldSetMaxLength() are convenience routines that set the XmNmaxLength resource for a Text or TextField
widget. Calling one of the routines is equivalent to calling XtSetValues() for
the resource, although the routines access the value through the widget instance
structures rather than through XtSetValues(). The resource limits the length
of a text string that a user may type, but it does not limit the length of strings
entered with the XmNvalue or XmNvalueWcs resources or the XmTextSetString(), XmTextFieldSetString(), XmTextSetStringWcs(), and
XmTextFieldSetStringWcs() routines.
See Also
XmTextGetMaxLength(1), XmText(2), XmTextField(2).
Motif Reference Manual
494
Motif Functions and Macros
Name
XmTextSetSelection, XmTextFieldSetSelection – set the value of the primary
selection.
Synopsis
#include <Xm/Text.h>
void XmTextSetSelection (Widget widget, XmTextPosition first, XmTextPosition
last, Time time)
#include <Xm/TextF.h>
void XmTextFieldSetSelection (Widget widget, XmTextPosition first, XmTextPosition last, Time time)
Inputs
widget
first
last
time
Specifies the Text or TextField widget.
Specifies the first character position to be selected.
Specifies the last character position to be selected.
Specifies the time of the event that caused the request.
Description
XmTextSetSelection() and XmTextFieldSetSelection() set the primary selection in the specified widget. XmTextSetSelection() works when
widget is a Text widget or a TextField widget, while XmTextFieldSetSelection() only works for a TextField widget. The first and last arguments
specify the beginning and ending positions of the text that is to be selected. Each
of these values specifies the position as the number of characters from the beginning of the text, where the first character position is 0 (zero). For each routine,
time specifies the server time of the event that caused the request to set the selection.
XmTextSetSelection() and XmTextFieldSetSelection() change the
insertion cursor for the widget to the last position of the selection. The routines
also invoke the callback routines for the XmNmotionVerifyCallback for the specified widget.
Usage
XmTextSetSelection() and XmTextFieldSetSelection() provide a
convenient way to set the current selection in a Text or TextField widget.
See Also
XmTextClearSelection(1), XmTextCopy(1), XmTextCut(1),
XmTextGetSelection(1), XmTextGetSelectionPosition(1),
XmTextGetSelectionWcs(1), XmTextRemove(1), XmText(2),
XmTextField(2).
Motif Reference Manual
495
Motif Functions and Macros
Name
XmTextSetSource – set the text source.
Synopsis
#include <Xm/Text.h>
void XmTextSetSource (Widget
XmTextSource
XmTextPosition
XmTextPosition
Inputs
widget
source
top_character
widget.
cursor_position
widget,
source,
top_character,
cursor_position)
Specifies the Text widget.
Specifies the text source.
Specifies the character position to display at the top of the
Specifies the position of the insertion cursor.
Description
XmTextSetSource() sets the source of the specified Text widget. The
top_character and cursor_position values specify positions as the number of
characters from the beginning of the text, where the first character position is 0
(zero). If source is NULL, the Text widget creates a default string source and displays a warning message.
Usage
Multiple text widgets can share the same text source, which means that editing in
one of the widgets is reflected in all of the others. XmTextGetSource()
retrieves the source for a widget; this source can then be used to set the source of
another Text widget using XmTextSetSource(). XmTextSetSource() is a
convenience routine that sets the value of the XmNsource resource for the Text
widget. Calling the routine is equivalent to calling XtSetValues() for the
resource, although the routine accesses the value through the widget instance
structures rather than through XtSetValues().
When a new text source is set, the old text source is destroyed unless another Text
widget is using the old source. If you want to replace a text source without
destroying it, create an unmanaged Text widget and set its source to the text
source you want to save.
See Also
XmTextGetSource(1), XmText(2).
Motif Reference Manual
496
Motif Functions and Macros
Name
XmTextSetString, XmTextFieldSetString – set the text string.
Synopsis
#include <Xm/Text.h>
void XmTextSetString (Widget widget, char *value)
#include <Xm/TextF.h>
void XmTextFieldSetString (Widget widget, char *value)
Inputs
widget
value
Specifies the Text or TextField widget.
Specifies the string value.
Description
XmTextSetString() and XmTextFieldSetString() set the current text
string in the specified widget to the specified value. XmTextSetString()
works when widget is a Text widget or a TextField widget, while XmTextFieldSetString() only works for a TextField widget. Both functions also
set the position of the insertion cursor to the beginning of the new text string.
XmTextSetString() and XmTextFieldSetString() invoke the callback
routines for the XmNvalueChangedCallback, the XmNmodifyVerifyCallback,
and the XmNmodifyVerifyCallbackWcs callbacks for the specified widget. If
both verification callbacks are present, the XmNmodifyVerifyCallback procedures are invoked first and the results are passed to the XmNmodifyVerifyCallbackWcs procedures. The routines also invoke the callback routines for the
XmNmotionVerifyCallback for the specified widget.
Usage
XmTextSetString() and XmTextFieldSetString() are convenience
routines that set the value of the XmNvalue resource for a Text or TextField
widget. Calling one of the routines is equivalent to calling XtSetValues() for
the resource, although the routines access the value through the widget instance
structures rather than through XtSetValues().
Example
The following code shows the use of XmTextSetString() in a routine that
displays the contents of file in a Text widget. The filename is specified by the user
in a TextField widget:
Widget text_w, file_w;
void read_file (void)
Motif Reference Manual
497
Motif Functions and Macros
{
char
struct stat
int
*filename, *text;
statb;
fd, len;
if (!(filename = XmTextFieldGetString (file_w)) || !*filename) {
XtFree (filename);
return;
}
if (!(fd = open (filename, O_RDONLY))) {
XtWarning ("internal error -- can’t open file");
}
if (fstat (fd, &statb) == -1 || !(text = XtMalloc ((len = statb.st_size) + 1))) {
XtWarning("internal error -- can’t show text");
(void) close (fd);
}
(void) read (fd, text, len);
text[len] = ‘\0’;
XmTextSetString (text_w, text);
XtFree (text);
XtFree (filename);
(void) close (fd);
}
See Also
XmTextGetString(1), XmTextGetStringWcs(1),
XmTextGetSubstring(1), XmTextGetSubstringWcs(1),
XmTextSetStringWcs(1), XmText(2), XmTextField(2).
Motif Reference Manual
498
Motif Functions and Macros
Name
XmTextSetStringWcs, XmTextFieldSetStringWcs – set the wide-character text
string.
Synopsis
#include <Xm/Text.h>
void XmTextSetStringWcs (Widget widget, wchar_t *wcstring)
#include <Xm/TextF.h>
void XmTextFieldSetStringWcs (Widget widget, wchar_t *wcstring)
Inputs
widget
wcstring
Specifies the Text or TextField widget.
Specifies the wide-character string value.
Availability
Motif 1.2 and later.
Description
XmTextSetStringWcs() and XmTextFieldSetStringWcs() set the
current wide-character text string in the specified widget to the specified
wcstring1. XmTextSetStringWcs() works when widget is a Text widget or a
TextField widget, while XmTextFieldSetStringWcs() only works for a
TextField widget. Both functions also set the position of the insertion cursor to
the beginning of the new text string.
XmTextSetStringWcs() and XmTextFieldSetStringWcs() invoke the
callback routines for the XmNvalueChangedCallback, the XmNmodifyVerifyCallback, and the XmNmodifyVerifyCallbackWcs callbacks for the specified
widget. If both verification callbacks are present, the XmNmodifyVerifyCallback
procedures are invoked first and the results are passed to the XmNmodifyVerifyCallbackWcs procedures. The routines also invoke the callback routines for the
XmNmotionVerifyCallback for the specified widget.
1.Erroneously given as string in 1st and 2nd editions.
Motif Reference Manual
499
Motif Functions and Macros
Usage
In Motif 1.2, the Text and TextField widgets support wide-character strings. The
resource XmNvalueWcs can be used to set the value of a Text or TextField
widget to a wide-character string. XmTextSetStringWcs() and XmTextFieldSetStringWcs() are convenience routines that set the value of the
XmNvalueWcs resource for a Text or TextField widget. Calling one of the routines is equivalent to calling XtSetValues() for the resource, although the routines access the value through the widget instance structures rather than through
XtSetValues().
See Also
XmTextGetString(1), XmTextGetStringWcs(1),
XmTextGetSubstring(1), XmTextGetSubstringWcs(1),
XmTextSetString(1), XmText(2), XmTextField(2).
Motif Reference Manual
500
Motif Functions and Macros
Name
XmTextSetTopCharacter – set the position of the first character of text that is displayed.
Synopsis
#include <Xm/Text.h>
void XmTextSetTopCharacter (Widget widget, XmTextPosition top_character)
Inputs
widget
Specifies the Text widget.
top_character Specifies the position that is to be displayed at the top of the
widget.
Description
XmTextSetTopCharacter() sets the value of the XmNtopCharacter
resource to top_character for the specified Text widget. If the XmNeditMode
resource is set to XmMULTI_LINE_EDIT, the routine scrolls the text so that the
line containing the character position specified by top_character appears at the
top of the widget, but does not shift the text left or right. Otherwise, the character
position specified by top_character is displayed as the first visible character in
the widget. top_character specifies a character position as the number of characters from the beginning of the text, where the first character position in 0 (zero).
Usage
XmTextSetTopCharacter() is a convenience routine that sets the value of
the XmNtopCharacter resource for a Text widget. Calling the routines is equivalent to calling XtSetValues() for the resource, although the routines accesses
the value through the widget instance structures rather than through XtSetValues().
See Also
XmTextGetCursorPosition(1),
XmTextGetInsertionPosition(1), XmTextGetLastPosition(1),
XmTextGetTopCharacter(1), XmTextScroll(1),
XmTextSetCursorPosition(1),
XmTextSetInsertionPosition(1), XmTextShowPosition(1),
XmText(2).
Motif Reference Manual
501
Motif Functions and Macros
Name
XmTextShowPosition, XmTextFieldShowPosition – display the text at a specified position.
Synopsis
#include <Xm/Text.h>
void XmTextShowPosition (Widget widget, XmTextPosition position)
#include <Xm/TextF.h>
void XmTextFieldShowPosition (Widget widget, XmTextPosition position)
Inputs
widget
position
Specifies the Text or TextField widget.
Specifies the character position that is to be displayed.
Description
XmTextShowPosition() and XmTextFieldShowPosition() cause the
text character at position to be displayed in the specified widget. XmTextShowPosition() works when widget is a Text widget or a TextField widget, while
XmTextFieldShowPosition() only works for a TextField widget. The
position argument specifies the position as the number of characters from the
beginning of the text, where the first character position in 0 (zero).
Usage
XmTextShowPosition() and XmTextFieldShowPosition() provide a
way to force a Text or TextField widget to display a certain portion of its text.
This routine is useful if you modify the value of widget and want the modification to be immediately visible without the user having to scroll the text. If the
value of the XmNautoShowCursorPosition resource is True, you should set the
insertion cursor to position as well. You can set the insertion cursor by setting the
XmNcursorPosition1 resource or by using XmTextSetInsertionPosition() or XmTextFieldSetInsertionPosition().
1.Erroneously given as XmcursorPosition in 1st and 2nd editions.
Motif Reference Manual
502
Motif Functions and Macros
Example
The following code shows the use of XmTextShowPosition() in a routine
that inserts a message into a status Text widget:
Widget status;
void insert_text (char *message)
{
XmTextPosition curpos = XmTextGetInsertionPosition (status);
XmTextInsert (status, curpos, message);
curpos = curpos + strlen (message);
XmTextShowPosition (status, curpos);
XmTextSetInsertionPosition (status, curpos);
}
See Also
XmTextGetCursorPosition(1),
XmTextGetInsertionPosition(1),
XmTextSetCursorPosition(1),
XmTextSetInsertionPosition(1), XmText(2), XmTextField(2).
Motif Reference Manual
503
Motif Functions and Macros
Name
XmTextXYToPos, XmTextFieldXYToPos – get the character position for an x, y
position.
Synopsis
#include <Xm/Text.h>
XmTextPosition XmTextXYToPos (Widget widget, Position x, Position y)
#include <Xm/TextF.h>
XmTextPosition XmTextFieldXYToPos (Widget widget, Position x, Position y)
Inputs
widget
x
widget.
y
widget.
Specifies the Text or TextField widget.
Specifies the x-coordinate relative to the upper-left corner of the
Specifies the y-coordinate relative to the upper-left corner of the
Returns
The character position that is closest to the x, y position.
Description
XmTextXYToPos() and XmTextFieldXYToPos() return the position of the
character closest to the specified x and y coordinates within the specified widget.
XmTextXYToPos() works when widget is a Text widget or a TextField widget,
while XmTextFieldXYToPos() only works for a TextField widget. The x and
y coordinates are relative to the upper-left corner of the widget. Character positions are numbered sequentially, starting with 0 (zero) at the beginning of the
text.
Usage
XmTextXYToPos() and XmTextFieldXYToPos() provide a way to determine the character at a particular coordinate in a Text or TextField widget. This
information is useful if you need to perform additional event processing or draw
special graphics in the widget.
See Also
XmTextPosToXY(1), XmText(2), XmTextField(2).
Motif Reference Manual
504
Motif Functions and Macros
Name
XmToggleButtonGetState, XmToggleButtonGadgetGetState – get the state of a
ToggleButton.
Synopsis
#include <Xm/ToggleB.h>
Boolean XmToggleButtonGetState (Widget widget)
#include <Xm/ToggleBG.h>
Boolean XmToggleButtonGadgetGetState (Widget widget)
Inputs
widget
Specifies the ToggleButton or ToggleButtonGadget.
Returns
The state of the button.
Description
XmToggleButtonGetState() and XmToggleButtonGadgetGetState() return the state of the specified widget. XmToggleButtonGetState() works when widget is a ToggleButton or a ToggleButtonGadget, while
XmToggleButtonGadgetGetState() only works for a ToggleButtonGadget. In Motif 1.2 and earlier, each of the routines returns True if the button is
selected or False if the button is unselected.
In Motif 2.0 and later, a Toggle can be in any of three states: XmSET, XmINDETERMINATE, and XmUNSET, where XmUNSET is equivalent to False and
XmSET is equivalent to True. The third indeterminate state is enabled if the
Motif 2.x XmNtoggleMode resource of the widget is set to the value
XmTOGGLE_INDETERMINATE. If the toggle mode is
XmTOGGLE_BOOLEAN, the widget has only two dynamic states, which is
consistent with Motif 1.2 behavior.
Usage
XmToggleButtonGetState() and XmToggleButtonGadgetGetState() are convenience routines that return the value of the XmNset resource
for a ToggleButton or ToggleButtonGadget. Calling one of the routines is equivalent to calling XtGetValues() for the resource, although the routines access
the value through the widget instance structures rather than through XtGetValues().
Motif Reference Manual
505
Motif Functions and Macros
Because XmToggleButtonGetState() returns the toggle set element of its
widget instance structure directly, and because XmINDETERMINATE is neither
True nor False, programs relying on the strictly Boolean nature of XmToggleButtonGetState() are at risk of error if the toggle is configured for three
states. Setting tri-state toggles using a convenience function should be performed
using XmToggleButtonSetValue().
See Also
XmToggleButtonSetState(1), XmToggleButtonSetValue(1),
XmToggleButton(2), XmToggleButtonGadget(2).
Motif Reference Manual
506
Motif Functions and Macros
Name
XmToggleButtonSetState, XmToggleButtonGadgetSetState – set the state of a
ToggleButton.
Synopsis
#include <Xm/ToggleB.h>
void XmToggleButtonSetState (Widget widget, Boolean state, Boolean notify)
#include <Xm/ToggleBG.h>
void XmToggleButtonGadgetSetState (Widget widget, Boolean state, Boolean
notify)
Inputs
widget
state
notify
Specifies the ToggleButton or ToggleButtonGadget.
Specifies the state of the button.
Specifies whether or not the XmNvalueChangedCallback is called.
Description
XmToggleButtonSetState() and XmToggleButtonGadgetSetState() set the state of the specified widget. XmToggleButtonSetState()
works when widget is a ToggleButton or a ToggleButtonGadget, while XmToggleButtonGadgetSetState() only works for a ToggleButtonGadget. In
Motif 1.2 and earlier, if state is True, the button is selected, and when state is
False, the button is deselected.
In Motif 2.0 and later, a Toggle can be in any of three states: XmSET, XmINDETERMINATE, and XmUNSET, where XmUNSET is equivalent to False and
XmSET is equivalent to True. The third indeterminate state is enabled if the
Motif 2.x XmNtoggleMode resource of the widget is set to the value
XmTOGGLE_INDETERMINATE. If the toggle mode is
XmTOGGLE_BOOLEAN, the widget has only two dynamic states, which is
consistent with Motif 1.2 behavior.
If notify is True, the routines invoke the callbacks specified by the XmNvalueChangedCallback resource. If the specified widget is the child of a RowColumn with XmNradioBehavior set to True, the currently selected child of the
RowColumn is deselected.
Motif Reference Manual
507
Motif Functions and Macros
Usage
XmToggleButtonSetState() and XmToggleButtonGadgetSetState() are convenience routines that set the value of the XmNset resource for a
ToggleButton or ToggleButtonGadget. Calling one of the routines is equivalent to
calling XtSetValues() for the resource, although the routines access the value
through the widget instance structures rather than through XtSetValues().
In Motif 2.0 and later, passing the value XmINDETERMINATE is mapped to
XmSET. It is therefore not possible to set the XmINDETERMINATE state
using XmToggleButtonSetState(). To set a Toggle into an indeterminate state
through the convenience functions, call XmToggleButtonSetValue() or
XmToggleButtonGadgetSetValue().
See Also
XmToggleButtonGetState(1), XmToggleButtonSetValue(1),
XmToggleButton(2), XmToggleButtonGadget(2).
Motif Reference Manual
508
Motif Functions and Macros
Name
XmToggleButtonSetValue, XmToggleButtonGadgetSetValue – set the value of a
ToggleButton.
Synopsis
#include <Xm/ToggleB.h>
Boolean XmToggleButtonSetValue (Widget widget, XmToggleButtonState state,
Boolean notify)
#include <Xm/ToggleBG.h>
Boolean XmToggleButtonGadgetSetValue ( Widget
XmToggleButtonState
Boolean
Inputs
widget
state
notify
widget,
state,
notify)
Specifies the ToggleButton or ToggleButtonGadget.
Specifies the state of the button.
Specifies whether or not the XmNvalueChangedCallback is called.
Availability
Motif 2.0 and later.
Description
XmToggleButtonSetValue() and XmToggleButtonGadgetSetValue() are similar to XmToggleButtonSetState() and XmToggleButtonGadgetSetState(), except that it is possible to set the ToggleButton into
an XmINDETERMINATE state, provided that the Toggle is in the correct mode.
If the widget has the XmNtoggleMode resource of
XmTOGGLE_INDETERMINATE, the routine sets the XmNset resource of the
widget to the required state, calls any XmNvalueChangedCallback procedures if
notify is True, and then returns True. Otherwise, the function returns False.
Usage
XmToggleButtonSetValue() and XmToggleButtonGadgetSetValue() are convenience routines that set the value of the XmNset resource for a
ToggleButton or ToggleButtonGadget which can display an indeterminate state.
Calling one of the routines is equivalent to calling XtSetValues() for the
resource, although the routines access the value through the widget instance
structures rather than through XtSetValues().
Motif Reference Manual
509
Motif Functions and Macros
Structures
The XmToggleButtonState type has the following possible values:
XmSET
XmUNSET
XmINDETERMINATE
See Also
XmToggleButtonGetState(1), XmToggleButtonSetState(1),
XmToggleButton(2), XmToggleButtonGadget(2).
Motif Reference Manual
510
Motif Functions and Macros
Name
XmTrackingEvent – allow for modal selection of a component.
Synopsis
#include <Xm/Xm.h>
Widget XmTrackingEvent (Widget widget, Cursor cursor, Boolean confine_to,
XEvent *event_return)
Inputs
widget
cursor
confine_to
Specifies the widget in which the modal interaction occurs.
Specifies the cursor that is to be used as the pointer.
Specifies whether or not the pointer is confined to widget.
Outputs
event_return Returns the ButtonRelease or KeyRelease event.
Returns
The widget or gadget that contains the pointer or NULL if no widget or gadget
contains the pointer.
Availability
Motif 1.2 and later.
Description
XmTrackingEvent() grabs the pointer and waits for the user to release BSelect or press and release a key, discarding all of the intervening events. The routine returns the ID of the widget or gadget containing the pointer when BSelect or
the key is released and event_return contains the release event. If no widget or
gadget contains the pointer when the release occurs, the function returns NULL.
The modal interaction occurs within the specified widget, which is typically a
top-level shell. During the interaction, cursor is used as the pointer shape. If
confine_to is True, the pointer is confined to widget during the interaction; otherwise the pointer is not confined.
Usage
XmTrackingEvent() provides a way to allow a user to select a component.
This modal interaction is meant to support a context-sensitive help system, where
the user clicks on a widget to obtain more information about it. XmTrackingEvent() returns the selected widget, so that a help callback can be invoked to
provide the appropriate information.
Motif Reference Manual
511
Motif Functions and Macros
Example
The following code shows the use of XmTrackingEvent() in a routine that
initiates context-sensitive help:
Widget toplevel, help_button;
...
XtAddCallback (help_button, XmNactivateCallback, query_for_help, toplevel);
...
void query_for_help (Widget widget, XtPointer client_data, XtPointer call_data)
{
Cursor
cursor;
Widget
top, help_widget;
XmAnyCallbackStruct
cb;
XtCallbackStatus
hascb;
XEvent
*event;
top = (Widget) client_data;
cursor = XCreateFontCursor (XtDisplay (top), XC_question_arrow);
help_widget = XmTrackingEvent (top, cursor, True, &event);
while (help_widget != NULL) {
hascb = XtHasCallbacks (help_widget, XmNhelpCallback);
if (hascb == XtCallbackHasSome) {
cb.reason = XmCR_HELP;
cb.event = event;
XtCallCallbacks (help_widget, XmNhelpCallback, (XtPointer)
&cb);
help_widget = NULL;
}
else
help_widget = XtParent (help_widget);
}
}
See Also
XmTrackingLocate(1).
Motif Reference Manual
512
Motif Functions and Macros
Name
XmTrackingLocate – allow for modal selection of a component.
Synopsis
Widget XmTrackingLocate (Widget widget, Cursor cursor, Boolean confine_to)
Inputs
widget
cursor
confine_to
Specifies the widget in which the modal interaction occurs.
Specifies the cursor that is to be used as the pointer.
Specifies whether or not the pointer is confined to widget.
Returns
The widget or gadget that contains the pointer or NULL if no widget or gadget
contains the pointer.
Availability
In Motif 1.2, XmTrackingLocate() is obsolete. It has been superseded by
XmTrackingEvent().
Description
XmTrackingLocate() grabs the pointer and waits for the user to release BSelect or press and release a key, discarding all of the intervening events. The routine returns the ID of the widget or gadget containing the pointer when BSelect or
the key is released. If no widget or gadget contains the pointer when the release
occurs, the function returns NULL. The modal interaction occurs within the
specified widget, which is typically a top-level shell. During the interaction, cursor is used as the pointer shape. If confine_to is True, the pointer is confined to
widget during the interaction; otherwise the pointer is not confined. XmTrackingLocate() is retained for compatibility with Motif 1.1 and should not be
used in newer applications.
Usage
XmTrackingLocate() provides a way to allow a user to select a component.
This modal interaction is meant to support a context-sensitive help system, where
the user clicks on a widget to obtain more information about it. XmTrackingLocate() returns the selected widget, so that a help callback can be invoked to
provide the appropriate information.
See Also
XmTrackingEvent(1).
Motif Reference Manual
513
Motif Functions and Macros
Name
XmTransfer – introduction to the uniform transfer model.
Synopsis
Public Header:
<Xm/Transfer.h>
Functions/Macros:
XmTransferDone(), XmTransferSendRequest(), XmTransferSetParameters(),
XmTransferStartRequest(), XmTransferValue().
Availability
Motif 2.0 and later.
Description
Motif widgets support several methods of data transfer. Data can be transferred
from a widget to the Primary or Secondary selection, the Clipboard, or, through
the drag and drop mechanisms, to another widget. Up until Motif 2.0, each of
these data transfer operations require a different treatment by the programmer. In
Motif 2.0 and later, the Uniform Transfer Model (UTM) makes it possible to perform data transfer using any of the transfer methods using a single programming
interface. UTM is designed to allow applications to use common code for all the
supported data transfer requirements, and is intentionally written to ease the way
in which new transfer targets can be written. Data transfer code written prior to
Motif 2.0 will continue to work in newer versions of the toolkit, although all the
widgets have been rewritten to internally use the UTM where appropriate.
The UTM is implemented through two new callback resources: XmNconvertCallback, and XmNdestinationCallback, which are available in the Primitive widget
class (and in any derived classes), as well as in the Container, Scale, and DrawingArea widget classes. The programmer provides XmNconvertCallback and
XmNdestinationCallback procedures which communicate with one another in
order to negotiate the target format in which the data is required. In addition, the
programmer provides a transfer procedure which performs the insertion of data in
the right format into the destination widget.
An XmNconvertCallback procedure is associated with the source of the data. It is
responsible for converting the data, typically the selected items of the source
widget, into the format requested by the destination. It may also provide a list of
the supported transfer targets requested by a XmNdestinationCallback procedure.
The convert procedure transfers data to the destination widget by placing values
within the XmConvertCallbackStruct structure passed as a parameter to the callback.
Motif Reference Manual
514
Motif Functions and Macros
The XmNdestinationCallback procedure is responsible for negotiating the format
in which data is required at the destination widget. It may request the set of supported formats in which the source can export the data, although the simplest procedure requests data in a specific target format. In specifying the request to the
source of the data, the callback specifies a further transfer procedure which performs the actual insertion of data at the destination. The destination callback
communicates with the source by issuing requests using the XmTransferValue() routine. If the destination callback requests the full list of supported
source targets, the transfer procedure itself decides the best format for the destination, and internally issues a further XmTransferValue() call, requesting the
data in a specific target format. The programmer will have to provide the logic
which determines the best format within the transfer procedure.
Usage
It is not necessary for the programmer to provide XmNconvertCallback and
XmNdestinationCallback procedures for all the targets which Motif supports. As
part of the UTM, Motif widgets which support the XmNconvertCallback and
XmNdestinationCallback resources also have internal routines which enable
automatic data transfer of a set of built-in target types. The internal routines are
implemented using the XmQTtransfer trait, which has convertProc and destinationProc methods. Where no XmNconvertCallback is supplied by the programmer, the convertProc is invoked to perform the data conversion. Similarly, in the
absence of a XmNdestinationCallback, UTM calls the destinationProc. A programmer only needs to implement XmNconvertCallback or XmNdestinationCallback procedures where a new target type is being provided over and above
those handled by the widget class default procedures.
Structures
A pointer to the following structure is passed to callbacks on the XmNconvertCallback list:
typedef struct {
int
invoked
XEvent
back
Atom
requested
Atom
XtPointer
XtPointer
transferred
int
Motif Reference Manual
reason;
*/
*event;
*/
selection;
*/
target;
source_data;
location_data;
*/
flags;
/* the reason that the callback is
/* points to event that triggered call/* selection for which conversion is
/* the conversion target */
/* selection source information */
/* information about the data to be
/* input status of the conversion*/
515
Motif Functions and Macros
XtPointer
int
unsigned long
parm;
parm_format;
parm_length;
data
*/
Atom
parm_type;
int
status;
XtPointer
value;
Atom
type;
int
format;
unsigned long
length;
sion data
*/
} XmConvertCallbackStruct;
/* parameter data for the target*/
/* format of parameter data*/
/* number of elements in parameter
/* the type of the parameter data*/
/* output status of the conversion*/
/* returned conversion data*/
/* type of conversion data returned*/
/* format of the conversion data*/
/* number of elements in the conver-
selection represents the selection for which conversion is requested. CLIPBOARD, PRIMARY, SECONDARY, or _MOTIF_DROP are the possible values
(that is, one of the types of data transfer which the UTM rationalizes).
target represents the required format for the data to transfer, expressed as an
Atom.
source_data provides data related to the source of the selection. If selection is
_MOTIF_DROP, then source_data points to a DragContext object, otherwise it is
NULL.
location_data specifies where the data to be converted is to be found. If
location_data is NULL, conversion data is interpreted as the widget’s current
selection. Otherwise, the interpretation of location_data is widget class specific.
flags specifies the current status of the conversion. Possible values of the enumerated type:
XmCONVERTING_NONE
XmCONVERTING_PARTIAL
converted
XmCONVERTING_SAME
transfer data
XmCONVERTING_TRANSACT
*/
/* unused
/* some, but not all, of target data is
*/
/* conversion target is source of the
*/
*/
/* unused
parm contains extra data associated with target. If target is the Atom represented
by _MOTIF_CLIPBOARD_TARGETS or
_MOTIF_DEFERRED_CLIPBOARD_TARGETS, then parm is one of
XmCOPY, XmMOVE, or XmLINK. parm is an array of data items, the number
of such items is specified by parm_length, and the type of each item by
parm_format.
Motif Reference Manual
516
Motif Functions and Macros
parm_format specifies whether the data within parm is represented by a list of
char, short, or long quantities. If parm_format is 0 (zero), parm is NULL. A
parm_format value of 8 indicates parm is logically a list of char, 16 represents a
list of short quantities, and 32 is for a list of long values. parm_format indicates
logical type, and not physical implementation: a parm_format of 32 indicates a
list of long quantities even if a particular machine has 64-bit longs.
parm_length specifies the number of data items at the parm address.
parm_type specifies the type of the parm data, expressed as an Atom. The default
is XA_INTEGER.
status specifies the status of the conversion. The initial (default) value is
XmCONVERT_DEFAULT, which, if unchanged by the callback, invokes any
conversion procedures associated with the widget class when the callback finishes. These are the convertProc methods of any XmQTtransfer trait which the
widget holds. Any converted data produced by a widget class routine overwrites
any data from the callback. If the callback sets status to
XmCONVERT_MERGE, widget class conversion procedures are invoked, merging any data so produced with conversion data from the callback. A returned status of XmCONVERT_REFUSE indicates that the callback terminates the
conversion process without completion, and no widget class procedures are to be
invoked. XmCONVERT_DONE similarly results in no widget class procedure
invocation, except that the callback indicates that conversion has been successfully completed.
value is where the callback places the result of the conversion process. The
default is NULL. It is assumed that any value specified is dynamically allocated
by the programmer, although the programmer must not subsequently free the
value: this is performed by the UTM. It is the responsibility of the programmer to
ensure that the type, format, and length elements are appropriately set to match
any data placed in value.
type specifies the logical type of any data returned within value, expressed as an
Atom.
format specifies whether the data within value is represented by a list of char,
short, or long quantities. If format is 0 (zero), value is NULL. A format value of 8
indicates value is logically a list of char, 16 represents a list of short quantities,
and 32 is for a list of long values. format indicates logical type, and not physical
implementation: a format of 32 indicates a list of long values even if they are
actually 64 bits.
length specifies the number of data items at the value address.
Motif Reference Manual
517
Motif Functions and Macros
Callbacks on the XmNdestinationCallback list are passed a pointer to the following structure:
typedef struct {
int
reason;
XEvent
*event;
Atom
selection;
XtEnum
operation;
int
flags;
*/
XtPointer
transfer_id;
XtPointer
destination_data;
XtPointer
location_data;
Time
time;
} XmDestinationCallbackStruct;
/* reason that the callback is invoked
*/
/* points to event that triggered callback */
/* the requested selection type, as an Atom */
/* the type of transfer requested
*/
/* whether destination and source are the same
/* unique identifier for the request
*/
/* information about the destination
*/
*/
/* information about the data
/* time when transfer operation started
*/
selection specifies, as an Atom, the type of selection for which data transfer is
required. CLIPBOARD, PRIMARY, SECONDARY, or _MOTIF_DROP are the
possible logical values.
operation indicates the type of data transfer operation requested. The possible
values are:
XmCOPY
XmMOVE
XmLINK
XmOTHER
/* copy transfer */
/* move transfer */
/* link transfer */
/* information contained within destination_data element */
If operation is XmOTHER, destination_data contains a pointer to an XmDropProcCallbackStruct, which contains an operation element. See XmDropSite for
more information concerning the XmDropProcCallbackStruct.
flags indicates whether the source of the transfer data is also the destination. Possible values are:
XmCONVERTING_NONE /* destination is not the source of the data */
XmCONVERTING_SAME /* destination is the source of the data */
transfer_id specifies a unique identifier for the current transfer request.
destination_data specifies information about the destination of the transfer operation. If the selection is _MOTIF_DROP, then the callback has been invoked by
an XmDropProc of the drop site, and destination_data contains a pointer to an
XmDropProcCallbackStruct. If the selection is SECONDARY, destination_data
is an Atom representing a target type into which the selection owner suggests the
transfer should be converted. Otherwise, destination_data is NULL.
Motif Reference Manual
518
Motif Functions and Macros
location_data determines where the data is to be transferred. The interpretation
varies between the widget classes. In the Container widget, the value of
location_data is a pointer to an XPoint structure, containing the x and y coordinates of the transfer location. If location_data is NULL, data is to be transferred
to the current cursor location for the widget.
time is the server time when the transfer operation was initiated.
Transfer procedures are passed a pointer to the following structure: the interpretation of the elements is the same as those in the callbacks described above.
typedef struct {
int
reason;
*/
XEvent
*event;
*/
Atom
selection;
*/
Atom
target;
*/
Atom
type;
*/
XtPointer
transfer_id;
*/
int
flags;
*/
int
remaining;
*/
XtPointer
value;
*/
unsigned long length;
*/
int
format;
*/
} XmSelectionCallbackStruct;
/* reason that the callback is invoked
/* points to event that triggered callback
/* the requested selection type, as an Atom
/* the conversion target
/* type of conversion data returned
/* unique identifier for the request
/* whether destination and source are same
/* number transfers remaining for transfer_id
/* returned conversion data
/* number of elements in conversion data
/* format of the conversion data
Example
The following is a specimen XmNdestinationCallback which simply requests
from the source the list of export targets, and which specifies a transfer procedure
for handling the data import.
void destination_handler (Widget w, XtPointer client_data, XtPointer call_data)
{
Motif Reference Manual
519
Motif Functions and Macros
XmDestinationCallbackStruct *dptr = (XmDestinationCallbackStruct *)
call_data;
Atom TARGETS = XmInternAtom (XtDisplay (w), "TARGETS", False);
/* transfer procedure will issue a subsequent request */
/* for data in a specific target format. it receives */
/* the list of supported targets from the source. */
XmTransferValue (dptr->transfer_id, TARGETS, (XtCallbackProc)
transfer_procedure,
NULL, XtLastTimestampProcessed (XtDisplay (w))1);
}
The following specimen XmNconvertCallback procedure exports the selected
text within a Text widget: although the convertProc method associated with the
Text’s XmQTtransfer trait performs this task in a modified form, the code does
outline the basic structure required.
void convert_callback (Widget w, XtPointer client_data, XtPointer call_data)
{
XmConvertCallbackStruct *cptr = (XmConvertCallbackStruct *)
call_data;
Atom
TARGETS, CB_TARGETS,
SELECTED_TEXT;
Atom
targets[1];
Display
*display = XtDisplay (w);
TARGETS = XmInternAtom (display, "TARGETS", False);
CB_TARGETS = XmInternAtom (display,
"_MOTIF_CLIPBOARD_TARGETS", False);
SELECTED_TEXT = XmInternAtom (display, "SELECTED_TEXT",
False);
/* if the destination has requested the list of supported targets */
/* this is returned in the callback data
*/
if ((cptr->target == TARGETS) || (cptr->target == CB_TARGETS)) {
targets[0] = SELECTED_TEXT;
cptr->type = XA_ATOM;
cptr->value = (XtPointer) targets;
cptr->length = 1;
cptr->format = 32;
/* merge the data with the list of targets supported by */
/* the convertProc method of the XmQTtransfer trait */
1.Erroneously given as XtLastTimestampProcessed() in 2nd edition.
Motif Reference Manual
520
Motif Functions and Macros
cptr->status = XmCONVERT_MERGE;
}
else {
if (cptr->target == SELECTED_TEXT) {
char *selection = XmTextGetSelection (w);
/* destination has requested the new target */
cptr->value = selection;
/* exported target is the requested target */
cptr->type = cptr->target;
cptr->format = 8;
cptr->length = (selection ? strlen (selection) : 0);
/* conversion complete */
cptr->status = XmCONVERT_DONE;
}
else {
/* target is one this procedure is not handling
*/
/* result is either XmCONVERT_MERGE or
XmCONVERT_DEFAULT */
/* depending on whether we throw away results from any */
/* other convert callback we have registered. */
/* the default is XmCONVERT_DEFAULT */
return XmCONVERT_MERGE;1
}
}
return XmCONVERT_MERGE;2
}
The following is a specimen transfer procedure, which is registered by a
XmNdestinationCallback using XmTransferValue():
void transfer_procedure (Widget w, XtPointer client_data, XtPointer call_data)
{
XmSelectionCallbackStruct *sptr = (XmSelectionCallbackStruct *)
call_data;
Atom
TARGETS, CB_TARGETS,
SELECTED_TEXT;
Display
*display = XtDisplay (w);
1.The 2nd edition gave XmCONVERT_DEFAULT as the return value here. Since certain focus operations built into
the toolkit use the Uniform Transfer Model as mechanism, you need to inherit these, so XmCONVERT_MERGE is
the better value. Apologies..
2.As above.
Motif Reference Manual
521
Motif Functions and Macros
Atom
int
*targets, choice;
i;
choice = (Atom) 0;
TARGETS = XmInternAtom (display, "TARGETS", False);
CB_TARGETS = XmInternAtom (display,
"_MOTIF_CLIPBOARD_TARGETS", False); SELECTED_TEXT =
XmInternAtom (display, "SELECTED_TEXT", False);
if (((sptr->target == TARGETS) || (sptr->target == CB_TARGETS)) &&
(sptr->type == XA_ATOM)) {
/* destination callback requested list of targets from the source */
/* the source convertCallback returns the list. We now choose... */
targets = (Atom *) sptr->value;
for (i = 0; i < sptr->length; i++) {
if (targets[i] == SELECTED_TEXT) {
/* the source exports selected text. lets pick this one... */
choice = targets[i];
}
}
/* There’s no selection we like... */
if (choice == (Atom) 0) {
XmTransferDone (sptr->transfer_id,
XmTRANSFER_DONE_FAIL);
return;
}
/* now go back to source and ask for the data in format of choice */
/* might as well use ourself again as transfer procedure...
*/
XmTransferValue (sptr->transfer_id, choice, /* Preferred
SELECTED_TEXT target */
transfer_procedure, NULL, XtLastTimestampProcessed (display)1);
}
else if (sptr->target == SELECTED_TEXT) {
/* insert the selected text at our own insertion point */
XmTextPosition pos = XmTextGetInsertionPosition (w);
XmTextInsert (w, pos, (char *) sptr->value);
/* all done */
1.Erroneously given as XtLastTimestampProcessed() in 2nd edition.
Motif Reference Manual
522
Motif Functions and Macros
XmTransferDone (sptr->transfer_id,
XmTRANSFER_DONE_SUCCEED);
}
}
See Also
XmTransferDone(1), XmTransferSendRequest(1),
XmTransferSetParameters(1), XmTransferStartRequest(1),
XmTransferValue(1), XmContainer(2), XmDrawingArea(2),
XmPrimitive(2), XmScale(2).
Motif Reference Manual
523
Motif Functions and Macros
Name
XmTransferDone – complete a data transfer operation.
Synopsis
#include <Xm/Transfer.h>
void XmTransferDone (XtPointer transfer_id, XmTransferStatus status)
Inputs
transfer_id
status
Specifies a unique identifier for the transfer operation.
Specifies the completion status of the transfer.
Availability
Motif 2.0 and later.
Description
Under the Uniform Transfer Model, XmTransferDone() completes a data
transfer operation. The procedure is called from destination callbacks or transfer
procedures in order to signal the end of data transfer back to the source of the
data.
transfer_id uniquely identifies a transfer operation, and the value is supplied
either from the transfer_id element of a XmDestinationCallbackStruct passed to
the destination callback, or from the transfer_id element of a XmSelectionCallbackStruct passed to a transfer procedure. status is set to indicate the status of the
current transfer operation, which is notified back to the selection owner.
status is one of XmTRANSFER_DONE_FAIL,
XmTRANSFER_DONE_SUCCEED, XmTRANSFER_DONE_CONTINUE, or
XmTRANSFER_DONE_DEFAULT. The status
XmTRANSFER_DONE_DEFAULT ignores all remaining queued transfer operations which may have been initiated within the destination callbacks and
invokes the widget class default transfer procedures. That is, any unprocessed
multiple batched requests created between XmTransferStartRequest()
and XmTransferSendRequest()1 calls are skipped. If status is
XmTRANSFER_DONE_FAIL, the XmNtransferStatus of the current DropTransfer object is set to XmTRANSFER_FAILURE.
XmTRANSFER_DONE_SUCCEED and XmTRANSFER_DONE_CONTINUE
are similar, except that with XmTRANSFER_DONE_CONTINUE the owner of
the selection is not notified if the target is _MOTIF_SNAPSHOT.
1.Erroneously given as XmTransferEndRequest() in 2nd edition.
Motif Reference Manual
524
Motif Functions and Macros
Usage
The Uniform Transfer Model (UTM) enhances the Motif 1.2 data transfer mechanisms by providing a standard interface through which Drag and Drop, Primary
and Secondary selection, and Clipboard data transfer is achieved both to and
from a widget. The implementation of the UTM is through XmNconvertCallback
and XmNdestinationCallback resource procedures. A convert callback is associated with the source of the data, and it is responsible for exporting data in the format required by the destination widget.
The destination callback is responsible for requesting data from the source in the
format which it requires, and it calls the function XmTransferValue() to do
this. The destination callback typically does not import the data directly, but
specifies a transfer procedure to perform the insertion of data at the destination
widget. The transfer procedure is specified by passing a routine as a parameter to
the XmTransferValue() call. When the transfer is finished, either because it
is completed or because it is aborted due to an error, the transfer procedure calls
XmTransferDone() to return the status to the source.
Structures
The XmTransferStatus type has the following possible values:
XmTRANSFER_DONE_CONTINUE
XmTRANSFER_DONE_DEFAULT
XmTRANSFER_DONE_FAIL
XmTRANSFER_DONE_SUCCEED
Example
The following specimen transfer procedure calls XmTransferDone() to indicate the status of the data drop:
void transfer_procedure (Widget w, XtPointer client_data, XtPointer call_data)
{
XmSelectionCallbackStruct *sptr = (XmSelectionCallbackStruct *)
call_data;
Atom
TARGETS, CB_TARGETS,
IMPORT_FORMAT;
Display
*display = XtDisplay (w);
Atom
*targets, choice;
int
i;
TARGETS = XmInternAtom (display, "TARGETS", False);
CB_TARGETS = XmInternAtom (display,
"_MOTIF_CLIPBOARD_TARGETS", False);
Motif Reference Manual
525
Motif Functions and Macros
IMPORT_FORMAT = XmInternAtom (display, "IMPORT_FORMAT",
False);
if (((sptr->target == TARGETS) || (sptr->target == CB_TARGETS)) &&
(sptr->type == XA_ATOM)) {
/* destination callback requested list of targets from the source */
/* the source convertCallback returns the list. We now choose... */
targets = (Atom *) sptr->value;
choice = (Atom) 0;
for (i = 0; i < sptr->length; i++) {
if (targets[i] == IMPORT_FORMAT) {
/* the source exports our required target... */
choice = targets[i];
}
}
if (choice == (Atom) 0) {
/* source does not export what we require
*/
/* assume destinationProc in the XmQTtransferTrait */
/* does not either...
*/
XmTransferDone (sptr->transfer_id,
XmTRANSFER_DONE_FAIL);
return;
}
/* now go back to source and ask for the data in format of choice */
/* might as well use ourself again as transfer procedure...
*/
XmTransferValue (sptr->transfer_id, choice, /* IMPORT_FORMAT */
transfer_procedure, NULL, XtLastTimestampProcessed (display)1);
}
else if (sptr->target == IMPORT_FORMAT) {
/* perform whatever is required to import sptr->value */
...
/* all done */
XmTransferDone (sptr->transfer_id,
XmTRANSFER_DONE_SUCCEED);
}
else {
/* wrong export target */
1.Erroneously given as XtLastTimestampProcessed() in 2nd edition.
Motif Reference Manual
526
Motif Functions and Macros
XmTransferDone (sptr->transfer_id, XmTRANSFER_DONE_FAIL);
}
}
See Also
XmTransferSendRequest(1), XmTransferSetParameters(1),
XmTransferStartRequest(1), XmTransferValue(1),
XmTransfer(1), XmDropTransfer(1).
Motif Reference Manual
527
Motif Functions and Macros
Name
XmTransferSendRequest – send a multiple transfer request.
Synopsis
#include <Xm/Transfer.h>
void XmTransferSendRequest (XtPointer transfer_id, Time time)
Inputs
transfer_id
time
Specifies a unique identifier for the transfer operation.
Specifies the time of the transfer.
Availability
Motif 2.0 and later.
Description
In the Uniform Transfer Model, XmTransferSendRequest() marks the end
of a series of transfer requests started by XmTransferStartRequest().
transfer_id uniquely identifies a transfer operation, and the value is supplied
from the transfer_id element of a XmDestinationCallbackStruct or XmSelectionCallbackStruct passed to a destination callback or transfer procedure respectively. time specifies the time of the XEvent which initiated the data transfer.
XtLastTimestampProcessed() is the simplest method of specifying the
time value.
Usage
The Uniform Transfer Model (UTM) enhances the Motif 1.2 data transfer mechanisms by providing a standard interface through which Drag and Drop, Primary
and Secondary selection, and Clipboard data transfer is achieved both to and
from a widget. The implementation of the UTM is through XmNconvertCallback
and XmNdestinationCallback resource procedures. The destination callback is
responsible for requesting data from the source in the format which it requires,
and it calls the function XmTransferValue() to do this. A set of data transfer
requests can be queued by wrapping the series of XmTransferValue() calls
within XmTransferStartRequest() and XmTransferSendRequest()
calls.
See Also
XmTransferDone(1), XmTransferSetParameters(1),
XmTransferStartRequest(1), XmTransferValue(1),
XmTransfer(1).
Motif Reference Manual
528
Motif Functions and Macros
Name
XmTransferSetParameters – set parameters for next transfer
Synopsis
#include <Xm/Transfer.h>
void XmTransferSetParameters ( XtPointer
XtPointer
int
unsigned long
Atom
Inputs
transfer_id
parm
parm_format
parm_length
parm_type
transfer_id,
parm,
parm_format,
parm_length,
parm_type)
Specifies a unique identifier for the transfer operation.
Specifies parameters to be passed to conversion routines.
Specifies the format of data in the parm argument.
Specifies the number of elements within the parm data.
Specifies the type of parm.
Availability
Motif 2.0 and later.
Description
In the Uniform Transfer Model, XmTransferSetParameters() defines
parameter data for a subsequent XmTransferValue() call. transfer_id
uniquely identifies a transfer operation, and the value is supplied from the
transfer_id element of a XmDestinationCallbackStruct or XmSelectionCallbackStruct passed to a destination callback or transfer procedure respectively.
parm specifies parameter data to be passed to the conversion function, and the
XmNconvertCallback procedures, of the source widget which owns the selection.
parm_format specifies whether the data within parm consists of 8, 16, or 32 bit
quantities. parm_length specifies the number of elements, of size determined by
parm_format, which are at the address parm. parm_type specifies the logical type
of parm, and is application specific. Neither Motif, the X toolkit, nor the X
library interpret parm_type in any manner.
Motif Reference Manual
529
Motif Functions and Macros
Usage
The Uniform Transfer Model enhances the Motif 1.2 data transfer mechanisms
by providing a standard interface by which the source and destination of the data
transfer can communicate. The programmer provides XmNdestinationCallback
procedures which issue the request to transfer data from the source of the transfer
by calling XmTransferValue(). Any parameterized data for the XmTransferValue() procedure is established through a prior XmTransferSetParameters() call. XmTransferSetParameters() is a convenience function
which maps simply onto a X Toolkit Intrinsics XtSetSelectionParameters() call.
See Also
XmTransferDone(1), XmTransferSendRequest(1),
XmTransferStartRequest(1), XmTransferValue(1),
XmTransfer(1).
Motif Reference Manual
530
Motif Functions and Macros
Name
XmTransferStartRequest – initiate a multiple data transfer request
Synopsis
#include <Xm/Transfer.h>
void XmTransferStartRequest (XtPointer transfer_id)
Inputs
transfer_id
Specifies a unique identifier for the current data transfer operation.
Availability
Motif 2.0 and later.
Description
XmTransferStartRequest() initiates the start of a series of transfer
requests. transfer_id uniquely identifies a transfer operation, and the value is supplied from the transfer_id element of a XmDestinationCallbackStruct or XmSelectionCallbackStruct passed to a destination callback or transfer procedure
respectively.
Usage
In Motif 2.0 and later, the Uniform Transfer Model enhances the Motif 1.2 data
transfer mechanisms by providing a standard interface by which the source and
destination of the data transfer can communicate. A set of data transfer requests
can be queued by wrapping the series of requests within XmTransferStartRequest() and XmTransferSendRequest() calls. The procedure
XmTransferValue() provides the data transfer requests in the queue.
See Also
XmTransferDone(1), XmTransferSendRequest(1),
XmTransferSetParameters(1), XmTransferValue(1),
XmTransfer(1).
Motif Reference Manual
531
Motif Functions and Macros
Name
XmTransferValue – transfer data to a destination
Synopsis
#include <Xm/Transfer.h>
void XmTransferValue ( XtPointer
Atom
XtCallbackProc
XtPointer
Time
Inputs
transfer_id
tion.
target
callback
client_data
time
transfer_id,
target,
callback,
client_data,
time)
Specifies a unique identifier for the current data transfer operaSpecifies the target to which the selection is to be converted.
Specifies a transfer procedure to be called when the selection has
been converted by the source.
Specifies application data to be passed to callback.
Specifies the time of the transfer.
Availability
Motif 2.0 and later.
Description
The Uniform Transfer Model (UTM) enhances the Motif 1.2 data transfer mechanisms by providing a standard interface through which Drag and Drop, Primary
and Secondary selection, and Clipboard data transfer is achieved both to and
from a widget. The implementation of the UTM is through XmNconvertCallback
and XmNdestinationCallback resource procedures. A convert callback is associated with the source of the data, and it is responsible for exporting data in the format required by the destination. The destination callback is responsible for
requesting data from the source in the format which it requires, and it calls the
function XmTransferValue() to do this. The destination callback itself does
not typically insert the transferred data into the destination widget: it specifies a
transfer procedure, which performs the import, as a parameter to the XmTransferValue() call.
XmTransferValue() arranges to transfer data from the source of transfer data
to the destination. transfer_id uniquely identifies a transfer operation, and the
value is supplied from the transfer_id element of a XmDestinationCallbackStruct
or XmSelectionCallbackStruct passed to a destination or transfer callback
respectively.
Motif Reference Manual
532
Motif Functions and Macros
target specifies the selection which is to be converted and transferred. If target is
_MOTIF_DROP, the function invokes XmDropTransferStart() with internal transfer procedures to perform the data transfer. Otherwise, the data is
extracted from the selection using XtGetSelectionValue().
callback is a transfer procedure, which is an application procedure that is called
when the data is converted and available from the source. client_data is any data
which the programmer wants to be passed to the callback. The callback is
invoked with three parameters: the destination widget, the application
client_data, and a pointer to a XmSelectionCallbackStruct.
time specifies the time of the XEvent which initiated the data transfer. XtLastTimestampProcessed() is the simplest method of specifying the time value.
Usage
XmTransferValue() is called from destination callbacks or transfer procedures to effect the actual transfer of data from the source, whether that be the
clipboard or a widget. The programmer-defined callback replaces the XmNtransferProc added to a DropTransfer object, which the Uniform Transfer Model internally encapsulates and hides.
See Also
XmTransferDone(1), XmTransferSendRequest(1),
XmTransferSetParameters(1), XmTransferStartRequest(1),
XmTransfer(1), XmDropTransfer(2).
Motif Reference Manual
533
Motif Functions and Macros
Name
XmTranslateKey – convert a keycode to a keysym using the default translator.
Synopsis
#include <Xm/Xm.h>
void XmTranslateKey ( Display
KeyCode
Modifiers
Modifiers
KeySym
*display,
keycode,
modifiers,
*modifiers_return,
*keysym_return)
Inputs
display
Specifies a connection to an X server; returned from XOpenDisplay() or XtDisplay().
keycode
Specifies the keycode that is translated.
modifiers
Specifies the modifier keys that are applied to the keycode.
Outputs
modifiers_return
the keysym.
keysym_return
Returns the modifiers used by the key translator to generate
Returns the resulting keysym.
Availability
Motif 1.2 and later.
Description
XmTranslateKey() is the default XtKeyProc translation procedure used by
Motif applications. The routine takes a keycode and modifiers and returns the
corresponding osf keysym.
Usage
The Motif toolkit uses a mechanism called virtual bindings to map one set of
keysyms to another set. This mapping permits widgets and applications to use
one set of keysyms in translation tables; applications and users can then customize the keysyms used in the translations based on the particular keyboard that is
being used. Keysyms that can be used in this way are called osf keysyms. Motif
maintains a mapping between the osf keysyms and the actual keysyms that represent keys on a particular keyboard. See the introduction to Section 2, Motif and
Xt Widget and Classes, for more information about the mapping of osf keysyms
to actual keysyms.
Motif Reference Manual
534
Motif Functions and Macros
XmTranslateKey() is used by the X Toolkit during event processing to translate the keycode of an event to the appropriate osf keysym if there is a mapping
for the keysym. The event is then dispatched to the appropriate action routine if
there is a translation for the osf keysym.
If you need to provide a new translator with expanded functionality, you can call
XmTranslateKey() to get the default translation. Use XtSetKeyTranslator() to register a new key translator. To reinstall the default behavior, you can
call XtSetKeyTranslator() with XmTranslateKey() as the proc argument.
See Also
xmbind(4).
Motif Reference Manual
535
Motif Functions and Macros
Name
XmUninstallImage – remove an image from the image cache.
Synopsis
Boolean XmUninstallImage (XImage *image)
Inputs
image
Specifies the image structure to be removed.
Returns
True on success or False if image is NULL or it cannot be found.
Description
XmUninstallImage() removes the specified image from the image cache.
The routine returns True if it is successful. It returns False if image is NULL or if
image is not found in the image cache.
Usage
XmUninstallImage() removes an image from the image cache. Once an
image is uninstalled, it cannot be referenced again and a new image can be
installed with the same name. If you have created any pixmaps that use the
image, they are not affected by the image being uninstalled, since they are based
on image data, not the image itself. After an image has been uninstalled, you can
safely free the image.
See Also
XmDestroyPixmap(1), XmGetPixmap(1), XmInstallImage(1).
Motif Reference Manual
536
Motif Functions and Macros
Name
XmUpdateDisplay – update the display.
Synopsis
void XmUpdateDisplay (Widget widget)
Inputs
widget
Specifies any widget.
Description
XmUpdateDisplay() causes all pending exposure events to be processed
immediately, instead of having them remain in the queue until all of the callbacks
have been invoked.
Usage
XmUpdateDisplay() provides applications with a way to force an visual
update of the display. Because callbacks are invoked before normal exposure
processing occurs, when a menu or a dialog box is unposted, the display is not
updated until all of the callbacks have been called. This routine is useful whenever a time-consuming action might delay the redrawing of the windows on the
display.
See Also
XmDisplay(2).
Motif Reference Manual
537
Motif Functions and Macros
Name
XmVaCreateSimpleCheckBox – create a CheckBox compound object.
Synopsis
Widget XmVaCreateSimpleCheckBox ( Widget
String
XtCallbackProc
...,
NULL)
parent,
name,
callback,
Inputs
parent
Specifies the widget ID of the parent of the new widget.
name
Specifies the string name of the new widget for resource lookup.
callback
Specifies the callback procedure that is called when the value of a
button changes.
..., NULL
A NULL-terminated variable-length list of resource name/value
pairs.
Returns
The widget ID of the RowColumn widget.
Description
XmVaCreateSimpleCheckBox() is a RowColumn convenience routine that
creates a CheckBox with ToggleButtonGadgets as its children. This routine is
similar to XmCreateSimpleCheckBox(), but it uses a NULL-terminated variable-length argument list in place of the arglist and argcount parameters. The
variable-length argument list specifies resource name/value pairs as well as the
children of the CheckBox. The callback argument specifies the callback routine
that is added to the XmNvalueChangedCallback of each ToggleButtonGadget
child of the CheckBox. When the callback is invoked, the button number of the
button whose value has changed is passed to the callback in the client_data
parameter.
The name of each ToggleButtonGadget child is button_n, where n is the number
of the button, ranging from 0 (zero) to 1 less than the number of buttons in the
CheckBox. The buttons are created and named in the order in which they are
specified in the variable-length argument list.
Usage
A variable-length argument list is composed of several groups of arguments.
Within each group, the first argument is a constant or a string that specifies which
arguments follow in the group. The first argument can be one of the following
values: XmVaCHECKBUTTON, a resource name, XtVaTypedList, or XtVaNestedList. The variable-length argument list must be NULL-terminated.
Motif Reference Manual
538
Motif Functions and Macros
If the first argument in a group is XmVaCHECKBUTTON, it is followed by four
arguments: label, mnemonic, accelerator, and accelerator text. This group specifies a ToggleButtonGadget child of the CheckBox and its associated resources.
(As of Motif 1.2, all but the label argument are ignored.)
If the first argument in a group is a resource name string, it is followed by a
resource value of type XtArgVal. This group specifies a standard resource name/
value pair for the RowColumn widget. If the first argument in a group is XtVaTypedArg, it is followed by four arguments: name, type, value, and size. This group
specifies a resource name and value using the standard XtVaTypedArg format. If
the first argument in a group is XtVaNestedList, it is followed by one argument of
type XtVarArgsList, which is returned by XtVaCreateArgsList().
Example
You can use XmVaCreateSimpleCheckBox() as in the following example:
Widget
XmString
toplevel, check_box;
normal, bold, italic;
normal = XmStringCreateLocalized ("normal");
bold = XmStringCreateLocalized ("bold");
italic = XmStringCreateLocalized ("italic");
check_box = XmVaCreateSimpleCheckBox (toplevel, "check_box", toggled,
XmVaCHECKBUTTON, normal,
NULL, NULL, NULL,
XmVaCHECKBUTTON, bold,
NULL, NULL, NULL,
XmVaCHECKBUTTON, italic,
NULL, NULL, NULL,
NULL);
XmStringFree (normal);
XmStringFree (bold);
XmStringFree (italic);
See Also
XmCheckBox(2), XmRowColumn(2), XmToggleButtonGadget(2).
Motif Reference Manual
539
Motif Functions and Macros
Name
XmVaCreateSimpleMenuBar – create a MenuBar compound object.
Synopsis
Widget XmVaCreateSimpleMenuBar (Widget parent, char *name,..., NULL)
Inputs
parent
name
..., NULL
pairs.
Specifies the widget ID of the parent of the new widget.
Specifies the string name of the new widget for resource lookup.
A NULL-terminated variable-length list of resource name/value
Returns
The widget ID of the RowColumn widget.
Description
XmVaCreateSimpleMenuBar() is a RowColumn convenience routine that
creates a MenuBar with CascadeButtonGadgets as its children. This routine is
similar to XmCreateSimpleMenuBar(), but it uses a NULL-terminated variable-length argument list in place of the arglist and argcount parameters. The variable-length argument list specifies resource name/value pairs as well as the
children of the MenuBar.
The name of each CascadeButtonGadget is button_n, where n is the number of
the button, ranging from 0 (zero) to 1 less than the number of buttons in the MenuBar. The buttons are created and named in the order in which they are specified
in the variable-length argument list.
Usage
A variable-length argument list is composed of several groups of arguments.
Within each group, the first argument is a constant or a string that specifies which
arguments follow in the group. The first argument can be one of the following
values: XmVaCASCADEBUTTON, a resource name, XtVaTypedList, or
XtVaNestedList. The variable-length argument list must be NULL-terminated.
If the first argument in a group is XmVaCASCADEBUTTON, it is followed by
two arguments: label and mnemonic. This group specifies a CascadeButtonGadget child of the MenuBar and its associated resources.
If the first argument in a group is a resource name string, it is followed by a
resource value of type XtArgVal. This group specifies a standard resource name/
value pair for the RowColumn widget. If the first argument in a group is XtVaTypedArg, it is followed by four arguments: name, type, value, and size. This group
specifies a resource name and value using the standard XtVaTypedArg format. If
Motif Reference Manual
540
Motif Functions and Macros
the first argument in a group is XtVaNestedList, it is followed by one argument of
type XtVarArgsList, which is returned by XtVaCreateArgsList().
Example
You can use XmVaCreateSimpleMenuBar() as in the following example:
Widget
XmString
top, mainw, menubar, fmenu, emenu;
file, edit, new, quit, cut, clear, copy, paste;
file = XmStringCreateLocalized ("File");
edit = XmStringCreateLocalized ("Edit");
menubar = XmVaCreateSimpleMenuBar (mainw, "menubar",
XmVaCASCADEBUTTON,
file,’F’,
XmVaCASCADEBUTTON,
edit,’E’,
NULL);
XmStringFree (file);
XmStringFree (edit);
new = XmStringCreateLocalized ("New");
quit = XmStringCreateLocalized ("Quit");
fmenu = XmVaCreateSimplePulldownMenu (menubar, "file_menu", 0, file_cb,
XmVaPUSHBUTTON,
new,’N’, NULL, NULL,
XmVaSEPARATOR,
XmVaPUSHBUTTON,
quit,’Q’, NULL, NULL,
NULL);
XmStringFree (new);
XmStringFree (quit);
cut = XmStringCreateLocalized ("Cut");
copy = XmStringCreateLocalized ("Copy");
clear = XmStringCreateLocalized ("Clear");
paste = XmStringCreateLocalized ("Paste");
emenu = XmVaCreateSimplePulldownMenu (menubar, "edit_menu", 0,
cut_paste,
XmVaPUSHBUTTON, cut,’C’,
NULL, NULL,
XmVaPUSHBUTTON,
copy,’o’, NULL, NULL,
XmVaPUSHBUTTON,
paste,’P’, NULL, NULL,
Motif Reference Manual
541
Motif Functions and Macros
XmVaSEPARATOR,
XmVaPUSHBUTTON,
clear,’l’, NULL, NULL,
NULL);
XmStringFree (cut);
XmStringFree (clear);
XmStringFree (copy);
XmStringFree (paste);
See Also
XmCascadeButtonGadget(2), XmMenuBar(2), XmRowColumn(2).
Motif Reference Manual
542
Motif Functions and Macros
Name
XmVaCreateSimpleOptionMenu – create an OptionMenu compound object.
Synopsis
Widget XmVaCreateSimpleOptionMenu (
Widget
String
XmString
KeySym
parent,
name,
option_label,
int
XtCallbackProc
...,
NULL)
button_set,
callback,
option_mnemonic,
Inputs
parent
name
lookup.
option_label
option_mnemonic
OptionMenu.
button_set
callback
is activated.
..., NULL
value pairs.
Specifies the widget ID of the parent of the new widget.
Specifies the string name of the new widget for resource
Specifies the label used for the OptionMenu.
Specifies the mnemonic character associated with the
Specifies the initial setting of the OptionMenu.
Specifies the callback procedure that is called when a button
A NULL-terminated variable-length list of resource name/
Returns
The widget ID of the RowColumn widget.
Description
XmVaCreateSimpleOptionMenu() is a RowColumn convenience routine
that creates an OptionMenu along with its submenu of CascadeButtonGadget
and/or PushButtonGadget children. This routine is similar to XmCreateSimpleOptionMenu(), but it uses a NULL-terminated variable-length argument
list in place of the arglist and argcount parameters. The variable-length argument
list specifies resource name/value pairs as well as the children of the OptionMenu.
The option_label, option_mnemonic, and button_set arguments are used to set
the XmNlabelString, XmNmnemonic, and XmNmenuHistory resources of the
RowColumn respectively. The button_set parameter specifies the nth button child
of the OptionMenu, where the first button is button 0 (zero); the XmNmenuHistory resource is set to the actual widget. The callback argument specifies the call-
Motif Reference Manual
543
Motif Functions and Macros
back routine that is added to the XmNactivateCallback of each
CascadeButtonGadget and PushButtonGadget child in the submenu of the
OptionMenu. When the callback is invoked, the button number of the button
whose value has changed is passed to the callback in the client_data parameter.
The name of each button is button_n, where n is the number of the button, ranging from 0 (zero) to 1 less than the number of buttons in the submenu. The name
of each separator is separator_n, where n is the number of the separator, ranging
from 0 (zero) to 1 less than the number of separators in the submenu. The buttons
are created and named in the order in which they are specified in the variablelength argument list.
Usage
A variable-length argument list is composed of several groups of arguments.
Within each group, the first argument is a constant or a string that specifies which
arguments follow in the group. The first argument can be one of the following
values: XmVaPUSHBUTTON, XmVaCASCADEBUTTON, XmVaSEPARATOR, XmVaDOUBLE_SEPARATOR, a resource name, XtVaTypedList, or
XtVaNestedList. The variable-length argument list must be NULL-terminated.
If the first argument in a group is XmVaPUSHBUTTON, it is followed by four
arguments: label, mnemonic, accelerator, and accelerator text. This group specifies a PushButtonGadget in the pulldown submenu of the OptionMenu and its
associated resources. If the first argument in a group is XmVaCASCADEBUTTON, it is followed by two arguments: label and mnemonic. This group specifies
a CascadeButtonGadget in the pulldown submenu of the OptionMenu and its
associated resources. If the first argument in a group is XmVaSEPARATOR or
XmVaDOUBLE_SEPARATOR, it is not followed by any arguments. These
groups specify SeparatorGadgets in the pulldown submenu of the OptionMenu.
If the first argument in a group is a resource name string, it is followed by a
resource value of type XtArgVal. This group specifies a standard resource name/
value pair for the RowColumn widget. If the first argument in a group is XtVaTypedArg, it is followed by four arguments: name, type, value, and size. This group
specifies a resource name and value using the standard XtVaTypedArg format. If
the first argument in a group is XtVaNestedList, it is followed by one argument of
type XtVarArgsList, which is returned by XtVaCreateArgsList().
Example
You can use XmVaCreateSimpleOptionMenu() as in the following example:
Widget
XmString
Motif Reference Manual
rc, option_menu;
draw_shape, line, square, circle;
544
Motif Functions and Macros
draw_shape = XmStringCreateLocalized ("Draw Mode:");
line = XmStringCreateLocalized ("Line");
square = XmStringCreateLocalized ("Square");
circle = XmStringCreateLocalized ("Circle");
option_menu = XmVaCreateSimpleOptionMenu (rc, "option_menu",
draw_shape, ’D’, 0, option_cb,
XmVaPUSHBUTTON, line,
’L’, NULL, NULL,
XmVaPUSHBUTTON, square,
’S’, NULL, NULL,
XmVaPUSHBUTTON, circle,
’C’, NULL, NULL,
NULL);
XmStringFree (line);
XmStringFree (square);
XmStringFree (circle);
XmStringFree (draw_shape);
See Also
XmOptionButtonGadget(1), XmOptionLabelGadget(1),
XmCascadeButtonGadget(2), XmLabelGadget(2),
XmOptionMenu(2), XmPushButtonGadget(2),
XmRowColumn(2), XmSeparatorGadget(2).
Motif Reference Manual
545
Motif Functions and Macros
Name
XmVaCreateSimplePopupMenu – create a PopupMenu compound object as the
child of a MenuShell.
Synopsis
Widget XmVaCreateSimplePopupMenu ( Widget
String
XtCallbackProc
...,
NULL)
Inputs
parent
name
callback
...,NULL
parent,
name,
callback,
Specifies the widget ID of the parent of the MenuShell.
Specifies the string name of the new widget for resource lookup.
Specifies the callback procedure that is called when a button is
activated or its value changes.
A NULL-terminated variable-length list of resource name/value
pairs.
Returns
The widget ID of the RowColumn widget.
Description
XmVaCreateSimplePopupMenu() is a RowColumn convenience routine
that creates a PopupMenu along with its button children. The routine creates the
PopupMenu as a child of a MenuShell. This routine is similar to XmCreateSimplePopupMenu(), but it uses a NULL-terminated variable-length argument
list in place of the arglist and argcount parameters. The variable-length argument
list specifies resource name/value pairs as well as the children of the PopupMenu.
The callback argument specifies the callback routine that is added to the XmNactivateCallback of each CascadeButtonGadget and PushButtonGadget child and
the XmNvalueChangedCallback of each ToggleButtonGadget child in the PopupMenu. When the callback is invoked, the button number of the button whose
value has changed is passed to the callback in the client_data parameter.
The name of each button is button_n, where n is the number of the button, ranging from 0 (zero) to 1 less than the number of buttons in the menu. The name of
each separator is separator_n, where n is the number of the separator, ranging
from 0 (zero) to 1 less than the number of separators in the menu. The name of
each title is label_n, where n is the number of the title, ranging from 0 (zero) to 1
less than the number of titles in the menu. The buttons are created and named in
the order in which they are specified in the variable-length argument list.
Motif Reference Manual
546
Motif Functions and Macros
Usage
A variable-length argument list is composed of several groups of arguments.
Within each group, the first argument is a constant or a string that specifies which
arguments follow in the group. The first argument can be one of the following
values: XmVaPUSHBUTTON, XmVaCASCADEBUTTON, XmVaRADIOBUTTON, XmVaCHECKBUTTON, XmVaTITLE, XmVaSEPARATOR,
XmVaDOUBLE_SEPARATOR, a resource name, XtVaTypedList, or XtVaNestedList. The variable-length argument list must be NULL-terminated.
If the first argument in a group is XmVaPUSHBUTTON, it is followed by four
arguments: label, mnemonic, accelerator, and accelerator text. This group specifies a PushButtonGadget child of the PopupMenu and its associated resources. If
the first argument in a group is XmVaCASCADEBUTTON, it is followed by two
arguments: label and mnemonic. This group specifies a CascadeButtonGadget
child of the PopupMenu and its associated resources. If the first argument in a
group is XmVaRADIOBUTTON or XmVaCHECKBUTTON, it is followed by
four arguments: label, mnemonic, accelerator, and accelerator text. These groups
specify ToggleButtonGadget children of the PopupMenu and their associated
resources.
If the first argument is XmVaTITLE, it is followed by a title argument. This
group specifies a LabelGadget title in the PopupMenu and its associated
resource. If the first argument in a group is XmVaSEPARATOR or
XmVaDOUBLE_SEPARATOR, it is not followed by any arguments. These
groups specify SeparatorGadgets in the PopupMenu.
If the first argument in a group is a resource name string, it is followed by a
resource value of type XtArgVal. This group specifies a standard resource name/
value pair for the RowColumn widget. If the first argument in a group is XtVaTypedArg, it is followed by four arguments: name, type, value, and size. This group
specifies a resource name and value using the standard XtVaTypedArg format. If
the first argument in a group is XtVaNestedList, it is followed by one argument of
type XtVarArgsList, which is returned by XtVaCreateArgsList().
Example
You can use XmVaCreateSimplePopupMenu() as in the following example:
Widget
XmString
drawing_a, popup_menu;
line, square, circle, quit, quit_acc;
line = XmStringCreateLocalized ("Line");
square = XmStringCreateLocalized ("Square");
circle = XmStringCreateLocalized ("Circle");
quit = XmStringCreateLocalized ("Quit");
Motif Reference Manual
547
Motif Functions and Macros
quit_acc = XmStringCreateLocalized ("Ctrl-C");
popup_menu = XmVaCreateSimplePopupMenu (drawing_a, "popup", popup_cb,
XmVaPUSHBUTTON, line, NULL, NULL,
NULL,
XmVaPUSHBUTTON, square, NULL,
NULL, NULL,
XmVaPUSHBUTTON, circle, NULL,
NULL, NULL,
XmVaSEPARATOR,
XmVaPUSHBUTTON, quit, NULL,
"Ctrl<Key>c", quit_acc,
NULL);
XmStringFree (line);
XmStringFree (square);
XmStringFree (circle);
XmStringFree (quit);
XmStringFree (quit_acc);
See Also
XmCascadeButtonGadget(2), XmLabelGadget(2), XmMenuShell(2),
XmPopupMenu(2), XmPushButtonGadget(2), XmRowColumn(2),
XmSeparatorGadget(2), XmToggleButtonGadget(2).
Motif Reference Manual
548
Motif Functions and Macros
Name
XmVaCreateSimplePulldownMenu – create a PulldownMenu compound object
as the child of a MenuShell.
Synopsis
Widget XmVaCreateSimplePulldownMenu (
Widget
String
int
parent,
name,
XtCallbackProc
...,
NULL)
callback,
post_from_button,
Inputs
parent
name
post_from_button
callback
..., NULL
Specifies the widget ID of the parent of the MenuShell.
Specifies the string name of the new widget for resource
lookup.
Specifies the CascadeButton or CascadeButtonGadget in
the parent widget to which the menu is attached.
Specifies the callback procedure that is called when a button is activated or its value changes.
A NULL-terminated variable-length list of resource
name/value pairs.
Returns
The widget ID of the RowColumn widget.
Description
XmVaCreateSimplePulldownMenu() is a RowColumn convenience routine that creates a PulldownMenu along with its button children. The routine creates the PulldownMenu as a child of a MenuShell. This routine is similar to
XmCreateSimplePulldownMenu(), but it uses a NULL-terminated variable-length argument list in place of the arglist and argcount parameters. The variable-length argument list specifies resource name/value pairs as well as the
children of the PulldownMenu.
The post_from_button parameter specifies the CascadeButton or CascadeButtonGadget to which the PulldownMenu is attached as a submenu. The argument
specifies the nth CascadeButton or CascadeButtonGadget, where the first button
is button 0 (zero). The callback argument specifies the callback routine that is
added to the XmNactivateCallback of each CascadeButtonGadget and PushButtonGadget child and the XmNvalueChangedCallback of each ToggleButtonGadget child in the PulldownMenu. When the callback is invoked, the button
Motif Reference Manual
549
Motif Functions and Macros
number of the button whose value has changed is passed to the callback in the
client_data parameter.
The name of each button is button_n, where n is the number of the button, ranging from 0 (zero) to 1 less than the number of buttons in the menu. The name of
each separator is separator_n, where n is the number of the separator, ranging
from 0 (zero) to 1 less than the number of separators in the menu. The name of
each title is label_n, where n is the number of the title, ranging from 0 (zero) to 1
less than the number of titles in the menu. The buttons are created and named in
the order in which they are specified in the variable-length argument list.
Usage
A variable-length argument list is composed of several groups of arguments.
Within each group, the first argument is a constant or a string that specifies which
arguments follow in the group. The first argument can be one of the following
values: XmVaPUSHBUTTON, XmVaCASCADEBUTTON, XmVaRADIOBUTTON, XmVaCHECKBUTTON, XmVaTITLE, XmVaSEPARATOR,
XmVaDOUBLE_SEPARATOR, a resource name, XtVaTypedList, or XtVaNestedList. The variable-length argument list must be NULL-terminated.
If the first argument in a group is XmVaPUSHBUTTON, it is followed by four
arguments: label, mnemonic, accelerator, and accelerator text. This group specifies a PushButtonGadget child of the PulldownMenu and its associated resources.
If the first argument in a group is XmVaCASCADEBUTTON, it is followed by
two arguments: label and mnemonic. This group specifies a CascadeButtonGadget child of the PulldownMenu and its associated resources. If the first argument in a group is XmVaRADIOBUTTON or XmVaCHECKBUTTON, it is
followed by four arguments: label, mnemonic, accelerator, and accelerator text.
These groups specify ToggleButtonGadget children of the PulldownMenu and
their associated resources.
If the first argument is XmVaTITLE, it is followed by a title argument. This
group specifies a LabelGadget title in the PulldownMenu and its associated
resource. If the first argument in a group is XmVaSEPARATOR or
XmVaDOUBLE_SEPARATOR, it is not followed by any arguments. These
groups specify SeparatorGadgets in the PulldownMenu.
If the first argument in a group is a resource name string, it is followed by a
resource value of type XtArgVal. This group specifies a standard resource name/
value pair for the RowColumn widget. If the first argument in a group is XtVaTypedArg, it is followed by four arguments: name, type, value, and size. This group
specifies a resource name and value using the standard XtVaTypedArg format. If
the first argument in a group is XtVaNestedList, it is followed by one argument of
type XtVarArgsList, which is returned by XtVaCreateArgsList().
Motif Reference Manual
550
Motif Functions and Macros
Example
You can use XmVaCreateSimplePulldownMenu() as in the following
example:
Widget
XmString
top, mainw, menubar, fmenu, emenu;
file, edit, new, quit, cut, clear, copy, paste;
file = XmStringCreateLocalized ("File");
edit = XmStringCreateLocalized ("Edit");
menubar = XmVaCreateSimpleMenuBar (mainw, "menubar",
XmVaCASCADEBUTTON, file, ’F’,
XmVaCASCADEBUTTON, edit, ’E’,
NULL);
XmStringFree (file);
XmStringFree (edit);
new = XmStringCreateLocalized ("New");
quit = XmStringCreateLocalized ("Quit");
fmenu = XmVaCreateSimplePulldownMenu (menubar, "file_menu", 0, file_cb,
XmVaPUSHBUTTON, new,
’N’, NULL, NULL,
XmVaSEPARATOR,
XmVaPUSHBUTTON, quit,
’Q’, NULL, NULL,
NULL);
XmStringFree (new);
XmStringFree (quit);
cut = XmStringCreateLocalized ("Cut");
copy = XmStringCreateLocalized ("Copy");
clear = XmStringCreateLocalized ("Clear");
paste = XmStringCreateLocalized ("Paste");
emenu = XmVaCreateSimplePulldownMenu (menubar, "edit_menu", 1,
cut_paste,
XmVaPUSHBUTTON, cut, ’C’,
NULL, NULL,
XmVaPUSHBUTTON, copy, ’o’,
NULL, NULL,
XmVaPUSHBUTTON, paste,
’P’, NULL, NULL,
XmVaSEPARATOR,
XmVaPUSHBUTTON, clear, ’l’,
NULL, NULL,
NULL);
Motif Reference Manual
551
Motif Functions and Macros
XmStringFree (cut);
XmStringFree (clear);
XmStringFree (copy);
XmStringFree (paste);
See Also
XmCascadeButtonGadget(2), XmLabelGadget(2), XmMenuShell(2),
XmPulldownMenu(2), XmPushButtonGadget(2), XmRowColumn(2),
XmSeparatorGadget(2), XmToggleButtonGadget(2).
Motif Reference Manual
552
Motif Functions and Macros
Name
XmVaCreateSimpleRadioBox – create a RadioBox compound object.
Synopsis
Widget XmVaCreateSimpleRadioBox ( Widget
String
int
XtCallbackProc
...,
NULL)
parent,
name,
button_set,
callback,
Inputs
parent
Specifies the widget ID of the parent of the new widget.
name
Specifies the string name of the new widget for resource
lookup.
button_set
Specifies the initial setting of the RadioBox.
callback
Specifies the callback procedure that is called when the value
of a button changes.
..., NULL
A NULL-terminated variable-length list of resource name/
value pairs.
Returns
The widget ID of the RowColumn widget.
Description
XmVaCreateSimpleRadioBox() is a RowColumn convenience routine that
creates a RadioBox with ToggleButtonGadgets as its children. This routine is
similar to XmCreateSimpleRadioBox(), but it uses a NULL-terminated variable-length argument list in place of the arglist and argcount parameters. The
variable-length argument list specifies resource name/value pairs as well as the
children of the CheckBox. The button_set argument is used to set the XmNmenuHistory resource of the RowColumn. The parameter specifies the nth button
child of the RadioBox, where the first button is button 0 (zero); the XmNmenuHistory resource is set to the actual widget. The callback argument specifies the
callback routine that is added to the XmNvalueChangedCallback of each ToggleButtonGadget child of the RadioBox. When the callback is invoked, the button
number of the button whose value has changed is passed to the callback in the
client_data parameter.
The name of each ToggleButtonGadget child is button_n, where n is the number
of the button, ranging from 0 (zero) to 1 less than the number of buttons in the
RadioBox. The buttons are created and named in the order in which they are
specified in the variable-length argument list.
Motif Reference Manual
553
Motif Functions and Macros
Usage
A variable-length argument list is composed of several groups of arguments.
Within each group, the first argument is a constant or a string that specifies which
arguments follow in the group. The first argument can be one of the following
values: XmVaRADIOBUTTON, a resource name, XtVaTypedList, or XtVaNestedList. The variable-length argument list must be NULL-terminated.
If the first argument in a group is XmVaRADIOBUTTON, it is followed by four
arguments: label, mnemonic, accelerator, and accelerator text. This group specifies a ToggleButtonGadget child of the RadioBox and its associated resources.
(As of Motif 1.2, all but the label argument are ignored.)
If the first argument in a group is a resource name string, it is followed by a
resource value of type XtArgVal. This group specifies a standard resource name/
value pair for the RowColumn widget. If the first argument in a group is XtVaTypedArg, it is followed by four arguments: name, type, value, and size. This group
specifies a resource name and value using the standard XtVaTypedArg format. If
the first argument in a group is XtVaNestedList, it is followed by one argument of
type XtVarArgsList, which is returned by XtVaCreateArgsList().
Example
You can use XmVaCreateSimpleRadioBox() as in the following example:
Widget
XmString
toplevel, radio_box;
one, two, three;
one = XmStringCreateLocalized ("WFNX");
two = XmStringCreateLocalized ("WMJX");
three = XmStringCreateLocalized ("WXKS");
radio_box = XmVaCreateSimpleRadioBox (toplevel, "radio_box", 0, toggled,
XmVaRADIOBUTTON, one, NULL,
NULL, NULL,
XmVaRADIOBUTTON, two, NULL,
NULL, NULL,
XmVaRADIOBUTTON, three,
NULL, NULL, NULL,
NULL);
XmStringFree (one);
XmStringFree (two);
XmStringFree (three);
See Also
XmRadioBox(2), XmRowColumn(2), XmToggleButtonGadget(2).
Motif Reference Manual
554
Motif Functions and Macros
Name
XmWidgetGetBaselines – get the positions of the baselines in a widget.
Synopsis
Boolean XmWidgetGetBaselines (Widget widget, Dimension **baselines, int
*line_count)
Inputs
widget
Outputs
baselines
widget.
line_count
Specifies the widget for which to get baseline values.
Returns an array containing the value of each baseline of text in the
Returns the number of lines of text in the widget.
Returns
True if the widget contains at least one baseline or False otherwise.
Availability
Motif 1.2 and later.
Description
XmWidgetGetBaselines() returns an array that contains the baseline values
for the specified widget. For each line of text in the widget, the baseline value is
the vertical offset in pixels from the origin of the bounding box of the widget to
the text baseline. The routine returns the baseline values in baselines and the
number of lines of text in the widget in line_count. XmWidgetGetBaselines() returns True if the widget contains at least one line of text and therefore
has a baseline. If the widget does not contain any text, the routine returns False
and the values of baselines and line_count are undefined. The routine allocates
storage for the returned values. The application is responsible for freeing this
storage using XtFree().
Usage
XmWidgetGetBaselines() provide information that is useful when you are laying
out an application and trying to align different components.
See Also
XmWidgetGetDisplayRect(1).
Motif Reference Manual
555
Motif Functions and Macros
Name
XmWidgetGetDisplayRect – get the display rectangle for a widget.
Synopsis
Boolean XmWidgetGetDisplayRect (Widget widget, XRectangle *displayrect)
Inputs
widget
Specifies the widget for which to get the display rectangle.
Outputs
displayrect
widget.
Returns an XRectangle that specifies the display rectangle of the
Returns
True if the widget has a display rectangle or False otherwise.
Availability
Motif 1.2 and later.
Description
XmWidgetGetDisplayRect() gets the display rectangle for the specified
widget. The routine returns the width, the height, and the x and y-coordinates of
the upper left corner of the display rectangle in the displayrect XRectangle. All
of the values are specified as pixels. The display rectangle for a widget is the
smallest rectangle that encloses the string or the pixmap in the widget. XmWidgetGetDisplayRect() returns True if the widget has a display rectangle; other
it returns False and the value of displayrect is undefined.
Usage
XmWidgetGetDisplayRect() provide information that is useful when you
are laying out an application and trying to align different components.
See Also
XmWidgetGetBaselines(1).
Motif Reference Manual
556
Section 2 - Motif and Xt Widget Classes
This page describes the format and contents of each reference page in Section 2,
which covers each of the Motif and Xt Intrinsics widget types.
Name
Widget – a brief description of the widget.
Synopsis
Public Headers:
The files to include when you use this widget.
Class Name:
The name of the widget class; used as the resource class for each instance of the
widget.
Class Hierarchy:
The superclasses of this widget, listed in superclass-to-subclass order. The arrow
symbol (→) indicates a subclass.
Class Pointer:
The global variable that points to the widget class structure. This is the value
used when creating a widget.
Instantiation:
C code that instantiates the widget, for widgets that can be instantiated. For the
widgets and gadgets in the Motif toolkit, we have shown how to instantiate the
widget using XtCreateWidget(). Each widget and gadget has a convenience
creation routine of the general form:
Widget XmCreateobject ( Widget
String
ArgList
Cardinal
parent
name
arglist,
argcount)
where object is the shorthand for the class.
Functions/Macros:
Functions and/or macros specific to this widget class.
Availability
This section describes the availability of the widget class across various versions
of Motif. The section is omitted if the widget class has always been present in the
toolkit.
Description
This section gives an overview of the widget class and the functionality it provides.
Motif Reference Manual
557
Introduction
Motif and Xt Widget Classes
Traits
This section appears for any traits that are set by the widget class. The Trait
mechanisms are available in Motif 2.0 and later.
New Resources
This section presents a table of the resources that are newly defined by each
widget class (not inherited from a superclass). In addition to the resource’s name,
class, data type, and default value, a fifth column lists a code consisting of one or
more of the letters C, S, and G. This code indicates whether the resource can be
set when the widget is created (C), whether it can be set with XtSetValues() (S),
and whether it can be read with XtGetValues() (G). A brief description of
each new resource follows the table. For resources whose values are defined constants, these constants are listed. Unless otherwise noted, they are defined in
<Xm/Xm.h>.
Other New Resources
If present, these sections describe resources associated with specific uses of the
widget; for example, RowColumn widget resources for use with simple creation
routines, or Text widget resources for use in text input.
Callback Resources
This section presents a table of the callback resources that are newly defined by
this class. The table lists the name of each resource along with its reason constant.
Callback Structure
This section lists the structure(s) associated with the object’s callback functions.
New Constraint Resources
This section defines any constraint resources that are newly defined by each
widget class (not inherited from a superclass). In addition to the resource’s name,
class, data type, and default value, a fifth column lists a code consisting of one or
more of the letters C, S, and G. This code indicates whether the constraint
resource can be set when a child widget is created (C), whether it can be set with
XtSetValues() (S), and whether it can be read with XtGetValues() (G). A
brief description of each new constraint resource follows the table. For resources
whose values are defined constants, these constants are listed. Unless otherwise
noted, they are defined in <Xm/Xm.h>.
Procedures
This section lists any procedure or function prototypes associated with the
widget.
558
Motif Reference Manual
Motif and Xt Widget Classes
Introduction
Default Resource Values
This section presents a table of the default resource values that are set when a
compound object is created.
Inherited Resources
This section presents an alphabetically arranged table of inherited resources,
along with the superclass that defines them.
Widget Hierarchy
This section presents the widget instance hierarchy that results from creating a
compound object.
The full widget hierarchy is shown in Figure 1.
Translations
This section presents the translations associated with each widget or gadget.
Because the button events and key events used in Motif do not necessarily correspond to the events in the X Window System, the Motif toolkit has created a
mechanism called virtual bindings. Virtual bindings link the translations used in
Motif to their X event counterparts. The "Translations" sections list their events
in terms of these virtual bindings. In order to understand the syntax used in the
"Translations" sections of these reference pages, you must understand the correspondence between virtual bindings and actual keysyms or buttons. The following tables describe the virtual bindings of events.
Virtual Modifier
Actual Modifier
MAlt
<Mod1>
MCtrl
<Ctrl>
MShift
<Shift>
MLink
<Ctrl><Shift>
MMove
<Shift>
MCopy
<Ctrl>
Virtual Button
Actual Button Events
BCustom
<Btn3>
BTransfer
<Btn2>
BExtend
<Shift><Btn1>
BMenu
<Btn3>
BSelect
<Btn1>
Motif Reference Manual
559
Introduction
Motif and Xt Widget Classes
ArrowButtonGadget
Core
CascadeButtonGadget
IconGadget
Object
PushButtonGadget
RectObj
Gadget
LabelGadget
ToggleButtonGadget
SeparatorGadget
WindowObj
ArrowButton
CascadeButton
Label
DrawnButton
List
PushButton
Primitive
ScrollBar
ToggleButton
Separator
Text
TextField
Form
BulletinBoard
Constraint
Command
Manager
SelectionBox
ComboBox
FileSelectionBox
Container
MessageBox
DrawingArea
Frame
Key
Composite
Notebook
Motif
PanedWindow
Xt Intrinsics
RowColumn
Scale
ScrolledWindow
MainWindow
SpinBox
SimpleSpinBox
GrabShell
OverrideShell
MenuShell
TopLevelShell
WMShell
VendorShell
TransientShell
ApplicationShell
PrintShell
Shell
DialogShell
SessionShell
Figure 1: Class Hierarchy of the Motif widget set
560
Motif Reference Manual
Motif and Xt Widget Classes
Introduction
Virtual Button
Actual Button Events
BToggle
<Ctrl><Btn1>
Virtual Key
Actual Key Events
KActivate
<Key>Return
<Ctrl><Key>Return
<Key>osfActivate
KAddMode
<Key>osfAddMode
KBackSpace
<Key>osfBackSpace
KBackTab
<Shift><Key>Tab
KBeginData
<Ctrl><Key>osfBeginLine
KBeginLine
<Key>osfBeginLine
KCancel
<Key>osfCancel
KClear
<Key>osfClear
KCopy
<Key>osfCopy
<Ctrl><Key>osfInsert
KCut
<Key>osfCut
<Shift><Key>osfDelete
KDelete
<Key>osfDelete
KDeselectAll
<Ctrl><Key>backslash
KDown
<Key>osfDown
KEndData
<Ctrl><Key>osfEndLine
KEndLine
<Key>osfEndLine
KEnter
<Key>Return
KEscape
<Key>Escape
KExtend
<Ctrl><Shift><Key>space
<Shift><Key>osfSelect
KHelp[
<Key>osfHelp
KInsert
<Key>osfInsert
KLeft
<Key>osfLeft
KMenu
<Key>osfMenu
KMenuBar
<Key>osfMenuBar
KNextField
<Key>Tab
<Ctrl><Key>Tab
Motif Reference Manual
561
Introduction
562
Motif and Xt Widget Classes
Virtual Key
Actual Key Events
KNextMenu
<Ctrl><Key>osfDown
<Ctrl><Key>osfRight
KPageDown
<Key>osfPageDown
KPageLeft
<Ctrl<Key>osfPageUp
<Key>osfPageUp
KPageRight
<Ctrl><Key>osfPageDown
KPageUp
<Key>osfPageUp
KPaste
<Key>osfPaste
<Shift><Key>osfInsert
KPrevField
<Shift><Key>Tab
<Ctrl><Key><Shift><Tab>
KPrevMenu
<Ctrl><Key>osfUp
<Ctrl><Key>osfLeft
KPrimaryCopy
<Ctrl><Key>osfPrimaryPaste
<Mod1><Key>osfCopy
<Mod1><Ctrl><Key>osfInsert
KPrimaryCut
<Mod1><Key>osfPrimaryPaste
<Mod1><Key>osfCut
<Mod1><Shift><Key>osfDelete
KPrimaryPaste
<Key>osfPrimaryPaste
KQuickCopy
<Ctrl><Key>osfQuickPaste
KQuickCut
<Mod1><Key>osfQuickPaste
KQuickExtend
<Shift><Key>osfQuickPaste
KQuickPaste
<key>osfQuickPaste
KReselect
<Ctrl><Shift><Key>osfSelect
KRestore
<Ctrl><Shift><Key>osfInsert
KRight
<Key>osfRight
KSelect
<Key>space
<Ctrl><Key>space
<Key>osfSelect
KSelectAll
<Ctrl><Key>slash
KSpace
<Key>space
KTab
<Key>Tab
KUndo
<Key>osfUndo
<Mod1><Key>osfBackSpace
Motif Reference Manual
Motif and Xt Widget Classes
Introduction
Virtual Key
Actual Key Events
KUp
<Key>osfUp
KAny
<Key>
Keysyms that begin with the letters osf are not defined by the X server. These
keysyms are generated at run time by a client, interpreted by XmTranslateKey(), and used by the translation manager when the server sends an
actual key event. An application maintains a mapping between osf keysyms and
actual keysyms that is based on information that is retrieved at application startup. This information comes from one of the following sources, listed in order of
precedence:
• The XmNdefaultVirtualBindings resource in a resource database. A
sample specification is shown below:
*defaultVirtualBindings:\
osfBackSpace:
<Key>BackSpace \n\
osfInsert:
<Key>InsertChar \n\
osfDelete:
<Key>DeleteChar
• A property on the root window. mwm sets this property on startup. It can also be
set by the xmbind client in Motif 1.2 or later, or the prior startup of another Motif
application.
• A file named .motifbind, in the user’s home directory. In this file, the previous
specification would be typed as follows:
osfBackSpace:
osfInsert:
osfDelete:
<Key>BackSpace
<Key>InsertChar
<Key>DeleteChar
• A vendor-specific set of bindings located using the file xmbind.alias. If this file
exists in the user’s home directory, it is searched for a pathname associated with
the vendor string or the vendor string and vendor release. If the search is unsuccessful, Motif continues looking for xmbind.alias in the directory specified by
XMBINDDIR or in /usr/lib/Xm/bindings if the variable is not set. If this file
exists, it is searched for a pathname as before. If either search locates a pathname
and the file exists, the bindings in that file are used. An xmbind.alias file contains
lines of the following form:
"vendor_string[vendor_release]"bindings_file
• Via fixed fallback defaults. osf keysym strings have the fixed fallback default
bindings listed below:
osfActivate
Motif Reference Manual
<unbound>
563
Introduction
Motif and Xt Widget Classes
osfAddMode
osfBackSpace
osfBeginLine
osfClear
osfCopy
osfCut
osfDelete
osfDown
osfEndLine
osfCancel
osfHelp
osfInsert
osfLeft
osfMenu
osfMenuBar
osfPageDown
osfPageLeft
osfPageRight
osfPageUp
osfPaste
osfPrimaryPaste
osfQuickPaste
osfRight
osfSelect
osfUndo
osfUp
<Shift> F8
Backspace
Home
Clear
<unbound>
<unbound>
Delete
Down
End
<Escape>
F1
Insert
Left
F4
F10
Next
<unbound>
<unbound>
Prior
<unbound>
<unbound>
<unbound>
Right
Select
Undo
Up
Action Routines
This section describes the action routines that are listed in the "Translations" section.
Behavior
This section describes the keyboard and mouse events that affect gadgets, which
do not have translations or actions.
Additional Behavior
This section describes any additional widget behavior that is not provided by
translations and actions.
See Also
This section refers you to related functions and widget classes. The numbers in
parentheses following each reference refer to the sections of this book in which
they are found.
564
Motif Reference Manual
Motif and Xt Widget Classes
ApplicationShell
Name
ApplicationShell widget class – the main shell for an application.
Synopsis
Public Headers:
<Xm/Xm.h>
<X11/Shell.h>
Class Name:
ApplicationShell
Class Hierarchy:
Core → Composite → Shell → WMShell → VendorShell → TopLevelShell →
ApplicationShell
Class Pointer:
applicationShellWidgetClass
Instantiation:
widget = XtAppInitialize (...)
or
widget = XtAppCreateShell (app_name, app_class,
applicationShellWidgetClass,...)
Functions/Macros:
XtAppCreateShell(), XtVaAppCreateShell(), XtIsApplicationShell()
Availability
From X11R6, the ApplicationShell is considered deprecated: you should give
preference to the SessionShell widget class.
Description
An ApplicationShell is the normal top-level window for an application. It does
not have a parent and it is at the root of the widget tree. An application should
have only one ApplicationShell, unless the application is implemented as multiple logical applications. Normally, an application will use TopLevelShell widgets
for other top-level windows.
An ApplicationShell is returned by the call to XtVaAppInitialize(). It can
also be created explicitly with a call to XtVaAppCreateShell().
Motif Reference Manual
565
ApplicationShell
Motif and Xt Widget Classes
New Resources
ApplicationShell defines the following resources:
Name
Class
Type
Default
Access
XmNargc
XmCArgc
int
0
CSG
XmNargv
XmCArgv
String *
NULL
CSG
XmNargc
Number of arguments in XmNargv.
XmNargv
List of command-line arguments used to start the application. This is the standard
C argv, passed in the call to XtAppInitialize(). It is used to set the
WM_COMMAND property for this window, which is the argument list required
by a session manager to restart the application if necessary. The resource value
can be changed at appropriate points if some specific internal state has been
reached from which the application can be directly restarted.
Inherited Resources
ApplicationShell inherits the following resources. The resources are listed alphabetically, along with the superclass that defines them. The default value of XmNborderWidth is reset to 0 by VendorShell.
Resource
Inherited From Resource
Inherited From
XmNaccelerators
Core
XmNmappedWhenManaged
Core
XmNallowShellResize
Shell
XmNmaxAspectX
WMShell
XmNancestorSensitive
Core
XmNmaxAspectY
WMShell
XmNaudibleWarning
VendorShell
XmNmaxHeight
WMShell
XmNbackground
Core
XmNmaxWIdth
WMShell
XmNbackgroundPixmap
Core
XmNminAspectX
WMShell
XmNbaseHeight
WMShell
XmNminAspectY
WMShell
XmNbaseWidth
WMShell
XmNminHeight
WMShell
XmNborderColor
Core
XmNminWidth
WMShell
XmNborderPixmap
Core
XmNmwmDecorations
VendorShell
XmNborderWidth
Core
XmNmwmFunctions
VendorShell
XmNbuttonFontList
VendorShell
XmNmwmInputMode
VendorShell
XmNbuttonRenderTable
VendorShell
XmNmwmMenu
VendorShell
XmNchildren
Composite
XmNnumChildren
Composite
XmNcolormap
Core
XmNoverrideRedirect
Shell
566
Motif Reference Manual
Motif and Xt Widget Classes
ApplicationShell
Resource
Inherited From Resource
Inherited From
XmNcreatePopupChildProc
Shell
XmNpopdownCalback
Shell
XmNdefaultFontList
VendorShell
XmNpopupCallback
Shell
XmNdeleteResponse
VendorShell
XmNpreeditType
VendorShell
XmNdepth
Core
XmNsaveUnder
Shell
XmNdestroyCallback
Core
XmNscreen
Core
XmNgeometry
Shell
XmNsensitive
Core
XmNheight
Core
XmNshellUnitType
VendorShell
XmNheightInc
WMShell
XmNtextFontList
VendorShell
XmNiconic
TopLevelShell
XmNtextRenderTable
VendorShell
XmNiconMask
WMShell
XmNtitle
WMShell
XmNiconName
TopLevelShell
XmNtitleEncoding
WMShell
XmNiconNameEncoding
TopLevelShell
XmNtransient
WMShell
XmNiconPixmap
WMShell
XmNtranslations
Core
XmNiconWindow
WMShell
XmNuseAsyncGeometry
VendorShell
XmNinitialResourcesPersistent Core
XmNunitType
VendorShell
XmNinitialState
WMShell
XmNvisual
Shell
XmNinput
WMShell
XmNwaitForWm
WMShell
XmNinputMethod
VendorShell
XmNwidth
Core
XmNinputPolicy
VendorShell
XmNwidthInc
WMShell
XmNinsertPosition
Composite
XmNwindowGroup
WMShell
XmNkeyboardFocusPolicy
VendorShell
XmNwinGravity
WMShell
XmNlabelFontList
VendorShell
XmNwmTimeout
WMShell
XmNlabelRenderTable
VendorShell
XmNx
Core
XmNlayoutDirection
VendorShell
XmNy
Core
The VendorShell superclass installs a handler which intercepts the window manager WM_DELETE_WINDOW message. The handler is inherited by sub-classes
of VendorShell, and has the behavior that if XmNdeleteResponse is XmDESTROY, and the widget is an instance of an ApplicationShell, then the application context associated with the widget is destroyed, followed by a call to exit().
See Also
Composite(2), Core(2), SessionShell(2), Shell(2),
TopLevelShell(2), VendorShell(2), WMShell(2).
Motif Reference Manual
567
Composite
Motif and Xt Widget Classes
Name
Composite widget class – the fundamental widget that can have children.
Synopsis
Public Headers:
<Xm/Xm.h>
<X11/Composite.h>
Class Name:
Composite
Class Hierarchy:
Core → Composite
Class Pointer:
compositeWidgetClass
Instantiation:
Composite is an Intrinsics meta-class and is not normally instantiated.
Functions/Macros:
XtIsComposite()
Description
Composite widgets contain other widgets. A Composite widget supports an arbitrary number of children, although derived classes may impose a limit for whatever reason. Composite handles the geometry management of its children. It also
manages the destruction of descendants when it is destroyed. Children of a Composite widget are ordered, and Composite provides the means to sort or place the
list of children in some logical order.
New Resources
Composite defines the following resources:
Name
Class
Type
Default
Access
XmNchildren
XmCReadOnly
WidgetList
NULL
G
XmNinsertPosition
XmCInsertPosition
XtOrderProc
NULL
CSG
XmNnumChildren
XmCReadOnly
Cardinal
0
G
XmNchildren
List of widget’s children.
XmNinsertPosition
Points to an XtOrderProc() function that is called to determine the position
at which each child is inserted into the XmNchildren array. Composite supplies a
default function that appends children in the order of creation.
568
Motif Reference Manual
Motif and Xt Widget Classes
Composite
XmNnumChildren
Length of the list in XmNchildren.
Procedures
XtOrderProc
An XtOrderProc is a pointer to a function, specified as follows:
typedef Cardinal (*XtOrderProc) (Widget);
An XtOrderProc function is called by the insert_child method of a Composite
or derived class, when a new child is created within the widget. The function has
a single parameter, which is the widget ID of the new child. The function returns
the number of children that go before the new child in the XmNchildren array.
Composite supplies a default function that simply appends new children in the
order of creation. Sub-classes may supply alternative default behavior. Programmers may supply their own XtOrderProc to sort children in some specified manner.
Inherited Resources
Composite inherits the following resources. The resources are listed alphabetically, along with the superclass that defines them.
Name
Inherited From
Name
Inherited From
XmNaccelerators
Core
XmNheight
Core
XmNancestorSensitive
Core
XmNinitialResourcesPersistent
Core
XmNbackground
Core
XmNmappedWhenManaged
Core
XmNbackgroundPixmap
Core
XmNscreen
Core
XmNborderColor
Core
XmNsensitive
Core
XmNborderPixmap
Core
XmNtranslations
Core
XmNborderWidth
Core
XmNwidth
Core
XmNcolormap
Core
XmNx
Core
XmNdepth
Core
XmNy
Core
XmNdestroyCallback
Core
See Also
Core(2).
Motif Reference Manual
569
Constraint
Motif and Xt Widget Classes
Name
Constraint widget class – a widget that provides constraint resources for its children.
Synopsis
Public Headers:
<Xm/Xm.h>
<X11/Constraint.h>
Class Name:
Constraint
Class Hierarchy:
Core → Composite → Constraint
Class Pointer:
constraintWidgetClass
Instantiation:
Constraint is an Intrinsics meta-class and is not normally instantiated.
Functions/Macros:
XtIsConstraint()
Description
Constraint widgets are so named because they may manage the geometry of their
children based on constraints associated with each child. These constraints can be
as simple as the maximum width and height the parent allows the child to occupy,
or as complicated as how other children change if a child is moved or resized.
Constraint widgets let a parent define resources that are supplied for their children. For example, if a Constraint parent defines the maximum width and height
for its children, these resources are retrieved for each child as if they are
resources that are defined by the child widget itself.
New Resources
Constraint does not define any new resources.
Inherited Resources
Constraint inherits the following resources. The resources are listed alphabetically, along with the superclass that defines them.
Name
Inherited From
Name
Inherited From
XmNaccelerators
Core
XmNheight
Core
XmNancestorSensitive
Core
XmNinsertPosition
Composite
XmNbackground
Core
XmNinitialResourcesPersistent
Core
570
Motif Reference Manual
Motif and Xt Widget Classes
Constraint
Name
Inherited From
Name
Inherited From
XmNbackgroundPixmap
Core
XmNmappedWhenManaged
Core
XmNborderColor
Core
XmNnumChildren
Composite
XmNborderPixmap
Core
XmNscreen
Core
XmNborderWidth
Core
XmNsensitive
Core
XmNchildren
Composite
XmNtranslations
Core
XmNcolormap
Core
XmNwidth
Core
XmNdepth
Core
XmNx
Core
XmNdestroyCallback
Core
XmNy
Core
See Also
Composite(2), Core(2).
Motif Reference Manual
571
Core
Motif and Xt Widget Classes
Name
Core widget class – the fundamental class for windowed widgets.
Synopsis
Public Header:
<Xm/Xm.h>
<X11/Core.h>
Class Name:
Core
Class Hierarchy:
Object → RectObj → unnamed → Core
Class Pointer:
widgetClass or coreWidgetClass
Instantiation:
Core is an Intrinsics meta-class and is not normally instantiated.
Functions/Macros:
XtIsWidget()
Description
Core is the fundamental class for windowed widgets. All widgets with windows
are subclasses of Core. The Object and RectObj classes support gadgets (windowless widgets). Core is sometimes instantiated for use as a basic drawing area.
New Resources
Core defines the following resources (some of which are actually defined by the
Object and RectObj classes)
Name
Class
Type
Default
Access
XmNaccelerators
XmCAccelerators
XtAccelerators
dynamic
CSG
XmNancestorSensitive
XmCSensitive
Boolean
dynamic
G
XmNbackground
XmCBackground
Pixel
dynamic
CSG
XmNbackgroundPixmap
XmCPixmap
Pixmap
XmUNSPECIFIED_PIXMAP
CSG
XmNborderColor
XmCBorderColor
Pixel
XtDefaultForeground
CSG
XmNborderPixmap
XmCPixmap
Pixmap
XmUNSPECIFIED_PIXMAP
CSG
XmNborderWidth
XmCBorderWidth
Dimension
1
CSG
XmNcolormap
XmCColormap
Colormap
dynamic
CSG
572
Motif Reference Manual
Motif and Xt Widget Classes
Core
Name
Class
Type
Default
Access
XmNdepth
XmCDepth
int
dynamic
CSG
XmNdestroyCallback
XmCCallback
XtCallbackList
NULL
C
XmNheight
XmCHeight
Dimension
dynamic
CSG
XmNinitialResourcesPersistent
XmCInitialResourcesPersistent
Boolean
True
C
XmNmappedWhenManaged
XmCMappedWhenManaged
Boolean
True
CSG
XmNscreen
XmCScreen
Screen *
dynamic
CG
XmNsensitive
XmCSensitive
Boolean
True
CSG
XmNtranslations
XmCTranslations
XtTranslations
dynamic
CSG
XmNwidth
XmCWidth
Dimension
dynamic
CSG
XmNx
XmCPosition
Position
0
CSG
XmNy
XmCPosition
Position
0
CSG
XmNaccelerators
A translation table bound with its actions for a widget. A destination widget can
be set up to use this accelerator table.
XmNancestorSensitive
Tells whether a widget’s immediate parent should receive input. Default value is
True if the widget is a top-level shell, copied from the XmNancestorSensitive
resource of its parent if the widget is a popup shell, or the bitwise AND of the
XmNsensitive and XmNancestorSensitive resources of the parent for other widgets.
XmNbackground
Widget’s background color.
XmNbackgroundPixmap
Pixmap with which to tile the background, beginning at the upper-left corner.
XmNborderColor
Pixel value that defines the color of the border.
XmNborderPixmap
Pixmap with which to tile the border, beginning at the upper-left corner of the
border.
XmNborderWidth
Width (in pixels) of the window’s border.
Motif Reference Manual
573
Core
Motif and Xt Widget Classes
XmNcolormap
Colormap used in converting to pixel values. Previously created pixel values are
unaffected. The default value is the screen’s default colormap for top-level shells
or is copied from the parent for other widgets.
XmNdepth
Number of bits allowed for each pixel. The Xt Intrinsics set this resource when
the widget is created. As with the XmNcolormap resource, the default value
comes from the screen’s default or is copied from the parent.
XmNdestroyCallback
List of callbacks invoked when the widget is destroyed.
XmNheight
Window height (in pixels), excluding the border.
XmNinitialResourcesPersistent
Tells whether resources should be reference counted. If True (default), it is
assumed that the widget won’t be destroyed while the application is running, and
thus the widget’s resources are not reference counted. Set this resource to False if
your application might destroy the widget and will need to deallocate the
resources.
XmNmappedWhenManaged
If True (default), the widget becomes visible (is mapped) as soon as it is both
realized and managed. If False, the application performs the mapping and
unmapping of the widget. If changed to False after the widget is realized and
managed, the widget is unmapped.
XmNscreen
Screen location of the widget. The default value comes either from the screen’s
default or is copied from the parent.
XmNsensitive
Tells whether a widget is sensitive to input. The XtSetSensitive() routine
can be used to change a widget’s sensitivity and to guarantee that if a parent has
its XmNsensitive resource set to False, then its children will have their ancestor-sensitive flag set correctly.
XmNtranslations
Points to a translation table; must be compiled with XtParseTranslationTable().
XmNwidth
Window width (in pixels), excluding the border.
XmNx
The x-coordinate of the widget’s upper-left outer corner, relative to the upper-left
inner corner of its parent.
574
Motif Reference Manual
Motif and Xt Widget Classes
Core
XmNy
The y-coordinate of the widget’s upper-left outer corner, relative to the upper-left
inner corner of its parent.
See Also
Object(2), RectObj(2).
Motif Reference Manual
575
Object
Motif and Xt Widget Classes
Name
Object widget class – fundamental object class.
Synopsis
Public Headers:
<Xm/Xm.h>
<X11/Object.h>
Class Name:
Object
Class Hierarchy:
Object
Class Pointer:
objectClass
Instantiation:
Object is an Intrinsics meta-class and is not normally instantiated.
Functions/Macros:
XtIsObject()
Description
Object is the root of the class hierarchy; it does not have a superclass. All widgets
and gadgets are subclasses of Object. Object encapsulates the mechanisms for
resource management and is never instantiated.
New Resources
Object defines the following resources:
Name
Class
Type
Default
Access
XmNdestroyCallback
XmCCallback
XtCallbackList
NULL
C
XmNdestroyCallback
List of callbacks invoked when the Object is destroyed.
See Also
Core(2).
576
Motif Reference Manual
Motif and Xt Widget Classes
OverrideShell
Name
OverrideShell widget class – a popup shell that bypasses window management.
Synopsis
Public Header:
<X11/Shell.h>
Class Name:
OverrideShell
Class Hierarchy:
Core → Composite → Shell → OverrideShell
Class Pointer:
overrideShellWidgetClass
Instantiation:
widget = XtCreatePopupShell (name, overrideShellWidgetClass,...)
Functions/Macros:
XtIsOverrideShell()
Description
OverrideShell is a direct subclass of Shell that performs no interaction with window managers. It is used for widgets, such as popup menus, that should bypass
the window manager.
New Resources
OverrideShell does not define any new resources.
Inherited Resources
OverrideShell inherits the following resources. The resources are listed alphabetically, along with the superclass that defines them. OverrideShell sets the default
values of both XmNoverrideRedirect and XmNsaveUnder to True.
Resource
Inherited From Resource
Inherited From
XmNaccelerators
Core
XmNinitialResourcesPersistent Core
XmNallowShellResize
Shell
XmNinsertPosition
XmNancestorSensitive
Core
XmNmappedWhenManaged
Core
XmNaudibleWarning
VendorShell
XmNnumChildren
Composite
Composite
XmNbackground
Core
XmNoverrideRedirect
Shell
XmNbackgroundPixmap
Core
XmNpopdownCalback
Shell
XmNborderColor
Core
XmNpopupCallback
Shell
XmNborderPixmap
Core
XmNsaveUnder
Shell
XmNborderWidth
Core
XmNscreen
Core
Motif Reference Manual
577
OverrideShell
Motif and Xt Widget Classes
Resource
Inherited From Resource
Inherited From
XmNchildren
Composite
XmNsensitive
Core
XmNcolormap
Core
XmNtranslations
Core
XmNcreatePopupChildProc Shell
XmNvisual
Shell
XmNdepth
Core
XmNwidth
Core
XmNdestroyCallback
Core
XmNx
Core
XmNgeometry
Shell
XmNy
Core
XmNheight
Core
See Also
Composite(2), Core(2), Shell(2).
578
Motif Reference Manual
Motif and Xt Widget Classes
RectObj
Name
RectObj widget class – fundamental object class with geometry.
Synopsis
Public Header:
<Xm/Xm.h>
<X11/RectObj.h>
Class Name:
RectObj
Class Hierarchy:
Object → RectObj
Class Pointer:
rectObjClass
Instantiation:
RectObj is an Intrinsics meta-class and is not normally instantiated.
Functions/Macros:
XtIsRectObj()
Description
RectObj is a supporting superclass for widgets and gadgets, defined by the X
toolkit intrinsics. All of the Motif widgets are ultimately derived from RectObj. It
does not have a window, but it does have a height, width, and location, and it
encapsulates the mechanisms for geometry management.
New Resources
RectObj defines the following resources:
Name
Class
Type
Default
XmNancestorSensitive
XmCSensitive
Boolean
dynamic
G
XmNborderWidth
XmCBorderWidth
Dimension
1
CSG
XmNheight
XmCHeight
Dimension
dynamic
CSG
XmNsensitive
XmCSensitive
Boolean
True
CSG
XmNwidth
XmCWidth
Dimension
dynamic
CSG
XmNx
XmCPosition
Position
0
CSG
XmNy
XmCPosition
Position
0
CSG
Motif Reference Manual
Access
579
RectObj
Motif and Xt Widget Classes
XmNancestorSensitive
Tells whether a gadget’s immediate parent should receive input. Default value is
the bitwise AND of the XmNsensitive and XmNancestorSensitive resources of
the parent.
XmNborderWidth
Width (in pixels) of the window’s border.
XmNheight
Window height (in pixels), excluding the border.
XmNsensitive
Tells whether a widget receives input (is sensitive). The XtSetSensitive() routine
can be used to change a widget’s sensitivity and to guarantee that if a parent has
its XmNsensitive resource set to False, then its children will have their ancestor-sensitive flag set correctly.
XmNwidth
Window width (in pixels), excluding the border.
XmNx
The x-coordinate of the widget’s upper-left outer corner, relative to the upper-left
inner corner of its parent.
XmNy
The y-coordinate of the widget’s upper-left outer corner (that is, outside of any
border or shadow rectangle), relative to its parents upper-left inner corner (inside
all border or shadow rectangles).
Inherited Resources
RectObj inherits the following resource:
Resource
Inherited From
XmNdestroyCallback
Core
See Also
Object(2).
580
Motif Reference Manual
Motif and Xt Widget Classes
SessionShell
Name
SessionShell widget class – the main shell for an application.
Synopsis
Public Headers:
<Xm/Xm.h>
<X11/Shell.h>
Class Name:
SessionShell
Class Hierarchy:
Core → Composite → Shell → WMShell → VendorShell → TopLevelShell →
ApplicationShell → SessionShell
Class Pointer:
sessionShellWidgetClass
Instantiation:
widget = XtAppInitialize (...)
or
widget = XtAppCreateShell (app_name, app_class,
sessionShellWidgetClass,...)
Functions/Macros:
XtAppCreateShell(), XtVaAppCreateShell(), XtIsSessionShell()
Availability
The Session shell is only available from X11R6.
Description
A SessionShell is the normal top-level window for an application. It does not
have a parent and it is at the root of the widget tree. An application should have
only one SessionShell, unless the application is implemented as multiple logical
applications. Normally, an application will use TopLevelShell widgets for other
top-level windows.
The SessionShell differs from the ApplicationShell in that it interfaces to the
X11R6 Session Management facilities, which enable applications to save or
restart themselves in a known state in response to commands from the desktop
A SessionShell is returned by the call to XtVaAppInitialize(). It can also
be created explicitly with a call to XtVaAppCreateShell().
Interaction with the user during session management is implemented through a
token-passing mechanism. A Checkpoint token is passed between the Session
Motif Reference Manual
581
SessionShell
Motif and Xt Widget Classes
Manager and the Session Shell callbacks; the application may interact with the
user directly (usually to ask the user if unsaved changes to the application should
be saved) only if the SessionShell of the application holds the token. The application may only interact with the user after issuing a request to do so. Issuing a
request takes the form of registering a procedure on the XtNinteractCallback list.
If and when the Session Manager decides that it is time to allow user interaction,
the interact procedures are invoked, with the checkpoint token passed to the
application through call_data for the procedures so registered. After the interaction with the user is complete, the application returns the checkpoint by calling
XtSessionReturnToken(). Unusually, callbacks on the XtNinteractCallback list are invoked one at a time; after the first procedure is called, it is removed
from the list.
New Resources
SessionShell defines the following resources:
Name
Class
Type
Default
Access
XtNcancelCallback
XtCCallback
XtNcloneCommand
XtCCloneCommand
XtCallbackList
NULL
C
String *
dynamic
CSG
XtNconnection
XtCConnection
SmcConn
NULL
CSG
XtNcurrentDirectory
XtCCurrentDirectory
String
NULL
CSG
XtNdieCallback
XtCCallback
XtCallbackList
NULL
C
XtNdiscardCommand
XtCDiscardCommand
String *
NULL
CSG
XtNenvironment
XtCEnvironment
String *
NULL
CSG
XtNerrorCallback
XtCCallback
XtCallbackList
NULL
C
XtNinteractCallback
XtCCallback
XtCallbackList
NULL
C
XtNjoinSession
XtCJoinSession
Boolean
True
CSG
XtNprogramPath
XtCProgramPath
String
dynamic
CSG
XtNresignCommand
XtCResignCommand
String *
NULL
CSG
XtNrestartCommand
XtCRestartCommand
String *
dynamic
CSG
XtNrestartStyle
XtCRestartStyle
unsigned char
SmRestartIfRunning
CSG
XtNsaveCallback
XtCCallback
XtCallbackList
NULL
C
XtNsaveCompleteCallback
XtCCallback
XtCallbackList
NULL
C
XtNsessionID
XtCSessionID
String
NULL
CSG
XtNshutdownCommand
XtCShutdownCommand
String *
NULL
CSG
XtNcancelCallback
List of callbacks to be invoked when the SessionShell receives a ShutdownCancelled message from the Session Manager.
582
Motif Reference Manual
Motif and Xt Widget Classes
SessionShell
XtNcloneCommand
Specifies a command which the Session Manager uses to create a new instance of
the application. If the value is NULL, the Session Manager will use the value of
the XtNrestartCommand resource.
XtNconnection
Specifies the connection between the SessionShell and the Session Manager.
Normally the SessionShell instantiates this value when the shell is created,
although the programmer can specify a value if the application has already established a private connection.
XtNcurrentDirectory
Specifies a location in the file system where the Session Manager should arrange
to restart the application when required to do so.
XtNdieCallback
List of callbacks invoked when the application receives a Die message from the
Session Manager. The application should take whatever steps are required to
cleanly terminate.
XtNdiscardCommand
Specifies a command which, if invoked, will cause the host to discard all information pertaining to the current application state. If NULL, the Session Manager
assumes that the application state is fully recoverable from the XtNrestartCommand specification.
XtNenvironment
Specifies the environment variables (and values) which the Session Manager
should set up prior to restarting the application. The resource is assumed to consist of a list of “name=value” strings.
XtNerrorCallback
List of callbacks to be invoked if the connection between the Session Manager
and the SessionShell becomes irrevocably lost. The XtNconnection is reset to
NULL by the SessionShell in these circumstances.
XtNinteractCallback
List of callbacks invoked when a client wants to interact with the user before a
session shutdown. This callback list is implemented in a special manner: each
time the Session Manager is issued a request to interact with the user, the Session
Manager calls and then removes the top callback from the list. Furthermore, the
request to interact with the user during Session Management operations is performed simply by registering a callback on this list. If there is more than one callback on the list, subsequent
callbacks below the top are not called until the application calls XtSessionReturnToken(), returning the checkpoint token to the Session Manager.
Motif Reference Manual
583
SessionShell
Motif and Xt Widget Classes
XtNjoinSession
Specifies whether the SessionShell should automatically initialize a connection
to the Session Manager. Setting the resource True at any time will initialize the
connection; subsequently setting it False will resign from the session.
XtNprogramPath
The full path of the program which is running. If NULL, the session management
uses the first element of the XtNrestartCommand array as the program path.
XtNresignCommand
Specifies a command which logically undoes the client: saved state should be
removed.
XtNrestartCommand
Specifies a command which should cause an instance of the application to be
invoked, such that it restarts in its current state. If NULL, the XmNargv resource
is used as fallback.
XtNrestartStyle
Specifies a hint to the session manager, indicating how the application would like
to be restarted. Possible values are:
SmRestartIfRunning
SmRestartAnyway
SmRestartImmediately
SmRestartNever
SmRestartIfRunning is the default, and specifies that the client should restart if it
was running at the end of the current session.
SmRestartAnyway specifies that the client should be restarted even if it terminated before the end of the current session.
SmRestartImmediately specifies that the client is meant to run continuously. If it
exits at any time, the session manager should restart it in the current session.
SmRestartNever specifies that the client should not be restarted under session
management control.
XtNsaveCallback
Specifies a list of callbacks to be invoked when the client receives a SaveYourself
message from the session manager. The procedures are responsible for saving the
application state.
XtNsaveCompleteCallback
Specifies a list of callbacks to be invoked when the session manager sends a
SaveComplete message to the client. Clients can continue their normal operations thereafter.
584
Motif Reference Manual
Motif and Xt Widget Classes
SessionShell
XtNsessionID
This resource identifies the client to the session manager. This is either assigned
by the session manager when connection is established, or deduced from any
-xtsessionID command line argument to the application.
XtNshutdownCommand
Specifies a command which the session manager will invoke at shutdown; the
command should clean up after the client, but not remove any saved state.
Callback Structure
Callbacks on the XtNsaveCallback and XtNinteractCallback lists are each passed
the following structure as call_data when invoked:
typedef struct _XtCheckpointTokenRec {
int
save_type;
int
interact_style;
Boolean
shutdown;
Boolean
fast;
Boolean
cancel_shutdown;
int
phase;
int
interact_dialog_type;
Boolean
request_cancel;
Boolean
request_next_phase;
Boolean
save_success;
int
type;
Widget
widget;
} XtCheckpointTokenRec, *XtCheckpointToken;
The save_type element indicates the type of information which the application
should attempt to save. Possible values are: SmSaveLocal, SmSaveGlobal,
SmSaveBoth.
The interact_style element indicates the kind of user interaction which is currently permitted. Possible values are: SmInteractStyleNone, SmInteractStyleErrors, SmInteractStyleAny.
The shutdown element indicates whether the save interaction is being performed
prior to a session shutdown.
If fast is True, the client should endeavour to save the minimum recovery state
possible.
If cancel_shutdown is True, the Session Manager has sent a ShutdownCancelled
message to the client.
Motif Reference Manual
585
SessionShell
Motif and Xt Widget Classes
The phase element is for specialized manager clients use only (the window manager), and indicates the state of the interaction between the Session Manager and
the client. The value will be either 1 or 2.
The remaining fields are where the client communicates back to the Session
Manager.
The interact_dialog_type element specifies the kind of interaction required by the
client. The initial value is SmDialogNormal, which is for a normal interactive
dialog. The value of SmDialogError requests an error dialog interaction.
The request_cancel element is only used by XtNinteractCallbacks, and is a hint
to the session manager that the client requests that the current shutdown operation should be cancelled.
The request_next_phase element is used by the specialized manager clients: the
default value is False, but can be set True by these clients.
The save_success element is where the client indicates to the Session Manager
the status of the application save-state operations. The value False indicates that
the client could not save its state successfully.
The type and widget fields are internal to the implementation, and are not to be
used by application programmers.
Inherited Resources
SessionShell inherits the following resources. The resources are listed alphabetically, along with the superclass that defines them. The default value of XmNborderWidth is reset to 0 by VendorShell.
586
Resource
Inherited From Resource
Inherited From
XmNaccelerators
Core
XmNlabelRenderTable
VendorShell
XmNallowShellResize
Shell
XmNlayoutDirection
VendorShell
XmNancestorSensitive
Core
XmNmappedWhenManaged Core
XmNargc
ApplicationShell
XmNmaxAspectX
WMShell
XmNargv
ApplicationShell
XmNmaxAspectY
WMShell
XmNaudibleWarning
VendorShell
XmNmaxHeight
WMShell
XmNbackground
Core
XmNmaxWIdth
WMShell
XmNbackgroundPixmap
Core
XmNminAspectX
WMShell
XmNbaseHeight
WMShell
XmNminAspectY
WMShell
XmNbaseWidth
WMShell
XmNminHeight
WMShell
XmNborderColor
Core
XmNminWidth
WMShell
XmNborderPixmap
Core
XmNmwmDecorations
VendorShell
Motif Reference Manual
Motif and Xt Widget Classes
SessionShell
Resource
Inherited From Resource
Inherited From
XmNborderWidth
Core
XmNmwmFunctions
VendorShell
XmNbuttonFontList
VendorShell
XmNmwmInputMode
VendorShell
XmNbuttonRenderTable
VendorShell
XmNmwmMenu
VendorShell
XmNchildren
Composite
XmNnumChildren
Composite
XmNcolormap
Core
XmNoverrideRedirect
Shell
XmNcreatePopupChildProc
Shell
XmNpopdownCalback
Shell
XmNdefaultFontList
VendorShell
XmNpopupCallback
Shell
XmNdeleteResponse
VendorShell
XmNpreeditType
VendorShell
XmNdepth
Core
XmNsaveUnder
Shell
XmNdestroyCallback
Core
XmNscreen
Core
XmNgeometry
Shell
XmNsensitive
Core
XmNheight
Core
XmNshellUnitType
VendorShell
XmNheightInc
WMShell
XmNtextFontList
VendorShell
XmNiconic
TopLevelShell
XmNtextRenderTable
VendorShell
XmNiconMask
WMShell
XmNtitle
WMShell
XmNiconName
TopLevelShell
XmNtitleEncoding
WMShell
XmNiconNameEncoding
TopLevelShell
XmNtransient
WMShell
XmNiconPixmap
WMShell
XmNtranslations
Core
XmNiconWindow
WMShell
XmNvisual
Shell
XmNinitialResourcesPersistent Core
XmNwaitForWm
WMShell
XmNinitialState
WMShell
XmNwidth
Core
XmNinput
WMShell
XmNwidthInc
WMShell
XmNinputMethod
VendorShell
XmNwindowGroup
WMShell
XmNinputPolicy
VendorShell
XmNwinGravity
WMShell
XmNinsertPosition
Composite
XmNwmTimeout
WMShell
XmNkeyboardFocusPolicy
VendorShell
XmNx
Core
XmNlabelFontList
VendorShell
XmNy
Core
The VendorShell superclass installs a handler which intercepts the window manager WM_DELETE_WINDOW message. The handler is inherited by sub-classes
of VendorShell, and has the behavior that if XmNdeleteResponse is XmDESTROY, and the widget is an instance of an ApplicationShell, then the application context associated with the widget is destroyed, followed by a call to exit().
Motif Reference Manual
587
SessionShell
Motif and Xt Widget Classes
See Also
ApplicationShell(2), Composite(2), Core(2), Shell(2),
TopLevelShell(2), VendorShell(2), WMShell(2).
588
Motif Reference Manual
Motif and Xt Widget Classes
Shell
Name
Shell widget class – fundamental widget class that controls interaction between
top-level windows and the window manager.
Synopsis
Public Header:
<Xm/Xm.h>
<X11/Shell.h>
Class Name:
Shell
Class Hierarchy:
Core → Composite → Shell
Class Pointer:
shellWidgetClass
Instantiation:
Shell is an Intrinsics meta-class and is not normally instantiated.
Functions/Macros:
XtIsShell()
Description
Shell is a subclass of Composite that handles interaction between the window
manager and its single child.
New Resources
Shell defines the following resources:
Name
Class
Type
Default
Access
XmNallowShellResize
XmCAllowShellResize
Boolean
False
CSG
XmNcreatePopupChildProc XmCCreatePopupChildProc XtCreatePopupChildProc NULL
CSG
XmNgeometry
XmCGeometry
String
NULL
CSG
XmNoverrideRedirect
XmCOverrideRedirect
Boolean
False
CSG
XmNpopdownCallback
XmCCallback
XtCallbackList
NULL
C
XmNpopupCallback
XmCCallback
XtCallbackList
NULL
C
XmNsaveUnder
XmCSaveUnder
Boolean
False
CSG
XmNvisual
XmCVisual
Visual *
CopyFromParent CSG
XmNallowShellResize
If False (default), the Shell widget refuses geometry requests from its children
(by returning XtGeometryNo).
Motif Reference Manual
589
Shell
Motif and Xt Widget Classes
XmNcreatePopupChildProc
A pointer to an XtCreatePopupChildProc procedure that creates a child
widget--but only when the shell is popped up, not when the application is started.
This is useful in menus, for example, since you don’t need to create the menu
until it is popped up. This procedure is called after any callbacks specified in the
XmNpopupCallback resource.
XmNgeometry
This resource specifies the values for the resources XmNx, XmNy, XmNwidth,
and
XmNheight in situations where an unrealized widget has added or removed
some of its managed children.
XmNoverrideRedirect
If True, the widget is considered a temporary window that redirects the keyboard
focus away from the main application windows. Usually this resource shouldn’t
be changed.
XmNpopdownCallback
List of callbacks that are called when the widget is popped down using XtPopdown().
XmNpopupCallback
List of callbacks that are called when the widget is popped up using XtPopup().
XmNsaveUnder
If True, screen contents that are obscured by a widget are saved, thereby avoiding
the overhead of sending expose events after the widget is unmapped.
XmNvisual
The visual server resource that is used when creating the widget.
Procedures
XtCreatePopupChildProc
An XtCreatePopupChildProc is a pointer to a procedure, specified as follows:
typedef void (*XtCreatePopupChildProc) (Widget);
An XtCreatePopupChildProc procedure is called when a Shell or derived class is
popped up, typically through a call to XtPopup(). The function has a single
parameter, which is the widget ID of the shell.
590
Motif Reference Manual
Motif and Xt Widget Classes
Shell
Inherited Resources
Shell inherits the following resources. The resources are listed alphabetically,
along with the superclass that defines them.
Name
Inherited From
Name
Inherited From
XmNaccelerators
Core
XmNheight
Core
XmNancestorSensitive
Core
XmNinsertPosition
Composite
XmNbackground
Core
XmNinitialResourcesPersistent
Core
XmNbackgroundPixmap
Core
XmNmappedWhenManaged
Core
XmNborderColor
Core
XmNnumChildren
Composite
XmNborderPixmap
Core
XmNscreen
Core
XmNborderWidth
Core
XmNsensitive
Core
XmNchildren
Composite
XmNtranslations
Core
XmNcolormap
Core
XmNwidth
Core
XmNdepth
Core
XmNx
Core
XmNdestroyCallback
Core
XmNy
Core
See Also
Composite(2), Core(2).
Motif Reference Manual
591
TopLevelShell
Motif and Xt Widget Classes
Name
TopLevelShell widget class – additional top-level shells for an application.
Synopsis
Public Header:
<Xm/Xm.h>
<X11/Shell.h>
Class Name:
TopLevelShell
Class Hierarchy:
Core → Composite → Shell → WMShell → VendorShell → TopLevelShell
Class Pointer:
topLevelShellWidgetClass
Instantiation:
widget = XtCreatePopupShell (name, topLevelShellWidgetClass,...)
Functions/Macros:
XtIsTopLevelShell()
Description
TopLevelShell is a subclass of VendorShell that is used for additional shells in
applications having more than one top-level window.
New Resources
TopLevelShell defines the following resources:
Name
Class
Type
Default
Access
XmNiconic
XmCIconic
Boolean
False
CSG
XmNiconName
XmCIconName
String
NULL
CSG
XmNiconNameEncoding
XmCIconNameEncoding
Atom
dynamic
CSG
XmNiconic
If True, the widget is realized as an icon, otherwise as a normal window. XmNiconic overrides the value of the inherited XmNinitialState resource.
XmNiconName
The abbreviated name that labels an iconified application.
XmNiconNameEncoding
The property type for encoding the XmNiconName resource.
592
Motif Reference Manual
Motif and Xt Widget Classes
TopLevelShell
Inherited Resources
TopLevelShell inherits the following resources. The resources are listed alphabetically, along with the superclass that defines them. TopLevelShell resets
XmNinput to True.
Resource
Inherited From Resource
Inherited From
XmNaccelerators
Core
WMShell
XmNmaxAspectX
XmNallowShellResize
Shell
XmNmaxAspectY
WMShell
XmNancestorSensitive
Core
XmNmaxHeight
WMShell
XmNaudibleWarning
VendorShell
XmNmaxWIdth
WMShell
XmNbackground
Core
XmNminAspectX
WMShell
XmNbackgroundPixmap
Core
XmNminAspectY
WMShell
XmNbaseHeight
WMShell
XmNminHeight
WMShell
XmNbaseWidth
WMShell
XmNminWidth
WMShell
XmNborderColor
Core
XmNmwmDecorations VendorShell
XmNborderPixmap
Core
XmNmwmFunctions
VendorShell
XmNborderWidth
Core
XmNmwmInputMode
VendorShell
XmNbuttonFontList
VendorShell
XmNmwmMenu
VendorShell
XmNbuttonRenderTable
VendorShell
XmNnumChildren
Composite
XmNchildren
Composite
XmNoverrideRedirect
Shell
XmNcolormap
Core
XmNpopdownCalback Shell
XmNcreatePopupChildProc
Shell
XmNpopupCallback
Shell
XmNdefaultFontList
VendorShell
XmNpreeditType
VendorShell
XmNdeleteResponse
VendorShell
XmNsaveUnder
Shell
XmNdepth
Core
XmNscreen
Core
XmNdestroyCallback
Core
XmNsensitive
Core
XmNgeometry
Shell
XmNshellUnitType
VendorShell
XmNheight
Core
XmNtextFontList
VendorShell
XmNheightInc
WMShell
XmNtextRenderTable
VendorShell
XmNiconMask
WMShell
XmNtitle
WMShell
XmNiconPixmap
WMShell
XmNtitleEncoding
WMShell
XmNiconWindow
WMShell
XmNtransient
WMShell
XmNinitialResourcesPersistent Core
XmNtranslations
Core
XmNinitialState
WMShell
XmNvisual
Shell
XmNinput
WMShell
XmNwaitForWm
WMShell
XmNinputMethod
VendorShell
XmNwidth
Core
Motif Reference Manual
593
TopLevelShell
Resource
Motif and Xt Widget Classes
Inherited From Resource
Inherited From
XmNinputPolicy
VendorShell
XmNwidthInc
WMShell
XmNinsertPosition
Composite
XmNwindowGroup
WMShell
XmNkeyboardFocusPolicy
VendorShell
XmNwinGravity
WMShell
XmNlabelFontList
VendorShell
XmNwmTimeout
WMShell
XmNlabelRenderTable
VendorShell
XmNx
Core
XmNlayoutDirection
VendorShell
XmNy
Core
XmNmappedWhenManaged
Core
See Also
Composite(2), Core(2). Shell(2), VendorShell(2), WMShell(2).
594
Motif Reference Manual
Motif and Xt Widget Classes
TransientShell
Name
TransientShell widget class – popup shell that interacts with the window manager.
Synopsis
Public Header:
<Xm/Xm.h>
<X11/Shell.h>
Class Name:
TransientShell
Class Hierarchy:
Core → Composite → Shell → WMShell → VendorShell → TransientShell
Class Pointer:
transientShellWidgetClass
Instantiation:
Functions/Macros:
XtIsTransientShell()
Description
TransientShell is a subclass of VendorShell that is used for popup shell widgets,
such as dialog boxes, that interact with the window manager. Most window managers will not allow the user to iconify a TransientShell window on its own and
may iconify it automatically if the window that it is transient for is iconified.
New Resources
TransientShell defines the following resources:
Name
Class
Type
Default
Access
XmNtransientFor
XmCTransientFor
Widget
NULL
CSG
XmNtransientFor
The widget from which the TransientShell will pop up. If the value of this
resource is NULL or identifies an unrealized widget, then TransientShell uses the
value of the WMShell resource XmNwindowGroup.
Motif Reference Manual
595
TransientShell
Motif and Xt Widget Classes
Inherited Resources
TransientShell inherits the following resources. The resources are listed alphabetically, along with the superclass that defines them. TransientShell resets the
resources XmNinput, XmNtransient, and XmNsaveUnder to True.
596
Resource
Inherited From Resource
Inherited From
XmNaccelerators
Core
WMShell
XmNmaxAspectX
XmNallowShellResize
Shell
XmNmaxAspectY
WMShell
XmNancestorSensitive
Core
XmNmaxHeight
WMShell
XmNaudibleWarning
VendorShell
XmNmaxWIdth
WMShell
XmNbackground
Core
XmNminAspectX
WMShell
XmNbackgroundPixmap
Core
XmNminAspectY
WMShell
XmNbaseHeight
WMShell
XmNminHeight
WMShell
XmNbaseWidth
WMShell
XmNminWidth
WMShell
XmNborderColor
Core
XmNmwmDecorations VendorShell
XmNborderPixmap
Core
XmNmwmFunctions
VendorShell
XmNborderWidth
Core
XmNmwmInputMode
VendorShell
XmNbuttonFontList
VendorShell
XmNmwmMenu
VendorShell
XmNbuttonRenderTable
VendorShell
XmNnumChildren
Composite
XmNchildren
Composite
XmNoverrideRedirect
Shell
XmNcolormap
Core
XmNpopdownCalback Shell
XmNcreatePopupChildProc
Shell
XmNpopupCallback
Shell
XmNdefaultFontList
VendorShell
XmNpreeditType
VendorShell
XmNdeleteResponse
VendorShell
XmNsaveUnder
Shell
XmNdepth
Core
XmNscreen
Core
XmNdestroyCallback
Core
XmNsensitive
Core
XmNgeometry
Shell
XmNshellUnitType
VendorShell
XmNheight
Core
XmNtextFontList
VendorShell
XmNheightInc
WMShell
XmNtextRenderTable
VendorShell
XmNiconMask
WMShell
XmNtitle
WMShell
XmNiconPixmap
WMShell
XmNtitleEncoding
WMShell
XmNiconWindow
WMShell
XmNtransient
WMShell
XmNinitialResourcesPersistent Core
XmNtranslations
Core
XmNinitialState
WMShell
XmNvisual
Shell
XmNinput
WMShell
XmNwaitForWm
WMShell
XmNinputMethod
VendorShell
XmNwidth
Core
Motif Reference Manual
Motif and Xt Widget Classes
Resource
TransientShell
Inherited From Resource
Inherited From
XmNinputPolicy
VendorShell
XmNwidthInc
WMShell
XmNinsertPosition
Composite
XmNwindowGroup
WMShell
XmNkeyboardFocusPolicy
VendorShell
XmNwinGravity
WMShell
XmNlabelFontList
VendorShell
XmNwmTimeout
WMShell
XmNlabelRenderTable
VendorShell
XmNx
Core
XmNlayoutDirection
VendorShell
XmNy
Core
XmNmappedWhenManaged
Core
See Also
Composite(2), Core(2), Shell(2), VendorShell(2), WMShell(2).
Motif Reference Manual
597
VendorShell
Motif and Xt Widget Classes
Name
VendorShell widget class – shell widget with Motif-specific hooks for window
manager interaction.
Synopsis
Public Header:
<Xm/VendorS.h>
<X11/Shell.h>
Class Name:
VendorShell
Class Hierarchy:
Core → Composite → Shell → WMShell → VendorShell
Class Pointer:
vendorShellWidgetClass
Instantiation:
VendorShell is a meta-class and is not normally instantiated.
Functions/Macros:
XmIsVendorShell()
Description
VendorShell is a vendor-specific supporting superclass for all shell classes that
are visible to the window manager and that do not have override redirection. VendorShell defines resources that provide the Motif look-and-feel and manages the
specific communication needed by the Motif Window Manager (mwm).
Traits
VendorShell holds the XmQTspecifyRenderTable, XmQTspecifyLayoutDirection, XmQTaccessColors and XmQTspecifyUnitType
traits, which are inherited by any derived classes, and uses the XmQTspecifyRenderTable trait.
New Resources
VendorShell defines the following resources:
Name
Class
Type
Default
Access
XmNaudibleWarning
XmCAudibleWarning
unsigned char
XmBELL
CSG
XmNbuttonFontList
XmCButtonFontList
XmFontList
dynamic
CSG
XmNbuttonRenderTable
XmCButtonRenderTable
XmRenderTable dynamic
CSG
XmNdefaultFontList
XmCDefaultFontList
XmFontList
dynamic
CG
XmNdeleteResponse
XmCDeleteResponse
unsigned char
XmDESTROY
CSG
XmNinputMethod
XmCInputMethod
String
NULL
CSG
598
Motif Reference Manual
Motif and Xt Widget Classes
VendorShell
Name
Class
Type
Default
Access
XmNinputPolicy
XmCInputPolicy
XmInputPolicy
XmPER_SHELL
CSG
XmNkeyboardFocusPolicy XmCKeyboardFocusPolicy unsigned char
XmEXPLICIT
CSG
XmNlabelFontList
XmCLabelFontList
XmFontList
dynamic
CG
XmNlabelRenderTable
XmCLabelRenderTable
XmRenderTable dynamic
XmNlayoutDirection
XmCLayoutDirection
XmDirection
XmLEFT_TO_RIGHT CG
XmNmwmDecorations
XmCMwMDecorations
int
-1
CSG
XmNmwmFunctions
XmCMwMFunctions
int
-1
CSG
XmNmwmInputMode
XmCMwMInputMode
int
-1
CSG
XmNmwmMenu
XmCMwmMenu
String
NULL
XmNpreeditType
XmCPreeditType
String
dynamic
CSG
CSG
XmNshellUnitType
XmCShellUnitType
unsigned char
XmPIXELS
CSG
XmNtextFontList
XmCTextFontList
XmFontList
dynamic
CG
XmNtextRenderTable
XmCTextRenderTable
XmRenderTable dynamic
CSG
XmNuseAsyncGeometry
XmCUseAsyncGeometry
Boolean
False
CSG
XmNunitType
XmCUnitType
unsigned char
XmPIXELS
CSG
XmNaudibleWarning
Specifies whether an action performs an associated audible cue. Possible values:
XmBELL
XmNONE
/* rings the bell */
/* does nothing */
XmNbuttonFontList
Specifies the font list used for the button descendants of the VendorShell widget.
In Motif 2.0 and later, the XmFontList is considered obsolete, and is replaced by
the XmRenderTable. The XmNbuttonRenderTable resource is the preferred
method of specifying appearance.
XmNbuttonRenderTable
In Motif 2.0 and later, specifies the render table to be used by VendorShell’s button descendants. If initially NULL, the value is taken from any specified XmNdefaultFontList value for backwards compatability. If this is also NULL, the nearest
ancestor which has the XmQTspecifyRenderTable trait is sought, taking the
XmBUTTON_RENDER_TABLE value from any widget so found.
XmNdefaultFontList
The default font list for the children of the VendorShell widget. The resource is
obsolete, replaced by the XmNbuttonFontList, XmNlabelFontList, and XmNtextFontList resources, which are in their turn also obsolete.
Motif Reference Manual
599
VendorShell
Motif and Xt Widget Classes
XmNdeleteResponse
The action to perform when the shell receives a WM_DELETE_WINDOW message. Possible values:
XmDESTROY
XmUNMAP
XmDO_NOTHING
/* destroy window
/* unmap window
/* leave window as is
*/
*/
*/
XmNinputMethod
Specifies the string that sets the locale modifier for the input method.
XmNinputPolicy
In Motif 2.0 and later, specifies the policy to adopt when creating an Input Context. Possible values:
XmPER_SHELL
XmPER_WIDGET
/* one input context per shell hierarchy */
/* one input context per widget
*/
XmNkeyboardFocusPolicy
The method of assigning keyboard focus. Possible values:
XmEXPLICIT
XmPOINTER
/* click-to-type policy
/* pointer-driven policy
*/
*/
XmNlabelFontList
Specifies the font list used for the label descendants of the VendorShell widget. In
Motif 2.0 and later, the XmFontList is considered obsolete, and is replaced by the
XmRenderTable. The XmNlabelRenderTable resource is the preferred method of
specifying appearance.
XmNlabelRenderTable
In Motif 2.0 and later, specifies the render table to be used by VendorShell’s label
descendants. If initially NULL, the value is taken from any specified XmNdefaultFontList value for backwards compatability. If this is also NULL, the nearest
ancestor which has the XmQTspecifyRenderTable trait is sought, taking the
XmLABEL_RENDER_TABLE value from any widget so found.
XmNlayoutDirection
In Motif 2.0 and later, specifies the default direction in which visual components
are to be laid out. Descendants of VendorShell use this value in the absence of an
explicit layout direction further down the widget hierarchy. Possible values:
XmLEFT_TO_RIGHT
XmRIGHT_TO_LEFT
XmBOTTOM_TO_TOP
XmTOP_TO_BOTTOM
XmBOTTOM_TO_TOP_LEFT_TO_RIGHT
XmBOTTOM_TO_TOP_RIGHT_TO_LEFT
600
Motif Reference Manual
Motif and Xt Widget Classes
VendorShell
XmTOP_TO_BOTTOM_LEFT_TO_RIGHT
XmTOP_TO_BOTTOM_RIGHT_TO_LEFT
XmLEFT_TO_RIGHT_BOTTOM_TO_TOP
XmRIGHT_TO_LEFT_BOTTOM_TO_TOP
XmLEFT_TO_RIGHT_TOP_TO_BOTTOM
XmRIGHT_TO_LEFT_TOP_TO_BOTTOM
XmNmwmDecorations
This resource corresponds to the values assigned by the decorations field of the
_MOTIF_WM_HINTS property. This resource determines which frame buttons
and handles to include with a window. The value for the resource is a bitwise
inclusive OR of one or more of the following, which are defined in <Xm/MwmUtil.h>:
MWM_DECOR_ALL
MWM_DECOR_BORDER
MWM_DECOR_RESIZEH
MWM_DECOR_TITLE
MWM_DECOR_MENU
MWM_DECOR_MINIMIZE
MWM_DECOR_MAXIMIZE
*/
*/
*/
*/
*/
*/
*/
/* remove decorations from full set
/* window border
/* resize handles
/* title bar
/* window’s menu button
/* minimize button
/* maximize button
XmNmwmFunctions
This resource corresponds to the values assigned by the functions field of the
_MOTIF_WM_HINTS property. This resource determines which functions to
include in the system menu. The value for the resource is a bitwise inclusive OR
of one or more of the following, which are defined in the header file
<Xm/MwmUtil.h>.
MWM_FUNC_ALL
MWM_FUNC_RESIZE
MWM_FUNC_MOVE
MWM_FUNC_MINIMIZE
MWM_FUNC_MAXIMIZE
MWM_FUNC_CLOSE
/* remove functions from full set
/* f.resize
/* f.move
/* f.minimize
/* f.maximize
/* f.kill
*/
*/
*/
*/
*/
*/
XmNmwmInputMode
This resource corresponds to the values assigned by the input_mode field of the
_MOTIF_WM_HINTS property. This resource determines the constraints on the
window’s keyboard focus. That is, it determines whether the application takes the
keyboard focus away from the primary window or not. The possible values are as
follows, defined in <Xm/MwmUtil.h>:
MWM_INPUT_MODELESS1
MWM_INPUT_PRIMARY_APPLICATION_MODAL
Motif Reference Manual
601
VendorShell
Motif and Xt Widget Classes
MWM_INPUT_SYSTEM_MODAL
MWM_INPUT_FULL_APPLICATION_MODAL
If the value is MWM_INPUT_MODELESS, input can be directed to any window. If the value is MWM_INPUT_PRIMARY_APPLICATION_MODAL,
input can not be directed at an ancestor of the window. The value
MWM_INPUT_SYSTEM_MODAL indicates that input only goes to the current
window. MWM_INPUT_FULL_APPLICATION_MODAL specifies that input
may not be directed at any other window of the application.
XmNmwmMenu
The menu items to add at the bottom of the client’s window menu. The string has
this format:
label [mnemonic] [accelerator] mwm_f.function
XmNpreeditType
Specifies the input method style(s) that are available. The resource value is a
comma separated list of the following values:
OffTheSpot
Root
None
OverTheSpot
OnTheSpot
/* XIMPreeditArea
/* XIMPreeditNothing
/* XIMPreeditNone
/* XIMPreeditPosition
/* XIMPreeditCallbacks
*/
*/
*/
*/
*/
XmNshellUnitType
The measurement units to use in resources that specify a size or position. In
Motif 2.0 and later, the resource is obsolete, being replaced by the XmNunitType
resource.
XmNtextFontList
Specifies the font list used for the text descendants of the VendorShell widget. In
Motif 2.0 and later, the XmFontList is considered obsolete, and is replaced by the
XmRenderTable. The XmNtextRenderTable resource is the preferred method of
specifying appearance.
XmNtextRenderTable
In Motif 2.0 and later, specifies the render table to be used by VendorShell’s text
and list descendants. If initially NULL, the value is taken from any specified
XmNdefaultFontList value for backwards compatability. If this is also NULL, the
nearest ancestor which has the XmQTspecifyRenderTable trait is sought, taking
the XmTEXT_RENDER_TABLE value from any widget so found.
1.Erroneously given as MWM_INPUT_MODELES in 2nd edition.
602
Motif Reference Manual
Motif and Xt Widget Classes
VendorShell
XmNuseAsyncGeometry
If True, the geometry manager doesn’t wait to confirm a geometry request that
was sent to the window manager. The geometry manager performs this by setting
the WMShell resource XmNwaitForWm to False and by setting the WMShell
resource XmNwmTimeout to 0.
If XmNuseAsyncGeometry is False (default), the geometry manager uses synchronous notification, and so it doesn’t change the resources XmNwaitForWm
and XmNwmTimeout.
XmNunitType
In Motif 2.0 and later, specifies the units in which size and position resources are
calculated. The resource replaces XmNshellUnitType, which is considered obsolete. The values XmFONT_UNITS and Xm100TH_FONT_UNITS have a horizontal and vertical component, calculated from the values of the
XmNhorizontalFontUnit and XmNverticalFontUnit resources of the XmScreen
object. Possible values:
XmPIXELS
XmMILLIMETERS
Xm100TH_MILLIMETERS
XmCENTIMETERS
XmINCHES
Xm1000TH_INCHES
XmPOINTS
Xm100TH_POINTS
XmFONT_UNITS
Xm100TH_FONT_UNITS
/* pixels
/* millimeters
/* 1/100 of a millimeter
/* centimeters
/* inches
/* 1/1000 of an inch
/* point units (1/72 of an inch)
/* 1/100 of a point
/* depends on XmScreen resources
/* 1/100 of the above
*/
*/
*/
*/
*/
*/
*/
*/
*/
*/
Inherited Resources
VendorShell inherits the following resources. The resources are listed alphabetically, along with the superclass that defines them. VendorShell resets XmNborderWidth from 1 to 0 and resets XmNinput to True.
Resource
Inherited From Resource
Inherited From
XmNaccelerators
Core
XmNmaxAspectX
WMShell
XmNallowShellResize
Shell
XmNmaxAspectY
WMShell
XmNancestorSensitive
Core
XmNmaxHeight
WMShell
XmNbackground
Core
XmNmaxWIdth
WMShell
XmNbackgroundPixmap
Core
XmNminAspectX
WMShell
XmNbaseHeight
WMShell
XmNminAspectY
WMShell
XmNbaseWidth
WMShell
XmNminHeight
WMShell
Motif Reference Manual
603
VendorShell
Motif and Xt Widget Classes
Resource
Inherited From Resource
Inherited From
XmNborderColor
Core
XmNminWidth
WMShell
XmNborderPixmap
Core
XmNnumChildren
Composite
XmNborderWidth
Core
XmNoverrideRedirect
Shell
XmNchildren
Composite
XmNpopdownCalback Shell
XmNcolormap
Core
XmNpopupCallback
Shell
XmNcreatePopupChildProc
Shell
XmNsaveUnder
Shell
XmNdepth
Core
XmNscreen
Core
XmNdestroyCallback
Core
XmNsensitive
Core
XmNgeometry
Shell
XmNtitle
WMShell
XmNheight
Core
XmNtitleEncoding
WMShell
XmNheightInc
WMShell
XmNtransient
WMShell
XmNiconic
TopLevelShell
XmNtranslations
Core
XmNiconMask
WMShell
XmNvisual
Shell
XmNiconName
TopLevelShell
XmNwaitForWm
WMShell
XmNiconNameEncoding
TopLevelShell
XmNwidth
Core
XmNiconPixmap
WMShell
XmNwidthInc
WMShell
XmNiconWindow
WMShell
XmNwindowGroup
WMShell
XmNinitialResourcesPersistent Core
XmNwinGravity
WMShell
XmNinitialState
WMShell
XmNwmTimeout
WMShell
XmNinput
WMShell
XmNx
Core
XmNinsertPosition
Composite
XmNy
Core
XmNmappedWhenManaged
Core
See Also
Composite(2), Core(2), Shell(2), WMShell(2).
604
Motif Reference Manual
Motif and Xt Widget Classes
WMShell
Name
WMShell widget class – fundamental shell widget that interacts with an
ICCCM-compliant window manager.
Synopsis
Public Header:
<Xm/Xm.h>
<X11/Shell.h>
Class Name:
WMShell
Class Hierarchy:
Core → Composite → Shell → WMShell
Class Pointer:
wmShellWidgetClass
Instantiation:
WMShell is an Intrinsics meta-class and is not normally instantiated.
Functions/Macros:
XtIsWMShell()
Description
WMShell is a direct subclass of Shell that provides basic window manager interaction. WMShell is not directly instantiated; it encapsulates the application
resources that applications use to communicate with window managers.
New Resources
WMShell defines the following resources:
Name
Class
Type
Default
Access
XmNbaseHeight
XmCBaseHeight
int
XtUnspecifiedShellInt
CSG
XmNbaseWidth
XmCBaseWidth
int
XtUnspecifiedShellInt
CSG
XmNheightInc
XmCHeightInc
int
XtUnspecifiedShellInt
CSG
XmNiconMask
XmCIconMask
Pixmap
NULL
CSG
XmNiconPixmap
XmCIconPixmap
Pixmap
NULL
CSG
XmNiconWindow
XmCIconWindow
Window
NULL
CSG
XmNinitialState
XmCInitialState
int
NormalState
CSG
XmNiconX
XmCIconY
int
-1
CSG
XmNiconY
XmCIconY
int
-1
CSG
XmNinput
XmCInput
Boolean
False
CSG
XmNmaxAspectX
XmCMaxAspectX
int
XtUnspecifiedShellInt
CSG
Motif Reference Manual
605
WMShell
Motif and Xt Widget Classes
Name
Class
Type
Default
Access
XmNmaxAspectY
XmCMaxAspectY
int
XtUnspecifiedShellInt
CSG
XmNmaxHeight
XmCMaxHeight
int
XtUnspecifiedShellInt
CSG
XmNmaxWIdth
XmCMaxWidth
int
XtUnspecifiedShellInt
CSG
XmNminAspectX
XmCMinAspectX
int
XtUnspecifiedShellInt
CSG
XmNminAspectY
XmCMinAspectY
int
XtUnspecifiedShellInt
CSG
XmNminHeight
XmCMinHeight
int
XtUnspecifiedShellInt
CSG
XmNminWidth
XmCMinWidth
int
XtUnspecifiedShellInt
CSG
XmNtitle
XmCTitle
String
dynamic
CSG
XmNtitleEncoding
XmCTitleEncoding
Atom
dynamic
CSG
XmNtransient
XmCTransient
Boolean
False
CSG
XmNwaitForWm
XmCWaitForWm
Boolean
True
CSG
XmNwidthInc
XmCWidthInc
int
XtUnspecifiedShellInt
CSG
XmNwindowGroup
XmCWindowGroup Window
dynamic
CSG
XmNwinGravity
XmCWinGravity
int
dynamic
CSG
XmNwmTimeout
XmCWmTimeout
int
5000
CSG
XmNbaseHeight
XmNbaseWidth
The base dimensions from which the preferred height and width can be stepped
up or down (as specified by XmNheightInc or XmNwidthInc).
XmNheightInc
The amount by which to increment or decrement the window’s height when the
window manager chooses a preferred value. The base height is XmNbaseHeight,
and the height can decrement to the value of XmNminHeight or increment to the
value of XmN-maxHeight. See also XmNwidthInc.
XmNiconMask
A bitmap that the window manager can use in order to clip the application’s icon
into a non-rectangular shape.
XmNiconPixmap
The application’s icon.
XmNiconWindow
The ID of a window that serves as the application’s icon.
XmNiconX
XmNiconY
Window manager hints for the root window coordinates of the application’s icon.
606
Motif Reference Manual
Motif and Xt Widget Classes
WMShell
XmNinitialState
The initial appearance of the widget instance. Possible values are defined in
<X11/Xutil.h>:
NormalState
IconicState
/* application starts as a window */
/* application starts as an icon */
XmNinput
A Boolean that, in conjunction with the WM_TAKE_FOCUS atom in the
WM_PROTOCOLS property, determines the application’s keyboard focus
model. The result is determined by the value of XmNinput and the existence of
the atom, as described below:
Value of XmNinput Resource
WM_TAKE_FOCUS Atom
Keyboard Focus Model
False
Does not exist
No input allowed
True
Does not exist
Passive
False
Exists
Globally active
True
Exists
Locally active
XmNmaxAspectX
XmNmaxAspectY
The numerator and denominator, respectively, of the maximum aspect ratio
requested for this widget.
XmNmaxHeight
XmNmaxWidth
The maximum dimensions for the widget’s preferred height or width.
XmNminAspectX
XmNminAspectY
The numerator and denominator, respectively, of the minimum aspect ratio
requested for this widget.
XmNminHeight
XmNminWidth
The minimum dimensions for the widget’s preferred height or width.
XmNtitle
The string that the window manager displays as the application’s name. By
default, the icon name is used, but if this isn’t specified, the name of the application is used.
Motif Reference Manual
607
WMShell
Motif and Xt Widget Classes
XmNtitleEncoding
The property type for encoding the XmNtitle resource.
XmNtransient
If True, this indicates a popup window or some other transient widget. This
resource is usually not changed.
XmNwaitForWm
If True (default), the X Toolkit waits for a response from the window manager
before acting as if no window manager exists. The waiting time is specified by
the XmNwmTimeout resource.
XmNwidthInc
The amount by which to increment or decrement the window’s width when the
window manager chooses a preferred value. The base width is XmNbaseWidth,
and the width can decrement to the value of XmNminWidth or increment to the
value of XmN-maxWidth. See also XmNheightInc.
XmNwindowGroup
The window associated with this widget instance. This window acts as the primary window of a group of windows that have similar behavior.
XmNwinGravity
The window gravity used in positioning the widget. Unless an initial value is
given, this resource will be set when the widget is realized. The default value is
NorthWestGravity (if the Shell resource XmNgeometry is NULL); otherwise,
XmNwinGravity assumes the value returned by the XmWMGeometry routine.
XmNwmTimeout
The number of milliseconds that the X Toolkit waits for a response from the window manager. This resource is meaningful when the XmNwaitForWm resource
is set to True.
Inherited Resources
WMShell inherits the following resources. The resources are listed alphabetically, along with the superclass that defines them.
608
Resource
Inherited From Resource
XmNaccelerators
Core
Inherited From
XmNinitialResourcesPersistent Core
XmNallowShellResize
Shell
XmNinsertPosition
Composite
XmNancestorSensitive
Core
XmNmappedWhenManaged
Core
XmNbackground
Core
XmNnumChildren
Composite
XmNbackgroundPixmap
Core
XmNoverrideRedirect
Shell
XmNborderColor
Core
XmNpopdownCalback
Shell
XmNborderPixmap
Core
XmNpopupCallback
Shell
Motif Reference Manual
Motif and Xt Widget Classes
WMShell
Resource
Inherited From Resource
Inherited From
XmNborderWidth
Core
XmNsaveUnder
Shell
XmNchildren
Composite
XmNscreen
Core
XmNcolormap
Core
XmNsensitive
Core
XmNtranslations
Core
XmNcreatePopupChildProc Shell
XmNdepth
Core
XmNvisual
Shell
XmNdestroyCallback
Core
XmNwidth
Core
XmNgeometry
Shell
XmNx
Core
XmNheight
Core
XmNy
Core
See Also
Composite(2), Core(2), Shell(2).
Motif Reference Manual
609
XmArrowButton
Motif and Xt Widget Classes
Name
XmArrowButton widget class – a directional arrow-shaped button widget.
Synopsis
Public Header:
<Xm/ArrowB.h>
Class Name:
XmArrowButton
Class Hierarchy:
Core → XmPrimitive → XmArrowButton
Class Pointer:
xmArrowButtonWidgetClass
Instantiation:
widget = XmCreateArrowButton (parent, name,...)
or
widget = XtCreateWidget (name, xmArrowButtonWidgetClass,...)
Functions/Macros:
XmCreateArrowButton(), XmIsArrowButton()
Description
An ArrowButton is a directional arrow-shaped button that includes a shaded border. The shading changes to make the ArrowButton appear either pressed in
when selected or raised when unselected.
Traits
ArrowButton holds the XmQTactivatable trait, which is inherited by any derived
classes.
New Resources
ArrowButton defines the following resources:
Name
Class
Type
XmNarrowDirection
XmCArrowDirection
unsigned char XmARROW_UP CSG
XmNdetailShadowThickness XmCShadowThickness Dimension
XmNmultiClick
XmCMultiClick
Default
Access
dynamic
CSG
unsigned char dynamic
CSG
XmNarrowDirection
Sets the arrow direction. Possible values:
XmARROW_UP
XmARROW_DOWN
610
XmARROW_LEFT
XmARROW_RIGHT
Motif Reference Manual
Motif and Xt Widget Classes
XmArrowButton
XmNdetailShadowThickness
In Motif 2.0 and later, specifies the thickness of the shadow inside the triangle of
the ArrowButton. Values of 0 (zero), 1, and 2 are supported. In Motif 2.0, the
default is 2. In Motif 2.1 and later, the default depends upon the value of the
XmDisplay resource XmNenableThinThickness: if True, the default is 1, otherwise 2.
XmNmultiClick
A flag that determines whether successive button clicks are processed or ignored.
Possible values:
XmMULTICLICK_DISCARD
XmMULTICLICK_KEEP
/* ignore successive button clicks; */
/* default value in a menu system */
/* count successive button clicks; */
/* default value when not in a menu */
Callback Resources
ArrowButton defines the following callback resources:
Callback
Reason Constant
XmNactivateCallback
XmCR_ACTIVATE
XmNarmCallback
XmCR_ARM
XmNdisarmCallback
XmCR_DISARM
XmNactivateCallback
List of callbacks that are called when BSelect is pressed and released inside the
widget.
XmNarmCallback
List of callbacks that are called when BSelect is pressed while the pointer is
inside the widget.
XmNdisarmCallback
List of callbacks that are called when BSelect is released after it has been pressed
inside the widget.
Callback Structure
Each callback function is passed the following structure:
typedef struct {
int
reason;
/* the reason that the callback was called */
XEvent
*event;
/* event structure that triggered callback */
int
click_count; /* number of clicks in multi-click sequence */
} XmArrowButtonCallbackStruct;
Motif Reference Manual
611
XmArrowButton
Motif and Xt Widget Classes
click_count is meaningful only for XmNactivateCallback. Furthermore, if the
XmN-multiClick resource is set to XmMULTICLICK_KEEP, then XmN-activateCallback is called for each click, and the value of click_count is the number of
clicks that have occurred in the last sequence of multiple clicks. If the XmNmultiClick resource is set to XmMULTICLICK_DISCARD, then click_count always
has a value of 1.
Inherited Resources
ArrowButton inherits the following resources. The resources are listed alphabetically, along with the superclass that defines them. The default value of XmNborderWidth is reset to 0 by Primitive.
Resource
Inherited From Resource
Inherited From
XmNaccelerators
Core
XmNhighlightThickness
XmPrimitive
XmNancestorSensitive
Core
XmNinitialResourcesPersistent Core
XmNbackground
Core
XmNlayoutDirection
XmNbackgroundPixmap
Core
XmNmappedWhenManaged
Core
XmNborderColor
Core
XmNnavigationType
XmPrimitive
XmNborderPixmap
Core
XmNpopupHandlerCallback
XmPrimitive
XmNborderWidth
Core
XmNscreen
Core
XmNbottomShadowColor
XmPrimitive
XmNsensitive
Core
XmNshadowThickness
XmPrimitive
XmNbottomShadowPixmap XmPrimitive
612
XmPrimitive
XmNcolormap
Core
XmNtopShadowColor
XmPrimitive
XmNconvertCallback
XmPrimitive
XmNtopShadowPixmap
XmPrimitive
XmNdepth
Core
XmNtranslations
Core
XmNdestroyCallback
Core
XmNtraversalOn
XmPrimitive
XmNforeground
XmPrimitive
XmNunitType
XmPrimitive
XmNheight
Core
XmNuserData
XmPrimitive
XmNhelpCallback
XmPrimitive
XmNwidth
Core
XmNhighlightColor
XmPrimitive
XmNx
Core
XmNhighlightOnEnter
XmPrimitive
XmNy
Core
XmNhighlightPixmap
XmPrimitive
Motif Reference Manual
Motif and Xt Widget Classes
XmArrowButton
Translations
The translations of ArrowButton include those of Primitive:
Event
Action
BSelect Press
Arm()
BSelect Click
Activate()
Disarm()
BSelect Release
Activate()
Disarm()
Bselect Press 2+
MultiArm()
BSelect Release 2+
MultiActivate()
KSelect
ArmAndActivate()
MCtrl BSelect Press
ButtonTakeFocus()
KHelp
Help()
Action Routines
ArrowButton defines the following action routines:
Activate()
Displays the ArrowButton as unselected, and invokes the list of
callbacks specified by XmNactivateCallback.
Arm()
Displays the ArrowButton as selected, and invokes the list of callbacks specified by XmNarmCallback.
ArmAndActivate()
Displays the ArrowButton as selected, and invokes the list of callbacks specified by XmNarmCallback. After doing this, the action
routine displays the ArrowButton as unselected, and invokes the list
of callbacks specified by XmNactivateCallback and XmNdisarmCallback.
ButtonTakeFocus()
In Motif 2.0 and later, moves the current keyboard focus to the
ArrowButton, without activating the widget.
Disarm()
Displays the ArrowButton as unselected, and invokes the list of
callbacks specified by XmNdisarmCallback.
Help()
Invokes the list of callbacks specified by XmNhelpCallback. If the
ArrowButton doesn’t have any help callbacks, the Help() routine
invokes those associated with the nearest ancestor that has them.
Motif Reference Manual
613
XmArrowButton
Motif and Xt Widget Classes
MultiActivate()
Increments the click_count member of XmArrowButtonCallbackStruct, displays the ArrowButton as unselected, and invokes the list
of callbacks specified by XmNactivateCallback and XmNdisarmCallback. This action routine takes effect only when the XmNmultiClick resource is set to XmMULTICLICK_KEEP.
MultiArm()
Displays the ArrowButton as selected, and invokes the list of callbacks specified by XmNarmCallback. This action routine takes
effect only when the XmNmultiClick resource is set to
XmMULTICLICK_KEEP.
Additional Behavior
ArrowButton has the following additional behavior:
<EnterWindow>
Displays the ArrowButton as selected if the pointer leaves and
re-enters the window while BSelect is pressed.
<LeaveWindow>
Displays the ArrowButton as unselected if the pointer leaves the
window while BSelect is pressed.
See Also
XmCreateObject(1), Core(2), XmPrimitive(2).
614
Motif Reference Manual
Motif and Xt Widget Classes
XmArrowButtonGadget
Name
XmArrowButtonGadget widget class – a directional arrow-shaped button gadget.
Synopsis
Public Header:
<Xm/ArrowBG.h>
Class Name:
XmArrowButtonGadget
Class Hierarchy:
Object → RectObj → XmGadget → XmArrowButtonGadget
Class Pointer:
xmArrowButtonGadgetClass
Instantiation:
widget = XmCreateArrowButtonGadget (parent, name,...)
or
widget = XtCreateWidget (name, xmArrowButtonGadgetClass,...)
Functions/Macros:
XmCreateArrowButtonGadget(), XmIsArrowButtonGadget()
Description
ArrowButtonGadget is the gadget variant of ArrowButton.
ArrowButtonGadget’s resources, callback resources, and callback structure are
the same as those of ArrowButton.
Traits
ArrowButtonGadget holds the XmQTactivatable, XmQTcareParentVisual, and
XmQTaccessColors traits, which are inherited by any derived classes.
Inherited Resources
ArrowButtonGadget inherits the following resources. The resources are listed
alphabetically, along with the superclass that defines them. The default value of
XmNborderWidth is reset to 0 by Gadget.
Resource
Inherited From Resource
XmNancestorSensitive
RectObj
Inherited From
XmNhighlightThickness XmGadget
XmNbackground
XmGadget
XmNlayoutDirection
XmGadget
XmNbackgroundPixmap
XmGadget
XmNnavigationType
XmGadget
XmNbottomShadowColor
XmGadget
XmNsensitive
RectObj
XmNbottomShadowPixmap XmGadget
XmNshadowThickness
XmGadget
XmNborderWidth
XmNtopShadowColor
XmGadget
Motif Reference Manual
RectObj
615
XmArrowButtonGadget
Motif and Xt Widget Classes
Resource
Inherited From Resource
Inherited From
XmNdestroyCallback
Object
XmNtopShadowPixmap XmGadget
XmNforeground
XmGadget
XmNtraversalOn
XmGadget
XmNheight
RectObj
XmNunitType
XmGadget
XmNhelpCallback
XmGadget
XmNuserData
XmGadget
XmNhighlightColor
XmGadget
XmNwidth
RectObj
XmNhighlightOnEnter
XmGadget
XmNx
RectObj
XmNhighlightPixmap
XmGadget
XmNy
RectObj
Behavior
As a gadget subclass, ArrowButtonGadget has no translations associated with it.
However, ArrowButtonGadget behavior corresponds to the action routines of the
ArrowButton widget. See the ArrowButton action routines for more information.
Event
Action
BSelect Press
Arm()
BSelect Click
Activate()
Disarm()
BSelect Release
Activate()
Disarm()
Bselect Press 2+
MultiArm()
BSelect Release 2+
MultiActivate()
KSelect
ArmAndActivate()
MCtrl BSelect Press
ButtonTakeFocus()
KHelp
Help()
ArrowButtonGadget has additional behavior associated with <Enter> and
<Leave>, which display the ArrowButtonGadget as selected if the pointer leaves
and re-enters the gadget while BSelect is pressed or as unselected if the pointer
leaves the gadget while BSelect is pressed.
See Also
XmCreateObject(1), Core(2), Object(2), RectObj(2),
XmArrowButton(2), XmGadget(2), XmPrimitive(2).
616
Motif Reference Manual
Motif and Xt Widget Classes
XmBulletinBoard
Name
XmBulletinBoard widget class – a simple geometry-managing widget.
Synopsis
Public Header:
<Xm/BulletinB.h>
Class Name:
XmBulletinBoard
Class Hierarchy:
Core → Composite → Constraint → XmManager → XmBulletinBoard
Class Pointer:
xmBulletinBoardWidgetClass
Instantiation:
widget = XmCreateBulletinBoard (parent, name,...)
or
widget = XtCreateWidget (name, xmBulletinBoardWidgetClass,...)
Functions/Macros:
XmCreateBulletinBoard(), XmCreateBulletinBoardDialog()
Description
BulletinBoard is a general-purpose manager that allows children to be placed at
arbitrary x, y positions. The simple geometry management of BulletinBoard can
be used to enforce margins and to prevent child widgets from overlapping. BulletinBoard is the base widget for most dialog widgets and defines many resources
that have an effect only when it is an immediate child of a DialogShell.
Traits
BulletinBoard holds the XmQTspecifyRenderTable and XmQTdialogShellSavvy
traits, which are inherited by any derived classes, and uses the XmQTtakesDefault and XmQTspecifyRenderTable traits.
New Resources
BulletinBoard defines the following resources:
Name
Class
Type
Default
Access
XmNallowOverlap
XmCAllowOverlap
Boolean
True
CSG
XmNautoUnmanage
XmCAutoUnmanage
Boolean
True
CSG
XmNbuttonFontList
XmCButtonFontList
XmFontList
dynamic
CSG
XmNbuttonRenderTable XmCButtonRenderTable XmRenderTable dynamic
CSG
XmNcancelButton
Motif Reference Manual
XmCWidget
Widgeta
NULL
SG
617
XmBulletinBoard
Name
Motif and Xt Widget Classes
Class
Type
Default
Access
XmNdefaultButton
XmCWidget
Widgetb
NULL
SG
XmNdefaultPosition
XmCDefaultPosition
unsigned char
True
CSG
XmNdialogStyle
XmCDialogStyle
unsigned char
dynamic
CSG
XmNdialogTitle
XmCDialogTitle
XmString
NULL
CSG
XmNlabelFontList
XmCLabelFontList
XmFontList
dynamic
CSG
XmNlabelRenderTable
XmCLabelRenderTable
XmRenderTable dynamic
CSG
XmNmarginHeight
XmCMarginHeight
Dimension
10
CSG
XmNmarginWidth
XmCMarginWidth
Dimension
10
CSG
XmNnoResize
XmCNoResize
Boolean
False
CSG
XmNresizePolicy
XmCResizePolicy
unsigned char
XmRESIZE_ANY
CSG
XmNshadowType
XmCShadowType
unsigned char
XmSHADOW_OUT CSG
XmNtextFontList
XmCTextFontList
XmFontList
dynamic
XmNtextRenderTable
XmCTextRenderTable
XmRenderTable dynamic
CSG
XmNtextTranslations
XmCTranslations
XtTranslations
C
NULL
CSG
a.Erroneously given as Window in 2nd Edition.
b.Erroneously given as Window in 2nd Edition.
XmNallowOverlap
If True (default), child widgets are allowed to overlap.
XmNautoUnmanage
If True (default), the BulletinBoard is automatically unmanaged after a button is
activated unless the button is an Apply or Help button.
XmNbuttonFontList
Specifies the font list used for the button descendants of the BulletinBoard
widget. In Motif 2.0 and later, the XmFontList is considered obsolete, and is
replaced by the XmRenderTable. The XmNbuttonRenderTable resource is the
preferred method of specifying appearance.
XmNbuttonRenderTable
In Motif 2.0 and later, specifies the render table used for any button descendants
of the BulletinBoard widget. If NULL, this is inherited from the nearest ancestor
that has the XmQTspecifyRenderTable trait, using the
XmBUTTON_RENDER_TABLE value of any ancestor so found.
The button render table resource takes precedence over any specified XmNbuttonFontList.
XmNcancelButton
The widget ID of the Cancel button. The subclasses of BulletinBoard define a
Cancel button and set this resource.
618
Motif Reference Manual
Motif and Xt Widget Classes
XmBulletinBoard
XmNdefaultButton
The widget ID of the default button. Some of the subclasses of BulletinBoard
define a default button and set this resource. To indicate that it is the default, this
button appears different from the others.
XmNdefaultPosition
If True (default) and if the BulletinBoard is the child of a DialogShell, then the
BulletinBoard is centered relative to the DialogShell’s parent.
XmNdialogStyle
The BulletinBoard’s dialog style, whose value can be set only if the BulletinBoard is unmanaged. Possible values:
XmDIALOG_WORK_AREA
/*default when parent is not a DialogShell */
XmDIALOG_MODELESS
/*default when parent is a DialogShell */*
XmDIALOG_FULL_APPLICATION_MODAL
XmDIALOG_APPLICATION_MODAL
XmDIALOG_PRIMARY_APPLICATION_MODAL
XmDIALOG_SYSTEM_MODAL
The value XmDIALOG_APPLICATION_MODAL, although maintained for
backwards compatibility, is deprecated in Motif 1.2 and later. Use
XmDIALOG_PRIMARY_APPLICATION_MODAL instead.
XmNdialogTitle
The dialog title. Setting this resource also sets the resources XmNtitle and XmN-titleEncoding in a parent that is a subclass of WMShell.
XmNlabelFontList
Specifies the font list used for the label descendants of the BulletinBoard widget.
In Motif 2.0 and later, the XmFontList is considered obsolete, and is replaced by
the XmRenderTable. The XmNlabelRenderTable resource is the preferred
method of specifying appearance.
XmNlabelRenderTable
In Motif 2.0 and later, specifies the render table used for any label descendants of
the BulletinBoard widget. If NULL, this is inherited from the nearest ancestor
that has the XmQTspecifyRenderTable trait, using the
XmLABEL_RENDER_TABLE value of any ancestor so found.
XmNmarginHeight
Minimum spacing between a BulletinBoard’s top or bottom edge and any child
widget.
XmNmarginWidth
Minimum spacing between a BulletinBoard’s right or left edge and any child
widget.
Motif Reference Manual
619
XmBulletinBoard
Motif and Xt Widget Classes
XmNnoResize
If False (default), mwm includes resize controls in the window manager frame of
the BulletinBoard’s shell parent.
XmNresizePolicy
How BulletinBoard widgets are resized. Possible values:
XmRESIZE_NONE
XmRESIZE_GROW
XmRESIZE_ANY
*/
/* remain at fixed size
/* expand only
*/
/* shrink or expand, as needed */
XmNshadowType
The style in which shadows are drawn. Possible values:
XmSHADOW_IN
XmSHADOW_OUT
XmSHADOW_ETCHED_IN
XmSHADOW_ETCHED_OUT
/* widget appears inset
*/
/* widget appears outset
*/
/* double line; widget appears inset */
/* double line; widget appears raised */
XmNtextFontList
Specifies the font list used for the text descendants of the BulletinBoard widget.
In Motif 2.0 and later, the XmFontList is considered obsolete, and is replaced by
the XmRenderTable. The XmNtextRenderTable resource is the preferred method
of specifying appearance.
XmNtextRenderTable
In Motif 2.0 and later, specifies the render table used for any text descendants of
the BulletinBoard widget. If NULL, this is inherited from the nearest ancestor
that has the XmQTspecifyRenderTable trait, using the
XmTEXT_RENDER_TABLE value of any ancestor so found.
XmNtextTranslations
For any Text widget (or its subclass) that is a child of a BulletinBoard, this
resource adds translations.
Callback Resources
BulletinBoard defines the following callback resources:
Callback
Reason Constant
XmNfocusCallback
XmCR_FOCUS
XmNmapCallback
XmCR_MAP
XmNunmapCallback
XmCR_UNMAP
XmNfocusCallback
List of callbacks that are called when the widget or one of its descendants
receives the input focus.
620
Motif Reference Manual
Motif and Xt Widget Classes
XmBulletinBoard
XmNmapCallback
List of callbacks that are called when the widget is mapped, if it is a child of a
DialogShell.
XmNunmapCallback
List of callbacks that are called when the widget is unmapped, if it is a child of a
DialogShell.
Callback Structure
Each callback function is passed the following structure:
typedef struct {
int
reason;
XEvent *event;
} XmAnyCallbackStruct;
/* the reason that the callback was called */
/* points to event structure that triggered callback */
Inherited Resources
BulletinBoard inherits the following resources. The resources are listed alphabetically, along with the superclass that defines them. BulletinBoard sets the value of
XmNinitialFocus to the value of XmNdefaultButton. When it is a child of a DialogShell, BulletinBoard resets the default XmNshadowThickness from 0 to 1.
The default value of XmNborderWidth is reset to 0 by Manager.
Resource
Inherited From Resource
Inherited From
XmNaccelerators
Core
XmNinsertPosition
Composite
XmNancestorSensitive
Core
XmNlayoutDirection
XmManager
XmNbackground
Core
XmNmappedWhenManaged Core
XmNbackgroundPixmap
Core
XmNnavigationType
XmManager
Composite
XmNborderColor
Core
XmNnumChildren
XmNborderPixmap
Core
XmNpopupHandlerCallback XmManager
XmNborderWidth
Core
XmNscreen
Core
XmNbottomShadowColor
XmManager
XmNsensitive
Core
XmNbottomShadowPixmap
XmManager
XmNshadowThickness
XmManager
XmNchildren
Composite
XmNstringDirection
XmManager
XmNcolormap
Core
XmNtopShadowColor
XmManager
XmNdepth
Core
XmNtopShadowPixmap
XmManager
XmNdestroyCallback
Core
XmNtranslations
Core
XmNforeground
XmManager
XmNtraversalOn
XmManager
XmNheight
Core
XmNunitType
XmManager
XmNhelpCallback
XmManager
XmNuserData
XmManager
XmNhighlightColor
XmManager
XmNwidth
Core
Motif Reference Manual
621
XmBulletinBoard
Motif and Xt Widget Classes
Resource
Inherited From Resource
Inherited From
XmNhighlightPixmap
XmManager
XmNx
Core
XmNinitialFocus
XmManager
XmNy
Core
XmNinitialResourcesPersistent Core
Translations
The translations for BulletinBoard include those of XmManager.
Additional Behavior
BulletinBoard has the following additional behavior:
MAny KCancel
For a sensitive Cancel button, invokes the XmNactivateCallback
callbacks.
KActivate
For the button that has keyboard focus, invokes the XmNactivateCallback callbacks.
<FocusIn>
Invokes the XmNfocusCallback callbacks. The widget receives
focus either when the user traverses to it (XmNkeyboardFocusPolicy is XmEXPLICIT) or when the pointer enters the window
(XmNkeyboardFocusPolicy is XmPOINTER).
<Map>
Invokes the XmNmapCallback callbacks.
<Unmap>
Invokes the XmNunmapCallback callbacks.
See Also
XmCreateObject(1), Composite(2), Constraint(2), Core(2),
XmBulletinBoardDialog(2), XmDialogShell(2), XmManager(2).
622
Motif Reference Manual
Motif and Xt Widget Classes
XmBulletinBoardDialog
Name
XmBulletinBoardDialog – an unmanaged BulletinBoard as a child of a DialogShell.
Synopsis
Public Header:
<Xm/BulletinB.h>
Instantiation:
widget = XmCreateBulletinBoardDialog(...)
Functions/Macros:
XmCreateBulletinBoardDialog()
Description
An XmBulletinBoardDialog is a compound object created by a call to XmCreateBulletinBoardDialog() that is useful for creating custom dialogs. A BulletinBoardDialog consists of a DialogShell with an unmanaged BulletinBoard
widget as its child. The BulletinBoardDialog does not contain any labels, buttons, or other dialog components; these components are added by the application.
Default Resource Values
A BulletinBoardDialog sets the following default values for BulletinBoard
resources:
Name
Default
XmNdialogStyle
XmDIALOG_MODELESS
Widget Hierarchy
When a BulletinBoardDialog is created with a specified name, the DialogShell is
named name_popup and the BulletinBoard is called name.
See Also
XmCreateObject(1), XmBulletinBoard(2), XmDialogShell(2).
Motif Reference Manual
623
XmCascadeButton
Motif and Xt Widget Classes
Name
XmCascadeButton widget class – a button widget that posts menus.
Synopsis
Public Header:
<Xm/CascadeB.h>
Class Name:
XmCascadeButton
Class Hierarchy:
Core → XmPrimitive → XmLabel → XmCascadeButton
Class Pointer:
xmCascadeButtonWidgetClass
Instantiation:
widget = XmCreateCascadeButton (parent, name,...)
or
widget = XtCreateWidget (name, xmCascadeButtonWidgetClass,...)
Functions/Macros:
XmCascadeButtonHighlight(), XmCreateCascadeButton(), XmIsCascadeButton()
Description
CascadeButtons are used in menu systems to post menus. A CascadeButton
either links a menu bar to a menu pane or connects a menu pane to another menu
pane. The widget can have a menu attached to it as a submenu.
Traits
CascadeButton uses the XmQTmenuSystem and XmQTspecifyRenderTable
traits.
New Resources
CascadeButton defines the following resources:
Name
Class
Type
Default
Access
XmNcascadePixmap
XmCPixmap
Pixmap
dynamic
CSG
XmNmappingDelay
XmCMappingDelay
int
180
CSG
XmNsubMenuId
XmCMenuWidget
Widget
NULL
CSG
XmNcascadePixmap
The pixmap within the CascadeButton that indicates a submenu. By default, this
pixmap is an arrow pointing toward the submenu to be popped up.
624
Motif Reference Manual
Motif and Xt Widget Classes
XmCascadeButton
XmNmappingDelay
The number of milliseconds it should take for the application to display a submenu after its CascadeButton has been selected.
XmNsubMenuId
The widget ID of the pulldown menu pane associated with the CascadeButton.
The menu pane is displayed when the CascadeButton is selected. The pulldown
menu pane and the CascadeButton must have a common parent.
Callback Resources
CascadeButton defines the following callback resources:
Callback
Reason Constant
XmNactivateCallback
XmCR_ACTIVATE
XmNcascadingCallback
XmCR_CASCADING
XmNactivateCallback
List of callbacks that are called when BSelect is pressed and released while the
pointer is inside the widget and there is no submenu to post.
XmNcascadingCallback
List of callbacks that are called before the submenu associated with the CascadeButton is mapped.
Callback Structure
Each callback function is passed the following structure:
typedef struct {
int
reason;
XEvent *event;
} XmAnyCallbackStruct;
/* the reason that the callback was called */
/* event structure that triggered callback */
Inherited Resources
CascadeButton inherits the following resources. The resources are listed alphabetically, along with the superclass that defines them. CascadeButton sets the
default values of XmNmarginBottom, XmNmarginRight, XmNmarginTop,
XmNmarginWidth, and XmN-traversalOn dynamically. In Motif 2.0 and earlier,
the default values of XmNhighlightThickness and XmNshadowThickness are
reset to 2. In Motif 2.1, the default values depend upon the XmDisplay XmNenableThinThickness resource: if True the default is 1, otherwise 2. The default
value of XmNborderWidth is reset to 0 by Primitive.
Motif Reference Manual
625
XmCascadeButton
626
Motif and Xt Widget Classes
Resource
Inherited From Resource
Inherited From
XmNaccelerator
XmLabel
XmNlabelType
XmLabel
XmNaccelerators
Core
XmNlayoutDirection
XmPrimitive
XmNacceleratorText
XmLabel
XmNmappedWhenManaged Core
XmNalignment
XmLabel
XmNmarginBottom
XmLabel
XmNancestorSensitive
Core
XmNmarginHeight
XmLabel
XmNbackground
Core
XmNmarginLeft
XmLabel
XmNbackgroundPixmap
Core
XmNmarginRight
XmLabel
XmNborderColor
Core
XmNmarginTop
XmLabel
XmNborderPixmap
Core
XmNmarginWidth
XmLabel
XmNborderWidth
Core
XmNmnemonicCharSet
XmLabel
XmNbottomShadowColor
XmPrimitive
XmNmnemonic
XmLabel
XmNbottomShadowPixmap
XmPrimitive
XmNnavigationType
XmPrimitive
XmNcolormap
Core
XmNpopupHandlerCallback XmPrimitive
XmNconvertCallback
XmPrimitive
XmNrecomputeSize
XmLabel
XmNdepth
Core
XmNrenderTable
XmLabel
XmNdestroyCallback
Core
XmNscreen
Core
XmNfontList
XmLabel
XmNsensitive
Core
XmNforeground
XmPrimitive
XmNshadowThickness
XmPrimitive
XmNheight
Core
XmNstringDirection
XmLabel
XmNhelpCallback
XmPrimitive
XmNtopShadowColor
XmPrimitive
XmNhighlightColor
XmPrimitive
XmNtopShadowPixmap
XmPrimitive
XmNhighlightOnEnter
XmPrimitive
XmNtranslations
Core
XmNhighlightPixmap
XmPrimitive
XmNtraversalOn
XmPrimitive
XmNhighlightThickness
XmPrimitive
XmNunitType
XmPrimitive
XmNinitialResourcesPersistent Core
XmNuserData
XmPrimitive
XmNlabelInsensitivePixmap
XmLabel
XmNwidth
Core
XmNlabelPixmap
XmLabel
XmNx
Core
XmNlabelString
XmLabel
XmNy
Core
Motif Reference Manual
Motif and Xt Widget Classes
XmCascadeButton
Translations
The translations of CascadeButton include the menu traversal translations of
Label.
Event
Action
BSelect Press
MenuBarSelect() (in a menu bar)
StartDrag() (in a popup or pulldown menu)
BSelect Release
DoSelect()
MCtrl BSelect Press
MenuButtonTakeFocus()
MCtrl BSelect Release
MenuButtonTakeFocusUp()
KActivate
KeySelect()
KSelect
KeySelect()
KHelp
Help()
MAny KCancel
CleanupMenuBar()
Action Routines
CascadeButton defines the following action routines:
CleanupMenuBar()
Unposts any menus and restores the keyboard focus to the group of
widgets (tab group) that had the focus before the CascadeButton
was armed.
DoSelect()
Posts the CascadeButton’s submenu and allows keyboard traversal.
If there is no submenu attached to the CascadeButton, this action
routine activates the CascadeButton and unposts all the menus in
the cascade.
Help()
Similar to CleanupMenuBar() in that the Help() routine unposts any
menus and restores keyboard focus. This routine also invokes the
list of callbacks specified by XmNhelpCallback. If the CascadeButton doesn’t have any help callbacks, the Help() routine invokes
those associated with the nearest ancestor that has them.
KeySelect()
Posts the CascadeButton’s submenu, provided that keyboard traversal is allowed. If there is no submenu attached to the CascadeButton, this action routine activates the CascadeButton and unposts all
the menus in the cascade.
Motif Reference Manual
627
XmCascadeButton
Motif and Xt Widget Classes
MenuBarSelect()
Unposts any previously posted menus, posts the submenu associated with the CascadeButton, and enables mouse traversal.
MenuButtonTakeFocus()
In Motif 2.0 and later, moves the current keyboard focus to the CascadeButton, without activating the widget.
StartDrag()
Posts the submenu associated with the CascadeButton and enables
mouse traversal.
Additional Behavior
CascadeButton has the following additional behavior:
<EnterWindow>
<LeaveWindow>
Arms the CascadeButton and posts its submenu.
Disarms the CascadeButton and unposts its submenu.
See Also
XmCascadeButtonHighlight(1), XmCreateObject(2), Core(2),
XmLabel(2), XmPrimitive(2), XmRowColumn(2).
628
Motif Reference Manual
Motif and Xt Widget Classes
XmCascadeButtonGadget
Name
XmCascadeButtonGadget widget class – a button gadget that posts menus.
Synopsis
Public Header:
<Xm/CascadeBG.h>
Class Name:
XmCascadeButtonGadget
Class Hierarchy:
Object → RectObj → XmGadget → XmLabelGadget → XmCascadeButtonGadget
Class Pointer:
xmCascadeButtonGadgetClass
Instantiation:
widget = XmCreateCascadeButtonGadget (parent, name,...)
or
widget = XtCreateWidget (name, xmCascadeButtonGadgetClass,...)1
Functions/Macros:
XmCascadeButtonGadgetHighlight(), XmCreateCascadeButtonGadget(),
XmIsCascadeButtonGadget(), XmOptionButtonGadget()
Description
CascadeButtonGadget is the gadget variant of CascadeButton.
CascadeButtonGadget’s new resources, callback resources, and callback structure are the same as those for CascadeButton.
Traits
CascadeButtonGadget uses the XmQTmenuSystem and XmQTspecifyRenderTable traits.
Inherited Resources
CascadeButtonGadget inherits the following resources. The resources are listed
alphabetically, along with the superclass that defines them. CascadeButtonGadget sets the default values of XmNmarginBottom, XmNmarginRight, XmNmarginTop, and XmNmarginWidth dynamically. It also sets the default value of
XmNhighlightThickness to 0. The default value of XmNborderWidth is reset to 0
by Gadget.
1.Erroneously given as xmCascadeButtonWidgetClass in 2nd Edition.
Motif Reference Manual
629
XmCascadeButtonGadget
Motif and Xt Widget Classes
Resource
Inherited From Resource
Inherited From
XmNaccelerator
XmLabelGadget
XmNmarginBottom
XmLabelGadget
XmNacceleratorText
XmLabelGadget
XmNmarginHeight
XmLabelGadget
XmNalignment
XmLabelGadget
XmNmarginLeft
XmLabelGadget
XmNancestorSensitive
RectObj
XmNmarginRight
XmLabelGadget
XmNbackground
XmGadget
XmNmarginTop
XmLabelGadget
XmNbackgroundPixmap
XmGadget
XmNmarginWidth
XmLabelGadget
XmNbottomShadowColor
XmGadget
XmNmnemonic
XmLabelGadget
XmNbottomShadowPixmap
XmGadget
XmNmnemonicCharSet XmLabelGadget
XmNborderWidth
RectObj
XmNnavigationType
XmGadget
XmNdestroyCallback
Object
XmNrecomputeSize
XmLabelGadget
XmNfontList
XmLabelGadget
XmNrenderTable
XmLabelGadget
XmNforeground
XmGadget
XmNsensitive
RectObj
XmNheight
RectObj
XmNshadowThickness
XmGadget
XmNhelpCallback
XmGadget
XmNstringDirection
XmLabelGadget
XmNhighlightColor
XmGadget
XmNtopShadowColor
XmGadget
XmNhighlightOnEnter
XmGadget
XmNtopShadowPixmap XmGadget
XmNhighlightPixmap
XmGadget
XmNtraversalOn
XmGadget
XmNhighlightThickness
XmGadget
XmNunitType
XmGadget
XmNlabelInsensitivePixmap XmLabelGadget
XmNuserData
XmGadget
XmNlabelPixmap
XmLabelGadget
XmNwidth
RectObj
XmNlabelType
XmLabelGadget
XmNx
RectObj
XmNlayoutDirection
XmGadget
XmNy
RectObj
Behavior
As a gadget subclass, CascadeButtonGadget has no translations associated with
it. However, CascadeButtonGadget behavior corresponds to the action routines of
the CascadeButton widget. See the CascadeButton action routines for more information.
630
Event
Action
BSelect Press
MenuBarSelect() (in a menu bar)
StartDrag() (in a popup or pulldown menu)
BSelect Release
DoSelect()
MCtrl BSelect Press
MenuButtonTakeFocus()
Motif Reference Manual
Motif and Xt Widget Classes
Event
XmCascadeButtonGadget
Action
MCtrl BSelect Release
MenuButtonTakeFocusUp()
KActivate
KeySelect()
KSelect
KeySelect()
KHelp
Help()
MAny KCancel
CleanupMenuBar()
In a menu bar that is armed, CascadeButtonGadget has additional behavior associated with <Enter>, which arms the CascadeButtonGadget and posts its submenu, and with <Leave>, which disarms the CascadeButtonGadget and unposts
its submenu.
See Also
XmCascadeButtonHighlight(1), XmCreateObject(1),
XmOptionButtonGadget(1), Object(2), RectObj(2),
XmCascadeButton(2), XmGadget(2), XmLabelGadget(2),
XmRowColumn(2).
Motif Reference Manual
631
XmCheckBox
Motif and Xt Widget Classes
Name
XmCheckBox – a RowColumn that contains ToggleButtons.
Synopsis
Public Header:
<Xm/RowColumn.h>
Class Name:
XmRowColumn
Class Hierarchy:
Core → Composite → Constraint → XmManager → XmRowColumn
Class Pointer:
xmRowColumnWidgetClass
Instantiation:
widget = XmCreateSimpleCheckBox (parent, name,...)
Functions/Macros:
XmCreateRowColumn(), XmCreateSimpleCheckBox(), XmIsRowColumn(),
XmVaCreateSimpleCheckBox()
Description
An XmCheckBox is an instance of a RowColumn widget that contains ToggleButton or ToggleButtonGadget children, any number of which may be selected at
a given time. A CheckBox is a RowColumn widget with its XmNrowColumnType resource set to XmWORK_AREA and XmNradioAlwaysOne set to False.
A CheckBox can be created by making a RowColumn with these resource values.
When it is created in this way, a CheckBox does not automatically contain ToggleButton children; they are added by the application.
A CheckBox can also be created by a call to XmCreateSimpleCheckBox() or
XmVaCreateSimpleCheckBox(). These routines automatically create the CheckBox with ToggleButtonGadgets as children. The routines use the RowColumn
resources associated with the creation of simple menus. For a CheckBox, the
only type allowed in the XmNbuttonType resource is XmCHECKBUTTON. The
name of each ToggleButtonGadget is button_n, where n is the number of the button, ranging from 0 to 1 less than the number of buttons in the CheckBox.
632
Motif Reference Manual
Motif and Xt Widget Classes
XmCheckBox
Default Resource Values
A CheckBox sets the following default values for its resources:
Name
Default
XmNnavigationType
XmTAB_GROUP
XmNradioBehavior
False
XmNrowColumnType
XmWORK_AREA
XmNtraversalOn
True
See Also
XmCreateObject(2), XmVaCreateSimpleCheckBox(2),
XmRowColumn(2), XmToggleButton(2), XmToggleButtonGadget(2).
Motif Reference Manual
633
XmComboBox
Motif and Xt Widget Classes
Name
XmComboBox widget class – a composite widget which combines a text widget
with a list of choices.
Synopsis
Public Header:
<Xm/ComboBox.h>
Class Name:
XmComboBox
Class Hierarchy:
Core → Composite → Constraint → XmManager → XmComboBox
Class Pointer:
xmComboBoxWidgetClass
Instantiation:
widget = XmCreateComboBox (parent, name,...)
or
widget = XmCreateDropDownComboBox (parent, name,...)
or
widget = XmCreateDropDownList (parent, name,...)
or
widget = XtCreateWidget (name, xmComboBoxWidgetClass,...)
Functions/Macros:
XmComboBoxAddItem(), XmComboBoxDeletePos(), XmComboBoxSelectItem(),
XmComboBoxSetItem(), XmComboBoxUpdate(), XmCreateComboBox(),
XmCreateDropDownComboBox(), XmCreateDropDownList(), XmIsComboBox()
Availability
Motif 2.0 and later.
Description
ComboBox is a composite widget that combines both text entry and scrolled list
selection. The ComboBox can be configured in various ways, depending on
whether the text field is to be editable, and whether the scrolled list is to be permanently visible. The text field contains the currently selected item; an item
selected from the list is automatically placed into the text field. Whether entering
data into the text field, or selecting from the list, the user can select only one item
at any given time. Data typed directly into the text field does not, however, automatically select any matching item in the list.
634
Motif Reference Manual
Motif and Xt Widget Classes
XmComboBox
By default, both the text field and the list are fully visible, and the list is placed
underneath the text widget. The user can either enter characters directly into the
text field, or select an item from the list. Alternatively, the ComboBox widget can
be configured such that the list is hidden until required. In this case, the ComboBox widget draws an arrow button adjacent to the text field. Clicking on the
arrow displays the hidden list underneath the text field. Selecting an item from
the displayed popup list automatically pops down the list.
The XmNcomboBoxType resource configures the type of the ComboBox. You
may specify one of the following types: combo box (XmCOMBO_BOX),
drop-down combo box (XmDROP_DOWN_COMBO_BOX), or drop-down list
(XmDROP_DOWN_LIST). The combo box type has a permanently visible list,
and the text field is editable. A drop-down combo box has an editable text field,
the list is hidden, and the arrow button is drawn. A drop-down list is identical to a
drop-down combo box except that the text field is not editable: the user must
select from the list to change the selection.
If the ComboBox widget has a non-editable text field, any characters typed do
not appear directly in the text field. Instead, any characters entered may be compared against items in the list, depending on the value of the XmNmatchBehavior
resource. When enabled, and the list has the input focus, characters typed are
compared against the first character of each item in the list. If a match is found,
the matched list item is automatically selected. Subsequently typing the same
character progresses cyclically through the list to find any further matching item.
The position of the drawn arrow button relative to the text field depends upon the
XmNlayoutDirection resource of the Shell ancestor of the ComboBox widget. If
XmNlayoutDirection is XmLEFT_TO_RIGHT, the arrow button is drawn to the
right of the text field. Otherwise, a value XmRIGHT_TO_LEFT draws the arrow
button to the left.
Traits
ComboBox uses the XmQTaccessTextual and XmQTspecifyRenderTable traits.
New Resources
ComboBox defines the following resources:
Name
Class
Type
Default
Access
XmNarrowSize
XmCArrowSize
Dimension
dynamic
CSG
XmNarrowSpacing
XmCArrowSpacing
Dimension
dynamic
CSG
XmNcolumns
XmCColumns
short
dynamic
CSG
XmNcomboBoxType
XmCComboBoxType
unsigned char
XmCOMBO_BOX CG
XmNfontList
XmCFontList
XmFontList
NULL
Motif Reference Manual
CSG
635
XmComboBox
Motif and Xt Widget Classes
Name
Class
Type
Default
Access
XmNhighlightThickness XmCHighlightThickness Dimension
dynamic
CSG
XmNitemCount
XmCItemCount
int
dynamic
CSG
XmNitems
XmCItems
XmStringTable
dynamic
CSG
XmNlist
XmCList
Widget
dynamic
G
XmNmarginHeight
XmCMarginHeight
Dimension
2
CSG
XmNmarginWidth
XmCMarginWidth
Dimension
2
CSG
XmNmatchBehavior
XmCMatchBehavior
unsigned char
dynamic
CSG
XmNpositionMode
XmCPositionMode
XtEnum
XmZERO_BASED CG
XmNrenderTable
XmCRenderTable
XmRenderTable dynamic
CSG
XmNselectedItem
XmCSelectedItem
XmString
NULL
CSG
XmNselectedPosition
XmCSelectedPosition
int
0
CSG
XmNtextField
XmCTextField
Widget
dynamic
G
XmNvisibleItemCount
XmCVisibleItemCount
int
10
CSG
XmNarrowSize
The size of the drawn arrow button used to display the hidden list. The default
size depends upon the size of the text field, and the size of the ComboBox
widget. Attempting to change the arrow size may result in a geometry request to
the parent of the ComboBox widget. If this request is refused, the arrow size is
set to the maximum size that fits into the space allowed by the parent of the ComboBox widget.
XmNarrowSpacing
The horizontal spacing, in pixels, between the drawn arrow button and the text
field. The default value is calculated from the value of the XmNmarginWidth
resource.
XmNcolumns
Specifies the number of columns in the text field. The default value is that of
XmTextField.
XmNcomboBoxType
Specifies the type of the ComboBox. Possible values:
XmCOMBO_BOX
XmDROP_DOWN_COMBO_BOX
XmDROP_DOWN_LIST
/* visible list; editable text field */
/* hidden list; editable text field */
/* hidden list; non-editable text field */
XmNfontList
The font list used for the items in the list and text field. In Motif 2.0 and later, the
XmFontList is obsolete as a data type, and the resource is maintained for backwards compatibility through an implementation as an XmRenderTable. The
636
Motif Reference Manual
Motif and Xt Widget Classes
XmComboBox
XmNrenderTable resource is the preferred method of specifying appearance. If
both a render table and font list are specified, the render table takes precedence.
The default font list is taken from the default render table.
XmNhighlightThickness
The thickness of the highlighting rectangle. In Motif 2.0, the default is 2. In
Motif 2.1 and later, the default depends upon the value of the XmDisplay
resource XmNenableThinThickness: if True, the default is 1, otherwise 2.
XmNitemCount
The total number of items. If unspecified, the value is taken from the internal list.
The ComboBox widget updates this resource every time a list item is added or
removed through the ComboBox convenience functions.
XmNitems
A pointer to an array of compound strings, representing the items to display in
the list. A call to XtGetValues() returns the actual list items, not a copy. Applications should not directly free any items fetched in this manner. If the resource is
unspecified, the value is taken from the internal list. The ComboBox widget
updates this resource every time a list item is added or removed through the
ComboBox convenience functions.
XmNlist
The list widget created by the ComboBox. Applications may not change the
value of this resource, but may fetch the value to perform required operations on
the internal list.
XmNmarginHeight
The minimum spacing between the ComboBox top or bottom edge and the child
list and text field widgets.
XmNmarginWidth
The minimum spacing between the ComboBox left or right edge and the child
list and text field widgets.
XmNmatchBehavior
Determines whether matching behavior is enabled, where characters typed are
compared against items in the list. Possible values:
XmNONE
XmQUICK_NAVIGATE
/* No match behavior */
/* Match behavior enabled */
The value XmQUICK_NAVIGATE may only be specified if the XmNcomboBoxType resource has value XmDROP_DOWN_LIST.
XmQUICK_NAVIGATE is the default when XmNcomboBoxType is
XmDROP_DOWN_LIST. Otherwise, XmNONE is the default.
Motif Reference Manual
637
XmComboBox
Motif and Xt Widget Classes
XmNpositionMode
Specifies the way in which the position of the selected item is reported in callbacks, and controls the initial index value of the XmNselectedPosition resource.
Possible values:
XmZERO_BASED
XmONE_BASED
/* first item in list is position zero */
/* first item in list is position one */
A value of XmZERO_BASED configures callback data on the XmNselectionCallback list such that the item_position element of the XmComboBoxCallbackStruct is indexed from zero: selecting the first list item has item_position set to
zero, selecting the second item has item_position as one, and so forth. Similarly,
fetching the XmNselectedPosition resource when the first item in the list is
selected will return the value zero.
A value of XmONE_BASED sets the item_position element such that selecting
the first item in the list is reported at position one, the second item is reported at
position two, and so on. By analogy, fetching the XmNselectedPosition resource
when the first item in the list is selected will return the value one.
In all cases, changes to the text field are reported with item_position set to zero.
A XmNpositionMode of XmONE_BASED therefore makes it easier to distinguish between text field and list selection, since item_position set to zero is not
ambiguous.
The ComboBox convenience functions for adding, deleting, or selecting items in
the list are unaffected by the value of this resource: these functions always
assume that the first item is at position one.
This resource is provided for CDE compatibility. In particular, setting the value
to XmZERO_BASED makes the ComboBox selection behavior consistent with
that of the DtComboBox widget.
XmNrenderTable
Specifies the render table for the ComboBox, and is used in both the text field and
list children. If NULL, this is inherited from the nearest ancestor that has the
XmQTspecifyRenderTable trait. The BulletinBoard, VendorShell, and MenuShell widgets and derived classes set this trait.
The render table resource takes precedence over any specified XmNfontList.
XmNselectedItem
A compound string representing the currently selected item contained within the
ComboBox text field.
638
Motif Reference Manual
Motif and Xt Widget Classes
XmComboBox
XmNselectedPosition
Identifies the index of the XmNselectedItem in the list. The interpretation of the
index depends upon the value of the XmNpositionMode resource. If XmNpositionMode is XmZERO_BASED, a XmNselectedPosition value of 0 (zero) indicates that the first list item is selected, a value of 1 indicates the second item is
selected, and so forth. If XmNpositionMode is XmONE_BASED, the value 1
indicates that the first list item is selected, the value 2 indicates the second list
item, and so on, with value 0 (zero) indicating that no list item is selected.
XmNtextField
The text field widget created by the ComboBox. Applications may not change the
value of this resource, but may fetch the value to perform required operations on
the internal text field.
XmNvisibleItemCount
The number of items to display in the work area of the list. If specified, this
resource overrides the XmNvisibleItemCount resource of the internal list widget.
The resource may affect the height of the list widget, and hence the ComboBox
itself, depending upon whether the list is permanently visible. If the XmNvisibleItemCount value is less than the number of items in the list, the list is automatically configured with a vertical ScrollBar.
Callback Resources
ComboBox defines the following callback resources:
Callback
Reason Constant
XmNselectionCallback
XmCR_SELECT
XmNselectionCallback
List of callbacks that are called when a selection occurs in the ComboBox
widget.
Callback Structure
Each callback function is passed the following structure:
typedef struct {
int
reason;
XEvent *event;
XmString item_or_text;
int
item_position;
} XmComboBoxCallbackStruct;
Motif Reference Manual
/* the reason that the callback was called
*/
/* points to event structure that triggered callback */
/* the selected item
*/
/* the index of the item in the list
*/
639
XmComboBox
Motif and Xt Widget Classes
The item_or_text element is a compound string representing the ComboBox
selected item. It points to allocated memory that is reclaimed after the callbacks
on the XmNselectionCallback list have returned. If the item is to be cached, the
application should copy the item using XmStringCopy().
The item_position element specifies the index of the selected item within the
XmNitems array of the list. The interpretation of the value will depend upon the
XmNpositionMode resource of the ComboBox widget. With XmNpositionMode
set to XmONE_BASED, an item_position of 1 refers to the first item in the list,
and an item_position of zero indicates that the selected item has been entered
directly into the text field (no list selection). With a XmNpositionMode of
XmZERO_BASED, an item_position of zero could either mean that the first item
in the list is selected, or that the selection is from direct text entry, and an
item_position of 1 refers to the second list item.
Default Resource Values
A ComboBox sets the following default values for the scrolled list resources:
Name
Default
XmNborderWidth
0
XmNhighlightThickness
dynamic
XmNlistSizePolicy
XmVARIABLE
XmNnavigationType
XmNONE
XmNrenderTable
dynamic
XmNselectionPolicy
XmBROWSE_SELECT
XmNspacing
0
XmNtraversalOn
dynamic
XmNvisualPolicy
XmVARIABLE
If the ComboBox is a drop down list, XmNcursorPositionVisible and XmNeditable are set to False, and the XmNshadowThickness is set to zero. Otherwise,
XmNcursorPositionVisible and XmNeditable are set True, and XmNeditMode is
set to XmSINGLE_LINE_EDIT.
Inherited Resources
ComboBox inherits the resources shown below. The resources are listed alphabetically, along with the superclass that defines them. ComboBox sets the default
values of XmNmarginWidth, and XmNmarginHeight to 2, and XmNnavigationType to XmSTICKY_TAB_GROUP. The default value of XmNborderWidth is
reset to 0 (zero) by Manager. The default values for XmNhighlightThickness and
XmNshadowThickness depend upon the XmDisplay XmNenableThinThickness
resource: if True, the default is 1, otherwise 2.
640
Motif Reference Manual
Motif and Xt Widget Classes
XmComboBox
Resource
Inherited From Resource
Inherited From
XmNaccelerators
Core
XmNinsertPosition
Composite
XmNancestorSensitive
Core
XmNlayoutDirection
XmManager
XmNbackground
Core
XmNmappedWhenManaged Core
XmNbackgroundPixmap
Core
XmNnavigationType
XmManager
Composite
XmNborderColor
Core
XmNnumChildren
XmNborderPixmap
Core
XmNpopupHandlerCallback XmManager
XmNborderWidth
Core
XmNscreen
Core
XmNbottomShadowColor
XmManager
XmNsensitive
Core
XmNbottomShadowPixmap
XmManager
XmNshadowThickness
XmManager
XmNchildren
Composite
XmNstringDirection
XmManager
XmNcolormap
Core
XmNtopShadowColor
XmManager
XmNdepth
Core
XmNtopShadowPixmap
XmManager
XmNdestroyCallback
Core
XmNtranslations
Core
XmNforeground
XmManager
XmNtraversalOn
XmManager
XmNheight
Core
XmNunitType
XmManager
XmNhelpCallback
XmManager
XmNuserData
XmManager
XmNhighlightColor
XmManager
XmNwidth
Core
XmNhighlightPixmap
XmManager
XmNx
Core
XmNinitialFocus
XmManager
XmNy
Core
XmNinitialResourcesPersistent Core
Widget Hierarchy
The ComboBox creates the text field with the name Text, and the scrolled list is
named List. If the ComboBox is of a drop down type, an XmGrabShell named
GrabShell is created as parent to the scrolled list.
Translations
The translations for ComboBox include those of XmManager.
Event
Action
BSelect Press
CBArmAndDropDownList()
BSelect Release
CBDisarm()
Motif Reference Manual
641
XmComboBox
Motif and Xt Widget Classes
ComboBox places the following translations upon the list:
Event
Action
KDown
CBDropDownList()
KUp
CBDropDownList()
KCancel
CBCancel()
KActivate
CBActivate()
MShift KBeginData
CBListAction(ListBeginData)
MShift KEndData
CBListAction(ListEndData)
KPageUp
CBListAction(ListPrevPage)
KPageDown
CBListAction(ListNextPage)
ComboBox places the following translations upon the text field:
Event
Action
<FocusOut>
CBTextFocusOut()
Action Routines
ComboBox defines the following action routines:
CBArmAndDropDownList()
If the mouse is over the drawn arrow button, draws the arrow button
as though selected, and posts the drop-down list.
CBDisarm()
Draws the arrow button in unselected state.
CBDropDownList()
Posts the drop-down list
CBFocusIn()
Draws focus highlighting around the ComboBox widget.
CBFocusOut()
Erases focus highlighting around the ComboBox widget. If the text
field has changed, invokes the list of callbacks specified by XmNselectionCallback.
CBCancel()
Pops down the drop-down list, and draws the arrow button in unselected state.
CBActivate()
Fetches the value from the text field. If the XmNcomboBoxType is
XmCOMBO_BOX, invokes the list of callbacks specified by XmNdefaultActionCallback for the internal list, passing the text field
642
Motif Reference Manual
Motif and Xt Widget Classes
XmComboBox
value as the selected item within the callback data. Regardless of
XmNcomboBoxType, if the value matches an item within the list,
the list item is selected, otherwise all list items are deselected.
Lastly, the list of callbacks specified by XmNselectionCallback is
invoked.
CBListAction(type)
A generic action to perform operations on the internal list. The
action type may be one of Up, Down, ListPrevPage, ListNextPage,
ListBeginData, or ListEndData. The types Up and Down simply
select the relevant item in the list in the required direction relative to
the currently selected item. The remaining types directly invoke the
ListPrevPage, ListNextPage, ListBeginData, or ListEndData
actions of the list. The types Up and Down differ from the corresponding List actions in that the ComboBox actions will wrap
around the items in the internal list.
CBTextFocusOut()
Turns off text field cursor blinking.
See Also
XmComboBoxAddItem(1), XmComboBoxDeletePos(1),
XmComboBoxSelectItem(1), XmComboBoxSetItem(1),
XmComboBoxUpdate(1), XmCreateObject(1), Composite(2),
Constraint(2), Core(2), XmManager(2).
Motif Reference Manual
643
XmCommand
Motif and Xt Widget Classes
Name
XmCommand widget class – a composite widget for command entry.
Synopsis
Public Header:
<Xm/Command.h>
Class Name:
XmCommand
Class Hierarchy:
Core → Composite → Constraint → XmManager → XmBulletinBoard →
XmSelectionBox → XmCommand
Class Pointer:
xmCommandWidgetClass
Instantiation:
widget = XmCreateCommand (parent, name,...)
or
widget = XtCreateWidget (name, xmCommandWidgetClass,...)
Functions/Macros:
XmCommandAppendValue(), XmCommandError(), XmCommandGetChild(),
XmCommandSetValue(), XmCreateCommand(), XmIsCommand()
Description
Command is a composite widget that handles command entry by providing a
prompt, a command input field, and a history list region. Many of the Command
widget’s new resources are in fact renamed resources from SelectionBox.
New Resources
Command defines the following resources:
644
Name
Class
Type
Default Access
XmNcommand
XmCTextString
XmString
NULL
CSG
XmNhistoryItems
XmCItems
XmStringTable NULL
CSG
XmNhistoryItemCount
XmCItemCount
int
CSG
XmNhistoryMaxItems
XmCMaxItems
int
0
100
CSG
XmNhistoryVisibleItemCount XmCVisibleItemCount int
dynamic
CSG
XmNpromptString
dynamic
CSG
XmCPromptString
XmString
Motif Reference Manual
Motif and Xt Widget Classes
XmCommand
XmNcommand
The text currently displayed on the command line. Synonymous with the XmNtextString resource in SelectionBox. XmNcommand can be changed using the
routines XmCommandSetValue() and XmCommandAppendValue().
XmNhistoryItems
The items in the history list. Synonymous with the XmNlistItems resource in
SelectionBox. A call to XtGetValues() returns the actual list items (not a
copy), so don’t have your application free these items.
XmNhistoryItemCount
The number of strings in XmNhistoryItems. Synonymous with the XmNlistItemCount resource in SelectionBox.
XmNhistoryMaxItems
The history list’s maximum number of items. When this number is reached, the
first history item is removed before the new command is added to the list.
XmNhistoryVisibleItemCount
The number of history list commands that will display at one time. Synonymous
with the XmNvisibleItemCount resource in SelectionBox.
XmNpromptString
The command-line prompt. Synonymous with the XmNselectionLabelString
resource in SelectionBox.
Callback Resources
Command defines the following callback resources:
Callback
Reason Constant
XmNcommandEnteredCallback
XmCR_COMMAND_ENTERED
XmNcommandChangedCallback
XmCR_COMMAND_CHANGED
XmNcommandChangedCallback
List of callbacks that are called when the value of the command changes.
XmNcommandEnteredCallback
List of callbacks that are called when a command is entered in the widget.
Callback Structure
Each callback function is passed the following structure:
typedef struct {
int
reason;
XEvent
*event;
XmString
value;
int
length;
} XmCommandCallbackStruct;
Motif Reference Manual
/* the reason that the callback was called
*/
/* points to event structure that triggered callback */
/* the string contained in the command area
*/
/* the size of this string
*/
645
XmCommand
Motif and Xt Widget Classes
Inherited Resources
Command inherits the resources shown below. The resources are listed alphabetically, along with the superclass that defines them. Command sets the default values of XmNautoUnmanage and XmNdefaultPosition to False, XmNdialogType
to XmDIALOG_COMMAND, and XmNlistLabelString to NULL. In versions of
Motif prior to 2.1.10, XmNresizePolicy is reset to XmRESIZE_NONE.
In Motif 2.1.10 and later, it is reset to XmRESIZE_ANY: this undocumented
change is a bug which persists in Motif 2.1.20. The default value of XmNborderWidth is reset to 0 by Manager. BulletinBoard sets the value of XmNinitialFocus
to XmNdefaultButton and resets the default XmNshadowThickness from 0 to 1 if
the Command widget is a child of a DialogShell.
646
Resource
Inherited From Resource
Inherited From
XmNaccelerators
Core
XmSelectionBox
XmNlistItemCount
XmNallowOverlap
XmBulletinBoard
XmNlistItems
XmSelectionBox
XmNancestorSensitive
Core
XmNlistLabelString
XmSelectionBox
XmNapplyCallback
XmSelectionBox
XmNlistVisibleItemCount
XmSelectionBox
XmNapplyLabelString
XmSelectionBox
XmNmapCallback
XmBulletinBoard
XmNautoUnmanage
XmBulletinBoard
XmNmappedWhenManaged Core
XmNbackground
Core
XmNmarginHeight
XmBulletinBoard
XmNbackgroundPixmap
Core
XmNmarginWidth
XmBulletinBoard
XmNborderColor
Core
XmNminimizeButtons
XmSelectionBox
XmNborderPixmap
Core
XmNmustMatch
XmSelectionBox
XmNborderWidth
Core
XmNnavigationType
XmManager
XmNbottomShadowColor
XmManager
XmNnoMatchCallback
XmSelectionBox
XmNbottomShadowPixmap
XmManager
XmNnoResize
XmBulletinBoard
XmNbuttonFontList
XmBulletinBoard
XmNnumChildren
Composite
XmNbuttonRenderTable
XmBulletinBoard
XmNokCallback
XmSelectionBox
XmSelectionBox
XmNcancelButton
XmBulletinBoard
XmNokLabelString
XmNcancelCallback
XmSelectionBox
XmNpopupHandlerCallback XmManager
XmNcancelLabelString
XmSelectionBox
XmNresizePolicy
XmBulletinBoard
XmNchildren
Composite
XmNscreen
Core
XmNchildPlacement
XmSelectionBox
XmNselectionLabelString
XmSelectionBox
XmNcolormap
Core
XmNsensitive
Core
XmNdefaultButton
XmBulletinBoard
XmNshadowThickness
XmManager
XmNdefaultPosition
XmBulletinBoard
XmNshadowType
XmBulletinBoard
XmNdepth
Core
XmNstringDirection
XmManager
Motif Reference Manual
Motif and Xt Widget Classes
XmCommand
Resource
Inherited From Resource
Inherited From
XmNdestroyCallback
Core
XmNtextAccelerators
XmSelectionBox
XmNdialogStyle
XmBulletinBoard
XmNtextColumns
XmSelectionBox
XmNdialogTitle
XmBulletinBoard
XmNtextFontList
XmBulletinBoard
XmNdialogType
XmSelectionBox
XmNtextRenderTable
XmBulletinBoard
XmNfocusCallback
XmBulletinBoard
XmNtextString
XmSelectionBox
XmNforeground
XmManager
XmNtextTranslations
XmBulletinBoard
XmNheight
Core
XmNtopShadowColor
XmManager
XmNhelpCallback
XmManager
XmNtopShadowPixmap
XmManager
XmNhelpLabelString
XmSelectionBox
XmNtranslations
Core
XmNhighlightColor
XmManager
XmNtraversalOn
XmManager
XmNhighlightPixmap
XmManager
XmNunitType
XmManager
XmNinitialFocus
XmManager
XmNunmapCallback
XmBulletinBoard
XmNinitialResourcesPersistent Core
XmNuserData
XmManager
XmNinsertPosition
Composite
XmNwidth
Core
XmNlabelFontList
XmBulletinBoard
XmNx
Core
XmNlabelRenderTable
XmBulletinBoard
XmNy
Core
XmNlayoutDirection
XmManager
Translations
The translations for Command are inherited from XmSelectionBox.
Action Routines
Command defines the following action routines:
SelectionBoxUpOrDown(flag)
Selects a command from the history list, replaces the current command-line text with this list item, and invokes the callbacks specified by XmNcommandChangedCallback. The value of flag
determines which history list command is selected. With a flag
value of 0, 1, 2, or 3, this action routine selects the list’s previous,
next, first, or last item, respectively.
Additional Behavior
Command has the following additional behavior:
MAny KCancel
The event is passed to the parent if it is a manager widget.
Motif Reference Manual
647
XmCommand
Motif and Xt Widget Classes
KActivate
In the Text widget, invokes the XmNactivateCallback callbacks,
appends the text to the history list, and invokes the XmNcommandEnteredCallback callbacks.
<Key>
In the Text widget, any keystroke that changes text invokes the
XmNcommandChangedCallback callbacks.
KActivate or <DoubleClick>
In the List widget, invokes the XmNdefaultActionCallback callbacks, appends the selected item to the history list, and invokes the
XmNcommandEnteredCallback callbacks.
<FocusIn>
Invokes the XmNfocusCallback callbacks.
<MapWindow>
If the widget is a child of a DialogShell, invokes the XmNmapCallback callbacks when the widget is mapped.
<UnmapWindow>
If the widget is a child of a DialogShell, invokes the XmNunmapCallback callbacks when the widget is unmapped.
See Also
XmCommandAppendValue(1), XmCommandError(1),
XmCommandGetChild(1), XmCommandSetValue(1),
XmCreateObject(1), Composite(2), Constraint(2), Core(2),
XmBulletinBoard(2), XmManager(2), XmSelectionBox(2).
648
Motif Reference Manual
Motif and Xt Widget Classes
XmContainer
Name
XmContainer widget class – a widget which controls the layout and selection of a
set of items
Synopsis
Public Header:
<Xm/Container.h>
Class Name:
XmContainer
Class Hierarchy:
Core → Composite → Constraint → XmManager → XmContainer
Class Pointer:
xmContainerWidgetClass
Instantiation:
widget = XmCreateContainer (parent, name,...)
or
widget = XtCreateWidget (name, xmContainerWidgetClass,...)
Functions/Macros:
XmContainerCopy(), XmContainerCopyLink(), XmContainerCut(),
XmContainerGetItemChild(), XmContainerPaste(), XmContainerPasteLink(), XmContainerRelayout(), XmContainerReorder(),
XmCreateContainer()
Availability
Motif 2.0 and later.
Description
A Container is a constraint widget which controls the layout and selection of container items. Container is intended to provide an object-oriented view of the
world: an application object can be represented in the Container as a container
item. The user can subsequently manipulate the item by moving, copying, selecting, or deleting it, or perform drag and drop operations between applications
using the item. New items can be dropped into the Container. At each stage, callbacks indicate to the application the operation performed upon each item, and
hence the requested operation upon the object which it represents. The Container
recognises as a container item any child widget which holds the XmQTcontainerItem trait. The IconGadget is the only standard Motif widget to hold this trait.
The Container provides three styles in which items can be displayed, specified
through the XmNlayoutType resource. The resource can have the values
XmOUTLINE, XmDETAIL, or XmSPATIAL.
Motif Reference Manual
649
XmContainer
Motif and Xt Widget Classes
The XmOUTLINE layout style provides a tree view onto the items, and is appropriate when application objects exist in a parent/child relationship to each other.
The logical relationship between items is specified by setting the XmNentryParent constraint resource of an item to point to the logical parent. The order of
items within the tree depends upon the XmNpositionIndex constraint value for
each item. The Container draws connecting lines between items to indicate the
relationships. The Container creates additional PushButtonGadgets which are
used for folding and unfolding portions of the tree.
The XmDETAIL layout style gives a tabular format, where each row of the table
represents an object, each cell within the row possibly representing a property of
the object. The data attached to an object and displayed in the row is specified
through the XmNdetail resources of the associated container item. Column headings can be specified through the XmNdetailColumnHeading resources of the
Container.
The XmSPATIAL layout style provides generic layout, where the exact positioning of items is controlled through further resources. This can take the form of a
grid layout, where items can span single or multiple cells of the grid, or a free
format where items can be positioned at absolute x, y coordinates of the Container. At the simplest, the grid layout can be used to construct a general purpose
icon box. The resources XmNspatialStyle, XmNspatialIncludeModel, and
XmNspatialSnapModel control the positioning of items.
The Container controls the way in which items are selected, and provides selection notification. The widget supports single, browse, multiple, and extended
selection. Selection of items within the Container can be performed by including
them within a rubberband rectangle called a Marquee, which the user specifies
using the mouse. Alternatively, selection can be performed by simply swiping the
mouse over an item. The style of selection is specified through the XmNselectionTechnique resource.
The user can only move container items if the XmNlayoutType is XmSPATIAL.
Traits
Container holds the XmQTtransfer, XmQTtraversalControl, and XmQTcontainer
traits, and uses the XmQTscrollFrame, XmQTcontainerItem, XmQTnavigator,
XmQTspecifyRenderTable, and XmQTpointIn traits.
650
Motif Reference Manual
Motif and Xt Widget Classes
XmContainer
New Resources
Container defines the following resources:
Name
Class
Type
Default
Access
XmNautomaticSelection
XmCAutomaticSelection
unsigned char
XmAUTO_SELECT
CSG
XmNcollapsedStatePixmap
XmCCollapsedStatePixmap
Pixmap
dynamic
CSG
XmNdetailColumnHeading
XmCDetailColumnHeading
XmStringTable
NULL
CSG
XmNdetailColumnHeadingCount XmCDetailColumnHeadingCount Cardinal
0
CSG
XmNdetailOrder
XmCDetailOrder
NULL
CSG
XmNdetailOrderCount
XmCDetailOrderCount
Cardinal
0
CSG
XmNdetailTabList
XmCDetailTabList
XmTabList
NULL
CSG
Cardinal *
XmNentryViewType
XmCEntryViewType
unsigned char
XmANY_ICON
CSG
XmNexpandedStatePixmap
XmCExpandedStatePixmap
Pixmap
dynamic
CSG
XmNfontList
XmCFontList
XmFontList
dynamic
CSG
XmNlargeCellHeight
XmCCellHeight
Dimension
0
CSG
XmNlargeCellWidth
XmCCellWidth
Dimension
0
CSG
XmNlayoutType
XmCLayoutType
unsigned char
XmSPATIAL
CSG
XmNmarginHeight
XmCMarginHeight
Dimension
0
CSG
XmNmarginWidth
XmCMarginWidth
Dimension
0
CSG
XmNoutlineButtonPolicy
XmCOutlineButtonPolicy
unsigned char
XmOUTLINE_BUTTON_PRESENT
CSG
XmNoutlineColumnWidth
XmCOutlineColumnWidth
Dimension
0
CSG
XmNoutlineIndentation
XmCOutlineIndentation
Dimension
40
CSG
XmNoutlineLineStyle
XmCOutlineLineStyle
unsigned char
XmSINGLE
CSG
XmNprimaryOwnership
XmCPrimaryOwnership
unsigned char
XmOWN_POSSIBLE_MULTIPLE
CSG
XmNrenderTable
XmCRenderTable
XmRenderTable dynamic
XmNselectColor
XmCSelectColor
Pixel
XmREVERSED_GROUND_COLORS CSG
XmNselectedObjectCount
XmCSelectedObjectCount
int
0
XmNselectedObjects
XmCSelectedObjects
WidgetList
NULL
SG
XmNselectionPolicy
XmCSelectionPolicy
unsigned char
XmEXTENDED_SELECT
CSG
XmNselectionTechnique
XmCSelectionTechnique
unsigned char
XmTOUCH_OVER
CSG
XmNsmallCellHeight
XmCCellHeight
Dimension
0
CSG
XmNsmallCellWidth
XmCCellWidth
Dimension
0
CSG
XmNspatialIncludeModel
XmCSpatialIncludeModel
unsigned char
XmAPPEND
CSG
XmNspatialResizeModel
XmCSpatialResizeModel
unsigned char
XmGROW_MINOR
CSG
XmNspatialSnapModel
XmCSpatialSnapModel
unsigned char
XmNONE
CSG
XmNspatialStyle
XmCSpatialStyle
unsigned char
XmGRID
CSG
Motif Reference Manual
CSG
SG
651
XmContainer
Motif and Xt Widget Classes
XmNautomaticSelection
Specifies whether selection callbacks are invoked immediately and each time that
an item is selected, or whether callbacks are invoked when the user has completed the selection action. Possible values:
XmAUTO_SELECT
XmNO_AUTO_SELECT
*/
/* callbacks called immediately on selection */
/* callbacks delayed until user action completed
XmNcollapsedStatePixmap
Specifies the pixmap to display on the PushButtonGadget to indicate that logical
child items are folded (hidden) within an XmOUTLINE layout. The resource has
no effect unless resource XmNoutlineButtonPolicy is
XmOUTLINE_BUTTON_PRESENT. Otherwise, if the resource is unspecified,
a default pixmap with an upwards pointing arrow is displayed.
XmNdetailColumnHeading
Specifies an XmString array to use as column headings in an XmDETAIL layout.
No column headings are displayed if the value is NULL.
XmNdetailColumnHeadingCount
Specifies the length of the array associated with the XmNdetailColumnHeading
resource.
XmNdetailOrder
Specifies an array of Cardinal values that represents which column, and in which
order, the detail data associated with container items is to be displayed. The
resource has no effect unless XmNlayoutType is XmDETAIL. If NULL, the
XmNdetailOrderCount resource is used to determine the column detail data associated with each item.
XmNdetailOrderCount
Specifies the length of the array associated with the XmNdetailOrder resource. If
XmNdetailOrder is NULL, and XmNdetailOrderCount is not zero, each container item displays any detail information in order starting from column 1, up to
the value of XmNdetailOrderCount. Otherwise, with a value of zero, a default
algorithm inspects the XmQTcontainerItem trait of each item to determine the
columnar data.
XmNdetailTabList
Specifies an XmTabList which indicates the start of each column in an XmDETAIL layout. If NULL, the Container calculates a default XmTabList.
XmNentryViewType
Specifies the view type for all Container children. If the value is XmANY_ICON,
then the XmQTcontainerItem trait of each child specifies the individual view
type. Possible values:
652
Motif Reference Manual
Motif and Xt Widget Classes
XmANY_ICON
XmLARGE_ICON
XmSMALL_ICON
XmContainer
/* children use their own view type */
/* all children forced to XmLARGE_ICON */
/* all children forced to XmSMALL_ICON */
XmNexpandedStatePixmap
Specifies the pixmap to display on the PushButtonGadget to indicate that logical
child items are unfolded (displayed). The resource has no effect unless XmNoutlineButtonPolicy is XmOUTLINE_BUTTON_PRESENT. Otherwise, if the
resource is unspecified, a default pixmap with a downwards pointing arrow is displayed.
XmNfontList
The XmFontList is considered obsolete in Motif 2.0 and later, and has been subsumed into the XmRenderTable. Any specified XmNrenderTable resource takes
precedence.
XmNlargeCellHeight
Specifies the height of a cell when the Container is using a grid layout. The
resource is not used when XmNentryViewType is XmSMALL_ICON.
XmNlargeCellWidth
Specifies the width of a cell when the Container is using a grid layout. The
resource is not used when XmNentryViewType is XmSMALL_ICON.
XmNlayoutType
Specifies the way in which the Container lays out children. Possible values:
XmOUTLINE
XmSPATIAL
XmDETAIL
*/
/* items are displayed in a tree arrangement
/* items displayed according to XmNspatialStyle resource */
/* items displayed in tabular row/column format
*/
XmNmarginHeight
Specifies the spacing at the top and bottom of the Container widget.
XmNmarginWidth
Specifies the spacing at the left and right of the Container widget.
XmNoutlineButtonPolicy
Specifies whether a PushButtonGadget, used for folding/unfolding items, is displayed with each container item that has logical children, specified by the
XmNentryParent resource. The resource has no effect if XmNspatialStyle is not
XmOUTLINE. Possible values:
XmOUTLINE_BUTTON_ABSENT
XmOUTLINE_BUTTON_PRESENT
/* display fold/unfold buttons */
/* no PushButtonGadget buttons */
XmNoutlineColumnWidth
Specifies the width of the first column within an XmDETAIL layout, and the preferred width of the Container within an XmOUTLINE layout. If zero, the Container will deduce a default value based upon the width of the widest item pixmap
and the XmNoutlineIndentation resource.
Motif Reference Manual
653
XmContainer
Motif and Xt Widget Classes
XmNoutlineIndentation
Specifies an indentation for container items. The resource has no effect when
XmNlayoutType1 is XmSPATIAL.
XmNoutlineLineStyle
Specifies whether to draw connecting lines between container items in an
XmOUTLINE or XmDETAIL layout. Possible values:
XmNO_LINE
XmSINGLE
*/
/* no line is drawn between items
*/
/* a line one pixel wide connects items
XmNprimaryOwnership
Specifies whether the Container takes possession of the primary selection when
the user makes a selection from the items within the widget. Possible values:
XmOWN_NEVER
*/
XmOWN_ALWAYS
*/
XmOWN_MULTIPLE
*/
XmOWN_POSSIBLE_MULTIPLE
*/
/* never own the primary selection
/* always own the primary selection
/* own if more than one item is selected
/* own if multiple selection possible
XmNrenderTable
Specifies the render table that is used for all children of the Container. If NULL,
the nearest ancestor holding the XmQTspecifyRenderTable trait is searched,
using the XmLABEL_FONTLIST value.
XmNselectColor
Specifies a color which container item children can use to indicate selected state.
In addition to allocated Pixel values, the constant
XmDEFAULT_SELECT_COLOR specifies a color between the XmNbackground and XmNbottomShadowColor, XmHIGHLIGHT_COLOR makes the
select color the same as the XmNhighlightColor value, and
XmREVERSED_GROUND_COLORS makes the XmNselectColor the same as
the XmNforeground, using the XmNbackground color to render any text.
XmNselectedObjectCount
Specifies the number of widgets in the array of selected container items, represented by the XmNselectedObjects resource.
1.Erroneously listed as XmNlayoutStyle in 2nd Edition.
654
Motif Reference Manual
Motif and Xt Widget Classes
XmContainer
XmNselectedObjects
Specifies an array of widgets representing the set of container items currently
selected.
XmNselectionPolicy
Specifies the way in which container items can be selected. Possible values:
XmSINGLE_SELECT
*/
XmBROWSE_SELECT
dragging */
XmMULTIPLE_SELECT
ble
*/
XmEXTENDED_SELECT
ble */
/* only one selected item permitted
/* as above, except items are selected by
/* items in contiguous range are selecta/* items in discontinuous range are selecta-
XmNselectionTechnique
Specifies the way in which items are selected. Possible values:
XmMARQUEE
/* items must be wholly enclosed
within Marquee
*/ XmMARQUEE_EXTEND_START/* includes item
containing Marquee start coordinate
*/ XmMARQUEE_EXTEND_BOTH/*
includes items containing Marquee start/end coordinates */ XmTOUCH_ONLY/*
select items between start and end location
*/
XmTOUCH_OVER
/* select only items the mouse passes
through
*/
XmNsmallCellHeight
Specifies the height of a cell when the Container spatial style is XmGRID, and
the XmNentryViewType resource is XmSMALL_ICON.
XmNsmallCellWidth
Specifies the width of a cell when the Container spatial style is XmGRID, and the
XmNentryViewType resource is XmSMALL_ICON.
XmNspatialIncludeModel
Specifies the layout of an item within a grid XmSPATIAL layout type, when the
item is managed. Possible values:
XmAPPEND
XmCLOSEST
XmFIRST_FIT
Motif Reference Manual
/* place after the last occupied cell */
/* according to XmNlayoutDirection */
/* place in the free cell */
/* nearest the x, y coordinates of the item */
/* place the item in the first free cell */
/* according to XmNlayoutDirection */
655
XmContainer
Motif and Xt Widget Classes
XmNspatialResizeModel
Specifies how the Container will attempt to resize itself when there is insufficient
space to contain a new item. The resource only has effect within a grid XmSPATIAL layout type. The definition of XmGROW_MAJOR and
XmGROW_MINOR depend upon the value of the XmNlayoutDirection
resource. The major dimension is width when the XmNlayoutDirection is horizontally oriented, and height when the direction is vertically oriented. Similarly,
the minor dimension is height when the XmNlayoutDirection is horizontally oriented, and width when the direction is vertically oriented. Possible values:
XmGROW_BALANCED
XmGROW_MAJOR
XmGROW_MINOR
/* request both width and height from parent */
/* request growth in the major dimension */
/* request growth in the minor dimension */
XmNspatialSnapModel
Specifies how the Container will position an item within a cell, when the XmNlayoutType is XmSPATIAL. A value of XmSNAP_TO_GRID positions the item
at the upper left or upper right of the cell, depending upon the value of XmNlayoutDirection. A value of XmNONE positions the item depending upon the value
of XmNx, XmNy: if these fall outside the cell, then layout is performed according to the XmSNAP_TO_GRID method. A value of XmCENTER centers the
item.
XmNspatialStyle
Specifies the layout of container items, when the XmNlayoutType is XmSPATIAL. Possible values:
XmCELLS
*/
XmGRID
*/
XmNONE
/* grid layout of same-sized cells. an item can occupy many cells
/* grid layout of same-sized cells. an item can occupy one cell
/* lay out according to XmNx, XmNy resources
*/
New Constraint Resources
Container defines the following constraint resources for its children:
656
Name
Class
Type
Default
Access
XmNentryParent
XmCEntryParent
Widget
NULL
CSG
XmNoutlineState
XmCOutlineState
unsigned char
XmCOLLAPSED
CSG
XmNpositionIndex
XmCPositionIndex
int
XmLAST_POSITION
CSG
Motif Reference Manual
Motif and Xt Widget Classes
XmContainer
XmNentryParent
Specifies a logical parent for the item. The root of a hierarchy has the value
NULL. Used when the XmNlayoutType is XmOUTLINE or XmDETAIL.
XmNoutlineState
Specifies whether to display logical child items when the XmNlayoutType is
XmOUTLINE or XmDETAIL. Possible values:
XmCOLLAPSED
XmEXPANDED
/* does not display child items */
/* displays child items
*/
XmNpositionIndex
Specifies the order of the item within the Container, when XmNlayoutType is
XmOUTLINE or XmDETAIL. Items are firstly ordered by XmNentryParent, and
by XmNpositionIndex within those items sharing the same XmNentryParent. If
unspecified, the highest such index for all other items sharing the same logical
parent is calculated, and then incremented. If no other item shares the same logical parent, the default is zero.
Callback Resources
Container defines the following callback resources:
Callback
Reason Constant
XmNconvertCallback
XmCR_OK
XmNdefaultActionCallback
XmCR_DEFAULT_ACTION
XmNdestinationCallback
XmCR_OK
XmNoutlineChangedCallback
XmCR_COLLAPSED
XmCR_EXPANDED
XmNselectionCallback
XmCR_SINGLE_SELECT
XmCR_BROWSE_SELECT
XmCR_MULTIPLE_SELECT
XmCR_EXTENDED_SELECT
XmNconvertCallback
List of callbacks called when a request is made to convert a selection.
XmNdefaultActionCallback
List of callbacks called when an item is double-clicked, or KActivate is pressed.
XmNdestinationCallback
List of callbacks called when the Container is the destination of a transfer.
XmNoutlineChangedCallback
List of callbacks called when a change is made to the XmNoutlineState value of
an item.
XmNselectionCallback
List of callbacks called when an item is selected.
Motif Reference Manual
657
XmContainer
Motif and Xt Widget Classes
Callback Structure
Each callback on the XmNoutlineChangedCallback list is passed the following
structure:
typedef struct
int
reason;
/* the reason that the callback was called */
XEvent
*event;
/* points to event that triggered callback */
Widget
item;
/* container item associated with event */
unsigned char new_outline_state;
/* the requested state */
} XmContainerOutlineCallbackStruct;
new_outline_state specifies an XmNoutlineState for item. The value may be
changed within the callback to force a particular state.
Each callback on the XmNselectionCallback and XmNdefaultActionCallback list
is passed the following structure:
typedef struct {
int
reason;
/* the reason that the callback was called */
XEvent
*event;
/* points to event that triggered callback */
WidgetList selected_items;
/* the list of selected items
*/
int
selected_item_count; /* the number of selected items */
unsigned char
auto_selection_type;
/* type of selection event */
} XmContainerSelectCallbackStruct;
selected_items is the array of container items selected by the event. The number
of such items is specified by selected_item_count. auto_selection_type indicates
the type of automatic selection event. If XmNautomaticSelection is False,
auto_selection_type has the value XmAUTO_UNSET. Otherwise, the range of
possible values is given by:
XmAUTO_BEGIN
XmAUTO_CANCEL
XmAUTO_CHANGE
XmAUTO_MOTION
XmAUTO_NO_CHANGE
/* event is the beginning of automatic selection */
/* current selection is cancelled
*/
/* current selection differs from initial selection */
/* current selection is caused by button drag */
/* current selection same as the initial selection */
Convert callbacks are fully described within the sections covering the Uniform
Transfer Model. See XmTransfer(1) for more details. For quick reference, a
pointer to the following structure is passed to callbacks on the XmNconvertCallback list:
typedef struct {
int
reason;
XEvent
*event;
Atom
selection;
658
/* reason that the callback is invoked
*/
/* points to event that triggered callback */
/* requested conversion selection
*/
Motif Reference Manual
Motif and Xt Widget Classes
XmContainer
Atom
target;
/* the conversion target
*/
XtPointer
source_data; /* selection source information
*/
XtPointer
location_data; /* information on data to be transferred */
int
flags;
/* input status of the conversion
*/
XtPointer
parm;
/* parameter data for the target
*
int
parm_format; /* format of parameter data
*/
unsigned long
parm_length; /* the number of elements
*/
/*
in parameter data
*/
Atom
parm_type;
/* the type of the parameter data */
int
status;
/* output status of the conversion
*/
XtPointer
value;
/* returned conversion data
*/
Atom
type;
/* type of conversion data returned
*/
int
format;
/* format of the conversion data
*/
unsigned long
length; /* number of elements in conversion data */
} XmConvertCallbackStruct;
Destination callbacks are fully described within the sections covering the Uniform Transfer Model. For quick reference, a pointer to the following structure is
passed to callbacks on the XmNdestinationCallback list:
typedef struct {
int
reason;
/* reason that the callback is invoked */
XEvent
*event;
/* points to event that triggered callback */
Atom
selection;
/* requested selection type, as an Atom */
XtEnum operation;
/* the type of transfer requested
*/
int
flags;
/* whether destination and source are same */
XtPointer transfer_id;
/* unique identifier for the request
*/
XtPointer destination_data; /* information about the destination
*/
XtPointer location_data;
/* information about the data
*/
Time
time;
/* time when transfer operation started */
} XmDestinationCallbackStruct;
Inherited Resources
Container inherits the resources shown below. The resources are listed alphabetically, along with the superclass that defines them.
Resource
Inherited From Resource
Inherited From
XmNaccelerators
Core
XmNinsertPosition
Composite
XmNancestorSensitive
Core
XmNlayoutDirection
XmManager
XmNbackground
Core
XmNmappedWhenManaged Core
XmNbackgroundPixmap
Core
XmNnavigationType
XmManager
XmNborderColor
Core
XmNnumChildren
Composite
Motif Reference Manual
659
XmContainer
Motif and Xt Widget Classes
Resource
Inherited From Resource
Inherited From
XmNborderPixmap
Core
XmNpopupHandlerCallback XmManager
XmNborderWidth
Core
XmNscreen
Core
XmNbottomShadowColor
XmManager
XmNsensitive
Core
XmNbottomShadowPixmap
XmManager
XmNshadowThickness
XmManager
XmNchildren
Composite
XmNstringDirection
XmManager
XmNcolormap
Core
XmNtopShadowColor
XmManager
XmNdepth
Core
XmNtopShadowPixmap
XmManager
XmNdestroyCallback
Core
XmNtranslations
Core
XmNforeground
XmManager
XmNtraversalOn
XmManager
XmNheight
Core
XmNunitType
XmManager
XmNhelpCallback
XmManager
XmNuserData
XmManager
XmNhighlightColor
XmManager
XmNwidth
Core
XmNhighlightPixmap
XmManager
XmNx
Core
XmNinitialFocus
XmManager
XmNy
Core
XmNinitialResourcesPersistent Core
Widget Hierarchy
The PushButtonGadget children created by an outline style Container are all
named OutlineButton.
Translations
The translations for Container include those of XmManager.
660
Event
Action
BSelect Press
ContainerHandleBtn1Down(ContainerBeginSelect, Copy)
BToggle Press
ContainerHandleBtn1Down(ContainerBeginToggle, Copy)
MLink BSelect Press
ContainerHandleBtn1Down(ContainerNoop, Link)
BExtend Press
ContainerHandleBtn1Down(ContainerBeginExtend Move)
BExtend Motion
ContainerHandleBtn1Motion(ContainerButtonMotion)
BSelect Release
ContainerHandleBtn1Up(ContainerEndSelect)
BToggle Release
ContainerHandleBtn1Up(ContainerEndToggle)
BExtend Release
ContainerHandleBtn1Up(ContainerEndExtend)
BTransfer Press
ContainerHandleBtn2Down(ContainerStartTransfer, Copy)
MLink BTransfer Press
ContainerHandleBtn2Down(ContainerStartTransfer, Link)
MMove BTransfer Press
ContainerHandleBtn2Down(ContainerStartTransfer, Move)
BTransfer Motion
ContainerHandleBtn2Motion(ContainerButtonMotion)
Motif Reference Manual
Motif and Xt Widget Classes
XmContainer
Event
Action
BTransfer Release
ContainerHandleBtn2Up(ContainerEndTransfer)
MShift KPrimaryCopy
ContainerPrimaryLink()
KPrimaryCopy
ContainerPrimaryCopy()
KPrimaryCut
ContainerPrimaryMove()
KCancel
ContainerCancel()
KExtend
ContainerExtend()
KSelect
ContainerSelect()
KSelectAll
ContainerSelectAll
KDeselectAll
ContainerDeselectAll()
KAddMode
ContainerToggleMode()
KActivate
ContainerActivate()
MShift KBeginData
ContainerExtendCursor(First)
MShift KEndData
ContainerExtendCursor(Last)
KBeginData
ContainerMoveCursor(First)
KEndData
ContainerMoveCursor(Last)
MCtrl KLeft
ContainerExpandOrCollapse(Left)
MCtrl KRight
ContainerExpandOrCollapse(Right)
MShift KUp
ContainerExtendCursor(Up)
MShift KDown
ContainerExtendCursor(Down)
MShift KLeft
ContainerExtendCursor(Left)
MShift KRight
ContainerExtendCursor(Right)
KUp
ContainerMoveCursor(Up)
KDown
ContainerMoveCursor(Down)
KLeft
ContainerMoveCursor(Left)
KRight
ContainerMoveCursor(Right)
Action Routines
Container defines the following action routines:
ContainerActivate()
Calls the procedures associated with the XmNdefaultActionCallback resource.
Motif Reference Manual
661
XmContainer
Motif and Xt Widget Classes
ContainerBeginExtend()
The action has no effect if the XmNlayoutType is XmSPATIAL, or
if the XmNselectionPolicy is either XmSINGLE_SELECT or
XmBROWSE_SELECT.
Otherwise, the location cursor is set to the object under the pointer,
and if no object is there, or if there is no anchor, the action returns.
Any items between the anchor and the location cursor are selected.
Finally, if automatic selection is enabled, the list of callbacks specified by the XmNselectionCallback resource is invoked.
ContainerBeginSelect()
Single selection: if the object under the pointer is the anchor item,
the selected state of the object is reversed. Otherwise, all items are
deselected, the object at the pointer is made the anchor item, and
the location cursor is set to it.
Browse selection: if the object under the pointer is not the anchor
item, all items are deselected, the object is made the anchor item
and selected, and the location cursor is set to it. If automatic selection is enabled, the list of callbacks specified by the XmNselectionCallback resource is invoked.
Multiple selection: sets the anchor item to the object under the
pointer, and sets the location cursor to it. The selected state of the
item is reversed. If the selection technique is XmTOUCH_OVER,
and the anchor item is NULL, the Marquee start point is initialized.
If automatic selection is enabled, the list of callbacks specified by
the XmNselectionCallback resource is invoked.
Extended selection: as for multiple selection, except initially all
items are deselected.
ContainerBeginToggle()
The action has no effect if the XmNlayoutType is XmSPATIAL, or
if the XmNselectionPolicy is either XmSINGLE_SELECT or
XmBROWSE_SELECT.
Multiple or Extended selection: the anchor item is set to the object
under the pointer, and the location cursor is set to it. The selected
state of the item is reversed. If automatic selection is enabled, the
list of callbacks specified by the XmNselectionCallback resource is
invoked. Lastly, if XmNselectionTechnique is
XmMARQUEE_EXTEND_START or
XmMARQUEE_EXTEND_BOTH, the Marquee rectangle is
drawn around the item.
662
Motif Reference Manual
Motif and Xt Widget Classes
XmContainer
ContainerButtonMotion()
The action has no effect if XmNselectionPolicy is
XmSINGLE_SELECT.
Browse selection: if the action follows ContainerBeginExtend() or
ContainerBeginToggle() action, or if the pointer is over the current
anchor item, the routine simply returns. Otherwise, the selected
state of the anchor item is reversed, the selected state of any item
under the pointer is also reversed, and the anchor item is reset to
point to it.
Multiple and extended selection: if a previous action has initiated
the Marquee, the rectangle is redrawn around the start point and the
current pointer location. The selected state of all items within the
Marquee are set to that of the anchor item. For non-Marquee selection, in a spatial layout the selected state of the item under the
pointer is reversed, and the anchor item is reset to it. In a non-spatial layout, the selected state of all items between the anchor item
and the item under the pointer are set to match the selected state of
the anchor item.
In all cases, if automatic selection is enabled, the list of callbacks
specified by the XmNselectionCallback resource is invoked.
ContainerCancel()
The selected state of all items reverts to the pre-selection state. If
automatic selection is enabled, the list of callbacks specified by the
XmNselectionCallback resource is invoked.
ContainerDeselectAll()
All items are deselected, and the callbacks on the XmNselectionCallback list are invoked.
ContainerEndExtend()
The action has no effect if XmNlayoutType is XmSPATIAL.
Multiple or Extended selection: the callbacks specified by XmNselectionCallback are invoked.
ContainerEndSelect()
Single selection: simply invokes the callbacks specified by the
XmNselectionCallback resource.
Browse selection: if the pointer is not over the current anchor item,
the selected state of the current anchor, and the selected state of any
item under the pointer are reversed. Callbacks specified by XmNselectionCallback are invoked.
Motif Reference Manual
663
XmContainer
Motif and Xt Widget Classes
Multiple and extended selection: similar to the ContainerButtonMotion() action, except that the auto_selection_type element within
XmNselectionCallback procedures is XmAUTO_CHANGE or
XmAUTO_NO_CHANGE rather than XmAUTO_MOTION.
ContainerEndToggle()
The action has no effect if XmNselectionPolicy is
XmSINGLE_SELECT or XmBROWSE_SELECT.
Multiple or extended selection: the procedure directly invokes the
ContainerEndSelect() action.
ContainerEndTransfer()
If the current transfer operation is XmLINK, the ContainerPrimaryLink() action is called. If the transfer operation is XmMOVE, the
procedure invokes ContainerPrimaryMove(). If the operation is
XmCOPY, the ContainerPrimaryCopy() action is called.
ContainerExpandOrCollapse(type)
The action has no effect if layout type is XmSPATIAL().
Otherwise, the outline state of the container item which has the
focus is changed. Possible values for type:
Collapse/* outline state set to XmCOLLAPSED */
Expand/* outline state set to XmEXPANDED */
Left/* depends upon layout direction */
Right/* depends upon layout direction */
If XmNlayoutDirection is XmLEFT_TO_RIGHT, Left is interpreted as XmCOLLAPSED, and Right as XmEXPANDED. This is
reversed if the layout direction is XmRIGHT_TO_LEFT.
ContainerExtend()
The action has no effect if layout type is XmSPATIAL(), or if
XmNselectionPolicy is XmSINGLE_SELECT or
XmBROWSE_SELECT.
Multiple selection: the selected state of all items between the
anchor item and the location cursor is set to that of the anchor item.
The callbacks specified by XmNselectionCallback are invoked.
Extended selection: in Normal mode, all items are deselected, then
any items between the anchor item and the location cursor are
selected. In Add mode, the selected state of all items between the
anchor item and the location cursor is set to that of the anchor item.
The callbacks specified by XmNselectionCallback are invoked.
664
Motif Reference Manual
Motif and Xt Widget Classes
XmContainer
ContainerExtendCursor(type)
The action has no effect if layout type is XmSPATIAL(), or if
XmNselectionPolicy is XmSINGLE_SELECT or
XmBROWSE_SELECT.
The location cursor is moved. If type is Left, Right, Up, Down,
First, or Last, the cursor is moved one item in the specified direction if possible (or to the first/last item).
Thereafter, the ContainerExtend() procedure is directly invoked.
ContainerHandleBtn1Down(string)
The XmDisplay resource XmNenableBtn1Transfer configures the
integration of selection and transfer operations on Button 1.
If XmNenableBtn1Transfer is not XmOFF, and the pointer is over
an unselected item, the actions ContainerBeginSelect() and ContainerEndSelect() are invoked in order to select the item. If thereafter
there is no selected item, the Marquee start point is initialized, otherwise the action becomes a data transfer operation, and the ContainerStartTransfer() action is invoked.
If XmNenableBtn1Transfer is XmOFF, and if no data transfer has
been initialized, the action specified by string is invoked to initiate
selection. Possible values for string:
ContainerBeginSelect,Copy
ContainerBeginToggle,Copy
ContainerNoop,Link
ContainerBeginExtend,Move
ContainerHandleBtn1Motion(string)
If the XmDisplay XmNenableBtn1Transfer resource is not
XmOFF, and a selection is in progress, a drag action is initiated.
Otherwise, the action as specified by string is invoked, typically
ContainerButtonMotion.
ContainerHandleBtn1Up(string)
If a Button1 transfer is in progress, the transfer is cancelled. Otherwise, the action as specified by string is invoked. Possible values for
string:
ContainerEndSelect
ContainerEndToggle
ContainerEndExtend
Motif Reference Manual
665
XmContainer
Motif and Xt Widget Classes
ContainerHandleBtn2Down(string)
If the XmDisplay XmNenableBtn1Transfer resource is
XmBUTTON2_ADJUST, the action ContainerBeginExtend is
directly invoked. Otherwise, the action as specified by string is
invoked. Possible values for string:
ContainerStartTransfer, Copy
ContainerStartTransfer, Link
ContainerStartTransfer, Move
ContainerHandleBtn2Motion(string)
If the XmDisplay XmNenableBtn1Transfer resource is not
XmBUTTON2_ADJUST, and a selection is in progress, a drag
action is initiated. Otherwise, the action as specified by string is
invoked, typically ContainerButtonMotion.
ContainerHandleBtn2Up(string)
If the XmDisplay XmNenableBtn1Transfer resource is
XmBUTTON2_ADJUST, the action directly invokes the ContainerEndExtend() action. Otherwise, the action as specified by string is
invoked, typically ContainerEndTransfer.
ContainerMoveCursor(string)
Moves the location cursor to the container item in a given direction,
if possible. Valid values of type: Up, Down, Left, Right, First, Last.
If the number of selected items is greater than 1, all items are deselected. The item at the location cursor is selected, and callbacks
associated with the XmNselectionCallback resource are invoked.
ContainerPrimaryCopy()
Requests a primary selection copy to the Container. Any XmNdestinationCallback procedures are invoked. By default, the Container
performs no data transfer: the programmer must provide a callback
for the task.
ContainerPrimaryLink()
Requests a primary selection link to the Container. Any XmNdestinationCallback procedures are invoked. By default, the Container
performs no data transfer: the programmer must provide a callback
for the task.
ContainerPrimaryMove()
Requests a primary selection copy to the Container. Any XmNdestinationCallback procedures are invoked. By default, the Container
performs no data transfer: the programmer must provide a callback
666
Motif Reference Manual
Motif and Xt Widget Classes
XmContainer
for the task. Subsequently, the selection owner’s XmNconvertCallback procedures are notified for the primary selection, with the target DELETE.
ContainerSelect()
Single or browse selection: deselects any selected item, and selects
the item at the location cursor.
Multiple selection: reverses the selected state of the item at the location cursor, and makes this the anchor for any further operations.
Extended selection: in Normal mode, deselects all items, and
selects the item at the location cursor. In Add mode, reverses the
selected state of the item, which becomes the anchor for further
operations.
In each case, callbacks associated with the XmNselectionCallback
resource are invoked.
ContainerSelectAll()
Single or browse selection: deselects any selected item, and selects
the item at the location cursor.
Multiple or extended selection: selects all container items.
In all cases, callbacks associated with the XmNselectionCallback
resource are invoked.
ContainerStartTransfer(type)
The action saves the value of the parameter type for reference by
later transfer operations. In XmSPATIAL layout, a DragContext is
created, and a transfer operation is initiated. By default, unless
overridden by a customized XmNconvertCallback procedure, if the
drop occurs within the Container, then any dragged unselected item
is moved to the pointer location, or if the item is selected, then all
selected items are relocated to the pointer. Possible values for type
are: Copy, Link, Move.
ContainerToggleMode()
Extended selection: toggles between Normal and Add mode.
Additional Behavior
Container has the following additional behavior:
<Double Click>
Calls the XmNdefaultActionCallback callbacks.
Motif Reference Manual
667
XmContainer
Motif and Xt Widget Classes
<FocusIn>
If the keyboard focus policy is explicit, sets the focus and draws the
location cursor.
<FocusOut>
If the keyboard focus policy is explicit, removes the focus and
erases the location cursor.
See Also
XmContainerCopy(1), XmContainerCopyLink(1),
XmContainerCut(1), XmContainerGetItemChildren(1),
XmContainerPaste(1), XmContainerPasteLink(1),
XmContainerRelayout(1), XmContainerReorder(1),
XmCreateObject(1), XmTransfer(1), Composite(2), Constraint(2),
Core(2), XmIconGadget(2), XmManager(2).
668
Motif Reference Manual
Motif and Xt Widget Classes
XmDialogShell
Name
XmDialogShell widget class – the Shell parent for dialog boxes.
Synopsis
Public Header:
<Xm/DialogS.h>
Class Name:
XmDialogShell
Class Hierarchy:
Core → Composite → Shell → WMShell → VendorShell → TransientShell →
XmDialogShell
Class Pointer:
xmDialogShellWidgetClass
Instantiation:
widget = XmCreateDialogShell (parent, name,...)
or
widget = XtCreateWidget (name, xmDialogShellWidgetClass,...)
Functions/Macros:
XmCreateDialogShell(), XmIsDialogShell()
Description
DialogShell is the parent for dialog boxes. A DialogShell cannot be iconified separately, but only when the main application shell is iconified. The child of a DialogShell is typically a subclass of BulletinBoard and much of the functionality of
DialogShell is based on this assumption.
Traits
DialogShell uses the XmQTdialogShellSavvy trait.
New Resources
DialogShell does not define any new resources.
Inherited Resources
DialogShell inherits the following resources. The resources are listed alphabetically, along with the superclass that defines them. DialogShell sets the default
values of XmNdeleteResponse to XmUNMAP and XmNinput and XmNtransient
to True. The default value of XmNborderWidth is reset to 0 by VendorShell.
Resource
Inherited From Resource
Inherited From
XmNaccelerators
Core
XmNmaxAspectX
WMShell
XmNallowShellResize
Shell
XmNmaxAspectY
WMShell
Motif Reference Manual
669
XmDialogShell
670
Motif and Xt Widget Classes
Resource
Inherited From Resource
Inherited From
XmNancestorSensitive
Core
XmNmaxHeight
WMShell
XmNaudibleWarning
VendorShell
XmNmaxWIdth
WMShell
XmNbackground
Core
XmNminAspectX
WMShell
XmNbackgroundPixmap
Core
XmNminAspectY
WMShell
XmNbaseHeight
WMShell
XmNminHeight
WMShell
XmNbaseWidth
WMShell
XmNminWidth
WMShell
XmNborderColor
Core
XmNmwmDecorations VendorShell
XmNborderPixmap
Core
XmNmwmFunctions
VendorShell
XmNborderWidth
Core
XmNmwmInputMode
VendorShell
XmNbuttonFontList
VendorShell
XmNmwmMenu
VendorShell
XmNbuttonRenderTable
VendorShell
XmNnumChildren
Composite
XmNchildren
Composite
XmNoverrideRedirect
Shell
XmNcolormap
Core
XmNpopdownCalback Shell
XmNcreatePopupChildProc
Shell
XmNpopupCallback
Shell
XmNdefaultFontList
VendorShell
XmNpreeditType
VendorShell
XmNdeleteResponse
VendorShell
XmNsaveUnder
Shell
XmNdepth
Core
XmNscreen
Core
XmNdestroyCallback
Core
XmNsensitive
Core
XmNgeometry
Shell
XmNshellUnitType
VendorShell
XmNheight
Core
XmNtextFontList
VendorShell
XmNheightInc
WMShell
XmNtextRenderTable
VendorShell
XmNiconMask
WMShell
XmNtitle
WMShell
XmNiconPixmap
WMShell
XmNtitleEncoding
WMShell
XmNiconWindow
WMShell
XmNtransient
WMShell
XmNinitialResourcesPersistent Core
XmNtransientFor
TransientShell
XmNinitialState
XmNtranslations
Core
WMShell
XmNinput
WMShell
XmNvisual
Shell
XmNinputMethod
VendorShell
XmNwaitForWm
WMShell
XmNinputPolicy
VendorShell
XmNwidth
Core
XmNinsertPosition
Composite
XmNwidthInc
WMShell
XmNkeyboardFocusPolicy
VendorShell
XmNwindowGroup
WMShell
XmNlabelFontList
VendorShell
XmNwinGravity
WMShell
XmNlabelRenderTable
VendorShell
XmNwmTimeout
WMShell
XmNlayoutDirection
VendorShell
XmNx
Core
XmNmappedWhenManaged
Core
XmNy
Core
Motif Reference Manual
Motif and Xt Widget Classes
XmDialogShell
See Also
XmCreateObject(1), Composite(2), Core(2), Shell(2),
TransientShell(2), VendorShell(2), WMShell(2),
XmBulletinBoardDialog(2), XmErrorDialog(2),
XmFileSelectionDialog(2), XmFormDialog(2),
XmInformationDialog(2), XmMessageDialog(2),
XmPromptDialog(2), XmQuestionDialog(2),
XmSelectionDialog(2), XmTemplateDialog(2),
XmWarningDialog(2), XmWorkingDialog(2).
Motif Reference Manual
671
XmDisplay
Motif and Xt Widget Classes
Name
XmDisplay widget class – an object to store display-specific information.
Synopsis
Public Header:
<Xm/Display.h>
Class Name:
XmDisplay
Class Hierarchy:
Core → Composite → Shell → WMShell → VendorShell → TopLevelShell →
ApplicationShell → XmDisplay
Class Pointer:
xmDisplayClass
Instantiation:
widget = XtAppInitialize(...)
Functions/Macros:
XmGetXmDisplay(), XmIsDisplay()
Availability
Motif 1.2 and later.
Description
The Display object stores display-specific information for use by the toolkit. An
application has a Display object for each display it accesses. When an application
creates its first shell on a display, typically by calling XtAppInitialize() or
XtAppCreateShell(), a Display object is created automatically. There is no
way to create a Display independently. The function XmGetXmDisplay() can
be used to get the widget ID of the Display object.
The XmNdragInitiatorProtocolStyle and XmNdragReceiverProtocolStyle
resources specify the drag protocol for an application that performs drag and
drop operations. The two protocol styles are Dynamic and Preregister. Under the
dynamic protocol, the initiator and receiver pass messages back and forth to handle drag and drop visuals. Under the Preregister protocol, the initiator handles
drag and drop visuals by reading information that is preregistered and stored in
properties. The actual protocol that is used by a specific initiator and receiver is
based on the requested protocol styles of the receiver and initiator:
672
Motif Reference Manual
Motif and Xt Widget Classes
XmDisplay
Drag Initiator
Drag Receiver Protocol Style
Protocol Style
Preregister
Prefer Preregister
Prefer Dynamic
Dynamic
Preregister
PREREGISTER
PREREGISTER
PREREGISTER
DROP_ONLY
Prefer Preregister
PREREGISTER
PREREGISTER
PREREGISTER
DYNAMIC
Prefer Receiver
PREREGISTER
PREREGISTER
DYNAMIC
DYNAMIC
Prefer Dynamic
PREREGISTER
DYNAMIC
DYNAMIC
DYNAMIC
Dynamic
DROP_ONLY
DYNAMIC
DYNAMIC
DYNAMIC
New Resources
Display defines the following resources:
Name
Class
Type
Default
Access
XmNdefaultButtonEmphasis
XmCDefaultButtonEmphasis
XtEnum
XmEXTERNAL_HIGHLIGHT
SG
dynamic
XmNdefaultVirtualBindings
XmCDefaultVirtualBindings
String
XmNdragInitiatorProtocolStyle
XmCDragInitiatorProtocolStyle
unsigned char XmDRAG_PREFER_RECEIVER
SG
SG
XmNdragReceiverProtocolStyle XmCDragReceiverProtocolStyle unsigned char XmDRAG_PREFER_PREREGISTER SG
XmNenableBtn1Transfer
XmCEnableBtn1Transfer
XtEnum
XmOFF
CG
XmNenableButtonTab
XmCEnableButtonTab
Boolean
False
CG
XmNenableDragIcon
XmCEnableDragIcon
Boolean
False
CG
XmNenableEtchedInMenu
XmCEnableEtchedinMenu
Boolean
False
CG
XmNenableMultiKeyBindings
XmCEnableMultiKeyBindings
Boolean
False
CG
XmNenableThinThickness
XmCEnableThinThickness
Boolean
False
CG
XmNenableToggleColor
XmCEnableToggleColor
Boolean
False
CG
XmNenableToggleVisual
XmCEnableToggleVisual
Boolean
False
CG
XmNenableUnselectableDrag
XmCEnableUnselectableDrag
Boolean
True
CG
XmNenableWarp
XmCEnableWarp
XtEnum
True
CG
XmNmotifVersion
XmCMotifVersion
int
XmVersion
CSG
XmNuserData
XmCUserData
XtPointer
NULL
CSG
XmNdefaultButtonEmphasis
In Motif 2.0 and later, specifies the manner in which button widgets and gadgets
which have the XmNshowAsDefault resource set are displayed. A button which
is the default has a double border. If XmNdefaultButtonEmphasis is
XmINTERNAL_HIGHLIGHT, the location cursor is drawn between the double
border. Otherwise, with a value of XmEXTERNAL_HIGHLIGHT, the location
Motif Reference Manual
673
XmDisplay
Motif and Xt Widget Classes
cursor is drawn outside of the double border. An internal indication uses less
space for the button.
XmNdefaultVirtualBindings
In Motif 2.0 and later, specifies the default virtual bindings for the display.
XmNdragInitiatorProtocolStyle
The client’s drag and drop protocol requirements or preference when it is the initiator of a drag and drop operation. Possible values:
XmDRAG_PREREGISTER
/* can only use the preregister protocol */
XmDRAG_DYNAMIC
/* can only use the dynamic protocol */
XmDRAG_NONE
/* drag and drop is disabled
*/
XmDRAG_DROP_ONLY
/* only supports dragging
*/
XmDRAG_PREFER_DYNAMIC
/* supports both but prefers dynamic */
XmDRAG_PREFER_PREREGISTER
/* supports both but prefers preregister */
XmDRAG_PREFER_RECEIVER /* supports both; prefers receiver’s
*/
/* protocol */
XmNdragReceiverProtocolStyle
The client’s drag and drop protocol requirements or preference when it is the
receiver. Possible values:
XmDRAG_PREREGISTER
/* can only use the preregister protocol */
XmDRAG_DYNAMIC
/* can only use the dynamic protocol */
XmDRAG_NONE
/* drag and drop is disabled
*/
XmDRAG_DROP_ONLY
/* only supports dropping
*/
XmDRAG_PREFER_DYNAMIC
/* supports both but prefers dynamic */
XmDRAG_PREFER_PREREGISTER
/* supports both but prefers preregister */
XmNenableBtn1Transfer
In Motif 2.0 and later, configures selection and transfer actions for Button1. The
Container, Text, TextField, and List actions are affected by this resource. Possible
values:
XmOFF
/* selection and transfer disabled for button 1 */
XmBUTTON2_TRANSFER /* selection on button 1, transfer on button 2 */
XmBUTTON2_ADJUST
/* selection on button 1, adjust on button 2 */
XmNenableButtonTab
In Motif 2.0 and later, configures the action of the Tab key with respect to keyboard navigation. If True, KNextField and KPrevField will behave like an Arrow
key, moving the focus between widgets within a Tab Group, until the boundary of
a Tab group is reached, at which point a subsequent navigation will move the
focus into the next or previous Tab group. If False, KNextField and KPrevField
move the focus to the next or previous tab group respectively.
674
Motif Reference Manual
Motif and Xt Widget Classes
XmDisplay
XmNenableDragIcon
In Motif 2.0 and later, a set of alternative icons representing the drag and drop
default cursors is available. A value of True specifies that the newer icons are the
default.
XmNenableEtchedInMenu
In Motif 2.0 and later, specifies the way in which buttons within menus are shadowed when the widget is activated. The value False results in an etched out
appearance, True gives an etched in shadowing, which is consistent with the
appearance of activated buttons outside of a menu system. The resource affects
PushButton, ToggleButton, CascadeButton widgets and gadget counterparts.
XmNenableMultiKeyBindings
In Motif 2.1, merges an additional set of translations into the resource database
which are compatible with CDE cancel translations.
XmNenableThinThickness
Introduced in Motif 1.2.5 to provide CDE style shadowing and highlighting, used
originally only by the ScrollBar. In Motif 2.1, the number of widgets sensitive to
the resource is considerably expanded. If True, the default shadow thickness is 1,
otherwise the default is 2.
XmNenableToggleColor
In Motif 2.0 and later, specifies how the default value of a toggle’s XmNselectColor is determined. True means that the default is taken from the XmNhighlightColor value, False uses the XmNbackground. XmNenableToggleColor is
ignored if an explicit XmNselectColor is supplied to the toggle widget or gadget.
The resource only takes effect if the indicator type of the toggle is
XmONE_OF_MANY or XmONE_OF_MANY_ROUND.
XmNenableToggleVisual
In Motif 2.0 and later, controls the default appearance of toggles. If False, a toggle with the indicator type of XmONE_OF_MANY is drawn as a diamond, and a
toggle with indicator type XmN_OF_MANY is drawn square. If True, a toggle
within a radio box has the default indicator type XmONE_OF_MANY_ROUND,
which is rendered as a circle. A toggle outside of a radio box has the default indicator type XmN_OF_MANY, which is rendered square, and a check mark is displayed when XmNindicatorOn is True.
XmNenableUnselectableDrag
In Motif 2.0 and later, specifies whether it is possible to initiate a drag operation
from Label, LabelGadget, or Scale widgets. The value True enables drag operations from the widgets.
Motif Reference Manual
675
XmDisplay
Motif and Xt Widget Classes
XmNenableWarp
In Motif 2.0 and later, specifies if the application is permitted to warp the pointer
away from the user. The value True enables warping.
XmNmotifVersion
In Motif 2.0 and later, specifies the current version of Motif.
XmNuserData
In Motif 2.0 and later, specifies a pointer to data that the application can attach to
the XmDisplay object. The resource is unused internally.
Callback Resources
In Motif 2.0 and later, Display defines the following callback resources:
Callback
Reason Constant
XmNdragStartCallback
XmCR_DRAG_START
XmNnoFontCallback
XmCR_NO_FONT
XmNnoRenditionCallback
XmCR_NO_RENDITION
XmNdragStartCallback
List of callbacks that are called when the procedure XmDragStart() is
invoked.
XmNnoFontCallback
List of callbacks that are called when an XmRendition object fails in an attempt
to load a font. This may happen if the object is created with an XmNloadModel
of XmLOAD_IMMEDIATE, and the font cannot be loaded there and then, or if
the XmNloadModel is XmLOAD_DEFERRED and a later attempt is made to
render a compound string using an unloadable font. A callback can be supplied to
rectify the situation: it can find or specify an alternative font, and invoke the function XmRenditionUpdate() upon the rendition object.
XmNnoRenditionCallback
List of callbacks that are called when an attempt is made to render using a rendition tag which does not match any entry within a given render table. A callback
can be supplied to rectify the problem: it can create a new rendition with the
problematic tag, and augment the render table.
Callback Structure
Each XmNnoFontCallback or XmNnoRenditionCallback procedure is passed the
following structure:
typedef struct {
int
XEvent
XmRendition
676
reason;
*event;
rendition;
/* the reason that the callback was called */
/* points to event that triggered callback */
/* the rendition with a missing font
*/
Motif Reference Manual
Motif and Xt Widget Classes
XmDisplay
char
*font_name;
XmRenderTable render_table;
XmString
tag;
} XmDisplayCallbackStruct;
/* the font which is not loadable
*/
/* the render table with a missing rendition */
/* the tag of the missing rendition
*/
The render_table and tag elements are only applicable to callbacks on the XmNnoRenditionCallback list. rendition and font_name are valid only for XmNnoFontCallback callbacks.
In addition, an XmNdragStartCallback procedure is passed the following structure:
typedef struct {
int
reason;
XEvent
*event;
Widget
widget;
Boolean
doit;
} XmDragStartCallbackStruct;
*/
/* the reason that the callback was called
/* points to event structure that triggered callback */
/* the ID of the widget where the drag initiated */
/* do the action (True) or undo it (False)
*/
Inherited Resources
None of the resources inherited by Display can be set by the programmer or user.
See Also
XmGetXmDisplay(1), ApplicationShell(2), Composite(2), Core(2),
Shell(2), TopLevelShell(2), VendorShell(2), WMShell(2),
XmScreen(2).
Motif Reference Manual
677
XmDragContext
Motif and Xt Widget Classes
Name
XmDragContext widget class – an object used to store information about a drag
transaction.
Synopsis
Public Header:
<Xm/DragDrop.h>
Class Name:
XmDragContext
Class Pointer:
xmDragContextClass
Class Hierarchy:
Core → DragContext
Instantiation:
widget = XmDragStart(...)
Functions/Macros:
XmDragCancel(), XmDragStart()
Availability
Motif 1.2 and later.
Description
The DragContext object stores information that the toolkit needs to process a
drag transaction. An application does not explicitly create a DragContext widget,
but instead initiates a drag and drop operation by calling XmDragStart(),
which initializes and returns a DragContext widget. The DragContext stores
information about the types of data and operations of the drag source, the drag
icons that are used during the drag, and the callbacks that are called during different parts of the drag. These characteristics can be specified as resources when the
DragContext is created using XmDragStart().
Each drag operation has a unique DragContext that is freed by the toolkit when
the operation is complete. The initiating and receiving clients in a drag and drop
operation both use the DragContext to keep track of the state of the operation.
The drag-over visual effects that are used during a drag operation depend on the
drag protocol that is being used. Under the preregister protocol, either a cursor or
a pixmap can be used, since the server is grabbed. Under the dynamic protocol,
the X cursor is used.
678
Motif Reference Manual
Motif and Xt Widget Classes
XmDragContext
New Resources
DragContext defines the following resources:
Name
Class
Type
Default
Access
XmNblendModel
XmCBlendModel
unsigned char
XmBLEND_ALL
CG
XmNclientData
XmCClientData
XtPointer
NULL
CSG
XmNconvertProc
XmCConvertProc
XtConvertSelectionIncrProc NULL
CSG
XmNcursorBackground
XmCCursorBackground
Pixel
dynamic
CSG
XmNcursorForeground
XmCCursorForeground
Pixel
dynamic
CSG
XmNdragOperations
XmCDragOperations
unsigned char
XmDROP_COPY | C
XmDROP_MOVE
XmNexportTargets
XmCExportTargets
Atom *
NULL
CSG
XmNincremental
XmCIncremental
Boolean
False
CSG
XmNinvalidCursorForeground XmCCursorForeground
Pixel
dynamic
CSG
XmNnoneCursorForeground
XmCCursorForeground
Pixel
dynamic
CSG
XmNnumExportTargets
XmCNumExportTargets
Cardinal
0
CSG
XmNoperationCursorIcon
XmCOperationCursorIcon Widget
dynamic
CSG
XmNsourceCursorIcon
XmCSourceCursorIcon
Widget
dynamic
CSG
XmNsourcePixmapIcon
XmCSourcePixmapIcon
Widget
dynamic
CSG
XmNstateCursorIcon
XmCStateCursorIcon
Pixel
dynamic
CSG
XmNvalidCursorForeground
XmCCursorForeground
Pixel
dynamic
CSG
XmNblendModel
The combination of DragIcons that are blended to produce a drag-over visual.
Possible values:
XmBLEND_ALL
XmBLEND_STATE_SOURCE
XmBLEND_JUST_SOURCE
XmBLEND_NONE
/* source, state, and operation */
/* source and state
*/
/* source only
*/
/* no drag-over visual
*/
XmNclientData
The client data that is passed to the XmNconvertProc.
XmNconvertProc
A procedure of type XtConvertSelectionIncrProc that converts the data to the format(s) specified by the receiving client. The widget argument passed to this procedure is the DragContext widget and the selection atom is _MOTIF_DROP. If
XmNincremental is False, the conversion procedure should process the conversion atomically and ignore the max_length, client_data, and request_-id argu-
Motif Reference Manual
679
XmDragContext
Motif and Xt Widget Classes
ments. Allocate any data returned by XmNconvertProc using XtMalloc() and it
will be freed automatically by the toolkit after the transfer.
XmNcursorBackground
The background color of the cursor.
XmNcursorForeground
The foreground color of the cursor when the state icon is not blended. The default
value is the foreground color of the widget passed to XmDragStart().
XmNdragOperations
The valid operations for the drag. The value is a bit mask that is formed by combining one or more of these possible values:
XmDROP_COPY
XmDROP_LINK
XmDROP_MOVE
XmDROP_NOOP
/* copy operations are valid */
/* link operations are valid */
/* move operations are valid */
/* no operations are valid */
For Text and TextField widgets, the default value is XmDROP_COPY |
XmDROP_MOVE. For List widgets and Label and subclasses, the default is
XmDROP_COPY.
XmNexportTargets
The list of target atoms that the source data can be converted to.
XmNincremental
If True, the initiator uses the Xt incremental selection transfer mechanism. If
False (default), the initiator uses atomic transfer.
XmNinvalidCursorForeground
The foreground color of the cursor when the state is invalid. The default value is
the value of the XmNcursorForeground resource.
XmNnoneCursorForeground
The foreground color of the cursor when the state is none. The default value is
the value of the XmNcursorForeground resource.
XmNnumExportTargets
The number of atoms in the XmNexportTargets list.
XmNoperationCursorIcon
The drag icon used to show the type of drag operation being performed. If the
value is NULL, the default Screen icons are used.
XmNsourceCursorIcon
The drag icon used to represent the source data under the dynamic protocol. If the
value is NULL, the default Screen icon is used.
680
Motif Reference Manual
Motif and Xt Widget Classes
XmDragContext
XmNsourcePixmapIcon
The drag icon used to represent the source data under the preregister protocol. If
the value is NULL, XmNsourceCursorIcon is used.
XmNstateCursorIcon
The drag icon used to show the state of a drop site. If the value is NULL, the
default Screen icons are used.
XmNvalidCursorForeground
The foreground color of the cursor when the state is valid. The default value is
the value of the XmNcursorForeground resource.
Callback Resources
DragContext defines the following callback resources:
Callback
Reason Constant
XmNdragDropFinishCallback
XmCR_DRAG_DROP_FINISH
XmNdragMotionCallback
XmCR_DRAG_MOTION
XmNdropFinishCallback
XmCR_DROP_FINISH
XmNdropSiteEnterCallback
XmCR_DROP_SITE_ENTER
XmNdropSiteLeaveCallback
XmCR_DROP_SITE_LEAVE
XmNdropStartCallback
XmCR_DROP_START
XmNoperationChangedCallback
XmCR_OPERATION_CHANGED
XmNtopLevelEnterCallback
XmCR_TOP_LEVEL_ENTER
XmNtopLevelLeaveCallback
XmCR_TOP_LEVEL_LEAVE
XmNdragDropFinishCallback
List of callbacks that are called when the entire transaction is finished.
XmNdragMotionCallback
List of callbacks that are called when the pointer moves during a drag.
XmNdropFinishCallback
List of callbacks that are called when the drop is finished.
XmNdropSiteEnterCallback
List of callbacks that are called when the pointer enters a drop site.
XmNdropSiteLeaveCallback
List of callbacks that are called when the pointer leaves a drop site.
XmNdropStartCallback
List of callbacks that are called when a drop is started.
XmNoperationChangedCallback
List of callbacks that are called when the user changes the operation during a
drag.
Motif Reference Manual
681
XmDragContext
Motif and Xt Widget Classes
XmNtopLevelEnterCallback
List of callbacks that are called when the pointer enters a top-level window or
root window.
XmNtopLevelLeaveCallback
List of callbacks that are called when the pointer leaves a top-level window or the
root window.
Callback Structure
The XmNdragDropFinishCallback is passed the following structure:
typedef struct {
int
reason;
/* the reason the callback was called */
XEvent
*event;
/* event structure that triggered callback */
Time
timeStamp;
/* time at which operation completed
*/
} XmDragDropFinishCallbackStruct, *XmDragDropFinishCallback;
The XmNdragMotionCallback is passed the following structure:
typedef struct {
int
reason;
/* reason the callback was called */
XEvent
*event;
/* event that triggered callback */
Time
timeStamp;
/* timestamp of logical event */
unsigned char operation;
/* current operation
*/
unsigned char operations;
/* supported operations
*/
unsigned char dropSiteStatus;
/* valid, invalid, or none
*/
Position
x;
/* x-coordinate of pointer
*/
Position
y;
/* y-coordinate of pointer
*/
} XmDragMotionCallbackStruct, *XmDragMotionCallback;
The XmNdropFinishCallback is passed the following structure:
typedef struct {
int
reason;
/* reason the callback was called */
XEvent
*event;
/* event that triggered callback */
Time
timeStamp;
/* time at which drop completed */
unsigned char
operation;
/* current operation
*/
unsigned char
operations;
/* supported operations
*/
unsigned char
dropSiteStatus;
/* valid, invalid, or none
*/
unsigned char
dropAction;
/* drop, cancel, help, or interrupt */
unsigned char
completionStatus; /* success or failure
*/
} XmDropFinishCallbackStruct, *XmDropFinishCallback;
682
Motif Reference Manual
Motif and Xt Widget Classes
XmDragContext
The XmNdropSiteEnterCallback is passed the following structure:
typedef struct {
int
reason;
/* reason the callback was called */
XEvent
*event;
/* event that triggered callback */
Time
timeStamp;
/* time of crossing event
*/
unsigned char
operation;
/* current operation
*/
unsigned char
operations;
/* supported operations
*/
unsigned char
dropSiteStatus;
/* valid, invalid, or none
*/
Position
x;
/* x-coordinate of pointer
*/
Position
y;
/* y-coordinate of pointer
*/
} XmDropSiteEnterCallbackStruct, *XmDropSiteEnterCallback;
The XmNdropSiteLeaveCallback is passed the following structure:
typedef struct {
int
reason;
/* reason the callback was called */
XEvent
*event;
/* event that triggered callback */
Time
timeStamp;
/* time of crossing event
*/
} XmDropSiteLeaveCallbackStruct, *XmDropSiteLeaveCallback;
The XmNdropStartCallback is passed the following structure:
typedef struct {
int
reason;
/* reason the callback was called */
XEvent
*event;
/* event that triggered callback */
Time
timeStamp;
/* time at which drag completed */
unsigned char
operation;
/* current operation
*/
unsigned char
operations;
/* supported operations
*/
unsigned char
dropSiteStatus; /* valid, invalid, or none
*/
unsigned char
dropAction;
/* drop, cancel, help, or interrupt */
Position
x;
/* x-coordinate of pointer
*/
Position
y;
/* y-coordinate of pointer
*/
} XmDropStartCallbackStruct, *XmDropStartCallback;
The XmNoperationChangedCallback is passed the following structure:
typedef struct {
int
reason;
/* reason the callback was called */
XEvent
*event;
/* event that triggered callback */
Time
timeStamp;
/* timestamp of logical event */
unsigned char
operation;
/* current operation
*/
unsigned char
operations;
/* supported operations
*/
unsigned char
dropSiteStatus;
/* valid, invalid, or none
*/
} XmOperationChangedCallbackStruct, *XmOperationChangedCallback;
Motif Reference Manual
683
XmDragContext
Motif and Xt Widget Classes
The XmNtopLevelEnterCallback is passed the following structure:
typedef struct {
int
reason;
/* reason callback was called */
XEvent
*event;
/* event that triggered callback */
Time
timestamp;
/* timestamp of logical event */
Screen
screen;
/* screen of top-level window */
Window
window;
/* window being entered
*/
Position
x;
/* x-coordinate of pointer
*/
Position
y;
/* y-coordinate of pointer
*/
unsigned char
dragProtocolStyle;
/* drag protocol of initiator */
} XmTopLevelEnterCallbackStruct, *XmTopLevelEnterCallback;
The XmNtopLevelLeaveCallback is passed the following structure:
typedef struct {
int
reason;
/* reason the callback was called */
XEvent
*event;
/* event that triggered callback */
Time
timestamp;
/* timestamp of logical event */
Screen
screen;
/* screen of top-level window */
Window
window;
/* window being left
*/
} XmTopLevelLeaveCallbackStruct, *XmTopLevelLeaveCallback;
The operations field in these structures specifies the set of operations supported
for the data being dragged. The toolkit initializes the value based on the operations field of the XmDragProcCallbackStruct, the XmNdropSiteOperations
resource of the DropSite, the XmNdragOperations resource of the DragContext
and the operation selected by the user. The operation field in these structures
specifies the current operation. The toolkit initializes the value based on the value
of the operation field of the XmDragProcCallbackStruct, operations, and the
XmNdropSiteOperations resource of the Drop Site.
The dropSiteStatus field in these structures specifies whether or not the drop site
is valid. The toolkit initializes the value based on the XmNimportTargets
resource of the DropSite and the XmNexportTargets resource of the DragContext
and the location of the pointer. The possible values are
XmDROP_SITE_VALID, XmDROP_SITE_INVALID, and
XmNO_DROP_SITE.
684
Motif Reference Manual
Motif and Xt Widget Classes
XmDragContext
The dropAction field in these structures specifies the action associated with the
drop. The possible values are XmDROP, XmDROP_CANCEL,
XmDROP_INTERRUPT, and XmDROP_HELP1. XmDROP_INTERRUPT is
unsupported and is interpreted as XmDROP_CANCEL.
The completionStatus field in the XmDropFinishCallbackStruct specifies the status of the drop transaction, which determines the drop visual effect. The value of
this field can be changed by the XmNdropFinishCallbackStruct. The possible
values are XmDROP_SUCCESS2 and XmDROP_FAILURE3.
Inherited Resources
DragContext inherits the following resources. The resources are listed alphabetically, along with the superclass that defines them. DragContext sets the default
value of XmNborderWidth to 0.
Name
Inherited From
Name
Inherited From
XmNaccelerators
Core
XmNheight
Core
XmNancestorSensitive
Core
XmNinitialResourcesPersistent
Core
XmNbackground
Core
XmNmappedWhenManaged
Core
XmNbackgroundPixmap
Core
XmNscreen
Core
XmNborderColor
Core
XmNsensitive
Core
XmNborderPixmap
Core
XmNtranslations
Core
XmNborderWidth
Core
XmNwidth
Core
XmNcolormap
Core
XmNx
Core
XmNdepth
Core
XmNy
Core
XmNdestroyCallback
Core
1.Erroneously given as DROP_HELP in 1st and 2nd edition.
2.Erroneously given as XmSUCCESS in 1st and 2nd edition.
3.Erroneously given as XmFAILURE in 1st and 2nd edition.
Motif Reference Manual
685
XmDragContext
Motif and Xt Widget Classes
Translations
Event
Action
BDrag Motion
DragMotion()
BDrag Release
FinishDrag()
KCancel
CancelDrag()
KHelp
HelpDrag()
Action Routines
DragContext defines the following action routines:
CancelDrag()
Cancels the drag operation and frees the associated DragContext.
DragMotion()
Drags the selected data as the pointer is moved.
FinishDrag()
Completes the drag operation and initiates the drop operation.
HelpDrag()
Starts a conditional drop that allows the receiving client to provide
help information to the user. The user can cancel or continue the
drop operation in response to this information.
See Also
XmDragCancel(1), XmDragStart(1), XmGetDragContext(1), Core(2),
XmDisplay(2), XmDragIcon(2), XmDropSite(2), XmDropTransfer(2),
XmScreen(2).
686
Motif Reference Manual
Motif and Xt Widget Classes
XmDragIcon
Name
XmDragIcon widget class – an object used to represent the data in a drag and
drop operation.
Synopsis
Public Header:
<Xm/DragDrop.h>
Class Name:
XmDragIcon
Class Pointer:
xmDragIconObjectClass
Class Hierarchy:
Object → DragIcon
Instantiation:
widget = XmCreateDragIcon(...)
Functions/Macros:
XmCreateDragIcon(), XmIsDragIconObjectClass()
Availability
Motif 1.2 and later.
Description
A DragIcon is an object that represents the source data in a drag and drop transaction. During a drag operation, the cursor changes into a visual that is created by
combining the various DragIcons specified in the DragContext associated with
the operation. A DragIcon is created using the XmCreateDragIcon() function
or from entries in the resource database.
A drag-over visual can have both a static and a dynamic part. The static part of
the visual is the DragIcon that represents the source data. The dynamic parts can
be DragIcons that change to indicate the type of operation that is being performed and whether the pointer is over a valid or an invalid drop site. The XmNblendModel resource of the DragContext for a drag and drop operation specifies
which icons are blended to produce the drag-over visual. DragIcon resources
specify the relative positions of the operation and state icons if they are used.
When a DragIcon is not specified, the default DragIcons from the appropriate
Screen object are used.
Motif Reference Manual
687
XmDragIcon
Motif and Xt Widget Classes
New Resources
DragIcon defines the following resources:
Name
Class
Type
Default
Access
XmNattachment
XmCAttachment
XmNdepth
XmCDepth
unsigned char
XmATTACH_NORTH_WEST
CSG
int
1
CSG
XmNheight
XmNhotX
XmCHeight
Dimension
0
CSG
XmCHot
Position
0
CSG
XmNhotY
XmCHot
Position
0
CSG
XmNmask
XmCPixmap
Pixmap
XmUNSPECIFIED_PIXMAP
CSG
XmNoffsetX
XmCOffset
Position
0
CSG
XmNoffsetY
XmCOffset
Position
0
CSG
XmNpixmap
XmCPixmap
Pixmap
XmUNSPECIFIED_PIXMAP
CSG
XmNwidth
XmCWidth
Dimension
0
CSG
XmNattachment
The relative location on the source icon where the state or operation icon is
attached. Possible values:
XmATTACH_NORTH_WEST
XmATTACH_NORTH_EAST
XmATTACH_SOUTH_EAST
XmATTACH_SOUTH_WEST
XmATTACH_CENTER
XmATTACH_NORTH
XmATTACH_EAST
XmATTACH_SOUTH
XmATTACH_WEST
XmATTACH_HOT
XmNdepth
The depth of the pixmap.
XmNheight
The height of the pixmap.
XmNhotX
The x-coordinate of the hotspot of the cursor.
XmNhotY
The y-coordinate of the hotspot of the cursor.
XmNmask
The mask for the DragIcon pixmap.
XmNoffsetX
The horizontal offset in pixels of the origin of the state or operation icon relative
to the attachment point on the source icon.
688
Motif Reference Manual
Motif and Xt Widget Classes
XmDragIcon
XmNoffsetY
The vertical offset in pixels of the origin of the state or operation icon relative to
the attachment point on the source icon.
XmNpixmap
The pixmap for the DragIcon.
XmNwidth
The width of the pixmap.
Inherited Resources
DragIcon inherits the following resource:
Resource
Inherited From
XmNdestroyCallback
Object
See Also
XmCreateObject(1), Object(2), XmDisplay(2), XmDragContext(2),
XmDropSite(2), XmDropTransfer(2), XmScreen(2).
Motif Reference Manual
689
XmDrawingArea
Motif and Xt Widget Classes
Name
XmDrawingArea widget class – a simple manager widget for interactive drawing.
Synopsis
Public Header:
<Xm/DrawingA.h>
Class Name:
XmDrawingArea
Class Hierarchy:
Core → Composite → Constraint → XmManager → XmDrawingArea
Class Pointer:
xmDrawingAreaWidgetClass
Instantiation:
widget = XmCreateDrawingArea (parent, name,...)
or
widget = XtCreateWidget (name, xmDrawingAreaWidgetClass,...)
Functions/Macros:
XmCreateDrawingArea(), XmIsDrawingArea()
Description
DrawingArea provides a blank canvas for interactive drawing. The widget does
not do any drawing of its own. Since DrawingArea is a subclass of Manager, it
can provide simple geometry management of multiple widget or gadget children.
The widget does not define any behavior except for invoking callbacks that notify
an application when it receives input events, exposure events, and resize events.
New Resources
DrawingArea defines the following resources:
Name
Class
Type
Default
Access
XmNmarginHeight
XmCMarginHeight
Dimension
10
CSG
XmNmarginWidth
XmCMarginWidth
Dimension
10
CSG
XmNresizePolicy
XmCResizePolicy
unsigned char
XmRESIZE_ANY
CSG
XmNmarginHeight
The spacing between a DrawingArea’s top or bottom edge and any child widget.
XmNmarginWidth
The spacing between a DrawingArea’s right or left edge and any child widget.
690
Motif Reference Manual
Motif and Xt Widget Classes
XmDrawingArea
XmNresizePolicy
How DrawingArea widgets are resized. Possible values:
XmRESIZE_NONE
XmRESIZE_GROW
XmRESIZE_ANY
/* remain at fixed size
*/
/* expand only
*/
/* shrink or expand, as needed */
Callback Resources
DrawingArea defines the following callback resources:
Callback
Reason Constant
XmNconvertCallback
XmCR_OK
XmNdestinationCallback
XmCR_OK
XmNexposeCallback
XmCR_EXPOSE
XmNinputCallback
XmCR_INPUT
XmNresizeCallback
XmCR_RESIZE
XmNconvertCallback
In Motif 2.0 and later, specifies the list of callbacks called when a request is made
to convert a selection.
XmNdestinationCallback
In Motif 2.0 and later, specifies the list of callbacks called when the DrawingArea
is the destination of a data transfer.
XmNexposeCallback
List of callbacks that are called when the DrawingArea receives an exposure
event.
XmNinputCallback
List of callbacks that are called when the DrawingArea receives a keyboard or
mouse event.
XmNresizeCallback
List of callbacks that are called when the DrawingArea receives a resize event.
Callback Structure
Each expose, resize, and input callback function is passed the following structure:
typedef struct {
int
reason;
/* the reason that the callback was called */
XEvent
*event;
/* event structure that triggered callback; */
/* for XmNresizeCallback, this is NULL */
Window
window;
/* the widget’s window
*/
} XmDrawingAreaCallbackStruct;
Motif Reference Manual
691
XmDrawingArea
Motif and Xt Widget Classes
Convert callbacks are fully described within the sections covering the Uniform
Transfer Model. See XmTransfer(1) for more details. For quick reference, a
pointer to the following structure is passed to callbacks on the XmNconvertCallback list:
typedef struct {
int
reason;
/* reason that the callback is invoked
*/
XEvent
*event;
/* points to event that triggered callback */
Atom
selection;
/* requested conversion selection
*/
Atom
target;
/* the conversion target
*/
XtPointer source_data; /* selection source information
*/
XtPointer location_data; /* information about data to be transferred*/
int
flags;
/* input status of the conversion
*/
XtPointer parm;
/* parameter data for the target
*/
int
parm_format; /* format of parameter data
*/
unsigned long parm_length; /* number of elements in
*/
/*
parameter data
*/
Atom
parm_type;
/* the type of the parameter data
*/
int
status;
/* output status of the conversion
*/
XtPointer value;
/* returned conversion data
*/
Atom
type;
/* type of conversion data returned
*/
int
format;
/* format of the conversion data
*/
unsigned long length;
/* number of elements in conversion data */
} XmConvertCallbackStruct;
Destination callbacks are fully described within the sections covering the Uniform Transfer Model. See XmTransfer(1) for more details. For quick reference, a pointer to the following structure is passed to callbacks on the
XmNdestinationCallback list:
typedef struct {
int
reason;
/* reason that the callback is invoked
*/
XEvent
*event;
/* points to event that triggered callback */
Atom
selection;
/* the requested selection type, as an Atom */
XtEnum
operation;
/* the type of transfer requested
*/
int
flags;
/* whether destination and source are same */
XtPointer transfer_id; /* unique identifier for the request
*/
XtPointer destination_data; /* information about the destination */
XtPointer location_data; /* information about the data
*/
Time
time;
/* the time when transfer operation started */
} XmDestinationCallbackStruct;
692
Motif Reference Manual
Motif and Xt Widget Classes
XmDrawingArea
Inherited Resources
DrawingArea inherits the following resources. The resources are listed alphabetically, along with the superclass that defines them. The default value of XmNborderWidth is reset to 0 by Manager.
Resource
Inherited From Resource
Inherited From
XmNaccelerators
Core
XmNinsertPosition
Composite
XmNancestorSensitive
Core
XmNlayoutDirection
XmManager
XmNbackground
Core
XmNmappedWhenManaged Core
XmNbackgroundPixmap
Core
XmNnavigationType
XmManager
XmNborderColor
Core
XmNnumChildren
Composite
XmNborderPixmap
Core
XmNpopupHandlerCallback XmManager
XmNborderWidth
Core
XmNscreen
Core
XmNbottomShadowColor
XmManager
XmNsensitive
Core
XmNbottomShadowPixmap
XmManager
XmNshadowThickness
XmManager
XmNchildren
Composite
XmNstringDirection
XmManager
XmNcolormap
Core
XmNtopShadowColor
XmManager
XmNdepth
Core
XmNtopShadowPixmap
XmManager
XmNdestroyCallback
Core
XmNtranslations
Core
XmNforeground
XmManager
XmNtraversalOn
XmManager
XmNheight
Core
XmNunitType
XmManager
XmNhelpCallback
XmManager
XmNuserData
XmManager
XmNhighlightColor
XmManager
XmNwidth
Core
XmNhighlightPixmap
XmManager
XmNx
Core
XmNinitialFocus
XmManager
XmNy
Core
XmNinitialResourcesPersistent Core
Translations
The translations for DrawingArea include those of Manager. All of the events in
the inherited translations except <BtnMotion>, <EnterWindow>, <LeaveWindow>, <FocusIn>, and <FocusOut> call the DrawingAreaInput() action before
calling the Manager actions.
Motif Reference Manual
693
XmDrawingArea
Motif and Xt Widget Classes
DrawingArea has the following additional translations:
Event
Action
MAny Bany Press
DrawingAreaInput()
MAny Bany Release
DrawingAreaInput()
Many KAny Press
DrawingAreaInput()
ManagerGadgetKeyInput()
MAny KAny Release
DrawingAreaInput()
Action Routines
DrawingArea defines the following action routines:
DrawingAreaInput()
When a widget child of a DrawingArea receives a keyboard or
mouse event, this action routine invokes the list of callbacks specified by XmNinputCallback.
ManagerGadgetKeyInput()
When a gadget child of a DrawingArea receives a keyboard or
mouse event, this action routine processes the event.
Additional Behavior
DrawingArea has the following additional behavior:
<Expose>
Invokes the XmNexposeCallback callbacks.
<WidgetResize>
Invokes the XmNresizeCallback callbacks.
See Also
XmCreateObject(1), XmTransfer(1), Composite(2), Constraint(2),
Core(2), XmManager(2).
694
Motif Reference Manual
Motif and Xt Widget Classes
XmDrawnButton
Name
XmDrawnButton widget class – a button widget that provides a graphics area.
Synopsis
Public Header:
<Xm/DrawnB.h>
Class Name:
XmDrawnButton
Class Hierarchy:
XmPrimitive → XmLabel → XmDrawnButton
Class Pointer:
xmDrawnButtonWidgetClass
Instantiation:
widget = XmCreateDrawnButton (parent, name,...)
or
widget = XtCreateWidget (name, xmDrawnButtonWidgetClass,...)
Functions/Macros:
XmCreateDrawnButton(), XmIsDrawnButton()
Description
DrawnButton is an empty widget window, surrounded by a shaded border. The
widget provides a graphics area that can act like a PushButton. The graphics can
be dynamically updated by the application.
Traits
DrawnButton holds the XmQTactivatable trait, which is inherited by any derived
classes, and uses the XmQTmenuSystem and XmQTspecifyRenderTable traits.
New Resources
DrawnButton defines the following resources:
Name
Class
Type
XmNmultiClick
XmCMultiClick
unsigned char dynamic
XmNpushButtonEnabled XmCPushButtonEnabled Boolean
XmNshadowType
XmCShadowType
Default
False
Access
CSG
CSG
unsigned char XmSHADOW_ETCHED_IN CSG
XmNmultiClick
A flag that determines whether successive button clicks are processed or ignored.
Possible values:
XmMULTICLICK_DISCARD
Motif Reference Manual
/* ignore successive button clicks; */
/* default value in a menu system */
695
XmDrawnButton
Motif and Xt Widget Classes
XmMULTICLICK_KEEP
/* count successive button clicks; */
/* default value when not in a menu */
XmNpushButtonEnabled
If False (default), the shadow drawing doesn’t appear three dimensional; if True,
the shading provides a pushed in or raised appearance as for the PushButton
widget.
XmNshadowType
The style in which shadows are drawn. Possible values:
XmSHADOW_IN
XmSHADOW_OUT
XmSHADOW_ETCHED_IN
XmSHADOW_ETCHED_OUT
*/
/* widget appears inset
/* widget appears outset
*/
/* double line; widget appears inset */
/* double line; widget appears raised */
Callback Resources
DrawnButton defines the following callback resources:
Callback
Reason Constant
XmNactivateCallback
XmCR_ACTIVATE
XmNarmCallback
XmCR_ARM
XmNdisarmCallback
XmCR_DISARM
XmNexposeCallback
XmCR_EXPOSE
XmNresizeCallback
XmCR_RESIZE
XmNactivateCallback
List of callbacks that are called when BSelect is pressed and released inside of
the widget.
XmNarmCallback
List of callbacks that are called when BSelect is pressed while the pointer is
inside the widget.
XmNdisarmCallback
List of callbacks that are called when BSelect is released after it has been pressed
inside of the widget.
XmNexposeCallback
List of callbacks that are called when the widget receives an exposure event.
XmNresizeCallback
List of callbacks that are called when the widget receives a resize event.
696
Motif Reference Manual
Motif and Xt Widget Classes
XmDrawnButton
Callback Structure
Each callback function is passed the following structure:
typedef struct {
int
reason;
/* the reason that the callback was called */
XEvent
*event;
/* event structure that triggered callback */
Window
window;
/* ID of window in which the event occurred */
int
click_count; /* number of multi-clicks
*/
} XmDrawnButtonCallbackStruct;
event is NULL for XmNresizeCallback and is sometimes NULL for XmNactivateCallback.
click_count is meaningful only for XmNactivateCallback. Furthermore, if the
XmNmultiClick resource has the value XmMULTICLICK_KEEP, then XmNactivateCallback is called for each click, and the value of click_count is the number
of clicks that have occurred in the last sequence of multiple clicks. If the XmNmultiClick resource is set to XmMULTICLICK_DISCARD, then click_count
always has a value of 1.
Inherited Resources
DrawnButton inherits the following resources. The resources are listed alphabetically, along with the superclass that defines them. DrawnButton sets default value
of XmNlabelString to XmUNSPECIFIED1. The default value of XmNborderWidth is reset to 0 by Primitive. In Motif 2.0 and earlier, the default value of
XmNhighlightThickness and XmNshadowThickness are reset to 2. In Motif 2.1
and later, the default values depend upon the XmDisplay XmNenableThinThickness resource: if True, the default is 1, otherwise 2.
Resource
Inherited From Resource
Inherited From
XmNaccelerator
XmLabel
XmNlabelType
XmLabel
XmNaccelerators
Core
XmNlayoutDirection
XmPrimitive
XmNacceleratorText
XmLabel
XmNmappedWhenManaged Core
XmNalignment
XmLabel
XmNmarginBottom
XmLabel
XmNancestorSensitive
Core
XmNmarginHeight
XmLabel
XmNbackground
Core
XmNmarginLeft
XmLabel
XmNbackgroundPixmap
Core
XmNmarginRight
XmLabel
XmNborderColor
Core
XmNmarginTop
XmLabel
1.Given as “” in 1st and 2nd editions. This is imprecise. The XmLabel superclass treats XmUNSPECIFIED as a special
value, which maps to an empty XmString.
Motif Reference Manual
697
XmDrawnButton
Motif and Xt Widget Classes
Resource
Inherited From Resource
Inherited From
XmNborderPixmap
Core
XmNmarginWidth
XmLabel
XmNborderWidth
Core
XmNmnemonicCharSet
XmLabel
XmNbottomShadowColor
XmPrimitive
XmNmnemonic
XmLabel
XmNbottomShadowPixmap
XmPrimitive
XmNnavigationType
XmPrimitive
XmNcolormap
Core
XmNpopupHandlerCallback XmPrimitive
XmNconvertCallback
XmPrimitive
XmNrecomputeSize
XmLabel
XmNdepth
Core
XmNrenderTable
XmLabel
XmNdestroyCallback
Core
XmNscreen
Core
XmNfontList
XmLabel
XmNsensitive
Core
XmNforeground
XmPrimitive
XmNshadowThickness
XmPrimitive
XmNheight
Core
XmNstringDirection
XmLabel
XmNhelpCallback
XmPrimitive
XmNtopShadowColor
XmPrimitive
XmNhighlightColor
XmPrimitive
XmNtopShadowPixmap
XmPrimitive
XmNhighlightOnEnter
XmPrimitive
XmNtranslations
Core
XmNhighlightPixmap
XmPrimitive
XmNtraversalOn
XmPrimitive
XmNhighlightThickness
XmPrimitive
XmNunitType
XmPrimitive
XmNinitialResourcesPersistent Core
XmNuserData
XmPrimitive
XmNlabelInsensitivePixmap
XmLabel
XmNwidth
Core
XmNlabelPixmap
XmLabel
XmNx
Core
XmNlabelString
XmLabel
XmNy
Core
Translations
698
Event
Action
BSelect Press
Arm()
MCtrl BSelect Press
ButtonTakeFocus()
BSelect Click
Activate()
Disarm()
BSelect Release
Activate()
Disarm()
BSelect Press 2+
MultiArm()
BSelect Release 2+
MultiActivate()
KSelect
ArmAndActivate()
KHelp
Help()
Motif Reference Manual
Motif and Xt Widget Classes
XmDrawnButton
Action Routines
DrawnButton defines the following action routines:
Activate()
Displays the DrawnButton as unselected if XmNpushButtonEnabled is True or displays the shadow according to XmNshadowType.
Invokes the list of callbacks specified by XmNactivateCallback.
Arm()
Displays the DrawnButton as selected if XmNpushButtonEnabled
is True or displays the shadow according to XmNshadowType.
Invokes the list of callbacks specified by XmNarmCallback.
ArmAndActivate()
Displays the DrawnButton as selected if XmNpushButtonEnabled
is True or displays the shadow according to XmNshadowType.
Invokes the list of callbacks specified by XmNarmCallback. After
doing this, the action routine displays the DrawnButton as unselected if XmNpushButtonEnabled is True or displays the shadow
according to XmNshadowType and invokes the list of callbacks
specified by XmNactivateCallback and XmNdisarmCallback.
ButtonTakeFocus()
In Motif 2.0 and later, moves the current keyboard focus to the
DrawnButton, without activating the widget.
Disarm()
Displays the DrawnButton as unselected and invokes the list of callbacks specified by XmNdisarmCallback.
Help()
Invokes the list of callbacks specified by XmNhelpCallback. If the
DrawnButton doesn’t have any help callbacks, the Help() routine
invokes those associated with the nearest ancestor that has them.
MultiActivate()
Increments the click_count member of XmDrawnButtonCallbackStruct, displays the DrawnButton as unselected if XmNpushButtonEnabled is True or displays the shadow according to
XmNshadowType, and invokes the list of callbacks specified by
XmNactivateCallback and XmNdisarmCallback. This action routine takes effect only when the XmNmultiClick resource is set to
XmMULTICLICK_KEEP.
MultiArm()
Displays the DrawnButton as selected if XmNpushButtonEnabled
is True or displays the shadow according to XmNshadowType, and
invokes the list of callbacks specified by XmNarmCallback. This
action routine takes effect only when the XmNmultiClick resource
is set to XmMULTICLICK_KEEP.
Motif Reference Manual
699
XmDrawnButton
Motif and Xt Widget Classes
Additional Behavior
DrawnButton has the following additional behavior:
<EnterWindow>
Displays the DrawnButton as selected if XmNpushButtonEnabled
is True and the pointer leaves and re-enters the window while BSelect is pressed.
<LeaveWindow>
Displays the DrawnButton as unselected if XmNpushButtonEnabled is True and the pointer leaves the window while BSelect is
pressed.
See Also
XmCreateObject(1), Core(2), XmLabel(2), XmPrimitive(2),
XmPushButton(2).
700
Motif Reference Manual
Motif and Xt Widget Classes
XmDropSite
Name
XmDropSite registry – an object that defines the characteristics of a drop site.
Synopsis
Public Header:
<Xm/DragDrop.h>
Class Hierarchy:
DropSite does not inherit from any widget class.
Instantiation:
XmDropSiteRegister(...)
Functions/Macros:
XmDropSiteConfigureStackingOrder(), XmDropSiteEndUpdate(),
XmDropSiteQueryStackingOrder(), XmDropSiteRegister(),
XmDropSiteRetrieve(), XmDropSiteStartUpdate(),
XmDropSiteUpdate(), XmDropSiteUnregister()
Availability
Motif 1.2 and later.
Description
An XmDropSite is an object that stores data about a drop site for drag and drop
operations. A DropSite is associated with a particular widget or gadget in an
application. An application registers a widget or gadget as a DropSite using
XmDropSiteRegister(). The DropSite stores information about the shape of
the drop site, the animation effects used when the pointer enters the drop site, the
types of data supported by the drop site, and the callback that is activated when a
drop occurs. These characteristics can be specified as resources when the DropSite is created.
The functions XmDropSiteUpdate() and XmDropSiteRetrieve() set and
get the drop site resources for a widget that is registered as a DropSite. Use these
routines instead of XtSetValues() and XtGetValues().
New Resources
DropSite defines the following resources:
Name
Class
Type
Default
Access
XmNanimationMask
XmCAnimationMask
Pixmap
XmUNSPECIFIED_PIXMAP
CSG
XmNanimationPixmap
XmCAnimationPixmap
Pixmap
XmUNSPECIFIED_PIXMAP
CSG
0
CSG
XmNanimationPixmapDepth XmCAnimationPixmapDepth int
XmNanimationStyle
XmCAnimationStyle
Motif Reference Manual
unsigned char XmDRAG_UNDER_HIGHLIGHT CSG
701
XmDropSite
Motif and Xt Widget Classes
Name
Class
Type
Default
Access
XmNdropRectangles
XmCDropRectangles
XRectangle * dynamic
CSG
XmNdropSiteActivity
XmCDropSiteActivity
unsigned char XmDROP_SITE_ACTIVE
CSG
XmNdropSiteOperations
XmCDropSiteOperations
unsigned char XmDROP_MOVE |
XmDROP_COPY
CSG
XmNdropSiteType
XmCDropSiteType
unsigned char XmDROP_SITE_SIMPLE
CG
XmNimportTargets
XmCImportTargets
Atom *
NULL
CSG
XmNnumDropRectangles
XmCNumDropRectangles
Cardinal
1
CSG
XmNnumImportTargets
XmCNumImportTargets
Cardinal
0
CSG
XmNanimationMask
The mask for the XmNanimationPixmap when the animation style is
XmDRAG_UNDER_PIXMAP.
XmNanimationPixmap
The pixmap used for drag-under animation when the animation style is
XmDRAG_UNDER_PIXMAP.
XmNanimationPixmapDepth
The depth of the pixmap specified by XmNanimationPixmap.
XmNanimationStyle
The style of drag-under animation used when the pointer enters a valid drop site
during a drag operation. Possible values:
XmDRAG_UNDER_HIGHLIGHT
/* drop site highlighted
*/
XmDRAG_UNDER_SHADOW_OUT /* drop site shown with outset shadow */
XmDRAG_UNDER_SHADOW_IN
/* drop site shown with inset shadow */
XmDRAG_UNDER_PIXMAP
/* drop site displays pixmap
XmDRAG_UNDER_NONE
*/
/* no animation effects unless in XmNdragProc */
XmNdropRectangles
A list of rectangles that specify the shape of the drop site. When the value is
NULL, the drop site is the entire widget.
XmNdropSiteActivity
Specifies the state of the drop site. Possible values:
XmDROP_SITE_ACTIVE
XmDROP_SITE_INACTIVE
/* participates in drop operations */
/* does not participate in drop operations */
XmNdropSiteOperations
The valid operations for a drop site. The value is a bit mask that is formed by
combining one or more of these possible values:
702
Motif Reference Manual
Motif and Xt Widget Classes
XmDropSite
XmDROP_COPY
XmDROP_LINK
XmDROP_MOVE
XmDROP_NOOP
/* copy operations are valid */
/* link operations are valid */
/* move operations are valid */
/* no operations are valid */
XmNdropSiteType
The type of the drop site. Possible values:
XmDROP_SITE_SIMPLE
XmDROP_SITE_COMPOSITE
/* no children are registered as drop sites */
/* has children registered as drop sites */
XmNimportTargets
The list of target atoms that the drop site accepts.
XmNnumDropRectangles
The number of rectangles in the XmNdropRectangles list.
XmNnumImportTargets
The number of atoms in the XmNimportTargets list.
Callback Resources
DropSite defines the following callback resources:
Callback
Reason Constant
XmNdragProc
XmCR_DROP_SITE_ENTER_MESSAGE
XmCR_DROP_SITE_LEAVE_MESSAGE
XmCR_DROP_SITE_MOTION_MESSAGE
XmCR_OPERATION_CHANGED_MESSAGE
XmNdropProc
XmCR_DROP_MESSAGE
XmNdragProc
The procedure that is called when the drop site receives a crossing, motion, or
operation changed message under the dynamic protocol. The reason passed to the
procedure depends on the type of message that is received.
XmNdropProc
The procedure that is called when a drop operation occurs on the drop site.
Callback Structure
The XmNdragProc is passed the following structure:
typedef struct {
int
XEvent
Time
Widget
Position
Position
Motif Reference Manual
reason;
*event;
timeStamp;
dragContext;
x;
y;
/* reason the callback was called
*/
/* event that triggered callback
*/
/* timestamp of logical event
*/
/* DragContext associated with operation */
/* x-coordinate of pointer
*/
/* y-coordinate of pointer
*/
703
XmDropSite
Motif and Xt Widget Classes
unsigned char dropSiteStatus; /* valid or invalid
*/
unsigned char operation;
/* current operation
*/
unsigned char operations;
/* supported operations
*/
Boolean
animate;
/* toolkit or receiver does animation */
} XmDragProcCallbackStruct, *XmDragProcCallback;
The XmNdragProc can change the value of the dropSiteStatus, operation, and
operations fields in this structure. When the drag procedure completes, the
toolkit uses the resulting values to initialize the corresponding fields in the callback structure passed to the initiating client’s callbacks.
The XmNdropProc is passed the following structure:
typedef struct {
*/
int
reason;
/* reason the callback was called
XEvent
*event;
/* event that triggered callback
*/
Time
timeStamp;
/* timestamp of logical event
*/
Widget
dragContext;
/* DragContext associated with operation */
Position
x;
/* x-coordinate of pointer
*/
Position
y;
/* y-coordinate of pointer
*/
unsigned char dropSiteStatus; /* valid or invalid
*/
unsigned char operation;
/* current operation
*/
unsigned char operations;
/* supported operations
*/
unsigned char dropAction;
/* drop or help
*/
} XmDropProcCallbackStruct, *XmDropProcCallback;
The XmNdropProc can change the value of the dropSiteStatus, operation, operations, and dropAction fields in this structure. When the drop procedure completes, the toolkit uses the resulting values to initialize the corresponding fields in
the XmDropProcCallbackStruct callback structure passed to the initiating client’s
drop start callbacks.
The dropSiteStatus field in these structures specifies whether or not the drop site
is valid. The toolkit initializes the value based on the XmNimportTargets
resource of the DropSite and the XmNexportTargets resource of the DragContext. The possible values are XmDROP_SITE_VALID and
XmDROP_SITE_INVALID.
The operations field in these structure specifies the set of operations supported
for the data being dragged. The toolkit initializes the value based on the XmNdragOperations resource of the DragContext and the operation selected by the
user. The operation field in these structures specifies the current operation. The
toolkit initializes the value based on the value of operations and the XmNdropSiteOperations resource.
704
Motif Reference Manual
Motif and Xt Widget Classes
XmDropSite
The animate field in the XmDragProcCallbackStruct specifies whether the toolkit
or the receiving client handles the drag-under effects for the drop site. If the value
is True, the toolkit handles the effects based on the XmNanimationStyle
resource. Otherwise the receiver is responsible for providing drag-under effects.
The dropAction field in the XmDropProcCallbackStruct specifies the action
associated with the drop, which is either a normal drop or a help action. The possible values are XmDROP and XmDROP_HELP.
See Also
XmDropSiteConfigureStackingOrder(1),
XmDropSiteEndUpdate(1), XmDropSiteQueryStackingOrder(1),
XmDropSiteRegister(1), XmDropSiteRetrieve(1),
XmDropSiteStartUpdate(1), XmDropSiteUnregister(1),
XmDropSiteUpdate(1), XmDisplay(1), XmDragContext(1),
XmDragIcon(2), XmDropTransfer(2), XmScreen(2).
Motif Reference Manual
705
XmDropTransfer
Motif and Xt Widget Classes
Name
XmDropTransfer widget class – an object used to store information about a drop
transaction.
Synopsis
Public Header:
<Xm/DragDrop.h>
Class Name:
XmDropTransfer
Class Pointer:
xmDropTransferObjectClass
Class Hierarchy:
Object → DropTransfer
Instantiation:
widget = XmDropTransferStart(...)
Functions/Macros:
XmDropTransferAdd(), XmDropTransferStart()
Availability
Motif 1.2 and later.
Description
The XmDropTransfer object stores information that the toolkit needs to process a
drop transaction. An application does not explicitly create a DropTransfer
widget, but instead initiates a data transfer by calling XmDropTransferStart(), which initializes and returns a DropTransfer widget. If XmDropTransferStart() is called within an XmNdropProc, the data transfer starts
after the callback returns. If no data needs to be transferred or the drop transaction is a failure, an application still needs to call XmDropTransferStart()
with a failure status, so that the toolkit can complete the drag and drop operation.
The XmNtransferProc resource specifies a procedure of type XtSelectionCallbackProc that handles transferring the requested selection data. This procedure
performs in conjunction with the underlying Xt selection mechanisms and is
called for each type of data being transferred. Target types can be added after a
transfer has started by calling the XmDropTransferAdd().
706
Motif Reference Manual
Motif and Xt Widget Classes
XmDropTransfer
New Resources
DropTransfer defines the following resources:
Name
Class
Type
Default
Access
XmNdropTransfers
XmCDropTransfers
XmDropTransferEntryRec * NULL
CG
XmNincremental
XmCIncremental
Boolean
False
CSG
XmNnumDropTransfers XmCNumDropTransfers Cardinal
0
CSG
XmNtransferProc
XmCTransferProc
XtSelectionCallbackProc
NULL
CSG
XmNtransferStatus
XmCTransferStatus
unsigned char
XmTRANSFER_SUCCESS CSG
XmNdropTransfers
Pointer to an array of XmDropTransferEntryRec structures, which specifies the
requested target data types for the source data. A XmDropTransferEntryRec is
defined as follows:
typedef struct {
XtPointer
client_data;
/* any additional information necessary */
Atom
target;
/* the selection target type
*/
} XmDropTransferEntryRec, *XmDropTransferEntry;
The drop transfer is done when all of the entries have been processed.
XmNincremental
If True, the receiver uses the Xt incremental selection transfer mechanism. If
False (default), the receiver uses atomic transfer.
XmNnumDropTransfers
The number of entries in XmNdropTransfers. The transfer is complete if the
value is set to 0 at any time.
XmNtransferProc
A procedure of type XtSelectionCallbackProc that provides the requested selection values. The widget argument passed to this procedure is the DropTransfer
widget and the selection atom is _MOTIF_DROP.
XmNtransferStatus
The current status of the drop transfer. The receiving client updates this value
when the transfer ends and the value is communicated to the initiator. Possible
values:
XmTRANSFER_SUCCESS
Motif Reference Manual
XmTRANSFER_FAILURE
707
XmDropTransfer
Motif and Xt Widget Classes
Inherited Resources
DropTransfer inherits the following resource:
Resource
Inherited From
XmNdestroyCallback
Object
See Also
XmDropTransferAdd(1), XmDropTransferStart(1),
XmTargetsAreCompatible(1), Object(2), XmDisplay(2),
XmDragContext(2), XmDragIcon(2), XmDropTransfer(2),
XmScreen(2).
708
Motif Reference Manual
Motif and Xt Widget Classes
XmErrorDialog
Name
XmErrorDialog – an unmanaged MessageBox as a child of a DialogShell.
Synopsis
Public Header:
<Xm/MessageB.h>
Instantiation:
widget = XmCreateErrorDialog(...)
Functions/Macros:
XmCreateErrorDialog(), XmMessageBoxGetChild()
Description
An XmErrorDialog is a compound object created by a call to XmCreateErrorDialog() that an application can use to inform the user about any type of error. An
ErrorDialog consists of a DialogShell with an unmanaged MessageBox widget as
its child. The MessageBox resource XmNdialogType is set to
XmDIALOG_ERROR. An ErrorDialog includes four components: a symbol, a
message, three buttons, and a separator between the message and the buttons. By
default, the symbol is an octagon with a diagonal slash. In Motif 1.2, the default
button labels can be localized. In the C locale, and in Motif 1.1, the PushButtons
are labelled OK, Cancel, and Help by default.
Default Resource Values
An ErrorDialog sets the following default values for MessageBox resources:
Name
Default
XmNdialogType
XmDIALOG_ERROR
XmNsymbolPixmap
xm_error
Widget Hierarchy
When an ErrorDialog is created with a specified name, the DialogShell is named
name_popup and the MessageBox is called name.
See Also
XmCreateObject(1), XmMessageBoxGetChild(1),
XmDialogShell(2), XmMessageBox(2).
Motif Reference Manual
709
XmFileSelectionBox
Motif and Xt Widget Classes
Name
XmFileSelectionBox widget class – a widget for selecting files.
Synopsis
Public Header:
<Xm/FileSB.h>
Class Name:
XmFileSelectionBox
Class Hierarchy:
Core → Composite → Constraint → XmManager → XmBulletinBoard →
XmSelectionBox → XmFileSelectionBox
Class Pointer:
xmFileSelectionBoxWidgetClass
Instantiation:
widget = XmCreateFileSelectionBox (parent, name,...)
or
widget = XtCreateWidget (name, xmFileSelectionBoxWidgetClass,...)
Functions/Macros:
XmCreateFileSelectionBox(), XmCreateFileSelectionDialog(),
XmFileSelectionBoxGetChild(), XmFileSelectionDoSearch(),
XmIsFileSelectionBox()
Description
FileSelectionBox is a composite widget that is used to traverse a directory hierarchy and select files. FileSelectionBox provides a directory mask input field, a
scrollable list of subdirectories, a scrollable list of filenames, a filename input
field, and a group of four PushButtons. The names for the filter text, directory list,
and directory list label are Text, DirList, and Dir respectively. The other components have the same names as the components in a SelectionBox.
In Motif 1.2, the button labels can be localized. In the C locale, and in Motif 1.1,
the PushButtons are labelled OK, Filter, Cancel, and Help by default.
You can customize a FileSelectionBox by removing existing children or adding
new children. Use XmFileSelectionBoxGetChild() to retrieve the widget
ID of an existing child and then unmanage the child. With Motif 1.2, multiple
widgets can be added as children of a FileSelectionBox. Additional children are
added in the same way as for a SelectionBox. In Motif 1.1, only a single widget
can be added as a child of a FileSelectionBox. This child is placed below the
filename input field and acts as a work area.
710
Motif Reference Manual
Motif and Xt Widget Classes
XmFileSelectionBox
In Motif 2.0 and later, the search pattern and base directory can be displayed in
two separate text fields, depending on the value of the XmNpathMode resource.
If the value is XmPATH_MODE_FULL, the behavior is consistent with that of
Motif 1.2, and the filter text field (Text) contains the XmNdirMask resource. If
the value is XmPATH_MODE_RELATIVE, t