GI.Gtk.Structs.WidgetPath

GtkWidgetPath is a boxed type that represents a widget hierarchy from the topmost widget, typically a toplevel, to any child. This widget path abstraction is used in StyleContext on behalf of the real widget in order to query style information.

If you are using GTK+ widgets, you probably will not need to use this API directly, as there is widgetGetPath, and the style context returned by widgetGetStyleContext will be automatically updated on widget hierarchy changes.

The widget path generation is generally simple:

Defining a button within a window

C code

{
  GtkWidgetPath *path;

  path = gtk_widget_path_new ();
  gtk_widget_path_append_type (path, GTK_TYPE_WINDOW);
  gtk_widget_path_append_type (path, GTK_TYPE_BUTTON);
}

Although more complex information, such as widget names, or different classes (property that may be used by other widget types) and intermediate regions may be included:

Defining the first tab widget in a notebook

C code

{
  GtkWidgetPath *path;
  guint pos;

  path = gtk_widget_path_new ();

  pos = gtk_widget_path_append_type (path, GTK_TYPE_NOTEBOOK);
  gtk_widget_path_iter_add_region (path, pos, "tab", GTK_REGION_EVEN | GTK_REGION_FIRST);

  pos = gtk_widget_path_append_type (path, GTK_TYPE_LABEL);
  gtk_widget_path_iter_set_name (path, pos, "first tab label");
}

All this information will be used to match the style information that applies to the described widget.

Exported types

newtype WidgetPath

Memory-managed wrapper type.

Constructors

WidgetPath (ManagedPtr WidgetPath)

Instances

Eq WidgetPath

Defined in GI.Gtk.Structs.WidgetPath

Methods

(==) :: WidgetPath -> WidgetPath -> Bool

(/=) :: WidgetPath -> WidgetPath -> Bool

IsGValue WidgetPath

Convert WidgetPath to and from GValue with toGValue and fromGValue.

Defined in GI.Gtk.Structs.WidgetPath

Methods

toGValue :: WidgetPath -> IO GValue

fromGValue :: GValue -> IO WidgetPath

BoxedObject WidgetPath

Defined in GI.Gtk.Structs.WidgetPath

Methods

boxedType :: WidgetPath -> IO GType

Methods

Overloaded methods

appendForWidget

widgetPathAppendForWidget

Arguments

:: (HasCallStack, MonadIO m, IsWidget a)

=> WidgetPath

path: a widget path

-> a

widget: the widget to append to the widget path

-> m Int32

Returns: the position where the data was inserted

Appends the data from widget to the widget hierarchy represented by path. This function is a shortcut for adding information from widget to the given path. This includes setting the name or adding the style classes from widget.

Since: 3.2

appendType

widgetPathAppendType

Arguments

:: (HasCallStack, MonadIO m)

=> WidgetPath

path: a WidgetPath

-> GType

type: widget type to append

-> m Int32

Returns: the position where the element was inserted

Appends a widget type to the widget hierarchy represented by path.

Since: 3.0

appendWithSiblings

widgetPathAppendWithSiblings

Arguments

:: (HasCallStack, MonadIO m)

=> WidgetPath

path: the widget path to append to

-> WidgetPath

siblings: a widget path describing a list of siblings. This path may not contain any siblings itself and it must not be modified afterwards.

-> Word32

siblingIndex: index into siblings for where the added element is positioned.

-> m Int32

Returns: the position where the element was inserted.

Appends a widget type with all its siblings to the widget hierarchy represented by path. Using this function instead of widgetPathAppendType will allow the CSS theming to use sibling matches in selectors and apply :nth-child() pseudo classes. In turn, it requires a lot more care in widget implementations as widgets need to make sure to call widgetResetStyle on all involved widgets when the siblings path changes.

Since: 3.2

copy

widgetPathCopy

Arguments

:: (HasCallStack, MonadIO m)

=> WidgetPath

path: a WidgetPath

-> m WidgetPath

Returns: a copy of path

Returns a copy of path

Since: 3.0

free

widgetPathFree

Arguments

:: (HasCallStack, MonadIO m)

=> WidgetPath

path: a WidgetPath

-> m ()

Decrements the reference count on path, freeing the structure if the reference count reaches 0.

Since: 3.0

