gi-gtk-3.0.26: Gtk bindings

CopyrightWill Thompson Iñaki García Etxebarria and Jonas Platte
LicenseLGPL-2.1
MaintainerIñaki García Etxebarria (garetxe@gmail.com)
Safe HaskellNone
LanguageHaskell2010

GI.Gtk.Objects.Widget

Contents

Description

GtkWidget is the base class all widgets in GTK+ derive from. It manages the widget lifecycle, states and style.

{geometry-management}

GTK+ uses a height-for-width (and width-for-height) geometry management system. Height-for-width means that a widget can change how much vertical space it needs, depending on the amount of horizontal space that it is given (and similar for width-for-height). The most common example is a label that reflows to fill up the available width, wraps to fewer lines, and therefore needs less height.

Height-for-width geometry management is implemented in GTK+ by way of five virtual methods:

There are some important things to keep in mind when implementing height-for-width and when using it in container implementations.

The geometry management system will query a widget hierarchy in only one orientation at a time. When widgets are initially queried for their minimum sizes it is generally done in two initial passes in the SizeRequestMode chosen by the toplevel.

For example, when queried in the normal SizeRequestModeHeightForWidth mode: First, the default minimum and natural width for each widget in the interface will be computed using widgetGetPreferredWidth. Because the preferred widths for each container depend on the preferred widths of their children, this information propagates up the hierarchy, and finally a minimum and natural width is determined for the entire toplevel. Next, the toplevel will use the minimum width to query for the minimum height contextual to that width using widgetGetPreferredHeightForWidth, which will also be a highly recursive operation. The minimum height for the minimum width is normally used to set the minimum size constraint on the toplevel (unless windowSetGeometryHints is explicitly used instead).

After the toplevel window has initially requested its size in both dimensions it can go on to allocate itself a reasonable size (or a size previously specified with windowSetDefaultSize). During the recursive allocation process it’s important to note that request cycles will be recursively executed while container widgets allocate their children. Each container widget, once allocated a size, will go on to first share the space in one orientation among its children and then request each child's height for its target allocated width or its width for allocated height, depending. In this way a Widget will typically be requested its size a number of times before actually being allocated a size. The size a widget is finally allocated can of course differ from the size it has requested. For this reason, Widget caches a small number of results to avoid re-querying for the same sizes in one allocation cycle.

See [GtkContainer’s geometry management section][container-geometry-management] to learn more about how height-for-width allocations are performed by container widgets.

If a widget does move content around to intelligently use up the allocated size then it must support the request in both GtkSizeRequestModes even if the widget in question only trades sizes in a single orientation.

For instance, a Label that does height-for-width word wrapping will not expect to have WidgetClass.get_preferred_height() called because that call is specific to a width-for-height request. In this case the label must return the height required for its own minimum possible width. By following this rule any widget that handles height-for-width or width-for-height requests will always be allocated at least enough space to fit its own content.

Here are some examples of how a SizeRequestModeHeightForWidth widget generally deals with width-for-height requests, for WidgetClass.get_preferred_height() it will do:

C code

static void
foo_widget_get_preferred_height (GtkWidget *widget,
                                 gint *min_height,
                                 gint *nat_height)
{
   if (i_am_in_height_for_width_mode)
     {
       gint min_width, nat_width;

       GTK_WIDGET_GET_CLASS (widget)->get_preferred_width (widget,
                                                           &min_width,
                                                           &nat_width);
       GTK_WIDGET_GET_CLASS (widget)->get_preferred_height_for_width
                                                          (widget,
                                                           min_width,
                                                           min_height,
                                                           nat_height);
     }
   else
     {
        ... some widgets do both. For instance, if a GtkLabel is
        rotated to 90 degrees it will return the minimum and
        natural height for the rotated label here.
     }
}

And in WidgetClass.get_preferred_width_for_height() it will simply return the minimum and natural width:

C code

static void
foo_widget_get_preferred_width_for_height (GtkWidget *widget,
                                           gint for_height,
                                           gint *min_width,
                                           gint *nat_width)
{
   if (i_am_in_height_for_width_mode)
     {
       GTK_WIDGET_GET_CLASS (widget)->get_preferred_width (widget,
                                                           min_width,
                                                           nat_width);
     }
   else
     {
        ... again if a widget is sometimes operating in
        width-for-height mode (like a rotated GtkLabel) it can go
        ahead and do its real width for height calculation here.
     }
}

Often a widget needs to get its own request during size request or allocation. For example, when computing height it may need to also compute width. Or when deciding how to use an allocation, the widget may need to know its natural size. In these cases, the widget should be careful to call its virtual methods directly, like this:

C code

GTK_WIDGET_GET_CLASS(widget)->get_preferred_width (widget,
                                                   &min,
                                                   &natural);

It will not work to use the wrapper functions, such as widgetGetPreferredWidth inside your own size request implementation. These return a request adjusted by SizeGroup and by the WidgetClass.adjust_size_request() virtual method. If a widget used the wrappers inside its virtual method implementations, then the adjustments (such as widget margins) would be applied twice. GTK+ therefore does not allow this and will warn if you try to do it.

Of course if you are getting the size request for another widget, such as a child of a container, you must use the wrapper APIs. Otherwise, you would not properly consider widget margins, SizeGroup, and so forth.

Since 3.10 GTK+ also supports baseline vertical alignment of widgets. This means that widgets are positioned such that the typographical baseline of widgets in the same row are aligned. This happens if a widget supports baselines, has a vertical alignment of AlignBaseline, and is inside a container that supports baselines and has a natural “row” that it aligns to the baseline, or a baseline assigned to it by the grandparent.

Baseline alignment support for a widget is done by the WidgetClass.get_preferred_height_and_baseline_for_width() virtual function. It allows you to report a baseline in combination with the minimum and natural height. If there is no baseline you can return -1 to indicate this. The default implementation of this virtual function calls into the WidgetClass.get_preferred_height() and WidgetClass.get_preferred_height_for_width(), so if baselines are not supported it doesn’t need to be implemented.

If a widget ends up baseline aligned it will be allocated all the space in the parent as if it was AlignFill, but the selected baseline can be found via widgetGetAllocatedBaseline. If this has a value other than -1 you need to align the widget such that the baseline appears at the position.

Style Properties

