CONTENTS Title Page Copyright Page Preface 1 Programming Overview of Xlib 1.1 Overview of Xlib 1.2 Sample Xlib Program 1.2.1 Initializing Xlib Resources 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 Handling Events 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.5.1 Using Properties to Communicate with the Window Manager 3.5.1.1 Defining Properties Using the SET WM HINTS Routine 3.5.1.2 Defining Individual Properties 3.5.1.3 Providing Size Hints 3.5.2 Exchanging Properties Between Clients 3.6 Changing Window Characteristics 3.6.1 Reconfiguring Windows 3.6.2 Effects of Reconfiguring Windows 3.6.3 Changing Stacking Order 3.6.4 Changing Window Attributes 3.7 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 VMS DECwindows 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 a Font 8.3 Getting Information About a Font 8.4 Freeing Font Resources 8.5 Computing the Size of Text 8.6 Drawing Text 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 Key Events 9.5 Window Entries and Exits 9.5.1 Normal Window Entries and Exits 9.5.2 Pseudomotion Window Entries and Exits 9.6 Input Focus Events 9.6.1 Normal Keyboard Input Focus 9.6.2 Keyboard Input Focus Changes Caused by Grabs 9.7 Key Map State Events 9.8 Exposure Events 9.8.1 Handling Window Exposures 9.8.2 Handling Graphics Exposures 9.9 Window State Notification Events 9.9.1 Handling Window Circulation 9.9.2 Handling Changes in Window Configuration 9.9.3 Handling Window Creations 9.9.4 Handling Window Destructions 9.9.5 Handling Changes in Window Position 9.9.6 Handling Window Mappings 9.9.7 Handling Key, Keyboard, and Pointer Mappings 9.9.8 Handling Window Reparenting 9.9.9 Handling Window Unmappings 9.9.10 Handling Changes in Window Visibility 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 an Event 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 A Compiling Fonts B Routines Requiring Protocol Requests C VMS DECwindows Named Colors D VMS DECwindows Fonts EXAMPLES 1-1 Sample 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 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 Using Named VMS DECwindows Colors 5-2 Specifying Exact Color Values 5-3 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 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 Set Window Attributes Data Structure 3-6 Window Before Restacking 3-7 Restacked Window 3-8 WM Hints Data Structure 3-9 Class Hint Data Structure 3-10 Size Hints Data Structure 3-11 Window Changes Data Structure 3-12 Reconfigured Window 3-13 East Bit Gravity 3-14 Northwest Window Gravity 3-15 Window Attributes Data Structure 4-1 GC Values Data Structure 4-2 Bounding Box 4-3 Line Styles 4-4 Butt, Round, and Projecting Cap Styles 4-5 Cap Not Last Style 4-6 Join Styles 4-7 Fill Rules 4-8 Pixel Boundary Cases 4-9 Styles for Filling Arcs 4-10 Dashed Line Offset 4-11 Dashed Line 4-12 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 Visual Info Data Structure 5-5 Color Data Structure 5-6 Polygons That Define the Color Wheel 6-1 Point Data Structure 6-2 Circles of Points Created Using the DRAW POINTS Routine 6-3 Star Created Using the DRAW LINES Routine 6-4 Segment Data Structure 6-5 Rectangle Coordinates and Dimensions 6-6 Rectangle Drawing 6-7 Rectangle Data Structure 6-8 Rectangles Drawn Using the DRAW RECTANGLES Routine 6-9 Specifying an Arc 6-10 Arc Data Structure 6-11 Multiple Arcs Drawn Using the DRAW ARCS Routine 6-12 Filled Star Created Using the FILL POLYGON Routine 6-13 Arcs Drawn Within a Region 6-14 Intersection of Two Regions 6-15 Cursor Shape and Cursor Mask 7-1 Image Data Structure 7-2 XY Bitmap Format 7-3 XY Pixmap Format 7-4 Z Format 8-1 Composition of a Character 8-2 Composition of a Slash 8-3 Char Struct Data Structure 8-4 Single-Row Font 8-5 Multiple-Row Font 8-6 Char 2B Data Structure 8-7 Font Struct Data Structure 8-8 Indexing Single-Row Font Character Metrics 8-9 Indexing Multiple-Row Font Character Metrics 8-10 Atoms and Font Properties 8-11 Font Prop Data Structure 8-12 Text Item Data Structure 8-13 Text Item 16 Data Structure 9-1 Any Event Data Structure 9-2 Event Data Structure 9-3 Button Event Data Structure 9-4 Motion Event Data Structure 9-5 Key Event Data Structure 9-6 Crossing Event Data Structure 9-7 Window Entries and Exits 9-8 Focus Change Event Data Structure 9-9 Keymap Event Data Structure 9-10 Expose Event Data Structure 9-11 Graphics Expose Event Data Structure 9-12 No Expose Event Data Structure 9-13 Window Scrolling 9-14 Circulate Event Data Structure 9-15 Configure Event Data Structure 9-16 Create Window Event Data Structure 9-17 Destroy Window Event Data Structure 9-18 Gravity Event Data Structure 9-19 Map Window Event Data Structure 9-20 Mapping Event Data Structure 9-21 Reparent Event Data Structure 9-22 Unmap Event Data Structure 9-23 Visibility Event Data Structure 9-24 Color Map Event Data Structure 9-25 Client Message Event Data Structure 9-26 Property Event Data Structure 9-27 Selection Clear Event Data Structure 9-28 Selection Request Event Data Structure 9-29 Selection Event Data Structure 9-30 Error Event Data Structure TABLES 2-1 Client-Server Connection Routines 2-2 Screen Routines 2-3 Image Format Routines 2-4 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 Atom Names of Window Manager Properties 3-7 WM Hints Data Structure Members 3-8 Class Hint Data Structure Members 3-9 Set Window Attributes Data Structure Flags 3-10 Size Hints Data Structure Members 3-11 Window Changes Data Structure Members 3-12 Stacking Values 3-13 Window Changes Data Structure Flags 3-14 Window Configuration Routines 3-15 Gravity Definitions 3-16 Routines for Changing Window Attributes 3-17 Effects of Window Attribute Changes 3-18 Window Information Routines 3-19 Window Attributes Data Structure Members 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 Xlib Cursors 6-7 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 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 Key Event Data Structure Members 9-8 Crossing Event Data Structure Members 9-9 Normal Window Entry and Exit Event Reporting 9-10 Focus Change Event Data Structure Members 9-11 Effect of Focus Changes: Windows on Same Screen 9-12 Focus Changes Caused by Pointer Movement 9-13 Effect of Focus Changes: Windows on Different Screens 9-14 Pointer Window and No Focus Changes 9-15 Keymap Event Data Structure Members 9-16 Expose Event Data Structure Members 9-17 Graphics Expose Event Data Structure Members 9-18 No Expose Event Data Structure Members 9-19 Circulate Event Data Structure Members 9-20 Configure Event Data Structure Members 9-21 Create Window Event Data Structure Members 9-22 Destroy Window Event Data Structure Members 9-23 Gravity Event Data Structure Members 9-24 Map Event Data Structure Members 9-25 Mapping Event Data Structure Members 9-26 Reparent Event Data Structure Members 9-27 Unmap Event Data Structure Members 9-28 Visibility Event Data Structure Members 9-29 Color Map Event Data Structure Members 9-30 Client Message Event Data Structure Members 9-31 Property Event Data Structure Members 9-32 Selection Clear Event Data Structure Members 9-33 Selection Request Event Data Structure Members 9-34 Selection Event Data Structure Members 9-35 Selecting Events Using a Predicate Procedure 9-36 Routines to Select Events Using a Mask 9-37 Error Event Data Structure Members 9-38 Event Error Codes B-1 Routines Requiring Protocol Requests C-1 VMS DECwindows Named Colors D-1 VMS DECwindows 75 DPI Fonts D-2 VMS DECwindows 100 DPI Fonts