0 " O0
Volume Four
X Toolkit Intrinsics
Programming Manual
By Adrian Nye and Tim O'Reilly
O'Reilly & Associates, Inc.
X Toolkit Intrinsics
Programming Manual
Table of Contents
Page
Preface .................................................................................................................................. xxv
Summary of Contents ................................................................................................................ xxv
Assumptions .............................................................................................................................. xxvi
Related Documents .................................................................................................................. xxvi
How to Use This Manual ....................................................................................................... xxviii
Font Conventions Used in This Manual ................................................................................... xxx
Request for Comments ............................................................................................................. xxxi
Bulk Sales Information ............................................................................................................ xxxi
Obtaining the X Window System Software .......................................................................... xxxii
Obtaining the Example Programs .......................................................................................... xxxii
FFP ....................................................................................................................................... xxxii
FFPMAIL ........................................................................................................................... xxxiii
BITFTP ............................................................................................................................... xxxiii
UUCP .................................................................................................................................. xxxiv
Compiling the Example Programs .......................................................................................... xxxv
Acknowledgments ................................................................................................................... xxxv
Chapter 1 Introduction to the X Window System ............................................... 3
1.1 The Server and Client ............................................................................................................. 5
1.2 The Software Hierarchy ......................................................................................................... 8
1.3 Event-driven Programming .................................................................................................. 10
1.4 The Window Manager .......................................................................................................... 11
1.5 Extensions to X ..................................................................................................................... 12
Chapter 2 Introduction to the X Toolkit ................................................................ 15
2.1 Programming with Widgets ................................................................................................. 15
2.1.1 About Widget Sets ......................................................................................................... 18
2.1.2 Widget Classes and Instances ....................................................................................... 20
2.1.3 Widget Configurability with Resources ...................................................................... 23
2.1.4 Widget Independence .................................................................................................... 24
2.1.5 Widget-Application Interaction ................................................................................... 26
2.1.6 Xt and Object-oriented Programming (OOP) .............................................................. 28
2.1.6.1 The Object ................................................................................................................. 28
2.1.6.2 Methods ..................................................................................................................... 29
2.1.6.3 Messages ................................................................................................................... 29
2.1.6.4 Encapsulation ............................................................................................................ 29
2.2 Structure of Applications ..................................................................................................... 30
2.3 A Simple X Toolkit Application .......................................................................................... 31
2.3.1 The Code ........................................................................................................................ 32
2.3.2 Compiling the Application ........................................................................................... 35
2.3.3 The App-defaults File ................................................................................................... 35
2.3.4 To Hardcode or Not to Hardcode ................................................................................. 39
2.4 Connecting Widgets to Application Code .......................................................................... 40
2.4.1 Callbacks ........................................................................................................................ 41
2.5 More About Resources ......................................................................................................... 44
2.5.1 Setting and Getting Resources from the Application ................................................. 44
2.5.1.1 Setting Resources with the Varargs Interfaces ....................................................... 45
2.5.1.2 Setting Resources with the ArgList Interfaces ....................................................... 47
2.5.1.3 Getting a Resource Value ........................................................................................ 48
2.5.2 Core Resources .............................................................................................................. 49
2.5.3 Other Inherited Resources ............................................................................................ 51
2.6 Advice on X Programming .................................................................................................. 54
2.7 Debugging Xt Applications ................................................................................................. 55
Chapter 3 More Techniques for Using Widgets ................... : ............................. 59
3.1 Using Composite Widgets ................................................................................................... 59
3.1.1 Setting Resources for an Instance Hierarchy .............................................................. 62
3.1.2 Geometry Management in Practice .............................................................................. 63
3.2 Using Constraint Widgets .................................................................................................... 67
3.3 Using Popups ........................................................................................................................ 70
3.4 More About Callbacks ......................................................................................................... 76
3.4.1 Passing Data to Callback Functions ............................................................................. 77
3.4.1.1 The client_data Argument ....................................................................................... 77
3.4.1.2 The call_data Argument ........................................................................................... 79
3.4.2 Callback Lists ................................................................................................................ 79
3.5 Application Resources ......................................................................................................... 80
3.5.1 The Application Data Structure .................................................................................... 81
3.5.2 The Resource List .......................................................................................................... 81
3.5.3 Getting the Resources ................................................................................................... 85
3.6 Command-line Options ........................................................................................................ 86
3.6.1 Standard Command-line Options ................................................................................. 87
3.6.2 Defining Your Own Command-line Options ............................................................... 88
3.7 Preventing User Customization of Widget Resources ....................................................... 92
3.7.1 Using the Varargs Interfaces ......................................................................................... 93
3.7.2 Using the Argument List Interfaces ............................................................................. 94
3.7.2.1 Another Way to Set Arguments ............................................................................... 96
3.7.2.2 Merging Argument Lists .......................................................................................... 97
3.8 More About Application Contexts ...................................................................................... 98
Chapter 4 An Example Application ....................................................................... lOl
4.1 xbitmapl: Bitmap Editor Using a BitmapEdit Widget ................................................... 102
4.1.1 Widget Public Functions ............................................................................................. 105
4.1.2 Application-defaults File ............................................................................................ 105
4.2 xbitmap2 and xbitmap3: Adding Graphics to Display the Bitmap ................................ 106
4.2.1 Graphics from the Application ................................................................................... 109
4.2.2 Writing a Bitmap File .................................................................................................. 113
4.2.3 Actions ......................................................................................................................... 114
4.2.3.1 The Actions Table .................................................................................................. 115
4.2.3.2 Format of an Action Function ............................................................................... 117
4.2.4 Translations .................................................................................................................. 118
4.2.4.1 The Translation Table ............................................................................................. 118
4.2.4.2 Hardcoding Translations ........................................................................................ 121
4.2.4.3 Action Parameters .................................................................................................. 122
4.2.5 Adding Actions to Existing Widgets ......................................................................... 122
4.3 xbitmap4: A Bitmap Editor Without a BitmapEdit Widget ........................................... 122
Chapter 5 The Athena Widget Set .......................................................................... 135
5.1 Simple Widgets ................................................................................................................... 135
5.2 Text Widgets ....................................................................................................................... 140
5.2.1 User's View of the Text Widget ................................................................................. 140
5.2.1.1 Search and Replace ................................................................................................ 140
5.2.1.2 File Insertion ........................................................................................................... 141
5.2.2 Common Text Widget Techniques ............................................................................. 141
5.2.2.1 Single-line Text Entry ............................................................................................ 141
5.2.2.2 The Editable Selection List ................................................................................... 145
5.2.3 Customization .............................................................................................................. 145
Chapter 6 Inside a Widget .......................................................................................... 149
6.1 Widget Source File Organization ...................................................................................... 150
6.2 The Private Header File--BitmapEdiP.h ......................................................................... 151
6.2.1 Parts and Records ........................................................................................................ 151
6.2.2 Class Part and Class Record ....................................................................................... 152
6.2.3 Instance Part and Instance Record ............................................................................. 153
6.3 The Widget Implementation File--BitmapEdit.c ........................................................... 155
6.3.1 Obligatory Include Files ............................................................................................. 156
6.3.2 Defining the Resource List ......................................................................................... 157
6.3.3 The Translation Table and Actions Table .................................................................. 160
6.3.4 Declaring Methods ...................................................................................................... 162
6.3.5 Initializing the Class Record ...................................................................................... 163
6.3.5.1 The Core Class Part ................................................................................................ 163
6.3.5.2 Initializing the Core Methods ................................................................................ 165
6.3.6 Description of Core Methods ..................................................................................... 167
6.3.7 Packaging the Class Record for Application Use ..................................................... 169
6.3.8 A Sample Method ........................................................................................................ 169
6.4 The Public Header File--BitmapEdit.h ........................................................................... 172
6.5 The Process of Widget Writing ......................................................................................... 174
6.6 Summary of Conventions ................................................................................................... 176
Chapter 7 Basic Widget Methods ............................................................................ 179
7.1 The X Graphics Model Inside Widgets ............................................................................. 180
7.2 The initialize Method ......................................................................................................... 181
7.2.1 Creating GCs ............................................................................................................... 183
7.3 The expose Method ............................................................................................................ 185
7.4 The set_values Method ...................................................................................................... 189
7.5 The resize Method .............................................................................................................. 191
7.6 The query_geometry Method ............................................................................................ 194
7.7 The destroy Method ............................................................................................................ 197
7.8 Actions in the Widget Framework .................................................................................... 198
Chapter 8 Events, Translations, and Accelerators ........................................... 203
8.1 Translation Table Syntax .................................................................................................... 204
8.1.1 The Directive ............................................................................................................... 205
8.1.2 Selecting the Events to Translate ............................................................................... 205
8.1.3 Details in Keyboard Events ........................................................................................ 208
8.1.4 Details in Other Event Types ...................................................................................... 209
8.1.5 Modifiers ...................................................................................................................... 211
8.1.5.1 Physical Keys Used as Modifiers .......................................................................... 212
8.1.5.2 Default Interpretation of the Modifier List .......................................................... 214
8.1.5.3 Prohibiting a Modifier ........................................................................................... 214
8.1.5.4 Requiring an Exact Match ..................................................................................... 215
8.1.5.5 Paying Attention to the Case of Keysyms ............................................................ 215
8.1.6 Event Sequences .......................................................................................................... 216
8.1.6.1 Special Considerations Involving Motion Events ............................................... 217
8.1.6.2 Modifiers and Event Sequences ............................................................................ 218
8.1.6.3 Using Modifiers to Specify Button Event Sequences ......................................... 218
8.1.6.4 Key Event Sequences ............................................................................................. 218
8.1.7 Interactions Between Translations ............................................................................. 219
8.1.7.1 Translations in Multiple Resource Files ............................................................... 219
8.1.7.2 Order of Translations .............................................................................................. 219
8.1.7.3 Event Sequences Sharing Initial Events ............................................................... 220
8.1.7.4 Event Sequences Sharing Noninitial Events ........................................................ 220
8.2 Accelerators ........................................................................................................................ 221
8.2.1 Xt Accelerators ............................................................................................................ 221
8.2.2 Event Propagation ....................................................................................................... 223
viii
..
8.2.3 Installing Accelerators in Multiple Widgets ............................................................. 225
8.2.4 Defining the Accelerator Table in the Code .............................................................. 226
8.2.5 The display_accelerators Method .............................................................................. 226
Chapter 9 More Input Techniques .......................................................................... 229
9.1 Event Handlers .................................................................................................................... 230
9.1.1 Adding Event Handlers ............................................................................................... 232
9.1.2 Adding Nonmaskable Event Handlers ....................................................................... 233
9.1.3 Removing Event Handlers .......................................................................................... 234
9.1.4 Adding Raw Event Handlers ...................................................................................... 235
9.2 Writing Routines That Use Specific Event Data .............................................................. 235
9.2.1 Event Types and Structure Names .............................................................................. 237
9.3 File, Pipe, and Socket Input ............................................................................................... 239
9.3.1 Getting File Input ........................................................................................................ 239
9.3.2 Getting Pipe Input ....................................................................................................... 241
9.4 Timeouts .............................................................................................................................. 242
9.5 Visibility Interest ................................................................................................................ 245
9.6 Work Procedures ................................................................................................................. 246
9.7 Low-level Management of the Event Queue .................................................................... 249
9.7.1 XtPending and XtPeekEvent ...................................................................................... 249
9.7.2 Event Filters ................................................................................................................. 250
9.7.3 Input Sensitivity .......................................................................................................... 251
Chapter 10 Resource Management and Type Conversion ........................... 255
10.1 Review of Resource Fundamentals ................................................................................. 255
10.2 How Xt's Resource Manager Works ............................................................................... 259
10.2.1 Basic Syntax of Resource Specifications ................................................................ 260
10.2.2 Wildcarding Resource Component Names ............................................................. 261
10.2.3 Merging of Resource Files ....................................................................................... 262
10.2.4 Syntax of Environment Variables ............................................................................ 264
10.2.5 Including Files in a Resource File ........................................................................... 267
10.2.6 The Language String ................................................................................................. 268
10.2.7 Screen-specific Resource Strings and Databases ................................................... 269
10.2.8 Fallback Resources ................................................................................................... 271
10.2.9 Resource Matching Algorithm ................................................................................. 272
10.2.10 Resource Precedence Rules .................................................................................... 274
10.2.11 Customized Resource Files .................................................................................... 278
10.2.12 The XtNbaseTranslations Resource ....................................................................... 279
10.3 Type Conversion ............................................................................................................... 280
10.3.1 Conversions from XtRString .................................................................................... 281
10.3.2 Other Built-in Type Conversions ............................................................................. 282
10.3.3 Special Resource Defaults That Do Not Use Conversion ...................................... 284
10.3.4 Registering Type Converters .................................................................................... 285
10.3.4.1 Passing Arguments to a Type Converter ............................................................ 289
10.3.5 Explicitly Invoking a Converter ............................................................................... 291
10.3.6 Writing a Type Converter ......................................................................................... 292
10.3.6.1 Defining the Default Value ................................................................................. 294
10.4 Subparts and Subresources .............................................................................................. 294
10.4.1 The Hook Methods .................................................................................................... 295
10.4.2 Managing Subresources ............................................................................................ 296
Chapter 11 Interclient Communications ............................................................. 299
11.1 Window Manager Interactions ........................................................................................ 300
11.1.1 Shell Subclasses ........................................................................................................ 300
11.1.2 Setting Shell Resources ............................................................................................ 301
11.1.3 Screen Space .............................................................................................................. 303
11.1.4 Input Model ............................................................................................................... 305
11.1.5 Colormaps .................................................................................................................. 306
11.1.6 Icons ........................................................................................................................... 308
11.1.7 Window Manager Decorations ................................................................................. 309
11.1.8 Interacting with the Window Manager .................................................................... 310
11.1.8.1 WM_PROTOCOLS ............................................................................................. 311
11.2 Selections: Widget-to-Widget Communication ............................................................ 311
11.2.1 How Atomic Selection Works .................................................................................. 312
11.2.2 Highlighting the Selected Data (Owner) ................................................................. 315
11.2.3 Making the Selection with XtOwnSelection (Owner) ........................................... 320
11.2.4 Requesting the Selection (Requestor) ..................................................................... 321
11.2.4.1 Possible Target Type Atoms ................................................................................ 322
11.2.4.2 The Paste Action from BitmapEdit ..................................................................... 324
11.2.5 Converting the Selection (Owner) ........................................................................... 324
11.2.6 Finally Pasting the Selection (Requestor) ............................................................... 327
11.2.7 If the Selection Is Lost (Owner) ............................................................................... 329
11.2.8 When the Selection Transfer Is Complete (Owner) ................................................ 329
11.2.9 ICCCM Compliance ................................................................................................... 329
11.2.9.1 Xmu Atom Caching ............................................................................................. 331
11.2.9.2 Converting the Standard Selections .................................................................... 332
11.2.10 How Incremental Selection Works ........................................................................ 333
11.2.11 Miscellaneous Selection Routines ......................................................................... 335
11.3 The Clipboard ................................................................................................................... 335
Chapter 12 Geometry Management ...................................................................... 339
12.1 How Composite Management Works ............................................................................. 341
12.1.1 Initial Geometry Negotiation ................................................................................... 342
12.1.2 User Resizes the Application ................................................................................... 344
12.1.3 Widget Desires a Size Change ................................................................................. 345
12.1.4 Application Resizes a Widget .................................................................................. 346
12.2 Writing a Composite Widget ........................................................................................... 347
12.2.1 Basic Core Methods in Composite Widgets ............................................................ 349
X
12.2.2 Laying Out Child Widgets ........................................................................................ 351
12.2.3 The change_managed Method ................................................................................. 353
12.2.4 The geometry_manager Method .............................................................................. 353
12.2.5 XtQueryGeometry and the query_geometry Method ............................................. 354
12.2.6 XtMakeGeometryRequest and the geometry_manager Method ........................... 355
12.2.7 The set_values_almost Method ................................................................................ 357
12.2.8 The insert_child and delete_child Methods ............................................................ 358
12.3 How Constraint Management Works .............................................................................. 359
12.4 Writing a Constraint Widget ............................................................................................ 359
12.4.1 The Core Resource List ............................................................................................ 360
12.4.2 The Constraint Resource List ................................................................................... 361
12.4.3 Class Structure Initialization .................................................................................... 363
12.4.4 The Constraint initialize Method ............................................................................. 365
12.4.5 The class_part_init Method ...................................................................................... 366
12.4.6 The geometry_manager Method .............................................................................. 367
12.4.7 The resize Method ..................................................................................................... 371
12.4.8 The Core and Constraint set_values Methods ......................................................... 373
12.4.9 The change_managed Method ................................................................................. 374
12.4.10 The query_geometry Method ................................................................................. 374
12.4.11 Delaying Geometry Recalculation ......................................................................... 375
12.5 Compound Widgets .......................................................................................................... 376
12.6 Stacking Order .................................................................................................................. 376
Chapter 13 Menus, Gadgets, and Cascaded Popups ....................................... 381
13.1 Menu Styles and Implementation .................................................................................... 383
13.1.1 How Menus are Popped Up ...................................................................................... 384
13.1.2 Menu Panes ................................................................................................................ 385
13.2 Basic Xt Popup Support ................................................................................................... 387
13.2.1 A Spring-loaded Menu: Pointer Grabbing ............................................................. 387
13.2.2 A Pulldown Menu ..................................................................................................... 395
13.2.3 Cascaded Menus ........................................................................................................ 399
13.2.4 Using the SimpleMenu Widget ................................................................................ 404
13.2.5 Delayed Popup Creation ........................................................................................... 408
13.3 About Dialog Boxes ......................................................................................................... 408
13.4 Gadgets .............................................................................................................................. 410
13.4.1 Inside a Gadget .......................................................................................................... 412
13.4.2 Private Header File .................................................................................................... 413
13.4.3 The Gadget Source File ............................................................................................ 414
13.4.4 The Public Header File ............................................................................................. 415
13.4.5 The Gadget Parent ..................................................................................................... 415
Chapter 14 Miscellaneous Toolkit Programming Techniques .................... 423
14.1 Errors and Warnings ......................................................................................................... 423
14.2 Objects ............................................................................................................................... 426
xi
14.3
14.4
14.5
14.6
14.7
14.8
Macros For Getting Information ..................................................................................... 427
The accept_focus Method and the Keyboard Focus ...................................................... 429
Keyboard Interpretation ................................................................................................... 429
Memory Allocation .......................................................................................................... 431
Action Hooks and Calling Actions Directly .................................................................. 431
Xt Grabbing Functions ..................................................................................................... 432
14.9 File Finding and Internationalization ............................................................................. 433
14.10 Application Contexts ..................................................................................................... 433
14.10.1 Multiple Application Contexts ............................................................................... 434
14.10.2 Rewriting XtAppMainLoop for Multiple Application Contexts ......................... 435
14.10.3 Functions Used with Multiple Application Contexts ........................................... 436
14.11 Multiple Top-level Shells .............................................................................................. 436
14.12 Connecting to Multiple Servers .................................................................................... 437
14.13 Class Extension Structures ............................................................................................ 437
14.14 Using Editres in Xt Programming ................................................................................. 439
14.14.1 A Tour ofeditres ...................................................................................................... 439
14.14.2 editres as a Programmer's Tool .............................................................................. 444
14.14.3 Using editres to Understand the Structure of an Application .............................. 445
14.14.4 Using editres to Test or Debug a Widget ............................................................... 446
14.14.4.1 Testing a Widget's set_values Procedures ....................................................... 446
14.14.4.2 Testing a Widget's geometry_manager ............................................................ 447
14.15 Internationalization in the X Toolkit ............................................................................ 447
14.15.1 String Encoding and Locale Dependencies in Xt ................................................. 448
14.15.2 Establishing Locale in an Xt Application ............................................................. 448
14.15.3 XFontSet Resources ................................................................................................ 449
14.15.4 Other Xt Changes for Internationalization ............................................................ 450
Appendix A Athena, OPEN LOOK, and Motif .................................................. 455
A. 1 The AT&T OPEN LOOK Widgets ..................................................................................... 459
A.1.1 Application Controls .................................................................................................. 460
A. 1.1.1 Command Buttons ................................................................................................. 460
A. 1.1.2 Exclusive and Nonexclusive Settings .................................................................. 462
A. 1.1.3 Analog Controls ..................................................................................................... 463
A. 1.2 Composite Widgets .................................................................................................... 464
A. 1.2.1 Menus and Control Areas ..................................................................................... 464
A. 1.2.2 General Purpose Composite Widgets .................................................................. 464
A. 1.2.3 Scrollbars and Scrollable Windows ..................................................................... 465
A. 1.3 Popups ......................................................................................................................... 466
A. 1.4 Text Widgets ............................................................................................................... 468
A. 1.5 Drawing Areas ............................................................................................................ 469
A.2 The OSF/Motif Widgets .................................................................................................... 469
A.2.1 Application Controls .................................................................................................. 470
A.2.1.1 Command Buttons ................................................................................................. 470
A.2.1.2 Analog Controls ..................................................................................................... 471
A.2.2 Composite Widgets .................................................................................................... 472
A.2.2.1 Menus and Control Areas ..................................................................................... 472
A.2.2.2 General Purpose Composite Widgets .................................................................. 474
A.2.2.3 Scrollable Windows .............................................................................................. 475
A.2.3 Popups ......................................................................................................................... 476
A.2.4 Text Widgets ............................................................................................................... 477
A.2.5 Drawing Areas ............................................................................................................ 477
Appendix B Specifying Fonts and Colors ............................................................ 481
B. 1 Color Specification ............................................................................................................ 481
B. 1.1 Color Names ................................................................................................................ 482
B. 1.2 Exact Color Specification .......................................................................................... 483
B. 1.2.1 The RGB Color Model .......................................................................................... 483
B. 1.2.2 How Many Colors Are Available? ....................................................................... 484
B.2 Font Specification .............................................................................................................. 486
B.2.1 Font Naming Conventions ......................................................................................... 487
B.2.2 Font Name Wildcarding ............................................................................................. 489
B.3 Font Service ....................................................................................................................... 490
B.4 Scalable Fonts .................................................................................................................... 492
B.4.1 Finding Scalable Fonts ............................................................................................... 493
B.4.2 Finding Derived Instances of Scalable Fonts ........................................................... 494
B.4.3 Using Scalable Fonts .................................................................................................. 496
B.5 Window Geometry ............................................................................................................. 498
Appendix C Naming Conventions ........................................................................... 503
Appendix D Release Notes .......................................................................................... 5o7
D. 1 R4 to R5 .............................................................................................................................. 507
Appendix E The xbitmap Application .................................................................. 511
E.1 The BitmapEdit Widget ..................................................................................................... 511
E.2 The BitmapEdiP.h Private Header File ............................................................................ 524
E.3 The BitmapEdit.h Public Header File ............................................................................... 525
E.4 xbitmap5 ............................................................................................................................. 527
Appendix F Sources of Additional Information .............................................. 535
F. 1 Getting the X Software ...................................................................................................... 535
F.I.1 Bug Fixes ..................................................................................................................... 536
F. 1.1.1 Notes ....................................................................................................................... 538
F. 1.1.2 Fairness ................................................................................................................... 538
xiii
F.2 Netnews ............................................................................................................................... 539
F.3 Training, Consulting, and Support .................................................................................... 539
F.4 The X Consortium .............................................................................................................. 540
F.5 Finding Out for Yourself .................................................................................................... 542
X/I/
Figures
Page
1-1 An X application, and an application on a traditional text terminal ................................. 3
1-2 A three-button mouse directing the pointer to select a menu item .................................... 4
1-3 Screen layout of a typical user's X Window System .......................................................... 5
1-4 Applications can run on any system across the network .................................................... 7
1-5 The software architecture of Xt Intrinsics-based applications .......................................... 9
2-1 A widget-based application (simulated) ............................................................................ 16
2-2 A Motif widget-based application (simulated) ................................................................. 18
2-3 Two ways to think about a class ......................................................................................... 21
2-4 Class hierarchy of the Athena widget set .......................................................................... 22
2-5 Several Athena Label widgets configured using resources ............................................. 23
2-6 Widgets operate independently of the application ........................................................... 25
2-7 XtSetValues lets the application set how a widget will operate itself ............................ 25
2-8 Application registers a function with Xt during startup phase ........................................ 26
2-9 Xt calls the function during the event-loop phase in response to an occurrence ........... 27
2-10 xhello: appearance on screen .......................................................................................... 31
2-11 The appearance of xgoodbye when the pointer is in the window ................................. 41
2-12 xgoodbye run with new resource settings ....................................................................... 53
3-1 xbox 1: appearance on the screen ...................................................................................... 60
3-2 Two configurations of xboxl ............................................................................................. 63
3-3 Incorrect results upon resize of Scrollbar widgets inside a Box widget ......................... 65
3-4 The xmh application and its instance hierarchy ............................................................... 66
3-5 Effect of the Form's fromHoriz constraint resource ......................................................... 70
3-6 xbox3: popping up a Dialog widget .................................................................................. 71
3-7 The widget instance and X window hierarchies are different only for popups .............. 76
4-1 xbitmapl: how it looks on the screen ............................................................................. 102
4-2 xbitmap2 and xbitmap3: true-scale normal and reverse bitmaps added ...................... 106
4-3 Application draws into Pixmap and copies it to widget window .................................. 107
4-4 Two-stage mapping with translation table and action table .......................................... 114
5-1 A List widget ..................................................................................................................... 135
5-2 A Panner widget ................................................................................................................ 136
5-3 A StripChart widget used in a load monitoring application .......................................... 138
5-4 A Toggle widget ................................................................................................................ 138
5-5 xtextentry: a simple forms entry dialog ........................................................................... 141
6-1 The class hierarchy of the BitmapEdit widget (with other classes shown dotted) ....... 151
6-2 Order of code in widget .c file ......................................................................................... 157
7-1 compress_exposure: 2 rectangles if XtExposeNoCompress; bounding box and
region if XtExposeCompressSeries or XtExposeCompressMultiple ............................ 188
8-1 xboxl: two Command widgets in a Box ........................................................................ 222
8-2 Key event propagation in xbox ........................................................................................ 224
9-1 xtetris in play ..................................................................................................................... 243
10-1 Typical resource setting search path on UNIX-based systems .................................... 265
10-2 The quit widget in a sample widget hierarchy .............................................................. 272
10-3 Steps in matching resource entries for one resource of widget being created ........... 278
XV
11-1
12-1
12-2
12-3
12-4
12-5
12-6
13-1
13-2
13-3
13-4
13-5
13-6
13-7
14-1
14-2
14-3
14-4
14-5
14-6
A-1
A-2
A-3
A-4
A-5
A-6
A-7
A-8
A-9
A-10
A-I1
A-12
A-13
A-14
A-15
A-16
A-17
A-18
A-19
A-20
B-1
B-2
B-3
The process of selection transfer ................................................................................... 314
Role of border width in widget geometry ..................................................................... 341
Initial geometry negotiation, assuming sufficient shell space ..................................... 343
Initial geometry negotiation, if resizing is necessary ................................................... 343
A widget requesting a size change ................................................................................ 346
A ScrollBox widget at two different sizes .................................................................... 348
Geometry negotiation by the set_values_almost method ............................................ 358
Athena Command widgets in an Athena Box widget, and the same commands
as a SimpleMenu ............................................................................................................. 382
Menus from the OPEN LOOK and Motif widget sets .................................................... 386
xmenu 1: application with spring-loaded pop-up menu ............................................... 390
xmenu2: a pulldown menu ............................................................................................ 396
xmenu5: cascaded spring-loaded menus ...................................................................... 399
xmenu7: a menu using the Athena SimpleMenu widget ............................................ 404
Class hierarchy derivation of Core ................................................................................ 411
editres immediately after startup ................................................................................... 440
editres with widget tree displayed ................................................................................. 44 1
editres display window IDs of widget tree .................................................................... 441
Flashing widget in application by selecting it in editres .............................................. 442
Resource box for the selected Label widget ................................................................. 443
Generalizing the widgets affected by the resource specification ................................ 443
An OPEN LOOK application ............................................................................................ 459
An OPEN LOOK ControlArea with OblongButton and ButtonStack widgets ............. 460
Class inheritance hierarchy of the AT&T OPEN LOOK widgets .................................. 461
OPEN LOOK RectButtons controlled by Exclusives and Nonexclusives widgets ....... 463
An OPEN LOOK CheckBox widget ................................................................................. 463
An OPEN LOOK Slider widget ........................................................................................ 464
An OPEN LOOK Scrollbar ............................................................................................... 465
An OPEN LOOK ScrollingList widget ............................................................................ 466
An OPEN LOOK Notice .................................................................................................... 466
An OPEN LOOK PopupWindow .................................................................................... 467
An OPEN LOOK Help window ...................................................................................... 468
Look of a Motif application .......................................................................................... 469
Class inheritance hierarchy of the Motif widget set .................................................... 472
Motif DrawnButton and PushButton widgets .............................................................. 472
A Motif RowColumn widget configured as a MenuBar ............................................. 473
A Motif RowColumn widget configured with four RadioBoxes ............................... 473
A Motif RowColumn widget configured as a drop-down window ............................ 474
A Motif Form widget and children ............................................................................... 474
A Motif ScrollBar .......................................................................................................... 475
A Motif SelectionBox .................................................................................................... 476
Multiple planes used to index a colormap ...................................................................... 485
A font name ....................................................................................................................... 487
A typical font server configuration ................................................................................. 491
xv/
Examples
Page
2-2 XHello: the app-defaults file ............................................................................................. 36
2-3 xgoodbye.c: complete code ............................................................................................... 41
2-4 XGoodbye: the app-defaults file ....................................................................................... 42
2-5 Using XtVaSetValues to set a widget resource ................................................................. 45
2-6 Using XtSetValues to set a widget resource ..................................................................... 47
2-7 Code fragment to set multiple resources of a widget ....................................................... 47
2-8 Code fragment to get a widget resource using XtVaGetValues ...................................... 48
2-9 Code fragment to get a widget resource using XtGetValues ........................................... 49
2-10 Alternate resource settings for xgoodbye ........................................................................ 52
3-1 xboxl.c" complete code ..................................................................................................... 60
3-2 XBox." app-defaults file ..................................................................................................... 62
3-3 XBox2: app-defaults file ................................................................................................... 68
3-4 xbox2: constraint resource settings added ........................................................................ 69
3-5 xbox3: application-defaults file ........................................................................................ 71
3-6 Creating a pop-up dialog box ............................................................................................. 72
3-7 Passing a single value to a callback function .................................................................... 77
3-8 Passing a pointer to a structure to a callback function ..................................................... 78
3-9 ANSI non-conformant callback function definition .......................................................... 79
3-10 Initializing a callback list ................................................................................................. 80
3-11 xbitmap" getting application resources ........................................................................... 81
3-12 The resource list for xbitmap4 ......................................................................................... 82
3-13 Calling XtGetApplicationResources and checking values ............................................ 85
3-14 xbitmap: specifying command-line options ................................................................... 88
3-15 The varargs interface to creating a widget ...................................................................... 93
3-16 An argument list ................................................................................................................ 95
3-17 Using an argument list in widget creation ....................................................................... 95
3-18 Setting the argument list with XtSetArg ......................................................................... 96
3-19 Incorrectly setting the argument list with XtSetArg ...................................................... 97
4-1 xbitmap 1" complete code ................................................................................................. 103
4-2 XBitmapl: application-defaults file ............................................................................... 105
4-3 xbitmap3: implementing small pixmaps by drawing into Core widgets ..................... 108
4-4 xbitmap3: creating pixmaps and GCs .............................................................................. 109
4-5 xbitmap3: the CellToggled routine ................................................................................. 111
4-6 xbitmap3: the RedrawSmallPicture routine ................................................................... 112
4-7 xbitmap3: writing a bitmap file ....................................................................................... 113
4-8 xbitmap3.c: adding a feature to a Core widget .............................................................. 116
4-9 An XtActionProc with widget and event arguments ...................................................... 117
4-10 A simple translation table ............................................................................................... 118
4-11 A complex translation table ........................................................................................... 119
4o12 XBitmap3: specifying translations in the app-defaults file ........................................ 119
4-13 Code fragment: specifying translations in the program .............................................. 121
4-14 A translation table with action parameters ................................................................... 122
4-15 xbitmap4: implementing the bitmap editor from the application ............................... 123
5-1 Code using the List widget ............................................................................................... 136
5-2 Toggle buttons used to implement radio buttons ............................................................ 138
5-3 App-defaults file for xtoggle ............................................................................................ 139
5-4 Code to make Text work for single-line text entry ......................................................... 142
5-5 Changing Text widget translations for xmh .................................................................... 145
6-1 BitmapEdiP.h: the class part and class record ............................................................... 152
6-2 BitmapEdiP.h: the instance part and instance record .................................................... 153
6-3 BitmapEdiP.h: declaring the extemal class record ........................................................ 155
6-4 BitmapEdit.c: include files .............................................................................................. 156
6-5 BitmapEdit's resource list ................................................................................................ 157
6-6 Setting the resource list into the class structure .............................................................. 160
6-7 The default translation table and the actions table ......................................................... 161
6-8 Translations in the Core class record ............................................................................... 161
6-9 BitmapEdit.c: function type declarations ....................................................................... 162
6-10 BitmapEdit.c: initialization of Core class record ........................................................ 163
6-11 BitmapEdit.c: declaring the class record pointer ......................................................... 169
6-12 BitmapEdit.c: inheriting a self-contained method ....................................................... 170
6-13 Inheriting by invoking the superclass method from a widget method ........................ 172
6-14 BitmapEdit.h: complete public header file .................................................................. 173
7-1 The initialize method ........................................................................................................ 181
7-2 Creating GCs from the initialize method ........................................................................ 184
7-3 The expose method ........................................................................................................... 186
7-4 The set_values method ..................................................................................................... 189
7-5 BitmapEdit: the resize method ........................................................................................ 192
7-6 The XtWidgetGeometry structure ................................................................................... 195
7-7 BitmapEdit: the query_geometry method ...................................................................... 196
7-8 The destroy method ........................................................................................................... 197
7-9 BitmapEdit: action routines ............................................................................................. 198
8-1 Installing accelerators in an application .......................................................................... 222
8-2 Specifying the XtNaccelerators resource from the app-defaults file ............................ 222
8-3 Conflicting translations and accelerators ........................................................................ 224
8-4 Installing accelerators from both command widgets ...................................................... 225
8-5 Accelerators resource settings for two widgets .............................................................. 225
9-1 Registering an event handler, and the handler function itself ....................................... 232
9-2 Adding a nonmaskable event handler .............................................................................. 234
9-3 Casting the event structure by declaring action routine arguments .............................. 236
9-4 Handling multiple event types in an action routine ........................................................ 236
9-5 Getting file input with XtAppAddlnput .......................................................................... 240
9-6 Reading stdin from an Xt application .............................................................................. 242
9-7 xtetris: registering a timeout and the timeout function ................................................. 243
9-8 xtetris: calling XtRemoveTimeOut ................................................................................ 244
9-9 Registering an Xt work procedure ................................................................................... 247
9-10 A work procedure to create a pop-up widget ................................................................ 247
9-11 Skeleton of a custom main loop ..................................................................................... 249
10-1 Three resources defined by the Label widget ............................................................... 256
10-2 The resource file ............................................................................................................. 267
10-3 An app-defaults file for the Spanish language .............................................................. 269
10-4 A user defaults file for color and monochrome screens ............................................... 270
xviii
10-5 Setting fallback resources in XtApplnitialize ............................................................... 271
10-6 A sample merged resource database .............................................................................. 273
10-7 Sample resource database with eliminated entries and components .......................... 273
10-8 Resource database after final elimination of entries and components ........................ 274
10-9 Resource database finalists in original form ................................................................. 275
10-10 A resource definition converting an integer to a pixmap .......................................... 283
10-11 A resource definition using XtRImmediate ................................................................ 284
10-12 A resource definition using XtRCallProc ................................................................... 285
10-13 An example of an XtResourceDefaultProc ................................................................. 285
10-14 Registering a type converter ........................................................................................ 287
10-15 Adding a converter with arguments ............................................................................ 289
10-16 Manually invoking a type converter ............................................................................ 291
10-17 A simple type converter ............................................................................................... 293
10-18 Testing for a special-case default value ...................................................................... 294
10-19 Simplified get_values_hook method of the AsciiSrc subpart of the Text widget .... 295
11-1 Setting the XtNinput resource of a Shell widget .......................................................... 306
11-2 Creating an icon pixmap, and setting XtNiconPixmap ................................................ 308
11-3 BitmapEdit: actions that highlight selection ................................................................ 315
11-4 BitmapEdit: getting the atom for a widget-specific target type ................................. 323
11-5 BitmapEdit: action to paste a selection ........................................................................ 324
11-6 BitmapEdit: converting the selection value ................................................................. 325
11-7 BitmapEdit: pasting selection in requestor_callback function ................................... 327
11-8 BitmapEdit: the lose_ownership_proc ......................................................................... 329
11-9 BitmapEdit: initializing Xmu's atom caching mechanism in the initialize method. 331
11-10 BitmapEdit: converting standard targets in the convert_proc .................................. 332
12-1 ScrollBox: the set_values method ................................................................................ 349
12-2
12-3
12-4
12-5
12-6
12-7
12-8
12-9
12-10
12-11
12-12
12-13
12-14
12-15
12-16
12-17
12-18
12-19
13-1
13-2
13-3
13-4
ScrollBox: the resize method ........................................................................................ 350
ScrollBox: the query__geometry method ...................................................................... 350
ScrollBox: private routine to lay out child widgets .................................................... 351
A basic change_managed method ................................................................................. 353
A simple geometry_manager method ............................................................................ 354
Form: the Core resource list .......................................................................................... 360
Form: constraint resource list ........................................................................................ 361
Form: constraint data structure ..................................................................................... 362
Form: class structure initialization ............................................................................. 363
Form: the Constraint initialize method ...................................................................... 366
Form: the class_part_init method ............................................................................... 366
Form: the geometry_manager method ....................................................................... 367
Form private functions: RefigureLocations and the layout method ........................ 368
Form: the LayoutChild private function .................................................................... 370
Form: the resize method .............................................................................................. 372
Form: the change_managed method ........................................................................... 374
Form: the query_geometry method ............................................................................ 375
Form: the public function for delaying calls to change_managed ........................... 375
xmenu 1: complete code ................................................................................................. 390
XMenu I: the app-defaults file ...................................................................................... 394
xmenu2: code to place pulldown menu ........................................................................ 396
XMenu2: translation portion of the app-defaults file .................................................. 398
x/x
13-5
13-6
13-7
13-8
13-9
13-10
13-11
13-12
13-13
13-14
14-1
14-2
14-3
B-1
B-2
B-3
B-4
B-5
E-1
E-2
E-3
E-4
xmenu5: actions that place, pop up, and pop down main menus and submenus ....... 400
XMenu5: translation portion of app-defaults file ........................................................ 402
xmenu7: using the SimpleMenu widget and its children ............................................ 405
XMenu7: app-defaults file ............................................................................................ 407
Sme gadget: class part and complete class structure declaration ............................... 413
Sme gadget: instance part and complete instance structure declaration ................. 414
SimpleMenu: expose method calling gadget children's expose methods ............... 416
SimpleMenu: resize method ........................................................................................ 417
SimpleMenu: the Notify action routine ..................................................................... 418
SimpleMenu.c: Setting accepts_objects in the Composite extension structure ....... 419
How to invoke XtAppErrorMsg (from AsciiSrc.c) ...................................................... 425
Common fields in a class extension record ................................................................... 438
Establishing the locale in an Xt application ................................................................. 449
Listing scalable fonts ....................................................................................................... 494
Finding derived instances of scalable fonts .................................................................... 495
Font name patterns that don't match scaled fonts .......................................................... 495
Determining if a font is scalable ..................................................................................... 496
Loading a derived instance of a scalable font ................................................................ 497
BitmapEdit: complete widget code ................................................................................ 511
BitmapEdiP.h: complete private header file .................................................................. 524
BitmapEdit.h: complete public header file .................................................................... 525
xbitmap5: complete application code ............................................................................ 527
XX
Tables
2-1
2-2
2-3
3-1
3-2
3-3
6-1
6-2
6-3
7-1
7-2
8-1
8-2
8-3
8-4
8-5
8-6
9-1
9-2
9-3
10-1
10-2
10-3
10-4
10-5
11-1
11-2
12-1
14-1
14-2
14-3
A-1
B-1
F-1
F-2
F-2
Page
Functions that Set Resources: ArgList and varargs Counterparts ................................... 45
Core Resources .................................................................................................................... 49
Label Resources .................................................................................................................. 51
Motif Resource Type Strings .............................................................................................. 84
Standard Command-line Parameters ................................................................................. 87
XrmOptionKind: Command-line Option Style Constants .............................................. 90
Resource List Constant Conventions ............................................................................... 159
Inheritance Style of Various Methods ............................................................................. 167
Summary of Xt Structure Name Conventions ................................................................ 176
XtWidgetGeometry request_mode Symbols ................................................................... 195
XtWidgetGeometry stack_mode Symbols ...................................................................... 195
Event Type Abbreviations in Translation Tables ............................................................ 206
Notify Mode Values for Enter, Leave, and Focus Events .............................................. 210
Atom Details for Various Events ..................................................................................... 211
Event Structure Fields Used As Translation Table Hints ............................................... 211
Modifiers Used in Translation Tables .............................................................................. 212
Modifier Symbols .............................................................................................................. 214
Event Masks and Event Types .......................................................................................... 231
Event Types and Event Structures ................................................................................... 238
Other Input Source Masks ................................................................................................ 239
Resource Type Strings .................................................................................................... 257
% path substitutions and their meanings ....................................................................... 265
Built-in Type Converters from XtRString ..................................................................... 281
Other Built-in Converters ............................................................................................... 283
Xmu Converters .............................................................................................................. 286
Shell Resources ............................................................................................................... 301
Target Types Suggested in ICCCM ................................................................................. 330
Return codes of geometry_manager Method ................................................................ 356
Xt Error and Warning Message Utilities ....................................................................... 425
Xt Routines That Use Default and Explicit Application Contexts ............................. 433
editres accelerators ......................................................................................................... 445
Comparison of Athena, OPEN LOOK, and Motif Widgets ............................................ 456
Geometry Specification: x and y Offsets ....................................................................... 498
Consortium Members ....................................................................................................... 540
Consortium Affiliates ....................................................................................................... 541
Index .................................................................................................................................. 545
xxi
Preface
Note that while Athena is used for the examples in this book, the techniques
described are equally applicable to and provide a good introduction to pro-
gramming with any other widget set based on Xt, such as Motif or Athena. It
is not difficult to convert an application between any of the widget sets listed
above, since all of them use the same Xt Intrinsics programming interface.
In the Preface:
Summary of Contents .......................................................................... xxv
Assumptions ........................................................................................ xxvi
Related Documents ............................................................................. xxvi
How to Use This Manual ..................................................................... xxvii
Font Conventions Used in This Manual ................................................ xxx
Request for Comments ........................................................................ xxxi
Bulk Sales Information ......................................................................... xxxi
Obtaining the X Window System Software ........................................... xxxi
Obtaining the Example Programs ........................................................ xxxii
FTP ................................................................................................ xxxii
FTPMAIL ......................................................................................... xxxiii
BITFTP ........................................................................................... xxxiii
UUCP ............................................................................................. xxxiv
Compiling the Example Programs ....................................................... xxxv
Acknowledgments .............................................................................. xxxv
Preface
This book describes how to write X Window System programs using the Xt Intrinsics library
(or simply Xt). Xt is a standard established by the X Consortium that provides an object-
oriented programming style in the C language.
The Athena widget set library provides user-interface objects to be used with Xt. Athena is
maintained by the X Consortium, but is not an X Consortium standard. However, it is widely
available and fre so that it is popular for use in public-domain and freely available pro-
grams. This book primarily describes the Xt Intrinsics, but it also provides an introduction to
Athena and uses Athena for many of the examples.
The Xt Intrinsics together with a second library such as Athena are collectively called the X
Toolkit.
Summary of Contents
The discussion of the X Toolkit is divided into three volumes: Volumes Four, Five, and Six of
the X Window System Series available from O'Reilly & Associates, Inc. Volume Six is only
for Motif programmers."
This is Volume Four, X Toolkit lntrinsics Programming Manual, Standard Edition. It pro-
vides an explanation of the X Toolkit, including tutorial material and numerous programming
examples. Arranged by task or topic, each chapter brings together a group of Xt functions,
describes the conceptual foundation on which they are based, and illustrates how they are
most often used in writing applications. This volume is structured to be useful as a tutorial
and also as a task-oriented reference.
Volume Five, X Toolkit lntrinsics Reference Manual, includes reference pages for each of the
Xt functions, as well as for the widget classes defined by Xt, organized alphabetically for
ease of reference; a permuted index; and numerous appendices and quick reference aids.
The two volumes are designed to be used together. To get the most out of the examples in
Volume Four, you will need the exact calling sequences of each function from Volume Five.
To understand fully how to use each of the functions described in Volume Five, all but the
most experienced Toolkit "hacker" will need the explanation and examples in Volume Four.
" In the summer of 1993, Volume 6 will be split into two volumes, Volume Six A, Motif Programming Manual, and
Volume Six B, Motif Reference Manual.
Preface xxv
Volumes Four and Five include material from the original Toolkit documentation provided
by MIT, though in Volume Four this material is mostly limited to the appendices. We have
done our best to incorporate all the useful information from the MIT documentation, to reor-
ganize and present it in a more useful form, and to supplement it with conceptual material,
tutorials, reference aids, and examples. In other words, this manual is not only a replacement
but is a superset of the MIT documentation.
Each reference page in Volume Five includes a detailed description of the routine similar to
that found in the Xt specification (X Toolkit Intrinsics Language Interface), plus in many
cases additional text that clarifies ambiguities and describes the context in which the routine
would be used. We have also added the definitions of structures and symbolic constants used
as arguments or returned values by the function, as well as cross-references to related refer-
ence pages and to where additional information can be found in Volume Four.
Assumptions
This book makes no assumptions about the reader's knowledge of object-oriented program-
ming or the X Window System. Readers should be proficient in the C programming lan-
guage, although examples are provided for infrequently used features of the language that are
necessary or useful when programming with the X Toolkit. In addition, general familiarity
with the principles of raster graphics will be helpful.
However, even though the Toolkit is intended to hide the low-level X interface provided by
Xlib, there are times in writing applications or widgets when Xlib functions will be necessary
because no Xt feature exists to do the same thing. This book describes the most common
occasions for using Xlib, but does not provide a reference to the particular functions
involved. Additional documentation on Xlib, such as that provided by Volume One, Xlib
Programming Manual, and Volume Two, Xlib Reference Manual, will be indispensable.
Related Documents
Several other books and a journal on the X Window System are available from O'Reilly &
Associates, Inc.:
Volume Zero
Volume One
Volume Two
Volume Three
Volume Five
Volume Six A
Volume Six B
X Protocol Reference Manual
Xlib Programming Manual
Xlib Reference Manual
X Window System User's Guide, Motif Edition and standard
edition
X Toolkit Intrinsics Reference Manual
Motif Programming Manual (Spring, 1993)
Motif Reference Manual (Spring, 1993)
xxvi X Toolkit Intrinsics Programming Manual Athena Edition
._
Volume Seven XView Programming Manual
Volume Eight X Window System Administrator's Guide
Quick Reference The X Window System in a Nutshell
PHIGS in X PHIGS Programming Manual
PHIGS Reference Manual
PEXIib PEXIib Programming Manual
PEXIib Reference Manual
The X Resource The X Resource is a journal dedicated to X programming. It con-
tains the latest information about X including articles, papers, and
documentation.
The following documents are included on the X 11 source tape (the X distribution from
MIT):
X Toolkit Intrinsics--C Language Interface, by Joel McCormack, Paul Asente,
and Ralph Swick
X Toolkit Athena Widgets--C Language Interface, by Chris D. Peterson
Xlib--C Language X Interface, by Jim Gettys, Ron Newman, and Robert
Scheifler
The following Nutshell Handbooks published by O'Reilly and Associates, Inc. are use-
ful when programming in C:
Checking C Programs with lint, by Ian Darwin
Managing Projects with make, by Andrew Oram and Steve Talbott
Using C on the UNIX System, by Dave Curry
Posix Programmer's Guide, by Donald Lewine
Practical C Programming, by Steve Oualline
Power Programming with RPC, by John Bloomer
Guide to Writing DCE Applications, by John Shirley
The following is the classic introduction to C programming:
The C Programming Language, by B. W. Kernighan and D. M. Ritchie
How to Use This Manual
Volume Four explains both application programming with widgets and widget programming
(the design and coding of new widgets).
The first four chapters treat widgets largely as "black boxes," which is appropriate consider-
ing the object-oriented philosophy of the Toolkit. These chapters also provide an overview
of many elements of the X Toolkit, and so are appropriate for all readers.
Chapter 1
Introduction to the X Window System, provides a discussion of the context in
which X programs operate. Programmers who are comfortable programming
with Xlib can skip Chapter 1.
Preface xxvii
Chapter 2 Introduction to the X Toolkit, describes the conceptual foundations underlying
Toolkit programming, and shows how to write simple programs that use widg-
ets from existing widget sets. It introduces such fundamental Toolkit pro-
gramming concepts as resources, the Translation Manager, callbacks, and
actions.
Chapter 3 More Techniques for Using Widgets, describes how to use some of the more
complex widgets found in applications, including composite widgets, con-
straint widgets, and popups. It also describes how to define application
resources and command-line options, and how to hardcode the value of widget
resources when you create a widget. Finally, it describes how to create multi-
ple top-level windows, and how to use application contexts to create applica-
tions that are more portable.
Chapter 4 An Example Application, describes a complete application, in several itera-
tions. First, it shows a simple version of the program, a bitmap editor, as it
would be written assuming the existence of a BitmapEdit widget (which is
actually developed in Chapter 6). Then, two refined versions are developed,
each demonstrating additional Toolkit programming techniques. Finally, the
same application is shown as it would be written if the bitmap editor were
implemented in an application window rather than with the BitmapEdit
widget, as it would be written if no BitmapEdit widget existed.
Chapter 5 The Athena Widget Set, describes and illustrates the widgets available in the
Athena widget set, and provides some basic programming tips to help you use
them effectively. As mentioned earlier, this volume does not contain detailed
reference information on each widget, and it gives examples using only a few
of the widgets in the Athena widget set.
The next two chapters describe widget internals and the process of creating new widgets.
Although this information is not essential for all application programmers, many applications
require a custom widget to implement their special graphics capabilities.
Chapter 6 Inside a Widget, describes the code inside a widget. Much of this code is
common to all widgets. You can think of it as a framework that Xt uses to
implement a widget's features. After reading this chapter, you should under-
stand the procedure for creating your own widget around this framework.
Chapter 7 Basic Widget Methods, describes a widget's initialize, expose,
set_values, destroy, resize, and query_geometry methods. (A
widget's methods are internal routines called automatically by Xt to give the
widget a degree of independence from the application.) The chapter explains
when Xt calls each method, and describes in detail what should be in each of
these methods. Among other things, these methods prepare for and do the
drawing of graphics that appear in a widget. This chapter describes what the
Toolkit adds to the graphics model provided by Xlib but does not describe in
detail how to draw using Xlib; this topic is described in Chapters 5, 6, and 7 of
Volume One, Xlib Programming Manual.
xxviii
X Toolkit Intfinsics Programming Manual, Athena Edition
..
Later chapters treat various topics of interest to either application or widget programmers, or
both. Some of these topics have been introduced in the earlier chapters and are explored
more completely in the following ones.
Chapter 8 Events, Translations, and Accelerators, describes the complete syntax of
translation tables, which allow the user to configure the mapping of event
sequences into widget actions. It also describes accelerators, a mechanism for
mapping events in one widget to actions in another.
Chapter 9 More Input Techniques, describes how to handle events with event handlers
and how to use information from the event structure inside an event handler or
action routine. It also describes how to get file, pipe, or socket input, how to
use timeouts to call a function after a delay or at particular intervals, and how
to use work procedures to do background processing. Finally, it discusses
some low-level features of Xt for directly interacting with the event queue.
Resource Management and Type Conversion, is a more thorough discussion of
how resources work and how they should be used. This chapter describes in
detail the resource file format and the rules that govern the precedence of
resource settings. It also describes how to add your own type converter so that
you can set application- or widget-specific data through resources. Finally, it
describes subresources and how to use them.
Interclient Communications, discusses communication through the X server
between an application and the window manager, and between two applica-
tions. The application-window manager communication is performed by code
in the Shell widget; the application sets shell resources to control this commu-
nication. Application-application communication is usually done with a pro-
cess called selections; this form of communication is already implemented in
most widgets that display text, but you may want to implement it in your own
custom widgets. Selections can also pass other kinds of data such as graphics.
Geometry Management, discusses how composite and constraint widgets man-
age the layout of widgets, and how to write your own simple composite and
constraint widgets.
Menus, Gadgets, and Cascaded Popups, describes how menus work and
describes several ways to create menu widgets. One of these ways involves
the use of windowless widgets, or gadgets. This chapter also describes how to
use more advanced features of the Xt pop-up mechanism, including modal
cascades, to implement cascading pop-up menus.
Miscellaneous Toolkit Programming Techniques, describes various Xt func-
tions and techniques that have not been treated elsewhere in the book. These
include functions for error and warning handling, case conversion, using edi-
tres, and so on.
Athena, OPEN LOOK, and Motif, provides a comparison of the widgets avail-
able in AT&T's OPEN LOOK widget set and OSF's Motif. These widgets are
contrasted with those in the Athena widget set.
Chapter 10
Chapter 11
Chapter 12
Chapter 13
Chapter 14
Appendix A
Preface xxix
Obtaining the Example Programs
The example programs in this book are available electronically in a number of ways: by ftp,
ftpmail, biotp, and uucp. The cheapest, fastest, and easiest ways are listed first. If you read
from the top down, the first one that works for you is probably the best. Use ftp if you are
directly on the Intemet. Use ftpmail if you are not on the Intemet but can send and receive
electronic mail to intemet sites (this includes CompuServe users). Use BITFTP if you send
electronic mail via BITNET. Use UUCP if none of the above works.
FTP
To use FTP, you need a machine with direct access to the Internet. A sample session is
shown, with what you should type in boldface.
% ftp ftp.uu.net
Connected to ftp.uu.net.
220 FTP server (Version 6.21 Tue Mar i0 22:09:55 EST 1992) ready.
Name (ftp.uu.net :kismet) : anonymous
331 Guest login ok, send domain style e-mail address as password.
Password: ki smet@ora, corn (use your user name and host here)
230 Guest login ok, access restrictions apply.
ftp> cd /published/oreilly/xbook/xt
250 CWD conmand successful.
ftp> binary (Very important{ You must specify binary transfer for compressed files )
200 Type set to I.
ftp> get xtprog3, tar. Z
200 PORT conmnnd successful.
150 Opening BINARY mode data connection for xtprogs2.tar.Z.
226 Transfer complete.
ftp> quit
221 Goodbye.
%
If the file is a compressed tar archive, extract the files from the archive by typing:
% zcat xtprogs2, tar. Z I tar xf -
System V systems require the following tar command instead:
% zcat xtprogs2.tar. Z [ tar xof -
If zcat is not available on your system, use separate uncompress and tar commands.
If the file is a compressed shar archive, you can extract the files from the archive by typing:
% uncompress FILE. shar. Z
% /bin/sh FILE. shar
xxxii X Toolkit Intrinsics Programming Manual Athena Edition
FTPMAIL
PTPMAIL is a mail server available to anyone who can send and receive electronic mail to
and from lnternet sites. This includes most workstations that have an email connection to the
outside world, and CompuServe users. You do not need to be directly on the Internet. Here's
how to do it.
You send mail toftpmail@decwrl.dec.com. In the message body, give the name of the anon-
ymousftp host and the ftp commands you want to run. The server will run anonymousftp for
you and mail the files back to you. To get a complete help file, send a message with no sub-
ject and the single word "help" in the body. The following is an example mail session that
should get you the examples. This command sends you a listing of the files in the selected
directory, and the requested examples file. The listing is useful in case there's a later version
of the examples you're interested in.
% mail ftpmail@decwrl.dec.com
Subj ect :
reply j erry@ora, com (where you want files mailed)
connect ftp. uu. net
chdir /published/oreilly/xbook/xt
dir
binary
uuencode (or btoa if you have it)
get xtprogs2, tar. Z
quit
A signature at the end of the message is acceptable as long as it appears after "quit."
All retrieved files will be split into 60KB chunks and mailed to you. You then remove the
mail headers and concatenate them into one file, and then uudecode or atob it. Once you've
got the desired file, follow the directions under FTP to extract the files from the archive.
VMS, DOS, and Mac versions of uudecode, atob, uncompress, and tar are available. The
VMS versions are on gatekeeper.dec.com in/archive/pub/VMS.
BITFTP
BITPTP is a mail server for BITNET users. You send it electronic mail messages requesting
files, and it sends you back the files by electronic mail. BITP'YP currently serves only users
who send it mail from nodes that are directly on BITNET, EARN, or NetNorth. BITPTP is a
public service of Princeton University. Here's how it works.
To use BITPTP, send mail containing yourftp commands to BITFTP@PUCC. For a complete
help file, send HELP as the message body.
The following is the message body you should send to BITP'YP:
FTP ftp. uu. net NETDATA
USER anonymous
PASS your Internet email address (not your bitnet address)
CD /published/oreilly/xbook/xt
Preface xxxiii
DIR
BINARY
GET xtprogs2, tar. Z
QUIT
Once you've got the desired file, follow the directions under FFP to extract the files from the
archive. Since you are probably not on a UNIX system, you may need to get versions of
uudecode, uncompress, atob, and tar for your system. VMS, DOS, and Mac versions are
available. The VMS versions are on gatekeeper.dec.com in/archive/pub/VMS.
Questions about BITFTP can be directed to Melinda Varian, MAINT@PUCC on BITNET.
UUCP
UUCP is standard on virtually all UNIX systems, and is available for IBM-compatible PCs and
Apple Macintoshes. The examples are available by UUCP via modem from UUNET;
UUNET's connect-time charges apply.
You can get the examples from UUNET whether you have an account or not. If you or your
company has an account with UUNET, you will have a system with a direct UUCP connection
to UUNET. Find that system, and type:
uucp uunet\ ! /published/ oreilly /xbook/xt /xtprogs2 . tar. Z yourhos.~/yourname/
The backslashes can be omitted if you use the Bourne shell (sh) instead of csh. The file
should appear some time later (up to a day or more) in the directory /usr/spool/uucppub-
lic/yournatne. If you don't have an account but would like one so that you can get electronic
mail, then contact UUNET at 703-204-8000.
If you don't have a UUNET account, you can set up a UUCP connection to UUNET using the
phone number 1-900-468-7727. As of this writing, the cost is 50 cents per minute. The
charges will appear on your next telephone bill. The login name is "uucp" with no password.
For example, an L.sys/Systems entry might look like:
uunet Any ACU 19200 1-900-468-7727 ogin:--ogin: uucp
Your entry may vary depending on your UUCP configuration. If you have a PEP-capable
modem, make sure s50=255s I 11 =30 is set before calling.
It's a good idea to get the file/published/oreilly/xbook/xt/ls-lR.Z as a short test file containing
the filenames and sizes of all the files in the directory.
Once you've got the desired file, follow the directions under FFP to extract the files from the
archive.
xxxiv X Toolkit Intrinsics Programming Manual, Athena Edition
..
Compiling the Example Programs
Once you've got the examples and unpacked the archive as described previously, you're
ready to compile them. The easiest way is to use imake, a program supplied with the X I 1
distribution that generates proper Makefiles on a wide variety of systems, imake uses confi-
guration files called lmakefiles which are included. If you have imake, you should go to the
top-level directory containing the examples, and type:
% make Makefiles
% make
All the application-defaults files are in the main examples directory. The application-
defaults files are not automatically installed in the system application-defaults directory
(usually/usr/lib/Xll/app-defaults on UNIX systems).1- If you have permission to write to that
directory, you can copy them there yourself. Or you may set the XAPPLRESDIR environment
variable to the complete path of the directory where you installed the examples. The value of
XAPPLRESDIR must end with a / (slash). (Most of the examples will not function properly
without the application-defaults files.)
Acknowledgments
As mentioned before, this manual includes some material from the X Toolkit lntrin-
sics Language Interface, by Joel McCormack, Paul Asente and Ralph Swick. This is the
document that defines the X Consortium standard for Xt, known as the Xt specification.
Overt borrowings from the Xt specification are rare in this volume. However, the Xt specifi-
cation document, as well as the sample code of Xt distributed with releases of X, provides the
intellectual basis for most of what appears here. Many thanks to the X Consortium for their
copyright policy that allows others to build on their work.
We'd like to thank Sony Microsystems for the loan of a Sony NEWS workstation running
their implementation of the X Window System. The speed and power of the Sony worksta-
tion, and the support of Sony's staff, were a great help in developing these books. Additional
development was done on a Sun-3 workstation running MIT's sample server, a Visual 640 X
Display Station, and an NCD 16 Network Display Station.
We would also like to thank the reviewers of the Alpha draft of this book, even though we
almost had to start over because of their comments. They were David Lewis of Integrated
Computer Solutions (ICS), Wendy Eisner of Sunquest Information Systems, Dan Heller of
Island Graphics, Inc. (now working with O'Reilly and Associates), Miles O'Neal of Systems
and Software Solutions, Inc., and Chris Peterson of MIT Project Athena (now of the X Con-
sortium), lan Darwin of SoftQuad and Bradley Ross of Cambridge Computer Associates
% On Sun systems under OpenWindows it is usually/usr/openwin/lib/app-defaults.
Preface xxxv
1
Introduction to the X Window System
This chapter introduces many of the most important concepts on which the X
Window System is based, and describes the environment in which the X
Toolkit operates. This chapter assumes that you are new to programming
the X Window System. If you already have some experience programming
the X Window System, you may wish to skim this chapter for a brief review
or even begin with Chapter 2.
In This Chapter:
The Server and Client ............................................................................ 6
The Software Hierarchy ......................................................................... 8
Event-driven Programming .................................................................. 10
The Window Manager .......................................................................... 11
Extensions to X ................................................................................... 12
1
Introduction to the X Window System
The X Window System (or simply X)I- is a hardware- and operating system-independent win-
dowing system. It was developed jointly by MIT and Digital Equipment Corporation, and
has been adopted by the computer industry as a standard for graphics applications.
X controls a "bit-mapped" display in which each pixel on the screen is individually controll-
able. This allows applications to draw pictures as well as text. Until recently, individual
control of screen pixels was widely available only on personal computers (PCs) and high-
priced technical workstations. Most general-purpose machines were limited to output on
text-only terminals. X brings a consistent world of graphic output to both PCs and more
powerful machines. Figure 1-1 compares an X application to an application running on a tra-
ditional text terminal.
text terminal
X window system
Figure 1-1. An X application, and an application on a traditional text terminal
fThe name "X Windows" is frowned upon by the developers of X.
Introduction to the X Window System 3
inside its border. The application or the user can change the dimensions of windows. Figure
1-3 shows a typical screen with several virtual terminals running. The screen also shows
some applications, such as xterm, oclock, and xcalc, that run in their own windows
xterm window
(typical of 3)
root window - . -
Figure 1-3. Screen layout of a typical user's X Window System
X supports both color and black-and-white displays.
Many of the above characteristics are also true of several other window systems. What is
unusual about X is that it is based on a network protocol instead of on system-specific proce-
dure and system calls. This network protocol enables X to be ported to different computer
architectures and operating systems; it also allows programs to run on one architecture or
operating system while displaying on another. Because of its unique design, X can make a
network of different computers cooperate. For example, a computationally intensive applica-
tion might run on a supercomputer, but take input from and display output on a workstation
connected across a local area network. To the user, the application would simply appear to
be running on the workstation.
1.1 The Server and Client
To allow programs to be run on one machine and display on another, X was designed as a net-
work protocol--a predefined set of requests and replies--between two processes. One of
these processes is an application program called a client, and the other, the server, controls
the display hardware, keyboard, and pointer.
The user sits at the machine running the server. At first, this use of the word "server" may
seem a little odd, since file and print servers normally are remote machines, but the usage is
consistent. The local display is accessible to other systems across the network, and for those
systems the X server does act like other types of server.
Introduction to the X Window System 5
Personal Computer
Supercomputer
Ir
Local
Client
Display Server
Large Minicomputer
Figure 1-4. Applications can run on any system across the network
This use of the network is known as distributed processing. It allows graphic output for pow-
erful systems that don't have their own built-in graphics facilities. Distributed processing
can also help solve the problem of unbalanced system loads. When one host machine is over-
loaded, users running clients on that machine can arrange for some of their clients to run on
other hosts. Eventually there may be automatic load-balancing applications, but currently
such remote execution is performed manually. It is not unusual to see users in the X environ-
ment having several xload load monitor applications running on various systems throughout
the network but displaying on their screen, so that they can see the balance of loads through-
out the network.
Before leaving the subject of servers and clients, we should mention PC servers and X termi-
nals. Software is available that allows various types of PCs to operate as X servers.'t" X ter-
minals are special-purpose devices designed to run just an X server, and to connect to remote
systems over a local area network. PC servers and X terminals are the least expensive way to
provide an X screen for a user. Since most PCs use single-tasking operating systems, they
can't run any clients at the same time as the server. Therefore, they too require a network
adapter to connect to another system where clients are run.
" Companies such as Graphics Software Systems, Interactive Systems, and Locus Computing offer server implemen-
tations for IBM-compatible PCs. White Pine Software offers an X server that runs under Multifinder on the Macin-
tosh. An Amiga server is available from GfxBase/Boing. X terminals are available from Visual Technology, NCR,
Network Computing Devices (NCD), Tektronix, Graphon Corp, and other companies. The number of X products on
the market is growing rapidly.
Introduction to the X Window System 7
Xt is built upon Xlib. The purpose of Xt is to provide an object-oriented layer that supports
the user-interface abstraction called a widget. A widget is a reusable, configurable piece of
code that operates independently of the application except through prearranged interactions.
A widget set is a collection of widgets that provide commonly used user-interface compo-
nents tied together with a consistent appearance and user interface (also called look and feel).
Several different widget sets are available from various vendors that are designed to work
with Xt. The use of widgets separates application code from user-interface code and pro-
vides ready-to-use user-interface components such as buttons and scrollbars. Xt, widgets,
and widget sets are described in much more detail in Chapter 2, Introduction to the X Toolkit.
In this book, we'll refer to the combination of the Xt lntrinsics and one widget set as the X
Toolkit or just the Toolkit. When referring to the Xt lntrinsics layer alone, we'll use Xt, or the
Intrinsics.
Applications often need to call Xlib directly to accomplish certain tasks such as drawing. Xt
does not provide its own graphics calls, nor does it provide access to every X protocol fea-
ture. This book describes the features of Xlib that you may need from an Xt application, but
it will not repeat the detailed description of Xlib programming found in Volume One, Xlib
Programming Manual. You will find Volume One and Volume Two, Xlib Reference Manual,
invaluable when you need to make Xlib calls.
Xlib, Xt, and several widget sets are available on MIT's public software distribution. The
Motif and OPEN LOOK widget sets are not on the Release 4 or 5 distributions from MIT, but
they are available for minimal cost from the vendors themselves (OSF, AT&T, or Sun,
respectively.) The darkly shaded areas of Figure !-5 indicate interfaces that are exclusive
standards of the X Consortium. That Xlib is an exclusive standard means that computer man-
ufacturers wishing to comply with the X Consortium standard must offer Xlib and cannot
offer any other low-level X interface in C. The lightly shaded areas (such as the Xt Intrin-
sics) are nonexclusive standards--vendors are required t 9 provide Xt but are also allowed to
provide other toolkit-level layers for the C Language. For example, Sun and AT&T offer Xt,
but they also offer XView as an alternate C-Language toolkit-level layer. XView was origi-
nally designed for porting existing SunView TM applications to X, but it can also be used for
writing new applications. Volume Seven, XView Programming Manual, describes program-
ming with XView.
X software is unlike that of many other window systems in that it was designed to provide
mechanism without mandating any certain style of user interface. In the words of its design-
ers, X provides "mechanism without policy." The Xlib and Xt layers are standard because
they can support any kind of interface. It is the widget set that actually imposes user-inter-
face conventions, and it is this layer for which no standard has yet been considered by the X
Consortium. However, because there is a strong need in the market for one or two standard
widget sets that provide consistent appearance and user-interface conventions, it is likely that
one or two widget sets will emerge as de-facto standards in the near future.
It is important to note that the X Consortium standards for Xlib and Xt define the program-
ming interface to each library (often referred to as the Application Programmer's Interface,
or API), not the underlying code. This means that vendors are allowed to modify or rewrite
the code to gain the best performance from their particular system, as long as they keep the
programming interface the same. To you, the application writer and user of the Intrinsics,
this means that you must always rely on documented behavior if you want your application to
Introduction to the X Window System 9
run on different systems. You must avoid accessing private structures, because they may be
different in another vendor's release of the library, or they may be changed in a future release
of X.
1.3 Event-driven Programming
Programming a graphically-based window system is fundamentally different from standard
procedural programming. In traditional character-based interfaces, once the application
starts, it is always in control. It knows only what kind of input it will allow, and may define
exclusive modes to limit that input. For example, the application might ask the user for input
with a menu, and use the reply to go down a level to a new menu, where the actions that were
possible at the previous level are no longer available. Or a text editor may operate in one
mode in which keyboard input is interpreted as editor commands, and another in which it is
interpreted as data to be stored in an editor buffer. In any case, only keyboard input is
expected.
In a window system, by contrast, multiple graphic applications may be running simulta-
neously. In addition to the keyboard, the user can use the pointer to select data, click on but-
tons or scrollbars, or change the keyboard focus from one application to another. Except in
special cases (for example, where a "dialog box" will not relinquish control until the user
provides some necessary information), applications are modeless--the user can suddenly
switch from the keyboard to the mouse, or from one application area to another. Further-
more, as the user moves and resizes windows on the screen, application windows may be
obscured or redisplayed. The application must be prepared to respond to any one of many
different events at any time.
An X event is a data structure sent by the server that describes something that just happened
that may be of interest to the application. There are two major categories of events: user
input and window system side effects. For example, the user pressing a keyboard key or
clicking a mouse button generates an event; a window being moved on the screen also gener-
ates events--possibly in other applications as well if the movement changes the visible por-
tions of their windows. It is the server's job to distribute events to the various windows on
the screen.
Event-driven window programming reduces modes to a minimum, so that the user does not
need to navigate a deep menu structure and can perform any action at any time. The user, not
the application, is in control. The application simply performs some setup and then goes into
a loop from which application functions may be invoked in any order as events arrive.
10 X Toolkit Intrinsics Programming Manual Athena Edition
1.4 The Window Manager
Because multiple applications can be running simultaneously, rules must exist for arbitrating
conflicting demands for input. For example, does keyboard input automatically go to which-
ever window the pointer is in, or must the user explicitly select a window? How does the
user move or resize windows?
Unlike most window systems, X itself makes no rules about this kind of thing. Instead, there
is a special client called the window manager that manages the positions and sizes of the
main windows of applications on a server's display. In Motif, this client is mwm. The win-
dow manager is just another client, but by convention it is given special responsibility to
mediate competing demands for the physical resources of a display, including screen space,
color resources, and the keyboard. The window manager allows the user to move windows
around on the screen, resize them, and usually start new applications. The window manager
also defines much of the visible behavior of the window system, such as whether windows
are allowed to overlap or are forced to tile (side by side), and whether the keyboard focus
simply follows the pointer from one window to the next window, or whether the user must
click a pointer button in a window to change the keyboard focus.
Applications are required to give the window manager certain information to help it mediate
competing demands for screen space or other resources. For example, an application speci-
fies its preferred size and size increments. These are known as window manager hints
because the window manager is not required to honor them. The Toolkit provides an easy
way for applications to set window manager hints.
The conventions for interaction with the window manager and with other clients have been
standardized by the X Consortium in a manual called the Inter-Client Communication Con-
ventions Manual (ICCCM for short). The ICCCM defines basic policy intentionally omitted
from X itself, such as the rules for transferring selections of data between applications, for
transferring keyboard focus, for installing colormaps, and so on.
As long as applications and window managers follow the conventions set out in the ICCCM,
applications created with different toolkits will be able to coexist and work together on the
same server. Toolkit applications should be immune to the effects of changes from earlier
conventions because the conventions are implemented by code hidden in a standard widget
called Shell. However, you should be aware that some older applications and window man-
agers do not play by the current rules.
Introduction to the X Window System 11
1.5 Extensions to X
X is also extensible. The code includes a defined mechanism for incorporating extensions, so
that vendors aren't forced to modify the existing system in incompatible ways when adding
features. An extension requires an additional piece of software on the server side and an
additional library at the same level as Xlib on the client side. After an initial query to see
whether the server portion of the extension software is installed, these extensions are used
just as Xlib routines and perform at the same level.
As time goes on, some extensions will become a basic part of what is called "X," and will
become X Consortium standards themselves. For example, as of Release 5 the X Consortium
has standardized three extensions: the non-rectangular window Shape extension, the X Input
extension for supporting input devices other than the keyboard and mouse, and PEX for 3-D
graphics. The only one of these libraries that is widely available on X servers, and is com-
monly used in conjunction with Xt, is the Shape extension. The C programming library used
to access the Shape extension is -1Xext.
12 X Toolkit Intrinsics Programming Manual, Athena Edition
2
Introduction to the X Toolkit
This chapter provides a conceptual introduction to the X Toolkit (including the
Athena widget set), followed by a practical tutorial that starts with the most
fundamental toolkit program, a "hello world" type application consisting of
only a single widget. This application is successively refined until the major
elements of any X Toolkit program have been introduced.
In This Chapter:
Programming with Widgets .................................................................. 15
About Widget Sets ........................................................................... 18
Widget Classes and Instances ......................................................... 20
Widget Configurability with Resources ............................................. 23
Widget Independence ...................................................................... 24
Widget-Application Interaction .......................................................... 26
Xt and Object-oriented Programming (OOP) ........... 