getObjectType

widgetPathGetObjectType

Arguments

:: (HasCallStack, MonadIO m)

=> WidgetPath

path: a Widget

-> m GType

Returns: The object type

Returns the topmost object type, that is, the object type this path is representing.

Since: 3.0

hasParent

widgetPathHasParent

Arguments

:: (HasCallStack, MonadIO m)

=> WidgetPath

path: a WidgetPath

-> GType

type: widget type to check in parents

-> m Bool

Returns: True if any parent is of type type

Returns True if any of the parents of the widget represented in path is of type type, or any subtype of it.

Since: 3.0

isType

widgetPathIsType

Arguments

:: (HasCallStack, MonadIO m)

=> WidgetPath

path: a WidgetPath

-> GType

type: widget type to match

-> m Bool

Returns: True if the widget represented by path is of type type

Returns True if the widget type represented by this path is type, or a subtype of it.

Since: 3.0

iterAddClass

widgetPathIterAddClass

Arguments

:: (HasCallStack, MonadIO m)

=> WidgetPath

path: a Widget

-> Int32

pos: position to modify, -1 for the path head

-> Text

name: a class name

-> m ()

Adds the class name to the widget at position pos in the hierarchy defined in path. See styleContextAddClass.

Since: 3.0

iterAddRegion

widgetPathIterAddRegion

Arguments

:: (HasCallStack, MonadIO m)

=> WidgetPath

path: a WidgetPath

-> Int32

pos: position to modify, -1 for the path head

-> Text

name: region name

-> [RegionFlags]

flags: flags affecting the region

-> m ()

Deprecated: (Since version 3.14)The use of regions is deprecated.

Adds the region name to the widget at position pos in the hierarchy defined in path. See styleContextAddRegion.

Region names must only contain lowercase letters and “-”, starting always with a lowercase letter.

Since: 3.0

iterClearClasses

widgetPathIterClearClasses

Arguments

:: (HasCallStack, MonadIO m)

=> WidgetPath

path: a Widget

-> Int32

pos: position to modify, -1 for the path head

-> m ()

Removes all classes from the widget at position pos in the hierarchy defined in path.

Since: 3.0

iterClearRegions

widgetPathIterClearRegions

Arguments

:: (HasCallStack, MonadIO m)

=> WidgetPath

path: a WidgetPath

-> Int32

pos: position to modify, -1 for the path head

-> m ()

Deprecated: (Since version 3.14)The use of regions is deprecated.

Removes all regions from the widget at position pos in the hierarchy defined in path.

Since: 3.0

iterGetName

widgetPathIterGetName

Arguments

:: (HasCallStack, MonadIO m)

=> WidgetPath

path: a WidgetPath

-> Int32

pos: position to get the widget name for, -1 for the path head

-> m (Maybe Text)

Returns: The widget name, or Nothing if none was set.

Returns the name corresponding to the widget found at the position pos in the widget hierarchy defined by path

iterGetObjectName

widgetPathIterGetObjectName

Arguments

:: (HasCallStack, MonadIO m)

=> WidgetPath

path: a WidgetPath

-> Int32

pos: position to get the object name for, -1 for the path head

-> m (Maybe Text)

Returns: the name or Nothing

Returns the object name that is at position pos in the widget hierarchy defined in path.

Since: 3.20

iterGetObjectType

widgetPathIterGetObjectType

Arguments

:: (HasCallStack, MonadIO m)

=> WidgetPath

path: a WidgetPath

-> Int32

pos: position to get the object type for, -1 for the path head

-> m GType

Returns: a widget type

Returns the object GType that is at position pos in the widget hierarchy defined in path.

Since: 3.0

iterGetSiblingIndex

widgetPathIterGetSiblingIndex

Arguments

:: (HasCallStack, MonadIO m)

=> WidgetPath

path: a WidgetPath

-> Int32

pos: position to get the sibling index for, -1 for the path head

-> m Word32

Returns: 0 or the index into the list of siblings for the element at pos.

Returns the index into the list of siblings for the element at pos as returned by widgetPathIterGetSiblings. If that function would return Nothing because the element at pos has no siblings, this function will return 0.

iterGetSiblings

widgetPathIterGetSiblings

Arguments

