gi-gtk-hs-0.3.18: A wrapper for gi-gtk, adding a few more idiomatic API parts on top

Stability | provisional
Portability | portable (depends on GHC)
Safe Haskell | None
Language | Haskell2010

Data.GI.Gtk.ModelView.CustomStore

Contents

- The definition of a row-based store.

Description

Allows a custom data structure to be used with the `TreeView` and other widgets that follow the model-view-controller paradigm. The two models `ListStore` and `TreeStore` are based on the `CustomStore`. Even if no application-specific tree model should be implemented, this module is relevant in that it provides the functions `customStoreSetColumn` and `customStoreGetRow` functions.

Synopsis

- newtype CustomStore private row = CustomStore (ManagedPtr (CustomStore private row))
- data TreeModelFlags
  - = TreeModelFlagsItersPersist
  - | TreeModelFlagsListOnly
  - | AnotherTreeModelFlags Int
- data TreeModelIface row = TreeModelIface {
  - treeModelIfaceGetFlags :: IO [TreeModelFlags]
  - treeModelIfaceGetIter :: TreePath -> IO (Maybe TreeIter)
  - treeModelIfaceGetPath :: TreeIter -> IO TreePath
  - treeModelIfaceGetRow :: TreeIter -> IO row
  - treeModelIfaceIterNext :: TreeIter -> IO (Maybe TreeIter)
  - treeModelIfaceIterChildren :: Maybe TreeIter -> IO (Maybe TreeIter)
  - treeModelIfaceIterHasChild :: TreeIter -> IO Bool
  - treeModelIfaceIterNChildren :: Maybe TreeIter -> IO Int
  - treeModelIfaceIterNthChild :: Maybe TreeIter -> Int -> IO (Maybe TreeIter)
  - treeModelIfaceIterParent :: TreeIter -> IO (Maybe TreeIter)
  - treeModelIfaceRefNode :: TreeIter -> IO ()
  - treeModelIfaceUnrefNode :: TreeIter -> IO ()
  }
- data DragSourceIface (model :: Type -> Type) row = DragSourceIface {
  - customDragSourceRowDraggable :: model row -> TreePath -> IO Bool
  - customDragSourceDragDataGet :: model row -> TreePath -> SelectionData -> IO Bool
  - customDragSourceDragDataDelete :: model row -> TreePath -> IO Bool
  }
- data DragDestIface (model :: Type -> Type) row = DragDestIface {
  - customDragDestRowDropPossible :: model row -> TreePath -> SelectionData -> IO Bool
  - customDragDestDragDataReceived :: model row -> TreePath -> SelectionData -> IO Bool
  }
- customStoreNew :: (MonadIO m, IsTreeModel (model row), IsTypedTreeModel model) => private -> (CustomStore private row -> model row) -> TreeModelIface row -> Maybe (DragSourceIface model row) -> Maybe (DragDestIface model row) -> m (model row)
- customStoreGetRow :: (MonadIO m, IsTypedTreeModel model) => model row -> TreeIter -> m row
- customStoreSetColumn :: (MonadIO m, IsTypedTreeModel model) => model row -> ColumnId row ty -> (row -> ty) -> m ()
- customStoreGetPrivate :: CustomStore private row -> private
- customStoreGetStamp :: MonadIO m => CustomStore private row -> m Int32
- customStoreInvalidateIters :: MonadIO m => CustomStore private row -> m ()

# The definition of a row-based store.

newtype CustomStore private row Source #

A `CustomStore` is an instance of a Gtk+ `TreeModel` and can thus be used for any widget that stores data in a `TreeModel`. The user may either create an instance of a `CustomStore` or use one of the pre-defined models `ListStore` or `TreeStore`.

Constructors

CustomStore (ManagedPtr (CustomStore private row)) |

#### Instances

Instances details

GObject (CustomStore private row) Source # |
Instance details Defined in Data.GI.Gtk.ModelView.CustomStore
TypedObject (CustomStore private row) Source # |
Instance details Defined in Data.GI.Gtk.ModelView.CustomStore Methods glibType :: IO GType Source #
HasParentTypes (CustomStore private row) Source # |
Instance details Defined in Data.GI.Gtk.ModelView.CustomStore
type ParentTypes (CustomStore private row) Source # |
Instance details Defined in Data.GI.Gtk.ModelView.CustomStore type ParentTypes (CustomStore private row) = '[TreeModel]

