RGtk2 (version 2.20.31)

gdk-Windows: Windows

Description

Onscreen display areas in the target window system

Arguments

Methods and Functions

gdkWindowNew(parent = NULL, attributes) gdkWindowDestroy(object) gdkWindowGetWindowType(object) gdkWindowAtPointer() gdkWindowShow(object) gdkWindowShowUnraised(object) gdkWindowHide(object) gdkWindowIsDestroyed(object) gdkWindowIsVisible(object) gdkWindowIsViewable(object) gdkWindowGetState(object) gdkWindowWithdraw(object) gdkWindowIconify(object) gdkWindowDeiconify(object) gdkWindowStick(object) gdkWindowUnstick(object) gdkWindowMaximize(object) gdkWindowUnmaximize(object) gdkWindowFullscreen(object) gdkWindowUnfullscreen(object) gdkWindowSetKeepAbove(object, setting) gdkWindowSetKeepBelow(object, setting) gdkWindowSetOpacity(object, opacity) gdkWindowSetComposited(object, composited) gdkWindowMove(object, x, y) gdkWindowResize(object, width, height) gdkWindowMoveResize(object, x, y, width, height) gdkWindowScroll(object, dx, dy) gdkWindowMoveRegion(object, region, x, y) gdkWindowFlush(object) gdkWindowEnsureNative(object) gdkWindowReparent(object, new.parent, x, y) gdkWindowClear(object) gdkWindowClearArea(object, x, y, width, height) gdkWindowClearAreaE(object, x, y, width, height) gdkWindowRaise(object) gdkWindowLower(object) gdkWindowRestack(object, sibling, above) gdkWindowFocus(object, timestamp = "GDK_CURRENT_TIME") gdkWindowRegisterDnd(object) gdkWindowBeginResizeDrag(object, edge, button, root.x, root.y, timestamp) gdkWindowBeginMoveDrag(object, button, root.x, root.y, timestamp) gdkWindowConstrainSize(geometry, width, height) gdkWindowBeep(object) gdkWindowBeginPaintRect(object, rectangle) gdkWindowBeginPaintRegion(object, region) gdkWindowEndPaint(object) gdkWindowInvalidateRect(object, rect = NULL, invalidate.children) gdkWindowInvalidateRegion(object, region, invalidate.children) gdkWindowInvalidateMaybeRecurse(object, region, child.func, user.data) gdkWindowGetUpdateArea(object) gdkWindowFreezeUpdates(object) gdkWindowThawUpdates(object) gdkWindowProcessAllUpdates() gdkWindowProcessUpdates(object, update.children) gdkWindowSetDebugUpdates(setting) gdkWindowGetInternalPaintInfo(object) gdkWindowEnableSynchronizedConfigure(object) gdkWindowConfigureFinished(object) gdkWindowSetUserData(object, user.data = NULL) gdkWindowSetOverrideRedirect(object, override.redirect) gdkWindowSetAcceptFocus(object, accept.focus) gdkWindowSetFocusOnMap(object, focus.on.map) gdkWindowAddFilter(object, fun, data) gdkWindowRemoveFilter(object, fun, data) gdkWindowShapeCombineMask(object, shape.mask = NULL, offset.x, offset.y) gdkWindowShapeCombineRegion(object, shape.region = NULL, offset.x, offset.y) gdkWindowSetChildShapes(object) gdkWindowMergeChildShapes(object) gdkWindowInputShapeCombineMask(object, mask, x, y) gdkWindowInputShapeCombineRegion(object, shape.region, offset.x, offset.y) gdkWindowSetChildInputShapes(object) gdkWindowMergeChildInputShapes(object) gdkWindowSetStaticGravities(object, use.static) gdkWindowSetHints(object, x, y, min.width, min.height, max.width, max.height, flags) gdkWindowSetTitle(object, title) gdkWindowSetBackground(object, color) gdkWindowSetBackPixmap(object, pixmap = NULL, parent.relative) gdkWindowSetCursor(object, cursor = NULL) gdkWindowGetCursor(object) gdkWindowGetUserData(object) gdkWindowGetGeometry(object) gdkWindowSetGeometryHints(object, geometry) gdkWindowSetIconList(object, pixbufs) gdkWindowSetModalHint(object, modal) gdkWindowSetTypeHint(object, hint) gdkWindowGetTypeHint(object) gdkWindowSetSkipTaskbarHint(object, modal) gdkWindowSetSkipPagerHint(object, modal) gdkWindowSetUrgencyHint(object, urgent) gdkWindowGetPosition(object) gdkWindowGetRootOrigin(object) gdkWindowGetFrameExtents(object) gdkWindowGetOrigin(object) gdkWindowGetDeskrelativeOrigin(object) gdkWindowGetRootCoords(object, x, y) gdkWindowGetPointer(object) gdkWindowGetParent(object) gdkWindowGetToplevel(object) gdkWindowGetChildren(object) gdkWindowPeekChildren(object) gdkWindowGetEvents(object) gdkWindowSetEvents(object, event.mask) gdkWindowSetIcon(object, icon.window, pixmap, mask) gdkWindowSetIconName(object, name) gdkWindowSetTransientFor(object, leader) gdkWindowSetRole(object, role) gdkWindowSetStartupId(object, startup.id) gdkWindowSetGroup(object, leader) gdkWindowGetGroup(object) gdkWindowSetDecorations(object, decorations) gdkWindowGetDecorations(object) gdkWindowSetFunctions(object, functions) gdkWindowGetToplevels() gdkGetDefaultRootWindow() gdkSetPointerHooks(object, new.hooks) gdkOffscreenWindowGetPixmap(window) gdkOffscreenWindowSetEmbedder(window, embedder) gdkOffscreenWindowGetEmbedder(window) gdkWindowGeometryChanged(object) gdkWindowRedirectToDrawable(object, drawable, src.x, src.y, dest.x, dest.y, width, height) gdkWindowRemoveRedirection(object) gdkWindow(parent = NULL, attributes)

