X Toolkit Intrinsics Programming Manual for X11, Release 5

by Nye, Adrian; O'Reilly, Tim

• ISBN13: 9781565920132
• ISBN10: 1565920139
• Format: Paperback
• Copyright: 1992-08-01
• Publisher: Oreilly & Associates Inc

Summary

Volume 4 is a complete guide to programming with the X Toolkit Intrinsics, the library of C language routines that facilitates the design of user interfaces with reusable components called widgets. It provides concepts and examples that show how to use the various X Toolkit routines. The first few chapters are devoted to using widgets; the remainder of the book covers the more complex task of writing new widgets. Uses the Motif 1.2 widget set in examples and covers X11 Release 5. Volume 4 includes: Introduction to the X Window System. Building applications with widgets. Constructing a bitmap editor with widgets. An overview of each widget in the widget set. Basic widget methods./li> Events, translations, and accelerators. Event handlers, timeouts, and work procedures. Resource management and type conversion. Selections and window manager interaction. Geometry management. Menus, gadgets, and cascaded pop-ups. Miscellaneous techniques. Comparison of Athena, OSF/Motif, and AT&T OPEN LOOK widgets. This book is designed to be used with Volume 5, X Toolkit Intrinsics Reference Manual, which provides reference pages for each of the Xt functions, the widget classes defined by Xt, and the Athena widget set.

Author Biography

Adrian Nye is the author or editor of several volumes in the X Window System Series from O'Reilly & Associates. Adrian has worked as a programmer writing educational software in C and as a mechanical engineer designing offshore oil spill cleanup equipment. He has interests in the environment and the impact of people and technology. He graduated from the Massachusetts Institute of Technology in 1984 with a B.S. in mechanical engineering.

Tim O'Reilly is the founder and CEO of O'Reilly & Associates, thought by many to be the best computer book publisher in the world. O'Reilly also publishes online through the O'Reilly Network (www.oreillynet.com) and hosts conferences on technology topics. Tim is an activist for open source and open standards, and an opponent of software patents and other incursions of new intellectual property laws into the public domain. Tim's long term vision for his company is to help change the world by capturing and transmitting the knowledge of innovators.

Table of Contents