data TreeModelFlags Source #

These flags indicate various properties of a `TreeModel`.

They are returned by `treeModelGetFlags`, and must be static for the lifetime of the object. A more complete description of `GTK_TREE_MODEL_ITERS_PERSIST` can be found in the overview of this section.

Constructors

TreeModelFlagsItersPersist | iterators survive all signals emitted by the tree
TreeModelFlagsListOnly | the model is a list only, and never has children
AnotherTreeModelFlags Int | Catch-all for unknown values

#### Instances

Instances details

Enum TreeModelFlags |

Instance details

Defined in GI.Gtk.Flags

Methods

succ :: TreeModelFlags -> TreeModelFlags Source #

pred :: TreeModelFlags -> TreeModelFlags Source #

toEnum :: Int -> TreeModelFlags Source #

fromEnum :: TreeModelFlags -> Int Source #

enumFrom :: TreeModelFlags -> [TreeModelFlags] Source #

enumFromThen :: TreeModelFlags -> TreeModelFlags -> [TreeModelFlags] Source #

enumFromTo :: TreeModelFlags -> TreeModelFlags -> [TreeModelFlags] Source #

enumFromThenTo :: TreeModelFlags -> TreeModelFlags -> TreeModelFlags -> [TreeModelFlags] Source #

Show TreeModelFlags |
Instance details Defined in GI.Gtk.Flags Methods showsPrec :: Int -> TreeModelFlags -> ShowS Source # show :: TreeModelFlags -> String Source # showList :: [TreeModelFlags] -> ShowS Source #
Eq TreeModelFlags |
Instance details Defined in GI.Gtk.Flags Methods (==) :: TreeModelFlags -> TreeModelFlags -> Bool Source # (/=) :: TreeModelFlags -> TreeModelFlags -> Bool Source #
Ord TreeModelFlags |

Instance details

Defined in GI.Gtk.Flags

Methods

compare :: TreeModelFlags -> TreeModelFlags -> Ordering Source #

(<) :: TreeModelFlags -> TreeModelFlags -> Bool Source #

(<=) :: TreeModelFlags -> TreeModelFlags -> Bool Source #

(>) :: TreeModelFlags -> TreeModelFlags -> Bool Source #

(>=) :: TreeModelFlags -> TreeModelFlags -> Bool Source #

max :: TreeModelFlags -> TreeModelFlags -> TreeModelFlags Source #

min :: TreeModelFlags -> TreeModelFlags -> TreeModelFlags Source #

BoxedFlags TreeModelFlags |
Instance details Defined in GI.Gtk.Flags
IsGFlag TreeModelFlags |
Instance details Defined in GI.Gtk.Flags
TypedObject TreeModelFlags |
Instance details Defined in GI.Gtk.Flags Methods glibType :: IO GType Source #
HasParentTypes TreeModelFlags |
Instance details Defined in GI.Gtk.Flags
type ParentTypes TreeModelFlags |
Instance details Defined in GI.Gtk.Flags type ParentTypes TreeModelFlags = '[] :: [Type]

data TreeModelIface row Source #

The `TreeModelIface` structure contains all functions that are required to implement an application-specific `TreeModel`.

Constructors

TreeModelIface |

Fields

- treeModelIfaceGetFlags :: IO [TreeModelFlags]

  Return the flags that are valid for this model.

- treeModelIfaceGetIter :: TreePath -> IO (Maybe TreeIter)

  Convert an path into the tree into a more concise `TreeIter`. Return `Nothing` if the path does not exit.

- treeModelIfaceGetPath :: TreeIter -> IO TreePath

  Convert an iterator to a path. The iterator will always be valid.

- treeModelIfaceGetRow :: TreeIter -> IO row

  Retrieve a row at the given iterator.

- treeModelIfaceIterNext :: TreeIter -> IO (Maybe TreeIter)

  Advance the given iterator to the next node at the same level. Return `Nothing` if there is no next node at this level.

- treeModelIfaceIterChildren :: Maybe TreeIter -> IO (Maybe TreeIter)

  Advance the given iterator to the first child of this iterator. Return `Notihing` if the node at this iterator has no children.

