Volume One. Xlib Programming Manual

Transcription

1 Volume One Xlib Programming Manual for Version 11 of the X Window System by Adrian Nye O'Reilly & Associates, Inc.

2 -^ Table of Contents Page Preface About This Manual Summary of Contents How to Use This Manual Getting the Example Programs FTP FTPMA1L BITFTP UUCP Compiling the Example Programs Assumptions Font Conventions Used in This Manual Related Documents Requests for Comments Bulk Sales Information Acknowledgements xxix xxix xxix xxx xxxii xxxii xxxiii xxxiii xxxiv xxxv xxxv xxxv xxxvi xxxvii xxxvii xxxvii Chapter 1 Introduction Versions of X X Window System Concepts Displays and Screens The Server-Client Model Window Management Events Extensions to X X Window System Software Architecture Overview of Xlib 11 Chapter 2 X Concepts How Xlib Works The X Protocol Buffering Resources Properties and Atoms The Window Manager What are X Windows? 23 v

3 2.2.1 Window Characteristics Window Hierarchy Window Stacking Order Mapping and Visibility Introduction to X Graphics Pixels and Colors Pixels and Planes Pixmaps and Drawables Drawing and the Graphics Context Tiles and Stipples More on Window Characteristics Window Attributes Window Configuration Class: InputOutput and InputOnly Windows Depth and Visual Icons Special Characteristics of the Root Window Introduction to Events What is an Event? Selection and Propagation of Events The Event Queue An Event Structure The Event Loop How to Program with Xlib Designing an X Application Design Requirements The User Interface Writing an X Application Resources and User Customizability Compiling and Linking X Programs Naming Conventions Using Structures, Symbols, and Masks Performance Optimizing ANSI-C and POSIX Portability Debugging an X Application Errors The XErrorEvent Structure Synchronizing Errors.' Software Interrupts 51 Chapter 3 Basic Window Program Running the Program The Main of basicwin Include Files and Declarations Connecting to a Server Display Macros 61 vi

4 3.2.4 Getting Window Information Creating Windows Color Strategy Preparing an Icon Pixmap Communicating with the Window Manager Selecting Desired Event Types Creating Server Resources Window Mapping Flushing the Output Buffer Setting Up an Event-gathering Loop Repainting the Window When Can I Draw? When Will My Drawing Appear? Handling Resizing of the Window Exiting the Program Error Handling Summary Complete Code for basicwin 83 Chapter 4 Window Attributes Setting Window Attributes The Window Attribute Structures Settable Attributes The Window Background background_pixmap background_pixei The Window Border border_pixmap border_pixel Bit Gravity Window Gravity Backing Store Saving Under Event Handling Substructure Redirect Override Colormap Cursor Default Attributes Information from the XWindowAttributes Structure 110 Chapter 5 The Graphics Context Creating and Setting a Graphics Context Switching Between Graphics Contexts Controlling Pixel Selection 122 vii

5 5.3.1 Line Characteristics Line Width Line Style Cap Style Join Style Dash List and Offset Example of Setting Line Characteristics The Font Fill Rule Arc Mode (for Filling) Clip Mask Controlling Coloring and Patterning Drawing in Foreground Only Tiles Stipples Fill Style Drawing in Foreground and Background Tile and Stipple Sizes Controlling Graphics Tricks Logical Function Plane Mask Graphics Exposure Subwindow Mode Sharing GCs Between Clients GCs and Server Efficiency Querying the Graphics Context The Default GC Versus Default Values of a GC 146 Chapter 6 Drawing Graphics and Text Drawing The Request Size Limit Scaling Graphics Example of Drawing Graphics Filling Creating Bitmaps, Pixmaps, Tiles, and Stipples Copying and Clearing Areas Fonts and Text Character Format Loading Fonts Font Naming Character Metrics The XCharStruct Structure The XFontStruct Structure Positioning of Text Text-drawing Routines The drawjext Routine 169 via