Widget 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][gtk3-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 widgetClassInstallStyleProperty to install style properties for a widget class, widgetClassFindStyleProperty or widgetClassListStyleProperties to get information about existing style properties and widgetStyleGetProperty, gtk_widget_style_get() or gtk_widget_style_get_valist() 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.

An example of a UI definition fragment specifying an accelerator: > >class="GtkButton" > 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 Widget.

An example of a UI definition fragment specifying an accessible: > >class="GtkLabel" id="label1"/ > name="label"I am a Label for a Button/property >/object >class="GtkButton" id="button1" > accessibility > action_name="click" translatable="yes"Click the button./action > target="label1" type="labelled-by"/ > /accessibility > internal-child="accessible" > class="AtkObject" id="a11y-button1" > name="accessible-name"Clickable Button/property > /object > /child >/object

Finally, GtkWidget allows style information such as style classes to be associated with widgets, using the custom <style> element: > >class="GtkButton" id="button1" > style > name="my-special-button-class"/ > name="dark-button"/ > /style >/object

# {composite-templates}

GtkWidget exposes some facilities to automate the procedure of creating composite widgets using Builder interface description language.

To create composite widgets with Builder XML, one must associate the interface description with the widget class at class initialization time using widgetClassSetTemplate.

The interface description semantics expected in composite template descriptions is slightly different from regular Builder XML.

Unlike regular interface descriptions, widgetClassSetTemplate will expect a <template> tag as a direct child of the toplevel <interface> tag. The <template> tag must specify the “class” attribute which must be the type name of the widget. Optionally, the “parent” attribute may be specified to specify the direct parent type of the widget type, this is ignored by the GtkBuilder but required for Glade to introspect what kind of properties and internal children exist for a given type when the actual type does not exist.

The XML which is contained inside the <template> tag behaves as if it were added to the <object> tag defining widget itself. You may set properties on widget by inserting <property> tags into the <template> tag, and also add <child> tags to add children and extend widget in the normal way you would with <object> tags.

Additionally, <object> tags can also be added before and after the initial <template> tag in the normal way, allowing one to define auxiliary objects which might be referenced by other widgets declared as children of the <template> tag.

An example of a GtkBuilder Template Definition: > >interface > class="FooWidget" parent="GtkBox" > name="orientation"GTK_ORIENTATION_HORIZONTAL/property > name="spacing"4/property > child > class="GtkButton" id="hello_button" > name="label"Hello World/property > name="clicked" handler="hello_button_clicked" object="FooWidget" swapped="yes"/ > /object > /child > child > class="GtkButton" id="goodbye_button" > name="label"Goodbye World/property > /object > /child > /template >/interface

Typically, you'll place the template fragment into a file that is bundled with your project, using Resource. In order to load the template, you need to call widgetClassSetTemplateFromResource from the class initialization of your Widget type:

C code

static void
foo_widget_class_init (FooWidgetClass *klass)
{
  // ...

  gtk_widget_class_set_template_from_resource (GTK_WIDGET_CLASS (klass),
                                               "/com/example/ui/foowidget.ui");
}

You will also need to call widgetInitTemplate from the instance initialization function:

C code

static void
foo_widget_init (FooWidget *self)
{
  // ...
  gtk_widget_init_template (GTK_WIDGET (self));
}

You can access widgets defined in the template using the widgetGetTemplateChild function, but you will typically declare a pointer in the instance private data structure of your type using the same name as the widget in the template definition, and call gtk_widget_class_bind_template_child_private() with that name, e.g.

C code

typedef struct {
  GtkWidget *hello_button;
  GtkWidget *goodbye_button;
} FooWidgetPrivate;

G_DEFINE_TYPE_WITH_PRIVATE (FooWidget, foo_widget, GTK_TYPE_BOX)

static void
foo_widget_class_init (FooWidgetClass *klass)
{
  // ...
  gtk_widget_class_set_template_from_resource (GTK_WIDGET_CLASS (klass),
                                               "/com/example/ui/foowidget.ui");
  gtk_widget_class_bind_template_child_private (GTK_WIDGET_CLASS (klass),
                                                FooWidget, hello_button);
  gtk_widget_class_bind_template_child_private (GTK_WIDGET_CLASS (klass),
                                                FooWidget, goodbye_button);
}

static void
foo_widget_init (FooWidget *widget)
{

}

You can also use gtk_widget_class_bind_template_callback() to connect a signal callback defined in the template with a function visible in the scope of the class, e.g.

C code

// the signal handler has the instance and user data swapped
// because of the swapped="yes" attribute in the template XML
static void
hello_button_clicked (FooWidget *self,
                      GtkButton *button)
{
  g_print ("Hello, world!\n");
}

static void
foo_widget_class_init (FooWidgetClass *klass)
{
  // ...
  gtk_widget_class_set_template_from_resource (GTK_WIDGET_CLASS (klass),
                                               "/com/example/ui/foowidget.ui");
  gtk_widget_class_bind_template_callback (GTK_WIDGET_CLASS (klass), hello_button_clicked);
}
Synopsis

Exported types

newtype Widget Source #

Memory-managed wrapper type.

Constructors

Widget (ManagedPtr Widget) 
Instances
GObject Widget Source # 
Instance details

Defined in GI.Gtk.Objects.Widget

Methods

gobjectType :: Widget -> IO GType #

IsImplementorIface Widget Source # 
Instance details

Defined in GI.Gtk.Objects.Widget

IsObject Widget Source # 
Instance details

Defined in GI.Gtk.Objects.Widget

IsBuildable Widget Source # 
Instance details

Defined in GI.Gtk.Objects.Widget

IsWidget Widget Source # 
Instance details

Defined in GI.Gtk.Objects.Widget

class GObject o => IsWidget o Source #

Type class for types which can be safely cast to Widget, for instance with toWidget.

Instances
(GObject a, (UnknownAncestorError Widget a :: Constraint)) => IsWidget a Source # 
Instance details

Defined in GI.Gtk.Objects.Widget

IsWidget Actionable Source # 
Instance details

Defined in GI.Gtk.Interfaces.Actionable

IsWidget AppChooser Source # 
Instance details

Defined in GI.Gtk.Interfaces.AppChooser

IsWidget CellEditable Source # 
Instance details

Defined in GI.Gtk.Interfaces.CellEditable

IsWidget ToolShell Source # 
Instance details

Defined in GI.Gtk.Interfaces.ToolShell

IsWidget Bin Source # 
Instance details

Defined in GI.Gtk.Objects.Bin

IsWidget Box Source # 
Instance details

Defined in GI.Gtk.Objects.Box

IsWidget Button Source # 
Instance details

Defined in GI.Gtk.Objects.Button

IsWidget ButtonBox Source # 
Instance details

Defined in GI.Gtk.Objects.ButtonBox

IsWidget Calendar Source # 
Instance details

Defined in GI.Gtk.Objects.Calendar

IsWidget CheckButton Source # 
Instance details

Defined in GI.Gtk.Objects.CheckButton

IsWidget CheckMenuItem Source # 
Instance details

Defined in GI.Gtk.Objects.CheckMenuItem

IsWidget ComboBox Source # 
Instance details

Defined in GI.Gtk.Objects.ComboBox

IsWidget Container Source # 
Instance details

Defined in GI.Gtk.Objects.Container

IsWidget Dialog Source # 
Instance details

Defined in GI.Gtk.Objects.Dialog

IsWidget Entry Source # 
Instance details

Defined in GI.Gtk.Objects.Entry

IsWidget FlowBox Source # 
Instance details

Defined in GI.Gtk.Objects.FlowBox

IsWidget FlowBoxChild Source # 
Instance details

Defined in GI.Gtk.Objects.FlowBoxChild

IsWidget Frame Source # 
Instance details

Defined in GI.Gtk.Objects.Frame

IsWidget IconView Source # 
Instance details

Defined in GI.Gtk.Objects.IconView

IsWidget Label Source # 
Instance details

Defined in GI.Gtk.Objects.Label

IsWidget ListBox Source # 
Instance details

Defined in GI.Gtk.Objects.ListBox

IsWidget ListBoxRow Source # 
Instance details

Defined in GI.Gtk.Objects.ListBoxRow

IsWidget Menu Source # 
Instance details

Defined in GI.Gtk.Objects.Menu

IsWidget MenuItem Source # 
Instance details

Defined in GI.Gtk.Objects.MenuItem

IsWidget MenuShell Source # 
Instance details

Defined in GI.Gtk.Objects.MenuShell

IsWidget Misc Source # 
Instance details

Defined in GI.Gtk.Objects.Misc

IsWidget Paned Source # 
Instance details

Defined in GI.Gtk.Objects.Paned

IsWidget Popover Source # 
Instance details

Defined in GI.Gtk.Objects.Popover

IsWidget RadioButton Source # 
Instance details

Defined in GI.Gtk.Objects.RadioButton

IsWidget Range Source # 
Instance details

Defined in GI.Gtk.Objects.Range

IsWidget Scale Source # 
Instance details

Defined in GI.Gtk.Objects.Scale

IsWidget ScaleButton Source # 
Instance details

Defined in GI.Gtk.Objects.ScaleButton

IsWidget Scrollbar Source # 
Instance details

Defined in GI.Gtk.Objects.Scrollbar

IsWidget ScrolledWindow Source # 
Instance details

Defined in GI.Gtk.Objects.ScrolledWindow

IsWidget Separator Source # 
Instance details

Defined in GI.Gtk.Objects.Separator

IsWidget ShortcutsWindow Source # 
Instance details

Defined in GI.Gtk.Objects.ShortcutsWindow

IsWidget SpinButton Source # 
Instance details

Defined in GI.Gtk.Objects.SpinButton

IsWidget Stack Source # 
Instance details

Defined in GI.Gtk.Objects.Stack

IsWidget ToggleButton Source # 
Instance details

Defined in GI.Gtk.Objects.ToggleButton

IsWidget ToggleToolButton Source # 
Instance details

Defined in GI.Gtk.Objects.ToggleToolButton

IsWidget ToolButton Source # 
Instance details

Defined in GI.Gtk.Objects.ToolButton

IsWidget ToolItem Source # 
Instance details

Defined in GI.Gtk.Objects.ToolItem

IsWidget ToolItemGroup Source # 
Instance details

Defined in GI.Gtk.Objects.ToolItemGroup

IsWidget TreeView Source # 
Instance details

Defined in GI.Gtk.Objects.TreeView

IsWidget Widget Source # 
Instance details

Defined in GI.Gtk.Objects.Widget

IsWidget VolumeButton Source # 
Instance details

Defined in GI.Gtk.Objects.VolumeButton

IsWidget Viewport Source # 
Instance details

Defined in GI.Gtk.Objects.Viewport

IsWidget VSeparator Source # 
Instance details

Defined in GI.Gtk.Objects.VSeparator

IsWidget VScrollbar Source # 
Instance details

Defined in GI.Gtk.Objects.VScrollbar

IsWidget VScale Source # 
Instance details

Defined in GI.Gtk.Objects.VScale

IsWidget VPaned Source # 
Instance details

Defined in GI.Gtk.Objects.VPaned

IsWidget VButtonBox Source # 
Instance details

Defined in GI.Gtk.Objects.VButtonBox

IsWidget VBox Source # 
Instance details

Defined in GI.Gtk.Objects.VBox

IsWidget Toolbar Source # 
Instance details

Defined in GI.Gtk.Objects.Toolbar

IsWidget TearoffMenuItem Source # 
Instance details

Defined in GI.Gtk.Objects.TearoffMenuItem

IsWidget Table Source # 
Instance details

Defined in GI.Gtk.Objects.Table

IsWidget Switch Source # 
Instance details

Defined in GI.Gtk.Objects.Switch

IsWidget Statusbar Source # 
Instance details

Defined in GI.Gtk.Objects.Statusbar

IsWidget StackSwitcher Source # 
Instance details

Defined in GI.Gtk.Objects.StackSwitcher

IsWidget StackSidebar Source # 
Instance details

Defined in GI.Gtk.Objects.StackSidebar

IsWidget Spinner Source # 
Instance details

Defined in GI.Gtk.Objects.Spinner

IsWidget Socket Source # 
Instance details

Defined in GI.Gtk.Objects.Socket

IsWidget ShortcutsShortcut Source # 
Instance details

Defined in GI.Gtk.Objects.ShortcutsShortcut

IsWidget ShortcutsSection Source # 
Instance details

Defined in GI.Gtk.Objects.ShortcutsSection

IsWidget ShortcutsGroup Source # 
Instance details

Defined in GI.Gtk.Objects.ShortcutsGroup

IsWidget ShortcutLabel Source # 
Instance details

Defined in GI.Gtk.Objects.ShortcutLabel

IsWidget SeparatorToolItem Source # 
Instance details

Defined in GI.Gtk.Objects.SeparatorToolItem

IsWidget SeparatorMenuItem Source # 
Instance details

Defined in GI.Gtk.Objects.SeparatorMenuItem

IsWidget SearchEntry Source # 
Instance details

Defined in GI.Gtk.Objects.SearchEntry

IsWidget SearchBar Source # 
Instance details

Defined in GI.Gtk.Objects.SearchBar

IsWidget Revealer Source # 
Instance details

Defined in GI.Gtk.Objects.Revealer

IsWidget RecentChooserWidget Source # 
Instance details

Defined in GI.Gtk.Objects.RecentChooserWidget

IsWidget RecentChooserMenu Source # 
Instance details

Defined in GI.Gtk.Objects.RecentChooserMenu

IsWidget RadioToolButton Source # 
Instance details

Defined in GI.Gtk.Objects.RadioToolButton

IsWidget RadioMenuItem Source # 
Instance details

Defined in GI.Gtk.Objects.RadioMenuItem

IsWidget ProgressBar Source # 
Instance details

Defined in GI.Gtk.Objects.ProgressBar

IsWidget PopoverMenu Source # 
Instance details

Defined in GI.Gtk.Objects.PopoverMenu

IsWidget PlacesSidebar Source # 
Instance details

Defined in GI.Gtk.Objects.PlacesSidebar

IsWidget Overlay Source # 
Instance details

Defined in GI.Gtk.Objects.Overlay

IsWidget Notebook Source # 
Instance details

Defined in GI.Gtk.Objects.Notebook

IsWidget ModelButton Source # 
Instance details

Defined in GI.Gtk.Objects.ModelButton

IsWidget MenuToolButton Source # 
Instance details

Defined in GI.Gtk.Objects.MenuToolButton

IsWidget MenuButton Source # 
Instance details

Defined in GI.Gtk.Objects.MenuButton

IsWidget MenuBar Source # 
Instance details

Defined in GI.Gtk.Objects.MenuBar

IsWidget LockButton Source # 
Instance details

Defined in GI.Gtk.Objects.LockButton

IsWidget LinkButton Source # 
Instance details

Defined in GI.Gtk.Objects.LinkButton

IsWidget LevelBar Source # 
Instance details

Defined in GI.Gtk.Objects.LevelBar

IsWidget Layout Source # 
Instance details

Defined in GI.Gtk.Objects.Layout

IsWidget Invisible Source # 
Instance details

Defined in GI.Gtk.Objects.Invisible

IsWidget InfoBar Source # 
Instance details

Defined in GI.Gtk.Objects.InfoBar

IsWidget ImageMenuItem Source # 
Instance details

Defined in GI.Gtk.Objects.ImageMenuItem

IsWidget HeaderBar Source # 
Instance details

Defined in GI.Gtk.Objects.HeaderBar

IsWidget HandleBox Source # 
Instance details

Defined in GI.Gtk.Objects.HandleBox

IsWidget HSeparator Source # 
Instance details

Defined in GI.Gtk.Objects.HSeparator

IsWidget HScrollbar Source # 
Instance details

Defined in GI.Gtk.Objects.HScrollbar

IsWidget HScale Source # 
Instance details

Defined in GI.Gtk.Objects.HScale

IsWidget HSV Source # 
Instance details

Defined in GI.Gtk.Objects.HSV

IsWidget HPaned Source # 
Instance details

Defined in GI.Gtk.Objects.HPaned

IsWidget HButtonBox Source # 
Instance details

Defined in GI.Gtk.Objects.HButtonBox

IsWidget HBox Source # 
Instance details

Defined in GI.Gtk.Objects.HBox

IsWidget Grid Source # 
Instance details

Defined in GI.Gtk.Objects.Grid

IsWidget GLArea Source # 
Instance details

Defined in GI.Gtk.Objects.GLArea

IsWidget FontSelection Source # 
Instance details

Defined in GI.Gtk.Objects.FontSelection

IsWidget FontChooserWidget Source # 
Instance details

Defined in GI.Gtk.Objects.FontChooserWidget

IsWidget FontButton Source # 
Instance details

Defined in GI.Gtk.Objects.FontButton

IsWidget Fixed Source # 
Instance details

Defined in GI.Gtk.Objects.Fixed

IsWidget FileChooserWidget Source # 
Instance details

Defined in GI.Gtk.Objects.FileChooserWidget

IsWidget FileChooserButton Source # 
Instance details

Defined in GI.Gtk.Objects.FileChooserButton

IsWidget Expander Source # 
Instance details

Defined in GI.Gtk.Objects.Expander

IsWidget EventBox Source # 
Instance details

Defined in GI.Gtk.Objects.EventBox

IsWidget DrawingArea Source # 
Instance details

Defined in GI.Gtk.Objects.DrawingArea

IsWidget ComboBoxText Source # 
Instance details

Defined in GI.Gtk.Objects.ComboBoxText

IsWidget ColorSelection Source # 
Instance details

Defined in GI.Gtk.Objects.ColorSelection

IsWidget ColorChooserWidget Source # 
Instance details

Defined in GI.Gtk.Objects.ColorChooserWidget

IsWidget ColorButton Source # 
Instance details

Defined in GI.Gtk.Objects.ColorButton

IsWidget AspectFrame Source # 
Instance details

Defined in GI.Gtk.Objects.AspectFrame

IsWidget Arrow Source # 
Instance details

Defined in GI.Gtk.Objects.Arrow

IsWidget AppChooserWidget Source # 
Instance details

Defined in GI.Gtk.Objects.AppChooserWidget

IsWidget AppChooserButton Source # 
Instance details

Defined in GI.Gtk.Objects.AppChooserButton

IsWidget Alignment Source # 
Instance details

Defined in GI.Gtk.Objects.Alignment

IsWidget ActionBar Source # 
Instance details

Defined in GI.Gtk.Objects.ActionBar

IsWidget AccelLabel Source # 
Instance details

Defined in GI.Gtk.Objects.AccelLabel

IsWidget Window Source # 
Instance details

Defined in GI.Gtk.Objects.Window

IsWidget RecentChooserDialog Source # 
Instance details

Defined in GI.Gtk.Objects.RecentChooserDialog

IsWidget Plug Source # 
Instance details

Defined in GI.Gtk.Objects.Plug

IsWidget OffscreenWindow Source # 
Instance details

Defined in GI.Gtk.Objects.OffscreenWindow

IsWidget MessageDialog Source # 
Instance details

Defined in GI.Gtk.Objects.MessageDialog

IsWidget FontSelectionDialog Source # 
Instance details

Defined in GI.Gtk.Objects.FontSelectionDialog

IsWidget FontChooserDialog Source # 
Instance details

Defined in GI.Gtk.Objects.FontChooserDialog

IsWidget FileChooserDialog Source # 
Instance details

Defined in GI.Gtk.Objects.FileChooserDialog

IsWidget ColorSelectionDialog Source # 
Instance details

Defined in GI.Gtk.Objects.ColorSelectionDialog

IsWidget ColorChooserDialog Source # 
Instance details

Defined in GI.Gtk.Objects.ColorChooserDialog

IsWidget ApplicationWindow Source # 
Instance details

Defined in GI.Gtk.Objects.ApplicationWindow

IsWidget AppChooserDialog Source # 
Instance details

Defined in GI.Gtk.Objects.AppChooserDialog

IsWidget AboutDialog Source # 
Instance details

Defined in GI.Gtk.Objects.AboutDialog

IsWidget Image Source # 
Instance details

Defined in GI.Gtk.Objects.Image

IsWidget ToolPalette Source # 
Instance details

Defined in GI.Gtk.Objects.ToolPalette

IsWidget TextView Source # 
Instance details

Defined in GI.Gtk.Objects.TextView

IsWidget CellView Source # 
Instance details

Defined in GI.Gtk.Objects.CellView

IsWidget Assistant Source # 
Instance details

Defined in GI.Gtk.Objects.Assistant

toWidget :: (MonadIO m, IsWidget o) => o -> m Widget Source #

Cast to Widget, for types for which this is known to be safe. For general casts, use castTo.

noWidget :: Maybe Widget Source #

A convenience alias for Nothing :: Maybe Widget.

Methods

activate

widgetActivate Source #

Arguments

:: (HasCallStack, MonadIO m, IsWidget a) 
=> a

widget: a Widget that’s activatable

-> m Bool

Returns: True if the widget was activatable

For widgets that can be “activated” (buttons, menu items, etc.) this function activates them. Activation is what happens when you press Enter on a widget during key navigation. If widget isn't activatable, the function returns False.

addAccelerator

widgetAddAccelerator Source #

Arguments

:: (HasCallStack, MonadIO m, IsWidget a, IsAccelGroup b) 
=> a

widget: widget to install an accelerator on

-> Text

accelSignal: widget signal to emit on accelerator activation

-> b

accelGroup: accel group for this widget, added to its toplevel

-> Word32

accelKey: GDK keyval of the accelerator

-> [ModifierType]

accelMods: modifier key combination of the accelerator

-> [AccelFlags]

accelFlags: flag accelerators, e.g. AccelFlagsVisible

-> m () 

Installs an accelerator for this widget in accelGroup that causes accelSignal to be emitted if the accelerator is activated. The accelGroup needs to be added to the widget’s toplevel via windowAddAccelGroup, and the signal must be of type SignalFlagsAction. Accelerators added through this function are not user changeable during runtime. If you want to support accelerators that can be changed by the user, use accelMapAddEntry and widgetSetAccelPath or menuItemSetAccelPath instead.

addDeviceEvents

widgetAddDeviceEvents Source #

Arguments

:: (HasCallStack, MonadIO m, IsWidget a, IsDevice b) 
=> a

widget: a Widget

-> b

device: a Device

-> [EventMask]

events: an event mask, see EventMask

-> m () 

Adds the device events in the bitfield events to the event mask for widget. See widgetSetDeviceEvents for details.

Since: 3.0

addEvents

widgetAddEvents Source #

Arguments

:: (HasCallStack, MonadIO m, IsWidget a) 
=> a

widget: a Widget

-> [EventMask]

events: an event mask, see EventMask

-> m () 

Adds the events in the bitfield events to the event mask for widget. See widgetSetEvents and the [input handling overview][event-masks] for details.

addMnemonicLabel

widgetAddMnemonicLabel Source #

Arguments

:: (HasCallStack, MonadIO m, IsWidget a, IsWidget b) 
=> a

widget: a Widget

-> b

label: a Widget that acts as a mnemonic label for widget

-> m () 

Adds a widget to the list of mnemonic labels for this widget. (See widgetListMnemonicLabels). Note the list of mnemonic labels for the widget is cleared when the widget is destroyed, so the caller must make sure to update its internal state at this point as well, by using a connection to the Widget::destroy signal or a weak notifier.

Since: 2.4

addTickCallback

widgetAddTickCallback Source #

Arguments

:: (HasCallStack, MonadIO m, IsWidget a) 
=> a

widget: a Widget

-> TickCallback

callback: function to call for updating animations

-> m Word32

Returns: an id for the connection of this callback. Remove the callback by passing it to widgetRemoveTickCallback

Queues an animation frame update and adds a callback to be called before each frame. Until the tick callback is removed, it will be called frequently (usually at the frame rate of the output device or as quickly as the application can be repainted, whichever is slower). For this reason, is most suitable for handling graphics that change every frame or every few frames. The tick callback does not automatically imply a relayout or repaint. If you want a repaint or relayout, and aren’t changing widget properties that would trigger that (for example, changing the text of a Label), then you will have to call widgetQueueResize or widgetQueueDrawArea yourself.

frameClockGetFrameTime should generally be used for timing continuous animations and frameTimingsGetPredictedPresentationTime if you are trying to display isolated frames at particular times.

This is a more convenient alternative to connecting directly to the FrameClock::update signal of FrameClock, since you don't have to worry about when a FrameClock is assigned to a widget.

Since: 3.8

canActivateAccel

widgetCanActivateAccel Source #

Arguments

:: (HasCallStack, MonadIO m, IsWidget a) 
=> a

widget: a Widget

-> Word32

signalId: the ID of a signal installed on widget

-> m Bool

Returns: True if the accelerator can be activated.

Determines whether an accelerator that activates the signal identified by signalId can currently be activated. This is done by emitting the Widget::can-activate-accel signal on widget; if the signal isn’t overridden by a handler or in a derived widget, then the default check is that the widget must be sensitive, and the widget and all its ancestors mapped.

Since: 2.4

childFocus

widgetChildFocus Source #

Arguments

:: (HasCallStack, MonadIO m, IsWidget a) 
=> a

widget: a Widget

-> DirectionType

direction: direction of focus movement

-> m Bool

Returns: True if focus ended up inside widget

This function is used by custom widget implementations; if you're writing an app, you’d use widgetGrabFocus to move the focus to a particular widget, and containerSetFocusChain to change the focus tab order. So you may want to investigate those functions instead.

widgetChildFocus is called by containers as the user moves around the window using keyboard shortcuts. direction indicates what kind of motion is taking place (up, down, left, right, tab forward, tab backward). widgetChildFocus emits the Widget::focus signal; widgets override the default handler for this signal in order to implement appropriate focus behavior.

The default ::focus handler for a widget should return True if moving in direction left the focus on a focusable location inside that widget, and False if moving in direction moved the focus outside the widget. If returning True, widgets normally call widgetGrabFocus to place the focus accordingly; if returning False, they don’t modify the current focus location.

childNotify

widgetChildNotify Source #

Arguments

:: (HasCallStack, MonadIO m, IsWidget a) 
=> a

widget: a Widget

-> Text

childProperty: the name of a child property installed on the class of widget’s parent

-> m () 

Emits a Widget::child-notify signal for the [child property][child-properties] childProperty on widget.

This is the analogue of objectNotify for child properties.

Also see containerChildNotify.

classPath

widgetClassPath Source #

Arguments

:: (HasCallStack, MonadIO m, IsWidget a) 
=> a

widget: a Widget

-> m (Word32, Text, Text) 

Deprecated: (Since version 3.0)Use widgetGetPath instead

Same as widgetPath, but always uses the name of a widget’s type, never uses a custom name set with widgetSetName.

computeExpand

widgetComputeExpand Source #

Arguments

:: (HasCallStack, MonadIO m, IsWidget a) 
=> a

widget: the widget

-> Orientation

orientation: expand direction

-> m Bool

Returns: whether widget tree rooted here should be expanded

Computes whether a container should give this widget extra space when possible. Containers should check this, rather than looking at widgetGetHexpand or widgetGetVexpand.

This function already checks whether the widget is visible, so visibility does not need to be checked separately. Non-visible widgets are not expanded.

The computed expand value uses either the expand setting explicitly set on the widget itself, or, if none has been explicitly set, the widget may expand if some of its children do.

createPangoContext

widgetCreatePangoContext Source #

Arguments

:: (HasCallStack, MonadIO m, IsWidget a) 
=> a

widget: a Widget

-> m Context

Returns: the new Context

Creates a new Context with the appropriate font map, font options, font description, and base direction for drawing text for this widget. See also widgetGetPangoContext.

createPangoLayout

widgetCreatePangoLayout Source #

Arguments

:: (HasCallStack, MonadIO m, IsWidget a) 
=> a

widget: a Widget

-> Maybe Text

text: text to set on the layout (can be Nothing)

-> m Layout

Returns: the new Layout

Creates a new Layout with the appropriate font map, font description, and base direction for drawing text for this widget.

If you keep a Layout created in this way around, you need to re-create it when the widget Context is replaced. This can be tracked by using the Widget::screen-changed signal on the widget.

destroy

widgetDestroy Source #

Arguments

:: (HasCallStack, MonadIO m, IsWidget a) 
=> a

widget: a Widget

-> m () 

Destroys a widget.

When a widget is destroyed all references it holds on other objects will be released:

  • if the widget is inside a container, it will be removed from its parent
  • if the widget is a container, all its children will be destroyed, recursively
  • if the widget is a top level, it will be removed from the list of top level widgets that GTK+ maintains internally

It's expected that all references held on the widget will also be released; you should connect to the Widget::destroy signal if you hold a reference to widget and you wish to remove it when this function is called. It is not necessary to do so if you are implementing a Container, as you'll be able to use the ContainerClass.remove() virtual function for that.

It's important to notice that widgetDestroy will only cause the widget to be finalized if no additional references, acquired using objectRef, are held on it. In case additional references are in place, the widget will be in an "inert" state after calling this function; widget will still point to valid memory, allowing you to release the references you hold, but you may not query the widget's own state.

You should typically call this function on top level widgets, and rarely on child widgets.

See also: containerRemove

destroyed

widgetDestroyed Source #

Arguments

:: (HasCallStack, MonadIO m, IsWidget a, IsWidget b) 
=> a

widget: a Widget

-> b

widgetPointer: address of a variable that contains widget

-> m Widget 

This function sets *widgetPointer to Nothing if widgetPointer != Nothing. It’s intended to be used as a callback connected to the “destroy” signal of a widget. You connect widgetDestroyed as a signal handler, and pass the address of your widget variable as user data. Then when the widget is destroyed, the variable will be set to Nothing. Useful for example to avoid multiple copies of the same dialog.

deviceIsShadowed

widgetDeviceIsShadowed Source #

Arguments

:: (HasCallStack, MonadIO m, IsWidget a, IsDevice b) 
=> a

widget: a Widget

-> b

device: a Device

-> m Bool

Returns: True if there is an ongoing grab on device by another Widget than widget.

Returns True if device has been shadowed by a GTK+ device grab on another widget, so it would stop sending events to widget. This may be used in the Widget::grab-notify signal to check for specific devices. See deviceGrabAdd.

Since: 3.0

dragBegin

widgetDragBegin Source #

Arguments

:: (HasCallStack, MonadIO m, IsWidget a) 
=> a

widget: the source widget

-> TargetList

targets: The targets (data formats) in which the source can provide the data

-> [DragAction]

actions: A bitmask of the allowed drag actions for this drag

-> Int32

button: The button the user clicked to start the drag

-> Maybe Event

event: The event that triggered the start of the drag, or Nothing if none can be obtained.

-> m DragContext

Returns: the context for this drag

Deprecated: (Since version 3.10)Use widgetDragBeginWithCoordinates instead

This function is equivalent to widgetDragBeginWithCoordinates, passing -1, -1 as coordinates.

dragBeginWithCoordinates

widgetDragBeginWithCoordinates Source #

Arguments

:: (HasCallStack, MonadIO m, IsWidget a) 
=> a

widget: the source widget

-> TargetList

targets: The targets (data formats) in which the source can provide the data

-> [DragAction]

actions: A bitmask of the allowed drag actions for this drag

-> Int32

button: The button the user clicked to start the drag

-> Maybe Event

event: The event that triggered the start of the drag, or Nothing if none can be obtained.

-> Int32

x: The initial x coordinate to start dragging from, in the coordinate space of widget. If -1 is passed, the coordinates are retrieved from event or the current pointer position

-> Int32

y: The initial y coordinate to start dragging from, in the coordinate space of widget. If -1 is passed, the coordinates are retrieved from event or the current pointer position

-> m DragContext

Returns: the context for this drag

Initiates a drag on the source side. The function only needs to be used when the application is starting drags itself, and is not needed when widgetDragSourceSet is used.

The event is used to retrieve the timestamp that will be used internally to grab the pointer. If event is Nothing, then CURRENT_TIME will be used. However, you should try to pass a real event in all cases, since that can be used to get information about the drag.

Generally there are three cases when you want to start a drag by hand by calling this function:

  1. During a Widget::button-press-event handler, if you want to start a drag immediately when the user presses the mouse button. Pass the event that you have in your Widget::button-press-event handler.
  2. During a Widget::motion-notify-event handler, if you want to start a drag when the mouse moves past a certain threshold distance after a button-press. Pass the event that you have in your Widget::motion-notify-event handler.
  3. During a timeout handler, if you want to start a drag after the mouse button is held down for some time. Try to save the last event that you got from the mouse, using eventCopy, and pass it to this function (remember to free the event with eventFree when you are done). If you really cannot pass a real event, pass Nothing instead.

Since: 3.10

dragCheckThreshold

widgetDragCheckThreshold Source #

Arguments

:: (HasCallStack, MonadIO m, IsWidget a) 
=> a

widget: a Widget

-> Int32

startX: X coordinate of start of drag

-> Int32

startY: Y coordinate of start of drag

-> Int32

currentX: current X coordinate

-> Int32

currentY: current Y coordinate

-> m Bool

Returns: True if the drag threshold has been passed.

Checks to see if a mouse drag starting at (startX, startY) and ending at (currentX, currentY) has passed the GTK+ drag threshold, and thus should trigger the beginning of a drag-and-drop operation.

dragDestAddImageTargets

widgetDragDestAddImageTargets Source #

Arguments

:: (HasCallStack, MonadIO m, IsWidget a) 
=> a

widget: a Widget that’s a drag destination

-> m () 

Add the image targets supported by SelectionData to the target list of the drag destination. The targets are added with info = 0. If you need another value, use targetListAddImageTargets and widgetDragDestSetTargetList.

Since: 2.6

dragDestAddTextTargets

widgetDragDestAddTextTargets Source #

Arguments

:: (HasCallStack, MonadIO m, IsWidget a) 
=> a

widget: a Widget that’s a drag destination

-> m () 

Add the text targets supported by SelectionData to the target list of the drag destination. The targets are added with info = 0. If you need another value, use targetListAddTextTargets and widgetDragDestSetTargetList.

Since: 2.6

dragDestAddUriTargets

widgetDragDestAddUriTargets Source #

Arguments

:: (HasCallStack, MonadIO m, IsWidget a) 
=> a

widget: a Widget that’s a drag destination

-> m () 

Add the URI targets supported by SelectionData to the target list of the drag destination. The targets are added with info = 0. If you need another value, use targetListAddUriTargets and widgetDragDestSetTargetList.

Since: 2.6

dragDestFindTarget

widgetDragDestFindTarget Source #

Arguments

:: (HasCallStack, MonadIO m, IsWidget a, IsDragContext b) 
=> a

widget: drag destination widget

-> b

context: drag context

-> Maybe TargetList

targetList: list of droppable targets, or Nothing to use gtk_drag_dest_get_target_list (widget).

-> m (Maybe Atom)

Returns: first target that the source offers and the dest can accept, or GDK_NONE

Looks for a match between the supported targets of context and the destTargetList, returning the first matching target, otherwise returning GDK_NONE. destTargetList should usually be the return value from widgetDragDestGetTargetList, but some widgets may have different valid targets for different parts of the widget; in that case, they will have to implement a drag_motion handler that passes the correct target list to this function.

dragDestGetTargetList

widgetDragDestGetTargetList Source #

Arguments

:: (HasCallStack, MonadIO m, IsWidget a) 
=> a

widget: a Widget

-> m (Maybe TargetList)

Returns: the TargetList, or Nothing if none

Returns the list of targets this widget can accept from drag-and-drop.

dragDestGetTrackMotion

widgetDragDestGetTrackMotion Source #

Arguments

:: (HasCallStack, MonadIO m, IsWidget a) 
=> a

widget: a Widget that’s a drag destination

-> m Bool

Returns: True if the widget always emits Widget::drag-motion events

Returns whether the widget has been configured to always emit Widget::drag-motion signals.

Since: 2.10

dragDestSet

widgetDragDestSet Source #

Arguments

:: (HasCallStack, MonadIO m, IsWidget a) 
=> a

widget: a Widget

-> [DestDefaults]

flags: which types of default drag behavior to use

-> Maybe [TargetEntry]

targets: a pointer to an array of GtkTargetEntrys indicating the drop types that this widget will accept, or Nothing. Later you can access the list with widgetDragDestGetTargetList and widgetDragDestFindTarget.

-> [DragAction]

actions: a bitmask of possible actions for a drop onto this widget.

-> m () 

Sets a widget as a potential drop destination, and adds default behaviors.

The default behaviors listed in flags have an effect similar to installing default handlers for the widget’s drag-and-drop signals (Widget::drag-motion, Widget::drag-drop, ...). They all exist for convenience. When passing GTK_DEST_DEFAULT_ALL for instance it is sufficient to connect to the widget’s Widget::drag-data-received signal to get primitive, but consistent drag-and-drop support.

Things become more complicated when you try to preview the dragged data, as described in the documentation for Widget::drag-motion. The default behaviors described by flags make some assumptions, that can conflict with your own signal handlers. For instance GTK_DEST_DEFAULT_DROP causes invokations of dragStatus in the context of Widget::drag-motion, and invokations of dragFinish in Widget::drag-data-received. Especially the later is dramatic, when your own Widget::drag-motion handler calls widgetDragGetData to inspect the dragged data.

There’s no way to set a default action here, you can use the Widget::drag-motion callback for that. Here’s an example which selects the action to use depending on whether the control key is pressed or not:

C code

static void
drag_motion (GtkWidget *widget,
             GdkDragContext *context,
             gint x,
             gint y,
             guint time)
{
  GdkModifierType mask;

  gdk_window_get_pointer (gtk_widget_get_window (widget),
                          NULL, NULL, &mask);
  if (mask & GDK_CONTROL_MASK)
    gdk_drag_status (context, GDK_ACTION_COPY, time);
  else
    gdk_drag_status (context, GDK_ACTION_MOVE, time);
}

dragDestSetProxy

widgetDragDestSetProxy Source #

Arguments

:: (HasCallStack, MonadIO m, IsWidget a, IsWindow b) 
=> a

widget: a Widget

-> b

proxyWindow: the window to which to forward drag events

-> DragProtocol

protocol: the drag protocol which the proxyWindow accepts (You can use gdk_drag_get_protocol() to determine this)

-> Bool

useCoordinates: If True, send the same coordinates to the destination, because it is an embedded subwindow.

-> m () 

Deprecated: (Since version 3.22)

Sets this widget as a proxy for drops to another window.

dragDestSetTargetList

widgetDragDestSetTargetList Source #

Arguments

:: (HasCallStack, MonadIO m, IsWidget a) 
=> a

widget: a Widget that’s a drag destination

-> Maybe TargetList

targetList: list of droppable targets, or Nothing for none

-> m () 

Sets the target types that this widget can accept from drag-and-drop. The widget must first be made into a drag destination with widgetDragDestSet.

dragDestSetTrackMotion

widgetDragDestSetTrackMotion Source #

Arguments

:: (HasCallStack, MonadIO m, IsWidget a) 
=> a

widget: a Widget that’s a drag destination

-> Bool

trackMotion: whether to accept all targets

-> m () 

Tells the widget to emit Widget::drag-motion and Widget::drag-leave events regardless of the targets and the DestDefaultsMotion flag.

This may be used when a widget wants to do generic actions regardless of the targets that the source offers.

Since: 2.10

dragDestUnset

widgetDragDestUnset Source #

Arguments

:: (HasCallStack, MonadIO m, IsWidget a) 
=> a

widget: a Widget

-> m () 

Clears information about a drop destination set with widgetDragDestSet. The widget will no longer receive notification of drags.

dragGetData

widgetDragGetData Source #

Arguments

:: (HasCallStack, MonadIO m, IsWidget a, IsDragContext b) 
=> a

widget: the widget that will receive the Widget::drag-data-received signal

-> b

context: the drag context

-> Atom

target: the target (form of the data) to retrieve

-> Word32

time_: a timestamp for retrieving the data. This will generally be the time received in a Widget::drag-motion or Widget::drag-drop signal

-> m () 

Gets the data associated with a drag. When the data is received or the retrieval fails, GTK+ will emit a Widget::drag-data-received signal. Failure of the retrieval is indicated by the length field of the selectionData signal parameter being negative. However, when widgetDragGetData is called implicitely because the DestDefaultsDrop was set, then the widget will not receive notification of failed drops.

dragHighlight

widgetDragHighlight Source #

Arguments

:: (HasCallStack, MonadIO m, IsWidget a) 
=> a

widget: a widget to highlight

-> m () 

Highlights a widget as a currently hovered drop target. To end the highlight, call widgetDragUnhighlight. GTK+ calls this automatically if DestDefaultsHighlight is set.

dragSourceAddImageTargets

widgetDragSourceAddImageTargets Source #

Arguments

:: (HasCallStack, MonadIO m, IsWidget a) 
=> a

widget: a Widget that’s is a drag source

-> m () 

Add the writable image targets supported by SelectionData to the target list of the drag source. The targets are added with info = 0. If you need another value, use targetListAddImageTargets and widgetDragSourceSetTargetList.

Since: 2.6

dragSourceAddTextTargets

widgetDragSourceAddTextTargets Source #

Arguments

:: (HasCallStack, MonadIO m, IsWidget a) 
=> a

widget: a Widget that’s is a drag source

-> m () 

Add the text targets supported by SelectionData to the target list of the drag source. The targets are added with info = 0. If you need another value, use targetListAddTextTargets and widgetDragSourceSetTargetList.

Since: 2.6

dragSourceAddUriTargets

widgetDragSourceAddUriTargets Source #

Arguments

:: (HasCallStack, MonadIO m, IsWidget a) 
=> a

widget: a Widget that’s is a drag source

-> m () 

Add the URI targets supported by SelectionData to the target list of the drag source. The targets are added with info = 0. If you need another value, use targetListAddUriTargets and widgetDragSourceSetTargetList.

Since: 2.6

dragSourceGetTargetList

widgetDragSourceGetTargetList Source #

Arguments

:: (HasCallStack, MonadIO m, IsWidget a) 
=> a

widget: a Widget

-> m (Maybe TargetList)

Returns: the TargetList, or Nothing if none

Gets the list of targets this widget can provide for drag-and-drop.

Since: 2.4

dragSourceSet

widgetDragSourceSet Source #

Arguments

:: (HasCallStack, MonadIO m, IsWidget a) 
=> a

widget: a Widget

-> [ModifierType]

startButtonMask: the bitmask of buttons that can start the drag

-> Maybe [TargetEntry]

targets: the table of targets that the drag will support, may be Nothing

-> [DragAction]

actions: the bitmask of possible actions for a drag from this widget

-> m () 

Sets up a widget so that GTK+ will start a drag operation when the user clicks and drags on the widget. The widget must have a window.

dragSourceSetIconGicon

widgetDragSourceSetIconGicon Source #

Arguments

:: (HasCallStack, MonadIO m, IsWidget a, IsIcon b) 
=> a

widget: a Widget

-> b

icon: A Icon

-> m () 

Sets the icon that will be used for drags from a particular source to icon. See the docs for IconTheme for more details.

Since: 3.2

dragSourceSetIconName

widgetDragSourceSetIconName Source #

Arguments

:: (HasCallStack, MonadIO m, IsWidget a) 
=> a

widget: a Widget

-> Text

iconName: name of icon to use

-> m () 

Sets the icon that will be used for drags from a particular source to a themed icon. See the docs for IconTheme for more details.

Since: 2.8

dragSourceSetIconPixbuf

widgetDragSourceSetIconPixbuf Source #

Arguments

:: (HasCallStack, MonadIO m, IsWidget a, IsPixbuf b) 
=> a

widget: a Widget

-> b

pixbuf: the Pixbuf for the drag icon

-> m () 

Sets the icon that will be used for drags from a particular widget from a Pixbuf. GTK+ retains a reference for pixbuf and will release it when it is no longer needed.

dragSourceSetIconStock

widgetDragSourceSetIconStock Source #

Arguments

:: (HasCallStack, MonadIO m, IsWidget a) 
=> a

widget: a Widget

-> Text

stockId: the ID of the stock icon to use

-> m () 

Deprecated: (Since version 3.10)Use widgetDragSourceSetIconName instead.

Sets the icon that will be used for drags from a particular source to a stock icon.

dragSourceSetTargetList

widgetDragSourceSetTargetList Source #

Arguments

:: (HasCallStack, MonadIO m, IsWidget a) 
=> a

widget: a Widget that’s a drag source

-> Maybe TargetList

targetList: list of draggable targets, or Nothing for none

-> m () 

Changes the target types that this widget offers for drag-and-drop. The widget must first be made into a drag source with widgetDragSourceSet.

Since: 2.4

dragSourceUnset

widgetDragSourceUnset Source #

Arguments

:: (HasCallStack, MonadIO m, IsWidget a) 
=> a

widget: a Widget

-> m () 

Undoes the effects of widgetDragSourceSet.

dragUnhighlight

widgetDragUnhighlight Source #

Arguments

:: (HasCallStack, MonadIO m, IsWidget a) 
=> a

widget: a widget to remove the highlight from

-> m () 

Removes a highlight set by widgetDragHighlight from a widget.

draw

widgetDraw Source #

Arguments

:: (HasCallStack, MonadIO m, IsWidget a) 
=> a

widget: the widget to draw. It must be drawable (see widgetIsDrawable) and a size must have been allocated.

-> Context

cr: a cairo context to draw to

-> m () 

Draws widget to cr. The top left corner of the widget will be drawn to the currently set origin point of cr.

You should pass a cairo context as cr argument that is in an original state. Otherwise the resulting drawing is undefined. For example changing the operator using cairo_set_operator() or the line width using cairo_set_line_width() might have unwanted side effects. You may however change the context’s transform matrix - like with cairo_scale(), cairo_translate() or cairo_set_matrix() and clip region with cairo_clip() prior to calling this function. Also, it is fine to modify the context with cairo_save() and cairo_push_group() prior to calling this function.

Note that special-purpose widgets may contain special code for rendering to the screen and might appear differently on screen and when rendered using widgetDraw.

Since: 3.0

ensureStyle

widgetEnsureStyle Source #

Arguments

:: (HasCallStack, MonadIO m, IsWidget a) 
=> a

widget: a Widget

-> m () 

Deprecated: (Since version 3.0)Use StyleContext instead

Ensures that widget has a style (widget->style).

Not a very useful function; most of the time, if you want the style, the widget is realized, and realized widgets are guaranteed to have a style already.

errorBell

widgetErrorBell Source #

Arguments

:: (HasCallStack, MonadIO m, IsWidget a) 
=> a

widget: a Widget

-> m () 

Notifies the user about an input-related error on this widget. If the Settings:gtk-error-bell setting is True, it calls windowBeep, otherwise it does nothing.

Note that the effect of windowBeep can be configured in many ways, depending on the windowing backend and the desktop environment or window manager that is used.

Since: 2.12

event

widgetEvent Source #

Arguments

:: (HasCallStack, MonadIO m, IsWidget a) 
=> a

widget: a Widget

-> Event

event: a Event

-> m Bool

Returns: return from the event signal emission (True if the event was handled)

Rarely-used function. This function is used to emit the event signals on a widget (those signals should never be emitted without using this function to do so). If you want to synthesize an event though, don’t use this function; instead, use mainDoEvent so the event will behave as if it were in the event queue. Don’t synthesize expose events; instead, use windowInvalidateRect to invalidate a region of the window.

freezeChildNotify

widgetFreezeChildNotify Source #

Arguments

:: (HasCallStack, MonadIO m, IsWidget a) 
=> a

widget: a Widget

-> m () 

Stops emission of Widget::child-notify signals on widget. The signals are queued until widgetThawChildNotify is called on widget.

This is the analogue of objectFreezeNotify for child properties.

getAccessible

widgetGetAccessible Source #

Arguments

:: (HasCallStack, MonadIO m, IsWidget a) 
=> a

widget: a Widget

-> m Object

Returns: the Object associated with widget

Returns the accessible object that describes the widget to an assistive technology.

If accessibility support is not available, this Object instance may be a no-op. Likewise, if no class-specific Object implementation is available for the widget instance in question, it will inherit an Object implementation from the first ancestor class for which such an implementation is defined.

The documentation of the ATK library contains more information about accessible objects and their uses.

getActionGroup

widgetGetActionGroup Source #

Arguments

:: (HasCallStack, MonadIO m, IsWidget a) 
=> a

widget: A Widget

-> Text

prefix: The “prefix” of the action group.

-> m (Maybe ActionGroup)

Returns: A ActionGroup or Nothing.

Retrieves the ActionGroup that was registered using prefix. The resulting ActionGroup may have been registered to widget or any Widget in its ancestry.

If no action group was found matching prefix, then Nothing is returned.

Since: 3.16

getAllocatedBaseline

widgetGetAllocatedBaseline Source #

Arguments

:: (HasCallStack, MonadIO m, IsWidget a) 
=> a

widget: the widget to query

-> m Int32

Returns: the baseline of the widget, or -1 if none

Returns the baseline that has currently been allocated to widget. This function is intended to be used when implementing handlers for the Widget::draw function, and when allocating child widgets in Widget::size_allocate.

Since: 3.10

getAllocatedHeight

widgetGetAllocatedHeight Source #

Arguments

:: (HasCallStack, MonadIO m, IsWidget a) 
=> a

widget: the widget to query

-> m Int32

Returns: the height of the widget

Returns the height that has currently been allocated to widget. This function is intended to be used when implementing handlers for the Widget::draw function.

getAllocatedSize

widgetGetAllocatedSize Source #

Arguments

:: (HasCallStack, MonadIO m, IsWidget a) 
=> a

widget: a Widget

-> m (Rectangle, Int32) 

Retrieves the widget’s allocated size.

This function returns the last values passed to widgetSizeAllocateWithBaseline. The value differs from the size returned in widgetGetAllocation in that functions like widgetSetHalign can adjust the allocation, but not the value returned by this function.

If a widget is not visible, its allocated size is 0.

Since: 3.20

getAllocatedWidth

widgetGetAllocatedWidth Source #

Arguments

:: (HasCallStack, MonadIO m, IsWidget a) 
=> a

widget: the widget to query

-> m Int32

Returns: the width of the widget

Returns the width that has currently been allocated to widget. This function is intended to be used when implementing handlers for the Widget::draw function.

getAllocation

widgetGetAllocation Source #

Arguments

:: (HasCallStack, MonadIO m, IsWidget a) 
=> a

widget: a Widget

-> m Rectangle 

Retrieves the widget’s allocation.

Note, when implementing a Container: a widget’s allocation will be its “adjusted” allocation, that is, the widget’s parent container typically calls widgetSizeAllocate with an allocation, and that allocation is then adjusted (to handle margin and alignment for example) before assignment to the widget. widgetGetAllocation returns the adjusted allocation that was actually assigned to the widget. The adjusted allocation is guaranteed to be completely contained within the widgetSizeAllocate allocation, however. So a Container is guaranteed that its children stay inside the assigned bounds, but not that they have exactly the bounds the container assigned. There is no way to get the original allocation assigned by widgetSizeAllocate, since it isn’t stored; if a container implementation needs that information it will have to track it itself.

Since: 2.18

getAncestor

widgetGetAncestor Source #

Arguments

:: (HasCallStack, MonadIO m, IsWidget a) 
=> a

widget: a Widget

-> GType

widgetType: ancestor type

-> m (Maybe Widget)

Returns: the ancestor widget, or Nothing if not found

Gets the first ancestor of widget with type widgetType. For example, gtk_widget_get_ancestor (widget, GTK_TYPE_BOX) gets the first Box that’s an ancestor of widget. No reference will be added to the returned widget; it should not be unreferenced. See note about checking for a toplevel Window in the docs for widgetGetToplevel.

Note that unlike widgetIsAncestor, widgetGetAncestor considers widget to be an ancestor of itself.

getAppPaintable

widgetGetAppPaintable Source #

Arguments

:: (HasCallStack, MonadIO m, IsWidget a) 
=> a

widget: a Widget

-> m Bool

Returns: True if the widget is app paintable

Determines whether the application intends to draw on the widget in an Widget::draw handler.

See widgetSetAppPaintable

Since: 2.18

getCanDefault

widgetGetCanDefault Source #

Arguments

:: (HasCallStack, MonadIO m, IsWidget a) 
=> a

widget: a Widget

-> m Bool

Returns: True if widget can be a default widget, False otherwise

Determines whether widget can be a default widget. See widgetSetCanDefault.

Since: 2.18

getCanFocus

widgetGetCanFocus Source #

Arguments

:: (HasCallStack, MonadIO m, IsWidget a) 
=> a

widget: a Widget

-> m Bool

Returns: True if widget can own the input focus, False otherwise

Determines whether widget can own the input focus. See widgetSetCanFocus.

Since: 2.18

getChildRequisition

widgetGetChildRequisition Source #

Arguments

:: (HasCallStack, MonadIO m, IsWidget a) 
=> a

widget: a Widget

-> m Requisition 

Deprecated: (Since version 3.0)Use widgetGetPreferredSize instead.

This function is only for use in widget implementations. Obtains widget->requisition, unless someone has forced a particular geometry on the widget (e.g. with widgetSetSizeRequest), in which case it returns that geometry instead of the widget's requisition.

This function differs from widgetSizeRequest in that it retrieves the last size request value from widget->requisition, while widgetSizeRequest actually calls the "size_request" method on widget to compute the size request and fill in widget->requisition, and only then returns widget->requisition.

Because this function does not call the “size_request” method, it can only be used when you know that widget->requisition is up-to-date, that is, widgetSizeRequest has been called since the last time a resize was queued. In general, only container implementations have this information; applications should use widgetSizeRequest.

getChildVisible

widgetGetChildVisible Source #

Arguments

:: (HasCallStack, MonadIO m, IsWidget a) 
=> a

widget: a Widget

-> m Bool

Returns: True if the widget is mapped with the parent.

Gets the value set with widgetSetChildVisible. If you feel a need to use this function, your code probably needs reorganization.

This function is only useful for container implementations and never should be called by an application.

getClip

widgetGetClip Source #

Arguments

:: (HasCallStack, MonadIO m, IsWidget a) 
=> a

widget: a Widget

-> m Rectangle 

Retrieves the widget’s clip area.

The clip area is the area in which all of widget's drawing will happen. Other toolkits call it the bounding box.

Historically, in GTK+ the clip area has been equal to the allocation retrieved via widgetGetAllocation.

Since: 3.14

getClipboard

widgetGetClipboard Source #

Arguments

:: (HasCallStack, MonadIO m, IsWidget a) 
=> a

widget: a Widget

-> Atom

selection: a Atom which identifies the clipboard to use. GDK_SELECTION_CLIPBOARD gives the default clipboard. Another common value is GDK_SELECTION_PRIMARY, which gives the primary X selection.

-> m Clipboard

Returns: the appropriate clipboard object. If no clipboard already exists, a new one will be created. Once a clipboard object has been created, it is persistent for all time.

Returns the clipboard object for the given selection to be used with widget. widget must have a Display associated with it, so must be attached to a toplevel window.

Since: 2.2

getCompositeName

widgetGetCompositeName Source #

Arguments

:: (HasCallStack, MonadIO m, IsWidget a) 
=> a

widget: a Widget

-> m Text

Returns: the composite name of widget, or Nothing if widget is not a composite child. The string should be freed when it is no longer needed.

Deprecated: (Since version 3.10)Use widgetClassSetTemplate, or don’t use this API at all.

Obtains the composite name of a widget.

getDefaultDirection

widgetGetDefaultDirection Source #

Arguments

:: (HasCallStack, MonadIO m) 
=> m TextDirection

Returns: the current default direction.

Obtains the current default reading direction. See widgetSetDefaultDirection.

getDefaultStyle

widgetGetDefaultStyle Source #

Arguments

:: (HasCallStack, MonadIO m) 
=> m Style

Returns: the default style. This Style object is owned by GTK+ and should not be modified or freed.

Deprecated: (Since version 3.0)Use StyleContext instead, and cssProviderGetDefault to obtain a StyleProvider with the default widget style information.

Returns the default style used by all widgets initially.

getDeviceEnabled

widgetGetDeviceEnabled Source #

Arguments

:: (HasCallStack, MonadIO m, IsWidget a, IsDevice b) 
=> a

widget: a Widget

-> b

device: a Device

-> m Bool

Returns: True is device is enabled for widget

Returns whether device can interact with widget and its children. See widgetSetDeviceEnabled.

Since: 3.0

getDeviceEvents

widgetGetDeviceEvents Source #

Arguments

:: (HasCallStack, MonadIO m, IsWidget a, IsDevice b) 
=> a

widget: a Widget

-> b

device: a Device

-> m [EventMask]

Returns: device event mask for widget

Returns the events mask for the widget corresponding to an specific device. These are the events that the widget will receive when device operates on it.

Since: 3.0

getDirection

widgetGetDirection Source #

Arguments

:: (HasCallStack, MonadIO m, IsWidget a) 
=> a

widget: a Widget

-> m TextDirection

Returns: the reading direction for the widget.

Gets the reading direction for a particular widget. See widgetSetDirection.

getDisplay

widgetGetDisplay Source #

Arguments

:: (HasCallStack, MonadIO m, IsWidget a) 
=> a

widget: a Widget

-> m Display

Returns: the Display for the toplevel for this widget.

Get the Display for the toplevel window associated with this widget. This function can only be called after the widget has been added to a widget hierarchy with a Window at the top.

In general, you should only create display specific resources when a widget has been realized, and you should free those resources when the widget is unrealized.

Since: 2.2

getDoubleBuffered

widgetGetDoubleBuffered Source #

Arguments

:: (HasCallStack, MonadIO m, IsWidget a) 
=> a

widget: a Widget

-> m Bool

Returns: True if the widget is double buffered

Determines whether the widget is double buffered.

See widgetSetDoubleBuffered

Since: 2.18

getEvents

widgetGetEvents Source #

Arguments

:: (HasCallStack, MonadIO m, IsWidget a) 
=> a

widget: a Widget

-> m Int32

Returns: event mask for widget

Returns the event mask (see EventMask) for the widget. These are the events that the widget will receive.

Note: Internally, the widget event mask will be the logical OR of the event mask set through widgetSetEvents or widgetAddEvents, and the event mask necessary to cater for every EventController created for the widget.

getFocusOnClick

widgetGetFocusOnClick Source #

Arguments

:: (HasCallStack, MonadIO m, IsWidget a) 
=> a

widget: a Widget

-> m Bool

Returns: True if the widget should grab focus when it is clicked with the mouse.

Returns whether the widget should grab focus when it is clicked with the mouse. See widgetSetFocusOnClick.

Since: 3.20

getFontMap

widgetGetFontMap Source #

Arguments

:: (HasCallStack, MonadIO m, IsWidget a) 
=> a

widget: a Widget

-> m (Maybe FontMap)

Returns: A FontMap, or Nothing

Gets the font map that has been set with widgetSetFontMap.

Since: 3.18

getFontOptions

widgetGetFontOptions Source #

Arguments

:: (HasCallStack, MonadIO m, IsWidget a) 
=> a

widget: a Widget

-> m (Maybe FontOptions)

Returns: the FontOptions or Nothing if not set

Returns the FontOptions used for Pango rendering. When not set, the defaults font options for the Screen will be used.

Since: 3.18

getFrameClock

widgetGetFrameClock Source #

Arguments

:: (HasCallStack, MonadIO m, IsWidget a) 
=> a

widget: a Widget

-> m (Maybe FrameClock)

Returns: a FrameClock, or Nothing if widget is unrealized

Obtains the frame clock for a widget. The frame clock is a global “ticker” that can be used to drive animations and repaints. The most common reason to get the frame clock is to call frameClockGetFrameTime, in order to get a time to use for animating. For example you might record the start of the animation with an initial value from frameClockGetFrameTime, and then update the animation by calling frameClockGetFrameTime again during each repaint.

frameClockRequestPhase will result in a new frame on the clock, but won’t necessarily repaint any widgets. To repaint a widget, you have to use widgetQueueDraw which invalidates the widget (thus scheduling it to receive a draw on the next frame). widgetQueueDraw will also end up requesting a frame on the appropriate frame clock.

A widget’s frame clock will not change while the widget is mapped. Reparenting a widget (which implies a temporary unmap) can change the widget’s frame clock.

Unrealized widgets do not have a frame clock.

Since: 3.8

getHalign

widgetGetHalign Source #

Arguments

:: (HasCallStack, MonadIO m, IsWidget a) 
=> a

widget: a Widget

-> m Align

Returns: the horizontal alignment of widget

Gets the value of the Widget:halign property.

For backwards compatibility reasons this method will never return AlignBaseline, but instead it will convert it to AlignFill. Baselines are not supported for horizontal alignment.

getHasTooltip

widgetGetHasTooltip Source #

Arguments

:: (HasCallStack, MonadIO m, IsWidget a) 
=> a

widget: a Widget

-> m Bool

Returns: current value of has-tooltip on widget.

Returns the current value of the has-tooltip property. See Widget:has-tooltip for more information.

Since: 2.12

getHasWindow

widgetGetHasWindow Source #

Arguments

:: (HasCallStack, MonadIO m, IsWidget a) 
=> a

widget: a Widget

-> m Bool

Returns: True if widget has a window, False otherwise

Determines whether widget has a Window of its own. See widgetSetHasWindow.

Since: 2.18

getHexpand

widgetGetHexpand Source #

Arguments

:: (HasCallStack, MonadIO m, IsWidget a) 
=> a

widget: the widget

-> m Bool

Returns: whether hexpand flag is set

Gets whether the widget would like any available extra horizontal space. When a user resizes a Window, widgets with expand=TRUE generally receive the extra space. For example, a list or scrollable area or document in your window would often be set to expand.

Containers should use widgetComputeExpand rather than this function, to see whether a widget, or any of its children, has the expand flag set. If any child of a widget wants to expand, the parent may ask to expand also.

This function only looks at the widget’s own hexpand flag, rather than computing whether the entire widget tree rooted at this widget wants to expand.

getHexpandSet

widgetGetHexpandSet Source #

Arguments

:: (HasCallStack, MonadIO m, IsWidget a) 
=> a

widget: the widget

-> m Bool

Returns: whether hexpand has been explicitly set

Gets whether widgetSetHexpand has been used to explicitly set the expand flag on this widget.

If hexpand is set, then it overrides any computed expand value based on child widgets. If hexpand is not set, then the expand value depends on whether any children of the widget would like to expand.

There are few reasons to use this function, but it’s here for completeness and consistency.

getMapped

widgetGetMapped Source #

Arguments

:: (HasCallStack, MonadIO m, IsWidget a) 
=> a

widget: a Widget

-> m Bool

Returns: True if the widget is mapped, False otherwise.

Whether the widget is mapped.

Since: 2.20

getMarginBottom

widgetGetMarginBottom Source #

Arguments

:: (HasCallStack, MonadIO m, IsWidget a) 
=> a

widget: a Widget

-> m Int32

Returns: The bottom margin of widget

Gets the value of the Widget:margin-bottom property.

Since: 3.0

getMarginEnd

widgetGetMarginEnd Source #

Arguments

:: (HasCallStack, MonadIO m, IsWidget a) 
=> a

widget: a Widget

-> m Int32

Returns: The end margin of widget

Gets the value of the Widget:margin-end property.

Since: 3.12

getMarginLeft

widgetGetMarginLeft Source #

Arguments

:: (HasCallStack, MonadIO m, IsWidget a) 
=> a

widget: a Widget

-> m Int32

Returns: The left margin of widget

Deprecated: (Since version 3.12)Use widgetGetMarginStart instead.

Gets the value of the Widget:margin-left property.

Since: 3.0

getMarginRight

widgetGetMarginRight Source #

Arguments

:: (HasCallStack, MonadIO m, IsWidget a) 
=> a

widget: a Widget

-> m Int32

Returns: The right margin of widget

Deprecated: (Since version 3.12)Use widgetGetMarginEnd instead.

Gets the value of the Widget:margin-right property.

Since: 3.0

getMarginStart

widgetGetMarginStart Source #

Arguments

:: (HasCallStack, MonadIO m, IsWidget a) 
=> a

widget: a Widget

-> m Int32

Returns: The start margin of widget

Gets the value of the Widget:margin-start property.

Since: 3.12

getMarginTop

widgetGetMarginTop Source #

Arguments

:: (HasCallStack, MonadIO m, IsWidget a) 
=> a

widget: a Widget

-> m Int32

Returns: The top margin of widget

Gets the value of the Widget:margin-top property.

Since: 3.0

getModifierMask

widgetGetModifierMask Source #

Arguments

:: (HasCallStack, MonadIO m, IsWidget a) 
=> a

widget: a Widget

-> ModifierIntent

intent: the use case for the modifier mask

-> m [ModifierType]

Returns: the modifier mask used for intent.

Returns the modifier mask the widget’s windowing system backend uses for a particular purpose.

See keymapGetModifierMask.

Since: 3.4

getModifierStyle

widgetGetModifierStyle Source #

Arguments

:: (HasCallStack, MonadIO m, IsWidget a) 
=> a

widget: a Widget

-> m RcStyle

Returns: the modifier style for the widget. This rc style is owned by the widget. If you want to keep a pointer to value this around, you must add a refcount using objectRef.

Deprecated: (Since version 3.0)Use StyleContext with a custom StyleProvider instead

Returns the current modifier style for the widget. (As set by widgetModifyStyle.) If no style has previously set, a new RcStyle will be created with all values unset, and set as the modifier style for the widget. If you make changes to this rc style, you must call widgetModifyStyle, passing in the returned rc style, to make sure that your changes take effect.

Caution: passing the style back to widgetModifyStyle will normally end up destroying it, because widgetModifyStyle copies the passed-in style and sets the copy as the new modifier style, thus dropping any reference to the old modifier style. Add a reference to the modifier style if you want to keep it alive.

getName

widgetGetName Source #

Arguments

:: (HasCallStack, MonadIO m, IsWidget a) 
=> a

widget: a Widget

-> m Text

Returns: name of the widget. This string is owned by GTK+ and should not be modified or freed

Retrieves the name of a widget. See widgetSetName for the significance of widget names.

getNoShowAll

widgetGetNoShowAll Source #

Arguments

:: (HasCallStack, MonadIO m, IsWidget a) 
=> a

widget: a Widget

-> m Bool

Returns: the current value of the “no-show-all” property.

Returns the current value of the Widget:no-show-all property, which determines whether calls to widgetShowAll will affect this widget.

Since: 2.4

getOpacity

widgetGetOpacity Source #

Arguments

:: (HasCallStack, MonadIO m, IsWidget a) 
=> a

widget: a Widget

-> m Double

Returns: the requested opacity for this widget.

Fetches the requested opacity for this widget. See widgetSetOpacity.

Since: 3.8

getPangoContext

widgetGetPangoContext Source #

Arguments

:: (HasCallStack, MonadIO m, IsWidget a) 
=> a

widget: a Widget

-> m Context

Returns: the Context for the widget.

Gets a Context with the appropriate font map, font description, and base direction for this widget. Unlike the context returned by widgetCreatePangoContext, this context is owned by the widget (it can be used until the screen for the widget changes or the widget is removed from its toplevel), and will be updated to match any changes to the widget’s attributes. This can be tracked by using the Widget::screen-changed signal on the widget.

getParent

widgetGetParent Source #

Arguments

:: (HasCallStack, MonadIO m, IsWidget a) 
=> a

widget: a Widget

-> m (Maybe Widget)

Returns: the parent container of widget, or Nothing

Returns the parent container of widget.

getParentWindow

widgetGetParentWindow Source #

Arguments

:: (HasCallStack, MonadIO m, IsWidget a) 
=> a

widget: a Widget.

-> m (Maybe Window)

Returns: the parent window of widget, or Nothing if it does not have a parent window.

Gets widget’s parent window, or Nothing if it does not have one.

getPath

widgetGetPath Source #

Arguments

:: (HasCallStack, MonadIO m, IsWidget a) 
=> a

widget: a Widget

-> m WidgetPath

Returns: The WidgetPath representing widget

Returns the WidgetPath representing widget, if the widget is not connected to a toplevel widget, a partial path will be created.

getPointer

widgetGetPointer Source #

Arguments

:: (HasCallStack, MonadIO m, IsWidget a) 
=> a

widget: a Widget

-> m (Int32, Int32) 

Deprecated: (Since version 3.4)Use windowGetDevicePosition instead.

Obtains the location of the mouse pointer in widget coordinates. Widget coordinates are a bit odd; for historical reasons, they are defined as widget->window coordinates for widgets that return True for widgetGetHasWindow; and are relative to widget->allocation.x, widget->allocation.y otherwise.

getPreferredHeight

widgetGetPreferredHeight Source #

Arguments

:: (HasCallStack, MonadIO m, IsWidget a) 
=> a

widget: a Widget instance

-> m (Int32, Int32) 

Retrieves a widget’s initial minimum and natural height.

This call is specific to width-for-height requests.

The returned request will be modified by the GtkWidgetClass::adjust_size_request virtual method and by any GtkSizeGroups that have been applied. That is, the returned request is the one that should be used for layout, not necessarily the one returned by the widget itself.

Since: 3.0

getPreferredHeightAndBaselineForWidth

widgetGetPreferredHeightAndBaselineForWidth Source #

Arguments

:: (HasCallStack, MonadIO m, IsWidget a) 
=> a

widget: a Widget instance

-> Int32

width: the width which is available for allocation, or -1 if none

-> m (Int32, Int32, Int32, Int32) 

Retrieves a widget’s minimum and natural height and the corresponding baselines if it would be given the specified width, or the default height if width is -1. The baselines may be -1 which means that no baseline is requested for this widget.

The returned request will be modified by the GtkWidgetClass::adjust_size_request and GtkWidgetClass::adjust_baseline_request virtual methods and by any GtkSizeGroups that have been applied. That is, the returned request is the one that should be used for layout, not necessarily the one returned by the widget itself.

Since: 3.10

getPreferredHeightForWidth

widgetGetPreferredHeightForWidth Source #

Arguments

:: (HasCallStack, MonadIO m, IsWidget a) 
=> a

widget: a Widget instance

-> Int32

width: the width which is available for allocation

-> m (Int32, Int32) 

Retrieves a widget’s minimum and natural height if it would be given the specified width.

The returned request will be modified by the GtkWidgetClass::adjust_size_request virtual method and by any GtkSizeGroups that have been applied. That is, the returned request is the one that should be used for layout, not necessarily the one returned by the widget itself.

Since: 3.0

getPreferredSize

widgetGetPreferredSize Source #

Arguments

:: (HasCallStack, MonadIO m, IsWidget a) 
=> a

widget: a Widget instance

-> m (Requisition, Requisition) 

Retrieves the minimum and natural size of a widget, taking into account the widget’s preference for height-for-width management.

This is used to retrieve a suitable size by container widgets which do not impose any restrictions on the child placement. It can be used to deduce toplevel window and menu sizes as well as child widgets in free-form containers such as GtkLayout.

Handle with care. Note that the natural height of a height-for-width widget will generally be a smaller size than the minimum height, since the required height for the natural width is generally smaller than the required height for the minimum width.

Use widgetGetPreferredHeightAndBaselineForWidth if you want to support baseline alignment.

Since: 3.0

getPreferredWidth

widgetGetPreferredWidth Source #

Arguments

:: (HasCallStack, MonadIO m, IsWidget a) 
=> a

widget: a Widget instance

-> m (Int32, Int32) 

Retrieves a widget’s initial minimum and natural width.

This call is specific to height-for-width requests.

The returned request will be modified by the GtkWidgetClass::adjust_size_request virtual method and by any GtkSizeGroups that have been applied. That is, the returned request is the one that should be used for layout, not necessarily the one returned by the widget itself.

Since: 3.0

getPreferredWidthForHeight

widgetGetPreferredWidthForHeight Source #

Arguments

:: (HasCallStack, MonadIO m, IsWidget a) 
=> a

widget: a Widget instance

-> Int32

height: the height which is available for allocation

-> m (Int32, Int32) 

Retrieves a widget’s minimum and natural width if it would be given the specified height.

The returned request will be modified by the GtkWidgetClass::adjust_size_request virtual method and by any GtkSizeGroups that have been applied. That is, the returned request is the one that should be used for layout, not necessarily the one returned by the widget itself.

Since: 3.0

getRealized

widgetGetRealized Source #

Arguments

:: (HasCallStack, MonadIO m, IsWidget a) 
=> a

widget: a Widget

-> m Bool

Returns: True if widget is realized, False otherwise

Determines whether widget is realized.

Since: 2.20

getReceivesDefault

widgetGetReceivesDefault Source #

Arguments

:: (HasCallStack, MonadIO m, IsWidget a) 
=> a

widget: a Widget

-> m Bool

Returns: True if widget acts as the default widget when focused, False otherwise

Determines whether widget is always treated as the default widget within its toplevel when it has the focus, even if another widget is the default.

See widgetSetReceivesDefault.

Since: 2.18

getRequestMode

widgetGetRequestMode Source #

Arguments

:: (HasCallStack, MonadIO m, IsWidget a) 
=> a

widget: a Widget instance

-> m SizeRequestMode

Returns: The SizeRequestMode preferred by widget.

Gets whether the widget prefers a height-for-width layout or a width-for-height layout.

Bin widgets generally propagate the preference of their child, container widgets need to request something either in context of their children or in context of their allocation capabilities.

Since: 3.0

getRequisition

widgetGetRequisition Source #

Arguments

:: (HasCallStack, MonadIO m, IsWidget a) 
=> a

widget: a Widget

-> m Requisition 

Deprecated: (Since version 3.0)The Requisition cache on the widget wasremoved, If you need to cache sizes across requests and allocations,add an explicit cache to the widget in question instead.

Retrieves the widget’s requisition.

This function should only be used by widget implementations in order to figure whether the widget’s requisition has actually changed after some internal state change (so that they can call widgetQueueResize instead of widgetQueueDraw).

Normally, widgetSizeRequest should be used.

Since: 2.20

getRootWindow

widgetGetRootWindow Source #

Arguments

:: (HasCallStack, MonadIO m, IsWidget a) 
=> a

widget: a Widget

-> m Window

Returns: the Window root window for the toplevel for this widget.

Deprecated: (Since version 3.12)Use screenGetRootWindow instead

Get the root window where this widget is located. This function can only be called after the widget has been added to a widget hierarchy with Window at the top.

The root window is useful for such purposes as creating a popup Window associated with the window. In general, you should only create display specific resources when a widget has been realized, and you should free those resources when the widget is unrealized.

Since: 2.2

getScaleFactor

widgetGetScaleFactor Source #

Arguments

:: (HasCallStack, MonadIO m, IsWidget a) 
=> a

widget: a Widget

-> m Int32

Returns: the scale factor for widget

Retrieves the internal scale factor that maps from window coordinates to the actual device pixels. On traditional systems this is 1, on high density outputs, it can be a higher value (typically 2).

See windowGetScaleFactor.

Since: 3.10

getScreen

widgetGetScreen Source #

Arguments

:: (HasCallStack, MonadIO m, IsWidget a) 
=> a

widget: a Widget

-> m Screen

Returns: the Screen for the toplevel for this widget.

Get the Screen from the toplevel window associated with this widget. This function can only be called after the widget has been added to a widget hierarchy with a Window at the top.

In general, you should only create screen specific resources when a widget has been realized, and you should free those resources when the widget is unrealized.

Since: 2.2

getSensitive

widgetGetSensitive Source #

Arguments

:: (HasCallStack, MonadIO m, IsWidget a) 
=> a

widget: a Widget

-> m Bool

Returns: True if the widget is sensitive

Returns the widget’s sensitivity (in the sense of returning the value that has been set using widgetSetSensitive).

The effective sensitivity of a widget is however determined by both its own and its parent widget’s sensitivity. See widgetIsSensitive.

Since: 2.18

getSettings

widgetGetSettings Source #

Arguments

:: (HasCallStack, MonadIO m, IsWidget a) 
=> a

widget: a Widget

-> m Settings

Returns: the relevant Settings object

Gets the settings object holding the settings used for this widget.

Note that this function can only be called when the Widget is attached to a toplevel, since the settings object is specific to a particular Screen.

getSizeRequest

widgetGetSizeRequest Source #

Arguments

:: (HasCallStack, MonadIO m, IsWidget a) 
=> a

widget: a Widget

-> m (Int32, Int32) 

Gets the size request that was explicitly set for the widget using widgetSetSizeRequest. A value of -1 stored in width or height indicates that that dimension has not been set explicitly and the natural requisition of the widget will be used instead. See widgetSetSizeRequest. To get the size a widget will actually request, call widgetGetPreferredSize instead of this function.

getState

widgetGetState Source #

Arguments

:: (HasCallStack, MonadIO m, IsWidget a) 
=> a

widget: a Widget

-> m StateType

Returns: the state of widget.

Deprecated: (Since version 3.0)Use widgetGetStateFlags instead.

Returns the widget’s state. See widgetSetState.

Since: 2.18

getStateFlags

widgetGetStateFlags Source #

Arguments

:: (HasCallStack, MonadIO m, IsWidget a) 
=> a

widget: a Widget

-> m [StateFlags]

Returns: The state flags for widget

Returns the widget state as a flag set. It is worth mentioning that the effective StateFlagsInsensitive state will be returned, that is, also based on parent insensitivity, even if widget itself is sensitive.

Also note that if you are looking for a way to obtain the StateFlags to pass to a StyleContext method, you should look at styleContextGetState.

Since: 3.0

getStyle

widgetGetStyle Source #

Arguments

:: (HasCallStack, MonadIO m, IsWidget a) 
=> a

widget: a Widget

-> m Style

Returns: the widget’s Style

Deprecated: (Since version 3.0)Use StyleContext instead

Simply an accessor function that returns widget->style.

getStyleContext

widgetGetStyleContext Source #

Arguments

:: (HasCallStack, MonadIO m, IsWidget a) 
=> a

widget: a Widget

-> m StyleContext

Returns: a StyleContext. This memory is owned by widget and must not be freed.

Returns the style context associated to widget. The returned object is guaranteed to be the same for the lifetime of widget.

getSupportMultidevice

widgetGetSupportMultidevice Source #

Arguments

:: (HasCallStack, MonadIO m, IsWidget a) 
=> a

widget: a Widget

-> m Bool

Returns: True if widget is multidevice aware.

Returns True if widget is multiple pointer aware. See widgetSetSupportMultidevice for more information.

getTemplateChild

widgetGetTemplateChild Source #

Arguments

:: (HasCallStack, MonadIO m, IsWidget a) 
=> a

widget: A Widget

-> GType

widgetType: The GType to get a template child for

-> Text

name: The “id” of the child defined in the template XML

-> m Object

Returns: The object built in the template XML with the id name

Fetch an object build from the template XML for widgetType in this widget instance.

This will only report children which were previously declared with widgetClassBindTemplateChildFull or one of its variants.

This function is only meant to be called for code which is private to the widgetType which declared the child and is meant for language bindings which cannot easily make use of the GObject structure offsets.

getTooltipMarkup

widgetGetTooltipMarkup Source #

Arguments

:: (HasCallStack, MonadIO m, IsWidget a) 
=> a

widget: a Widget

-> m (Maybe Text)

Returns: the tooltip text, or Nothing. You should free the returned string with free when done.

Gets the contents of the tooltip for widget.

Since: 2.12

getTooltipText

widgetGetTooltipText Source #

Arguments

:: (HasCallStack, MonadIO m, IsWidget a) 
=> a

widget: a Widget

-> m (Maybe Text)

Returns: the tooltip text, or Nothing. You should free the returned string with free when done.

Gets the contents of the tooltip for widget.

Since: 2.12

getTooltipWindow

widgetGetTooltipWindow Source #

Arguments

:: (HasCallStack, MonadIO m, IsWidget a) 
=> a

widget: a Widget

-> m Window

Returns: The Window of the current tooltip.

Returns the Window of the current tooltip. This can be the GtkWindow created by default, or the custom tooltip window set using widgetSetTooltipWindow.

Since: 2.12

getToplevel

widgetGetToplevel Source #

Arguments

:: (HasCallStack, MonadIO m, IsWidget a) 
=> a

widget: a Widget

-> m Widget

Returns: the topmost ancestor of widget, or widget itself if there’s no ancestor.

This function returns the topmost widget in the container hierarchy widget is a part of. If widget has no parent widgets, it will be returned as the topmost widget. No reference will be added to the returned widget; it should not be unreferenced.

Note the difference in behavior vs. widgetGetAncestor; gtk_widget_get_ancestor (widget, GTK_TYPE_WINDOW) would return Nothing if widget wasn’t inside a toplevel window, and if the window was inside a Window-derived widget which was in turn inside the toplevel Window. While the second case may seem unlikely, it actually happens when a Plug is embedded inside a Socket within the same application.

To reliably find the toplevel Window, use widgetGetToplevel and call GTK_IS_WINDOW() on the result. For instance, to get the title of a widget's toplevel window, one might use:

C code

static const char *
get_widget_toplevel_title (GtkWidget *widget)
{
  GtkWidget *toplevel = gtk_widget_get_toplevel (widget);
  if (GTK_IS_WINDOW (toplevel))
    {
      return gtk_window_get_title (GTK_WINDOW (toplevel));
    }

  return NULL;
}

getValign

widgetGetValign Source #

Arguments

:: (HasCallStack, MonadIO m, IsWidget a) 
=> a

widget: a Widget

-> m Align

Returns: the vertical alignment of widget, ignoring baseline alignment

Gets the value of the Widget:valign property.

For backwards compatibility reasons this method will never return AlignBaseline, but instead it will convert it to AlignFill. If your widget want to support baseline aligned children it must use widgetGetValignWithBaseline, or g_object_get (widget, "valign", &value, NULL), which will also report the true value.

getValignWithBaseline

widgetGetValignWithBaseline Source #

Arguments

:: (HasCallStack, MonadIO m, IsWidget a) 
=> a

widget: a Widget

-> m Align

Returns: the vertical alignment of widget

Gets the value of the Widget:valign property, including AlignBaseline.

Since: 3.10

getVexpand

widgetGetVexpand Source #

Arguments

:: (HasCallStack, MonadIO m, IsWidget a) 
=> a

widget: the widget

-> m Bool

Returns: whether vexpand flag is set

Gets whether the widget would like any available extra vertical space.

See widgetGetHexpand for more detail.

getVexpandSet

widgetGetVexpandSet Source #

Arguments

:: (HasCallStack, MonadIO m, IsWidget a) 
=> a

widget: the widget

-> m Bool

Returns: whether vexpand has been explicitly set

Gets whether widgetSetVexpand has been used to explicitly set the expand flag on this widget.

See widgetGetHexpandSet for more detail.

getVisible

widgetGetVisible Source #

Arguments

:: (HasCallStack, MonadIO m, IsWidget a) 
=> a

widget: a Widget

-> m Bool

Returns: True if the widget is visible

Determines whether the widget is visible. If you want to take into account whether the widget’s parent is also marked as visible, use widgetIsVisible instead.

This function does not check if the widget is obscured in any way.

See widgetSetVisible.

Since: 2.18

getVisual

widgetGetVisual Source #

Arguments

:: (HasCallStack, MonadIO m, IsWidget a) 
=> a

widget: a Widget

-> m Visual

Returns: the visual for widget

Gets the visual that will be used to render widget.

getWindow

widgetGetWindow Source #

Arguments

:: (HasCallStack, MonadIO m, IsWidget a) 
=> a

widget: a Widget

-> m (Maybe Window)

Returns: widget’s window.

Returns the widget’s window if it is realized, Nothing otherwise

Since: 2.14

grabAdd

widgetGrabAdd Source #

Arguments

:: (HasCallStack, MonadIO m, IsWidget a) 
=> a

widget: The widget that grabs keyboard and pointer events

-> m () 

Makes widget the current grabbed widget.

This means that interaction with other widgets in the same application is blocked and mouse as well as keyboard events are delivered to this widget.

If widget is not sensitive, it is not set as the current grabbed widget and this function does nothing.

grabDefault

widgetGrabDefault Source #

Arguments

:: (HasCallStack, MonadIO m, IsWidget a) 
=> a

widget: a Widget

-> m () 

Causes widget to become the default widget. widget must be able to be a default widget; typically you would ensure this yourself by calling widgetSetCanDefault with a True value. The default widget is activated when the user presses Enter in a window. Default widgets must be activatable, that is, widgetActivate should affect them. Note that Entry widgets require the “activates-default” property set to True before they activate the default widget when Enter is pressed and the Entry is focused.

grabFocus

widgetGrabFocus Source #

Arguments

:: (HasCallStack, MonadIO m, IsWidget a) 
=> a

widget: a Widget

-> m () 

Causes widget to have the keyboard focus for the Window it's inside. widget must be a focusable widget, such as a Entry; something like Frame won’t work.

More precisely, it must have the GTK_CAN_FOCUS flag set. Use widgetSetCanFocus to modify that flag.

The widget also needs to be realized and mapped. This is indicated by the related signals. Grabbing the focus immediately after creating the widget will likely fail and cause critical warnings.

grabRemove

widgetGrabRemove Source #

Arguments

:: (HasCallStack, MonadIO m, IsWidget a) 
=> a

widget: The widget which gives up the grab

-> m () 

Removes the grab from the given widget.

You have to pair calls to widgetGrabAdd and widgetGrabRemove.

If widget does not have the grab, this function does nothing.

hasDefault

widgetHasDefault Source #

Arguments

:: (HasCallStack, MonadIO m, IsWidget a) 
=> a

widget: a Widget

-> m Bool

Returns: True if widget is the current default widget within its toplevel, False otherwise

Determines whether widget is the current default widget within its toplevel. See widgetSetCanDefault.

Since: 2.18

hasFocus

widgetHasFocus Source #

Arguments

:: (HasCallStack, MonadIO m, IsWidget a) 
=> a

widget: a Widget

-> m Bool

Returns: True if the widget has the global input focus.

Determines if the widget has the global input focus. See widgetIsFocus for the difference between having the global input focus, and only having the focus within a toplevel.

Since: 2.18

hasGrab

widgetHasGrab Source #

Arguments

:: (HasCallStack, MonadIO m, IsWidget a) 
=> a

widget: a Widget

-> m Bool

Returns: True if the widget is in the grab_widgets stack

Determines whether the widget is currently grabbing events, so it is the only widget receiving input events (keyboard and mouse).

See also widgetGrabAdd.

Since: 2.18

hasRcStyle

widgetHasRcStyle Source #

Arguments

:: (HasCallStack, MonadIO m, IsWidget a) 
=> a

widget: a Widget

-> m Bool

Returns: True if the widget has been looked up through the rc mechanism, False otherwise.

Deprecated: (Since version 3.0)Use StyleContext instead

Determines if the widget style has been looked up through the rc mechanism.

Since: 2.20

hasScreen

widgetHasScreen Source #

Arguments

:: (HasCallStack, MonadIO m, IsWidget a) 
=> a

widget: a Widget

-> m Bool

Returns: True if there is a Screen associated with the widget.

Checks whether there is a Screen is associated with this widget. All toplevel widgets have an associated screen, and all widgets added into a hierarchy with a toplevel window at the top.

Since: 2.2

hasVisibleFocus

widgetHasVisibleFocus Source #

Arguments

:: (HasCallStack, MonadIO m, IsWidget a) 
=> a

widget: a Widget

-> m Bool

Returns: True if the widget should display a “focus rectangle”

Determines if the widget should show a visible indication that it has the global input focus. This is a convenience function for use in ::draw handlers that takes into account whether focus indication should currently be shown in the toplevel window of widget. See windowGetFocusVisible for more information about focus indication.

To find out if the widget has the global input focus, use widgetHasFocus.

Since: 3.2

hide

widgetHide Source #

Arguments

:: (HasCallStack, MonadIO m, IsWidget a) 
=> a

widget: a Widget

-> m () 

Reverses the effects of widgetShow, causing the widget to be hidden (invisible to the user).

hideOnDelete

widgetHideOnDelete Source #

Arguments

:: (HasCallStack, MonadIO m, IsWidget a) 
=> a

widget: a Widget

-> m Bool

Returns: True

Utility function; intended to be connected to the Widget::delete-event signal on a Window. The function calls widgetHide on its argument, then returns True. If connected to ::delete-event, the result is that clicking the close button for a window (on the window frame, top right corner usually) will hide but not destroy the window. By default, GTK+ destroys windows when ::delete-event is received.

inDestruction

widgetInDestruction Source #

Arguments

:: (HasCallStack, MonadIO m, IsWidget a) 
=> a

widget: a Widget

-> m Bool

Returns: True if widget is being destroyed

Returns whether the widget is currently being destroyed. This information can sometimes be used to avoid doing unnecessary work.

initTemplate

widgetInitTemplate Source #

Arguments

:: (HasCallStack, MonadIO m, IsWidget a) 
=> a

widget: a Widget

-> m () 

Creates and initializes child widgets defined in templates. This function must be called in the instance initializer for any class which assigned itself a template using widgetClassSetTemplate

It is important to call this function in the instance initializer of a Widget subclass and not in Object.constructed() or Object.constructor() for two reasons.

One reason is that generally derived widgets will assume that parent class composite widgets have been created in their instance initializers.

Another reason is that when calling g_object_new() on a widget with composite templates, it’s important to build the composite widgets before the construct properties are set. Properties passed to g_object_new() should take precedence over properties set in the private template XML.

Since: 3.10

inputShapeCombineRegion

widgetInputShapeCombineRegion Source #

Arguments

:: (HasCallStack, MonadIO m, IsWidget a) 
=> a

widget: a Widget

-> Maybe Region

region: shape to be added, or Nothing to remove an existing shape

-> m () 

Sets an input shape for this widget’s GDK window. This allows for windows which react to mouse click in a nonrectangular region, see windowInputShapeCombineRegion for more information.

Since: 3.0

insertActionGroup

widgetInsertActionGroup Source #

Arguments

:: (HasCallStack, MonadIO m, IsWidget a, IsActionGroup b) 
=> a

widget: a Widget

-> Text

name: the prefix for actions in group

-> Maybe b

group: a ActionGroup, or Nothing

-> m () 

Inserts group into widget. Children of widget that implement Actionable can then be associated with actions in group by setting their “action-name” to prefix.action-name.

If group is Nothing, a previously inserted group for name is removed from widget.

Since: 3.6

intersect

widgetIntersect Source #

Arguments

:: (HasCallStack, MonadIO m, IsWidget a) 
=> a

widget: a Widget

-> Rectangle

area: a rectangle

-> m (Bool, Maybe Rectangle)

Returns: True if there was an intersection

Computes the intersection of a widget’s area and area, storing the intersection in intersection, and returns True if there was an intersection. intersection may be Nothing if you’re only interested in whether there was an intersection.

isAncestor

widgetIsAncestor Source #

Arguments

:: (HasCallStack, MonadIO m, IsWidget a, IsWidget b) 
=> a

widget: a Widget

-> b

ancestor: another Widget

-> m Bool

Returns: True if ancestor contains widget as a child, grandchild, great grandchild, etc.

Determines whether widget is somewhere inside ancestor, possibly with intermediate containers.

isComposited

widgetIsComposited Source #

Arguments

:: (HasCallStack, MonadIO m, IsWidget a) 
=> a

widget: a Widget

-> m Bool

Returns: True if the widget can rely on its alpha channel being drawn correctly.

Deprecated: (Since version 3.22)Use screenIsComposited instead.

Whether widget can rely on having its alpha channel drawn correctly. On X11 this function returns whether a compositing manager is running for widget’s screen.

Please note that the semantics of this call will change in the future if used on a widget that has a composited window in its hierarchy (as set by windowSetComposited).

Since: 2.10

isDrawable

widgetIsDrawable Source #

Arguments

:: (HasCallStack, MonadIO m, IsWidget a) 
=> a

widget: a Widget

-> m Bool

Returns: True if widget is drawable, False otherwise

Determines whether widget can be drawn to. A widget can be drawn to if it is mapped and visible.

Since: 2.18

isFocus

widgetIsFocus Source #

Arguments

:: (HasCallStack, MonadIO m, IsWidget a) 
=> a

widget: a Widget

-> m Bool

Returns: True if the widget is the focus widget.

Determines if the widget is the focus widget within its toplevel. (This does not mean that the Widget:has-focus property is necessarily set; Widget:has-focus will only be set if the toplevel widget additionally has the global input focus.)

isSensitive

widgetIsSensitive Source #

Arguments

:: (HasCallStack, MonadIO m, IsWidget a) 
=> a

widget: a Widget

-> m Bool

Returns: True if the widget is effectively sensitive

Returns the widget’s effective sensitivity, which means it is sensitive itself and also its parent widget is sensitive

Since: 2.18

isToplevel

widgetIsToplevel Source #

Arguments

:: (HasCallStack, MonadIO m, IsWidget a) 
=> a

widget: a Widget

-> m Bool

Returns: True if widget is a toplevel, False otherwise

Determines whether widget is a toplevel widget.

Currently only Window and Invisible (and out-of-process GtkPlugs) are toplevel widgets. Toplevel widgets have no parent widget.

Since: 2.18

isVisible

widgetIsVisible Source #

Arguments

:: (HasCallStack, MonadIO m, IsWidget a) 
=> a

widget: a Widget

-> m Bool

Returns: True if the widget and all its parents are visible

Determines whether the widget and all its parents are marked as visible.

This function does not check if the widget is obscured in any way.

See also widgetGetVisible and widgetSetVisible

Since: 3.8

keynavFailed

widgetKeynavFailed Source #

Arguments

:: (HasCallStack, MonadIO m, IsWidget a) 
=> a

widget: a Widget

-> DirectionType

direction: direction of focus movement

-> m Bool

Returns: 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).