Hierarchy

GObject
   +----GdkDrawable
         +----GdkWindow

Detailed Description

A GdkWindow is a rectangular region on the screen. It's a low-level object, used to implement high-level objects such as GtkWidget and GtkWindow on the GTK+ level. A GtkWindow is a toplevel window, the thing a user might think of as a "window" with a titlebar and so on; a GtkWindow may contain many GdkWindow. For example, each GtkButton has a GdkWindow associated with it.

Composited Windows

Normally, the windowing system takes care of rendering the contents of a child window onto its parent window. This mechanism can be intercepted by calling gdkWindowSetComposited on the child window. For a composited window it is the responsibility of the application to render the window contents at the right spot. Composited windows
# The expose event handler for the event box.
# 
# This function simply draws a transparency onto a widget on the area
# for which it receives expose events.  This is intended to give the
# event box a "transparent" background.
# 
# In order for this to work properly, the widget must have an RGBA
# colormap.  The widget should also be set as app-paintable since it
# doesn't make sense for GTK+ to draw a background if we are drawing it
# (and because GTK+ might actually replace our transparency with its
# default background color).
# 
transparent_expose <- function(widget, event)
{
  cr <- gdkCairoCreate(widget$window)
  cr$setOperator("clear")
  gdkCairoRegion(cr, event$region)
  cr$fill() return(FALSE)
} # The expose event handler for the window.
# 
# This function performs the actual compositing of the event box onto
# the already-existing background of the window at 50% normal opacity.
# 
# In this case we do not want app-paintable to be set on the widget
# since we want it to draw its own (red) background. Because of this,
# however, we must ensure that we set after = TRUE when connecting to the signal
# so that this handler is called after the red has been drawn. If it was
# called before then GTK would just blindly paint over our work.
# 
# Note: if the child window has children, then you need a cairo 1.16
# feature to make this work correctly.
# window_expose_event <- function(widget, event)
{
  # get our child (in this case, the event box) 
  child <- widget$getChild() # create a cairo context to draw to the window 
  cr <- gdkCairoCreate(widget$window) # the source data is the (composited) event box
  gdkCairoSetSourcePixmap(cr, child$window, child$allocation$x, 
                          child$allocation$y) # draw no more than our expose event intersects our child
  region <- gdkRegionRectangle(child$allocation)
  region$intersect(event$region)
  gdkCairoRegion(cr, region)
  cr$clip() # composite, with a 50% opacity
  cr$setOperator("over")
  cr$paintWithAlpha(0.5) return(FALSE)
} # Make the widgets
button <- gtkButton("A Button")
event <- gtkEventBox()
window <- gtkWindow() # Put a red background on the window
red <- gdkColorParse("red")$color
window$modifyBg("normal", red) # Set the colormap for the event box.
# Must be done before the event box is realized.
#
screen <- event$getScreen()
rgba <- screen$getRgbaColormap()
event$setColormap(rgba) # Set our event box to have a fully-transparent background
# drawn on it. Currently there is no way to simply tell GTK+
# that "transparency" is the background color for a widget.
#
event$setAppPaintable(TRUE)
gSignalConnect(event, "expose-event", transparent_expose) # Put them inside one another
window$setBorderWidth(10)
window$add(event)
event$add(button) # Set the event box GdkWindow to be composited.
# Obviously must be performed after event box is realized.
#
event$window$setComposited(TRUE) # Set up the compositing handler.
# Note that we do _after_ so that the normal (red) background is drawn
# by gtk before our compositing occurs.
#
gSignalConnect(window, "expose-event", window_expose_event, after = TRUE)
In the example , a button is placed inside of an event box inside of a window. The event box is set as composited and therefore is no longer automatically drawn to the screen. When the contents of the event box change, an expose event is generated on its parent window (which, in this case, belongs to the toplevel GtkWindow). The expose handler for this widget is responsible for merging the changes back on the screen in the way that it wishes. In our case, we merge the contents with a 50% transparency. We also set the background colour of the window to red. The effect is that the background shows through the button.

