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

1. The client assigns window width and height the value of 600 (pixels) each.
2. The client specifies the position of the window using two display information routines, DISPLAY WIDTH and DISPLAY HEIGHT. The WINDOW_1X and WINDOW_1Y coordinates define the top left outside corner of the window borders relative to the inside of the parent border. In this case, the parent is the root window, which does not have a border.
3. The CREATE SIMPLE WINDOW routine call has the following format:

   window_id = X$CREATE_SIMPLE_WINDOW(display, parent_id, x_coord, y_coord, width, height, border_width, border_id, background_id)

   
   The client specifies a black border ten pixels wide, a white background, and a size of 600 by 600 pixels.
   The window manager overrides border width and color.
   CREATE SIMPLE WINDOW returns a unique identifier, WINDOW_1, used in subsequent calls related to the window.

To create a window whose attributes are different from the parent window, use the CREATE WINDOW routine. The CREATE WINDOW routine enables clients to specify the following window attributes when creating an input-output window:

• Default contents of an input-output window
• Border of an input-output window
• Treatment of the window when it or its relative is obscured
• Treatment of the window when it or its relative is moved
• Information the window receives about operations associated with other windows
• Color
• Cursor

Clients creating input-only windows can define the following attributes:

• Treatment of the window when it or its relative is moved
• Information the window receives about operations associated with other windows
• Cursor

Specifying other attributes for an input-only window causes the server to generate an error. Input-only windows cannot have input-output windows as children.

Use the following method to define window attributes:

• Assign values to the relevant members of a set window attributes data structure.
• Indicate the defined attribute by specifying the appropriate flag and in the value_mask argument of the CREATE WINDOW routine. If more than one attribute is to be defined, indicate the attributes by doing a bitwise OR on the appropriate flags and passing the result in the value_mask argument of the CREATE WINDOW routine.

Figure 3-5 illustrates the set window attributes data structure.

Figure 3-5 Set Window Attributes Data Structure

Table 3-8 WM Hints Data Structure Members

Member Name	Contents
X$L_HINT_FLAGS	Specifies the members of the data structure that are defined.
X$L_HINT_INPUT	Indicates whether or not the client relies on the window manager to get keyboard input.
X$L_HINT_INITIAL_STATE	Defines how the window should appear in its initial configuration. Possible initial states are as follows: Constant Name Description x$c_withdrawn_state Neither client's top-level window nor icon window is visible. x$c_normal_state Client's top-level window is visible. x$c_iconic_state Client's top-level window starts as an icon.
X$L_HINT_ICON_PIXMAP	Identifies the pixmap used to create the window icon.
X$L_HINT_ICON_WINDOW	Specifies the window to be used as an icon.
X$L_HINT_ICON_X	Specifies the initial x-coordinate of the icon position.
X$L_HINT_ICON_Y	Specifies the initial y-coordinate of the icon position.
X$L_HINT_ICON_MASK	Specifies the pixels of the icon pixmap used to create the icon.
X$L_HINT_WINDOW_GROUP	Specifies that a window belongs to a group of other windows.

3.7.2 Providing Size Hints

Xlib provides routines that the client can use to set or read the WM_NORMAL_HINTS property for a given window. These routines use the size hints data structure to communicate to the window manager about the size and position of windows in their normal and iconic startup states.

Use the SET WM NORMAL HINTS routine to set a window's X$C_XA_WM_NORMAL_HINTS property. Use the GET WM NORMAL HINTS routine to read a window's X$C_XA_WM_NORMAL_HINTS property.

Table 3-9 lists the flags used in the size hints data structure.

Table 3-9 Size Hints Data Structure Flags

Flag Name	Size Hints Member
x$m_us_position	User-specified position of the window
x$m_us_size	User-specified size of the window
x$m_p_position	Client-specified position
x$m_p_size	Client-specified size
x$m_p_min_size	Client-specified minimum size of the window
x$m_p_max_size	Client-specified maximum size of the window
x$m_p_resize_inc	Client-specified increments for resizing the window
x$m_p_aspect	Client-specified minimum and maximum aspect ratios
x$m_p_base_size	Client-specified desired size of the window
x$m_p_win_gravity	Client-specified window gravity
x$m_p_all_hints	The bitwise OR of x$m_p_position, x$m_p_size, x$m_p_min_size, x$m_p_max_size, x$m_p_resize_inc, and x$m_p_aspect