- treeModelIfaceIterHasChild :: TreeIter -> IO Bool

  Check if the node at the given iterator has children.

- treeModelIfaceIterNChildren :: Maybe TreeIter -> IO Int

  Query the number of children the the node at the given iteratore has.

- treeModelIfaceIterNthChild :: Maybe TreeIter -> Int -> IO (Maybe TreeIter)

  Ask for an iterator to the `n`th child. Return `Nothing` if no such child exists.

- treeModelIfaceIterParent :: TreeIter -> IO (Maybe TreeIter)

  Ask for an iterator to the parent of the node.

- treeModelIfaceRefNode :: TreeIter -> IO ()

  Increase a reference count for this node. A positive reference count indicates that the node is used (that is, most likely it is visible) in at least one widget. Tracking reference counts for nodes is optional but may be useful to infer when a given row can be discarded if it was retrieved from an external source.

- treeModelIfaceUnrefNode :: TreeIter -> IO ()

  Decrement the reference count of the given node.

data DragSourceIface (model :: Type -> Type) row Source #

A structure containing functions that enable this widget to be used as a source in drag-and-drop.

Constructors

DragSourceIface |

Fields

- customDragSourceRowDraggable :: model row -> TreePath -> IO Bool

  Determine if the row at the given path is draggable. Return `False` if for some reason this row should not be dragged by the user.

- customDragSourceDragDataGet :: model row -> TreePath -> SelectionData -> IO Bool

  Fill in the `SelectionData` structure with information on the given node using `selectionDataSet`.

- customDragSourceDragDataDelete :: model row -> TreePath -> IO Bool

  The widget is informed that the row at the given path should be deleted as the result of this drag.

data DragDestIface (model :: Type -> Type) row Source #

A structure containing functions that enable this widget to be used as a target in drag-and-drop.

Constructors

DragDestIface |

Fields

- customDragDestRowDropPossible :: model row -> TreePath -> SelectionData -> IO Bool

  Tell the drag-and-drop mechanism if the row can be dropped at the given path.

- customDragDestDragDataReceived :: model row -> TreePath -> SelectionData -> IO Bool

  The data in the `SelectionDataM` structure should be read using `selectionDataGet` and its information be used to insert a new row at the given path.

customStoreNew Source #

Arguments

:: (MonadIO m, IsTreeModel (model row), IsTypedTreeModel model) |
=> private | Any private data the store needs to store. Usually an `IORef`.
-> (CustomStore private row -> model row) |
-> TreeModelIface row | Functions necessary to implement the `TreeModel` interface.
-> Maybe (DragSourceIface model row) | Functions to enable this store to generate drag events.
-> Maybe (DragDestIface model row) | Functions to enable this store to receive drag events.
-> m (model row) |

Create a new store that implements the `TreeModelIface` interface and optionally the `DragSourceIface` and the `DragDestIface`. If the latter two are set to `Nothing` a dummy interface is substituted that rejects every drag and drop.

customStoreGetRow :: (MonadIO m, IsTypedTreeModel model) => model row -> TreeIter -> m row Source #

Extract a row of the given model at the given `TreeIter`.

customStoreSetColumn Source #

Arguments

:: (MonadIO m, IsTypedTreeModel model) |
=> model row | the store in which to allocate a new column
-> ColumnId row ty | the column that should be set
-> (row -> ty) | the function that sets the property
-> m () |

Set or update a column mapping. This function should be used before the model is installed into a widget since the number of defined columns are only checked once by widgets.

customStoreGetPrivate :: CustomStore private row -> private Source #

Return the private data stored in this `CustomStore`. The private data is meant as a container for the data stored in this model.

customStoreGetStamp :: MonadIO m => CustomStore private row -> m Int32 Source #

Query the current value of the stamp that is used to create `TreeIter` iterators. The stamp is compared each time a view accesses this store. If the stamp doesn't match, a warning is emitted. The stamp should be updated each time a the data in the model changes. The rationale is that a view should never use a stale `TreeIter`, i.e., one that refers to an old model.

customStoreInvalidateIters :: MonadIO m => CustomStore private row -> m () Source #

Create a new stamp. See `customStoreGetStamp`.