Xlib enables clients to draw text stored in text data structures, text whose foreground bits only are displayed, and text whose foreground and background bits are displayed.

To draw 8-bit or 2-byte text stored in data structures, use either the DRAW TEXT or the DRAW TEXT 16 routine. Xlib includes text item and text item 16 data structures to enable clients to store text. Figure 8-12 illustrates the text item data structure.

Figure 8-12 Text Item Data Structure

Table 8-8 Text Item 16 Data Structure Members

Member Name	Contents
X$A_TX16_CHARS	Address of a string of characters stored in a char 2B data structure. For a description of the char 2B data structure, see Figure 8-6.
X$L_TX16_N_CHARS	Number of characters in the string.
X$L_TX16_DELTA	Horizontal spacing before the start of the string. Spacing is always added to the string origin and is not dependent on the font used.
X$L_TX16_FONT	Identifier of the font used to print the string. If the value of this member is x$c_none, the server uses the current font in the GC data structure. If the member has a value other than x$c_none, the specified font is stored in the GC data structure.

Xlib processes each text item in turn. Each character image, as defined by the font in the graphics context, is treated as an additional mask for a fill operation on the drawable. The drawable is modified only where the font character has a bit set to 1.

Example 8-1 illustrates using the DRAW TEXT routine to draw three words in one call.

Example 8-1 Drawing Text Using the DRAW TEXT Routine

. . . RECORD /X$TEXT_ITEM/ TEXT_ARR(3) CHARACTER*57 FIRST_FONT DATA FIRST_FONT 1 /'-Adobe-New Century Schoolbook-Bold-R-NormaL--*-80-*-*-P-*-ISO8859-1'/ CHARACTER*58 SECOND_FONT DATA SECOND_FONT 1 /'-Adobe-New Century Schoolbook-Bold-R-Normal--*-140-*-*-P-*-ISO8859-1'/ CHARACTER*58 THIRD_FONT DATA THIRD_FONT 1 /'-Adobe-New Century Schoolbook-Bold-R-Normal--*-240-*-*-P-*-ISO8859-1'/ CHARACTER*5 FIRST_WORD DATA FIRST_WORD /'SMALL'/ CHARACTER*6 SECOND_WORD DATA SECOND_WORD /'BIGGER'/ CHARACTER*7 THIRD_WORD DATA THIRD_WORD /'BIGGEST'/ . . . C C Load the fonts for text writing C FONT_1 = X$LOAD_FONT(DPY, FIRST_FONT) TEXT_ARR(1).X$A_TEXT_CHARS = %LOC(FIRST_WORD) TEXT_ARR(1).X$L_TEXT_N_CHARS = 5 TEXT_ARR(1).X$L_TEXT_DELTA = 0 TEXT_ARR(1).X$L_TEXT_FONT = FONT_1 FONT_2 = X$LOAD_FONT(DPY, SECOND_FONT) CALL X$SET_FONT(DPY, GC, FONT_2) TEXT_ARR(2).X$A_TEXT_CHARS = %LOC(SECOND_WORD) TEXT_ARR(2).X$L_TEXT_N_CHARS = 6 TEXT_ARR(2).X$L_TEXT_DELTA = 20 TEXT_ARR(2).X$L_TEXT_FONT = FONT_2 FONT_3 = X$LOAD_FONT(DPY, THIRD_FONT) TEXT_ARR(3).X$A_TEXT_CHARS = %LOC(THIRD_WORD) TEXT_ARR(3).X$L_TEXT_N_CHARS = 7 TEXT_ARR(3).X$L_TEXT_DELTA = 20 TEXT_ARR(3).X$L_TEXT_FONT = FONT_3 . . . C C Handle events C DO WHILE (.TRUE.) CALL X$NEXT_EVENT(DPY, EVENT) IF (EVENT.EVNT_TYPE .EQ. X$C_EXPOSE) THEN CALL X$DRAW_IMAGE_STRING(DPY, WINDOW, GC, 1 150, 25, 'To draw text, click MB1') CALL X$DRAW_IMAGE_STRING(DPY, WINDOW, GC, 1 150, 50, 'To exit, click MB2') END IF IF (EVENT.EVNT_TYPE .EQ. X$C_BUTTON_PRESS .AND. 1 EVENT.EVNT_BUTTON.X$L_BTEV_BUTTON .EQ. X$C_BUTTON1) THEN CALL X$DRAW_TEXT(DPY, WINDOW, GC, 100, 200, TEXT_ARR(1), 3) END IF IF (EVENT.EVNT_TYPE .EQ. X$C_BUTTON_PRESS .AND. 1 EVENT.EVNT_BUTTON.X$L_BTEV_BUTTON .EQ. X$C_BUTTON2) THEN CALL SYS$EXIT(%VAL(1)) END IF END DO

