gi-gtk-3.0.43: Gtk bindings

Copyright | Will Thompson and Iñaki García Etxebarria
License | LGPL-2.1
Maintainer | Iñaki García Etxebarria
Safe Haskell | None
Language | Haskell2010

GI.Gtk.Objects.TreeSelection

Contents

- Exported types
- Methods
  - countSelectedRows
  - getMode
  - getSelected
  - getSelectedRows
  - getTreeView
  - iterIsSelected
  - pathIsSelected
  - selectAll
  - selectIter
  - selectPath
  - selectRange
  - selectedForeach
  - setMode
  - setSelectFunction
  - unselectAll
  - unselectIter
  - unselectPath
  - unselectRange
- Properties
  - mode
- Signals
  - changed

Description

The `TreeSelection` object is a helper object to manage the selection for a `TreeView` widget. The `TreeSelection` object is automatically created when a new `TreeView` widget is created, and cannot exist independently of this widget. The primary reason the `TreeSelection` objects exists is for cleanliness of code and API. That is, there is no conceptual reason all these functions could not be methods on the `TreeView` widget instead of a separate function.

The `TreeSelection` object is gotten from a `TreeView` by calling `treeViewGetSelection`. It can be manipulated to check the selection status of the tree, as well as select and deselect individual rows. Selection is done completely view side. As a result, multiple views of the same model can have completely different selections. Additionally, you cannot change the selection of a row on the model that is not currently displayed by the view without expanding its parents first.

One of the important things to remember when monitoring the selection of a view is that the TreeSelection::changed signal is mostly a hint. That is, it may only emit one signal when a range of rows is selected. Additionally, it may on occasion emit a TreeSelection::changed signal when nothing has happened (mostly as a result of programmers calling select_row on an already selected row).

Synopsis

- newtype TreeSelection = TreeSelection (ManagedPtr TreeSelection)
- class (GObject o, IsDescendantOf TreeSelection o) => IsTreeSelection o
- toTreeSelection :: (MonadIO m, IsTreeSelection o) => o -> m TreeSelection
- treeSelectionCountSelectedRows :: (HasCallStack, MonadIO m, IsTreeSelection a) => a -> m Int32
- treeSelectionGetMode :: (HasCallStack, MonadIO m, IsTreeSelection a) => a -> m SelectionMode
- treeSelectionGetSelected :: (HasCallStack, MonadIO m, IsTreeSelection a) => a -> m (Bool, TreeModel, TreeIter)
- treeSelectionGetSelectedRows :: (HasCallStack, MonadIO m, IsTreeSelection a) => a -> m ([TreePath], TreeModel)
- treeSelectionGetTreeView :: (HasCallStack, MonadIO m, IsTreeSelection a) => a -> m TreeView
- treeSelectionIterIsSelected :: (HasCallStack, MonadIO m, IsTreeSelection a) => a -> TreeIter -> m Bool
- treeSelectionPathIsSelected :: (HasCallStack, MonadIO m, IsTreeSelection a) => a -> TreePath -> m Bool
- treeSelectionSelectAll :: (HasCallStack, MonadIO m, IsTreeSelection a) => a -> m ()
- treeSelectionSelectIter :: (HasCallStack, MonadIO m, IsTreeSelection a) => a -> TreeIter -> m ()
- treeSelectionSelectPath :: (HasCallStack, MonadIO m, IsTreeSelection a) => a -> TreePath -> m ()
- treeSelectionSelectRange :: (HasCallStack, MonadIO m, IsTreeSelection a) => a -> TreePath -> TreePath -> m ()
- treeSelectionSelectedForeach :: (HasCallStack, MonadIO m, IsTreeSelection a) => a -> TreeSelectionForeachFunc -> m ()
- treeSelectionSetMode :: (HasCallStack, MonadIO m, IsTreeSelection a) => a -> SelectionMode -> m ()
- treeSelectionSetSelectFunction :: (HasCallStack, MonadIO m, IsTreeSelection a) => a -> Maybe TreeSelectionFunc -> m ()
- treeSelectionUnselectAll :: (HasCallStack, MonadIO m, IsTreeSelection a) => a -> m ()
- treeSelectionUnselectIter :: (HasCallStack, MonadIO m, IsTreeSelection a) => a -> TreeIter -> m ()
- treeSelectionUnselectPath :: (HasCallStack, MonadIO m, IsTreeSelection a) => a -> TreePath -> m ()
- treeSelectionUnselectRange :: (HasCallStack, MonadIO m, IsTreeSelection a) => a -> TreePath -> TreePath -> m ()
- constructTreeSelectionMode :: (IsTreeSelection o, MonadIO m) => SelectionMode -> m (GValueConstruct o)
- getTreeSelectionMode :: (MonadIO m, IsTreeSelection o) => o -> m SelectionMode
- setTreeSelectionMode :: (MonadIO m, IsTreeSelection o) => o -> SelectionMode -> m ()
- type TreeSelectionChangedCallback = IO ()
- afterTreeSelectionChanged :: (IsTreeSelection a, MonadIO m) => a -> ((?self :: a) => TreeSelectionChangedCallback) -> m SignalHandlerId
- onTreeSelectionChanged :: (IsTreeSelection a, MonadIO m) => a -> ((?self :: a) => TreeSelectionChangedCallback) -> m SignalHandlerId

