GdkWindow Attributes

gdk_window_new() (shown in Figure 1) allows you to specify all of a window's attributes when you create it; many of them can be changed later as well. To specify a block of attributes, you pass in a GdkWindowAttr object; its contents will give you an idea what attributes a GdkWindow can have:

typedef struct _GdkWindowAttr GdkWindowAttr;

struct _GdkWindowAttr
{
  gchar *title;
  gint event_mask;
  gint16 x, y;
  gint16 width;
  gint16 height;
  GdkWindowClass wclass;
  GdkVisual *visual;
  GdkColormap *colormap;
  GdkWindowType window_type;
  GdkCursor *cursor;
  gchar *wmclass_name;
  gchar *wmclass_class;
  gboolean override_redirect;
};

Because some of the fields in GdkWindowAttr are optional, gdk_window_new() is used with an attributes_mask to specify which optional fields contain valid information (bit flags are available representing each optional field). GDK will only examine the optional fields given in the mask, so you can let the default values remain for fields you aren't interested in. Table 1 summarizes them briefly; fields with no attributes_mask flag are required and have no default value.

gdk_window_new() is typically used in widget implementations to create the widget's GdkWindow; you will rarely use it in any other context. gdk_window_destroy() destroys a window when you are done with it. Windows are also reference counted; be sure to read the section called GDK Resource Management for more details on this.

#include <gdk/gdk.h>

A GdkWindow's title is only really important for toplevel windows; most window managers will place it in the titlebar. Usually you should not specify it when creating a GdkWindow, however; instead, let your widget's users call gtk_window_set_title().

The window's event mask determines which events will be received on this window; the section called Events goes into more detail about events.

The X and Y coordinates for a window are specified in pixels, relative to the parent window's origin. The origin of each window is its top left ("northwest") corner. Notice that a 16-bit signed integer is used; X windows have a maximum size of 32768 pixels. Negative values are allowed, but the window will be clipped by its parent window (only the portion inside the parent window will be visible).

The width and height of a window are given in pixels, and are also 16-bit signed integers.

A window's GdkWindowClass can have one of two values:

• GDK_INPUT_OUTPUT is a normal window.

• GDK_INPUT_ONLY is a window that has a position and receives events but has no visual representation. Its children must also be input only. You can set the cursor and other attributes for an input only window, but there is no way to draw to it (it's invisible). Input-only windows are occasionally useful to capture events or change the cursor in a region that overlaps two normal windows.

A visual describes the color-handling characteristics of a display; a colormap contains the colors you can use to draw. the section called Visuals and Colormaps gives details on visuals and colormaps.

Windows can be one of several different types, specified by the GdkWindowType enumeration:

• GDK_WINDOW_ROOT is the type of the GDK wrapper for the root window, created at initialization time.

• GDK_WINDOW_TOPLEVEL is a toplevel window; the parent argument to gdk_window_new() should be NULL in this case. GDK automatically uses the root window as the window's parent.

• GDK_WINDOW_CHILD is a subwindow within a toplevel window.

• GDK_WINDOW_DIALOG is essentially the same as a toplevel window; its parent should be NULL and GDK will substitute the root window. A hint will be set to tell the window manager the window is a dialog; some window managers take this into account.

• GDK_WINDOW_TEMP is used for popup menus and the like; it's a window that will exist only briefly. It's a toplevel window, so its parent should be NULL. These windows are always override redirect and their cursor is always the same as their parent's. So they will ignore those elements of the attributes struct.

• GDK_WINDOW_PIXMAP is not a window at all; GdkPixmap and GdkWindow are almost always treated the same way, so GDK uses the same struct to represent them. They can both be considered kinds of GdkDrawable. See the section called Drawables and Pixmaps.

• GDK_WINDOW_FOREIGN identifies a wrapper around a window not created by GDK.

Only GDK_WINDOW_TOPLEVEL, GDK_WINDOW_CHILD, GDK_WINDOW_TEMP, and GDK_WINDOW_DIALOG are valid for gdk_window_new(). Library users may not create a GDK_WINDOW_ROOT. Pixmaps (GDK_WINDOW_PIXMAP) are created with gdk_pixmap_new(). Foreign windows (GDK_WINDOW_FOREIGN) are X windows created outside of GDK and wrapped using gdk_window_foreign_new() (declared in gdk/gdkx.h, since you will only need this function if you are using Xlib directly).

The cursor field specifies the mouse pointer (cursor) to use in this window; see the section called The Mouse Pointer for information about cursors.

The "class hint" is described in the section called Setting Window Class Hints in the chapter called The Main Window: GnomeApp. When writing widgets, you will not usually set the class hint. It is only relevant for toplevel windows; GTK+ provides gtk_window_set_wmclass() so application authors can set it to something sensible.

The last field in GdkWindowAttr determines whether the window is "override redirect." Normally, window managers intercept all requests to show, hide, move, or resize a toplevel window. They can then redirect or cancel these requests, to force windows to behave according to the window manager's layout policy. You can override this behavior by setting override_redirect to TRUE. Since window managers can not move windows with this flag set, they will normally not put a title bar or other decorations on them. Note that all GDK_WINDOW_TEMP windows use TRUE for this field; recall that GDK_WINDOW_TEMP is often used for popup menus, which are not controlled by the window manager.

Typically you should not change the override_redirect field; the default is almost always right, if you specify the correct GdkWindowType. However, there are some exceptions; the Gnome panel application sets this field, for example.