Offscreen Windows

Offscreen windows are more general than composited windows, since they allow not only to modify the rendering of the child window onto its parent, but also to apply coordinate transformations. To integrate an offscreen window into a window hierarchy, one has to call gdkWindowSetEmbedder() and handle a number of signals. The gdkOffscreenWindowSetEmbedder and handle a number of signals. The "pick-embedded-child" signal on the embedder window is used to select an offscreen child at given coordinates, and the "to-embedder" and "from-embedder" signals on the offscreen window are used to translate coordinates between the embedder and the offscreen window. For rendering an offscreen window onto its embedder, the contents of the offscreen window are available as a pixmap, via gdkOffscreenWindowGetPixmap.

Structures

GdkWindow
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.
GdkGeometry
The GdkGeometry struct gives the window manager information about a window's geometry constraints. Normally you would set these on the GTK+ level using gtkWindowSetGeometryHints. GtkWindow then sets the hints on the GdkWindow it creates. gdkWindowSetGeometryHints expects the hints to be fully valid already and simply passes them to the window manager; in contrast, gtkWindowSetGeometryHints performs some interpretation. For example, GtkWindow will apply the hints to the geometry widget instead of the toplevel window, if you set a geometry widget. Also, the min.width/min.height/max.width/max.height fields may be set to -1, and GtkWindow will substitute the size request of the window or geometry widget. If the minimum size hint is not provided, GtkWindow will use its requisition as the minimum size. If the minimum size is provided and a geometry widget is set, GtkWindow will take the minimum size as the minimum size of the geometry widget rather than the entire window. The base size is treated similarly. The canonical use-case for gtkWindowSetGeometryHints is to get a terminal widget to resize properly. Here, the terminal text area should be the geometry widget; GtkWindow will then automatically set the base size to the size of other widgets in the terminal window, such as the menubar and scrollbar. Then, the width.inc and height.inc fields should be set to the size of one character in the terminal. Finally, the base size should be set to the size of one character. The net effect is that the minimum size of the terminal will have a 1x1 character terminal area, and only terminal sizes on the "character grid" will be allowed. Here's an example of how the terminal example would be implemented, assuming a terminal area widget called "terminal" and a toplevel window "toplevel":
fields <- c("base.width", "base.height", "min.width", "min.height", "width.inc",
            "height.inc")