:: (HasCallStack, MonadIO m)

=> WidgetPath

path: a WidgetPath

-> Int32

pos: position to get the siblings for, -1 for the path head

-> m WidgetPath

Returns: Nothing or the list of siblings for the element at pos.

Returns the list of siblings for the element at pos. If the element was not added with siblings, Nothing is returned.

iterGetState

widgetPathIterGetState

Arguments

:: (HasCallStack, MonadIO m)

=> WidgetPath

path: a WidgetPath

-> Int32

pos: position to get the state for, -1 for the path head

-> m [StateFlags]

Returns: The state flags

Returns the state flags corresponding to the widget found at the position pos in the widget hierarchy defined by path

Since: 3.14

iterHasClass

widgetPathIterHasClass

Arguments

:: (HasCallStack, MonadIO m)

=> WidgetPath

path: a WidgetPath

-> Int32

pos: position to query, -1 for the path head

-> Text

name: class name

-> m Bool

Returns: True if the class name is defined for the widget at pos

Returns True if the widget at position pos has the class name defined, False otherwise.

Since: 3.0

iterHasName

widgetPathIterHasName

Arguments

:: (HasCallStack, MonadIO m)

=> WidgetPath

path: a WidgetPath

-> Int32

pos: position to query, -1 for the path head

-> Text

name: a widget name

-> m Bool

Returns: True if the widget at pos has this name

Returns True if the widget at position pos has the name name, False otherwise.

Since: 3.0

iterHasQclass

widgetPathIterHasQclass

Arguments

:: (HasCallStack, MonadIO m)

=> WidgetPath

path: a WidgetPath

-> Int32

pos: position to query, -1 for the path head

-> Word32

qname: class name as a GQuark

-> m Bool

Returns: True if the widget at pos has the class defined.

See widgetPathIterHasClass. This is a version that operates with GQuarks.

Since: 3.0

iterHasQname

widgetPathIterHasQname

Arguments

:: (HasCallStack, MonadIO m)

=> WidgetPath

path: a WidgetPath

-> Int32

pos: position to query, -1 for the path head

-> Word32

qname: widget name as a GQuark

-> m Bool

Returns: True if the widget at pos has this name

See widgetPathIterHasName. This is a version that operates on GQuarks.

Since: 3.0

iterHasQregion

widgetPathIterHasQregion

Arguments

:: (HasCallStack, MonadIO m)

=> WidgetPath

path: a WidgetPath

-> Int32

pos: position to query, -1 for the path head

-> Word32

qname: region name as a GQuark

-> m (Bool, [RegionFlags])

Returns: True if the widget at pos has the region defined.

Deprecated: (Since version 3.14)The use of regions is deprecated.

See widgetPathIterHasRegion. This is a version that operates with GQuarks.

Since: 3.0

iterHasRegion

widgetPathIterHasRegion

Arguments

:: (HasCallStack, MonadIO m)

=> WidgetPath

path: a WidgetPath

-> Int32

pos: position to query, -1 for the path head

-> Text

name: region name

-> m (Bool, [RegionFlags])

Returns: True if the class name is defined for the widget at pos

Deprecated: (Since version 3.14)The use of regions is deprecated.

Returns True if the widget at position pos has the class name defined, False otherwise.

Since: 3.0

iterListClasses

widgetPathIterListClasses

Arguments

:: (HasCallStack, MonadIO m)

=> WidgetPath

path: a WidgetPath

-> Int32

pos: position to query, -1 for the path head

-> m [Text]

Returns: The list of classes, This is a list of strings, the SList contents are owned by GTK+, but you should use g_slist_free() to free the list itself.

Returns a list with all the class names defined for the widget at position pos in the hierarchy defined in path.

Since: 3.0

iterListRegions

widgetPathIterListRegions

Arguments

:: (HasCallStack, MonadIO m)

=> WidgetPath

path: a WidgetPath

-> Int32

pos: position to query, -1 for the path head

-> m [Text]

Returns: The list of regions, This is a list of strings, the SList contents are owned by GTK+, but you should use g_slist_free() to free the list itself.

Deprecated: (Since version 3.14)The use of regions is deprecated.

Returns a list with all the region names defined for the widget at position pos in the hierarchy defined in path.

Since: 3.0

