GtkWidget: GtkWidget

Description Methods and Functions Hierarchy Interfaces Interface Derivations Detailed Description Structures Convenient Construction Enums and Flags User Functions Signals Properties Style Properties Author(s) References

Description

Base class for all widgets

Methods and Functions

gtkWidgetNew(type, ..., show = TRUE)
gtkWidgetDestroy(object, ...)
gtkWidgetSet(obj, ...)
gtkWidgetUnparent(object)
gtkWidgetShow(object)
gtkWidgetShowNow(object)
gtkWidgetHide(object)
gtkWidgetShowAll(object)
gtkWidgetHideAll(object)
gtkWidgetMap(object)
gtkWidgetUnmap(object)
gtkWidgetRealize(object)
gtkWidgetUnrealize(object)
gtkWidgetQueueDraw(object)
gtkWidgetQueueResize(object)
gtkWidgetQueueResizeNoRedraw(object)
gtkWidgetDraw(object, area)
gtkWidgetSizeRequest(object)
gtkWidgetGetChildRequisition(object)
gtkWidgetSizeAllocate(object, allocation)
gtkWidgetAddAccelerator(object, accel.signal, accel.group, accel.key, accel.mods, accel.flags)
gtkWidgetRemoveAccelerator(object, accel.group, accel.key, accel.mods)
gtkWidgetSetAccelPath(object, accel.path, accel.group)
gtkWidgetListAccelClosures(object)
gtkWidgetCanActivateAccel(object, signal.id)
gtkWidgetEvent(object, event)
gtkWidgetActivate(object)
gtkWidgetReparent(object, new.parent)
gtkWidgetIntersect(object, area, intersection)
gtkWidgetIsFocus(object)
gtkWidgetGrabFocus(object)
gtkWidgetGrabDefault(object)
gtkWidgetSetName(object, name)
gtkWidgetGetName(object)
gtkWidgetSetState(object, state)
gtkWidgetSetSensitive(object, sensitive)
gtkWidgetSetParent(object, parent)
gtkWidgetSetParentWindow(object, parent.window)
gtkWidgetGetParentWindow(object)
gtkWidgetSetUposition(object, x, y)
gtkWidgetSetUsize(object, width, height)
gtkWidgetSetEvents(object, events)
gtkWidgetAddEvents(object, events)
gtkWidgetSetExtensionEvents(object, mode)
gtkWidgetGetExtensionEvents(object)
gtkWidgetGetToplevel(object)
gtkWidgetGetAncestor(object, widget.type)
gtkWidgetGetColormap(object)
gtkWidgetSetColormap(object, colormap)
gtkWidgetGetVisual(object)
gtkWidgetGetEvents(object)
gtkWidgetGetPointer(object)
gtkWidgetIsAncestor(object, ancestor)
gtkWidgetTranslateCoordinates(object, dest.widget, src.x, src.y)
gtkWidgetHideOnDelete(object)
gtkWidgetSetStyle(object, style = NULL)
gtkWidgetEnsureStyle(object)
gtkWidgetGetStyle(object)
gtkWidgetResetRcStyles(object)
gtkWidgetPushColormap(cmap)
gtkWidgetPopColormap()
gtkWidgetSetDefaultColormap(colormap)
gtkWidgetGetDefaultStyle()
gtkWidgetGetDefaultColormap()
gtkWidgetGetDefaultVisual()
gtkWidgetSetDirection(object, dir)
gtkWidgetGetDirection(object)
gtkWidgetSetDefaultDirection(dir)
gtkWidgetGetDefaultDirection()
gtkWidgetShapeCombineMask(object, shape.mask, offset.x, offset.y)
gtkWidgetInputShapeCombineMask(object, shape.mask = NULL, offset.x, offset.y)
gtkWidgetPath(object)
gtkWidgetClassPath(object)
gtkWidgetGetCompositeName(object)
gtkWidgetModifyStyle(object, style)
gtkWidgetGetModifierStyle(object)
gtkWidgetModifyFg(object, state, color = NULL)
gtkWidgetModifyBg(object, state, color = NULL)
gtkWidgetModifyText(object, state, color = NULL)
gtkWidgetModifyBase(object, state, color = NULL)
gtkWidgetModifyFont(object, font.desc = NULL)
gtkWidgetModifyCursor(object, primary, secondary)
gtkWidgetCreatePangoContext(object)
gtkWidgetGetPangoContext(object)
gtkWidgetCreatePangoLayout(object, text)
gtkWidgetRenderIcon(object, stock.id, size, detail = NULL)
gtkWidgetPopCompositeChild()
gtkWidgetPushCompositeChild()
gtkWidgetQueueClear(object)
gtkWidgetQueueClearArea(object, x, y, width, height)
gtkWidgetQueueDrawArea(object, x, y, width, height)
gtkWidgetResetShapes(object)
gtkWidgetSetAppPaintable(object, app.paintable)
gtkWidgetSetDoubleBuffered(object, double.buffered)
gtkWidgetSetRedrawOnAllocate(object, redraw.on.allocate)
gtkWidgetSetCompositeName(object, name)
gtkWidgetSetScrollAdjustments(object, hadjustment = NULL, vadjustment = NULL)
gtkWidgetMnemonicActivate(object, group.cycling)
gtkWidgetClassInstallStyleProperty(klass, pspec)
gtkWidgetClassInstallStylePropertyParser(klass, pspec, parser)
gtkWidgetClassFindStyleProperty(klass, property.name)
gtkWidgetClassListStyleProperties(klass)
gtkWidgetRegionIntersect(object, region)
gtkWidgetSendExpose(object, event)
gtkWidgetStyleGet(object, ...)
gtkWidgetStyleGetProperty(object, property.name)
gtkWidgetStyleAttach(object)
gtkWidgetGetAccessible(object)
gtkWidgetChildFocus(object, direction)
gtkWidgetChildNotify(object, child.property)
gtkWidgetFreezeChildNotify(object)
gtkWidgetGetChildVisible(object)
gtkWidgetGetParent(object)
gtkWidgetGetSettings(object)
gtkWidgetGetClipboard(object, selection)
gtkWidgetGetDisplay(object)
gtkWidgetGetRootWindow(object)
gtkWidgetGetScreen(object)
gtkWidgetHasScreen(object)
gtkWidgetGetSizeRequest(object)
gtkWidgetSetChildVisible(object, is.visible)
gtkWidgetSetSizeRequest(object, width, height)
gtkWidgetThawChildNotify(object)
gtkWidgetSetNoShowAll(object, no.show.all)
gtkWidgetGetNoShowAll(object)
gtkWidgetListMnemonicLabels(object)
gtkWidgetAddMnemonicLabel(object, label)
gtkWidgetRemoveMnemonicLabel(object, label)
gtkWidgetGetAction(object)
gtkWidgetGetAction(object)
gtkWidgetIsComposited(object)
gtkWidgetErrorBell(object)
gtkWidgetKeynavFailed(object, direction)
gtkWidgetGetTooltipMarkup(object)
gtkWidgetSetTooltipMarkup(object, markup)
gtkWidgetGetTooltipText(object)
gtkWidgetSetTooltipText(object, text)
gtkWidgetGetTooltipWindow(object)
gtkWidgetSetTooltipWindow(object, custom.window)
gtkWidgetGetHasTooltip(object)
gtkWidgetSetHasTooltip(object, has.tooltip)
gtkWidgetTriggerTooltipQuery(object)
gtkWidgetGetSnapshot(object, clip.rect = NULL)
gtkWidgetGetWindow(object)
gtkWidgetGetAllocation(object)
gtkWidgetSetAllocation(object, allocation)
gtkWidgetGetAppPaintable(object)
gtkWidgetGetCanDefault(object)
gtkWidgetSetCanDefault(object, can.default)
gtkWidgetGetCanFocus(object)
gtkWidgetSetCanFocus(object, can.focus)
gtkWidgetGetDoubleBuffered(object)
gtkWidgetGetHasWindow(object)
gtkWidgetSetHasWindow(object, has.window)
gtkWidgetGetSensitive(object)
gtkWidgetIsSensitive(object)
gtkWidgetGetState(object)
gtkWidgetGetVisible(object)
gtkWidgetSetVisible(object, visible)
gtkWidgetHasDefault(object)
gtkWidgetHasFocus(object)
gtkWidgetHasGrab(object)
gtkWidgetHasRcStyle(object)
gtkWidgetIsDrawable(object)
gtkWidgetIsToplevel(object)
gtkWidgetSetWindow(object, window)
gtkWidgetSetReceivesDefault(object, receives.default)
gtkWidgetGetReceivesDefault(object)
gtkWidgetSetRealized(object, realized)
gtkWidgetGetRealized(object)
gtkWidgetSetMapped(object, mapped)
gtkWidgetGetMapped(object)
gtkWidgetGetRequisition(object)
gtkRequisitionCopy(object)
gtkWidget(type, ..., show = TRUE)