Figure 3-9 illustrates the size hints data structure. Table 3-10 describes the members of the data structure.

Figure 3-9 Size Hints Data Structure

Table 3-11 Text Property Data Structure Members

Member Name	Contents
X$B_TXTP_VALUE	Character string
X$L_TXTP_ENCODING	Type of encoding
X$L_TXTP_FORMAT	Number of bits: 8, 16, or 32
X$L_TXTP_NITEMS	Number of items in value

Xlib provides an additional routine to set a window name. The STORE NAME routine assigns a name to a window and displays it in a prominent place such as the title bar. Example 1-1 in Chapter 1 uses the STORE NAME routine to define the name of its parent window, as follows:

CALL X$STORE_NAME(DPY, WINDOW_1, WINDOW_NAME);

To define and get the class of a specified window, use the SET CLASS HINT and GET CLASS HINT routines. The routines refer to the class hint data structure. Figure 3-11 illustrates the class hint data structure. Table 3-12 describes the members of the data structure.

Figure 3-11 Class Hint Data Structure

Table 3-13 Window Changes Data Structure Members

Member Name	Contents
X$L_WCHG_X	Defines the x-coordinate of the new location of the window relative to the origin of its parent. The x- and y-coordinates specify the upper left outside corner of the window.
X$L_WCHG_Y	Defines the y-coordinate of the new location of the window relative to the origin of its parent. The x- and y-coordinates specify the upper left outside corner of the window.
X$L_WCHG_WIDTH	Defines the new width of the window, excluding the border.
X$L_WCHG_HEIGHT	Defines the new height of the window, excluding the border.
X$L_WCHG_BORDER_WIDTH	Specifies the new window border in pixels.
X$L_WCHG_SIBLING	Specifies the sibling window for stacking order.
X$L_WCHG_STACK_MODE	Defines how the window is restacked. Table 3-14 lists constants and definitions for restacking windows.

The client can change the hierarchical position of a window in relation to all windows in the stack or to a specified sibling. If the client changes the size, position, and stacking order of the window by calling CONFIGURE WINDOW, the server restacks the window based on its final, not initial, size and position. Table 3-14 lists constants and definitions for restacking windows.

Table 3-14 Stacking Values

Constants	Relative to All	Relative to Sibling
x$c_above	Top of stack.	Just above sibling.
x$c_below	Bottom of stack.	Just below sibling.
x$c_top_if	If any sibling obscures a window, the server places the obscured window on top of the stack.	If the specified sibling obscures a window, the server places the obscured window at the top of the stack.
x$c_bottom_if	If a window obscures any sibling, the server places the obscuring window at the bottom of the stack.	If the window obscures the specified sibling, the server places the obscuring window at the bottom of the stack.
x$c_opposite	If any sibling obscures a window, the server places the obscured window on top of the stack. If a window obscures any window, the server places the obscuring window at the bottom of the stack.	If the specified sibling obscures a window, the server places the obscuring window on top of the stack. If a window obscures the specified sibling, the server places the obscuring window on the bottom of the stack.

Xlib assigns a symbol to the flag associated with each member of the data structure (Table 3-15).

Table 3-15 Window Changes Data Structure Flags

Flag Name	Window Changes Member
x$m_cw_x	X$L_WCHG_X
x$m_cw_y	X$L_WCHG_Y
x$m_cw_width	X$L_WCHG_WIDTH
x$m_cw_height	X$L_WCHG_HEIGHT
x$m_cw_border_width	X$L_WCHG_BORDER_WIDTH
x$m_cw_sibling	X$L_WCHG_SIBLING
x$m_cw_stack_mode	X$L_WCHG_STACK_MODE

Example 3-5 illustrates using CONFIGURE WINDOW to change the position, size, and stacking order of a window when the user presses a button.

Example 3-5 Reconfiguring a Window

C C This program changes the position, size, and stacking C order of SUBWINDOW_1 RECORD /X$WINDOW_CHANGES/ XWC . . . (1) WCHG_MASK = X$M_CW_X .OR. X$M_CW_Y .OR. X$M_CW_WIDTH .OR. 1 X$M_CW_HEIGHT .OR. X$M_CW_SIBLING .OR. X$M_CW_STACK_MODE (2) XWC.X$L_WCHG_X = 200 XWC.X$L_WCHG_Y = 350 XWC.X$L_WCHG_WIDTH = 200 XWC.X$L_WCHG_HEIGHT = 50 XWC.X$L_WCHG_SIBLING = SUBWINDOW_2 XWC.X$L_WCHG_STACK_MODE = X$C_ABOVE (3) CALL X$CONFIGURE_WINDOW(DPY, SUBWINDOW_1, WCHG_MASK, XWC)