This function should be called whenever keyboard navigation within a single widget hits a boundary. The function emits the Widget::keynav-failed signal on the widget and its return value should be interpreted in a way similar to the return value of widgetChildFocus:

When True is returned, stay in the widget, the failed keyboard navigation is OK and/or there is nowhere we can/should move the focus to.

When False is returned, the caller should continue with keyboard navigation outside the widget, e.g. by calling widgetChildFocus on the widget’s toplevel.

The default ::keynav-failed handler returns False for DirectionTypeTabForward and DirectionTypeTabBackward. For the other values of DirectionType it returns True.

Whenever the default handler returns True, it also calls widgetErrorBell to notify the user of the failed keyboard navigation.

A use case for providing an own implementation of ::keynav-failed (either by connecting to it or by overriding it) would be a row of Entry widgets where the user should be able to navigate the entire row with the cursor keys, as e.g. known from user interfaces that require entering license keys.

Since: 2.12

listAccelClosures

widgetListAccelClosures Source #

Arguments

:: (HasCallStack, MonadIO m, IsWidget a) 
=> a

widget: widget to list accelerator closures for

-> m [Closure]

Returns: a newly allocated List of closures

Lists the closures used by widget for accelerator group connections with accelGroupConnectByPath or accelGroupConnect. The closures can be used to monitor accelerator changes on widget, by connecting to the gtkAccelGroup::accel-changed signal of the AccelGroup of a closure which can be found out with accelGroupFromAccelClosure.