iterRemoveClass

widgetPathIterRemoveClass

Arguments

:: (HasCallStack, MonadIO m)

=> WidgetPath

path: a WidgetPath

-> Int32

pos: position to modify, -1 for the path head

-> Text

name: class name

-> m ()

Removes the class name from the widget at position pos in the hierarchy defined in path.

Since: 3.0

iterRemoveRegion

widgetPathIterRemoveRegion

Arguments

:: (HasCallStack, MonadIO m)

=> WidgetPath

path: a WidgetPath

-> Int32

pos: position to modify, -1 for the path head

-> Text

name: region name

-> m ()

Deprecated: (Since version 3.14)The use of regions is deprecated.

Removes the region name from the widget at position pos in the hierarchy defined in path.

Since: 3.0

iterSetName

widgetPathIterSetName

Arguments

:: (HasCallStack, MonadIO m)

=> WidgetPath

path: a WidgetPath

-> Int32

pos: position to modify, -1 for the path head

-> Text

name: widget name

-> m ()

Sets the widget name for the widget found at position pos in the widget hierarchy defined by path.

Since: 3.0

iterSetObjectName

widgetPathIterSetObjectName

Arguments

:: (HasCallStack, MonadIO m)

=> WidgetPath

path: a WidgetPath

-> Int32

pos: position to modify, -1 for the path head

-> Maybe Text

name: object name to set or Nothing to unset

-> m ()

Sets the object name for a given position in the widget hierarchy defined by path.

When set, the object name overrides the object type when matching CSS.

Since: 3.20

iterSetObjectType

widgetPathIterSetObjectType

Arguments

:: (HasCallStack, MonadIO m)

=> WidgetPath

path: a WidgetPath

-> Int32

pos: position to modify, -1 for the path head

-> GType

type: object type to set

-> m ()

Sets the object type for a given position in the widget hierarchy defined by path.

Since: 3.0

iterSetState

widgetPathIterSetState

Arguments

:: (HasCallStack, MonadIO m)

=> WidgetPath

path: a WidgetPath

-> Int32

pos: position to modify, -1 for the path head

-> [StateFlags]

state: state flags

-> m ()

Sets the widget name for the widget found at position pos in the widget hierarchy defined by path.

If you want to update just a single state flag, you need to do this manually, as this function updates all state flags.

Setting a flag

C code

gtk_widget_path_iter_set_state (path, pos, gtk_widget_path_iter_get_state (path, pos) | flag);

Unsetting a flag

C code

gtk_widget_path_iter_set_state (path, pos, gtk_widget_path_iter_get_state (path, pos) & ~flag);

Since: 3.14

length

widgetPathLength

Arguments

:: (HasCallStack, MonadIO m)

=> WidgetPath

path: a WidgetPath

-> m Int32

Returns: the number of elements in the path

Returns the number of Widget GTypes between the represented widget and its topmost container.

Since: 3.0

new

widgetPathNew

Arguments

:: (HasCallStack, MonadIO m)

=> m WidgetPath

Returns: A newly created, empty, WidgetPath

Returns an empty widget path.

Since: 3.0

prependType

widgetPathPrependType

Arguments

:: (HasCallStack, MonadIO m)

=> WidgetPath

path: a WidgetPath

-> GType

type: widget type to prepend

-> m ()

Prepends a widget type to the widget hierachy represented by path.

Since: 3.0

ref

widgetPathRef

Arguments

:: (HasCallStack, MonadIO m)

=> WidgetPath

path: a WidgetPath

-> m WidgetPath

Returns: path itself.

Increments the reference count on path.

Since: 3.2

toString

widgetPathToString

Arguments

:: (HasCallStack, MonadIO m)

=> WidgetPath

path: the path

-> m Text

Returns: A new string describing path.

Dumps the widget path into a string representation. It tries to match the CSS style as closely as possible (Note that there might be paths that cannot be represented in CSS).

The main use of this code is for debugging purposes, so that you can g_print() the path or dump it in a gdb session.

Since: 3.2

unref

widgetPathUnref

Arguments

:: (HasCallStack, MonadIO m)

=> WidgetPath

path: a WidgetPath

-> m ()

Decrements the reference count on path, freeing the structure if the reference count reaches 0.

Since: 3.2