1. Specify the members of the window changes data structure that have assigned values. Create a mask by performing a bitwise OR operation on relevant flags that indicate which members of WINDOW CHANGES the client will define.
2. Assign values to relevant members of the window changes data structure. Because the client identifies a sibling (SUBWINDOW_1), it must also choose a mode for stacking operations.
3. The call to reconfigure SUBWINDOW_1. The CONFIGURE WINDOW routine call has the following format:

   X$CONFIGURE_WINDOW(display, window_id, change_mask, values)

Figure 3-13 illustrates how the windows look after being reconfigured.

Figure 3-13 Reconfigured Window

Table 3-16 lists routines to change individual window characteristics.

Table 3-16 Window Configuration Routines

Routine	Description
MOVE WINDOW	Moves a window without changing its size.
RESIZE WINDOW	Changes the size of a window without moving it. The upper left window coordinate does not change after resizing.
MOVE RESIZE WINDOW	Moves and changes the size of a window.
SET WINDOW BORDER WIDTH	Changes the border width of a window.

3.9.2 Effects of Reconfiguring Windows

It is important to know how reconfiguring windows affects graphics and text drawn in them by the client. (See Chapter 6 for a description of working with graphics and Chapter 8 for a description of writing text.) When a client resizes a window, window contents are either moved or lost, depending on the bit gravity of the window. Bit gravity indicates that a designated region of the window should be relocated when the window is resized. Resizing also causes the server to resize children of the changed window.

To control how the server moves children when a parent is resized, set the window gravity attribute. Table 3-17 lists choices for retaining window contents and controlling how the server relocates children.

Table 3-17 Gravity Definitions

Constant Name	Movement of Window Contents and Subwindows
x$c_forget_gravity	The server always discards window contents and tiles the window with its selected background. If the client has not specified a background, existing screen contents remain the same.
x$c_north_west_gravity	Not moved.
x$c_north_gravity	Moved to the right half of the window width.
x$c_north_east_gravity	Moved to the right, the distance of the window width.
x$c_west_gravity	Moved down half the window height.
x$c_center_gravity	Moved to the right half of the window width and down half of the window height.
x$c_east_gravity	Moved to the right, the distance of the window width and down half the window height.
x$c_south_west_gravity	Moved down the distance of the window height.
x$c_south_gravity	Moved to the right half of the window width and down the distance of the window height.
x$c_south_east_gravity	Moved to the right, the distance of the window width and down the distance of the window height.
x$c_static_gravity	Contents or origin is not moved relative to the origin of the root window. Static gravity only takes effect with a change in window width or height.
x$c_unmap_gravity	Window should not be moved; the child should be unmapped when the parent is resized.

Figure 3-14 illustrates how the server moves the contents of a reconfigured window when the bit gravity is set to the constant x$c_east_gravity.

Figure 3-15 illustrates how the server moves a child window if its parent is resized and its window gravity is set to the constant x$c_north_west_gravity.

Figure 3-14 East Bit Gravity

Figure 3-15 Northwest Window Gravity

Xlib provides routines that alter the window stacking order in the following ways:

• A specified window moves to either the top or the bottom of the stack.
• The lowest mapped child obscured by a sibling moves to the top of the stack.
• The highest mapped child that obscures a sibling moves to the bottom of the stack.

Use the RAISE WINDOW and LOWER WINDOW routines to move a specified window to either the top or the bottom of the stack, respectively.

To raise the lowest mapped child of an obscured window to the top of the stack, call CIRCULATE SUBWINDOWS UP. To lower the highest mapped child that obscures another child, call CIRCULATE SUBWINDOWS DOWN. The CIRCULATE SUBWINDOWS routine enables the client to perform these operations by specifying either the constant x$c_raise_lowest or the constant x$c_lower_highest.

To change the order of the window stack, use RESTACK WINDOW, which changes the window stack to a specified order. Reordered windows must have a common parent. If the first window the client specifies has other unspecified siblings, its order relative to those siblings remains unchanged.