CONTENTS Title Page Copyright Page Preface 1 Programming Overview of Xlib 1.1 Overview of Xlib 1.2 Sample Xlib Program 1.2.1 Sample Initialization Routine 1.2.1.1 Creating Windows 1.2.1.2 Defining Colors 1.2.1.3 Working with the Window Manager 1.2.1.4 Making Windows Visible on the Screen 1.2.2 Sample Event-Handling Routine 1.3 Handling Error Conditions 1.4 Debugging Xlib Programs 2 Managing the Client-Server Connection 2.1 Overview of the Client-Server Connection 2.2 Establishing the Client-Server Connection 2.3 Closing the Client-Server Connection 2.4 Getting Information About the Client-Server Connection 2.5 Managing Requests to the Server 3 Working with Windows 3.1 Window Fundamentals 3.1.1 Window Hierarchy 3.1.2 Window Position 3.1.3 Window Visibility and Occlusion 3.2 Creating Windows 3.2.1 Using Attributes of the Parent Window 3.2.2 Defining Window Attributes 3.3 Destroying Windows 3.4 Mapping and Unmapping Windows 3.5 Associating Properties with Windows 3.6 Exchanging Properties Between Clients 3.7 Changing Window Characteristics 3.7.1 Reconfiguring Windows 3.7.2 Effects of Reconfiguring Windows 3.7.3 Changing Stacking Order 3.7.4 Changing Window Attributes 3.8 Getting Information About Windows 4 Defining Graphics Characteristics 4.1 The Graphics Context 4.2 Defining Multiple Graphics Characteristics in One Call 4.3 Defining Individual Graphics Characteristics 4.4 Copying, Changing, and Freeing Graphics Contexts 4.5 Using Graphics Characteristics Efficiently 5 Using Color 5.1 Pixels and Color Maps 5.1.1 Installing Color Maps 5.2 Matching Color Requirements to Display Types 5.2.1 Visual Types 5.2.2 Determining the Default Visual Type 5.2.3 Determining Multiple Visual Types 5.3 Sharing Color Resources 5.3.1 Using Named Colors 5.3.2 Specifying Exact Color Values 5.4 Allocating Colors for Exclusive Use 5.4.1 Specifying a Color Map 5.4.2 Allocating Color Cells 5.4.3 Storing Color Values 5.5 Freeing Color Resources 5.6 Querying Color Map Entries 6 Drawing Graphics 6.1 Graphics Coordinates 6.2 Using Graphics Routines Efficiently 6.3 Drawing Points and Lines 6.3.1 Drawing Points 6.3.2 Drawing Lines and Line Segments 6.4 Drawing Rectangles and Arcs 6.4.1 Drawing Rectangles 6.4.2 Drawing Arcs 6.5 Filling Areas 6.5.1 Filling Rectangles and Arcs 6.5.2 Filling a Polygon 6.6 Clearing and Copying Areas 6.6.1 Clearing Window Areas 6.6.2 Copying Areas of Windows and Pixmaps 6.7 Defining Regions 6.7.1 Creating Regions 6.7.2 Managing Regions 6.8 Defining Cursors 6.8.1 Creating Cursors 6.8.2 Managing Cursors 6.8.3 Destroying Cursors 7 Using Pixmaps and Images 7.1 Creating and Freeing Pixmaps 7.2 Creating and Managing Bitmaps 7.3 Working with Images 8 Writing Text 8.1 Characters and Fonts 8.2 Specifying Fonts 8.3 Getting Information About a Font 8.4 Freeing Font Resources 8.5 Computing the Size of Text 8.6 Drawing Text 8.7 Font Usage Hints 8.7.1 Font Fallback Strategy 8.7.2 Speeding Up Font Name Searches 8.7.3 Monitor Density Independence 8.7.4 Character Set Considerations 9 Handling Events 9.1 Event Processing 9.2 Selecting Event Types 9.2.1 Using the SELECT INPUT Routine 9.2.2 Specifying Event Types When Creating a Window 9.2.3 Specifying Event Types When Changing Window Attributes 9.3 Pointer Events 9.3.1 Handling Button Presses and Releases 9.3.2 Handling Pointer Motion 9.4 Window Entries and Exits 9.4.1 Normal Window Entries and Exits 9.4.2 Pseudomotion Window Entries and Exits 9.5 Input Focus Events 9.6 Exposure Events 9.6.1 Handling Window Exposures 9.6.2 Handling Graphics Exposures 9.7 Key Events 9.8 Window State Notification Events 9.8.1 Handling Window Circulation 9.8.2 Handling Changes in Window Configuration 9.8.3 Handling Window Creations 9.8.4 Handling Window Destructions 9.8.5 Handling Changes in Window Position 9.8.6 Handling Window Mappings 9.8.7 Handling Key, Keyboard, and Pointer Mappings 9.8.8 Handling Window Reparenting 9.8.9 Handling Window Unmappings 9.8.10 Handling Changes in Window Visibility 9.9 Key Map State Events 9.10 Color Map State Events 9.11 Client Communication Events 9.11.1 Handling Event Notification from Other Clients 9.11.2 Handling Changes in Properties 9.11.3 Handling Changes in Selection Ownership 9.11.4 Handling Requests to Convert a Selection 9.11.5 Handling Requests to Notify of a Selection 9.12 Event Queue Management 9.12.1 Checking the Contents of the Event Queue 9.12.2 Returning the Next Event on the Queue 9.12.3 Selecting Events That Match User-Defined Routines 9.12.4 Selecting Events Using an Event Mask 9.12.5 Putting Events Back on Top of the Queue 9.12.6 Sending Events to Other Clients 9.13 Error Handling 9.13.1 Enabling Synchronous Operation 9.13.2 Using the Default Error Handlers 9.13.3 Confirming X Resource Creation 10 Using the X Resource Manager 10.1 Defining Resource Manager Fundamentals 10.1.1 Names and Classes 10.1.2 Forming Names and Classes 10.1.3 Resource Manager Matching Rules 10.2 Getting the Default Values 10.3 Storing Resources into a Database 10.4 Retrieving from the Resource Database 10.5 Merging and Storing Databases 10.6 Using Representations for Strings 10.6.1 Converting a String to a Quark 10.6.2 Retrieving Resources with Quarks 11 Using Grabs 11.1 Grab Fundamentals 11.1.1 Event Reporting 11.1.2 Active and Passive Grabs 11.2 Pointer Grabs 11.3 Button Grabs 11.4 Key and Keyboard Grabs 11.5 Allowing Events 12 Complying with Inter-Client Communications Conventions 12.1 Communicating with Standard Properties 12.2 Manipulating Top-Level Windows 12.3 Defining Window Manager Properties 12.3.1 Setting Window Manager Hints 12.3.2 Providing Size Hints 12.3.3 Setting Window and Icon Names 12.3.4 Example of Setting Properties 12.3.5 Using the SET WM PROPERTIES Routine A Compiling Fonts B VMS DECwindows Named Colors C VMS DECwindows Fonts EXAMPLES 1-1 Sample Xlib Program 3-1 Creating a Simple Window 3-2 Defining Attributes When Creating Windows 3-3 Mapping and Raising Windows 3-4 Exchanging Window Properties 3-5 Reconfiguring a Window Using the CONFIGURE WINDOW Routine 3-6 Changing Window Attributes 4-1 Defining Graphics Characteristics Using the CREATE GC Routine 4-2 Using Individual Routines to Define Graphics Characteristics 5-1 Matching Visual Information 5-2 Using Named VMS DECwindows Colors 5-3 Specifying Exact Color Values 5-4 Allocating Colors for Exclusive Use 6-1 Drawing Multiple Points 6-2 Drawing Multiple Lines 6-3 Drawing Multiple Rectangles 6-4 Drawing Multiple Arcs 6-5 Filling a Polygon 6-6 Clearing a Window 6-7 Defining a Region Using the POLYGON REGION Routine 6-8 Defining the Intersection of Two Regions 6-9 Creating a Pixmap Cursor 7-1 Creating a Pixmap 7-2 Creating a Bitmap Data File 7-3 Creating a Pixmap from Bitmap Data 8-1 Drawing Text Using the DRAW TEXT Routine 8-2 Drawing Text Using the DRAW STRING Routine 9-1 Selecting Event Types Using the CREATE WINDOW Routine 9-2 Handling Button Presses 9-3 Handling Pointer Motion 9-4 Handling Window Entries and Exits 9-5 Handling Graphics Exposures 10-1 Using the GET DEFAULT Routine 10-2 Creating and Storing into the Database 10-3 Retrieving a Resource from the Database 10-4 Merging and Storing Databases 10-5 Converting a String to a Quark 10-6 Retrieving Quarks 11-1 Grabbing the Pointer 11-2 Grabbing a Button 11-3 Grabbing a Key 12-1 Reconfiguring a Top-Level Window 12-2 Setting Window Manager Properties 12-3 Using the SET WM PROPERTIES Routine FIGURES 1-1 Client, Xlib, and Server 2-1 Graphics Output to Instructor VAXstation 2-2 Graphics Output to Student VAXstations 3-1 Root Window and One Child 3-2 Relationship Between Second-Level Windows 3-3 Relationship Between Third-Level Windows 3-4 Coordinate System 3-5 Window Before Restacking 3-6 Restacked Window 3-7 Reconfigured Window 3-8 East Bit Gravity 3-9 Northwest Window Gravity 4-1 Bounding Box 4-2 Line Styles 4-3 Butt, Round, and Projecting Cap Styles 4-4 Cap Not Last Style 4-5 Join Styles 4-6 Fill Rules 4-7 Pixel Boundary Cases 4-8 Styles for Filling Arcs 4-9 Dashed Line Offset 4-10 Dashed Line 4-11 Line Defined Using GC Routines 5-1 Pixel Values and Planes 5-2 Color Map, Cell, and Index 5-3 Visual Types and Color Map Characteristics 5-4 Polygons That Define the Color Wheel 6-1 Circles of Points Created Using the DRAW POINTS Routine 6-2 Star Created Using the DRAW LINES Routine 6-3 Rectangle Coordinates and Dimensions 6-4 Rectangle Drawing 6-5 Rectangles Drawn Using the DRAW RECTANGLES Routine 6-6 Multiple Arcs Drawn Using the DRAW ARCS Routine 6-7 Filled Star Created Using the FILL POLYGON Routine 6-8 Arcs Drawn Within a Region 6-9 Intersection of Two Regions 6-10 Cursor Shape and Cursor Mask 7-1 XY Bitmap Format 7-2 XY Pixmap Format 7-3 Z Format 8-1 Composition of a Character 8-2 Composition of a Slash 8-3 Single-Row Font 8-4 Multiple-Row Font 8-5 Indexing Single-Row Font Character Metrics 8-6 Indexing Multiple-Row Font Character Metrics 8-7 Atoms and Font Properties 9-1 Window Entries and Exits 9-2 Window Scrolling 10-1 Interface of Client xgr 10-2 Hierarchy of Names and Classes of the Client xgr 10-3 String and Quark Routines Operation TABLES 2-1 Output Buffer Routines 3-1 Set Window Attributes Data Structure Members 3-2 Default Values of the Set Window Attributes Data Structure 3-3 Set Window Attributes Data Structure Flags 3-4 Predefined Atoms 3-5 Routines for Managing Properties 3-6 Window Changes Data Structure Members 3-7 Stacking Values 3-8 Window Changes Data Structure Flags 3-9 Window Configuration Routines 3-10 Gravity Definitions 3-11 Routines for Changing Window Attributes 3-12 Window Information Routines 4-1 GC Data Structure Default Values 4-2 GC Values Data Structure Members 4-3 GC Values Data Structure Flags 4-4 Routines That Define Individual or Functional Groups of Graphics Characteristics 5-1 Visual Info Data Structure Members 5-2 Color Data Structure Members 6-1 Point Data Structure Members 6-2 Segment Data Structure Members 6-3 Rectangle Data Structure Members 6-4 Arc Data Structure Members 6-5 Routines for Managing Regions 6-6 Predefined VMS DECwindows Cursors 7-1 Image Data Structure Members 7-2 Routines That Change Images 8-1 Char Struct Data Structure Members 8-2 Char 2B Data Structure Members 8-3 Font Struct Data Structure Members 8-4 Font Prop Data Structure Members 8-5 Atom Names of Font Properties 8-6 Complimentary Font Routines 8-7 Text Item Data Structure Members 8-8 Text Item 16 Data Structure Members 8-9 Fonts Not Recommended for General Use 9-1 Event Types 9-2 Any Event Data Structure Members 9-3 Event Masks 9-4 Values Used for Grabbing Buttons 9-5 Button Event Data Structure Members 9-6 Motion Event Data Structure Members 9-7 Crossing Event Data Structure Members 9-8 Expose Event Data Structure Members 9-9 Graphics Expose Event Data Structure Members 9-10 No Expose Event Data Structure Members 9-11 Selecting Events Using a Predicate Procedure 9-12 Routines to Select Events Using a Mask 9-13 Error Event Data Structure Members 10-1 Example of Using a Name and a Class 10-2 Resource Manager Matching Rules 10-3 Resource Manager Value Data Structure Members 12-1 Atom Names of Standard Properties 12-2 Window Manager Hints Data Structure Flags 12-3 WM Hints Data Structure Members 12-4 Size Hints Data Structure Flags 12-5 Size Hints Data Structure Members 12-6 Text Property Data Structure Members 12-7 Class Hint Data Structure Members C-1 VMS DECwindows 75 dpi Fonts C-2 VMS DECwindows 100 dpi Fonts C-3 VMS DECwindows Common Fonts