# Exported types

newtype TreeSelection Source #

Memory-managed wrapper type.

Constructors

TreeSelection (ManagedPtr TreeSelection) |

#### Instances

Instances details

Eq TreeSelection Source # |
Instance details Defined in GI.Gtk.Objects.TreeSelection Methods (==) :: TreeSelection -> TreeSelection -> Bool Source # (/=) :: TreeSelection -> TreeSelection -> Bool Source #
GObject TreeSelection Source # |
Instance details Defined in GI.Gtk.Objects.TreeSelection
ManagedPtrNewtype TreeSelection Source # |
Instance details Defined in GI.Gtk.Objects.TreeSelection Methods toManagedPtr :: TreeSelection -> ManagedPtr TreeSelection Source #
TypedObject TreeSelection Source # |
Instance details Defined in GI.Gtk.Objects.TreeSelection Methods glibType :: IO GType Source #
HasParentTypes TreeSelection Source # |
Instance details Defined in GI.Gtk.Objects.TreeSelection
IsGValue (Maybe TreeSelection) Source # | Convert `TreeSelection` to and from `GValue`. See `toGValue` and `fromGValue`.
Instance details Defined in GI.Gtk.Objects.TreeSelection Methods gvalueGType_ :: IO GType Source # gvalueSet_ :: Ptr GValue -> Maybe TreeSelection -> IO () Source # gvalueGet_ :: Ptr GValue -> IO (Maybe TreeSelection) Source #
type ParentTypes TreeSelection Source # |
Instance details Defined in GI.Gtk.Objects.TreeSelection type ParentTypes TreeSelection = '[Object]

class (GObject o, IsDescendantOf TreeSelection o) => IsTreeSelection o Source #

Type class for types which can be safely cast to `TreeSelection`, for instance with `toTreeSelection`.

#### Instances

Instances details

(GObject o, IsDescendantOf TreeSelection o) => IsTreeSelection o Source # |
Instance details Defined in GI.Gtk.Objects.TreeSelection

toTreeSelection :: (MonadIO m, IsTreeSelection o) => o -> m TreeSelection Source #

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

# Methods

### Click to display all available methods, including inherited ones

Expand

#### Methods

bindProperty, bindPropertyFull, countSelectedRows, forceFloating, freezeNotify, getv, isFloating, iterIsSelected, notify, notifyByPspec, pathIsSelected, ref, refSink, runDispose, selectAll, selectIter, selectPath, selectRange, selectedForeach, stealData, stealQdata, thawNotify, unref, unselectAll, unselectIter, unselectPath, unselectRange, watchClosure.

#### Getters

getData, getMode, getProperty, getQdata, getSelected, getSelectedRows, getTreeView.

#### Setters

setData, setDataFull, setMode, setProperty, setSelectFunction.

## countSelectedRows

treeSelectionCountSelectedRows Source #

Arguments

:: (HasCallStack, MonadIO m, IsTreeSelection a) |
=> a | `selection`: A `TreeSelection`.
-> m Int32 | Returns: The number of rows selected.

Returns the number of rows that have been selected in `tree`.

Since: 2.2

## getMode

treeSelectionGetMode Source #