hints[fields] <- char_width
toplevel$setGeometryHints(terminal, hints)
The other useful fields are the min.aspect and max.aspect fields; these contain a width/height ratio as a floating point number. If a geometry widget is set, the aspect applies to the geometry widget rather than the entire window. The most common use of these hints is probably to set min.aspect and max.aspect to the same value, thus forcing the window to keep a constant aspect ratio. GdkGeometry is a transparent-type.
min_width
minimum width of window (or -1 to use requisition, with GtkWindow only)
min_height
minimum height of window (or -1 to use requisition, with GtkWindow only)
max_width
maximum width of window (or -1 to use requisition, with GtkWindow only)
max_height
maximum height of window (or -1 to use requisition, with GtkWindow only)
base_width
allowed window widths are base.width + width.inc * N where N is any integer (-1 allowed with GtkWindow)
base_height
allowed window widths are base.height + height.inc * N where N is any integer (-1 allowed with GtkWindow)
width_inc
width resize increment
height_inc
height resize increment
min_aspect
minimum width/height ratio
max_aspect
maximum width/height ratio
win_gravity
window gravity, see gtkWindowSetGravity
GdkWindowAttr
Attributes to use for a newly-created window. GdkWindowAttr is a transparent-type.
title
title of the window (for toplevel windows)
event_mask
event mask (see gdkWindowSetEvents)
x
X coordinate relative to parent window (see gdkWindowMove)
y
Y coordinate relative to parent window (see gdkWindowMove)
width
width of window
height
height of window
wclass
GDK_INPUT_OUTPUT (normal window) or GDK_INPUT_ONLY (invisible window that receives events)
visual
GdkVisual for window
colormap
GdkColormap for window
window_type
type of window
cursor
cursor for the window (see gdkWindowSetCursor)
wmclass_name
don't use (see gtkWindowSetWmclass)
wmclass_class
don't use (see gtkWindowSetWmclass)
override_redirect
TRUE to bypass the window manager
type_hint
a hint of the function of the window
GdkFilterReturn
Specifies the result of applying a GdkFilterFunc to a native event.

Convenient Construction

gdkWindow is the equivalent of gdkWindowNew.

Enums and Flags

