VMS DECwindows Guide to Xlib (Release 4) Programming: VAX
VMS DECwindows Guide to Xlib (Release 4)
Programming: VAX Binding
This manual is a guide to programming Xlib routines.
This is a new manual.
VMS Version 5.4
VMS DECwindows Motif Version 1.0
Digital Equipment Corporation
The information in this document is subject to change without notice
and should not be construed as a commitment by Compaq Computer
Corporation. Compaq Computer Corporation assumes no responsibility for
any errors that may appear in this document.
The software described in this document is furnished under a license
and may be used or copied only in accordance with the terms of such
No responsibility is assumed for the use or reliability of software on
equipment that is not supplied by Compaq Computer Corporation or its
Restricted Rights: Use, duplication, or disclosure by the U.S.
Government is subject to restrictions as set forth in subparagraph
(c)(1)(ii) of the Rights in Technical Data and Computer Software clause
at DFARS 252.227-7013.
The following are trademarks of Compaq Computer Corporation:
Bookreader, CDA, DEC, DECnet, DECwindows, DECwrite, Digital, LinkWorks,
LiveLink, LN03, MicroVAX, PrintServer, ReGIS, ULTRIX, VAX, VAXcluster,
VAXserver, VAXstation, VMS, VT, XUI, and the DIGITAL logo.
Adobe is a registered trademark of Adobe Systems Incorporated.
BITSTREAM is a registered trademark of Bitstream, Inc.
Helvetica is a trademark of Linotype AG or its subsidiaries, or both.
ITC Avant Garde Gothic is a registered trademark of International
Motif is a trademark of the Open Software Foundation, Inc.
Open Software Foundation, OSF, OSF/Motif, and Motif are trademarks of
the Open Software Foundation, Inc.
PostScript is a registered trademark of Adobe Systems Incorporated.
Sony is a registered trademark of Sony Corporation.
Times is a trademark of Linotype AG or its subsidiaries, or both.
This document was prepared using DECdocument, Version V3.3-1e.
This manual describes how to program Xlib routines using the VAX
binding. VMS DECwindows provides the VAX binding for Xlib programmers
who want to adhere to the VAX calling standard. For information about
the standard, see the Introduction to VMS System Routines in the VMS operating system
The manual includes an overview of Xlib and tutorials that show how to
use Xlib routines.
This manual uses a generic format when referring to Xlib routine names
in text. Routine names are represented in all uppercase letters with
separating spaces. In addition, the X prefix has been omitted. For
example, in text the routine name is written as OPEN DISPLAY; however,
the VAX Binding format of the same routine is X$OPEN_DISPLAY.
See the DECwindows Motif for OpenVMS Guide to Non-C Bindings for a complete reference of all VAX Binding Xlib
routines. See the X Window System for a description of the routines.
This manual is intended for experienced programmers who need to learn
graphics programming using Xlib routines. Readers should be familiar
with a high-level language. The manual requires minimal knowledge of
This manual is organized as follows:
- Chapter 1 provides an overview of Xlib, a sample Xlib program,
and a guide to debugging Xlib programs.
- Chapters 2 through 9 provide tutorials that show how to use Xlib
routines and include descriptions of predefined Xlib data structures
and code examples that illustrate the concepts described.
This manual also includes the following appendixes:
- Appendix A is a guide to using the VMS DECwindows font compiler.
- Appendix B provides information about VMS DECwindows named colors.
- Appendix C lists VMS DECwindows fonts.
The following documents contain additional information:
- X Window System---Provides detailed descriptions of each Xlib routine,
as well as, the Inter-Client Communication Conventions Manual (ICCCM),
the X Logical Font Description Conventions, and the X Window System
- DECwindows Motif for OpenVMS Guide to Non-C Bindings--- Describes non-C bindings for Xlib, Intrinsics,
Motif Toolkit, and Digital extension routines.
- DECwindows Extensions to Motif--- Provides reference information on the Digital
extensions to Motif.
- DECwindows Companion to the OSF/Motif Style Guide--- Covers style issues for Digital extensions to Motif
and topics not addressed in the OSF/Motif Style Guide.
- DECwindows Motif Guide to Application Programming--- Describes how to program with the Digital
extensions to the Motif Toolkit. It supplements the OSF/Motif Programmer's Guide.
- X and Motif Quick Reference Guide--- Provides quick reference information on Xlib,
Intrinsics, and the Motif Toolkit.
- OSF/Motif Style Guide--- Describes style guidelines for applications based
on the Motif Toolkit.
- OSF/Motif Programmer's Guide--- Describes how to program with the Motif Window
Manager, Motif Toolkit, and the Motif User Interface Language (UIL).
- OSF/Motif Programmer's Reference--- Provides reference information on the Motif Toolkit.
The following conventions are used in this manual:
mouse is used to refer to any pointing device, such as a
mouse, a puck, or a stylus.
MB1 indicates the left mouse button, MB2 indicates the middle mouse
button, and MB3 indicates the right mouse button. (The buttons can be
redefined by the user.)
A sequence such as Ctrl+x (or Ctrl/x) indicates that you must hold down
the key labeled Ctrl while you press another key or a pointing device
A vertical ellipsis indicates the omission of items from a code example
or command format; the items are omitted because they are not important
to the topic being discussed.
In format descriptions, brackets indicate that whatever is enclosed
within the brackets is optional; you can select none, one, or all of
the choices. (Brackets are not, however, optional in the syntax of a
directory name in a file specification or in the syntax of a substring
specification in an assignment statement.)
Boldface text represents the introduction of a new term or the name of
an argument, an attribute, or a reason.
Boldface text is also used to show user input in online versions of
Italic text represents information that can vary in system messages
(for example, Internal error
Uppercase letters indicate that you must enter a command (for example,
enter OPEN/READ), or they indicate the name of a routine, the name of a
file, the name of a file protection code, or the abbreviation for a
Hyphens in coding examples indicate that additional arguments to the
request are provided on the line that follows.
Unless otherwise noted, all numbers in the text are assumed to be
decimal. Nondecimal radixes---binary, octal, or hexadecimal---are
Programming Overview of Xlib
The VMS DECwindows programming environment includes Xlib, a library of
low-level routines that enable the VMS DECwindows programmer to perform
windowing and graphics operations.
This chapter provides the following:
- An overview of the library
- A description of error-handling conditions
- Xlib debugging techniques
Additionally, the chapter includes an introductory Xlib program. The
program includes annotations that are explained more completely in the
programming descriptions in later chapters of this guide.
1.1 Overview of Xlib
The VMS DECwindows programming environment enables application
programs, called clients, to interact with
workstations using the X Window System, Version 11 protocol software.
The program that controls workstation devices such as screens and
pointing devices is the server.
Xlib is a library of routines that enables a client to communicate with
the server to create and manage the following:
- Connections between clients and the server
- Graphics characteristics such as line width and line style
- Fonts and text
- Pixmaps and offscreen images
- Windowing and sending graphics between clients
- Client notification of windowing and graphics operations
Xlib processes some client requests, such as requests to measure the
width of a character string, within the Xlib library. It sends other
client requests, such as those pertaining to putting graphics on a
screen or receiving device input, to the server.
The server returns information to clients through either replies or
events. Replies and events both return information to clients; the
server returns replies synchronously and events asynchronously.
See the X Window System for a list of routines that cause Xlib to send
requests to the server.
Figure 1-1 illustrates the relationships among client, Xlib, and
server. The client calls Xlib routines, which always reside on the
client system. If possible, Xlib processes calls internally and returns
information to the client when appropriate. When an Xlib routine
requires server intervention, Xlib generates a request and sends the
request to the server.
The server may or may not reside on the same system as the client and
Xlib. In either case, Xlib communicates with the server through a
transport protocol, which can be either local shared memory or DECnet
Figure 1-1 Client, Xlib, and Server
1.2 Sample Xlib Program
The introductory Xlib program described in Example 1-1 illustrates the
structure of a typical client program that uses Xlib windowing and
graphic operations. The program creates two windows, draws text into
one of them, and exits if the user clicks any mouse button while the
cursor is in the window containing text.
This section describes the program and introduces fundamental concepts
about Xlib resources, windowing, and event-handling.
1.2.1 Initializing Xlib Resources
The sample program begins by creating Xlib resources that the client
needs in order to perform tasks. Xlib resources include windows, fonts,
pixmaps, cursors, color maps, and data structures that define the
characteristics of graphics objects. The sample program uses a default
font, default cursor, default color map, client-defined windows, and a
client-defined data structure that specifies the characteristics of the
The program first makes a connection between the client and the server.
The client-server connection is the display. After
making the connection, or opening the display, the client can get
display information from the server. For example, immediately after
opening the display, the program calls the DEFAULT SCREEN OF DISPLAY
routine to get the identifier of the default screen. The program uses
the identifier as an argument in a variety of routines it calls later.
220.127.116.11 Creating Windows
A window is an area of the screen that either receives
input or both receives input and displays graphics.
Windows in the X Window System are hierarchically related. At the base
of the hierarchy is the root window.
All windows that a client creates after opening a display are
inferiors of the root window.
The sample program includes two inferiors of the root window.
First-generation inferiors of a window are its
The root window has one child, identified in the sample
asWINDOW_1. The window named WINDOW_2 is an inferior
of the root window and a child of WINDOW_1.
To complete the window genealogy, all windows created before a
specified window and hierarchically related to it are its ancestors. In
the sample program, WINDOW_1 has one ancestor (the root
window); WINDOW_2 has two ancestors (the root window and
18.104.22.168 Defining Colors
Defining background and foreground colors is part of the process of
creating windows in the sample program. The DEFINE_COLOR subroutine
allocates named VMS DECwindows colors for client use in a way that
permits other clients to share the same color resource. For example,
the routine specifies the VMS DECwindows color named "light
grey" as the background color of WINDOW_2. If other
clients were using VMS DECwindows color resources, they too could
access the VMS DECwindows data structure that defines "light
grey." Sharing enables clients to use color resources efficiently.
The program calls the DEFINE_COLOR subroutine again in the next step of
initialization, creating the graphics context that defines the
characteristics of a graphics object. In this case, the program defines
foreground and background colors used when writing text.
22.214.171.124 Working with the Window Manager
Most clients run on systems that have a window manager, which is an
Xlib application that controls conflicts between clients. The window
manager also provides the user with control of the appearance of the
window session screen. Clients provide the window manager with
information about how it should treat client resources, although the
manager can ignore the information. The sample program provides the
window manager with information about the size and placement of
WINDOW_1. Additionally, the program assigns a name that the
window manager displays in the title bar of WINDOW_1.
126.96.36.199 Making Windows Visible on the Screen
Creating windows does not make them visible. To make its windows
visible, a client must map them, painting the windows
on a specified screen. The last step of initializing the sample program
is to map WINDOW_1 and WINDOW_2.
1.2.2 Handling Events
The core of an Xlib program is a loop in which the client waits for the
server to notify it of an event, which is a report of
either a change in the state of a device or the execution of a routine
call by another client. The server can report 30 types of events
associated with the following occurrences:
- Key presses and releases
- Pointer motion
- Window entries and exits
- Changes of keyboards receiving input
- Changes in keyboard configuration
- Window and graphics exposures
- Changes in window hierarchy and configuration
- Requests by other clients to change windows
- Changes in available color resources
- Communication from other clients
When an event occurs, the server sends information about the event to
Xlib. Xlib stores the information in a data structure. If the client
has specified an interest in that kind of event, Xlib puts the data
structure on an event queue. The sample program polls the event queue
to determine if it contains an event of interest to the client. When
the program finds an event that is of interest to the client, the
program performs a task.
Because Xlib clients do their essential work in response to events,
they are event driven.
The sample program continually checks its event queue to determine if a
window has been made visible or a button has been clicked. When the
server informs it of either kind of event, the program performs its
real work, as follows.
If a window has been made visible, the server reports a window exposure
event. Upon receiving this type of event, the program determines
whether the window exposed is WINDOW_2, and if the event is
the first instance of the exposure. If both conditions are true, the
program writes a message into the window.
If the event reported is a button press, the program checks to make
certain the cursor is in WINDOW_2 when the user clicks the
mouse button. If the user clicks the mouse button when the cursor is in
WINDOW_1, the program reminds the user to click on
WINDOW_2. Otherwise, the program initiates a series of
The shutdown routines unmap WINDOW_1 and WINDOW_2,
free resources allocated for the windows, break the connection between
the sample program and its server, and exit the system.
On the VMS operating system, clients only need to call SYS$EXIT.
Exiting the system causes the other shutdown operations to occur. The
call to SYS$EXIT breaks the connection between client and server, which
frees resources allocated for client windows, and so forth.
See Example 1-1 for the sample Xlib program.
|Example 1-1 Sample Program
INTEGER*4 DPY ! display id
INTEGER*4 SCREEN ! screen id
INTEGER*4 WINDOW_1, WINDOW_2 ! window id
INTEGER*4 ATTR_MASK ! attributes mask
INTEGER*4 GC ! gc id
INTEGER*4 FONT ! font id
INTEGER*4 DEFINE_COLOR ! color function
INTEGER*4 WINDOW_1X, WINDOW_1Y ! window origin
INTEGER*4 DEPTH ! number of planes
INTEGER*4 STATUS, FUNC ! synchronous behavior
INTEGER*4 STATE ! flag for text
RECORD /X$VISUAL/ VISUAL ! visual type
RECORD /X$SET_WIN_ATTRIBUTES/ XSWDA ! window attributes
RECORD /X$GC_VALUES/ XGCVL ! gc values
RECORD /X$EVENT/ EVENT ! input event
DATA WINDOW_NAME /'Sample Xlib Program'/
1 /' -Adobe-New Century Schoolbook-Medium-R-Normal--*-140-*-*-P-*-ISO8859-1'/
DATA MESSAGE /'Click here to exit ', 'Click HERE to exit!'/
PARAMETER WINDOW_1W = 400, WINDOW_1H = 300,
1 WINDOW_2W = 300, WINDOW_2H = 150,
1 WINDOW_2X = 50, WINDOW_2Y = 75
STATE = 1
C Initialize display id and screen id
(1) DPY = X$OPEN_DISPLAY()
IF (DPY .EQ. 0) THEN
WRITE(6,*) 'Display not opened!'
SCREEN = X$DEFAULT_SCREEN_OF_DISPLAY(DPY)
(2) STATUS = X$SYNCHRONIZE(DPY,1, FUNC)
C Create the WINDOW_1 window
WINDOW_1X = (X$WIDTH_OF_SCREEN(DPY) - WINDOW_1W) / 2
WINDOW_1Y = (X$HEIGHT_OF_SCREEN(DPY) - WINDOW_1H) / 2
DEPTH = X$DEFAULT_DEPTH_OF_SCREEN(SCREEN)
CALL X$DEFAULT_VISUAL_OF_SCREEN(SCREEN, VISUAL)
ATTR_MASK = X$M_CW_EVENT_MASK .OR. X$M_CW_BACK_PIXEL
XSWDA.X$L_SWDA_EVENT_MASK = X$M_EXPOSURE .OR. X$M_BUTTON_PRESS
1 DEFINE_COLOR(DPY, SCREEN, VISUAL, 1)
(3) WINDOW_1 = X$CREATE_WINDOW(DPY,
1 WINDOW_1X, WINDOW_1Y, WINDOW_1W, WINDOW_1H, 0,
1 DEPTH, X$C_INPUT_OUTPUT, VISUAL, ATTR_MASK, XSWDA)
C Create the WINDOW_2 window
1 DEFINE_COLOR(DPY, SCREEN, VISUAL, 2)
WINDOW_2 = X$CREATE_WINDOW(DPY, WINDOW_1,
1 WINDOW_2X, WINDOW_2Y, WINDOW_2W, WINDOW_2H, 4,
1 DEPTH, X$C_INPUT_OUTPUT, VISUAL, ATTR_MASK, XSWDA)
C Define the name of the window
CALL X$STORE_NAME(DPY, WINDOW_1, WINDOW_NAME)
C Create graphics context
1 DEFINE_COLOR(DPY, SCREEN, VISUAL, 3)
1 DEFINE_COLOR(DPY, SCREEN, VISUAL, 2)
(4) GC = X$CREATE_GC(DPY, WINDOW_2,
1 (X$M_GC_FOREGROUND .OR. X$M_GC_BACKGROUND), XGCVL)
C Load the font for text writing
(5) FONT = X$LOAD_FONT(DPY, FONT_NAME)
CALL X$SET_FONT(DPY, GC, FONT)
C Map the windows
(6) CALL X$MAP_WINDOW(DPY, WINDOW_1)
CALL X$MAP_WINDOW(DPY, WINDOW_2)
C Handle events
(7) DO WHILE (.TRUE.)
CALL X$NEXT_EVENT(DPY, EVENT)
C If this is an expose event on our child window,
C then write the text.
IF (EVENT.EVNT_TYPE .EQ. X$C_EXPOSE .AND.
1 EVENT.EVNT_EXPOSE.X$L_EXEV_WINDOW .EQ. WINDOW_2 THEN
CALL X$CLEAR_WINDOW(DPY, WINDOW_2)
CALL X$DRAW_IMAGE_STRING(DPY, WINDOW_2, GC,
1 75, 75, MESSAGE(STATE))
IF (EVENT.EVNT_TYPE .EQ. X$C_BUTTON_PRESS) THEN
IF (EVENT.EVNT_EXPOSE.X$L_EXEV_WINDOW .EQ. WINDOW_1) THEN
STATE = 2
CALL X$DRAW_IMAGE_STRING(DPY, WINDOW_2, GC,
1 75, 75, MESSAGE(STATE))
C Unmap and destroy windows
(8) CALL X$DESTROY_WINDOW(DPY, WINDOW_1)
C Create color
(9) INTEGER*4 FUNCTION DEFINE_COLOR(DISP, SCRN, VISU, N)
INTEGER*4 DISP, SCRN, N
RECORD /X$VISUAL/ VISU
RECORD /X$COLOR/ SCREEN_COLOR
INTEGER*4 STR_SIZE, STATUS, COLOR_MAP
DATA COLOR_NAME /'DARK SLATE BLUE', 'LIGHT GREY ', 'FIREBRICK '/
IF (VISU.X$L_VISU_CLASS .EQ. X$C_TRUE_COLOR .OR.
1 VISU.X$L_VISU_CLASS .EQ. X$C_PSEUDO_COLOR .OR
1 VISU.X$L_VISU_CLASS .EQ. X$C_DIRECT_COLOR .OR.
1 VISU.X$L_VISU_CLASS .EQ. X$C_STATIC_COLOR) THEN
COLOR_MAP = X$DEFAULT_COLORMAP_OF_SCREEN(SCRN)
STATUS = STR$TRIM(COLOR_NAME(N),
1 COLOR_NAME(N), STR_SIZE)
STATUS = X$ALLOC_NAMED_COLOR(DISP, COLOR_MAP,
1 COLOR_NAME(N)(1:STR_SIZE), SCREEN_COLOR)
IF (STATUS .NE. 0) THEN
DEFINE_COLOR = SCREEN_COLOR.X$L_COLR_PIXEL
WRITE(6,*) 'Color not allocated!'
DEFINE_COLOR = 0
IF (N .EQ. 1 .OR. N .EQ. 3)
1 DEFINE_COLOR = X$BLACK_PIXEL_OF_SCREEN(DISP)
IF (N .EQ. 2 )
1 DEFINE_COLOR = X$WHITE_PIXEL_OF_SCREEN(DISP)