gdk-Windows: Windows

In RGtk2: R Bindings for Gtk 2.8.0 and Above

Description

Onscreen display areas in the target window system

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

GdkFilterFunc(xevent, event, data)

Specifies the type of function used to filter native events before they are converted to GDK events.

When a filter is called, event is unpopulated, except for event->window. 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 GDK_FILTER_TRANSLATE.

xevent

the native event to filter.

event

the GDK event to which the X event will be translated.

data

user data set when the filter was installed.

Returns: [GdkFilterReturn] a GdkFilterReturn value.

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

cursor [GdkCursor : * : Read / Write]

The mouse pointer for a GdkWindow. See gdkWindowSetCursor and gdkWindowGetCursor for details. Since 2.18

Author(s)

Derived by RGtkGen from GTK+ documentation

References

https://developer.gnome.org/gdk2/stable/gdk2-Windows.html

RGtk2 documentation built on Oct. 14, 2021, 5:08 p.m.