Hierarchy

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
GObject
   +----GInitiallyUnowned
         +----GtkObject
               +----GtkWidget
                     +----GtkContainer
                     +----GtkMisc
                     +----GtkCalendar
                     +----GtkCellView
                     +----GtkDrawingArea
                     +----GtkEntry
                     +----GtkRuler
                     +----GtkRange
                     +----GtkSeparator
                     +----GtkHSV
                     +----GtkInvisible
                     +----GtkOldEditable
                     +----GtkPreview
                     +----GtkProgress
GBoxed
   +----GtkRequisition
GBoxed
   +----GtkSelectionData

Interfaces

GtkWidget implements AtkImplementorIface and GtkBuildable.

Interface Derivations

GtkWidget is required by GtkCellEditable, GtkFileChooser and GtkToolShell.

Detailed Description

GtkWidget is the base class all widgets in GTK+ derive from. It manages the widget lifecycle, states and style. GtkWidget introduces style properties - these are basically object properties that are stored not on the object, but in the style object associated to the widget. Style properties are set in resource files. This mechanism is used for configuring such things as the location of the scrollbar arrows through the theme, giving theme authors more control over the look of applications without the need to write a theme engine in C.

Use gtkWidgetClassInstallStyleProperty to install style properties for a widget class, gtkWidgetClassFindStyleProperty or gtkWidgetClassListStyleProperties to get information about existing style properties and gtkWidgetStyleGetProperty, gtkWidgetStyleGet or gtkWidgetStyleGetValist() to obtain the value of a style property.

GtkWidget as GtkBuildable The GtkWidget implementation of the GtkBuildable interface supports a custom <accelerator> element, which has attributes named key, modifiers and signal and allows to specify accelerators.

A UI definition fragment specifying an accelerator

1
2
3
<object class="GtkButton">
  <accelerator key="q" modifiers="GDK_CONTROL_MASK" signal="clicked"/>
</object>

In addition to accelerators, GtkWidget also support a custom <accessible> element, which supports actions and relations. Properties on the accessible implementation of an object can be set by accessing the internal child "accessible" of a GtkWidget.

A UI definition fragment specifying an accessible

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
<object class="GtkButton" id="label1"/>
  <property name="label">I am a Label for a Button</property>
</object>
<object class="GtkButton" id="button1">
  <accessibility>
    <action action_name="click" translatable="yes">Click the button.</action>
    <relation target="label1" type="labelled-by"/>
  </accessibility>
  <child internal-child="accessible">
    <object class="AtkObject" id="a11y-button1">
      <property name="AtkObject::name">Clickable Button</property>
    </object>
  </child>
</object>

Structures

GtkWidget

undocumented

style

[GtkStyle]

requisition

[GtkRequisition]

allocation

[GtkAllocation]

window

[GdkWindow]

parent

[GtkWidget]

GtkWidgetClass

activate_signal The signal to emit when a widget of this class is activated, gtkWidgetActivate handles the emission. Implementation of this signal is optional. set_scroll_adjustment_signal This signal is emitted when a widget of this class is added to a scrolling aware parent, gtkWidgetSetScrollAdjustments handles the emission. Implementation of this signal is optional.

GtkRequisition

A GtkRequisition represents the desired size of a widget. See for more information.

width

[integer] the widget's desired width

height

[integer] the widget's desired height

GtkAllocation

A GtkAllocation of a widget represents region which has been allocated to the widget by its parent. It is a subregion of its parents allocation. See for more information. GtkAllocation is a transparent-type.

x

the X position of the widget's area relative to its parents allocation.

y

the Y position of the widget's area relative to its parents allocation.

width

the width of the widget's allocated area.

height

the height of the widget's allocated area.

GtkSelectionData