listActionPrefixes

widgetListActionPrefixes Source #

Arguments

:: (HasCallStack, MonadIO m, IsWidget a) 
=> a

widget: A Widget

-> m [Text]

Returns: a Nothing-terminated array of strings.

Retrieves a Nothing-terminated array of strings containing the prefixes of 'GI.Gio.Interfaces.ActionGroup.ActionGroup'\'s available to widget.

Since: 3.16

listMnemonicLabels

widgetListMnemonicLabels Source #

Arguments

:: (HasCallStack, MonadIO m, IsWidget a) 
=> a

widget: a Widget

-> m [Widget]

Returns: the list of mnemonic labels; free this list with g_list_free() when you are done with it.

Returns a newly allocated list of the widgets, normally labels, for which this widget is the target of a mnemonic (see for example, labelSetMnemonicWidget).

The widgets in the list are not individually referenced. If you want to iterate through the list and perform actions involving callbacks that might destroy the widgets, you must call g_list_foreach (result, (GFunc)g_object_ref, NULL) first, and then unref all the widgets afterwards.

Since: 2.4

map

widgetMap Source #

Arguments

:: (HasCallStack, MonadIO m, IsWidget a) 
=> a

widget: a Widget

-> m () 

This function is only for use in widget implementations. Causes a widget to be mapped if it isn’t already.

