Xfce Foundation Classes
Main Page  | Index |  Namespace List  |  Alphabetical List  |  Class List  |  File List


Xfc::Gdk::Window Class Reference

A GdkWindow C++ wrapper class. More...

#include <xfc/gdk/window.hh>

Inheritance diagram for Xfc::Gdk::Window:

Xfc::Gdk::Drawable Xfc::G::Object Xfc::G::TypeInstance Xfc::Trackable List of all members.

Public Member Functions

Constructors
Accessors
Methods
Input methods

Static Public Member Functions

Constructors
Accessors

Protected Member Functions

Constructors

Detailed Description

A GdkWindow C++ wrapper class.

A Gdk::Window is a rectangular region on the screen. It's a low-level object, used to implement high-level objects such as Gtk::Widget and Gtk::Window. A Gtk::Window is a toplevel window, the thing a user might think of as a "window" with a titlebar and so on; a Gtk::Window may contain many Gdk::Window. For example, each Gtk::Button has a Gdk::Window associated with it.

Constructor & Destructor Documentation

Xfc::Gdk::Window::Window (  GdkWindow *  window,
bool  owns_reference = true
)  [explicit, protected]
 

Construct a new Gdk::Window from an existing GdkWindow.

Parameters:
window A pointer to a GdkWindow.
owns_reference Set false if the initial reference count is floating, set true if it's not.
The window can be a newly created GdkWindow or an existing GdkWindow. (see G::Object::Object).

Xfc::Gdk::Window::Window (  const WindowAttr &  attributes  ) 
 

Construct a new window with the root window of the default display as the parent.

Parameters:
attributes The attributes of the new window.
A Gdk::Window must be explicitly destroyed by calling dispose().

Xfc::Gdk::Window::Window (  const Window &  parent,
const WindowAttr &  attributes
) 
 

Construct a new window with parent as the parent.

Parameters:
parent A Gdk::Window.
attributes The attributes of the new window.
This is the constructor to use to create a new window on a display other than the default display. A Gdk::Window must be explicitly destroyed by calling dispose().

Member Function Documentation

void Xfc::Gdk::Window::add_filter (  Window *  window,
GdkFilterFunc  function,
void *  data
)  [static]
 

Adds an event filter for window, allowing you to intercept events before they reach GDK.

Parameters:
window The Gdk::Window to get the events for, or null for all windows.
function The filter callback to call on each event.
data Data to pass to filter callback.
This is a low-level operation and makes it easy to break GDK and/or GTK+, so you have to know what you're doing.

Window* Xfc::Gdk::Window::at_pointer (  Point &  point,
const Display *  display = 0
)  [static]
 

Obtains the window underneath the mouse pointer on display, returning the location of that window in point.

