CONTENTS Acknowledgments X Window System, Version 11 Xlib -C Library X Interface, Release 1 Release 4 X Window System Protocol Inter-Client Communication Conventions Manual X Logical Font Description Introduction Principles History The MIT X Consortium The Structure of This Book Part I. XLib -C Language X Interface Chapter 1. Introduction to Xlib 1.1 Overview of the X Window System 1.2 Errors 1.3 Naming and Argument Conventuions within Xlib 1.4 Programming Considerations 1.5 Formating Conventions Chapter 2. Display Functions 2.1 Opening the Display 2.2 Obtaining Information about the Display, Image Formats, or Screens 2.2.1 Display Macros 2.2.2 Image Format Functions and Macros 2.2.3 Screen Information Macros 2.3 Generating a NoOperation Protocol Request 2.4 Freeing Client-Created Data 2.5 Closing the Display 2.6 X Server Connection Close Operations Chapter 3. Window Functions 3.1 Visual Types 3.2 Window Attributes 3.2.1 Background Attribute 3.2.2 Border Attribute 3.2.3 Gravity Attributes 3.2.4 Backing Store Attribute 3.2.5 Save Under Flag 3.2.6 Backing Planes and Backing Pixel Attributes 3.2.7 Event Mask and Do Not Propagate Mask Attributes 3.2.8 Override Redirect Flag 3.2.9 Colormap Attribute 3.2.10 Cursor Attribute 3.3 Creating Windows 3.4 Destroying Windows 3.5 Mapping Windows 3.6 Unmapping Windows 3.7 Configuring Windows 3.8 Changing Window Stacking Order 3.9 Changing Window Attributes 3.10 Translating Window Coordinates Chapter 4. Window Information Functions 4.1 Obtaining Window Information 4.2 Properties and Atoms 4.3 Obtaining and Changing Window Properties 4.4 Selections Chapter 5. Graphics Resource Functions 5.1 Colormap Functions 5.1.1 Creating, Copying, and Destroying Colormaps 5.1.2 Allocating, Modifying, and Freeing Color Cells 5.1.3 Reading Entries in a Colormap 5.2 Creating and Freeing Pixmaps 5.3 Manipulating Graphics Context/State 5.4 Using GC Convenience Routines 5.4.1 Setting the Foreground, Background, Function, or Plane Mask 5.4.2 Setting the Line Attributes and Dashes 5.4.3 Setting the Fill Style and Fill Rule 5.4.4 Setting the Fill Tile and Stipple 5.4.5 Setting the Current Font 5.4.6 Setting the Clip Region 5.4.7 Setting the Arc Mode, Subwindow Mode, and Graphics Exposure Chapter 6. Graphics Functions 6.1 Clearing Areas 6.2 Copying Areas 6.3 Drawing Points, Lines, Rectangles, and Arcs 6.3.1 Drawing Single and Multiple Points 6.3.2 Drawing Single and Multiple Lines 6.3.3 Drawing Single and Multiple Rectangles 6.3.4 Drawing Single and Multiple Arcs 6.4 Filling Areas 6.4.1 Filling Single and Multiple Rectangles 6.4.2 Filling a Single Polygon 6.4.3 Filling Single and Multiple Arcs 6.5 Font Metrics 6.5.1 Loading and Freeing Fonts 6.5.2 Obtaining and Freeing Font Names and Information 6.5.3 Setting and Retrieving the Font Search Path 6.5.4 Computing Character String Sizes 6.5.5 Computing Logical Extents 6.5.6 Querying Character String Sizes 6.6 Drawing Text 6.6.1 Drawing Complex Text 6.6.2 Drawing Text Characters 6.6.3 Drawing Image Text Characters 6.7 Transfering Images between Client and Server 6.8 Cursors 6.8.1 Creating a Cursor 6.8.2 Changing and Destroying Cursors 6.8.3 Defining the Cursor Chapter 7. Window Manager Functions 7.1 Changing the Parent of a Window 7.2 Controlling the Lifetime of a Window 7.3 Determining Resident Colormaps 7.4 Pointer Grabbing 7.5 Keyboard Grabbing 7.6 Server Grabbing 7.7 Miscellaneous Control Functions 7.7.1 Controlling Input Focus 7.7.2 Killing Clients 7.8 Keyboard and Pointer Settings 7.9 Keyboard Encoding 7.10 Screen Saver Control 7.11 Controlling Host Access 7.11.1 Adding, Getting, or Removing Hosts 7.11.2 Changing, Enabling, or Disabling Access Control Chapter 8. Events and Event-Handling Functions 8.1 Event Types 8.2 Event Structures 8.3 Event Masks 8.4 Event Processing 8.4.1 Keyboard and Pointer Events 8.4.1.1 Pointer B utton E vents 8.4.1.2 Keyboard and Pointer E vents 8.4.2 Window Entry/Exit Events 8.4.2.1 Normal E ntry/E xit E vents 8.4.2.2 Grab and Ungrab E ntry/E xit E vents 8.4.3 Input Focus Events 8.4.3.1 Normal F ocus E vents and F ocus E vents While Grabbed 8.4.3.2 F ocus E vents Generated by Grabs 8.4.4 Keymap State Notification Events 8.4.5 Exposure Events 8.4.5.1 E xpos e E vents 8.4.5.2 Graphics E xpos e and NoE xpos e E vents 8.4.6 Window State Change Events 8.4.6.1 CirculateNotify E vents 8.4.6.2 ConfigureNotify E vents 8.4.6.3 CreateNotify E vents 8.4.6.4 Des troyNotify E vents 8.4.6.5 GravityNotify E vents 8.4.6.6 MapNotify E vents 8.4.6.7 MappingNotify E vents 8.4.6.8 ReparentNotify E vents 8.4.6.9 UnmapNotify E vents 8.4.6.10 Vis ibilityNotify E vents 8.4.7 Structure Control Events 8.4.7.1 CirculateReques t E vents 8.4.7.2 ConfigureReques t E vents 8.4.7.3 MapReques t E vents 8.4.7.4 Res izeReques t E vents 8.4.8 Colormap State Change Events 8.4.9 Client Communication Events 8.4.9.1 ClientMes s age E vents 8.4.9.2 PropertyNotify E vents 8.4.9.3 S electionClear E vents 8.4.9.4 S electionReques t E vents 8.4.9.5 S electionNotify E vents 8.5 Selecting Events 8.6 Handling the Output Buffer 8.7 Event Queue Management 8.8 Manipulating the Event Queue 8.8.1 Returning the Next Event 8.8.2 Selecting Events Using a Predicate Procedure 8.8.3 Selecting Events Using a Window or Event Mask 8.9 Putting an Event Back into the Queue 8.10 Sending Events to Other Applications 8.11 Getting Pointer Motion History 8.12 Handling Error Events 8.12.1 Enabling or Disabling Synchronization 8.12.2 Using the Default Error Handlers Chapter 9. Inter-Client Communication Functions 9.1 Client to Window Manager Communication 9.1.1 Manipulating Top-Level Windows 9.1.2 Converting String Lists 9.1.3 Setting and Reading Text Properties 9.1.4 Setting and Reading the WM_NAME Property 9.1.5 Setting and Reading the WM_ICON_NAME Property 9.1.6 Setting and Reading the WM_HINTS Property 9.1.7 Setting and Reading the WM_NORMAL_HINTS Property 9.1.8 Setting and Reading the WM_CLASS Property 9.1.9 Setting and Reading the WM_TRANSIENT_FOR Property 9.1.10 Setting and Reading the WM_PROTOCOLS Property 9.1.11 Setting and Reading the WM_COLORMAP_WINDOWS Property 9.1.12 Setting and Reading the WM_ICON_SIZE Property 9.1.13 Using Window Manager Convenience Functions 9.2 Client to Session Manager Communication 9.2.1 Setting and Reading the WM_COMMAND Property 9.2.2 Setting and Reading the WM_CLIENT_MACHINE Property 9.3 Standard Colormaps 9.3.1 Standard Colormap Properties and Atoms 9.3.2 Setting and Obtaining Standard Colormaps Chapter 10. Application Utility Functions 10.1 Keyboard Utility Functions 10.1.1 Keyboard Event Functions 10.1.2 Keysym Classification Macros 10.2 Obtaining the X Environment Defaults 10.3 Parsing the Window Geometry 10.4 Parsing the Color Specifications 10.5 Generating Regions 10.6 Manipulating Regions 10.6.1 Creating, Copying, or Destroying Regions 10.6.2 Moving or Shrinking Regions 10.6.3 Computing with Regions 10.6.4 Determining if Regions Are Empty or Equal 10.6.5 Locating a Point or a Rectangle in a Region 10.7 Using the Cut and Paste Buffers 10.8 Determining the Appropriate Visual Type 10.9 Manipulating Images 10.10 Manipulating Bitmaps 10.11 Using the Resource Manager 10.11.1 Resource Manager Matching Rules 10.11.2 Basic Resource Manager Definitions 10.11.3 Resource Database Access 10.11.3.1 S toring I nto a Res ource Databas e 10.11.3.2 L ooking Up from a Res ource Databas e 10.11.3.3 Databas e S earch L is ts 10.11.3.4 Merging Res ource Databas es 10.11.3.5 Retrieving and S toring Databas es 10.11.4 Parsing Command Line Options 10.12 Using the Context Manager Part II. X Window System Protocol SECTION 1. PROTOCOL FORMATS Request Format Reply Format Error Format Event Format SECTION 2. SYNTACTIC CONVENTIONS RequestName EventName SECTION 3. COMMON TYPES SECTION 4. ERRORS SECTION 5. KEYBOARDS SECTION 6. POINTERS SECTION 7. PREDEFINED ATOMS SECTION 8. CONNECTION SETUP Connection Initiation Server Response Server Information Screen Information Visual Information SECTION 9. REQUESTS CreateWindow ChangeWindowAttributes GetWindowAttributes DestroyWindow DestroySubwindows ChangeSaveSet ReparentWindow MapWindow MapSubwindows UnmapWindow UnmapSubwindows ConfigureWindow CirculateWindow GetGeometry QueryTree InternAtom GetAtomName ChangeProperty DeleteProperty GetProperty RotateProperties ListProperties SetSelectionOwner GetSelectionOwner ConvertSelection SendEvent GrabPointer UngrabPointer GrabButton UngrabButton ChangeActivePointerGrab GrabKeyboard UngrabKeyboard GrabKey UngrabKey AllowEvents GrabServer UngrabServer QueryPointer GetMotionEvents TranslateCoordinates WarpPointer SetInputFocus GetInputFocus QueryKeymap OpenFont CloseFont QueryFont QueryTextExtents ListFonts ListFontsWithInfo SetFontPath GetFontPath CreatePixmap FreePixmap CreateGC ChangeGC CopyGC SetDashes SetClipRectangles FreeGC ClearArea CopyArea CopyPlane PolyPoint PolyLine PolySegment PolyRectangle PolyArc FillPoly PolyFillRectangle PolyFillArc PutImage GetImage PolyText8 PolyText16 ImageText8 ImageText16 CreateColormap FreeColormap CopyColormapAndFree InstallColormap UninstallColormap ListInstalledColormaps AllocColor AllocNamedColor AllocColorCells AllocColorPlanes FreeColors StoreColors StoreNamedColor QueryColors LookupColor CreateCursor CreateGlyphCursor FreeCursor RecolorCursor QueryBestSize QueryExtension ListExtensions SetModifierMapping GetModifierMapping ChangeKeyboardMapping GetKeyboardMapping ChangeKeyboardControl GetKeyboardControl Bell SetPointerMapping GetPointerMapping ChangePointerControl GetPointerControl SetScreenSaver GetScreenSaver ForceScreenSaver ChangeHosts ListHosts SetAccessControl SetCloseDownMode KillClient SECTION 10. CONNECTION CLOSE SECTION 11. EVENTS KeyPress, KeyRelease, ButtonPress, ButtonRelease, MotionNotif EnterNotify, LeaveNotify FocusIn, FocusOut KeymapNotify Expose GraphicsExposure NoExposure VisibilityNotify CreateNotify DestroyNotify UnmapNotify MapNotify MapRequest ReparentNotify ConfigureNotify GravityNotify ResizeRequest ConfigureRequest CirculateNotify CirculateRequest PropertyNotify SelectionClear SelectionRequest SelectionNotify ColormapNotify MappingNotify ClientMessage SECTION 12. FLOW CONTROL AND CONCURRENCY Part III. Inter-Client Communication Conventions Manual Chapter 1. INTRODUCTION 1.1 Evolution of the Conventions 1.2 Atoms 1.2.1 What Are Atoms? 1.2.2 Predefined Atoms 1.2.3 Naming Conventions 1.2.4 Semantics 1.2.5 Name Spaces Chapter 2. PEER-TO-PEER COMMUNICATION BY MEANS OF SELECTIONS 2.1 Acquiring Selection Ownership SetSelectionOwner GetSelectionOwner 2.4 Responsibilities of the Selection Owner SelectionRequest SelectionNotify SelectionClear 2.8 Giving Up Selection Ownership 2.8.1 Voluntarily Giving Up Selection Ownership 2.8.2 Forcibly Giving Up Selection Ownership 2.9 Requesting a Selection ConvertSelection GetProperty 2.12 Large Data Transfers 2.13 Use of Selection Atoms 2.13.1 Selection Atoms 2.13.1.1 T he PRI MARY S election 2.13.1.2 T he S E CONDARY S election 2.13.1.3 T he CL I PB OARD S election 2.13.2 Target Atoms 2.13.3 Selection Targets with Side Effects 2.13.3.1 DE L E T E 2.13.3.2 I NS E RT _ S E L E CT I ON 2.13.3.3 I NS E RT _ PROPE RT Y 2.14 Use of Selection Properties 2.14.1 TEXT Properties 2.14.2 INCR Properties 2.14.3 DRAWABLE Properties 2.14.4 SPAN Properties Chapter 3. PEER-TO-PEER COMMUNICATION BY MEANS OF CUT BUFFERS Chapter 4. CLIENT TO WINDOW MANAGER COMMUNICATION 4.1 Client's Actions 4.1.1 Creating a Top-Level Window 4.1.2 Client Properties 4.1.2.1 WM_ NAME Property 4.1.2.2 WM_ I CON_ NAME Property 4.1.2.3 WM_ NORMAL _ HI NT S Property 4.1.2.4 WM_ HI NT S Property 4.1.2.5 WM_ CL AS S Property 4.1.2.6 WM_ T RANS I E NT _ F OR Property 4.1.2.7 WM_ PROT OCOL S Property 4.1.2.8 WM_ COL ORMAP_ WI NDOWS Property 4.1.3 Window Manager Properties 4.1.3.1 WM_ S T AT E Property 4.1.3.2 WM_ I CON_ S I Z E Property 4.1.4 Changing Window State 4.1.5 Configuring the Window 4.1.6 Changing Window Attributes 4.1.7 Input Focus 4.1.8 Colormaps 4.1.9 Icons 4.1.10 Pop-up Windows 4.1.11 Window Groups 4.2 Client Responses to Window Manager Actions 4.2.1 Reparenting 4.2.2 Redirection of Operations 4.2.3 Window Move 4.2.4 Window Resize 4.2.5 Iconify and Deiconify 4.2.6 Colormap Change 4.2.7 Input Focus SetInputFocus 4.3.1 ClientMessage Events 4.3.2 Redirecting Requests 4.4 Summary of Window Manager Property Types Chapter 5. CLIENT TO SESSION MANAGER COMMUNICATION 5.1 Client Actions 5.1.1 Properties 5.1.1.1 WM_ COMMAND Property 5.1.1.2 WM_ CL I E NT _ MACHI NE Property 5.1.1.3 WM_ S T AT E Property 5.1.2 Termination 5.2 Client Responses to Session Manager Actions 5.2.1 Saving Client State 5.2.2 Window Deletion 5.3 Summary of Session Manager Property Types Chapter 6. MANIPULATION OF SHARED RESOURCES 6.1 The Input Focus 6.2 The Pointer 6.3 Grabs 6.4 Colormaps 6.5 The Keyboard Mapping 6.6 The Modifier Mapping Part IV. X Logical Font Descriptions Chapter 1. INTRODUCTION Chapter 2. REQUIREMENTS AND GOALS 2.1 Provide Unique and Descriptive Font Names 2.2 Support Multiple Font Vendors and Character Sets 2.3 Be Independent of X Server and Operating or File System 2.4 Support Arbitrarily Complex Font Matching and Substitution 2.5 Be Extensible Chapter 3. X LOGICAL FONT DESCRIPTION 3.1 FontName 3.1.1 FontName Syntax 3.1.2 FontName Field Definitions 3.1.2.1 F OUNDRY F ield 3.1.2.2 F AMI L Y_ NAME F ield 3.1.2.3 WE I GHT _ NAME F ield 3.1.2.4 S L ANT F ield 3.1.2.5 S E T WI DT H_ NAME F ield 3.1.2.6 ADD_ S T YL E _ NAME F ield 3.1.2.7 PI XE L _ S I Z E F ield 3.1.2.8 POI NT _ S I Z E F ield 3.1.2.9 RE S OL UT I ON_ X and RE S OL UT I ON_ Y F ields 3.1.2.10 S PACI NG F ield 3.1.2.11 AVE RAGE _ WI DT H F ield 3.1.2.12 CHARS E T _ RE GI S T RY and CHARS E T _ E NCODI NG F ields 3.1.3 Examples 3.2 FontProperties 3.2.1 FOUNDRY 3.2.2 FAMILY_NAME 3.2.3 WEIGHT_NAME 3.2.4 SLANT 3.2.5 SETWIDTH_NAME 3.2.6 ADD_STYLE_NAME 3.2.7 PIXEL_SIZE 3.2.8 POINT_SIZE 3.2.9 RESOLUTION_X 3.2.10 RESOLUTION_Y 3.2.11 SPACING 3.2.12 AVERAGE_WIDTH 3.2.13 CHARSET_REGISTRY 3.2.14 CHARSET_ENCODING 3.2.15 MIN_SPACE 3.2.16 NORM_SPACE 3.2.17 MAX_SPACE 3.2.18 END_SPACE 3.2.19 AVG_CAPITAL_WIDTH 3.2.20 AVG_LOWERCASE_WIDTH 3.2.21 QUAD_WIDTH 3.2.22 FIGURE_WIDTH 3.2.23 SUPERSCRIPT_X 3.2.24 SUPERSCRIPT_Y 3.2.25 SUBSCRIPT_X 3.2.26 SUBSCRIPT_Y 3.2.27 SUPERSCRIPT_SIZE 3.2.28 SUBSCRIPT_SIZE 3.2.29 SMALL_CAP_SIZE 3.2.30 UNDERLINE_POSITION 3.2.31 UNDERLINE_THICKNESS 3.2.32 STRIKEOUT_ASCENT 3.2.33 STRIKEOUT_DESCENT 3.2.34 ITALIC_ANGLE 3.2.35 CAP_HEIGHT 3.2.36 X_HEIGHT 3.2.37 RELATIVE_SETWIDTH 3.2.38 RELATIVE_WEIGHT 3.2.39 WEIGHT 3.2.40 RESOLUTION 3.2.41 FACE_NAME 3.2.42 COPYRIGHT 3.2.43 NOTICE 3.2.44 DESTINATION 3.3 Built-in Font Property Atoms Chapter 4. AFFECTED ELEMENTS OF XLIB AND THE X PROTOCOL Chapter 5. BDF CONFORMANCE 5.1 XLFD Conformance Requirements 5.2 FONT_ASCENT, FONT_DESCENT, and DEFAULT_CHAR 5.2.1 FONT_ASCENT 5.2.2 FONT_DESCENT 5.2.3 DEFAULT_CHAR Appendix A. Xlib Functions and Protocol Requests Appendix B. X Font Cursors Appendix C. Extensions Basic Protocol Support Routines Hooking into Xlib Hooks into the Library Hooks onto Xlib Data Structures GC Caching Graphics Batching Writing Extension Stubs Requests, Replies, and Xproto.h Request Format Starting to Write a Stub Routine Locking Data Structures Sending the Protocol Request and Arguments Variable Length Arguments Replies Synchronous Calling Allocating and Deallocating Memory Portability Considerations Deriving the Correct Extension Opcode Appendix D. Compatibility Functions X VERSION 11 COMPATIBILITY FUNCTIONS Setting Standard Properties Setting and Getting Window Sizing Hints Getting and Setting an XStandardColormap Structure Parsing Window Geometry X VERSION 10 COMPATIBILITY FUNCTIONS Drawing and Filling Polygons and Curves Associating User Data with a Value Appendix E. KEYSYM Encoding Appendix F. Protocol Encoding Syntactic Conventions NameofThing Common Types Errors Request Value Window Pixmap Atom Cursor Font Match Drawable Access Alloc Colormap GContext IDChoice Name Length Implementation Keyboards Pointers Predefined Atoms Connection Setup Requests CreateWindow ChangeWindowAttributes GetWindowAttributes DestroyWindow DestroySubwindows ChangeSaveSet ReparentWindow MapWindow MapSubwindows UnmapWindow UnmapSubwindows ConfigureWindow CirculateWindow GetGeometry QueryTree InternAtom GetAtomName ChangeProperty DeleteProperty GetProperty ListProperties SetSelectionOwner GetSelectionOwner ConvertSelection SendEvent GrabPointer UngrabPointer GrabButton UngrabButton ChangeActivePointerGrab GrabKeyboard UngrabKeyboard GrabKey UngrabKey AllowEvents GrabServer UngrabServer QueryPointer GetMotionEvents TranslateCoordinates WarpPointer SetInputFocus GetInputFocus QueryKeymap OpenFont CloseFont QueryFont QueryTextExtents ListFonts ListFontsWithInfo SetFontPath GetFontPath CreatePixmap FreePixmap CreateGC ChangeGC CopyGC SetDashes SetClipRectangles FreeGC ClearArea CopyArea CopyPlane PolyPoint PolyLine PolySegment PolyRectangle PolyArc FillPoly PolyFillRectangle PolyFillArc PutImage GetImage PolyText8 PolyText16 ImageText8 ImageText16 CreateColormap FreeColormap CopyColormapAndFree InstallColormap UninstallColormap ListInstalledColormaps AllocColor AllocNamedColor AllocColorCells AllocColorPlanes FreeColors StoreColors StoreNamedColor QueryColors LookupColor CreateCursor CreateGlyphCursor FreeCursor RecolorCursor QueryBestSize QueryExtension ListExtensions ChangeKeyboardMapping GetKeyboardMapping ChangeKeyboardControl GetKeyboardControl Bell ChangePointerControl GetPointerControl SetScreenSaver GetScreenSaver ChangeHosts ListHosts SetAccessControl SetCloseDownMode KillClient RotateProperties ForceScreenSaver SetPointerMapping GetPointerMapping SetModifierMapping GetModifierMapping NoOperation Events KeyPress KeyRelease ButtonPress ButtonRelease MotionNotify EnterNotify LeaveNotify FocusIn FocusOut KeymapNotify Expose GraphicsExposure NoExposure VisibilityNotify CreateNotify DestroyNotify UnmapNotify MapNotify MapRequest ReparentNotify ConfigureNotify ConfigureRequest GravityNotify ResizeRequest CirculateNotify CirculateRequest PropertyNotify SelectionClear SelectionRequest SelectionNotify ColormapNotify ClientMessage MappingNotify Appendix G. X Consortium Standard Character Set Names Appendix H. Bitmap Distribution Format Version 2.1 Introduction File Format Metric Information An Example File Glossary Figures 2-1: X window system block diagram 1-1: Window hierarchy 3-1: Pseudo color, gray scale, static color or static gray 3-2: Direct color 3-3: Window gravity 5-1: Request of 3 cells and 2 planes 5-2: Example of graphics operation using func - tion and plane mask (4bits/pixel) 5-3: Wide line cap and join styles 5-4: Fill rule 5-5: Arc mode 5-6: Dashes: 20 50 40 50 60 50 80 50 160 50 6-1: XDrawArc (DPW, W, GC, x, y, width, height, 45*64, 225*64 6-2: XCharStruct components H-1: An example of a descender H-2: An example with the origin outside the bounding box 9-1: Coordinate system Tables E-1: Table of Character Values