mnemonicActivate

widgetMnemonicActivate Source #

Arguments

:: (HasCallStack, MonadIO m, IsWidget a) 
=> a

widget: a Widget

-> Bool

groupCycling: True if there are other widgets with the same mnemonic

-> m Bool

Returns: True if the signal has been handled

Emits the Widget::mnemonic-activate signal.

modifyBase

widgetModifyBase Source #

Arguments

:: (HasCallStack, MonadIO m, IsWidget a) 
=> a

widget: a Widget

-> StateType

state: the state for which to set the base color

-> Maybe Color

color: the color to assign (does not need to be allocated), or Nothing to undo the effect of previous calls to of widgetModifyBase.

-> m () 

Deprecated: (Since version 3.0)Use widgetOverrideBackgroundColor instead

Sets the base color for a widget in a particular state. All other style values are left untouched. The base color is the background color used along with the text color (see widgetModifyText) for widgets such as Entry and TextView. See also widgetModifyStyle.

Note that “no window” widgets (which have the @/GTK_NO_WINDOW/@
flag set) draw on their parent container’s window and thus may
not draw any background themselves. This is the case for e.g.
'GI.Gtk.Objects.Label.Label'.

To modify the background of such widgets, you have to set the
base color on their parent; if you want to set the background
of a rectangular area around a label, try placing the label in
a 'GI.Gtk.Objects.EventBox.EventBox' widget and setting the base color on that.

