HP OpenVMS Systems Documentation

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

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.

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

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

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:

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.

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.

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