undocumented

selection

[GdkAtom]

target

[GdkAtom]

type

[GdkAtom]

format

[integer]

data

[raw]

Convenient Construction

gtkWidget is the equivalent of gtkWidgetNew.

Enums and Flags

GtkWidgetFlags

Tells about certain properties of the widget.

toplevel

widgets without a real parent, as there are GtkWindows and GtkMenus have this flag set throughout their lifetime. Toplevel widgets always contain their own GdkWindow.

no-window

Indicative for a widget that does not provide its own GdkWindow. Visible action (e.g. drawing) is performed on the parent's GdkWindow.

realized

Set by gtkWidgetRealize, unset by gtkWidgetUnrealize. A realized widget has an associated GdkWindow.

mapped

Set by gtkWidgetMap, unset by gtkWidgetUnmap. Only realized widgets can be mapped. It means that gdkWindowShow has been called on the widgets window(s).

visible

Set by gtkWidgetShow, unset by gtkWidgetHide. Implies that a widget will be mapped as soon as its parent is mapped.

sensitive

Set and unset by gtkWidgetSetSensitive. The sensitivity of a widget determines whether it will receive certain events (e.g. button or key presses). One premise for the widget's sensitivity is to have this flag set.

parent-sensitive

Set and unset by gtkWidgetSetSensitive operations on the parents of the widget. This is the second premise for the widget's sensitivity. Once it has GTK_SENSITIVE and GTK_PARENT_SENSITIVE set, its state is effectively sensitive. This is expressed (and can be examined) by the GTK_WIDGET_IS_SENSITIVE function.

can-focus

Determines whether a widget is able to handle focus grabs.

has-focus

Set by gtkWidgetGrabFocus for widgets that also have GTK_CAN_FOCUS set. The flag will be unset once another widget grabs the focus.

can-default

The widget is allowed to receive the default action via gtkWidgetGrabDefault and will reserve space to draw the default if possible

has-default

The widget currently is receiving the default action and should be drawn appropriately if possible

has-grab

Set by gtkGrabAdd, unset by gtkGrabRemove. It means that the widget is in the grab_widgets stack, and will be the preferred one for receiving events other than ones of cosmetic value.

rc-style

Indicates that the widget's style has been looked up through the rc mechanism. It does not imply that the widget actually had a style defined through the rc mechanism.

composite-child

Indicates that the widget is a composite child of its parent; see gtkWidgetPushCompositeChild, gtkWidgetPopCompositeChild.

no-reparent

Unused since before GTK+ 1.2, will be removed in a future version.

app-paintable

Set and unset by gtkWidgetSetAppPaintable. Must be set on widgets whose window the application directly draws on, in order to keep GTK+ from overwriting the drawn stuff. See for a detailed description of this flag.

receives-default

The widget when focused will receive the default action and have GTK_HAS_DEFAULT set even if there is a different widget set as default.

double-buffered

Set and unset by gtkWidgetSetDoubleBuffered. Indicates that exposes done on the widget should be double-buffered. See for a detailed discussion of how double-buffering works in GTK+ and why you may want to disable it for special cases.

no-show-all

undocumented

GtkWidgetHelpType

undocumented

tooltip

undocumented

whats-this

undocumented

GtkTextDirection

undocumented

none

undocumented

ltr

undocumented

rtl

undocumented

User Functions

GtkCallback(widget, data)

The type of the callback functions used for e.g. iterating over the children of a container, see gtkContainerForeach.

widget

the widget to operate on

data

user-supplied data

Signals

accel-closures-changed(widget, user.data)

undocumented

widget

the object which received the signal.

user.data

user data set when the signal handler was connected.

button-press-event(widget, event, user.data)

The ::button-press-event signal will be emitted when a button (typically from a mouse) is pressed.

To receive this signal, the GdkWindow associated to the widget needs to enable the GDK_BUTTON_PRESS_MASK mask.

This signal will be sent to the grab widget if there is one.

widget

the object which received the signal.

event

the GdkEventButton which triggered this signal

user.data

user data set when the signal handler was connected.

Returns: [logical] TRUE to stop other handlers from being invoked for the event. FALSE to propagate the event further.

button-release-event(widget, event, user.data)

The ::button-release-event signal will be emitted when a button (typically from a mouse) is released.

To receive this signal, the GdkWindow associated to the widget needs to enable the GDK_BUTTON_RELEASE_MASK mask.

This signal will be sent to the grab widget if there is one.

widget

the object which received the signal.

event

the GdkEventButton which triggered this signal

user.data

user data set when the signal handler was connected.

Returns: [logical] TRUE to stop other handlers from being invoked for the event. FALSE to propagate the event further.

can-activate-accel(widget, signal.id, user.data)

Determines whether an accelerator that activates the signal identified by signal.id can currently be activated. This signal is present to allow applications and derived widgets to override the default GtkWidget handling for determining whether an accelerator can be activated.

widget

the object which received the signal

signal.id

the ID of a signal installed on widget

user.data

user data set when the signal handler was connected.

Returns: [logical] TRUE if the signal can be activated.

child-notify(widget, pspec, user.data)

The ::child-notify signal is emitted for each child property that has changed on an object. The signal's detail holds the property name.

widget

the object which received the signal

pspec

the GParamSpec of the changed child property

user.data

user data set when the signal handler was connected.

client-event(widget, event, user.data)

The ::client-event will be emitted when the widget's window receives a message (via a ClientMessage event) from another application.

widget

the object which received the signal

event

the GdkEventClient which triggered this signal

user.data

user data set when the signal handler was connected.

Returns: [logical] TRUE to stop other handlers from being invoked for the event. FALSE to propagate the event further.

composited-changed(widget, user.data)

The ::composited-changed signal is emitted when the composited status of widgets screen changes. See gdkScreenIsComposited.

widget

the object on which the signal is emitted

user.data

user data set when the signal handler was connected.

configure-event(widget, event, user.data)

The ::configure-event signal will be emitted when the size, position or stacking of the widget's window has changed.

To receive this signal, the GdkWindow associated to the widget needs to enable the GDK_STRUCTURE_MASK mask. GDK will enable this mask automatically for all new windows.

widget

the object which received the signal

event

the GdkEventConfigure which triggered this signal

user.data

user data set when the signal handler was connected.

