Technical Standard Window Management (X11R5): Xlib-C Language Binding NICAL H S C T A E N T D A R D [This page intentionally left blank] X/Open CAE Specification Window Management (X11R5): Xlib - C Language Binding X/Open Company Ltd. May 1995, X/Open Company Limited All rights reserved. No part of this publication may be reproduced, stored in a retrieval system, or transmitted, in any form or by any means, electronic, mechanical, photocopying, recording or otherwise, without the prior permission of the copyright owners. This specification is derived from documents which are Copyright 1985, 1986, 1987, 1988, 1989, 1990, 1991 by Massachusetts Institute of Technology, Cambridge, Massachusetts, and Digital Equipment Corporation, Maynard, Massachusetts, and Copyright 1990, 1991 by Tektronix, Inc. Permission for X/Open to use, copy, modify and distribute this documentation for any purpose and without fee has been granted by these copyright owners. X/Open CAE Specification Window Management (X11R5): Xlib - C Language Binding ISBN: ISBN 1-85912-088-1 X/Open Document Number: C508 Published by X/Open Company Ltd., U.K. Any comments relating to the material contained in this document may be submitted to X/Open at: X/Open Company Limited Apex Plaza Forbury Road Reading Berkshire, RG1 1AX United Kingdom or by Electronic Mail to: [email protected] ii X/Open CAE Specification Contents Chapter 1 Overview of the X Window System ............................................... 1 1.1 Introduction..................................................................................................... 1 1.2 X Window System Overview....................................................................... 2 1.2.1 X Platform Abstraction Layers.................................................................. 2 1.2.2 User Interface Platform .............................................................................. 3 1.2.3 A Single X Application ............................................................................... 4 1.2.4 X Application Relationships...................................................................... 5 Chapter 2 Introduction to Xlib.................................................................................. 7 2.1 General Concepts............................................................................................ 8 2.2 Status ................................................................................................................. 10 2.3 Errors................................................................................................................. 11 2.4 Standard Header Files ................................................................................... 12 2.5 Generic Values and Types............................................................................. 14 2.6 Naming and Argument Conventions within Xlib................................... 15 2.7 Programming Considerations...................................................................... 16 2.8 Character Sets and Encodings...................................................................... 17 2.9 Formatting Conventions ............................................................................... 18 Chapter 3 Display Functions...................................................................................... 19 3.1 Opening the Display ...................................................................................... 20 3.2 Obtaining Information about the Display, Image Formats or Screens.........21 3.2.1 Display Macros............................................................................................. 21 3.2.2 Image Format Functions and Macros...................................................... 26 3.2.3 Screen Information Macros........................................................................ 28 3.3 Generating a NoOperation Protocol Request........................................... 32 3.4 Freeing Client-created Data.......................................................................... 33 3.5 Closing the Display ........................................................................................ 34 3.6 X Server Connection Close Operations...................................................... 35 Chapter 4 Window Functions .................................................................................... 37 4.1 Visual Types..................................................................................................... 38 4.2 Window Attributes......................................................................................... 40 4.2.1 Background Attribute ................................................................................. 42 4.2.2 Border Attribute........................................................................................... 43 4.2.3 Gravity Attributes ....................................................................................... 43 4.2.4 Backing Store Attribute .............................................................................. 44 4.2.5 Save Under Flag ........................................................................................... 45 4.2.6 Backing Planes and Backing Pixel Attributes ........................................ 45 4.2.7 Event Mask and Do Not Propagate Mask Attributes .......................... 45 4.2.8 Override Redirect Flag................................................................................ 45 4.2.9 Colormap Attribute..................................................................................... 46 Window Management (X11R5): Xlib - C Language Binding iii Contents 4.2.10 Cursor Attribute........................................................................................... 46 4.3 Creating Windows.......................................................................................... 47 4.4 Destroying Windows ..................................................................................... 50 4.5 Mapping Windows ........................................................................................ 51 4.6 Unmapping Windows ................................................................................... 53 4.7 Configuring Windows ................................................................................... 54 4.8 Changing Window Stacking Order ............................................................ 58 4.9 Changing Window Attributes ..................................................................... 61 Chapter 5 Window Information Functions ....................................................... 65 5.1 Obtaining Window Information.................................................................. 66 5.2 Translating Screen Coordinates................................................................... 70 5.3 Properties and Atoms .................................................................................... 72 5.4 Obtaining and Changing Window Properties.......................................... 75 5.5 Selections.......................................................................................................... 79 Chapter 6 Pixmap and Cursor Functions ............................................................ 81 6.1 Creating and Freeing Pixmaps..................................................................... 82 6.2 Creating, Recoloring and Freeing Cursors ................................................ 83 Chapter 7 Color Management Functions............................................................ 87 7.1 Color Structures .............................................................................................. 89 7.2 Color Strings .................................................................................................... 92 7.2.1 RGB Device String Specification............................................................... 92 7.2.2 RGB Intensity String Specification........................................................... 93 7.2.3 Device-independent String Specifications.............................................. 93 7.3 Color Conversion Contexts and Gamut Mapping .................................. 94 7.4 Creating, Copying and Destroying Colormaps ....................................... 95 7.5 Mapping Color Names to Values ................................................................ 97 7.6 Allocating and Freeing Color Cells............................................................. 99 7.7 Modifying and Querying Colormap Cells ................................................ 104 7.8 Color Conversion Context Functions......................................................... 109 7.8.1 Getting and Setting the Color Conversion Context of a Colormap.. 109 7.8.2 Obtaining the Default Color Conversion Context................................ 110 7.8.3 Color Conversion Context Macros .......................................................... 110 7.8.4 Modifying Attributes of a Color Conversion Context......................... 111 7.8.5 Creating and Freeing a Color Conversion Context .............................. 112 7.9 Converting Between Color Spaces.............................................................. 114 7.10 Callback Functions ......................................................................................... 115 7.10.1 Prototype Gamut Compression Procedure............................................ 115 7.10.2 Supplied Gamut Compression Procedures............................................ 116 7.10.3 Prototype White Point Adjustment