book

XLIB Programming Manual, Rel. 5, Third Edition

by Adrian Nye

June 1994

Intermediate to advanced

821 pages

24h 40m

English

O'Reilly Media, Inc.

Read now

Unlock full access

About This Manual
FTPFTPMAILBITFTPUUCP

1.1 Versions of X
1.2.1 Displays and Screens1.2.2 The Server-Client Model1.2.3 Window Management1.2.4 Events1.2.5 Extensions to X
2.1 How Xlib Works2.1.1 The X Protocol2.1.2 Buffering2.1.3 Resources2.1.4 Properties and Atoms2.1.5 The Window Manager
2.2.1 Window Characteristics2.2.2 Window Hierarchy2.2.3 Window Stacking Order2.2.4 Mapping and Visibility
2.3.1 Pixels and Colors2.3.2 Pixels and Planes2.3.3 Pixmaps and Drawables2.3.4 Drawing and the Graphics Context2.3.5 Tiles and Stipples
2.4.1 Window Attributes2.4.2 Window Configuration2.4.3 Class: InputOutput and InputOnly Windows2.4.4 Depth and Visual2.4.5 Icons2.4.6 Special Characteristics of the Root Window
2.5.1 What is an Event?2.5.2 Selection and Propagation of Events2.5.3 The Event Queue2.5.4 An Event Structure2.5.5 The Event Loop
2.6.1 Designing an X Application2.6.1.1 Design Requirements2.6.1.2 The User Interface2.6.2 Writing an X Application2.6.2.1 Resources and User Customizability2.6.2.2 Compiling and Linking X Programs2.6.2.3 Naming Conventions2.6.2.4 Using Structures, Symbols, and Masks2.6.2.5 Performance Optimizing2.6.2.6 ANSI-C and POSIX Portability2.6.3 Debugging an X Application2.6.3.1 Errors2.6.3.2 The XErrorEvent Structure2.6.3.3 Synchronizing Errors2.6.3.4 Software Interrupts
3.1 Running the Program
3.2.1 Include Files and Declarations3.2.2 Connecting to a Server3.2.3 Display Macros3.2.4 Getting Window Information3.2.5 Creating Windows3.2.6 Color Strategy3.2.7 Preparing an Icon Pixmap3.2.8 Communicating with the Window Manager3.2.9 Selecting Desired Event Types3.2.10 Creating Server Resources3.2.11 Window Mapping3.2.12 Flushing the Output Buffer3.2.13 Setting Up an Event-gathering Loop3.2.13.1 Repainting the Window3.2.14 When Can I Draw?3.2.15 When Will My Drawing Appear?3.2.16 Handling Resizing of the Window3.2.17 Exiting the Program3.2.18 Error Handling3.2.19 Summary3.2.20 Complete Code for basicwin
4.1 Setting Window Attributes
4.3.1 The Window Background4.3.1.1 background_pixmap4.3.1.2 background_pixel4.3.2 The Window Border4.3.2.1 border_pixmap4.3.2.2 border_pixel4.3.3 Bit Gravity4.3.4 Window Gravity4.3.5 Backing Store4.3.6 Saving Under4.3.7 Event Handling4.3.8 Substructure Redirect Override4.3.9 Colormap4.3.10 Cursor4.3.11 Default Attributes
5.1 Creating and Setting a Graphics Context
5.3.1 Line Characteristics5.3.1.1 Line Width5.3.1.2 Line Style5.3.1.3 Cap Style5.3.1.4 Join Style5.3.1.5 Dash List and Offset5.3.1.6 Example of Setting Line Characteristics5.3.2 The Font5.3.3 Fill Rule5.3.4 Arc Mode (for Filling)5.3.5 Clip Mask
5.4.1 Drawing in Foreground Only5.4.2 Tiles5.4.3 Stipples5.4.4 Fill Style5.4.5 Drawing in Foreground and Background5.4.5.1 Tile and Stipple Sizes
5.5.1 Logical Function5.5.2 Plane Mask
6.1 Drawing6.1.1 The Request Size Limit6.1.2 Scaling Graphics6.1.3 Example of Drawing Graphics6.1.4 Filling6.1.5 Creating Bitmaps, Pixmaps, Tiles, and Stipples6.1.6 Copying and Clearing Areas
6.2.1 Character Format6.2.2 Loading Fonts6.2.3 Font Naming6.2.4 Character Metrics6.2.4.1 The XCharStruct Structure6.2.4.2 The XFontStruct Structure6.2.5 Positioning of Text6.2.6 Text-drawing Routines6.2.7 The draw_text Routine6.2.8 Vertical Text and Rotated Text6.2.9 Font Properties6.2.10 Setting the Font Path
6.3.1 Moving and Resizing Regions6.3.2 Computations with Regions6.3.3 Returning Region Information
6.4.1 Manipulating Images6.4.2 Examples Using Images
6.5.1 The Standard Cursor Font6.5.2 Creating a Pixmap Cursor6.5.3 Loading and Changing Cursors
7.1 Basic Color Terms and Concepts
7.2.1 The Server-side Color Name Database7.2.2 Xcms Color Specification7.2.3 The Client-side Color Name Database7.2.4 Hexadecimal Color Specification
7.3.1 Mid-range Color Displays7.3.2 Monochrome and Gray Scale7.3.3 High Performance Color Displays7.3.4 How X Describes Color Support with Visuals7.3.5 Shareability vs. Changeability
7.4.1 The XColor Structure7.4.2 Code to Allocate Read-only Colors7.4.3 Highlighting in Two Colors7.4.4 Choosing Default Colors
7.5.1 Allocating Read/Write Colorcells for Dynamic Colors7.5.2 Allocating Read/Write Colorcells for Overlays7.5.3 Using XAllocColorPlanes()
7.6.1 The XVisualInfo Structure7.6.2 Example of Choosing a Visual
7.8.1 The Standard Colormap Properties7.8.2 The XStandardColormap Structure7.8.3 The 3/3/2 Standard Colormap7.8.4 Creating and Using a Standard Colormap7.8.5 RGB-to-Pixel Conversion
7.9.1 The Fundamentals of Color Representation7.9.2 Screen Characterization and the XDCCC7.9.3 The Xcms Programming Interface7.9.3.1 Color and Colormap Functions7.9.3.2 Color Conversion7.9.3.3 Gamut-querying Functions
7.10.1 Functions for Manipulating Colormaps7.10.2 The ColormapNotify Event7.10.3 The Required Colormap List
8.1 Overview of Event Handling
8.2.1 The Event Structures8.2.2 Event Types and XEvent Union8.2.3 Xlib’s Event Queue8.2.4 Writing the Event Loop8.2.5 Printing the Event Type8.2.6 Routines that Get Events8.2.7 Predicate Procedures
8.3.1 Correspondence Between Event Masks and Events8.3.2 Propagation of Device Events8.3.2.1 The Keyboard Focus Window8.3.2.2 Keyboard and Pointer Grabbing8.3.3 Event Masks8.3.3.1 KeyPressMask and KeyReleaseMask8.3.3.2 ButtonPressMask, ButtonReleaseMask, and OwnerGrabButtonMask8.3.3.3 The Pointer Motion Masks8.3.3.4 FocusChangeMask8.3.3.5 EnterWindowMask and LeaveWindowMask8.3.3.6 KeymapStateMask8.3.3.7 ExposureMask8.3.3.8 VisibilityChangeMask8.3.3.9 ColormapChangeMask8.3.3.10 PropertyChangeMask8.3.3.11 StructureNotifyMask and SubstructureNotifyMask8.3.3.12 SubstructureRedirectMask8.3.3.13 ResizeRedirectMask8.3.3.14 Automatically Selected Events
9.1 The Keyboard9.1.1 Simple Keyboard Input9.1.1.1 Getting a String — A Dialog Box9.1.2 The Keyboard Mappings9.1.2.1 Keysyms to Strings9.1.2.2 The Modifier Keys9.1.2.3 Keycodes to Keysyms9.1.3 Background on Keysyms9.1.3.1 The Design of Keysyms9.1.3.2 Conventions for Keysym Meaning9.1.4 Changing the Server-wide Keyboard Mappings9.1.4.1 Changing the Keycode-to-Keysym Mapping9.1.4.2 Changing Modifier Mapping9.1.5 Other Keyboard-handling Routines
9.2.1 Tracking Pointer Motion9.2.1.1 Getting All Motion Events9.2.1.2 Using Pointer Motion Hints9.2.1.3 Motion History9.2.2 Handling Pointer Button Events9.2.3 Changing the Pointer Button Mapping9.2.4 Moving the Pointer
9.3.1 The KeymapNotify Event
9.4.1 Implementing Type-ahead for Information Entry
9.5.1 Setting Keyboard Preferences9.5.2 Getting Keyboard Preferences
10.1 An Overview of Internationalization10.1.1 Internationalization with ANSI-C10.1.2 Text Representation in an Internationalized Application10.1.2.1 ISO8859-1 and Other Encodings10.1.2.2 Multi-byte Strings and Wide-character Strings10.1.3 Internationalization Using X
10.3.1 Creating and Manipulating Fontsets10.3.2 Querying Fontset Metrics10.3.3 Context Dependencies in Displayed Text10.3.4 Measuring Strings10.3.5 Drawing Internationalized Text
11.1 Issues of Internationalized Text Input
11.2.1 Input Methods and Input Servers11.2.2 User Interaction with an Input Method11.2.3 The X Input Method11.2.4 The X Input Context11.2.5 Input Context Focus Management11.2.6 Preedit and Status Area Geometry Management11.2.7 Preedit and Status Callbacks11.2.8 Getting Composed Input11.2.9 Filtering Events11.2.10 The Big Picture
11.4.1 Opening and Closing an Input Method11.4.2 Querying Input Method Values
11.5.1 Choosing an Interaction Style11.5.2 Creating and Destroying Input Contexts11.5.3 Querying and Modifying an XIC11.5.4 Resetting an Input Context11.5.5 Setting Input Context Focus11.5.6 Input Context Utility Functions
11.6.1 XNInputStyle11.6.2 XNClientWindow11.6.3 XNFocusWindow11.6.4 XNResourceName and XNResourceClass11.6.5 XNGeometryCallback11.6.6 XNFilterEvents11.6.7 XNPreeditAttributes and XNStatusAttributes11.6.7.1 XNArea11.6.7.2 XNAreaNeeded11.6.7.3 XNSpotLocation11.6.7.4 XNColormap11.6.7.5 XNStdColormap11.6.7.6 XNForeground11.6.7.7 XNBackground11.6.7.8 XNBackgroundPixmap11.6.7.9 XNFontSet11.6.7.10 XNLineSpacing11.6.7.11 XNCursor11.6.7.12 Preedit and Status Callbacks
11.8.1 The Geometry Callback11.8.2 The PreeditStartCallback and the PreeditEndCallback11.8.3 The PreeditDrawCallback11.8.4 The PreeditCaretCallback11.8.5 The StatusStartCallback and the StatusDoneCallback11.8.6 The StatusDrawCallback
12.1 Properties and Atoms
12.3.1 Standard Properties for Window Manager12.3.1.1 Application Name – XA_WM_NAME12.3.1.2 Icon Name - XA_WM_ICON_NAME12.3.1.3 Window Size Hints - XA_WM_NORMAL_HINTS12.3.1.4 Additional Window Manager Hints – XA_WM_HINTS12.3.1.4.1 Flags Field12.3.1.4.2 Input Field and the Keyboard Focus12.3.1.4.3 Initial State Field12.3.1.4.4 Icon Hints Fields12.3.1.4.5 Window Group Field12.3.1.4.6 Transient Window Field12.3.1.5 Application Class Name and Instance Name – XA_WM_CLASS12.3.2 Standard Properties for Session Manager12.3.2.1 Application Command and Arguments12.3.2.2 Client Machine12.3.3 Optional Properties for Window and Session Manager12.3.3.1 Using Created Colormaps - WM_COLORMAP_WINDOWS12.3.3.2 Window Manager Protocols - WM_PROTOCOLS12.3.3.2.1 WM_TAKE_FOCUS12.3.3.2.2 WM_SAVE_YOURSELF12.3.3.2.3 WM_DELETE_WINDOW12.3.4 Properties Set by the Window Manager12.3.4.1 XA_WM_ICON_SIZE12.3.4.2 WM_STATE12.3.5 Text Properties12.3.6 Constraints on Client Actions12.3.6.1 Changing Application State12.3.6.2 Reconfiguring the Top-level Window
12.4.1 The Selection Mechanism12.4.2 An Example of Selection12.4.3 Acquiring Selection Ownership12.4.4 Responsibilities of the Selection Owner12.4.5 Giving Up Selection Ownership12.4.6 Requesting a Selection12.4.7 Large Data Transfers12.4.8 More on Selection Properties and Types12.4.9 Target Atoms
13.1 Using XGetDefault()
13.2.1 Resource Files and Merging13.2.2 Including Files in a Resource File13.2.3 Resource Properties13.2.4 The Low Level Xrm Routines
13.4.1 Tight Bindings and Loose Bindings13.4.2 Wildcarding Resource Component Names13.4.3 The -name Option13.4.4 Storage/Access Rules13.4.5 Resource Manager Values and Representation Types
13.5.1 Putting Resources into the Database13.5.2 Combining the Contents of Databases13.5.3 Enumerating Database Entries13.5.4 Associating a Resource Database with a Display13.5.5 Getting the Locale of a Database13.5.6 Quarks
14.1 Description of basecalc
14.4.1 User Defaults for basecalc14.4.2 Parsing the Command Line14.4.3 Getting the Databases14.4.4 Getting Options from the Database
15.1 Reading and Writing Properties
15.3.1 The Host Access List15.3.2 Enabling and Disabling Access Control
15.7.1 The Context Manager
15.10.1 <X11/Xosdefs.h>15.10.2 <X11/Xos.h>15.10.3 <X11/Xfuncs.h>15.10.4 <X11/Xfuncproto.h>15.10.5 Other Symbols
16.1 Layout Policy
16.3.1 Shadows
16.5.1 Reading the Hints16.5.2 Setting Icon Sizes16.5.3 Window Manager Protocols
16.7.1 Operation of the Program16.7.2 Description of the Code of main16.7.3 Window Layering16.7.4 Selecting Input16.7.5 Handling Input16.7.6 Inverting an Area16.7.7 Cursors16.7.8 Grabbing the Pointer16.7.9 Painting the Menu16.7.10 Circulating Windows16.7.11 Raising and Lowering Windows16.7.12 Moving and Resizing Windows16.7.13 The draw_box Routine16.7.14 (De)Iconifying Windows16.7.15 Creating the Icons16.7.16 Getting the Icon Size16.7.17 Updating the Icon List16.7.18 Removing Icons16.7.19 Changing Keyboard Focus16.7.20 Drawing the Focus Frame16.7.21 Executing a Shell Command
A.1 Font SpecificationA.1.1 Font Naming ConventionsA.1.2 Font Name WildcardingA.1.3 Font Name AliasingA.1.4 Making the Server Aware of AliasesA.1.5 The fonts.dir Files
A.2.1 Font Server NamingA.2.2 Font Server Configuration
A.3.1 Finding Scalable FontsA.3.2 Finding Derived Instances of Scalable FontsA.3.3 Using Scalable Fonts
B.1 XDraw and XDrawFilled()
C.1 Basic Protocol Support RoutinesC.1.1 XListExtensionsC.1.2 XFreeExtensionList
C.2.1 XInitExtensionC.2.2 XAddExtensionC.2.3 Hooks into the LibraryC.2.3.1 XESetCloseDisplayC.2.3.2 XESetCreateGCC.2.3.3 XESetCopyGCC.2.3.4 XESetFreeGCC.2.3.5 XESetCreateFontC.2.3.6 XESetFreeFontC.2.4 Defining New Events and ErrorsC.2.4.1 XESetWireToEventC.2.4.2 _XSetLastRequestReadC.2.4.3 XESetEventToWireC.2.4.4 XESetWireToErrorC.2.4.5 XESetErrorC.2.4.6 XESetErrorStringC.2.4.7 XESetPrintErrorValuesC.2.4.8 XESetFlushGCC.2.5 Hooks onto Xlib Data StructuresC.2.5.1 XEHeadOfExtensionListC.2.5.2 XAddToExtensionListC.2.5.3 XFindOnExtensionListC.2.5.4 XAllocID
C.5.1 Requests, Replies, and Xproto.hC.5.2 Request FormatC.5.3 Starting to Write a Stub RoutineC.5.4 Locking Data StructuresC.5.5 Sending the Protocol Request and ArgumentsC.5.6 Variable Length ArgumentsC.5.7 RepliesC.5.7.1 _XRead16C.5.7.2 _XRead32C.5.7.3 _XRead16PadC.5.7.4 _XReadPadC.5.8 Synchronous CallingC.5.9 Allocating and Deallocating MemoryC.5.10 Portability ConsiderationsC.5.11 Deriving the Correct Extension Opcode
E.1 Meaning of Common Structure Elements
F.1 Atom Functions
G.1 Getting the X SoftwareG.1.1 Bug FixesG.1.1.1 NotesG.1.1.2 Fairness
H.1 Changes from Release 4 to Release 5H.1.1 InternationalizationH.1.2 X Color Management SystemH.1.3 Resource ManagementH.1.4 Scalable Font Support
H.3.1 New RoutinesH.3.2 Existing Interface ChangesH.3.2.1 XOpenDisplay()H.3.2.2 Error HandlersH.3.2.3 Nonstandard KeysymsH.3.2.4 XReadBitmapFile()H.3.2.5 Resource Specification SyntaxH.3.2.6 XrmParseCommand()H.3.2.7 Keyboard Groups