6 6.2.8 Vertical Text and Rotated Text Font Properties Setting the Font Path Regions Moving and Resizing Regions Computations with Regions Returning Region Information Images Manipulating Images Examples Using Images Cursors The Standard Cursor Font Creating a Pixmap Cursor Loading and Changing Cursors 183 Chapter 7 Color Basic Color Terms and Concepts Color Naming and Specification The Server-side Color Name Database Xcms Color Specification The Client-side Color Name Database Hexadecimal Color Specification Differences in Display Hardware Mid-range Color Displays Monochrome and Gray Scale High Performance Color Displays How X Describes Color Support with Visuals Shareability vs. Changeability Allocating Shared Colors The XColor Structure Code to Allocate Read-only Colors Highlighting in Two Colors Choosing Default Colors Allocating Private Colors Allocating Read/Write Colorcells for Dynamic Colors Allocating Read/Write Colorcells for Overlays Using XAllocColorPlanes() Getting Complete Visual Information The XVisuallnfo Structure Example of Choosing a Visual The Grayscale Visual Standard Colormaps The Standard Colormap Properties The XStandardColormap Structure The 3/3/2 Standard Colormap Creating and Using a Standard Colormap 224 IX

7 7.8.5 RGB-to-Pixel Conversion Device-independent Color and Xcms The Fundamentals of Color Representation Screen Characterization and the XDCCC The Xcms Programming Interface Color and Colormap Functions Color Conversion Gamut-querying Functions Creating and Installing Colormaps Functions for Manipulating Colormaps The ColormapNotify Event The Required Colormap List Miscellaneous Color-handling Functions 245 Chapter 8 Events Overview of Event Handling Event Processing The Event Structures Event Types and XEvent Union Xlib's Event Queue Writing the Event Loop Printing the Event Type Routines that Get Events Predicate Procedures Selecting Events Correspondence Between Event Masks and Events Propagation of Device Events The Keyboard Focus Window Keyboard and Pointer Grabbing Event Masks KeyPressMask and KeyReleaseMask ButtonPressMask, ButtonReleaseMask, and OwnerGrabButtonMask The Pointer Motion Masks FocusChangeMask EnterWindowMask and LeaveWindowMask KeymapStateMask ExposureMask VisibilityChangeMask ColormapChangeMask PropertyChangeMask StructureNotifyMask and SubstructureNotifyMask SubstructureRedirectMask ResizeRedirectMask Automatically Selected Events Sending Events Where to Find More on Each Event 280 x i

8 -- jr Chapter 9 The Keyboard and Pointer The Keyboard Simple Keyboard Input Getting a String A Dialog Box The Keyboard Mappings Keysyms to Strings The Modifier Keys Keycodes to Keysyms Background on Keysyms The Design of Keysyms Conventions for Keysym Meaning Changing the Server-wide Keyboard Mappings Changing the Keycode-to-Keysym Mapping Changing Modifier Mapping Other Keyboard-handling Routines The Pointer Tracking Pointer Motion Getting All Motion Events Using Pointer Motion Hints Motion History Handling Pointer Button Events Changing the Pointer Button Mapping Moving the Pointer Border Crossing and Keyboard Focus Change Events The KeymapNotify Event Grabbing the Keyboard and Pointer Implementing Type-ahead for Information Entry Keyboard Preferences Setting Keyboard Preferences Getting Keyboard Preferences Pointer Preferences X Input Extension 323 Chapter 10 Internationalization An Overview of Internationalization Internationalization with ANSI-C Text Representation in an Internationalized Application IS and Other Encodings Multi-byte Strings and Wide-character Strings Internationalization Using X Locale Management in X Internationalized Text Output in X Creating and Manipulating Fontsets Querying Fontset Metrics Context Dependencies in Displayed Text 340 XI

9 г Measuring Strings Drawing Internationalized Text String Encoding Changes for Internationalization Internationalized Interclient Communication Localization of Resource Databases Summary: Writing an Internationalized Application 353 Chapter 11 Internationalized Text Input Issues of Internationalized Text Input Overview of the X Input Method Architecture Input Methods and Input Servers User Interaction with an Input Method The X Input Method The X Input Context Input Context Focus Management Preedit and Status Area Geometry Management Preedit and Status Callbacks Getting Composed Input Filtering Events The Big Picture XIM Programming Interface XIM Functions Opening and Closing an Input Method Querying Input Method Values XIC Functions Choosing an Interaction Style Creating and Destroying Input Contexts Querying and Modifying an XIC Resetting an Input Context Setting Input Context Focus Input Context Utility Functions Input Context Attributes XNInputStyle XNClientWindow XNFocusWindow XNResourceName and XNResourceClass XNGeometryCallback XNFilterEvents XNPreeditAttributes and XNStatusAttributes XNArea XNAreaNeeded XNSpotLocation XNColormap XNStdColormap XNForeground XNBackground : 377 xii

