Windows
<!-- ##### SECTION Short_Description ##### -->
-
-onscreen display areas in the target window system
+Onscreen display areas in the target window system
<!-- ##### SECTION Long_Description ##### -->
<para>
<!-- ##### STRUCT GdkWindow ##### -->
<para>
-
+An opaque structure representing an onscreen drawable.
+Pointers to structures of type #GdkPixmap, #GdkBitmap,
+and #GdkWindow, can often be used interchangeably.
+The type #GdkDrawable refers generically to any of
+these types.
</para>
-@user_data: used to store the #GtkWidget associated with this window
<!-- ##### ENUM GdkWindowType ##### -->
<para>
<para>
Here's an example of how the terminal example would be implemented, assuming
a terminal area widget called "terminal" and a toplevel window "toplevel":
-<programlisting>
+<informalexample><programlisting>
GdkGeometry hints;
hints.base_width = terminal->char_width;
GDK_HINT_RESIZE_INC |
GDK_HINT_MIN_SIZE |
GDK_HINT_BASE_SIZE);
-</programlisting>
+</programlisting></informalexample>
</para>
<para>
<!-- ##### ENUM GdkGravity ##### -->
<para>
-
-</para>
-
-@GDK_GRAVITY_NORTH_WEST:
-@GDK_GRAVITY_NORTH:
-@GDK_GRAVITY_NORTH_EAST:
-@GDK_GRAVITY_WEST:
-@GDK_GRAVITY_CENTER:
-@GDK_GRAVITY_EAST:
-@GDK_GRAVITY_SOUTH_WEST:
-@GDK_GRAVITY_SOUTH:
-@GDK_GRAVITY_SOUTH_EAST:
-@GDK_GRAVITY_STATIC:
+Defines the reference point of a window and the meaning of coordinates
+passed to gtk_window_move(). See gtk_window_move() and the "implementation
+notes" section of the
+<ulink url="http://www.freedesktop.org/standards/wm-spec.html">extended
+window manager hints</ulink> specification for more details.
+</para>
+
+@GDK_GRAVITY_NORTH_WEST: the reference point is at the top left corner.
+@GDK_GRAVITY_NORTH: the reference point is in the middle of the top edge.
+@GDK_GRAVITY_NORTH_EAST: the reference point is at the top right corner.
+@GDK_GRAVITY_WEST: the reference point is at the middle of the left edge.
+@GDK_GRAVITY_CENTER: the reference point is at the center of the window.
+@GDK_GRAVITY_EAST: the reference point is at the middle of the right edge.
+@GDK_GRAVITY_SOUTH_WEST: the reference point is at the lower left corner.
+@GDK_GRAVITY_SOUTH: the reference point is at the middle of the lower edge.
+@GDK_GRAVITY_SOUTH_EAST: the reference point is at the lower right corner.
+@GDK_GRAVITY_STATIC: the reference point is at the top left corner of the
+ window itself, ignoring window manager decorations.
<!-- ##### ENUM GdkWindowEdge ##### -->
<para>
-
+Determines a window edge or corner.
</para>
-@GDK_WINDOW_EDGE_NORTH_WEST:
-@GDK_WINDOW_EDGE_NORTH:
-@GDK_WINDOW_EDGE_NORTH_EAST:
-@GDK_WINDOW_EDGE_WEST:
-@GDK_WINDOW_EDGE_EAST:
-@GDK_WINDOW_EDGE_SOUTH_WEST:
-@GDK_WINDOW_EDGE_SOUTH:
-@GDK_WINDOW_EDGE_SOUTH_EAST:
+@GDK_WINDOW_EDGE_NORTH_WEST: the top left corner.
+@GDK_WINDOW_EDGE_NORTH: the top edge.
+@GDK_WINDOW_EDGE_NORTH_EAST: the top right corner.
+@GDK_WINDOW_EDGE_WEST: the left edge.
+@GDK_WINDOW_EDGE_EAST: the right edge.
+@GDK_WINDOW_EDGE_SOUTH_WEST: the lower left corner.
+@GDK_WINDOW_EDGE_SOUTH: the lower edge.
+@GDK_WINDOW_EDGE_SOUTH_EAST: the lower right corner.
<!-- ##### ENUM GdkWindowTypeHint ##### -->
<para>
-
+These are hints for the window manager that indicate what type of function
+the window has. The window manager can use this when determining decoration
+and behaviour of the window. The hint must be set before mapping the window.
</para>
-@GDK_WINDOW_TYPE_HINT_NORMAL:
-@GDK_WINDOW_TYPE_HINT_DIALOG:
-@GDK_WINDOW_TYPE_HINT_MENU:
-@GDK_WINDOW_TYPE_HINT_TOOLBAR:
+@GDK_WINDOW_TYPE_HINT_NORMAL: Normal toplevel window.
+@GDK_WINDOW_TYPE_HINT_DIALOG: Dialog window.
+@GDK_WINDOW_TYPE_HINT_MENU: Window used to implement a menu.
+@GDK_WINDOW_TYPE_HINT_TOOLBAR: Window used to implement toolbars.
+@GDK_WINDOW_TYPE_HINT_SPLASHSCREEN:
+@GDK_WINDOW_TYPE_HINT_UTILITY:
+@GDK_WINDOW_TYPE_HINT_DOCK:
+@GDK_WINDOW_TYPE_HINT_DESKTOP:
<!-- ##### STRUCT GdkWindowAttr ##### -->
<para>
@window:
+<!-- ##### FUNCTION gdk_window_fullscreen ##### -->
+<para>
+
+</para>
+
+@window:
+
+
+<!-- ##### FUNCTION gdk_window_unfullscreen ##### -->
+<para>
+
+</para>
+
+@window:
+
+
+<!-- ##### FUNCTION gdk_window_set_keep_above ##### -->
+<para>
+
+</para>
+
+@window:
+@setting:
+
+
+<!-- ##### FUNCTION gdk_window_set_keep_below ##### -->
+<para>
+
+</para>
+
+@window:
+@setting:
+
+
<!-- ##### FUNCTION gdk_window_move ##### -->
<para>
<!-- ##### FUNCTION gdk_window_register_dnd ##### -->
<para>
-
+Registers a window as a potential drop destination.
</para>
-@window:
+@window: a #GdkWindow.
<!-- ##### FUNCTION gdk_window_begin_resize_drag ##### -->
@invalidate_children:
+<!-- ##### FUNCTION gdk_window_invalidate_maybe_recurse ##### -->
+<para>
+
+</para>
+
+@window:
+@region:
+@child_func:
+@user_data:
+
+
<!-- ##### FUNCTION gdk_window_get_update_area ##### -->
<para>
<!-- ##### USER_FUNCTION GdkFilterFunc ##### -->
<para>
Specifies the type of function used to filter native events before they are
-converted to GDK events. A filter may translate the native event to a GDK
-event or handle it without translation.
+converted to GDK events.
+</para>
+
+<para>
+When a filter is called, @event is unpopulated, except for
+<literal>event->window</literal>. The filter may translate the native
+event to a GDK event and store the result in @event, or handle it without
+translation. If the filter translates the event and processing should
+continue, it should return <literal>GDK_FILTER_TRANSLATE</literal>.
</para>
@xevent: the native event to filter.
</para>
@GDK_FILTER_CONTINUE: event not handled, continue processing.
-@GDK_FILTER_TRANSLATE: translated event stored.
+@GDK_FILTER_TRANSLATE: native event translated into a GDK event and stored
+ in the <literal>event</literal> structure that was passed in.
@GDK_FILTER_REMOVE: event handled, terminate processing.
<!-- ##### TYPEDEF GdkXEvent ##### -->
@mask:
@x:
@y:
-<!-- # Unused Parameters # -->
-@shape_mask:
-@offset_x:
-@offset_y:
<!-- ##### FUNCTION gdk_window_shape_combine_region ##### -->
<!-- ##### MACRO GDK_PARENT_RELATIVE ##### -->
<para>
-
+A special value for <literal>GdkPixmap*</literal> variables, indicating
+that the background pixmap for a window should be inherited from the parent
+window.
</para>
@window:
@geometry:
@geom_mask:
-<!-- # Unused Parameters # -->
-@flags:
<!-- ##### FUNCTION gdk_window_set_icon_list ##### -->
@window:
@pixbufs:
-<!-- # Unused Parameters # -->
-@Returns:
<!-- ##### FUNCTION gdk_window_set_modal_hint ##### -->
@hint:
+<!-- ##### FUNCTION gdk_window_set_skip_taskbar_hint ##### -->
+<para>
+
+</para>
+
+@window:
+@skips_taskbar:
+
+
+<!-- ##### FUNCTION gdk_window_set_skip_pager_hint ##### -->
+<para>
+
+</para>
+
+@window:
+@skips_pager:
+
+
<!-- ##### FUNCTION gdk_window_get_position ##### -->
<para>
<!-- ##### ENUM GdkModifierType ##### -->
<para>
-
-</para>
-
-@GDK_SHIFT_MASK:
-@GDK_LOCK_MASK:
-@GDK_CONTROL_MASK:
-@GDK_MOD1_MASK:
-@GDK_MOD2_MASK:
-@GDK_MOD3_MASK:
-@GDK_MOD4_MASK:
-@GDK_MOD5_MASK:
-@GDK_BUTTON1_MASK:
-@GDK_BUTTON2_MASK:
-@GDK_BUTTON3_MASK:
-@GDK_BUTTON4_MASK:
-@GDK_BUTTON5_MASK:
-@GDK_RELEASE_MASK:
+A set of bit-flags to indicate the state of modifier keys and mouse buttons
+in various event types. Typical modifier keys are Shift, Control, Meta, Super,
+Hyper, Alt, Compose, Apple, CapsLock or ShiftLock.
+</para>
+<para>
+Like the X Window System, GDK supports 8 modifier keys and 5 mouse buttons.
+</para>
+
+@GDK_SHIFT_MASK: the Shift key.
+@GDK_LOCK_MASK: a Lock key (depending on the modifier mapping of the
+ X server this may either be CapsLock or ShiftLock).
+@GDK_CONTROL_MASK: the Control key.
+@GDK_MOD1_MASK: the fourth modifier key (it depends on the modifier
+ mapping of the X server which key is interpreted as this modifier, but
+ normally it is the Alt key).
+@GDK_MOD2_MASK: the fifth modifier key (it depends on the modifier
+ mapping of the X server which key is interpreted as this modifier).
+@GDK_MOD3_MASK: the sixth modifier key (it depends on the modifier
+ mapping of the X server which key is interpreted as this modifier).
+@GDK_MOD4_MASK: the seventh modifier key (it depends on the modifier
+ mapping of the X server which key is interpreted as this modifier).
+@GDK_MOD5_MASK: the eighth modifier key (it depends on the modifier
+ mapping of the X server which key is interpreted as this modifier).
+@GDK_BUTTON1_MASK: the first mouse button.
+@GDK_BUTTON2_MASK: the second mouse button.
+@GDK_BUTTON3_MASK: the third mouse button.
+@GDK_BUTTON4_MASK: the fourth mouse button.
+@GDK_BUTTON5_MASK: the fifth mouse button.
+@GDK_RELEASE_MASK: not used in GDK itself. GTK+ uses it to differentiate
+ between (keyval, modifiers) pairs from key press and release events.
@GDK_MODIFIER_MASK:
<!-- ##### FUNCTION gdk_window_get_parent ##### -->
@window:
@parent:
-<!-- # Unused Parameters # -->
-@leader:
<!-- ##### FUNCTION gdk_window_set_role ##### -->
<!-- ##### ENUM GdkWMDecoration ##### -->
<para>
-
+These are hints originally defined by the Motif toolkit.
+The window manager can use them when determining how to decorate
+the window. The hint must be set before mapping the window.
</para>
-@GDK_DECOR_ALL:
-@GDK_DECOR_BORDER:
-@GDK_DECOR_RESIZEH:
-@GDK_DECOR_TITLE:
-@GDK_DECOR_MENU:
-@GDK_DECOR_MINIMIZE:
-@GDK_DECOR_MAXIMIZE:
+@GDK_DECOR_ALL: all decorations should be applied.
+@GDK_DECOR_BORDER: a frame should be drawn around the window.
+@GDK_DECOR_RESIZEH: the frame should have resize handles.
+@GDK_DECOR_TITLE: a titlebar should be placed above the window.
+@GDK_DECOR_MENU: a button for opening a menu should be included.
+@GDK_DECOR_MINIMIZE: a minimize button should be included.
+@GDK_DECOR_MAXIMIZE: a maximize button should be included.
<!-- ##### FUNCTION gdk_window_set_functions ##### -->
<para>
<!-- ##### ENUM GdkWMFunction ##### -->
<para>
-
+These are hints originally defined by the Motif toolkit.
+The window manager can use them when determining the functions
+to offer for the window.
+The hint must be set before mapping the window.
</para>
-@GDK_FUNC_ALL:
-@GDK_FUNC_RESIZE:
-@GDK_FUNC_MOVE:
-@GDK_FUNC_MINIMIZE:
-@GDK_FUNC_MAXIMIZE:
-@GDK_FUNC_CLOSE:
+@GDK_FUNC_ALL: all functions should be offered.
+@GDK_FUNC_RESIZE: the window should be resizable.
+@GDK_FUNC_MOVE: the window should be movable.
+@GDK_FUNC_MINIMIZE: the window should be minimizable.
+@GDK_FUNC_MAXIMIZE: the window should be maximizable.
+@GDK_FUNC_CLOSE: the window should be closable.
<!-- ##### FUNCTION gdk_window_get_toplevels ##### -->
<para>
<!-- ##### STRUCT GdkPointerHooks ##### -->
<para>
-
+A table of pointers to functions for getting quantities related to
+the current pointer position. GDK has one global table of this type,
+which can be set using gdk_set_pointer_hooks().
+</para>
+<para>
+This is only useful for such low-level tools as an event recorder.
+Applications should never have any reason to use this facility
</para>
-@get_pointer:
-@window_at_pointer:
+@get_pointer: Obtains the current pointer position and modifier state.
+ The position is given in coordinates relative to the window containing
+ the pointer, which is returned in @window.
+@window_at_pointer: Obtains the window underneath the mouse pointer,
+ returning the location of that window in @win_x, @win_y. Returns %NULL
+ if the window under the mouse pointer is not known to GDK (for example,
+ belongs to another application).
<!-- ##### FUNCTION gdk_set_pointer_hooks ##### -->
<para>