AuroraMiddleware/gtk2
1
0
Fork 0
forked from AuroraMiddleware/gtk
Code Issues Pull Requests Projects Releases Wiki Activity

selectionmodel: Convert docs

Browse Source
This commit is contained in:
Matthias Clasen 2021-03-01 01:51:02 -05:00 committed by Emmanuele Bassi
parent da6b6d44c1
commit 3f201aeb21
1 changed files with 71 additions and 69 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

140
gtk/gtkselectionmodel.c
View File

@ -26,35 +26,33 @@
#include "gtkmarshalers.h" #include "gtkmarshalers.h"
/** /**
* SECTION:gtkselectionmodel * GtkSelectionModel:
* @Title: GtkSelectionModel
* @Short_description: An extension of the list model interface that handles selections
* @See_also: #GListModel, #GtkSingleSelection
* *
* #GtkSelectionModel is an interface that extends the #GListModel interface by * `GtkSelectionModel` is an interface that add support for selection to list models.
* adding support for selections. This support is then used by widgets using list *
* models to add the ability to select and unselect various items. * This support is then used by widgets using list models to add the ability
* to select and unselect various items.
* *
* GTK provides default implementations of the most common selection modes such * GTK provides default implementations of the most common selection modes such
* as #GtkSingleSelection, so you will only need to implement this interface if * as [class@Gtk.SingleSelection], so you will only need to implement this
* you want detailed control about how selections should be handled. * interface if you want detailed control about how selections should be handled.
* *
* A #GtkSelectionModel supports a single boolean per item indicating if an item * A `GtkSelectionModel` supports a single boolean per item indicating if an item is
* is selected or not. This can be queried via gtk_selection_model_is_selected(). * selected or not. This can be queried via [method@Gtk.SelectionModel.is_selected].
* When the selected state of one or more items changes, the model will emit the * When the selected state of one or more items changes, the model will emit the
* #GtkSelectionModel::selection-changed signal by calling the * [signal@Gtk.SelectionModel::selection-changed] signal by calling the
* gtk_selection_model_selection_changed() function. The positions given in that * [method@Gtk.SelectionModel.selection_changed] function. The positions given
* signal may have their selection state changed, though that is not a requirement. * in that signal may have their selection state changed, though that is not a
* If new items added to the model via the #GListModel::items-changed signal are * requirement. If new items added to the model via the ::items-changed signal
* selected or not is up to the implementation. * are selected or not is up to the implementation.
* *
* Note that items added via #GListModel::items-changed may already be selected * Note that items added via ::items-changed may already be selected and no
* and no #GtkSelectionModel::selection-changed will be emitted for them. So to * [Gtk.SelectionModel::selection-changed] will be emitted for them. So to
* track which items are selected, it is necessary to listen to both signals. * track which items are selected, it is necessary to listen to both signals.
* *
* Additionally, the interface can expose functionality to select and unselect * Additionally, the interface can expose functionality to select and unselect
* items. If these functions are implemented, GTK's list widgets will allow users * items. If these functions are implemented, GTK's list widgets will allow users
* to select and unselect items. However, #GtkSelectionModels are free to only * to select and unselect items. However, `GtkSelectionModel`s are free to only
* implement them partially or not at all. In that case the widgets will not * implement them partially or not at all. In that case the widgets will not
* support the unimplemented operations. * support the unimplemented operations.
* *
@ -244,17 +242,16 @@ gtk_selection_model_default_init (GtkSelectionModelInterface *iface)
/** /**
* GtkSelectionModel::selection-changed * GtkSelectionModel::selection-changed
* @model: a #GtkSelectionModel * @model: a `GtkSelectionModel`
* @position: The first item that may have changed * @position: The first item that may have changed
* @n_items: number of items with changes * @n_items: number of items with changes
* *
* Emitted when the selection state of some of the items in @model changes. * Emitted when the selection state of some of the items in @model changes.
* *
* Note that this signal does not specify the new selection state of the items, * Note that this signal does not specify the new selection state of the
* they need to be queried manually. * items, they need to be queried manually. It is also not necessary for
* It is also not necessary for a model to change the selection state of any of * a model to change the selection state of any of the items in the selection
* the items in the selection model, though it would be rather useless to emit * model, though it would be rather useless to emit such a signal.
* such a signal.
*/ */
signals[SELECTION_CHANGED] = signals[SELECTION_CHANGED] =
g_signal_new ("selection-changed", g_signal_new ("selection-changed",
@ -271,13 +268,13 @@ gtk_selection_model_default_init (GtkSelectionModelInterface *iface)
/** /**
* gtk_selection_model_is_selected: * gtk_selection_model_is_selected:
* @model: a #GtkSelectionModel * @model: a `GtkSelectionModel`
* @position: the position of the item to query * @position: the position of the item to query
* *
* Checks if the given item is selected. * Checks if the given item is selected.
* *
* Returns: %TRUE if the item is selected * Returns: %TRUE if the item is selected
**/ */
gboolean gboolean
gtk_selection_model_is_selected (GtkSelectionModel *model, gtk_selection_model_is_selected (GtkSelectionModel *model,
guint position) guint position)
@ -292,18 +289,18 @@ gtk_selection_model_is_selected (GtkSelectionModel *model,
/** /**
* gtk_selection_model_get_selection: * gtk_selection_model_get_selection:
* @model: a #GtkSelectionModel * @model: a `GtkSelectionModel`
* *
* Gets the set containing all currently selected items in the model. * Gets the set containing all currently selected items in the model.
* *
* This function may be slow, so if you are only interested in single item, * This function may be slow, so if you are only interested in single item,
* consider using gtk_selection_model_is_selected() or if you are only * consider using [method@Gtk.SelectionModel.is_selected] or if you are only
* interested in a few consider gtk_selection_model_get_selection_in_range(). * interested in a few, consider [method@Gtk.SelectionModel.get_selection_in_range].
* *
* Returns: (transfer full): a #GtkBitset containing all the values currently * Returns: (transfer full): a `GtkBitset` containing all the values currently
* selected in @model. If no items are selected, the bitset is empty. * selected in @model. If no items are selected, the bitset is empty.
* The bitset must not be modified. * The bitset must not be modified.
**/ */
GtkBitset * GtkBitset *
gtk_selection_model_get_selection (GtkSelectionModel *model) gtk_selection_model_get_selection (GtkSelectionModel *model)
{ {
@ -314,22 +311,22 @@ gtk_selection_model_get_selection (GtkSelectionModel *model)
/** /**
* gtk_selection_model_get_selection_in_range: * gtk_selection_model_get_selection_in_range:
* @model: a #GtkSelectionModel * @model: a `GtkSelectionModel`
* @position: start of the queired range * @position: start of the queired range
* @n_items: number of items in the queried range * @n_items: number of items in the queried range
* *
* Gets a set containing a set where the values in the range `[position, * Gets the set of selected items in a range.
* position + n_items)` match the selected state of the items in that range.
* All values outside that range are undefined.
* *
* This function is an optimization for gtk_selection_model_get_selection() when * This function is an optimization for
* you are only interested in part of the model's selected state. A common use * [method@Gtk.SelectionModel.get_selection] when you are only
* case is in response to the #GtkSelectionModel::selection-changed signal. * interested in part of the model's selected state. A common use
* case is in response to the [signal@Gtk.SelectionModel::selection-changed]
* signal.
* *
* Returns: A #GtkBitset that matches the selection state for the given state * Returns: A `GtkBitset` that matches the selection state
* with all other values being undefined. * for the given range with all other values being undefined.
* The bitset must not be modified. * The bitset must not be modified.
**/ */
GtkBitset * GtkBitset *
gtk_selection_model_get_selection_in_range (GtkSelectionModel *model, gtk_selection_model_get_selection_in_range (GtkSelectionModel *model,
guint position, guint position,
@ -348,14 +345,14 @@ gtk_selection_model_get_selection_in_range (GtkSelectionModel *model,
/** /**
* gtk_selection_model_select_item: * gtk_selection_model_select_item:
* @model: a #GtkSelectionModel * @model: a `GtkSelectionModel`
* @position: the position of the item to select * @position: the position of the item to select
* @unselect_rest: whether previously selected items should be unselected * @unselect_rest: whether previously selected items should be unselected
* *
* Requests to select an item in the model. * Requests to select an item in the model.
* *
* Returns: %TRUE if this action was supported and no fallback should be * Returns: %TRUE if this action was supported and no fallback should be
* tried. This does not mean the item was selected. * tried. This does not mean the item was selected.
*/ */
gboolean gboolean
gtk_selection_model_select_item (GtkSelectionModel *model, gtk_selection_model_select_item (GtkSelectionModel *model,
@ -372,7 +369,7 @@ gtk_selection_model_select_item (GtkSelectionModel *model,
/** /**
* gtk_selection_model_unselect_item: * gtk_selection_model_unselect_item:
* @model: a #GtkSelectionModel * @model: a `GtkSelectionModel`
* @position: the position of the item to unselect * @position: the position of the item to unselect
* *
* Requests to unselect an item in the model. * Requests to unselect an item in the model.
@ -394,7 +391,7 @@ gtk_selection_model_unselect_item (GtkSelectionModel *model,
/** /**
* gtk_selection_model_select_range: * gtk_selection_model_select_range:
* @model: a #GtkSelectionModel * @model: a `GtkSelectionModel`
* @position: the first item to select * @position: the first item to select
* @n_items: the number of items to select * @n_items: the number of items to select
* @unselect_rest: whether previously selected items should be unselected * @unselect_rest: whether previously selected items should be unselected
@ -420,7 +417,7 @@ gtk_selection_model_select_range (GtkSelectionModel *model,
/** /**
* gtk_selection_model_unselect_range: * gtk_selection_model_unselect_range:
* @model: a #GtkSelectionModel * @model: a `GtkSelectionModel`
* @position: the first item to unselect * @position: the first item to unselect
* @n_items: the number of items to unselect * @n_items: the number of items to unselect
* *
@ -444,7 +441,7 @@ gtk_selection_model_unselect_range (GtkSelectionModel *model,
/** /**
* gtk_selection_model_select_all: * gtk_selection_model_select_all:
* @model: a #GtkSelectionModel * @model: a `GtkSelectionModel`
* *
* Requests to select all items in the model. * Requests to select all items in the model.
* *
@ -464,7 +461,7 @@ gtk_selection_model_select_all (GtkSelectionModel *model)
/** /**
* gtk_selection_model_unselect_all: * gtk_selection_model_unselect_all:
* @model: a #GtkSelectionModel * @model: a `GtkSelectionModel`
* *
* Requests to unselect all items in the model. * Requests to unselect all items in the model.
* *
@ -484,22 +481,24 @@ gtk_selection_model_unselect_all (GtkSelectionModel *model)
/** /**
* gtk_selection_model_set_selection: * gtk_selection_model_set_selection:
* @model: a #GtkSelectionModel * @model: a `GtkSelectionModel`
* @selected: bitmask specifying if items should be selected or * @selected: bitmask specifying if items should be selected or
* unselected * unselected
* @mask: bitmask specifying which items should be updated * @mask: bitmask specifying which items should be updated
* *
* This is the most advanced selection updating method that allows * Make selection changes.
* the most fine-grained control over selection changes.
* If you can, you should try the simpler versions, as implementations
* are more likely to implement support for those.
* *
* Requests that the selection state of all positions set in @mask be * This is the most advanced selection updating method that allows
* updated to the respective value in the @selected bitmask. * the most fine-grained control over selection changes. If you can,
* you should try the simpler versions, as implementations are more
* likely to implement support for those.
*
* Requests that the selection state of all positions set in @mask
* be updated to the respective value in the @selected bitmask.
* *
* In pseudocode, it would look something like this: * In pseudocode, it would look something like this:
* *
* |[<!-- language="C" --> * ```c
* for (i = 0; i < n_items; i++) * for (i = 0; i < n_items; i++)
* { * {
* // don't change values not in the mask * // don't change values not in the mask
@ -512,16 +511,19 @@ gtk_selection_model_unselect_all (GtkSelectionModel *model)
* unselect_item (i); * unselect_item (i);
* } * }
* *
* gtk_selection_model_selection_changed (model, first_changed_item, n_changed_items); * gtk_selection_model_selection_changed (model,
* ]| * first_changed_item,
* n_changed_items);
* ```
* *
* @mask and @selected must not be modified. They may refer to the same bitset, * @mask and @selected must not be modified. They may refer to the
* which would mean that every item in the set should be selected. * same bitset, which would mean that every item in the set should
* be selected.
* *
* Returns: %TRUE if this action was supported and no fallback should be * Returns: %TRUE if this action was supported and no fallback should be
* tried. This does not mean that all items were updated according * tried. This does not mean that all items were updated according
* to the inputs. * to the inputs.
**/ */
gboolean gboolean
gtk_selection_model_set_selection (GtkSelectionModel *model, gtk_selection_model_set_selection (GtkSelectionModel *model,
GtkBitset *selected, GtkBitset *selected,
@ -539,13 +541,14 @@ gtk_selection_model_set_selection (GtkSelectionModel *model,
/** /**
* gtk_selection_model_selection_changed: * gtk_selection_model_selection_changed:
* @model: a #GtkSelectionModel * @model: a `GtkSelectionModel`
* @position: the first changed item * @position: the first changed item
* @n_items: the number of changed items * @n_items: the number of changed items
* *
* Helper function for implementations of #GtkSelectionModel. * Helper function for implementations of `GtkSelectionModel`.
*
* Call this when a the selection changes to emit the * Call this when a the selection changes to emit the
* #GtkSelectionModel::selection-changed signal. * [signal@Gtk.SelectionModel::selection-changed] signal.
*/ */
void void
gtk_selection_model_selection_changed (GtkSelectionModel *model, gtk_selection_model_selection_changed (GtkSelectionModel *model,
@ -558,4 +561,3 @@ gtk_selection_model_selection_changed (GtkSelectionModel *model,
g_signal_emit (model, signals[SELECTION_CHANGED], 0, position, n_items); g_signal_emit (model, signals[SELECTION_CHANGED], 0, position, n_items);
} }