Preface	xxvii
Summary of Contents	xxvii
Assumptions	xxviii
Related Documents	xxviii
How to Use This Manual	xxix
Font Conventions Used in This Manual	xxxii
Request for Comments	xxxiii
Bulk Sales Information	xxxiii
Obtaining the X Window System Software	xxxiii
Obtaining Motif	xxxiv
Obtaining the Example Programs	xxxiv
FTP	xxxiv
FTPMAIL	xxxv
BITFTP	xxxv
UUCP	xxxvi
Compiling the Example Programs	xxxvii
Acknowledgments	xxxvii
Introduction to the X Window System	3	(12)
The Server and Client	6	(2)
The Software Hierarchy	8	(2)
Event-driven Programming	10	(1)
The Window Manager	11	(1)
Extensions to X	12	(3)
Introduction to the X Toolkit and Motif	15	(46)
Programming with Widgets	15	(16)
About Widget Sets	18	(2)
Widget Classes and Instances	20	(3)
Widget Configurability with Resources	23	(2)
Widget Independence	25	(2)
Widget-Application Interaction	27	(2)
Xt and Object-oriented Programming (OOP)	29	(1)
The Object	29	(1)
Methods	30	(1)
Messages	30	(1)
Encapsulation	30	(1)
Structure of Motif Applications	31	(1)
A Simple X Toolkit Application	32	(9)
The Code	33	(3)
Compiling the Application	36	(1)
The App-defaults File	36	(4)
To Hardcode or Not to Hardcode	40	(1)
Connecting Widgets to Application Code	41	(4)
Callbacks	42	(3)
More About Resources	45	(12)
Setting and Getting Resources from the Application	46	(1)
Setting Resources with the Varargs Interfaces	47	(2)
Setting Resources with the ArgList Interfaces	49	(1)
Getting a Resource Value	50	(1)
Core Resources	51	(3)
Other Inherited Resources	54	(3)
Advice on X Programming	57	(1)
Debugging Xt Applications	58	(3)
More Techniques for Using Widgets	61	(52)
Using Composite Widgets	61	(8)
Setting Resources for an Instance Hierarchy	64	(1)
Geometry Management in Practice	65	(4)
Using Constraint Widgets	69	(3)
The Standard Motif Instance Hierarchy	72	(5)
Motif Widget Creation Routines	74	(1)
Building a Main Window	74	(3)
Using Popups	77	(8)
Creating a Basic Menu	77	(3)
Creating a Basic Dialog Box	80	(4)
Popup Window Hierarchy	84	(1)
More About Callbacks	85	(5)
Passing Data to Callback Functions	86	(1)
The client_data Argument	86	(2)
The call_data Argument	88	(1)
Callback Lists	89	(1)
Application Resources	90	(6)
The Application Data Structure	91	(1)
The Resource List	91	(4)
Getting the Resources	95	(1)
Command-line Options	96	(7)
Standard Command-line Options	97	(1)
Defining Your Own Command-line Options	98	(5)
Preventing User Customization of Widget Resources	103	(6)
Using the Varargs Interfaces	103	(2)
Using the Argument List Interfaces	105	(2)
Another Way to Set Arguments	107	(1)
Merging Argument Lists	108	(1)
More About Application Contexts	109	(4)
An Example Application	113	(38)
xbitmap1: Bitmap Editor Using a BitmapEdit Widget	114	(5)
XBitmap1 App-defaults File	119	(1)
xbitmap2: Adding Graphics to Display the Bitmap	119	(10)
Exposure Strategy	121	(3)
Graphics from the Application	124	(4)
Writing a Bitmap File	128	(1)
xbitmap3: Another Way to Create a Custom Window	129	(9)
Actions	129	(2)
The Actions Table	131	(1)
Format of an Action Function	132	(1)
Translations	133	(1)
The Translation Table	134	(2)
Hardcoding Translations	136	(2)
Action Parameters	138	(1)
Adding Actions to Existing Widgets	138	(1)
xbitmap4: A Bitmap Editor Without a BitmapEdit Widget	138	(13)
More About Motif	151	(34)
The Remaining Motif Widgets and Gadgets	152	(7)
Geometry Managing Widgets	157	(1)
Dialog Widgets	158	(1)
Widget Creation Functions	159	(3)
Compound Strings	162	(6)
Simple Compound Strings	162	(2)
Strings with Multiple Fonts	164	(2)
Manipulating Compound Strings	166	(1)
Converting Compound Strings to Text	167	(1)
Rendering Compound Strings	168	(1)
Pixmap and Image Caching Functions	168	(2)
Dynamic Resource Defaulting	170	(1)
Resolution Independence	170	(1)
Keyboard Traversal and Focus	171	(2)
Motif Virtual Keyboard Bindings	173	(1)
Drag and Drop	174	(3)
Drag Protocol	174	(1)
Drop Protocol	175	(1)
Operations	175	(1)
Application Programming Interface	176	(1)
Summary: Drag and Drop in Applications	176	(1)
Tear-off Menus	177	(1)
The Motif User Interface Language	177	(8)
Inside a Widget	185	(32)
Widget Source File Organization	186	(1)
The Private Header File---BitmapEditP.h	187	(4)
Parts and Records	187	(1)
Class Part and Class Record	188	(1)
Instance Part and Instance Record	189	(2)
The Widget Implementation File---BitmapEdit.c	191	(18)
Obligatory Include Files	192	(1)
Defining the Resource List	193	(3)
The Translation Table and Actions Table	196	(2)
Declaring Methods	198	(1)
Initializing the Class Part	199	(1)
The Core Class Part	199	(3)
Initializing the Core Methods	202	(2)
Description of Core Methods	204	(2)
Packaging the Class Record for Application Use	206	(1)
A Sample Method	206	(3)
The Public Header File---BitmapEdit.h	209	(2)
The Process of Widget Writing	211	(1)
Summary of Conventions	212	(5)
Basic Widget Methods	217	(26)
The X Graphics Model Inside Widgets	218	(1)
The initialize Method	219	(5)
Creating GCs	221	(3)
The expose Method	224	(3)
The set_values Method	227	(3)
The resize Method	230	(3)
The query_geometry Method	233	(3)
The destroy Method	236	(1)
Actions in the Widget Framework	237	(6)
Events, Translations, and Accelerators	243	(28)
Translation Table Syntax	244	(17)
The Directive	245	(1)
Selecting the Events to Translate	245	(3)
Details in Keyboard Events	248	(1)
Details in Other Event Types	249	(2)
Modifiers	251	(1)
Physical Keys Used as Modifiers	252	(2)
Default Interpretation of the Modifier List	254	(1)
Prohibiting a Modifier	254	(1)
Requiring an Exact Match	255	(1)
Paying Attention to the Case of Keysyms	255	(1)
Event Sequences	256	(1)
Special Considerations Involving Motion Events	257	(1)
Modifiers and Event Sequences	258	(1)
Using Modifiers to Specify Button Event Sequences	258	(1)
Key Event Sequences	258	(1)
Interactions Between Translations	259	(1)
Translations in Multiple Resource Files	259	(1)
Order of Translations	259	(1)
Event Sequences Sharing Initial Events	260	(1)
Event Sequences Sharing Noninitial Events	260	(1)
Accelerators and Mnemonics	261	(10)
Xt Accelerators	261	(2)
Event Propagation	263	(2)
Installing Accelerators in Multiple Widgets	265	(1)
Defining the Accelerator Table in the Code	266	(1)
Motif Accelerators and Mnemonics	267	(1)
Mnemonics	267	(1)
The display_accelerators Method	268	(3)
More Input Techniques	271	(26)
Event Handlers	272	(6)
Adding Event Handlers	275	(1)
Adding Nonmaskable Event Handlers	276	(1)
Removing Event Handlers	277	(1)
Adding Raw Event Handlers	278	(1)
Writing Routines That Use Specific Event Data	278	(4)
Event Types and Structure Names	280	(2)
File, Pipe, and Socket Input	282	(3)
Getting File Input	282	(2)
Getting Pipe Input	284	(1)
Timeouts	285	(3)
Visibility Interest	288	(2)
Work Procedures	290	(2)
Low-level Management of the Event Queue	292	(5)
XtPending and XtPeekEvent	292	(1)
Event Filters	293	(1)
Input Sensitivity	294	(3)
Resource Management and Type Conversion	297	(44)
Review of Resource Fundamentals	298	(3)
How Xt's Resource Manager Works	301	(21)
Basic Syntax of Resource Specifications	302	(2)
Wildcarding Resource Component Names	304	(1)
Merging of Resource Files	304	(3)
Syntax of Environment Variables	307	(1)
Including Files in a Resource File	308	(1)
The Language String	309	(1)
Screen-specific Resource Strings and Databases	310	(2)
Fallback Resources	312	(1)
Resource Matching Algorithm	313	(2)
Resource Precedence Rules	315	(4)
Customized Resource Files	319	(2)
The XtNbase Translations Resource	321	(1)
Type Conversion	322	(14)
Conversions from XmRString	322	(2)
Other Built-in Type Conversions	324	(1)
Special Resource Defaults That Do Not Use Conversion	325	(2)
Registering Type Converters	327	(3)
Passing Arguments to a Type Converter	330	(2)
Explicitly Invoking a Converter	332	(2)
Writing a Type Converter	334	(1)
Defining the Default Value	335	(1)
Subparts and Subresources	336	(5)
The Hook Methods	337	(1)
Managing Subresources	338	(3)
Interclient Communications	341	(42)
Window Manager Interactions	342	(12)
Shell Subclasses	343	(1)
Setting Shell Resources	343	(3)
Screen Space	346	(1)
Input Model	347	(2)
Colormaps	349	(1)
Icons	350	(2)
Window Manager Decorations	352	(1)
Interacting With the Motif Window Manager	352	(1)
WM_PROTOCOLS	353	(1)
_MOTIF_WM_MESSAGES	354	(1)
_MOTIF_WM_HINTS	354	(1)
Selections: Widget-to-Widget Communication	354	(25)
How Atomic Selection Works	356	(3)
Highlighting the Selected Data (Owner)	359	(5)
Making the Selection with XtOwnSelection (Owner)	364	(1)
Requesting the Selection (Requestor)	365	(1)
Possible Target Type Atoms	366	(2)
The Paste Action from BitmapEdit	368	(1)
Converting the Selection (Owner)	368	(2)
Finally Pasting the Selection (Requestor)	370	(2)
If the Selection is Lost (Owner)	372	(1)
When the Selection Transfer is Complete (Owner)	373	(1)
ICCCM Compliance	373	(2)
Xmu Atom Caching	375	(1)
Converting the Standard Selections	375	(2)
How Incremental Selection Works	377	(2)
Miscellaneous Selection Routines	379	(1)
Motif Cut and Paste Functions and the Clipboard	379	(4)
Geometry Management	383	(42)
How Composite Management Works	384	(8)
Initial Geometry Negotiation	386	(3)
User Resizes the Application	389	(1)
Widget Desires a Size Change	389	(2)
Application Resizes a Widget	391	(1)
Writing a Composite Widget	392	(12)
Basic Core Methods in Composite Widgets	394	(2)
Laying Out Child Widgets	396	(2)
The change_managed Method	398	(1)
The geometry_manager Method	398	(1)
XtQueryGeometry and the query_geometry Method	399	(1)
XtMakeGeometryRequest and the geometry_manager Method	400	(2)
The set_values_almost Method	402	(1)
The insert_child and delete_child Methods	403	(1)
How Constraint Management Works	404	(1)
Writing a Constraint Widget	404	(16)
The Core Resource List	405	(1)
The Constraint Resource List	406	(2)
Class Structure Initialization	408	(2)
The Constraint initialize Method	410	(1)
The class_part_init Method	411	(1)
The geometry_manager Method	412	(4)
The resize Method	416	(2)
The Core and Constraint set_values Methods	418	(1)
The change_managed Method	418	(1)
The query_geometry Method	419	(1)
Delaying Geometry Recalculation	420	(1)
Compound Widgets	420	(1)
Stacking Order	421	(4)
Menus, Gadgets, and Cascaded Popups	425	(42)
Menu Styles and Implementation	427	(1)
Using Motif Menus	428	(3)
Popup Menus	429	(1)
Cascaded Menus	430	(1)
Basic Xt Popup Support	431	(22)
A Spring-loaded Menu: Pointer Grabbing	432	(8)
A Pulldown Menu	440	(3)
Cascaded Menus	443	(5)
Using the R4 Simple Menu Widget	448	(4)
Delayed Popup Creation	452	(1)
About Dialog Boxes	453	(1)
Gadgets	454	(13)
Inside a Gadget	457	(1)
Private Header File	458	(1)
The Gadget Source File	459	(1)
The Public Header File	460	(1)
The Gadget Parent	460	(7)
Miscellaneous Toolkit Programming Techniques	467	(36)
Errors and Warnings	467	(3)
Objects	470	(1)
Macros For Getting Information	471	(2)
The accept_focus Method and the Keyboard Focus	473	(1)
Keyboard Interpretation	474	(1)
Memory Allocation	475	(1)
Action Hooks and Calling Actions Directly	476	(1)
Xt Grabbing Functions	476	(1)
File Finding and Internationalization	477	(1)
Application Contexts	477	(3)
Multiple Application Contexts	479	(1)
Rewriting XtAppMainLoop for Multiple Application Contexts	479	(1)
Functions Used with Multiple Application Contexts	480	(1)
Multiple Top-level Shells	480	(1)
Connecting to Multiple Servers	481	(1)
Class Extension Structures	481	(2)
Using Editres in Xt Programming	483	(11)
A Tour of editres	483	(7)
editres as a Programmer's Tool	490	(1)
Adding editres Support to an Xt Application	490	(1)
Using editres to Understand the Structure of an Application	491	(1)
Using editres to Test or Debug a Widget	492	(1)
Testing a Widget's set_values Procedures	492	(1)
Testing a Widget's geometry_manager	493	(1)
Internationalization in the X Toolkit	494	(9)
String Encoding and Locale Dependencies in Xt	494	(1)
Establishing Locale in an Xt Application	494	(2)
XFontSet Resources	496	(1)
Other Xt Changes for Internationalization	496	(1)
Internationalization in Motif 1.2	497	(1)
Text Output	497	(1)
Text Input	498	(1)
Compound Text Conversion	498	(1)
_XmGetLocalized()	498	(1)
Summary	498	(5)
Appendix A Athena, OPEN LOOK, and Motif	503	(28)
A.1 The AT&T OPEN LOOK Widgets	507	(10)
A.1.1 Application Controls	508	(1)
A.1.1.1 Command Buttons	508	(2)
A.1.1.2 Exclusive and Nonexclusive Settings	510	(2)
A.1.1.3 Analog Controls	512	(1)
A.1.2 Composite Widgets	512	(1)
A.1.2.1 Menus and Control Areas	512	(1)
A.1.2.2 General Purpose Composite Widgets	513	(1)
A.1.2.3 Scrollbars and Scrollable Windows	513	(2)
A.1.3 Popups	515	(2)
A.1.4 Text Widgets	517	(1)
A.1.5 Drawing Areas	517	(1)
A.2 The OSF/Motif Widgets	517	(14)
A.2.1 Application Controls	520	(1)
A.2.1.1 Command Buttons	520	(1)
A.2.1.2 Analog Controls	521	(1)
A.2.2 Composite Widgets	521	(1)
A.2.2.1 Menus and Control Areas	521	(2)
A.2.2.2 General Purpose Composite Widgets	523	(1)
A.2.2.3 Scrollable Windows	524	(2)
A.2.3 Popups	526	(1)
A.2.4 Text Widgets	526	(1)
A.2.5 Drawing Areas	527	(4)
Appendix B Specifying Fonts and Colors	531	(24)
B.1 Color Specification	531	(5)
B.1.1 Color Names	531	(1)
B.1.2 Hexadecimal Color Specification	532	(1)
B.1.2.1 The RGB Color Model	533	(1)
B.1.2.2 How Many Colors are Available?	534	(2)
B.2 Font Specification	536	(6)
B.2.1 Font Naming Conventions	537	(1)
B.2.2 Font Name Wildcarding	538	(2)
B.2.3 Font Name Aliasing	540	(1)
B.2.4 Making the Server Aware of Aliases	541	(1)
B.2.5 The fonts.dir Files	542	(1)
B.3 Font Service	542	(2)
B.4 Scalable Fonts	544	(6)
B.4.1 Finding Scalable Fonts	545	(1)
B.4.2 Finding Derived Instances of Scalable Fonts	546	(2)
B.4.3 Using Scalable Fonts	548	(2)
B.5 Window Geometry	550	(5)
Appendix C Naming Conventions	555	(4)
Appendix D Release Notes	559	(8)
D.1 R4 to R5	559	(1)
D.2 Motif 1.1 to 1.2	560	(7)
D.2.1 Widget Changes	561	(1)
D.2.2 New Display and Screen Objects	562	(1)
D.2.3 Default Colors	562	(1)
D.2.4 Insensitive Visuals	563	(1)
D.2.5 Baseline Alignment	563	(1)
D.2.6 Geometry Management	563	(1)
D.2.7 Traversal	563	(1)
D.2.8 Representation Type Convenience Functions	563	(1)
D.2.9 caddr_t Changed to XtPointer	564	(1)
D.2.10 Mwm	564	(1)
D.2.11 UIL and Mrm	564	(3)
Appendix E The xbitmap Application	567	(26)
E.1 The BitmapEdit Widget	567	(13)
E.2 The BitmapEdiP.h Private Header File	580	(2)
E.3 The BitmapEdit.h Public Header File	582	(1)
E.4 xbitmap5	583	(10)
Appendix F Sources of Additional Information	593	(10)
F.1 Getting the X Software	593	(4)
F.1.1 Bug Fixes	594	(2)
F.1.1.1 Notes	596	(1)
F.1.1.2 Fairness	596	(1)
F.2 Netnews	597	(1)
F.3 Training, Consulting, and Support	597	(1)
F.4 The X Consortium	598	(1)
F.5 Finding Out for Yourself	599	(4)
Glossary	603	(22)
Master Index	625