Arguments

:: (HasCallStack, MonadIO m, IsTreeSelection a) |
=> a | `selection`: a `TreeSelection`
-> m SelectionMode | Returns: the current selection mode

Gets the selection mode for `selection`. See `treeSelectionSetMode`.

## getSelected

treeSelectionGetSelected Source #

Arguments

:: (HasCallStack, MonadIO m, IsTreeSelection a) |
=> a | `selection`: A `TreeSelection`.
-> m (Bool, TreeModel, TreeIter) | Returns: `True`, if there is a selected node.

Sets `iter` to the currently selected node, if `selection` is set to `SelectionModeSingle` or `SelectionModeBrowse`.

The `iter` argument may be `Nothing` if you just want to test if `selection` has any selected nodes.

The `model` argument is filled with the current model as a convenience.

This function will not work with `SelectionModeMultiple`. See `treeSelectionGetSelectedRows` instead.

## getSelectedRows

treeSelectionGetSelectedRows Source #

Arguments

:: (HasCallStack, MonadIO m, IsTreeSelection a) |
=> a | `selection`: A `TreeSelection`.
-> m ([TreePath], TreeModel) | Returns: the selected paths

Creates a list of path of all selected rows.

Additionally, if you are planning on modifying the model after calling this function, you may want to convert the returned list into a list of `GtkTreeRowReferences`.

To do this, you can use `treeRowReferenceNew`.

To free the return value, use:

### C code

    g_list_free_full (list, (GDestroyNotify) gtk_tree_path_free);

Since: 2.2

## getTreeView

treeSelectionGetTreeView Source #

Arguments

:: (HasCallStack, MonadIO m, IsTreeSelection a) |
=> a | `selection`: A `TreeSelection`
-> m TreeView | Returns: A `TreeView`

Returns the tree view associated with `selection`.

## iterIsSelected

treeSelectionIterIsSelected Source #

Arguments

:: (HasCallStack, MonadIO m, IsTreeSelection a) |
=> a | `selection`: A `TreeSelection`
-> TreeIter | `iter`: A valid `TreeIter`
-> m Bool | Returns: `True`, if `iter` is selected

Returns `True` if the row at `iter` is currently selected.

## pathIsSelected

treeSelectionPathIsSelected Source #

Arguments

:: (HasCallStack, MonadIO m, IsTreeSelection a) |
=> a | `selection`: A `TreeSelection`.
-> TreePath | `path`: A `TreePath` to check selection on.
-> m Bool | Returns: `True` if `path` is selected.

Returns `True` if the row pointed to by `path` is currently selected. If `path` does not point to a valid location, `False` is returned

## selectAll

treeSelectionSelectAll Source #

Arguments

:: (HasCallStack, MonadIO m, IsTreeSelection a) |
=> a | `selection`: A `TreeSelection`.
-> m () |

Selects all the nodes. `selection` must be set to `GTK_SELECTION_MULTIPLE` mode.

## selectIter

treeSelectionSelectIter Source #

Arguments

:: (HasCallStack, MonadIO m, IsTreeSelection a) |
=> a | `selection`: A `TreeSelection`.
-> TreeIter | `iter`: The `TreeIter` to be selected.
-> m () |

Selects the specified iterator.

## selectPath

treeSelectionSelectPath Source #

Arguments

:: (HasCallStack, MonadIO m, IsTreeSelection a) |
=> a | `selection`: A `TreeSelection`.
-> TreePath | `path`: The `TreePath` to be selected.
-> m () |

Select the row at `path`.

## selectRange

treeSelectionSelectRange Source #

Arguments

:: (HasCallStack, MonadIO m, IsTreeSelection a) |
=> a | `selection`: A `TreeSelection`.
-> TreePath | `startPath`: The initial node of the range.
-> TreePath | `endPath`: The final node of the range.
-> m () |

Selects a range of nodes, determined by `startPath` and `endPath` inclusive. `selection` must be set to `GTK_SELECTION_MULTIPLE` mode.

## selectedForeach

treeSelectionSelectedForeach Source #

Arguments

:: (HasCallStack, MonadIO m, IsTreeSelection a) |
=> a | `selection`: A `TreeSelection`.
-> TreeSelectionForeachFunc | `func`: The function to call for each selected node.
-> m () |

