Copyright	Will Thompson Iñaki García Etxebarria and Jonas Platte
License	LGPL-2.1
Maintainer	Iñaki García Etxebarria (garetxe@gmail.com)
Safe Haskell	None
Language	Haskell2010

GI.Gtk.Structs.WidgetPath

Contents

Exported types
Methods

Description

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.

Synopsis

newtype WidgetPath = WidgetPath (ManagedPtr WidgetPath)
noWidgetPath :: Maybe WidgetPath
widgetPathAppendForWidget :: (HasCallStack, MonadIO m, IsWidget a) => WidgetPath -> a -> m Int32
widgetPathAppendType :: (HasCallStack, MonadIO m) => WidgetPath -> GType -> m Int32
widgetPathAppendWithSiblings :: (HasCallStack, MonadIO m) => WidgetPath -> WidgetPath -> Word32 -> m Int32
widgetPathCopy :: (HasCallStack, MonadIO m) => WidgetPath -> m WidgetPath
widgetPathFree :: (HasCallStack, MonadIO m) => WidgetPath -> m ()
widgetPathGetObjectType :: (HasCallStack, MonadIO m) => WidgetPath -> m GType
widgetPathHasParent :: (HasCallStack, MonadIO m) => WidgetPath -> GType -> m Bool
widgetPathIsType :: (HasCallStack, MonadIO m) => WidgetPath -> GType -> m Bool
widgetPathIterAddClass :: (HasCallStack, MonadIO m) => WidgetPath -> Int32 -> Text -> m ()
widgetPathIterAddRegion :: (HasCallStack, MonadIO m) => WidgetPath -> Int32 -> Text -> [RegionFlags] -> m ()
widgetPathIterClearClasses :: (HasCallStack, MonadIO m) => WidgetPath -> Int32 -> m ()
widgetPathIterClearRegions :: (HasCallStack, MonadIO m) => WidgetPath -> Int32 -> m ()
widgetPathIterGetName :: (HasCallStack, MonadIO m) => WidgetPath -> Int32 -> m (Maybe Text)
widgetPathIterGetObjectName :: (HasCallStack, MonadIO m) => WidgetPath -> Int32 -> m (Maybe Text)
widgetPathIterGetObjectType :: (HasCallStack, MonadIO m) => WidgetPath -> Int32 -> m GType
widgetPathIterGetSiblingIndex :: (HasCallStack, MonadIO m) => WidgetPath -> Int32 -> m Word32
widgetPathIterGetSiblings :: (HasCallStack, MonadIO m) => WidgetPath -> Int32 -> m WidgetPath
widgetPathIterGetState :: (HasCallStack, MonadIO m) => WidgetPath -> Int32 -> m [StateFlags]
widgetPathIterHasClass :: (HasCallStack, MonadIO m) => WidgetPath -> Int32 -> Text -> m Bool
widgetPathIterHasName :: (HasCallStack, MonadIO m) => WidgetPath -> Int32 -> Text -> m Bool
widgetPathIterHasQclass :: (HasCallStack, MonadIO m) => WidgetPath -> Int32 -> Word32 -> m Bool
widgetPathIterHasQname :: (HasCallStack, MonadIO m) => WidgetPath -> Int32 -> Word32 -> m Bool
widgetPathIterHasQregion :: (HasCallStack, MonadIO m) => WidgetPath -> Int32 -> Word32 -> m (Bool, [RegionFlags])
widgetPathIterHasRegion :: (HasCallStack, MonadIO m) => WidgetPath -> Int32 -> Text -> m (Bool, [RegionFlags])
widgetPathIterListClasses :: (HasCallStack, MonadIO m) => WidgetPath -> Int32 -> m [Text]
widgetPathIterListRegions :: (HasCallStack, MonadIO m) => WidgetPath -> Int32 -> m [Text]
widgetPathIterRemoveClass :: (HasCallStack, MonadIO m) => WidgetPath -> Int32 -> Text -> m ()
widgetPathIterRemoveRegion :: (HasCallStack, MonadIO m) => WidgetPath -> Int32 -> Text -> m ()
widgetPathIterSetName :: (HasCallStack, MonadIO m) => WidgetPath -> Int32 -> Text -> m ()
widgetPathIterSetObjectName :: (HasCallStack, MonadIO m) => WidgetPath -> Int32 -> Maybe Text -> m ()
widgetPathIterSetObjectType :: (HasCallStack, MonadIO m) => WidgetPath -> Int32 -> GType -> m ()
widgetPathIterSetState :: (HasCallStack, MonadIO m) => WidgetPath -> Int32 -> [StateFlags] -> m ()
widgetPathLength :: (HasCallStack, MonadIO m) => WidgetPath -> m Int32
widgetPathNew :: (HasCallStack, MonadIO m) => m WidgetPath
widgetPathPrependType :: (HasCallStack, MonadIO m) => WidgetPath -> GType -> m ()
widgetPathRef :: (HasCallStack, MonadIO m) => WidgetPath -> m WidgetPath
widgetPathToString :: (HasCallStack, MonadIO m) => WidgetPath -> m Text
widgetPathUnref :: (HasCallStack, MonadIO m) => WidgetPath -> m ()

Exported types

newtype WidgetPath Source #

Memory-managed wrapper type.

Constructors

WidgetPath (ManagedPtr WidgetPath)

Instances

BoxedObject WidgetPath Source #
Instance details Defined in GI.Gtk.Structs.WidgetPath Methods boxedType :: WidgetPath -> IO GType #

noWidgetPath :: Maybe WidgetPath Source #

A convenience alias for Nothing :: Maybe WidgetPath.

Methods

appendForWidget

widgetPathAppendForWidget Source #

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 Source #

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 Source #

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 Source #

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 Source #

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 Source #

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 Source #

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 Source #

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 Source #

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 Source #

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 Source #

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 Source #

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 Source #

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 Source #

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 Source #

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 Source #

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 Source #

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 Source #

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 Source #

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 Source #

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 Source #

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 Source #

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 Source #

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 Source #

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 Source #

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 Source #

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 Source #

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 Source #

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 Source #

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 Source #

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 Source #

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 Source #

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 Source #

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 Source #

Arguments

:: (HasCallStack, MonadIO m)
=> m WidgetPath	Returns: A newly created, empty, `WidgetPath`

Returns an empty widget path.

Since: 3.0

prependType

widgetPathPrependType Source #

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 Source #

Arguments

:: (HasCallStack, MonadIO m)
=> WidgetPath	`path`: a `WidgetPath`
-> m WidgetPath	Returns: `path` itself.

Increments the reference count on path.

Since: 3.2

toString

widgetPathToString Source #

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 Source #

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