HP OpenVMS Systems Documentation

VMS DECwindows Guide to Xlib (Release 4) Programming: VAX Binding

August 1991

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

August 1991

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.

Copyright ©1991

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

Preface

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.

Note

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.

Intended Audience

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.

Document Structure

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.

Associated Documents

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

Conventions

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.

Chapter 1
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
Windows
Colors
Graphics characteristics such as line width and line style
Graphics
Cursors
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 networking software.

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

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

Contents

Index

HP OpenVMS Systems Documentation

VMS DECwindows Guide to Xlib (Release 4) Programming: VAX Binding

August 1991

Copyright ©1991

Preface

Intended Audience

Document Structure

Associated Documents

Conventions

Chapter 1Programming Overview of Xlib

1.1 Overview of Xlib

1.2 Sample Xlib Program

1.2.1 Initializing Xlib Resources

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 Handling Events

Chapter 1
Programming Overview of Xlib