Calls a function for each selected node. Note that you cannot modify the tree or selection from within this function. As a result, `treeSelectionGetSelectedRows` might be more useful.

## setMode

treeSelectionSetMode Source #

Arguments

:: (HasCallStack, MonadIO m, IsTreeSelection a) |
=> a | `selection`: A `TreeSelection`.
-> SelectionMode | `type`: The selection mode
-> m () |

Sets the selection mode of the `selection`. If the previous type was `GTK_SELECTION_MULTIPLE`, then the anchor is kept selected, if it was previously selected.

## setSelectFunction

treeSelectionSetSelectFunction Source #

Arguments

:: (HasCallStack, MonadIO m, IsTreeSelection a) |
=> a | `selection`: A `TreeSelection`.
-> Maybe TreeSelectionFunc | `func`: The selection function. May be `Nothing`
-> m () |

Sets the selection function.

If set, this function is called before any node is selected or unselected, giving some control over which nodes are selected. The select function should return `True` if the state of the node may be toggled, and `False` if the state of the node should be left unchanged.

## unselectAll

treeSelectionUnselectAll Source #

Arguments

:: (HasCallStack, MonadIO m, IsTreeSelection a) |
=> a | `selection`: A `TreeSelection`.
-> m () |

Unselects all the nodes.

## unselectIter

treeSelectionUnselectIter Source #

Arguments

:: (HasCallStack, MonadIO m, IsTreeSelection a) |
=> a | `selection`: A `TreeSelection`.
-> TreeIter | `iter`: The `TreeIter` to be unselected.
-> m () |

Unselects the specified iterator.

## unselectPath

treeSelectionUnselectPath Source #

Arguments

:: (HasCallStack, MonadIO m, IsTreeSelection a) |
=> a | `selection`: A `TreeSelection`.
-> TreePath | `path`: The `TreePath` to be unselected.
-> m () |

Unselects the row at `path`.

## unselectRange

treeSelectionUnselectRange Source #

Arguments

:: (HasCallStack, MonadIO m, IsTreeSelection a) |
=> a | `selection`: A `TreeSelection`.
-> TreePath | `startPath`: The initial node of the range.
-> TreePath | `endPath`: The initial node of the range.
-> m () |

Unselects a range of nodes, determined by `startPath` and `endPath` inclusive.

Since: 2.2

# Properties

## mode

Selection mode. See `treeSelectionSetMode` for more information on this property.

Since: 3.2

constructTreeSelectionMode :: (IsTreeSelection o, MonadIO m) => SelectionMode -> m (GValueConstruct o) Source #

Construct a `GValueConstruct` with valid value for the “`mode`” property. This is rarely needed directly, but it is used by `new`.

getTreeSelectionMode :: (MonadIO m, IsTreeSelection o) => o -> m SelectionMode Source #

Get the value of the “`mode`” property. When overloading is enabled, this is equivalent to

    get treeSelection #mode

setTreeSelectionMode :: (MonadIO m, IsTreeSelection o) => o -> SelectionMode -> m () Source #

Set the value of the “`mode`” property. When overloading is enabled, this is equivalent to

    set treeSelection [ #mode := value ]

# Signals

## changed

type TreeSelectionChangedCallback = IO () Source #

Emitted whenever the selection has (possibly) changed. Please note that this signal is mostly a hint. It may only be emitted once when a range of rows are selected, and it may occasionally be emitted when nothing has happened.

afterTreeSelectionChanged :: (IsTreeSelection a, MonadIO m) => a -> ((?self :: a) => TreeSelectionChangedCallback) -> m SignalHandlerId Source #

Connect a signal handler for the changed signal, to be run after the default handler. When overloading is enabled, this is equivalent to

    after treeSelection #changed callback

By default the object invoking the signal is not passed to the callback. If you need to access it, you can use the implit `?self` parameter. Note that this requires activating the `ImplicitParams` GHC extension.

onTreeSelectionChanged :: (IsTreeSelection a, MonadIO m) => a -> ((?self :: a) => TreeSelectionChangedCallback) -> m SignalHandlerId Source #

Connect a signal handler for the changed signal, to be run before the default handler. When overloading is enabled, this is equivalent to

    on treeSelection #changed callback