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.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

  10     Using the X Resource Manager

  10.1    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    Resource Manager Value Data Structure

  10.4    Storing Resources into a Database

  10.5    Retrieving from the Resource Database

  10.6    Merging and Storing Databases

  10.7    Using Representations for Strings
    10.7.1     Converting a String to a Quark
    10.7.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

  A   Compiling Fonts

  B   Routines Requiring Protocol Requests

  C   VMS DECwindows Named Colors

  D   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

  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        Specifying an Arc

  6-7        Multiple Arcs Drawn Using the DRAW ARCS Routine

  6-8        Filled Star Created Using the FILL POLYGON Routine

  6-9        Arcs Drawn Within a Region

  6-10       Intersection of Two Regions

  6-11       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        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

  10-1       Example of Using a Name and a Class

  10-2       Resource Manager Matching Rules

  10-3       Resource Manager Value Data Structure Members

  11-1       Predefined Values for ALLOW EVENTS Routine

  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