To draw 8-bit or 2-byte text, use the DRAW STRING, DRAW STRING 16, DRAW IMAGE STRING, and DRAW IMAGE STRING 16 routines. DRAW STRING and DRAW STRING 16 display the foreground values of text only. DRAW IMAGE STRING and DRAW IMAGE STRING 16 display both foreground and background values.

Example 8-2 illustrates drawing text with the DRAW STRING routine. The example modifies the sample program in Chapter 1 to draw shadow text.

Example 8-2 Drawing Text Using the DRAW STRING Routine

. . . 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$SET_FOREGROUND(DPY, GC, 1 DEFINE_COLOR(DPY, SCREEN, VISUAL,3)) CALL X$DRAW_STRING(DPY, WINDOW_2, GC, 1 35, 75, MESSAGE(STATE)) CALL X$SET_FOREGROUND(DPY, GC, 1 DEFINE_COLOR(DPY, SCREEN, VISUAL,4)) CALL X$DRAW_STRING(DPY, WINDOW_2, GC, 1 31, 71, 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$CLEAR_WINDOW(DPY, WINDOW_2) CALL X$SET_FOREGROUND(DPY, GC, 1 DEFINE_COLOR(DPY, SCREEN, VISUAL, 3)) CALL X$DRAW_STRING(DPY, WINDOW_2, GC, 1 35, 75, MESSAGE(STATE)) CALL X$SET_FOREGROUND(DPY, GC, 1 DEFINE_COLOR(DPY, SCREEN, VISUAL, 4)) CALL X$DRAW_STRING(DPY, WINDOW_2, GC, 1 31, 71, MESSAGE(STATE)) ELSE C C Unmap and destroy windows C CALL X$UNMAP_WINDOW(DPY, WINDOW_1) CALL X$DESTROY_WINDOW(DPY, WINDOW_1) CALL X$CLOSE_DISPLAY(DPY) CALL SYS$EXIT(%VAL(1)) END IF END IF END DO END

The server refers to the following members of the GC data structure when writing text with DRAW TEXT, DRAW TEXT 16, DRAW STRING, and DRAW STRING 16:

Function	Plane mask
Foreground	Subwindow mode
Stipple	Font
Background	Tile
Tile stipple x origin	Tile stipple y origin
Clip x origin	Clip y origin
Clip mask	Fill style

To draw both foreground and background values of text, use the DRAW IMAGE STRING and DRAW IMAGE STRING 16 routines. For example, the sample program uses the DRAW IMAGE routine to write the text "Click here to exit," as follows:

INTEGER*4 STATE !flag for text CHARACTER*19 MESSAGE(2) DATA MESSAGE /'Click here to exit ', 'Click HERE to exit!'/ . . . CALL X$DRAW_IMAGE_STRING(DPY, WINDOW_2, GC, 1 75, 75, MESSAGE(STATE))

The effect is first to fill a rectangle with the background defined in the graphics context and then to paint the text with the foreground pixel. The upper left corner of the filled rectangle is at 75, (75- font ascent ) . The width of the rectangle is equal to the width of the string. The height of the rectangle is equal to font ascent + font descent .

When drawing text in response to calls to DRAW IMAGE STRING and DRAW IMAGE STRING 16, the server ignores the function and fill style the client has defined in the graphics context. The value of the function member of the GC data structure is effectively the value specified by the constant x$c_gx_copy. The value of the fill style member is effectively the value specified by the constant x$c_fill_solid.

The server refers to the following members of the GC data structure when writing text with DRAW IMAGE STRING and DRAW IMAGE STRING 16:

Subwindow mode	Plane mask
Foreground	Background
Stipple	Font
Clip x origin	Clip y origin
Clip mask

8.7 Font Usage Hints

This section includes information about the Digital font fallback strategy and hints for using font names efficiently.

8.7.1 Font Fallback Strategy

When specifying fonts, the client should use fonts that are common to both DECwindows Motif and X Window System, Version 11, Release 4 software. Using common fonts makes a client application interoperable and enables it to display on a wide variety of third-party workstations and X terminals. The following lists the common font families:

• Courier
• Helvetica
• New Century Schoolbook
• Symbol
• Times

If clients use other font families (such as ITC Avant Garde Gothic, ITC Lubalin Graph, or ITC Souvenir), the DECwindows toolkit provides the DxmFindFontFallback routine that supports the Digital font fallback strategy. For more information about this routine, see the DECwindows Extensions to Motif.

Digital recommends that clients not use certain fonts. Table 8-9 lists the font families and the reason why. All other font families are for general use.

Table 8-9 Fonts Not Recommended for General Use

Font Family	Reason
Interim DEC Math	For use only by the DECwindows Bookreader. This font will eventually be phased out.
Menu	For use by the DECwindows Toolkit.
Terminal	For use by terminal emulators.
Fixed	Available for compatibility reasons only. Should not be used by new clients.
Variable	Available for compatibility reasons only. Should not be used by new clients.
Fixed Width	Available for compatibility reasons only. Should not be used by new clients.

8.7.2 Speeding Up Font Name Searches

The DECwindows X server uses a heuristic to speed up font name searching. When the client specifies the FAMILY_NAME, WEIGHT_NAME, SLANT, SETWIDTH_NAME, CHARSET_REGISTRY, and CHARSET_ENCODING fields explicitly, the server uses a hash table to speed up font name searching. For example, the following font name is specified correctly to use the heuristic:

-*-Times-Medium-R-Normal--*-140-*-*-P-*-ISO8859-1

The previous example will be found more quickly than the following because a wildcard has been used in the SLANT field:

-*-Times-Medium-*-Normal--*-140-*-*-P-*-ISO8859-1

The client can specify other fields, such as the FOUNDRY field; however, all fourteen hyphens in a font name must be specified for the heuristic to work. The ADD_STYLE_NAME field (the field after Normal in the example) should be left empty because this field may be used in the hashing algorithm in the future.

8.7.3 Monitor Density Independence

To choose a particular sized font without regard to the density of the monitor, the client should always use a wildcard for the PIXEL_SIZE field and never use a wildcard for the POINT_SIZE field. In addition, the client should use a wildcard for the RESOLUTION_X and RESOLUTION_Y fields.

8.7.4 Character Set Considerations

The client should always explicitly specify the CHARSET_REGISTRY and CHARSET_ENCODING fields (for example, ISO8859-1), not only because they speed up font name searching, but because they ensure that the client uses the correct character set. ISO8859-1 specifies the Latin-1 character set that is normally used in text files. There are other possible character sets that could match a wildcard search, such as Latin-2 or Latin-3, but they should not be used if the client can only process and display Latin-1 text.

An event is a report of either a change in the state of a device (such as a mouse) or the execution of a routine called by a client. An event can be either unsolicited or solicited. Typically, unsolicited events are reports of keyboard or pointer activity. Solicited events are Xlib responses to calls by clients.

Xlib reports events asynchronously. When any event occurs, Xlib processes the event and sends it to clients that have specified an interest in that type of event.

This chapter describes the following concepts needed to manage events:

• Event processing---An overview of types of events
• Event type selection---A description of how clients can specify the types of events Xlib reports to them
• Event handling---A description of handling specific types of events

This chapter provides information for a subset of event types. For a complete reference of event handling routines and data structures, see the DECwindows Motif for OpenVMS Guide to Non-C Bindings and the X Window System.

9.1 Event Processing

Apart from errors, which Section 9.13 describes, Xlib events issue from operations on either windows or pixmaps. Most events result from operations associated with windows. The smallest window that contains the pointer when a window event occurs is the source window.

Xlib searches the window hierarchy upward from the source window until one of the following applies:

• Xlib finds a window that one or more clients have identified as interested in the event. This window is the event window. After Xlib locates an event window, it sends information about the event to appropriate clients.
• Xlib finds a window whose X$L_SWDA_DO_NOT_PROPAGATE attribute has been set by a client. Setting this attribute specifies that Xlib should not notify ancestors of the window owned by the client of events occurring in the window and its children. For more information about the X$L_SWDA_DO_NOT_PROPAGATE attribute, see Chapter 3.
• Xlib reaches the top of the window hierarchy without finding a window that a client has identified as interested in the event. In this case, the event is not sent.

While there are many types of window events, events associated with pixmaps occur only when a client cannot compute a destination region because the source region is out-of-bounds (see Chapter 6 for a description of source and destination regions). When a client attempts an operation on an out-of-bounds pixmap region, Xlib puts the event on the event queue and checks a list to determine if a client is interested in the event. If a client is interested, Xlib sends information to the client using an event data structure.

Xlib can report 30 types of events related to keyboards, mice, windowing, and graphics operations. A flag identifies each type to facilitate referring to the event. Table 9-1 lists event types, grouped by category, and the flags that represent them.

Table 9-1 Event Types

Event Type	Flag Name
Keyboard Events
Key press	x$c_key_press
Key release	x$c_key_release
Pointer Motion Events
Button press	x$c_button_press
Button release	x$c_button_release
Motion notify	x$c_motion_notify
Window Crossing Events
Enter notify	x$c_enter_notify
Leave notify	x$c_leave_notify
Input Focus Events
Focus in	x$c_focus_in
Focus out	x$c_focus_out
Keymap State Event
Keymap notify	x$c_keymap_notify
Exposure Events
Expose	x$c_expose
Graphics expose	x$c_graphics_expose
No expose	x$c_no_expose
Data Structure Control Events
Circulate request	x$c_circulate_request
Configure request	x$c_configure_request
Map request	x$c_map_request
Resize request	x$c_resize_request
Window State Events
Circulate notify	x$c_circulate_notify
Configure notify	x$c_configure_notify
Create notify	x$c_create_notify
Destroy notify	x$c_destroy_notify
Gravity notify	x$c_gravity_notify
Map notify	x$c_map_notify
Mapping notify	x$c_mapping_notify
Reparent notify	x$c_reparent_notify
Unmap notify	x$c_unmap_notify
Visibility notify	x$c_visibility_notify
Color Map State Events
Color map notify	x$c_colormap_notify
Client Communication Events
Client message	x$c_client_message
Property notify	x$c_property_notify
Selection clear	x$c_selection_clear
Selection notify	x$c_selection_notify
Selection request	x$c_selection_request

Every event type has a corresponding data structure that Xlib uses to pass information to clients. See the sections that describe handling specific event types for a description of the relevant event-specific data structures.

Xlib includes the any event data structure, which clients can use to receive reports of any type of event. Figure 9-1 illustrates the data structure.

Figure 9-1 Any Event Data Structure