modifyBg

widgetModifyBg Source #

Arguments

:: (HasCallStack, MonadIO m, IsWidget a) 
=> a

widget: a Widget

-> StateType

state: the state for which to set the background color

-> Maybe Color

color: the color to assign (does not need to be allocated), or Nothing to undo the effect of previous calls to of widgetModifyBg.

-> m () 

Deprecated: (Since version 3.0)Use widgetOverrideBackgroundColor instead

Sets the background color for a widget in a particular state.

All other style values are left untouched. See also widgetModifyStyle.

Note that “no window” widgets (which have the @/GTK_NO_WINDOW/@
flag set) draw on their parent container’s window and thus may
not draw any background themselves. This is the case for e.g.
'GI.Gtk.Objects.Label.Label'.

To modify the background of such widgets, you have to set the
background color on their parent; if you want to set the background
of a rectangular area around a label, try placing the label in
a 'GI.Gtk.Objects.EventBox.EventBox' widget and setting the background color on that.

modifyCursor

widgetModifyCursor Source #

Arguments

:: (HasCallStack, MonadIO m, IsWidget a) 
=> a

widget: a Widget

-> Maybe Color

primary: the color to use for primary cursor (does not need to be allocated), or Nothing to undo the effect of previous calls to of widgetModifyCursor.