Returns: [logical] TRUE to stop other handlers from being invoked for the event. FALSE to propagate the event further.

damage-event(widget, event, user.data)

Emitted when a redirected window belonging to widget gets drawn into. The region/area members of the event shows what area of the redirected drawable was drawn into. Since 2.14

widget

the object which received the signal

event

the GdkEventExpose event

user.data

user data set when the signal handler was connected.

Returns: [logical] TRUE to stop other handlers from being invoked for the event. FALSE to propagate the event further.

delete-event(widget, event, user.data)

The ::delete-event signal is emitted if a user requests that a toplevel window is closed. The default handler for this signal destroys the window. Connecting gtkWidgetHideOnDelete to this signal will cause the window to be hidden instead, so that it can later be shown again without reconstructing it.

widget

the object which received the signal

event

the event which triggered this signal

user.data

user data set when the signal handler was connected.

Returns: [logical] TRUE to stop other handlers from being invoked for the event. FALSE to propagate the event further.

destroy-event(widget, event, user.data)

The ::destroy-event signal is emitted when a GdkWindow is destroyed. You rarely get this signal, because most widgets disconnect themselves from their window before they destroy it, so no widget owns the window at destroy time.

To receive this signal, the GdkWindow associated to the widget needs to enable the GDK_STRUCTURE_MASK mask. GDK will enable this mask automatically for all new windows.

widget

the object which received the signal.

event

the event which triggered this signal

user.data

user data set when the signal handler was connected.

Returns: [logical] TRUE to stop other handlers from being invoked for the event. FALSE to propagate the event further.

direction-changed(widget, previous.direction, user.data)

The ::direction-changed signal is emitted when the text direction of a widget changes.

widget

the object on which the signal is emitted

previous.direction

the previous text direction of widget

user.data

user data set when the signal handler was connected.

drag-begin(widget, drag.context, user.data)

The ::drag-begin signal is emitted on the drag source when a drag is started. A typical reason to connect to this signal is to set up a custom drag icon with gtkDragSourceSetIcon.

Note that some widgets set up a drag icon in the default handler of this signal, so you may have to use gSignalConnectAfter() to override what the default handler did.

widget

the object which received the signal

drag.context

the drag context

user.data

user data set when the signal handler was connected.

drag-data-delete(widget, drag.context, user.data)

The ::drag-data-delete signal is emitted on the drag source when a drag with the action GDK_ACTION_MOVE is successfully completed. The signal handler is responsible for deleting the data that has been dropped. What "delete" means depends on the context of the drag operation.

widget

the object which received the signal

drag.context

the drag context

user.data

user data set when the signal handler was connected.

drag-data-get(widget, drag.context, data, info, time, user.data)

The ::drag-data-get signal is emitted on the drag source when the drop site requests the data which is dragged. It is the responsibility of the signal handler to fill data with the data in the format which is indicated by info. See gtkSelectionDataSet and gtkSelectionDataSetText.

widget

the object which received the signal

drag.context

the drag context

data

the GtkSelectionData to be filled with the dragged data

info

the info that has been registered with the target in the GtkTargetList

time

the timestamp at which the data was requested

user.data

user data set when the signal handler was connected.

drag-data-received(widget, drag.context, x, y, data, info, time, user.data)

The ::drag-data-received signal is emitted on the drop site when the dragged data has been received. If the data was received in order to determine whether the drop will be accepted, the handler is expected to call gdkDragStatus and not finish the drag. If the data was received in response to a "drag-drop" signal (and this is the last target to be received), the handler for this signal is expected to process the received data and then call gtkDragFinish, setting the success parameter depending on whether the data was processed successfully.

The handler may inspect and modify drag.context->action before calling gtkDragFinish, e.g. to implement GDK_ACTION_ASK as shown in the following example:

drag_data_received <- function(widget, drag_context, x, y, data, info, time)
{
  if (data$getLength() > 0L)
    {
      if (drag_context$getAction() == "ask")
        {
          dialog <- gtkMessageDialog(NULL,
                                     c("modal", "destroy-with-parent"),
                                     "info", "yes-no", "Move the data ?\n")
          response <- dialog$run()
          dialog$destroy()

### FIXME: setAction() not yet supported
          if (response == GtkResponseType["yes"])
            drag_context$setAction("move")
          else
            drag_context$setAction("copy")
        }

      gtkDragFinish(drag_context, TRUE, FALSE, time)
    }

  gtkDragFinish (drag_context, FALSE, FALSE, time)
}
widget

the object which received the signal

drag.context

the drag context

x

where the drop happened

y

where the drop happened

data

the received data

info

the info that has been registered with the target in the GtkTargetList

time

the timestamp at which the data was received

user.data

user data set when the signal handler was connected.

drag-drop(widget, drag.context, x, y, time, returns, user.data)

The ::drag-drop signal is emitted on the drop site when the user drops the data onto the widget. The signal handler must determine whether the cursor position is in a drop zone or not. If it is not in a drop zone, it returns FALSE and no further processing is necessary. Otherwise, the handler returns TRUE. In this case, the handler must ensure that gtkDragFinish is called to let the source know that the drop is done. The call to gtkDragFinish can be done either directly or in a "drag-data-received" handler which gets triggered by calling gtkDragGetData to receive the data for one or more of the supported targets.

widget

the object which received the signal

drag.context

the drag context

x

the x coordinate of the current cursor position

y

the y coordinate of the current cursor position

time

the timestamp of the motion event

returns

whether the cursor position is in a drop zone

user.data

user data set when the signal handler was connected.

drag-end(widget, drag.context, user.data)

The ::drag-end signal is emitted on the drag source when a drag is finished. A typical reason to connect to this signal is to undo things done in "drag-begin".

widget

the object which received the signal

drag.context

the drag context

user.data

user data set when the signal handler was connected.

drag-failed(widget, drag.context, result, user.data)

The ::drag-failed signal is emitted on the drag source when a drag has failed. The signal handler may hook custom code to handle a failed DND operation based on the type of error, it returns TRUE is the failure has been already handled (not showing the default "drag operation failed" animation), otherwise it returns FALSE. Since 2.12

widget

the object which received the signal

drag.context

the drag context

result

the result of the drag operation

user.data

user data set when the signal handler was connected.

Returns: [logical] TRUE if the failed drag operation has been already handled.

drag-leave(widget, drag.context, time, user.data)