Parameters:
point The return location for the x, y coordinates of the origin of the window under the pointer.
display The display to use, or null for the default display.
Returns:
A pointer to the Gdk::Window under the mouse pointer.
Returns null if the window under the mouse pointer is not known to GDK (if the window belongs to another application and a Gdk::Window hasn't been created for it with create()).

Window* Xfc::Gdk::Window::at_pointer (  int *  win_x,
int *  win_y,
const Display *  display = 0
)  [static]
 

Obtains the window underneath the mouse pointer on display, returning the location of that window in win_x, win_y.

Parameters:
win_x The return location for the X coordinate of the origin of the window under the pointer.
win_y The return location for the Y coordinate of the origin of the window under the pointer
display The display to use, or null for the default display.
Returns:
A pointer to the Gdk::Window under the mouse pointer.
Returns null if the window under the mouse pointer is not known to GDK (if the window belongs to another application and a Gdk::Window hasn't been created for it with create()).

void Xfc::Gdk::Window::begin_move_drag (  int  button,
int  root_x,
int  root_y,
unsigned int  timestamp
) 
 

Begins a window move operation (for a toplevel window).

Parameters:
button The button being used to drag.
root_x The root window X coordinate of the mouse click that began the drag.
root_y The root window Y coordinate of the mouse click that began the drag.
timestamp The timestamp of the mouse click that began the drag.
You might use this method to implement a "window move grip," for example. The method works best with window managers that support the Extended Window Manager Hints spec (see http://www.freedesktop.org), but has a fallback implementation for other window managers.

void Xfc::Gdk::Window::begin_paint (  const Region &  region  ) 
 

Indicates that you are beginning the process of redrawing region.

Parameters:
region The region you intend to draw to.
A backing store (offscreen buffer) large enough to contain region will be created. The backing store will be initialized with the background color or background pixmap for the window. Then, all drawing operations performed on window will be diverted to the backing store. When you call end_paint(), the backing store will be copied to the window, making it visible onscreen. Only the part of the window contained in the region will be modified; that is, drawing operations are clipped to the region. The net result of all this is to remove flicker, because the user sees the finished product appear all at once when you call end_paint(). If you draw to the window directly without calling begin_paint(), the user may see flicker as individual drawing operations are performed in sequence. The clipping and background-initializing features of begin_paint() are conveniences for the programmer, so you can avoid doing that work yourself.

The GTK+ widget system automatically places calls to begin_paint() and end_paint() around emissions of the expose_event signal. That is, if you're writing an expose event handler, you can assume that the exposed area in Gdk::EventExpose has already been cleared to the window background, is already set as the clip region, and already has a backing store. Therefore in most cases, application code need not call begin_paint(). You can disable the automatic calls around expose events on a widget-by-widget basis by calling Gtk::Widget::set_double_buffered().

If you call this method multiple times before calling the matching end_paint(), the backing stores are pushed onto a stack. end_paint() copies the topmost backing store onscreen, subtracts the topmost region from all other regions in the stack, and pops the stack. All drawing operations affect only the topmost backing store in the stack. One matching call to end_paint() is required for each call to begin_paint().

void Xfc::Gdk::Window::begin_paint (  const Rectangle &  rectangle  ) 
 

Indicates that you are beginning the process of redrawing a rectangular region.

Parameters:
rectangle The rectangualr region you intend to draw to.
This method is a convenience wrapper around begin_paint(const Region&)) which creates a rectangular region for you.

void Xfc::Gdk::Window::begin_resize_drag (  WindowEdge  edge,
int  button,
int  root_x,
int  root_y,
unsigned int  timestamp
) 
 

Begins a window resize operation (for a toplevel window).

Parameters:
edge The edge or corner from which the drag is started.
button The button being used to drag.
root_x The root window X coordinate of the mouse click that began the drag.
root_y The root window Y coordinate of the mouse click that began the drag.
timestamp Timestamp of the mouse click that began the drag (use Gdk::Event::get_time()).
You might use this method to implement a "window resize grip," for example; in fact Gtk::Statusbar uses it. The method works best with window managers that support the Extended Window Manager Hints spec (see http://www.freedesktop.org), but has a fallback implementation for other window managers.

void Xfc::Gdk::Window::clear_area (  const Rectangle &  rectangle,
bool  generate_expose = false
) 
 

Clears an area of the window to the background color or background pixmap.

Parameters:
rectangle The rectangle to clear.
generate_expose If true generates an expose event for the cleared area.

void Xfc::Gdk::Window::clear_area (  int  x,
int  y,
int  width,
int  height,
bool  generate_expose = false
) 
 

Clears an area of the window to the background color or background pixmap.

Parameters:
x The X coordinate of the origin of rectangle to clear.
y The Y coordinate of the origin of rectangle to clear.
width The width of the rectangle to clear.
height The height of the rectangle to clear.
generate_expose If true generates an expose event for the cleared area.

void Xfc::Gdk::Window::configure_finished (   ) 
 

Signal to the window system that the application has finished handling "configure" events it has received.

Window Managers can use this to better synchronize the frame repaint with the application. GTK+ applications will automatically call this function when appropriate.

Pointer<Window> Xfc::Gdk::Window::create (  GdkNativeWindow  anid,
const Display *  display = 0
)  [static]
 

Wraps a native window in a Gdk::Window.

Parameters:
anid A native window handle.
display The Display where the window handle comes from, or null for the default display.
Returns:
A smart pointer to the newly-created Gdk::Window wrapper for the native window, or null if the window has been destroyed.
In the X backend, a native window handle is an Xlib XID. This method fail if the pixmap has been destroyed.

void Xfc::Gdk::Window::deiconify (   ) 
 

Attempts to deiconify (unminimize) the window.

On X11 the window manager may choose to ignore the request to deiconify. Using Gtk::Window::deiconify() instead of the Gdk::Window variant is preferred. Or better yet, you probably want to use Gtk::Window::present(), which raises the window, focuses it, unminimizes it, and puts it on the current desktop.

virtual void Xfc::Gdk::Window::dispose (   )  [virtual]
 

Destroys the window system resources associated with the window and decrements window's reference count.

The window system resources for all children of window are also destroyed, but the children's reference counts are not decremented.

Note: A Gdk::Window will not be destroyed automatically when its reference count reaches zero. You must call this method yourself before that happens. This method is declared virtual for XFC's use only.

Reimplemented from Xfc::G::Object.

void Xfc::Gdk::Window::enable_synchronized_configure (   ) 
 

Indicates that the application will cooperate with the window system in synchronizing the window repaint with the window manager during resizing operations.

After an application calls this function, it must call configure_finished() every time it has finished all processing associated with a set of "configure" events. Toplevel GTK+ windows automatically use this protocol. On X, calling this function makes window participate in the _NET_WM_SYNC_REQUEST window manager protocol.

void Xfc::Gdk::Window::end_paint (   ) 
 

Indicates that the backing store created by the most recent call to begin_paint() should be copied onscreen and deleted, leaving the next-most-recent backing store or no backing store at all as the active paint region (see begin_paint(const Region&) for full details).

It is an error to call this method without a matching begin_paint() first.

void Xfc::Gdk::Window::focus (  unsigned int  timestamp  ) 
 

Sets keyboard focus to the window.

Parameters:
timestamp A timestamp of the event triggering the window focus.
If window is not onscreen this method will not work. In most cases, Gtk::Window::present() should be used on a Gtk::Window, rather than calling this method.

void Xfc::Gdk::Window::freeze_updates (   ) 
 

Temporarily freezes a window such that it won't receive expose events.

The window will begin receiving expose events again when thaw_updates() is called. If freeze_updates() has been called more than once, thaw_updates() must be called an equal number of times to begin processing exposes.

void Xfc::Gdk::Window::fullscreen (   ) 
 

Moves the window into fullscreen mode.

This means the window covers the entire screen and is above any panels or task bars. If the window was already fullscreen, then this function does nothing. On X11, asks the window manager to put window in a fullscreen state, if the window manager supports this operation. Not all window managers support this, and some deliberately ignore it or don't have a concept of "fullscreen"; so you can't rely on the fullscreenification actually happening. But it will happen with most standard window managers, and GDK makes a best effort to get it to happen.

bool Xfc::Gdk::Window::get_children (  std::vector< Window * > &  child_list  )  const
 

Gets the list of children of the window known to GDK.

Parameters:
child_list A reference to a vector of Window* to hold the child windows.
Returns:
true if the vector is not empty.
This method only returns children created via GDK, so for example it's useless when used with the root window; it only returns windows an application created itself.

bool Xfc::Gdk::Window::get_decorations (  WMDecorationField *  decorations  )  const
 

Gets the decorations set on the window with set_decorations().

Returns:
The group leader window for the window.
Parameters:
decorations The return location for the window's Gdk::WMDecoration bitfield.
Returns:
true if the window has decorations set, false otherwise.

EventMaskField Xfc::Gdk::Window::get_events (   )  const
 

Gets the event mask for window (see set_events()).

Returns:
The event mask for window.

void Xfc::Gdk::Window::get_frame_extents (  Rectangle &  rectangle  )  const
 

Obtains the bounding box of the window, including window manager titlebar/borders if any.

Parameters:
rectangle The rectangle to fill with bounding box of the window frame.
The frame position is given in root window coordinates. To get the position of the window itself (rather than the frame) in root window coordinates, use get_origin().

Rectangle Xfc::Gdk::Window::get_frame_extents (   )  const
 

Obtains the bounding box of the window, including window manager titlebar/borders if any.

Returns:
A Rectangle filled with bounding box of the window frame.
The frame position is given in root window coordinates. To get the position of the window itself (rather than the frame) in root window coordinates, use get_origin().

void Xfc::Gdk::Window::get_geometry (  Rectangle &  rectangle,
int *  depth
)  const
 

Gets the current geometry of the window.

Parameters:
rectangle The return location for the x, y coordinates, width and height of the window (relative to its parent).
depth The return location for the bit depth of the window.
The depth argument may be null, if you aren't interested in getting the depth. The X and Y coordinates returned are relative to the parent window of window, which for toplevels usually means relative to the window decorations (titlebar, etc.) rather than relative to the root window (screen-size background window).

On the X11 platform, the geometry is obtained from the X server, so reflects the latest position of window; this may be out-of-sync with the position of window delivered in the most-recently-processed Gdk::EventConfigure. get_position() in contrast gets the position from the most recent configure event.

void Xfc::Gdk::Window::get_geometry (  int *  x,
int *  y,
int *  width,
int *  height,
int *  depth
)  const
 

Gets the current geometry of the window.

Parameters:
x The return location for the X coordinate of the window (relative to its parent).
y The return location for the Y coordinate of the window (relative to its parent).
width The return location for the width of the window.
height The return location for the height of the window.
depth The return location for the bit depth of the window.
Any of the return location arguments to this method may be null, if you aren't interested in getting the value of that field. The X and Y coordinates returned are relative to the parent window of window, which for toplevels usually means relative to the window decorations (titlebar, etc.) rather than relative to the root window (screen-size background window).

On the X11 platform, the geometry is obtained from the X server, so reflects the latest position of window; this may be out-of-sync with the position of window delivered in the most-recently-processed Gdk::EventConfigure. get_position() in contrast gets the position from the most recent configure event.

Point Xfc::Gdk::Window::get_origin (   )  const
 

Obtains the position of a window in root window coordinates.

Returns:
A Point holding the x, y coordinates.
Compare with get_position() and get_geometry() which return the position of a window relative to its parent window.

bool Xfc::Gdk::Window::get_origin (  int *  x,
int *  y
)  const
 

Obtains the position of a window in root window coordinates.

Parameters:
x The return location for X coordinate.
y The return location for Y coordinate.
Returns:
Nothing meaningful, ignore it.
Compare with get_position() and get_geometry() which return the position of a window relative to its parent window.

Window* Xfc::Gdk::Window::get_parent (   )  const
 

Obtains the parent of window, as known to GDK.

Returns:
The parent of the window.
Does not query the X server; thus this returns the parent as passed to the Gdk::Window constructor, not the actual parent. This should never matter unless you're using Xlib calls mixed with GDK calls on the X11 platform. It may also matter for toplevel windows, because the window manager may choose to reparent them.

Window* Xfc::Gdk::Window::get_pointer (  int *  x,
int *  y,
ModifierTypeField *  mask
)  const
 

Obtains the current pointer position and modifier state.

Parameters:
x The return location for X coordinate of the pointer.
y The return location for Y coordinate of the pointer.
mask The return location for modifier mask.
Returns:
The window containing the pointer (as with at_pointer()), or null if the window containing the pointer isn't known to GDK
The position is given in coordinates relative to the window.

Point Xfc::Gdk::Window::get_position (   )  const
 

Obtains the position of the window as reported in the most-recently-processed Gdk::EventConfigure (see get_position(int*, int*) const).

Returns:
A Point containing the x, y coordinates of the window relative to the parent window.
Contrast with get_geometry() which queries the X server for the current window position, regardless of which events have been received or processed. The position coordinates are relative to the window's parent window.

void Xfc::Gdk::Window::get_position (  int *  x,
int *  y
)  const
 

Obtains the position of the window as reported in the most-recently-processed Gdk::EventConfigure.

Parameters:
x The X coordinate of the window relative to the window's parent window.
y The Y coordinate of the window relative to the window's parent window.
Contrast with get_geometry() which queries the X server for the current window position, regardless of which events have been received or processed. The position coordinates are relative to the window's parent window.

Point Xfc::Gdk::Window::get_root_origin (   )  const
 

Obtains the top-left corner of the window manager frame in root window coordinates.

Returns:
A Point containing the x, y position of the window frame.

void Xfc::Gdk::Window::get_root_origin (  int *  x,
int *  y
)  const
 

Obtains the top-left corner of the window manager frame in root window coordinates.

Parameters:
x The return location for X position of the window frame.
y The return location for Y position of the window frame.

WindowState Xfc::Gdk::Window::get_state (   )  const
 

Gets the bitwise OR of the currently active window state flags, from the Gdk::WindowState enumeration.

Returns:
The window state bitfield.

Window* Xfc::Gdk::Window::get_toplevel (   )  const
 

Gets the toplevel window that's an ancestor of the window.

Returns:
The toplevel window containing the window.

bool Xfc::Gdk::Window::get_toplevels (  std::vector< Window * > &  toplevels  )  [static]
 

Obtains a list of all toplevel windows known to GDK on the default screen (see get_toplevels_for_screen()).

Parameters:
toplevels A reference to a vector of Window* to hold the list of toplevel windows.
Returns:
true if the vector is not empty.
A toplevel window is a child of the root window (see Gdk::get_default_root_window()).

Pointer<Region> Xfc::Gdk::Window::get_update_area (   )  const
 

Transfers ownership of the update area from the window to the caller of the method.

Returns:
The update area for the window, or null if there is no update area.
After calling this method the window will no longer have an invalid/dirty region; the update area is removed from the window and handed to you.

void Xfc::Gdk::Window::get_user_data (  void *&  data  )  const
 

Retrieves the user data for window, which is normally the widget that window belongs to (see set_user_data()).

Parameters:
data A reference to the return location for the user data.

void Xfc::Gdk::Window::hide (   ) 
 

For toplevel windows, withdraws them, so they will no longer be known to the window manager; for all windows, unmaps them, so they won't be displayed.

Normally done automatically as part of Gtk::Widget::hide().

void Xfc::Gdk::Window::iconify (   ) 
 

Asks to iconify (minimize) the window.

The window manager may choose to ignore the request, but normally will honor it. Using Gtk::Window::iconify() is preferred, if you have a Gtk::Window widget. This method only makes sense when the window is a toplevel window.

void Xfc::Gdk::Window::invalidate (  const Region &  region,
bool  invalidate_children
) 
 

Adds region to the update area for the window.

Parameters:
region A Region to invalidate.
invalidate_children Set true to also invalidate child windows.
The update area is the region that needs to be redrawn, or "dirty region." The call process_updates() sends one or more expose events to the window, which together cover the entire update area. An application would normally redraw the contents of the window in response to those expose events.

GDK will call process_all_updates() on your behalf whenever your program returns to the main loop and becomes idle, so normally there's no need to do that manually, you just need to invalidate regions that you know should be redrawn.

The invalidate_children parameter controls whether the region of each child window that intersects region will also be invalidated. If false, then the update area for child windows will remain unaffected. See gdk_window_invalidate_maybe_recurse() if you need fine grained control over which children are invalidated.

void Xfc::Gdk::Window::invalidate (  const Rectangle &  rectangle,
bool  invalidate_children
) 
 

Adds rectangle to the update area for the window.

Parameters:
rectangle A Rectangle.
invalidate_children Set true to also invalidate child windows.
This method is a convenience wrapper around invalidate(const Region&, bool) which invalidates a rectangular region.

bool Xfc::Gdk::Window::is_viewable (   )  const
 

Checks if the window and all ancestors of the window are mapped.

Returns:
true if the window is viewable.
This is not necessarily "viewable" in the X sense, since we only check as far as we have GDK window parents, not to the root window.

bool Xfc::Gdk::Window::is_visible (   )  const
 

Gets whether the window has been mapped (with show() or show_unraised()).

Returns:
true if the window is mapped.

GrabStatus Xfc::Gdk::Window::keyboard_grab (  bool  owner_events = false,
unsigned int  time = GDK_CURRENT_TIME
) 
 

This window grabs the keyboard so that all events are passed to this application until the keyboard is ungrabbed with Gdk::keyboard_ungrab().

Parameters:
owner_events If false then all keyboard events are reported with respect to the window. If true then keyboard events for this application are reported as normal, but keyboard events outside this application are reported with respect to the window. Both key press and key release events are always reported, independant of the event mask set by the application.
time A timestamp from a Gdk::Event, or GDK_CURRENT_TIME if no timestamp is available.
Returns:
GRAB_SUCCESS if the grab was successful.
This overrides any previous keyboard grab by this client.

Window* Xfc::Gdk::Window::lookup (  GdkNativeWindow  anid,
const Display *  display = 0
)  [static]
 

Looks up the Gdk::Window that wraps the given native window handle.

Parameters:
anid A native pixmap handle.
display The Display corresponding to the window handle, or null for the default display.
Returns:
The Gdk::Window wrapper for the native window, or null if there is none.
In the X backend, a native window handle is an Xlib XID.

void Xfc::Gdk::Window::lower (   ) 
 

Lowers the window to the bottom of the Z-order (stacking order), so that other windows with the same parent window appear above the window.

This is true whether or not the other windows are visible. If the window is a toplevel, the window manager may choose to deny the request to move the window in the Z-order, lower() only requests the restack, does not guarantee it.

Note that show() raises the window again, so don't call this function before show() (try show_unraised()).

void Xfc::Gdk::Window::maximize (   ) 
 

Maximizes the window.

If the window was already maximized, then this method does nothing. On X11, asks the window manager to maximize window, if the window manager supports this operation. Not all window managers support this, and some deliberately ignore it or don't have a concept of "maximized"; so you can't rely on the maximization actually happening. But it will happen with most standard window managers, and GDK makes a best effort to get it to happen.

void Xfc::Gdk::Window::merge_child_shapes (   ) 
 

Merges the shape masks for any child windows into the shape mask for this window (that is, the union of all masks for the window and its children will become the new mask for window (see shape_combine_mask()).

This method is distinct from set_child_shapes() because it includes window's shape mask in the set of shapes to be merged.

void Xfc::Gdk::Window::move (  const Point &  point  ) 
 

Repositions the window relative to its parent window.

Parameters:
point The x, y coordinates relative to window's parent.
For toplevel windows, window managers may ignore or modify the move; you should probably use Gtk::Window_move() on a Gtk::Window widget anyway, instead of using GDK methods. For child windows, the move will reliably succeed. If you're also planning to resize the window, use move_resize() to both move and resize simultaneously, for a nicer visual effect.

void Xfc::Gdk::Window::move (  int  x,
int  y
) 
 

Repositions the window relative to its parent window.

Parameters:
x The X coordinate relative to window's parent.
y The Y coordinate relative to window's parent.
For toplevel windows, window managers may ignore or modify the move; you should probably use Gtk::Window_move() on a Gtk::Window widget anyway, instead of using GDK methods. For child windows, the move will reliably succeed. If you're also planning to resize the window, use move_resize() to both move and resize simultaneously, for a nicer visual effect.

void Xfc::Gdk::Window::move_resize (  const Rectangle &  rectangle  ) 
 

Equivalent to calling move() and resize(), except that both operations are performed at once, avoiding strange visual effects.

Parameters:
rectangle A Gdk::Rectangle holding the new x, y coordinates relative to window's parent, and the new width and height.

void Xfc::Gdk::Window::move_resize (  int  x,
int  y,
int  width,
int  height
) 
 

Equivalent to calling move() and resize(), except that both operations are performed at once, avoiding strange visual effects.

Parameters:
x The X coordinate relative to window's parent.
y The Y coordinate relative to window's parent.
width The new width of the window.
height The new height of the window.
The user may be able to see the window first move, then resize, if you don't use move_resize().

GrabStatus Xfc::Gdk::Window::pointer_grab (  EventMaskField  event_mask,
Window *  confine_to = 0,
Cursor *  cursor = 0,
bool  owner_events = false,
unsigned int  time = GDK_CURRENT_TIME
) 
 

This window grabs the pointer (usualy a mouse) so that all events are passed to this application until the pointer is ungrabbed with Gdk::pointer_ungrab(), or the grab window becomes unviewable.

Parameters:
event_mask Specifies the event mask, which is used in accordance with owner_events.
confine_to If non-null, the pointer will be confined to this window during the grab. If the pointer is outside confine_to, it will automatically be moved to the closest edge of confine_to and enter and leave events will be generated as necessary.
cursor The cursor to display while the grab is active. If this is null then the normal cursors are used for window and its descendants, and the cursor for window is used for all other windows.
owner_events If false then all pointer events are reported with respect to window and are only reported if selected by event_mask. If true then pointer events for this application are reported as normal, but pointer events outside this application are reported with respect to window and only if selected by event_mask. In either mode, unreported events are discarded.
time The timestamp of the event which led to this pointer grab. This usually comes from Gdk::EventButton, though GDK_CURRENT_TIME can be used if the time isn't known.
Returns:
GRAB_SUCCESS if the grab was successful.
This overrides any previous pointer grab by this client. Pointer grabs are used for operations which need complete control over mouse events, even if the mouse leaves the application. For example in GTK+ it is used for Drag and Drop, and for dragging the handle in the Gtk::HPaned and Gtk::VPaned widgets.

Note that if the event mask of an X window has selected both button press and button release events, then a button press event will cause an automatic pointer grab until the button is released. X does this automatically since most applications expect to receive button press and release events in pairs. It is equivalent to a pointer grab on the window with owner_events set to true.

void Xfc::Gdk::Window::process_updates (  bool  update_children  ) 
 

Sends one or more expose events to the window.

Parameters:
update_children Whether to also process updates for child windows.
The areas in each expose event will cover the entire update area for the window (see invalidate(const Region&, bool) for details). Normally GDK calls process_all_updates() on your behalf, so there's no need to call this function unless you want to force expose events to be delivered immediately and synchronously (vs. the usual case, where GDK delivers them in an idle handler). Occasionally this is useful to produce nicer scrolling behavior, for example.

void Xfc::Gdk::Window::raise (   ) 
 

Raises the window to the top of the Z-order (stacking order), so that other windows with the same parent window appear below the window.

This method works whether or not the windows are visible. If window is a toplevel, the window manager may choose to deny the request to move the window in the Z-order, raise() only requests the restack, does not guarantee it.

void Xfc::Gdk::Window::remove_filter (  Window *  window,
GdkFilterFunc  function,
void *  data
)  [static]
 

Remove a filter previously added with add_filter().

Parameters:
window The Gdk::Window the filter was added to, or null for all windows.
function The filter callback to call on each event.
data Data to pass to filter callback.

void Xfc::Gdk::Window::reparent (  Window &  new_parent,
int  x,
int  y
) 
 

Reparents the window into the given new_parent.

The window being reparented will be unmapped as a side effect.

Parameters:
new_parent The new parent to move window into.
x The X location inside the new parent.
y The Y location inside the new parent.

void Xfc::Gdk::Window::resize (  int  width,
int  height
) 
 

Resizes the window; for toplevel windows, asks the window manager to resize the window.

Parameters:
width The new width of the window.
height The new height of the window.
The window manager may not allow the resize. Use Gtk::Window::resize() instead of this low-level method. Windows may not be resized below 1x1. If you're also planning to move the window, use move_resize() to both move and resize simultaneously, for a nicer visual effect.

void Xfc::Gdk::Window::scroll (  int  dx,
int  dy
) 
 

Scroll the contents of window, both pixels and children, by the given amount.

Parameters:
dx The amount to scroll in the X direction.
dy The amount to scroll in the Y direction.
The window itself does not move. Portions of the window that the scroll operation brings in from offscreen areas are invalidated. The invalidated region may be bigger than what would strictly be necessary. (For X11, a minimum area will be invalidated if the window has no subwindows, or if the edges of the window's parent do not extend beyond the edges of the window. In other cases, a multi-step process is used to scroll the window which may produce temporary visual artifacts and unnecessary invalidations.)

void Xfc::Gdk::Window::set_accept_focus (  bool  accept_focus  ) 
 

Setting accept_focus to false hints the desktop environment that the window doesn't want to receive the input focus.

Parameters:
accept_focus Set true if the window should receive input focus.
On X, it is the responsibility of the window manager to interpret this hint. ICCCM-compliant window managers usually respect it.

void Xfc::Gdk::Window::set_back_pixmap (  Pixmap *  pixmap,
bool  parent_relative = false
) 
 

Sets the background pixmap of the window.

Parameters:
pixmap A Pixmap, or null for no background.
parent_relative Whether the tiling origin is at the origin of window's parent.
To set a background of "None" on the window, set a background pixmap of null. A background pixmap will be tiled, positioning the first tile at the origin of the window, or if parent_relative is true, the tiling will be done based on the origin of the parent window (useful to align tiles in a parent with tiles in a child).

A background pixmap of null means that the window will have no background. A window with no background will never have its background filled by the windowing system, instead the window will contain whatever pixels were already in the corresponding area of the display. The windowing system will normally fill a window with its background when the window is obscured then exposed, and when you call clear().

void Xfc::Gdk::Window::set_background (  const Color &  color  ) 
 

Sets the background color of the window.

Parameters:
color An allocated Color.
When using a Gtk::Widget, set the background of the widget with Gtk::Widget::modify_bg() if you're an application, or Gtk::Style::set_background() if you're implementing a custom widget. The color must be allocated; Gdk::Colormap::rgb_find_color() is the best way to allocate a color. See also set_back_pixmap().

void Xfc::Gdk::Window::set_child_shapes (   ) 
 

Sets the shape mask of the window to the union of shape masks for all children of the window, ignoring the shape mask of the window itself.

Contrast with merge_child_shapes() which includes the shape mask of the window in the masks to be merged. This method quickly takes the shapes of all the child windows and uses their shapes as the shape mask for this window.

void Xfc::Gdk::Window::set_cursor (  const Cursor &  cursor  ) 
 

Sets the mouse pointer for the window.

Parameters:
cursor A Cursor.
By default, most windows use the cursor of its parent window.

void Xfc::Gdk::Window::set_debug_updates (  bool  setting  ) 
 

With update debugging enabled, calls to invalidate(const Region&, bool) clear the invalidated region of the screen to a noticeable color, and GDK pauses for a short time before sending exposes to windows during process_updates().

Parameters:
setting Set true to turn on update debugging.
The net effect is that you can see the invalid region for each window and watch redraws as they occur. This allows you to diagnose inefficiencies in your application. In essence, because the GDK rendering model prevents all flicker, if you are redrawing the same region 400 times you may never notice, aside from noticing a speed problem. Enabling update debugging causes GTK to flicker slowly and noticeably, so you can see exactly what's being redrawn when, in what order.

The --gtk-debug=updates command line option passed to GTK+ programs enables this debug option at application startup time. That's usually more useful than calling set_debug_updates() yourself, though you might want to use this method to enable updates sometime after application startup time.

void Xfc::Gdk::Window::set_decorations (  WMDecorationField  decorations  ) 
 

"Decorations" are the features the window manager adds to a toplevel Gdk::Window

Parameters:
decorations The Gdk::WMDecoration hint mask.
This method sets the traditional Motif window manager hints that tell the window manager which decorations you would like your window to have. Usually you should use Gtk::Window::set_decorated() on a Gtk::Window instead of using this GDK method.

The decorations argument is the logical OR of the fields in the WMDecoration enumeration. If DECOR_ALL is included in the mask, the other bits indicate which decorations should be turned off. If DECOR_ALL is not included, then the other bits indicate which decorations should be turned on.

Most window managers honor a decorations hint of 0 to disable all decorations, but very few honor all possible combinations of bits.

void Xfc::Gdk::Window::set_events (  EventMaskField  event_mask  ) 
 

Sets the event mask for the window.

Parameters:
event_mask The event mask for the window.
The event mask for a window determines which events will be reported for that window. For example, an event mask including BUTTON_PRESS_MASK means the window should report button press events. The event mask is the bitwise OR of values from the EventMask enumeration.

void Xfc::Gdk::Window::set_extension_events (  int  mask,
ExtensionMode  mode
) 
 

Turns extension events on or off for a particular window, and specifies the event mask for extension events.

Parameters:
mask The event mask.
mode The type of extension events that are desired.

void Xfc::Gdk::Window::set_focus_on_map (  bool  focus_on_map  ) 
 

Setting focus_on_map to false hints the desktop environment that the window doesn't want to receive input focus when it is mapped.

Parameters:
focus_on_map Set to true if the window should receive input focus when mapped.
The focus_on_map property should be turned off for windows that aren't triggered interactively (such as popups from network activity). On X, it is the responsibility of the window manager to interpret this hint. Window managers following the freedesktop.org window manager extension specification should respect it.

void Xfc::Gdk::Window::set_functions (  WMFunctionField  functions  ) 
 

Sets the traditional Motif window manager hint for which operations the window manager should allow on a toplevel window.

Parameters:
functions The Gdk::WMFunction bitmask of operations to allow on the window.
This method isn't really good for much. Few window managers do anything reliable or interesting with this hint. Many ignore it entirely.

The functions argument is the logical OR of values from the GdkWMFunction enumeration. If the bitmask includes FUNC_ALL, then the other bits indicate which functions to disable; if it doesn't include FUNC_ALL, it indicates which functions to enable.

void Xfc::Gdk::Window::set_geometry_hints (  const Geometry *  geometry  ) 
 

Sets the geometry hints for the window.

Parameters:
geometry A Geometry object containing geometry information, or null to unset all hints.
Geometry hints not specifically set in geometry will be unset. To unset all hints pass a geometry of null.

This method provides hints to the windowing system about acceptable sizes for a toplevel window. The purpose of this is to constrain user resizing, but the windowing system will typically (but is not required to) also constrain the current size of the window to the provided values and constrain programatic resizing via resize() or move_resize().

Note that on X11, this effect has no effect on windows of type WINDOW_TEMP or windows where override_redirect has been turned on via set_override_redirect() since these windows are not resizable by the user.

Since you can't count on the windowing system doing the constraints for programmatic resizes, you should generally call Gdk::Geometry::constrain_size() yourself to determine appropriate sizes.

void Xfc::Gdk::Window::set_group (  Window &  leader  ) 
 

Sets the group leader window for the window.

Parameters:
leader The group leader window.
By default, GDK sets the group leader for all toplevel windows to a global window implicitly created by GDK. With this function you can override this default. The group leader window allows the window manager to distinguish all windows that belong to a single application. It may for example allow users to minimize/unminimize all windows belonging to an application at once. You should only set a non-default group window if your application pretends to be multiple applications. The group leader window may not be changed after a window has been mapped (with show() for example).

void Xfc::Gdk::Window::set_icon (  Pixmap *  pixmap,
Bitmap *  mask,
Window *  icon_window = 0
) 
 

Sets the icon of the window as a pixmap or window.

Parameters:
icon_window A Gdk::Window to use for the icon, or null to unset.
pixmap A Pixmap to use as the icon, or null to unset.
mask A 1-bit pixmap (Gdk::Bitmap) to use as mask for pixmap, or null for none.
Investigate Gtk::Window::set_default_icon_list() first, and then Gtk::Window::set_icon_list() and Gtk::Window::set_icon(). If those don't meet your needs, look at Gdk::Window::set_icon_list(). Only if all those are too high-level do you want to fall back to set_icon().

void Xfc::Gdk::Window::set_icon_list (  const std::vector< Pixbuf * > &  pixbufs  ) 
 

Sets a list of icons for the window.

Parameters:
pixbufs A reference to a vector of Pixbuf* that holds a list of pixbufs, of different sizes.
One of these will be used to represent the window when it has been iconified. The icon is usually shown in an icon box or some sort of task bar. Which icon size is shown depends on the window manager. The window manager can scale the icon but setting several size icons can give better image quality since the window manager may only need to scale the icon by a small amount or not at all.

void Xfc::Gdk::Window::set_icon_name (  const String &  name  ) 
 

Windows may have a name used while minimized, distinct from the name they display in their titlebar.

Parameters:
name The name of window while iconified (minimized).
Most of the time this is a bad idea from a user interface standpoint. But you can set such a name with this method, if you like.

void Xfc::Gdk::Window::set_keep_above (  bool  setting  ) 
 

Set if the window must be kept above other windows.

Parameters:
setting Whether to keep the window above other windows.
If the window was already above, then this function does nothing. On X11, this method asks the window manager to keep the window above, if the window manager supports this operation. Not all window managers support this, and some deliberately ignore it or don't have a concept of "keep above"; so you can't rely on the window being kept above. But it will happen with most standard window managers, and GDK makes a best effort to get it to happen.

void Xfc::Gdk::Window::set_keep_below (  bool  setting  ) 
 

Set if the window must be kept below other windows.

Parameters:
setting Whether to keep the window below other windows.
If the window was already below, then this function does nothing. On X11, this method asks the window manager to keep window below, if the window manager supports this operation. Not all window managers support this, and some deliberately ignore it or don't have a concept of "keep below"; so you can't rely on the window being kept below. But it will happen with most standard window managers, and GDK makes a best effort to get it to happen.

void Xfc::Gdk::Window::set_modal_hint (  bool  modal  ) 
 

The application can use this hint to tell the window manager that a certain window has modal behaviour.

Parameters:
modal Set true if the window is modal, false otherwise.
The window manager can use this information to handle modal windows in a special way. You should only use this on windows for which you have previously called set_transient_for().

void Xfc::Gdk::Window::set_override_redirect (  bool  override_redirect  ) 
 

An override redirect window is not under the control of the window manager (this means it won't have a titlebar, won't be minimizable, etc., it will be entirely under the control of the application).

Parameters:
override_redirect true if window should be override redirect.
The window manager can't see the override redirect window at all. Override redirect should only be used for short-lived temporary windows, such as popup menus. Gtk::Menu uses an override redirect window in its implementation, for example.

void Xfc::Gdk::Window::set_role (  const String &  role  ) 
 

Typically you should use Gtk::Window::set_role() instead of this low-level method.

Parameters:
role A string indicating its role.
The window manager and session manager use a window's role to distinguish it from other kinds of window in the same application. When an application is restarted after being saved in a previous session, all windows with the same title and role are treated as interchangeable. So if you have two windows with the same title that should be distinguished for session management purposes, you should set the role on those windows. It doesn't matter what string you use for the role, as long as you have a different role for each non-interchangeable kind of window.

void Xfc::Gdk::Window::set_skip_pager_hint (  bool  skips_pager  ) 
 

Toggles whether the window should appear in a pager (workspace switcher, or other desktop utility program that displays a small thumbnail representation of the windows on the desktop).

Parameters:
skips_pager Set true to skip the pager.
If a window's semantic type as specified with set_type_hint() already fully describes the window, this function should NOT be called in addition, instead you should allow the window to be treated according to standard policy for its semantic type.

void Xfc::Gdk::Window::set_skip_taskbar_hint (  bool  skips_taskbar  ) 
 

Toggles whether the window should appear in a task list or window list.

Parameters:
skips_taskbar Set true to skip the taskbar.
If a window's semantic type as specified with set_type_hint() already fully describes the window, this method should NOT be called in addition, instead you should allow the window to be treated according to standard policy for its semantic type.

bool Xfc::Gdk::Window::set_static_gravities (  bool  use_static  ) 
 

Set the bit gravity of the window to static and flag it so all children get static subwindow gravity.

Parameters:
use_static set true to turn on static gravity.
Returns:
true if the server supports static gravity.
This is used if you are implementing scary features that involve deep knowledge of the windowing system. Don't worry about it unless you have to.

void Xfc::Gdk::Window::set_title (  const String &  title  ) 
 

Sets the title of a toplevel window, to be displayed in the titlebar.

Parameters:
title The title of the window.
If you haven't explicitly set the icon name for the window (using set_icon_name()), the icon name will be set to title as well.

void Xfc::Gdk::Window::set_transient_for (  Window &  parent  ) 
 

Indicates to the window manager that window is a transient dialog associated with the application window parent.

Parameters:
parent Another toplevel Gdk::Window.
This allows the window manager to do things like center window on parent and keep window above parent. See Gtk::Window::set_transient_for() if you're using Gtk::Window or Gtk::Dialog.

void Xfc::Gdk::Window::set_type_hint (  WindowTypeHint  hint  ) 
 

The application can use this call to provide a hint to the window manager about the functionality of the window.

Parameters:
hint A hint of the function this window will have.
The window manager can use this information when determining the decoration and behaviour of the window. The hint must be set before the window is mapped.

void Xfc::Gdk::Window::set_user_data (  void *  user_data  ) 
 

For most purposes this method is deprecated in favor of G::Object::set_data().

Parameters:
user_data The user_data.
For historical reasons GTK+ stores the GtkWidget that owns a Gdk::Window as user data on the Gdk::Window. So, custom widget implementations should use this method for that. If GTK+ receives an event for a Gdk::Window, and the user data for the window is non-null, GTK+ will assume the user data is a GtkWidget, and forward the event to that widget.

void Xfc::Gdk::Window::shape_combine_mask (  Bitmap *  shape_mask,
int  x = 0,
int  y = 0
) 
 

Make a shaped partially transparent window using a bitmap mask.

Parameters:
shape_mask The shape mask, or null to unset a previously set shape mask.
x The X position of shape_mask with respect to the window.
y The Y position of shape_mask with respect to the window.
Applies shape_mask to the window. Pixels in the window corresponding to set bits in the mask will be visible; pixels in the window corresponding to unset bits in the mask will be transparent. This gives a non-rectangular window. If shape_mask is null, the shape mask will be unset, and the x/y parameters are not used.

On the X11 platform, this uses an X server extension which is widely available on most common platforms, but not available on very old X servers, and occasionally the implementation will be buggy. On servers without the shape extension, this method will do nothing.

Note: This method works on both toplevel and child windows.

void Xfc::Gdk::Window::shape_combine_region (  Region *  shape_region,
int  offset_x = 0,
int  offset_y = 0
) 
 

Makes pixels in the window outside shape_region be transparent, so that the window may be non-rectangular (see also shape_combine_mask() to use a bitmap as the mask.

Parameters:
shape_region The region of the window to be non-transparent, or null to unset a previously set shape_region.
offset_x The X position of shape_region in window coordinates.
offset_y The Y position of shape_region in window coordinates.
If shape_region is null, the shape will be unset, so the whole window will be opaque again. offset_x and offset_y are ignored if shape_region is null.

On the X11 platform, this uses an X server extension which is widely available on most common platforms, but not available on very old X servers, and occasionally the implementation will be buggy. On servers without the shape extension, this method will do nothing.

Note: This method works on both toplevel and child windows.

void Xfc::Gdk::Window::show (   ) 
 

Like show_unraised(), but also raises the window to the top of the window stack (moves the window to the front of the Z-order).

This method maps a window so it's visible onscreen. It's opposite is hide().

Note: When implementing a Gtk::Widget, you should call this method on the widget's Gdk::Window as part of the "map" method.

void Xfc::Gdk::Window::show_unraised (   ) 
 

Shows a Gdk::Window onscreen, but does not modify its stacking order.

In contrast, show() will raise the window to the top of the window stack. On the X11 platform, in Xlib terms, this function calls XMapWindow() (it also updates some internal GDK state, which means that you can't really use XMapWindow() directly on a GDK window).

void Xfc::Gdk::Window::stick (   ) 
 

"Pins" the window such that it's on all workspaces and does not scroll with viewports, for window managers that have scrollable viewports

When using Gtk::Window, Gtk::Window::stick() may be more useful. On the X11 platform, this method depends on window manager support, so may have no effect with many window managers. However, GDK will do the best it can to convince the window manager to stick the window. For window managers that don't support this operation, there's nothing you can do to force it to happen.

void Xfc::Gdk::Window::unfullscreen (   ) 
 

Moves the window out of fullscreen mode.

If the window was not fullscreen, does nothing. On X11, asks the window manager to move window out of the fullscreen state, if the window manager supports this operation. Not all window managers support this, and some deliberately ignore it or don't have a concept of "fullscreen"; so you can't rely on the unfullscreenification actually happening. But it will happen with most standard window managers, and GDK makes a best effort to get it to happen.

void Xfc::Gdk::Window::unmaximize (   ) 
 

Unmaximizes the window.

If the window wasn't maximized, then this method does nothing. On X11, asks the window manager to unmaximize window, if the window manager supports this operation. Not all window managers support this, and some deliberately ignore it or don't have a concept of "maximized"; so you can't rely on the unmaximization actually happening. But it will happen with most standard window managers, and GDK makes a best effort to get it to happen.

void Xfc::Gdk::Window::withdraw (   ) 
 

Withdraws the window (unmaps it and asks the window manager to forget about it).

This function is not really useful as hide() automatically withdraws toplevel windows before hiding them.

The documentation for this class was generated from the following file: Xfce Foundation Classes
Copyright © 2004-2005 The XFC Development Team XFC 4.3