Content preview from XLIB Programming Manual, Rel. 5, Third Edition

10.3 Internationalized Text Output in X

Before R5, the Xlib drawing routines made the fundamental assumption that the encoding of a character was equal to the index of the character’s glyph in the font. As explained in 10.1.2 Text Representation in an Internationalized Application, this is a useful and valid assumption when text in a language can be most naturally encoded as an 8- or 16-bit wide charset. Unfortunately, it is not valid in many important cases.

R5 bases its new text output routines on a new Xlib abstraction, the XFontSet. An XFontSet is bound to the locale in which it is created, and contains all the fonts needed to display text in that locale, or all the independent charsets used in the encoding of that locale. Technical Japanese text, for example, often mixes Latin with Japanese characters, so for a Japanese locale, fonts might be required with the charsets jisx0208.1983-0 for Kanji ideographic characters, jisx0201.1976-0 for Kana phonetic characters, and iso8859-1 for Latin characters.

Drawing internationalized text in R5 is conceptually very similar to drawing text in X11R4—there are routines that allow you to query font metrics, measure strings, and draw strings. The new R5 functions use an XFontSet rather than an XFontStruct or a font specified in a graphics context. The drawing and measuring routines interpret text in the encoding of the locale of the fontset, and correctly map wide or multi-byte characters to the corresponding font glyph (or glyphs).