The ::drag-leave signal is emitted on the drop site when the cursor leaves the widget. A typical reason to connect to this signal is to undo things done in "drag-motion", e.g. undo highlighting with gtkDragUnhighlight

widget

the object which received the signal.

drag.context

the drag context

time

the timestamp of the motion event

user.data

user data set when the signal handler was connected.

drag-motion(widget, drag.context, x, y, time, returns, user.data)

The drag-motion signal is emitted on the drop site when the user moves the cursor over the widget during a drag. The signal handler must determine whether the cursor position is in a drop zone or not. If it is not in a drop zone, it returns FALSE and no further processing is necessary. Otherwise, the handler returns TRUE. In this case, the handler is responsible for providing the necessary information for displaying feedback to the user, by calling gdkDragStatus.

If the decision whether the drop will be accepted or rejected can't be made based solely on the cursor position and the type of the data, the handler may inspect the dragged data by calling gtkDragGetData and defer the gdkDragStatus call to the "drag-data-received" handler. Note that you cannot not pass GTK_DEST_DEFAULT_DROP, GTK_DEST_DEFAULT_MOTION or GTK_DEST_DEFAULT_ALL to gtkDragDestSet when using the drag-motion signal that way.

Also note that there is no drag-enter signal. The drag receiver has to keep track of whether he has received any drag-motion signals since the last "drag-leave" and if not, treat the drag-motion signal as an "enter" signal. Upon an "enter", the handler will typically highlight the drop site with gtkDragHighlight.

drag_motion <- function(widget, context, x, y, time)
{
  state <- widget$getData("drag-state")
  
  if (!state$drag_highlight) {
    state$drag_highlight <- T
    gtkDragHighlight(widget)
  }
  
  target <- gtkDragDestFindTarget(widget, context, NULL)
  if (target == 0)
    gdkDragStatus(context, 0, time)
  else {
    state$pending_status <- context[["suggestedAction"]]
    gtkDragGetData(widget, context, target, time)
  }
  
  widget$setData("drag-state", state)
  
  return(TRUE)
}

drag_data_received <- function(widget, context, x, y, selection_data, info,
                               time)
{
  state <- widget$getData("drag-state")
  
  if (state$pending_status) { 
    ## We are getting this data due to a request in drag_motion,
    ## rather than due to a request in drag_drop, so we are just
    ## supposed to call gdk_drag_status(), not actually paste in the data.

    str <- gtkSelectionDataGetText(selection_data)
    if (!data_is_acceptable (str)) 
      gdkDragStatus(context, 0, time)
    else
      gdkDragStatus(context, state$pending_status, time)
    
    state$pending_status <- 0
  }
  else {
    ## accept the drop
  }
  
  widget$setData("drag-state", state)
}
widget

the object which received the signal

drag.context

the drag context

x

the x coordinate of the current cursor position

y

the y coordinate of the current cursor position

time

the timestamp of the motion event

returns

whether the cursor position is in a drop zone

user.data

user data set when the signal handler was connected.

enter-notify-event(widget, event, user.data)

The ::enter-notify-event will be emitted when the pointer enters the widget's window.

To receive this signal, the GdkWindow associated to the widget needs to enable the GDK_ENTER_NOTIFY_MASK mask.

This signal will be sent to the grab widget if there is one.

widget

the object which received the signal

event

the GdkEventCrossing which triggered this signal

user.data

user data set when the signal handler was connected.

Returns: [logical] TRUE to stop other handlers from being invoked for the event. FALSE to propagate the event further.

event(widget, event, user.data)

The GTK+ main loop will emit three signals for each GDK event delivered to a widget: one generic ::event signal, another, more specific, signal that matches the type of event delivered (e.g. "key-press-event") and finally a generic "event-after" signal.

widget

the object which received the signal.

event

the GdkEvent which triggered this signal

user.data

user data set when the signal handler was connected.

Returns: [logical] TRUE to stop other handlers from being invoked for the event and to cancel the emission of the second specific ::event signal. FALSE to propagate the event further and to allow the emission of the second signal. The ::event-after signal is emitted regardless of the return value.

event-after(widget, event, user.data)

After the emission of the gtkWidgetEvent signal and (optionally) the second more specific signal, ::event-after will be emitted regardless of the previous two signals handlers return values.

widget

the object which received the signal.

event

the GdkEvent which triggered this signal

user.data

user data set when the signal handler was connected.

expose-event(widget, event, user.data)

The ::expose-event signal is emitted when an area of a previously obscured GdkWindow is made visible and needs to be redrawn. GTK_NO_WINDOW widgets will get a synthesized event from their parent widget.

To receive this signal, the GdkWindow associated to the widget needs to enable the GDK_EXPOSURE_MASK mask.

widget

the object which received the signal.

event

the GdkEventExpose which triggered this signal

user.data

user data set when the signal handler was connected.

Returns: [logical] TRUE to stop other handlers from being invoked for the event. FALSE to propagate the event further.

focus(widget, user.data)

undocumented

widget

the object which received the signal.

user.data

user data set when the signal handler was connected.

Returns: [logical] TRUE to stop other handlers from being invoked for the event. FALSE to propagate the event further.

focus-in-event(widget, event, user.data)

The ::focus-in-event signal will be emitted when the keyboard focus enters the widget's window.

To receive this signal, the GdkWindow associated to the widget needs to enable the GDK_FOCUS_CHANGE_MASK mask.

widget

the object which received the signal

event

the GdkEventFocus which triggered this signal

user.data

user data set when the signal handler was connected.

Returns: [logical] TRUE to stop other handlers from being invoked for the event. FALSE to propagate the event further.

focus-out-event(widget, event, user.data)

The ::focus-out-event signal will be emitted when the keyboard focus leaves the widget's window.

To receive this signal, the GdkWindow associated to the widget needs to enable the GDK_FOCUS_CHANGE_MASK mask.

widget

the object which received the signal

event

the GdkEventFocus which triggered this signal

user.data

user data set when the signal handler was connected.

Returns: [logical] TRUE to stop other handlers from being invoked for the event. FALSE to propagate the event further.

grab-broken-event(widget, event, user.data)

Emitted when a pointer or keyboard grab on a window belonging to widget gets broken.

On X11, this happens when the grab window becomes unviewable (i.e. it or one of its ancestors is unmapped), or if the same application grabs the pointer or keyboard again. Since 2.8