-> Maybe Color

secondary: the color to use for secondary cursor (does not need to be allocated), or Nothing to undo the effect of previous calls to of widgetModifyCursor.

-> m () 

Deprecated: (Since version 3.0)Use widgetOverrideCursor instead.

Sets the cursor color to use in a widget, overriding the Widget cursor-color and secondary-cursor-color style properties.

All other style values are left untouched. See also widgetModifyStyle.

Since: 2.12

modifyFg

widgetModifyFg Source #

Arguments

:: (HasCallStack, MonadIO m, IsWidget a) 
=> a

widget: a Widget

-> StateType

state: the state for which to set the foreground color

-> Maybe Color

color: the color to assign (does not need to be allocated), or Nothing to undo the effect of previous calls to of widgetModifyFg.

-> m () 

Deprecated: (Since version 3.0)Use widgetOverrideColor instead

Sets the foreground color for a widget in a particular state.

All other style values are left untouched. See also widgetModifyStyle.

modifyFont

widgetModifyFont Source #

Arguments

:: (HasCallStack, MonadIO m, IsWidget a) 
=> a

widget: a Widget

-> Maybe FontDescription

fontDesc: the font description to use, or Nothing to undo the effect of previous calls to widgetModifyFont

-> m () 

Deprecated: (Since version 3.0)Use widgetOverrideFont instead

