Order Number: AA--PGZDA--TE
This manual is a guide to programming Xlib routines.
Revision/Update Information: This is a new manual.
Operating System: VMS Version 5.4
Software Version: VMS DECwindows Motif Version 1.0
Digital Equipment Corporation
Maynard, Massachusetts
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 license.
No responsibility is assumed for the use or reliability of software on equipment that is not supplied by Compaq Computer Corporation or its affiliated companies.
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 Typeface Corporation.
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.
ZK5643
This document was prepared using DECdocument, Version V3.3-1e.
| Contents | Index |
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 documentation set.
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 graphics programming.
This manual is organized as follows:
This manual also includes the following appendixes:
The following documents contain additional information:
The following conventions are used in this manual:
| mouse | The term mouse is used to refer to any pointing device, such as a mouse, a puck, or a stylus. |
|
MB1 (Select)
MB2 (Drag) MB3 (Menu) |
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.) |
| Ctrl+x | 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 button. |
|
.
. . |
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 |
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 the book. |
| italic text | Italic text represents information that can vary in system messages (for example, Internal error number). |
| UPPERCASE TEXT | 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 system privilege. |
| - | Hyphens in coding examples indicate that additional arguments to the request are provided on the line that follows. |
| numbers | Unless otherwise noted, all numbers in the text are assumed to be decimal. Nondecimal radixes---binary, octal, or hexadecimal---are explicitly indicated. |
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:
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:
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 networking software.
Figure 1-1 Client, Xlib, and Server
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 text displayed.
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.
1.2.1.1 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 children. 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
WINDOW_1).
1.2.1.2 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.
1.2.1.3 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.
1.2.1.4 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:
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 shutdown routines.
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 |
|---|
PROGRAM SAMPLE_PROGRAM
INCLUDE 'SYS$LIBRARY:DECW$XLIBDEF'
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
CHARACTER*19 WINDOW_NAME
DATA WINDOW_NAME /'Sample Xlib Program'/
CHARACTER*60 FONT_NAME
DATA FONT_NAME
1 /' -Adobe-New Century Schoolbook-Medium-R-Normal--*-140-*-*-P-*-ISO8859-1'/
CHARACTER*19 MESSAGE(2)
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
C Initialize display id and screen id
C
(1) DPY = X$OPEN_DISPLAY()
IF (DPY .EQ. 0) THEN
WRITE(6,*) 'Display not opened!'
CALL SYS$EXIT(%VAL(1))
END IF
SCREEN = X$DEFAULT_SCREEN_OF_DISPLAY(DPY)
(2) STATUS = X$SYNCHRONIZE(DPY,1, FUNC)
C
C Create the WINDOW_1 window
C
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
XSWDA.X$L_SWDA_BACKGROUND_PIXEL =
1 DEFINE_COLOR(DPY, SCREEN, VISUAL, 1)
(3) WINDOW_1 = X$CREATE_WINDOW(DPY,
1 X$ROOT_WINDOW_OF_SCREEN(SCREEN),
1 WINDOW_1X, WINDOW_1Y, WINDOW_1W, WINDOW_1H, 0,
1 DEPTH, X$C_INPUT_OUTPUT, VISUAL, ATTR_MASK, XSWDA)
C
C Create the WINDOW_2 window
C
XSWDA.X$L_SWDA_BACKGROUND_PIXEL =
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
C Create graphics context
C
XGCVL.X$L_GCVL_FOREGROUND =
1 DEFINE_COLOR(DPY, SCREEN, VISUAL, 3)
XGCVL.X$L_GCVL_BACKGROUND =
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
C Load the font for text writing
C
(5) FONT = X$LOAD_FONT(DPY, FONT_NAME)
CALL X$SET_FONT(DPY, GC, FONT)
C
C Map the windows
C
(6) CALL X$MAP_WINDOW(DPY, WINDOW_1)
CALL X$MAP_WINDOW(DPY, WINDOW_2)
C
C Handle events
C
(7) DO WHILE (.TRUE.)
CALL X$NEXT_EVENT(DPY, EVENT)
C
C If this is an expose event on our child window,
C then write the text.
C
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))
END IF
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))
ELSE
C
C Unmap and destroy windows
C
(8) CALL X$DESTROY_WINDOW(DPY, WINDOW_1)
CALL X$CLOSE_DISPLAY(DPY)
CALL SYS$EXIT(%VAL(1))
END IF
END IF
END DO
END
C
C
C Create color
C
(9) INTEGER*4 FUNCTION DEFINE_COLOR(DISP, SCRN, VISU, N)
INCLUDE 'SYS$LIBRARY:DECW$XLIBDEF'
INTEGER*4 DISP, SCRN, N
RECORD /X$VISUAL/ VISU
RECORD /X$COLOR/ SCREEN_COLOR
INTEGER*4 STR_SIZE, STATUS, COLOR_MAP
CHARACTER*15 COLOR_NAME(3)
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
ELSE
WRITE(6,*) 'Color not allocated!'
CALL LIB$SIGNAL(%VAL(STATUS))
DEFINE_COLOR = 0
END IF
ELSE
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)
END IF
RETURN
END
|
| Next | Contents | Index |