PEXUtCreateWindow(3G)

Name

PEXUtCreateWindow − create a Window using specified attributes

Syntax

#include <pexutcmap.h>

int PEXUtCreateWindow(Display *display, int screen, PEXUtWindowSpecification *window_info, XVisualInfo *vis_info, Window *window_return, XColor *background_color_return)

typedef struct {
        unsigned longattr_mask;
        XSetWindowAttributesattrs;
        char*title;
        XSizeHintsize_hints;
        Windowparent;
        unsigned intborder_width;
        char*background_color_name;
        char*border_color_name;
} PEXUtWindowSpecification;

Parameters

display
A pointer to a display structure returned by a successful XOpenDisplay call, on which PEXlib has been initialized.

screenThe screen number of the display where the Window is to be created.

window_info
A pointer to a structure specifying attributes of the Window to be created. See the description section below for details.

vis_info
A pointer to a valid structure that describes the Visual in which the Window will be created.

window_return
A pointer to a Window identifier. The created Window identifier is returned via this parameter.

background_color_return
A pointer to an structure. Upon successful return, this structure is written with the description of the background color used in creation of the Window.

Returns

The function returns a value of if it is successful in creating the Window.

A negative return value indicates failure. The following are the meanings of the different failure values:

•A return value of means that an error was encountered during an Xlib call. One possible cause is that no Colormap identifier or mask bit was specified in window_info (see the description below).

•means that the utility ran out of memory.

Description

This procedure creates a Window in the specified Visual (described by vis_info) using the window attributes specified in window_info. The created Window ID is returned in window_return. Note well: The created Window has not been mapped when this function returns. Applications should issue their own XMapWindow call when they are ready for this to occur.

A typical usage of this utility is to create extra Windows after PEXUtCreateWindowAndColormap has been used to create the first. By specifying the same Visual and Colormap for several Windows, extraneous Visual selection and creation of resources can be avoided. Another possible use is when some other methods (perhaps other PEXUt routines) have been used to select a Visual and create a Colormap, and only Window creation is desired.

The window_info structure is used as follows:

The and structure function exactly as they do in a direct call to XCreateWindow, with the following exceptions:

The field in window_info->attrs, and the bit in window_info->attr_mask, must be specified in all cases. It is assumed that this Colormap has been created in the specified Visual. The Window will be created using this Colormap.

If and/or are not specified, then this procedure will look up pixel values in the Colormap using the and strings. Specifying or will have normal effects.

Fields related to backing storage should be used with caution, since many PEX implementations do not support backing store for PEX rendering.

The string is assigned as the name of the Window.

describes desired window size and placement in a manner that can be relayed to any window manager that is running. The procedure calls XSetNormalHints to pass this information on.

The field specifies the ID of the parent for the Window to be created, just as in XCreateWindow.

The field specifies the width of the window border in pixels, again as in XCreateWindow.

and are color names as found in the X RGB color data base. The utility procedure uses XAllocNamedColor with the specified Colormap in order to derive pixel values for the window background and border. If the strings are empty or invalid, a background of "Black" and a border of "White" are used by default.

Restrictions

Since X/PEX programs normally operate in an environment where a window manager is running (to which some of the generated requests will be redirected), it is strongly recommended that the application wait for the proper events to be assured that the Window has been mapped, before going on to make PEXlib calls. Since the application must issue its own XMapWindow request when this procedure is used, the timing of the mapping is not controlled by this utility.

Museum