widget

the object which received the signal

event

the GdkEventGrabBroken event

user.data

user data set when the signal handler was connected.

Returns: [logical] TRUE to stop other handlers from being invoked for the event. FALSE to propagate the event further.

grab-focus(widget, user.data)

undocumented

widget

the object which received the signal.

user.data

user data set when the signal handler was connected.

grab-notify(widget, was.grabbed, user.data)

The ::grab-notify signal is emitted when a widget becomes shadowed by a GTK+ grab (not a pointer or keyboard grab) on another widget, or when it becomes unshadowed due to a grab being removed.

A widget is shadowed by a gtkGrabAdd when the topmost grab widget in the grab stack of its window group is not its ancestor.

widget

the object which received the signal

was.grabbed

FALSE if the widget becomes shadowed, TRUE if it becomes unshadowed

user.data

user data set when the signal handler was connected.

hide(widget, user.data)

undocumented

widget

the object which received the signal.

user.data

user data set when the signal handler was connected.

hierarchy-changed(widget, previous.toplevel, user.data)

The ::hierarchy-changed signal is emitted when the anchored state of a widget changes. A widget is anchored when its toplevel ancestor is a GtkWindow. This signal is emitted when a widget changes from un-anchored to anchored or vice-versa.

widget

the object on which the signal is emitted

previous.toplevel

the previous toplevel ancestor, or NULL if the widget was previously unanchored. [ allow-none ]

user.data

user data set when the signal handler was connected.

key-press-event(widget, event, user.data)

The ::key-press-event signal is emitted when a key is pressed.

To receive this signal, the GdkWindow associated to the widget needs to enable the GDK_KEY_PRESS_MASK mask.

This signal will be sent to the grab widget if there is one.

widget

the object which received the signal

event

the GdkEventKey which triggered this signal

user.data

user data set when the signal handler was connected.

Returns: [logical] TRUE to stop other handlers from being invoked for the event. FALSE to propagate the event further.

key-release-event(widget, event, user.data)

The ::key-release-event signal is emitted when a key is pressed.

To receive this signal, the GdkWindow associated to the widget needs to enable the GDK_KEY_RELEASE_MASK mask.

This signal will be sent to the grab widget if there is one.

widget

the object which received the signal

event

the GdkEventKey which triggered this signal

user.data

user data set when the signal handler was connected.

Returns: [logical] TRUE to stop other handlers from being invoked for the event. FALSE to propagate the event further.

keynav-failed(widget, direction, user.data)

Gets emitted if keyboard navigation fails. See gtkWidgetKeynavFailed for details. Since 2.12

widget

the object which received the signal

direction

the direction of movement

user.data

user data set when the signal handler was connected.

Returns: [logical] TRUE if stopping keyboard navigation is fine, FALSE if the emitting widget should try to handle the keyboard navigation attempt in its parent container(s).

leave-notify-event(widget, event, user.data)

The ::leave-notify-event will be emitted when the pointer leaves the widget's window.

To receive this signal, the GdkWindow associated to the widget needs to enable the GDK_LEAVE_NOTIFY_MASK mask.

This signal will be sent to the grab widget if there is one.

widget

the object which received the signal

event

the GdkEventCrossing which triggered this signal

user.data

user data set when the signal handler was connected.

Returns: [logical] TRUE to stop other handlers from being invoked for the event. FALSE to propagate the event further.

map(widget, user.data)

undocumented

widget

the object which received the signal.

user.data

user data set when the signal handler was connected.

map-event(widget, event, user.data)

The ::map-event signal will be emitted when the widget's window is mapped. A window is mapped when it becomes visible on the screen.

To receive this signal, the GdkWindow associated to the widget needs to enable the GDK_STRUCTURE_MASK mask. GDK will enable this mask automatically for all new windows.

widget

the object which received the signal

event

the GdkEventAny which triggered this signal

user.data

user data set when the signal handler was connected.

Returns: [logical] TRUE to stop other handlers from being invoked for the event. FALSE to propagate the event further.

mnemonic-activate(widget, user.data)

undocumented

widget

the object which received the signal.

user.data

user data set when the signal handler was connected.

motion-notify-event(widget, event, user.data)

The ::motion-notify-event signal is emitted when the pointer moves over the widget's GdkWindow.

To receive this signal, the GdkWindow associated to the widget needs to enable the GDK_POINTER_MOTION_MASK mask.

This signal will be sent to the grab widget if there is one.

widget

the object which received the signal.

event

the GdkEventMotion which triggered this signal

user.data

user data set when the signal handler was connected.

Returns: [logical] TRUE to stop other handlers from being invoked for the event. FALSE to propagate the event further.

move-focus(widget, user.data)

undocumented

widget

the object which received the signal.

user.data

user data set when the signal handler was connected.

no-expose-event(widget, event, user.data)

The ::no-expose-event will be emitted when the widget's window is drawn as a copy of another GdkDrawable (with gdkDrawDrawable or gdkWindowCopyArea()) which was completely unobscured. If the source window was partially obscured GdkEventExpose events will be generated for those areas.

widget

the object which received the signal

event

the GdkEventNoExpose which triggered this signal

user.data

user data set when the signal handler was connected.

Returns: [logical] TRUE to stop other handlers from being invoked for the event. FALSE to propagate the event further.

parent-set(widget, old.parent, user.data)

The ::parent-set signal is emitted when a new parent has been set on a widget.

widget

the object on which the signal is emitted

old.parent

the previous parent, or NULL if the widget just got its initial parent. [ allow-none ]

user.data

user data set when the signal handler was connected.

popup-menu(widget, user.data)

This signal gets emitted whenever a widget should pop up a context menu. This usually happens through the standard key binding mechanism; by pressing a certain key while a widget is focused, the user can cause the widget to pop up a menu. For example, the GtkEntry widget creates a menu with clipboard commands. See for an example of how to use this signal.

widget

the object which received the signal

user.data

user data set when the signal handler was connected.

Returns: [logical] TRUE if a menu was activated

property-notify-event(widget, event, user.data)

The ::property-notify-event signal will be emitted when a property on the widget's window has been changed or deleted.

To receive this signal, the GdkWindow associated to the widget needs to enable the GDK_PROPERTY_CHANGE_MASK mask.

widget

the object which received the signal

event

the GdkEventProperty which triggered this signal