10 XNBackgroundPixmap XNFontSet XNLineSpacing XNCursor Preedit and Status Callbacks Negotiating Preedit and Status Area Geometries Geometry, Preedit, and Status Callbacks The Geometry Callback The PreeditStartCallback and the PreeditEndCallback The PreeditDrawCallback The PreeditCaretCallback The StatusStartCallback and the StatusDoneCallback The StatusDrawCallback Filtering Events Getting Composed Text XIM Programming Checklist 391 Chapter 12 Interclient Communication Properties and Atoms The Compound Text Encoding Communicating with the Window Manager Standard Properties for Window Manager Application Name -XA_WM_NAME Icon Name - XA_WM_ICON_NAME Window Size Hints - XA_WM_NORMAL_HINTS Additional Window Manager Hints - XA_WM_HINTS Application Class Name and Instance Name - XA_WM_CLASS Standard Properties for Session Manager Application Command and Arguments Client Machine Optional Properties for Window and Session Manager Using Created Colormaps - WM_COLORMAP_WINDOWS Window Manager Protocols - WM_PROTOCOLS Properties Set by the Window Manager XA_WM_ICON_SIZE WM_STATE Text Properties Constraints on Client Actions Changing Application State Reconfiguring the Top-level Window Selections The Selection Mechanism An Example of Selection Acquiring Selection Ownership Responsibilities of the Selection Owner Giving Up Selection Ownership 433 xiii

11 Requesting a Selection ; Large Data Transfers More on Selection Properties and Types Target Atoms Cut Buffers 436 Chapter 13 Managing User Preferences Using XGetDefault() Using the Low-level Resource Manager Routines Resource Files and Merging Including Files in a Resource File Resource Properties The Low Level Xrm Routines Standard Geometry Resource Specification and Matching Tight Bindings and Loose Bindings Wildcarding Resource Component Names The -name Option Storage/Access Rules Resource Manager Values and Representation Types Other Resource Manager Routines Putting Resources into the Database Combining the Contents of Databases Enumerating Database Entries Associating a Resource Database with a Display Getting the Locale of a Database Quarks 464 Chapter 14 A Complete Application Description of basecalc Include Files The Main of basecalc Getting User Preferences User Defaults for basecalc Parsing the Command Line Getting the Databases Getting Options from the Database Printing a Usage Message Initializing the Calculator Making Windows Selecting Events Processing Events Drawing a Pad Routines Not Shown 490 xiv

12 Chapter 15 Other Programming Techniques Reading and Writing Properties Screen Saver Host Access and Security The Host Access List Enabling and Disabling Access Control Getting the Window Hierarchy Close Down Mode Connection Close Operations Data Management The Context Manager The After Function Coordinate Transformation ANSI-C and POSIX Portability <Xll/Xosdefs.h> <Xll/Xos.h> <X11/Xfuncs.h> <Xll/Xfuncproto.h> Other Symbols Porting Programs to X Programming for Multiple X Releases Using Extensions to X 508 Chapter 16 Window Management Layout Policy Substructure Redirection Reparenting Shadows Window Save-set Window Manager - Client Communications Reading the Hints Setting Icon Sizes Window Manager Protocols Window Management Functions A Basic Window Manager Operation of the Program Description of the Code of main Window Layering Selecting Input Handling Input Inverting an Area Cursors Grabbing the Pointer Painting the Menu Circulating Windows 534 xv

13 Raising and Lowering Windows Moving and Resizing Windows The draw_box Routine (De)Iconifying Windows Creating the Icons Getting the Icon Size Updating the Icon List Removing Icons Changing Keyboard Focus Drawing the Focus Frame Executing a Shell Command 551 Appendix A Specifying Fonts 555 A.l Font Specification 555 A.l.l Font Naming Conventions 556 A.1.2 Font Name Wildcarding 558 A.1.3 Font Name Aliasing 559 A.l.4 Making the Server Aware of Aliases 560 A.1.5 The fonts.dir Files 561 A.2 Font Service 562 A.2.1 Font Server Naming 564 A.2.2 Font Server Configuration 565 A.3 Scalable Fonts 565 A.3.1 Finding Scalable Fonts 566 A.3.2 Finding Derived Instances of Scalable Fonts 567 A.3.3 Using Scalable Fonts 569 Appendix В Х10 Compatibility 575 B.l XDraw and XDrawFilled() 575 B.2 Association Tables 578 Appendix С Writing Extensions to X 581 C.l Basic Protocol Support Routines 582 C.l.l XListExtensions 582 C.1.2 XFreeExtensionList 583 C.2 Hooking into Xlib 583 C.2.1 XInitExtension 583 C.2.2 XAddExtension 584 C.2.3 Hooks into the Library 584 C XESetCloseDisplay 584 C XESetCreateGC 585 C XESetCopyGC 585 XVI