GdkWindowType
Describes the kind of window.
root
root window; this window has no parent, covers the entire screen, and is created by the window system
toplevel
toplevel window (used to implement GtkWindow)
child
child window (used to implement e.g. GtkEntry)
dialog
useless/deprecated compatibility type
temp
override redirect temporary window (used to implement GtkMenu)
foreign
foreign window (see gdkWindowForeignNew())
GdkWindowClass
GDK.INPUT.OUTPUT windows are the standard kind of window you might expect. GDK.INPUT.ONLY windows are invisible; they are used to trap events, but you can't draw on them.
output
window for graphics and events
only
window for events only
GdkWindowHints
Used to indicate which fields of a GdkGeometry struct should be paid attention to. Also, the presence/absence of GDK.HINT.POS, GDK.HINT.USER.POS, and GDK.HINT.USER.SIZE is significant, though they don't directly refer to GdkGeometry fields. GDK.HINT.USER.POS will be set automatically by GtkWindow if you call gtkWindowMove. GDK.HINT.USER.POS and GDK.HINT.USER.SIZE should be set if the user specified a size/position using a --geometry command-line argument; gtkWindowParseGeometry() automatically sets these flags.
pos
indicates that the program has positioned the window
min-size
min size fields are set
max-size
max size fields are set
base-size
base size fields are set
aspect
aspect ratio fields are set
resize-inc
resize increment fields are set
win-gravity
window gravity field is set
user-pos
indicates that the window's position was explicitly set by the user
user-size
indicates that the window's size was explicitly set by the user
GdkGravity
Defines the reference point of a window and the meaning of coordinates passed to gtkWindowMove. See gtkWindowMove and the "implementation notes" section of the Extended Window Manager Hints (http://www.freedesktop.org/Standards/wm-spec) specification for more details.
north-west
the reference point is at the top left corner.
north
the reference point is in the middle of the top edge.
north-east
the reference point is at the top right corner.
west
the reference point is at the middle of the left edge.
center
the reference point is at the center of the window.
east
the reference point is at the middle of the right edge.
south-west
the reference point is at the lower left corner.
south
the reference point is at the middle of the lower edge.
south-east
the reference point is at the lower right corner.
static
the reference point is at the top left corner of the window itself, ignoring window manager decorations.
GdkWindowEdge
Determines a window edge or corner.
north-west
the top left corner.
north
the top edge.
north-east
the top right corner.
west
the left edge.
east
the right edge.
south-west
the lower left corner.
south
the lower edge.
south-east
the lower right corner.
GdkWindowTypeHint
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. See the Extended Window Manager Hints (http://www.freedesktop.org/Standards/wm-spec) specification for more details about window types.
normal
Normal toplevel window.
dialog
Dialog window.
menu
Window used to implement a menu; GTK+ uses this hint only for torn-off menus, see GtkTearoffMenuItem.
toolbar
Window used to implement toolbars.
splashscreen
Window used to display a splash screen during application startup.
utility
Utility windows which are not detached toolbars or dialogs.
dock
Used for creating dock or panel windows.
desktop
Used for creating the desktop background window.
GdkWindowAttributesType
Used to indicate which fields in the GdkWindowAttr struct should be honored. For example, if you filled in the "cursor" and "x" fields of GdkWindowAttr, pass "GDK.WA.X | GDK.WA.CURSOR" to gdkWindowNew. Fields in GdkWindowAttr not covered by a bit in this enum are required; for example, the width/height, wclass, and window.type fields are required, they have no corresponding flag in GdkWindowAttributesType.
title
Honor the title field
x
Honor the X coordinate field
y
Honor the Y coordinate field
cursor
Honor the cursor field
colormap
Honor the colormap field
visual
Honor the visual field
wmclass
Honor the wmclass_class and wmclass_name fields
noredir
Honor the override_redirect field
GdkFilterReturn
Specifies the result of applying a GdkFilterFunc to a native event.
continue
event not handled, continue processing.
translate
native event translated into a GDK event and stored in the event structure that was passed in.
remove
event handled, terminate processing.
GdkModifierType
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. Like the X Window System, GDK supports 8 modifier keys and 5 mouse buttons. Since 2.10, GDK recognizes which of the Meta, Super or Hyper keys are mapped to Mod2 - Mod5, and indicates this by setting GDK_SUPER_MASK, GDK_HYPER_MASK or GDK_META_MASK in the state field of key events.
shift-mask
the Shift key.
lock-mask
a Lock key (depending on the modifier mapping of the X server this may either be CapsLock or ShiftLock).
control-mask
the Control key.
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).
mod2-mask
the fifth modifier key (it depends on the modifier mapping of the X server which key is interpreted as this modifier).
mod3-mask
the sixth modifier key (it depends on the modifier mapping of the X server which key is interpreted as this modifier).
mod4-mask
the seventh modifier key (it depends on the modifier mapping of the X server which key is interpreted as this modifier).
mod5-mask
the eighth modifier key (it depends on the modifier mapping of the X server which key is interpreted as this modifier).
button1-mask
the first mouse button.
button2-mask
the second mouse button.
button3-mask
the third mouse button.
button4-mask
the fourth mouse button.
button5-mask
the fifth mouse button.
release-mask
the Super modifier. Since 2.10
modifier-mask
the Hyper modifier. Since 2.10
GdkWMDecoration
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.
all
all decorations should be applied.
border
a frame should be drawn around the window.
resizeh
the frame should have resize handles.
title
a titlebar should be placed above the window.
menu
a button for opening a menu should be included.
minimize
a minimize button should be included.
maximize
a maximize button should be included.
GdkWMFunction
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.
all
all functions should be offered.
resize
the window should be resizable.
move
the window should be movable.
minimize
the window should be minimizable.
maximize
the window should be maximizable.
close
the window should be closable.

User Functions

Signals

from-embedder(window, embedder-x, embedder-y, offscreen-x, offscreen-y, user.data)
The ::from-embedder signal is emitted to translate coordinates in the embedder of an offscreen window to the offscreen window. See also "to-embedder". Since 2.18
window
the offscreen window on which the signal is emitted
embedder-x
x coordinate in the embedder window
embedder-y
y coordinate in the embedder window
offscreen-x
return location for the x coordinate in the offscreen window
offscreen-y
return location for the y coordinate in the offscreen window
user.data
user data set when the signal handler was connected.
pick-embedded-child(window, x, y, user.data)
The ::pick-embedded-child signal is emitted to find an embedded child at the given position. Since 2.18
window
the window on which the signal is emitted
x
x coordinate in the window
y
y coordinate in the window
user.data
user data set when the signal handler was connected.
Returns: [GdkWindow] the GdkWindow of the embedded child at x, y, or NULL
to-embedder(window, offscreen-x, offscreen-y, embedder-x, embedder-y, user.data)
The ::to-embedder signal is emitted to translate coordinates in an offscreen window to its embedder. See also "from-embedder". Since 2.18
window
the offscreen window on which the signal is emitted
offscreen-x
x coordinate in the offscreen window
offscreen-y
y coordinate in the offscreen window
embedder-x
return location for the x coordinate in the embedder window
embedder-y
return location for the y coordinate in the embedder window
user.data
user data set when the signal handler was connected.

Properties

References

http://library.gnome.org/devel//gdk/gdk-Windows.html