user.data

user data set when the signal handler was connected.

Returns: [logical] TRUE to stop other handlers from being invoked for the event. FALSE to propagate the event further.

proximity-in-event(widget, event, user.data)

To receive this signal the GdkWindow associated to the widget needs to enable the GDK_PROXIMITY_IN_MASK mask.

This signal will be sent to the grab widget if there is one.

widget

the object which received the signal

event

the GdkEventProximity which triggered this signal

user.data

user data set when the signal handler was connected.

Returns: [logical] TRUE to stop other handlers from being invoked for the event. FALSE to propagate the event further.

proximity-out-event(widget, event, user.data)

To receive this signal the GdkWindow associated to the widget needs to enable the GDK_PROXIMITY_OUT_MASK mask.

This signal will be sent to the grab widget if there is one.

widget

the object which received the signal

event

the GdkEventProximity which triggered this signal

user.data

user data set when the signal handler was connected.

Returns: [logical] TRUE to stop other handlers from being invoked for the event. FALSE to propagate the event further.

query-tooltip(widget, x, y, keyboard.mode, tooltip, user.data)

Emitted when "has-tooltip" is TRUE and the "gtk-tooltip-timeout" has expired with the cursor hovering "above" widget; or emitted when widget got focus in keyboard mode.

Using the given coordinates, the signal handler should determine whether a tooltip should be shown for widget. If this is the case TRUE should be returned, FALSE otherwise. Note that if keyboard.mode is TRUE, the values of x and y are undefined and should not be used.

The signal handler is free to manipulate tooltip with the therefore destined function calls. Since 2.12

widget

the object which received the signal

x

the x coordinate of the cursor position where the request has been emitted, relative to widget->window

y

the y coordinate of the cursor position where the request has been emitted, relative to widget->window

keyboard.mode

TRUE if the tooltip was trigged using the keyboard

tooltip

a GtkTooltip

user.data

user data set when the signal handler was connected.

Returns: [logical] TRUE if tooltip should be shown right now, FALSE otherwise.

realize(widget, user.data)

undocumented

widget

the object which received the signal.

user.data

user data set when the signal handler was connected.

screen-changed(widget, previous.screen, user.data)

The ::screen-changed signal gets emitted when the screen of a widget has changed.

widget

the object on which the signal is emitted

previous.screen

the previous screen, or NULL if the widget was not associated with a screen before. [ allow-none ]

user.data

user data set when the signal handler was connected.

scroll-event(widget, event, user.data)

The ::scroll-event signal is emitted when a button in the 4 to 7 range is pressed. Wheel mice are usually configured to generate button press events for buttons 4 and 5 when the wheel is turned.

To receive this signal, the GdkWindow associated to the widget needs to enable the GDK_BUTTON_PRESS_MASK mask.

This signal will be sent to the grab widget if there is one.

widget

the object which received the signal.

event

the GdkEventScroll which triggered this signal

user.data

user data set when the signal handler was connected.

Returns: [logical] TRUE to stop other handlers from being invoked for the event. FALSE to propagate the event further.

selection-clear-event(widget, event, user.data)

The ::selection-clear-event signal will be emitted when the the widget's window has lost ownership of a selection.

widget

the object which received the signal

event

the GdkEventSelection which triggered this signal

user.data

user data set when the signal handler was connected.

Returns: [logical] TRUE to stop other handlers from being invoked for the event. FALSE to propagate the event further.

selection-get(widget, user.data)

undocumented

widget

the object which received the signal.

user.data

user data set when the signal handler was connected.

selection-notify-event(widget, user.data)

undocumented

widget

the object which received the signal.

user.data

user data set when the signal handler was connected.

Returns: [logical] TRUE to stop other handlers from being invoked for the event. FALSE to propagate the event further.

selection-received(widget, user.data)

undocumented

widget

the object which received the signal.

user.data

user data set when the signal handler was connected.

selection-request-event(widget, event, user.data)

The ::selection-request-event signal will be emitted when another client requests ownership of the selection owned by the widget's window.

widget

the object which received the signal

event

the GdkEventSelection which triggered this signal

user.data

user data set when the signal handler was connected.

Returns: [logical] TRUE to stop other handlers from being invoked for the event. FALSE to propagate the event further.

show(widget, user.data)

undocumented

widget

the object which received the signal.

user.data

user data set when the signal handler was connected.

show-help(widget, user.data)

undocumented

widget

the object which received the signal.

user.data

user data set when the signal handler was connected.

size-allocate(widget, user.data)

undocumented

widget

the object which received the signal.

user.data

user data set when the signal handler was connected.

size-request(widget, user.data)

undocumented

widget

the object which received the signal.

user.data

user data set when the signal handler was connected.

state-changed(widget, state, user.data)

The ::state-changed signal is emitted when the widget state changes. See gtkWidgetGetState.

widget

the object which received the signal.

state

the previous state

user.data

user data set when the signal handler was connected.

style-set(widget, previous.style, user.data)

The ::style-set signal is emitted when a new style has been set on a widget. Note that style-modifying functions like gtkWidgetModifyBase also cause this signal to be emitted.

widget

the object on which the signal is emitted

previous.style

the previous style, or NULL if the widget just got its initial style. [ allow-none ]

user.data

user data set when the signal handler was connected.

unmap(widget, user.data)

undocumented

widget

the object which received the signal.

user.data

user data set when the signal handler was connected.

unmap-event(widget, event, user.data)

The ::unmap-event signal will be emitted when the widget's window is unmapped. A window is unmapped when it becomes invisible on the screen.

To receive this signal, the GdkWindow associated to the widget needs to enable the GDK_STRUCTURE_MASK mask. GDK will enable this mask automatically for all new windows.

widget

the object which received the signal

event

the GdkEventAny which triggered this signal

user.data

user data set when the signal handler was connected.

Returns: [logical] TRUE to stop other handlers from being invoked for the event. FALSE to propagate the event further.

unrealize(widget, user.data)

undocumented

widget

the object which received the signal.

user.data

user data set when the signal handler was connected.

visibility-notify-event(widget, event, user.data)

The ::visibility-notify-event will be emitted when the widget's window is obscured or unobscured.

To receive this signal the GdkWindow associated to the widget needs to enable the GDK_VISIBILITY_NOTIFY_MASK mask.

widget

the object which received the signal

event