Sets the font to use for a widget.

All other style values are left untouched. See also widgetModifyStyle.

modifyStyle

widgetModifyStyle Source #

Arguments

:: (HasCallStack, MonadIO m, IsWidget a, IsRcStyle b) 
=> a

widget: a Widget

-> b

style: the RcStyle-struct holding the style modifications

-> m () 

Deprecated: (Since version 3.0)Use StyleContext with a custom StyleProvider instead

Modifies style values on the widget.

Modifications made using this technique take precedence over style values set via an RC file, however, they will be overridden if a style is explicitly set on the widget using widgetSetStyle. The RcStyle-struct is designed so each field can either be set or unset, so it is possible, using this function, to modify some style values and leave the others unchanged.

Note that modifications made with this function are not cumulative with previous calls to widgetModifyStyle or with such functions as widgetModifyFg. If you wish to retain previous values, you must first call widgetGetModifierStyle, make your modifications to the returned style, then call widgetModifyStyle with that style. On the other hand, if you first call widgetModifyStyle, subsequent calls to such functions widgetModifyFg will have a cumulative effect with the initial modifications.

modifyText

widgetModifyText Source #

Arguments

:: (HasCallStack, MonadIO m, IsWidget a) 
=> a

widget: a Widget

-> StateType

state: the state for which to set the text color

-> Maybe Color

color: the color to assign (does not need to be allocated), or Nothing to undo the effect of previous calls to of widgetModifyText.

-> m () 

Deprecated: (Since version 3.0)Use widgetOverrideColor instead

Sets the text color for a widget in a particular state.

All other style values are left untouched. The text color is the foreground color used along with the base color (see widgetModifyBase) for widgets such as Entry and TextView. See also widgetModifyStyle.

overrideBackgroundColor

widgetOverrideBackgroundColor Source #

Arguments

:: (HasCallStack, MonadIO m, IsWidget a) 
=> a

widget: a Widget

-> [StateFlags]

state: the state for which to set the background color

-> Maybe RGBA

color: the color to assign, or Nothing to undo the effect of previous calls to widgetOverrideBackgroundColor

-> m () 

Deprecated: (Since version 3.16)This function is not useful in the context of CSS-based rendering. If you wish to change the way a widget renders its background you should use a custom CSS style, through an application-specific StyleProvider and a CSS style class. You can also override the default drawing of a widget through the Widget::draw signal, and use Cairo to draw a specific color, regardless of the CSS style.

Sets the background color to use for a widget.

All other style values are left untouched. See widgetOverrideColor.

Since: 3.0

overrideColor

widgetOverrideColor Source #

Arguments

:: (HasCallStack, MonadIO m, IsWidget a) 
=> a

widget: a Widget

-> [StateFlags]

state: the state for which to set the color

-> Maybe RGBA

color: the color to assign, or Nothing to undo the effect of previous calls to widgetOverrideColor

-> m () 

Deprecated: (Since version 3.16)Use a custom style provider and style classes instead

Sets the color to use for a widget.

All other style values are left untouched.

This function does not act recursively. Setting the color of a container does not affect its children. Note that some widgets that you may not think of as containers, for instance GtkButtons, are actually containers.

This API is mostly meant as a quick way for applications to change a widget appearance. If you are developing a widgets library and intend this change to be themeable, it is better done by setting meaningful CSS classes in your widget/container implementation through styleContextAddClass.

This way, your widget library can install a CssProvider with the STYLE_PROVIDER_PRIORITY_FALLBACK priority in order to provide a default styling for those widgets that need so, and this theming may fully overridden by the user’s theme.

Note that for complex widgets this may bring in undesired results (such as uniform background color everywhere), in these cases it is better to fully style such widgets through a CssProvider with the STYLE_PROVIDER_PRIORITY_APPLICATION priority.

Since: 3.0

overrideCursor

widgetOverrideCursor Source #

Arguments

:: (HasCallStack, MonadIO m, IsWidget a) 
=> a

widget: a Widget

-> Maybe RGBA

cursor: the color to use for primary cursor (does not need to be allocated), or Nothing to undo the effect of previous calls to of widgetOverrideCursor.

-> Maybe RGBA

secondaryCursor: the color to use for secondary cursor (does not need to be allocated), or Nothing to undo the effect of previous calls to of widgetOverrideCursor.

-> m () 

Deprecated: (Since version 3.16)This function is not useful in the context of CSS-based rendering. If you wish to change the color used to render the primary and secondary cursors you should use a custom CSS style, through an application-specific StyleProvider and a CSS style class.

Sets the cursor color to use in a widget, overriding the cursor-color and secondary-cursor-color style properties. All other style values are left untouched. See also widgetModifyStyle.

Note that the underlying properties have the Color type, so the alpha value in primary and secondary will be ignored.

Since: 3.0

overrideFont

widgetOverrideFont Source #

Arguments

:: (HasCallStack, MonadIO m, IsWidget a) 
=> a

widget: a Widget

-> Maybe FontDescription

fontDesc: the font description to use, or Nothing to undo the effect of previous calls to widgetOverrideFont

-> m () 

Deprecated: (Since version 3.16)This function is not useful in the context of CSS-based rendering. If you wish to change the font a widget uses to render its text you should use a custom CSS style, through an application-specific StyleProvider and a CSS style class.

Sets the font to use for a widget. All other style values are left untouched. See widgetOverrideColor.

Since: 3.0

overrideSymbolicColor

widgetOverrideSymbolicColor Source #

Arguments

:: (HasCallStack, MonadIO m, IsWidget a) 
=> a

widget: a Widget

-> Text

name: the name of the symbolic color to modify

-> Maybe RGBA

color: the color to assign (does not need to be allocated), or Nothing to undo the effect of previous calls to widgetOverrideSymbolicColor

-> m () 

Deprecated: (Since version 3.16)This function is not useful in the context of CSS-based rendering. If you wish to change the color used to render symbolic icons you should use a custom CSS style, through an application-specific StyleProvider and a CSS style class.

Sets a symbolic color for a widget.

All other style values are left untouched. See widgetOverrideColor for overriding the foreground or background color.

Since: 3.0

path

widgetPath Source #

Arguments

:: (HasCallStack, MonadIO m, IsWidget a) 
=> a

widget: a Widget

-> m (Word32, Text, Text) 

Deprecated: (Since version 3.0)Use widgetGetPath instead

Obtains the full path to widget. The path is simply the name of a widget and all its parents in the container hierarchy, separated by periods. The name of a widget comes from widgetGetName. Paths are used to apply styles to a widget in gtkrc configuration files. Widget names are the type of the widget by default (e.g. “GtkButton”) or can be set to an application-specific value with widgetSetName. By setting the name of a widget, you allow users or theme authors to apply styles to that specific widget in their gtkrc file. pathReversedP fills in the path in reverse order, i.e. starting with widget’s name instead of starting with the name of widget’s outermost ancestor.

popCompositeChild

widgetPopCompositeChild :: (HasCallStack, MonadIO m) => m () Source #

Deprecated: (Since version 3.10)Use widgetClassSetTemplate, or don’t use this API at all.

Cancels the effect of a previous call to widgetPushCompositeChild.

pushCompositeChild

widgetPushCompositeChild :: (HasCallStack, MonadIO m) => m () Source #

Deprecated: (Since version 3.10)This API never really worked well and was mostly unused, nowwe have a more complete mechanism for composite children, see widgetClassSetTemplate.

Makes all newly-created widgets as composite children until the corresponding widgetPopCompositeChild call.

A composite child is a child that’s an implementation detail of the container it’s inside and should not be visible to people using the container. Composite children aren’t treated differently by GTK+ (but see containerForeach vs. containerForall), but e.g. GUI builders might want to treat them in a different way.

queueAllocate

widgetQueueAllocate Source #

Arguments

:: (HasCallStack, MonadIO m, IsWidget a) 
=> a

widget: a Widget

-> m () 

This function is only for use in widget implementations.

Flags the widget for a rerun of the GtkWidgetClass::size_allocate function. Use this function instead of widgetQueueResize when the widget's size request didn't change but it wants to reposition its contents.

An example user of this function is widgetSetHalign.

Since: 3.20

queueComputeExpand

widgetQueueComputeExpand Source #

Arguments

:: (HasCallStack, MonadIO m, IsWidget a) 
=> a

widget: a Widget

-> m () 

Mark widget as needing to recompute its expand flags. Call this function when setting legacy expand child properties on the child of a container.

See widgetComputeExpand.

queueDraw

widgetQueueDraw Source #

Arguments

:: (HasCallStack, MonadIO m, IsWidget a) 
=> a

widget: a Widget

-> m () 

Equivalent to calling widgetQueueDrawArea for the entire area of a widget.

queueDrawArea

widgetQueueDrawArea Source #

Arguments

:: (HasCallStack, MonadIO m, IsWidget a) 
=> a

widget: a Widget

-> Int32

x: x coordinate of upper-left corner of rectangle to redraw

-> Int32

y: y coordinate of upper-left corner of rectangle to redraw

-> Int32

width: width of region to draw

-> Int32

height: height of region to draw

-> m () 

Convenience function that calls widgetQueueDrawRegion on the region created from the given coordinates.

The region here is specified in widget coordinates. Widget coordinates are a bit odd; for historical reasons, they are defined as widget->window coordinates for widgets that return True for widgetGetHasWindow, and are relative to widget->allocation.x, widget->allocation.y otherwise.

width or height may be 0, in this case this function does nothing. Negative values for width and height are not allowed.

queueDrawRegion

widgetQueueDrawRegion Source #

Arguments

:: (HasCallStack, MonadIO m, IsWidget a) 
=> a

widget: a Widget

-> Region

region: region to draw

-> m () 

Invalidates the area of widget defined by region by calling windowInvalidateRegion on the widget’s window and all its child windows. Once the main loop becomes idle (after the current batch of events has been processed, roughly), the window will receive expose events for the union of all regions that have been invalidated.

Normally you would only use this function in widget implementations. You might also use it to schedule a redraw of a DrawingArea or some portion thereof.

Since: 3.0

queueResize

widgetQueueResize Source #

Arguments

:: (HasCallStack, MonadIO m, IsWidget a) 
=> a

widget: a Widget

-> m () 

This function is only for use in widget implementations. Flags a widget to have its size renegotiated; should be called when a widget for some reason has a new size request. For example, when you change the text in a Label, Label queues a resize to ensure there’s enough space for the new text.

Note that you cannot call widgetQueueResize on a widget from inside its implementation of the GtkWidgetClass::size_allocate virtual method. Calls to widgetQueueResize from inside GtkWidgetClass::size_allocate will be silently ignored.

queueResizeNoRedraw

widgetQueueResizeNoRedraw Source #

Arguments

:: (HasCallStack, MonadIO m, IsWidget a) 
=> a

widget: a Widget

-> m () 

This function works like widgetQueueResize, except that the widget is not invalidated.

Since: 2.4

realize

widgetRealize Source #

Arguments

:: (HasCallStack, MonadIO m, IsWidget a) 
=> a

widget: a Widget

-> m () 

Creates the GDK (windowing system) resources associated with a widget. For example, widget->window will be created when a widget is realized. Normally realization happens implicitly; if you show a widget and all its parent containers, then the widget will be realized and mapped automatically.

Realizing a widget requires all the widget’s parent widgets to be realized; calling widgetRealize realizes the widget’s parents in addition to widget itself. If a widget is not yet inside a toplevel window when you realize it, bad things will happen.