14 C XESetFreeGC 586 C XESetCreateFont 586 C XESetFreeFont 587 C.2.4 Defining New Events and Errors 587 C XESetWireToEvent 588 C _XSetLastRequestRead 588 C XESetEventToWire 589 C XESetWireToError 589 C XESetError 590 C XESetErrorString 591 C XESetPrintErrorValues 591 C XESetFlushGC 592 C.2.5 Hooks onto Xlib Data Structures 592 C XEHeadOfExtensionList 593 C XAddToExtensionList..593 C XFindOnExtensionList 593 C XAllocID 593 C.3 GC Caching 594 C.4 Graphics Batching 594 C.5 Writing Extension Stubs 596 C.5.1 Requests, Replies, and Xproto.h 596 C.5.2 Request Format 596 C.5.3 Starting to Write a Stub Routine 598 C.5.4 Locking Data Structures 598 C.5.5 Sending the Protocol Request and Arguments 599 C.5.6 Variable Length Arguments 600 C.5.7 Replies 600 C _XReadl6 602 C _XRead C _XReadl6Pad 603 C _XReadPad 603 C.5.8 Synchronous Calling 603 C.5.9 Allocating and Deallocating Memory 604 C.5.10 Portability Considerations 604 C.5.11 Deriving the Correct Extension Opcode 605 Appendix D The basecalc Application 609 Appendix E Event Reference 639 E.l Meaning of Common Structure Elements 639 ButtonPress, ButtonRelease 642 CirculateNotify 644 CirculateRequest 645 ClientMessage 646 ColormapNotify 647 xv/v

15 ConfigureNotify 648 ConfigureRequest 650 CreateNotify 652 DestroyNotify 654 EnterNotify, LeaveNotify 655 Expose, 661 Focusln, FocusOut 663 GraphicsExpose, NoExpose 669 GravityNotify 671 KeymapNotify 672 KeyPress, Key Release 673 MapNotify, UnmapNotify 675 MappingNotify 677 MapRequest 679 MotionNotify 680 PropertyNotify 682 ReparentNotify 683 ResizeRequest 684 SelectionClear 685 SelectionNotify 686 SeiectionRequest 687 VisibilityNotify 688 Appendix F The Xmu Library 693 F.l Atom Functions 693 F.2 Error Handler Functions 694 F.3 System Utility Functions 694 F.4 Window Utility Functions 694 F.5 Cursor Utility Functions 695 F.6 Color Utilities 695 F.7 Pixmap Utilities 695 F.8 Graphics Functions 695 F.9 Selection Functions 696 F.10 Character Set Functions 696 F.ll Compound Text Functions 697 F.12 CloseDisplay Hook Functions 697 F.13 Display Queue Functions 697 F.14 Standard Colormap Functions 698 Appendix G Sources of Additional Information 701 G.l Getting the X Software 701 G.l.l Bug Fixes 702 G.l.1.1 Notes 704 G.l.1.2 Fairness 704 XVIII

16 G.2 Netnews 705 G.3 Training, Consulting, and Support 705 G.4 The X Consortium 706 G.5 Finding Out for Yourself 708 Appendix H Release Notes 711 H.l Changes from Release 4 to Release H.l.l Internationalization 711 H.l.2 X Color Management System 712 H.1.3 Resource Management 713 H.1.4 Scalable Font Support 713 H.2 Miscellaneous Xlib Changes 713 H.3 Changes from Release 3 to Release H.3.1 New Routines 714 H.3.2 Existing Interface Changes 717 H XOpenDisplayO 717 H Error Handlers 717 H Nonstandard Keysyms 717 H XReadBitmapFileO 718 H Resource Specification Syntax 718 H XrmParseCommandO 718 H Keyboard Groups 718 References 744 Glossary 723 References 744 Index 747 XIX