the GdkEventVisibility which triggered this signal

user.data

user data set when the signal handler was connected.

Returns: [logical] TRUE to stop other handlers from being invoked for the event. FALSE to propagate the event further.

window-state-event(widget, event, user.data)

The ::window-state-event will be emitted when the state of the toplevel window associated to the widget changes.

To receive this signal the GdkWindow associated to the widget needs to enable the GDK_STRUCTURE_MASK mask. GDK will enable this mask automatically for all new windows.

widget

the object which received the signal

event

the GdkEventWindowState which triggered this signal

user.data

user data set when the signal handler was connected.

Returns: [logical] TRUE to stop other handlers from being invoked for the event. FALSE to propagate the event further.

Properties

app-paintable [logical : Read / Write]

Whether the application will paint directly on the widget. Default value: FALSE

can-default [logical : Read / Write]

Whether the widget can be the default widget. Default value: FALSE

can-focus [logical : Read / Write]

Whether the widget can accept the input focus. Default value: FALSE

composite-child [logical : Read]

Whether the widget is part of a composite widget. Default value: FALSE

double-buffered [logical : Read / Write]

Whether or not the widget is double buffered. Default value: TRUE Since 2.18

events [GdkEventMask : Read / Write]

The event mask that decides what kind of GdkEvents this widget gets. Default value: GDK_STRUCTURE_MASK

extension-events [GdkExtensionMode : Read / Write]

The mask that decides what kind of extension events this widget gets. Default value: GDK_EXTENSION_EVENTS_NONE

has-default [logical : Read / Write]

Whether the widget is the default widget. Default value: FALSE

has-focus [logical : Read / Write]

Whether the widget has the input focus. Default value: FALSE

has-tooltip [logical : Read / Write]

Enables or disables the emission of "query-tooltip" on widget. A value of TRUE indicates that widget can have a tooltip, in this case the widget will be queried using "query-tooltip" to determine whether it will provide a tooltip or not.

Note that setting this property to TRUE for the first time will change the event masks of the GdkWindows of this widget to include leave-notify and motion-notify events. This cannot and will not be undone when the property is set to FALSE again. Default value: FALSE Since 2.12

height-request [integer : Read / Write]

Override for height request of the widget, or -1 if natural request should be used. Allowed values: >= -1 Default value: -1

is-focus [logical : Read / Write]

Whether the widget is the focus widget within the toplevel. Default value: FALSE

name [character : * : Read / Write]

The name of the widget. Default value: NULL

no-show-all [logical : Read / Write]

Whether gtk_widget_show_all() should not affect this widget. Default value: FALSE

parent [GtkContainer : * : Read / Write]

The parent widget of this widget. Must be a Container widget.

receives-default [logical : Read / Write]

If TRUE, the widget will receive the default action when it is focused. Default value: FALSE

sensitive [logical : Read / Write]

Whether the widget responds to input. Default value: TRUE

style [GtkStyle : * : Read / Write]

The style of the widget, which contains information about how it will look (colors etc).

tooltip-markup [character : * : Read / Write]

Sets the text of tooltip to be the given string, which is marked up with the Pango text markup language. Also see gtkTooltipSetMarkup.

This is a convenience property which will take care of getting the tooltip shown if the given string is not NULL: "has-tooltip" will automatically be set to TRUE and there will be taken care of "query-tooltip" in the default signal handler. Default value: NULL Since 2.12

tooltip-text [character : * : Read / Write]

Sets the text of tooltip to be the given string.

Also see gtkTooltipSetText.

This is a convenience property which will take care of getting the tooltip shown if the given string is not NULL: "has-tooltip" will automatically be set to TRUE and there will be taken care of "query-tooltip" in the default signal handler. Default value: NULL Since 2.12

visible [logical : Read / Write]

Whether the widget is visible. Default value: FALSE

width-request [integer : Read / Write]

Override for width request of the widget, or -1 if natural request should be used. Allowed values: >= -1 Default value: -1

window [GdkWindow : * : Read]

The widget's window if it is realized, NULL otherwise. Since 2.14

Style Properties

cursor-aspect-ratio [numeric : Read]

Aspect ratio with which to draw insertion cursor. Allowed values: [0,1] Default value: 0.04

cursor-color [GdkColor : * : Read]

Color with which to draw insertion cursor.

draw-border [GtkBorder : * : Read]

The "draw-border" style property defines the size of areas outside the widget's allocation to draw. Since 2.8

focus-line-pattern [character : * : Read]

Dash pattern used to draw the focus indicator. Default value: "\001\001"

focus-line-width [integer : Read]

Width, in pixels, of the focus indicator line. Allowed values: >= 0 Default value: 1

focus-padding [integer : Read]

Width, in pixels, between focus indicator and the widget 'box'. Allowed values: >= 0 Default value: 1

interior-focus [logical : Read]

Whether to draw the focus indicator inside widgets. Default value: TRUE

link-color [GdkColor : * : Read]

The "link-color" style property defines the color of unvisited links. Since 2.10

scroll-arrow-hlength [integer : Read]

The "scroll-arrow-hlength" style property defines the length of horizontal scroll arrows. Allowed values: >= 1 Default value: 16 Since 2.10

scroll-arrow-vlength [integer : Read]

The "scroll-arrow-vlength" style property defines the length of vertical scroll arrows. Allowed values: >= 1 Default value: 16 Since 2.10

secondary-cursor-color [GdkColor : * : Read]

Color with which to draw the secondary insertion cursor when editing mixed right-to-left and left-to-right text.

separator-height [integer : Read]

The "separator-height" style property defines the height of separators. This property only takes effect if "wide-separators" is TRUE. Allowed values: >= 0 Default value: 0 Since 2.10

separator-width [integer : Read]

The "separator-width" style property defines the width of separators. This property only takes effect if "wide-separators" is TRUE. Allowed values: >= 0 Default value: 0 Since 2.10

visited-link-color [GdkColor : * : Read]

The "visited-link-color" style property defines the color of visited links. Since 2.10

wide-separators [logical : Read]

The "wide-separators" style property defines whether separators have configurable width and should be drawn using a box instead of a line. Default value: FALSE Since 2.10

Author(s)

Derived by RGtkGen from GTK+ documentation

References

https://developer.gnome.org/gtk2/stable/GtkWidget.html


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

Related to GtkWidget in RGtk2...