AuroraMiddleware/gtk
1
0
Fork 1
mirror of https://gitlab.gnome.org/GNOME/gtk.git synced 2024-12-25 21:21:21 +00:00
Code Issues Projects Releases Wiki Activity

docs: Tweak documentation for list widgets

Browse Source 
Fix numerous cases of : vs :: for signal references,
add some more details here and there.
This commit is contained in:
Matthias Clasen 2020-08-03 18:41:36 -04:00
parent 7972dc8776
commit 20c1fb0a0a
10 changed files with 77 additions and 63 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
docs/reference/gtk/gtk4-sections.txt
View File

@ -431,7 +431,7 @@ gtk_single_selection_get_type
<SECTION>
<FILE>gtkmultiselection</FILE>
<TITLE>GtkMultiSeledction</TITLE>
<TITLE>GtkMultiSelection</TITLE>
GtkMultiSelection
gtk_multi_selection_new
gtk_multi_selection_get_model

10
gtk/gtkcolumnviewcolumn.c
View File

@ -42,6 +42,13 @@
* @see_also: #GtkColumnView
*
* GtkColumnViewColumn represents the columns being added to #GtkColumnView.
*
* Columns have a title, and can optionally have a header menu set
* with gtk_column_view_column_set_header_menu().
*
* A sorter can be associated with a column using
* gtk_column_view_column_set_sorter(), to let users influence sorting by
* clicking on the column header.
*/
struct _GtkColumnViewColumn
@ -756,6 +763,9 @@ gtk_column_view_column_remove_from_sorter (GtkColumnViewColumn *self)
*
* This sorter can be made active by clicking on the column
* header, or by calling gtk_column_view_sort_by_column().
*
* See gtk_column_view_get_sorter() for the necessary steps
* for setting up customizable sorting for #GtkColumnView.
*/
void
gtk_column_view_column_set_sorter (GtkColumnViewColumn *self,

14
gtk/gtkdirectorylist.c
View File

@ -34,21 +34,22 @@
* It presents a #GListModel and fills it asynchronously with the #GFileInfos
* returned from that function.
*
* Enumeration will start automatically when a the GtkDirectoryList:file property
* Enumeration will start automatically when a the #GtkDirectoryList:file property
* is set.
*
* While the #GtkDirectoryList is being filled, the GtkDirectoryList:loading
* While the #GtkDirectoryList is being filled, the #GtkDirectoryList:loading
* property will be set to %TRUE. You can listen to that property if you want
* to show information like a #GtkSpinner or a "Loading..." text.
* If loading fails at any point, the GtkDirectoryList:error property will be set
* to give more indication about the failure.
*
* If loading fails at any point, the #GtkDirectoryList:error property will be
* set to give more indication about the failure.
*
* The #GFileInfos returned from a #GtkDirectoryList have the "standard::file"
* attribute set to the #GFile they refer to. This way you can get at the file
* that is referred to in the same way you would via g_file_enumerator_get_child().
* This means you do not need access to the #GtkDirectoryList but can access
* the #GFile directly from the #GFileInfo when operating with a #GtkListView or
* similar.
* the #GFile directly from the #GFileInfo when operating with a #GtkListView
* or similar.
*/
/* random number that everyone else seems to use, too */
@ -817,6 +818,7 @@ gtk_directory_list_get_io_priority (GtkDirectoryList *self)
*
* Returns %TRUE if the children enumeration is currently in
* progress.
*
* Files will be added to @self from time to time while loading is
* going on. The order in which are added is undefined and may change
* inbetween runs.

6
gtk/gtkdropdown.c
View File

@ -58,13 +58,11 @@
*
* The options are given to GtkDropDown in the form of #GListModel,
* and how the individual options are represented is determined by
* a #GtkListItemFactory. The default factory displays simple strings,
* and expects to obtain these from the model by evaluating an expression
* that has to be provided via gtk_drop_down_set_expression().
* a #GtkListItemFactory. The default factory displays simple strings.
*
* GtkDropDown knows how to obtain strings from the items in a
* #GtkStringList; for other models, you have to provide an expression
* to find the strings.
* to find the strings via gtk_drop_down_set_expression().
*
* GtkDropDown can optionally allow search in the popup, which is
* useful if the list of options is long. To enable the search entry,

2
gtk/gtkmultiselection.c
View File

@ -347,7 +347,7 @@ gtk_multi_selection_class_init (GtkMultiSelectionClass *klass)
gobject_class->dispose = gtk_multi_selection_dispose;
/**
* GtkMultiSelection:model
* GtkMultiSelection:model:
*
* The list managed by this selection
*/

2
gtk/gtknoselection.c
View File

@ -31,7 +31,7 @@
* @Title: GtkNoSelection
* @see_also: #GtkSelectionModel
*
* GtkNoSelection is an implementation of the #GtkSelectionModel interface
* GtkNoSelection is an implementation of the #GtkSelectionModel interface
* that does not allow selecting anything.
*
* This model is meant to be used as a simple wrapper to #GListModels when a

62
gtk/gtkselectionmodel.c
View File

@ -31,40 +31,40 @@
* @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 adding
* support for selections. This support is then used by widgets using list models to add
* the ability to select and unselect various items.
* #GtkSelectionModel is an interface that extends the #GListModel interface by
* adding support for selections. 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 mode common selection modes such as
* #GtkSingleSelection, so you will only need to implement this interface if you want
* detailed control about how selections should be handled.
* GTK provides default implementations of the most common selection modes such
* as #GtkSingleSelection, so you will only need to implement this interface if
* you want detailed control about how selections should be handled.
*
* A #GtkSelectionModel supports a single boolean per item indicating if an item is selected
* or not. This can be queried via gtk_selection_model_is_selected(). When the selected
* state of one or more items changes, the model will emit the
* A #GtkSelectionModel supports a single boolean per item indicating if an item
* is selected or not. This can be queried via gtk_selection_model_is_selected().
* When the selected state of one or more items changes, the model will emit the
* #GtkSelectionModel::selection-changed signal by calling the
* gtk_selection_model_selection_changed() function. The positions given in that signal
* may have their selection state changed, though that is not a requirement.
* If new items added to the model via the #GListModel::items-changed signal are selected
* or not is up to the implementation.
* gtk_selection_model_selection_changed() function. The positions given in that
* signal may have their selection state changed, though that is not a requirement.
* If new items added to the model via the #GListModel::items-changed signal are
* selected or not is up to the implementation.
*
* Note that items added via #GListModel::items-changed may already be selected
* and no #GtkSelectionModel::selection-changed will be emitted for them. So to
* track which items are selected, it is necessary to listen to both signals.
*
* Additionally, the interface can expose functionality to select and unselect items.
* If these functions are implemented, GTK's list widgets will allow users to select and
* unselect items. However, #GtkSelectionModels are free to only implement them
* partially or not at all. In that case the widgets will not support the unimplemented
* operations.
* Additionally, the interface can expose functionality to select and unselect
* items. If these functions are implemented, GTK's list widgets will allow users
* to select and unselect items. However, #GtkSelectionModels are free to only
* implement them partially or not at all. In that case the widgets will not
* support the unimplemented operations.
*
* When selecting or unselecting is supported by a model, the return values of the
* selection functions do NOT indicate if selection or unselection happened. They are
* only meant to indicate complete failure, like when this mode of selecting is not
* supported by the model.
* When selecting or unselecting is supported by a model, the return values of
* the selection functions do *not* indicate if selection or unselection happened.
* They are only meant to indicate complete failure, like when this mode of
* selecting is not supported by the model.
*
* Selections may happen asynchronously, so the only reliable way to find out when an
* item was selected is to listen to the signals that indicate selection.
* Selections may happen asynchronously, so the only reliable way to find out
* when an item was selected is to listen to the signals that indicate selection.
*/
G_DEFINE_INTERFACE (GtkSelectionModel, gtk_selection_model, G_TYPE_LIST_MODEL)
@ -251,7 +251,7 @@ gtk_selection_model_default_init (GtkSelectionModelInterface *iface)
* 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,
* they need to be queried manually.
* they need to be queried manually.
* It is also not necessary for a model to change the selection state of any of
* the items in the selection model, though it would be rather useless to emit
* such a signal.
@ -318,13 +318,13 @@ gtk_selection_model_get_selection (GtkSelectionModel *model)
* @position: start of the queired range
* @n_items: number of items in the queried range
*
* Gets a set containing a set where the values in the range [position,
* position + n_items) match the selected state of the items in that range.
* Gets a set containing a set where the values in the range `[position,
* 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
* you are only interested in part of the model's selected state. A common use
* case is in response to the :selection-changed signal.
* case is in response to the #GtkSelectionModel::selection-changed signal.
*
* Returns: A #GtkBitset that matches the selection state for the given state
* with all other values being undefined.
@ -495,7 +495,7 @@ gtk_selection_model_unselect_all (GtkSelectionModel *model)
* are more likely to implement support for those.
*
* Requests that the selection state of all positions set in @mask be
* updated to the respecitve value in the @selected bitmask.
* updated to the respecitve value in the @selected bitmask.
*
* In pseudocode, it would look something like this:
*
@ -544,8 +544,8 @@ gtk_selection_model_set_selection (GtkSelectionModel *model,
* @n_items: the number of changed items
*
* Helper function for implementations of #GtkSelectionModel.
* Call this when a the selection changes to emit the ::selection-changed
* signal.
* Call this when a the selection changes to emit the
* #GtkSelectionModel::selection-changed signal.
*/
void
gtk_selection_model_selection_changed (GtkSelectionModel *model,

12
gtk/gtksignallistitemfactory.c
View File

@ -163,7 +163,7 @@ gtk_signal_list_item_factory_class_init (GtkSignalListItemFactoryClass *klass)
* The ::setup signal is emitted when a new listitem has been created and
* needs to be setup for use. It is the first signal emitted for every listitem.
*
* The GtkSignalListItemFactory::teardown signal is the opposite of this signal
* The #GtkSignalListItemFactory::teardown signal is the opposite of this signal
* and can be used to undo everything done in this signal.
*/
signals[SETUP] =
@ -184,13 +184,13 @@ gtk_signal_list_item_factory_class_init (GtkSignalListItemFactoryClass *klass)
* @self: The #GtkSignalListItemFactory
* @listitem: The #GtkListItem to bind
*
* The ::bind signal is emitted when a new GtkListItem:item has been set
* The ::bind signal is emitted when a new #GtkListItem:item has been set
* on the @listitem and should be bound for use.
*
* After this signal was emitted, the listitem might be shown in a #GtkListView
* or other list widget.
*
* The GtkSignalListItemFactory::unbind signal is the opposite of this signal
* The #GtkSignalListItemFactory::unbind signal is the opposite of this signal
* and can be used to undo everything done in this signal.
*/
signals[BIND] =
@ -212,9 +212,9 @@ gtk_signal_list_item_factory_class_init (GtkSignalListItemFactoryClass *klass)
* @listitem: The #GtkListItem to unbind
*
* The ::unbind signal is emitted when a listitem has been removed from use
* in a list widget and its new GtkListItem:item is about to be unset.
* in a list widget and its new #GtkListItem:item is about to be unset.
*
* This signal is the opposite of the GtkSignalListItemFactory::bind signal
* This signal is the opposite of the #GtkSignalListItemFactory::bind signal
* and should be used to undo everything done in that signal.
*/
signals[UNBIND] =
@ -238,7 +238,7 @@ gtk_signal_list_item_factory_class_init (GtkSignalListItemFactoryClass *klass)
* The ::teardown signal is emitted when a listitem is about to be destroyed.
* It is the last signal ever emitted for this @listitem.
*
* This signal is the opposite of the GtkSignalListItemFactory::setup signal
* This signal is the opposite of the #GtkSignalListItemFactory::setup signal
* and should be used to undo everything done in that signal.
*/
signals[TEARDOWN] =

26
gtk/gtksingleselection.c
View File

@ -36,8 +36,8 @@
* used by list widgets in GTK.
*
* Note that the selection is *persistent* -- if the selected item is removed
* and re-added in the same ::items-changed emission, it stays selected. In
* particular, this means that changing the sort order of an underlying sort
* and re-added in the same #GListModel::items-changed emission, it stays selected.
* In particular, this means that changing the sort order of an underlying sort
* model will preserve the selection.
*/
struct _GtkSingleSelection
@ -570,11 +570,13 @@ gtk_single_selection_get_selected (GtkSingleSelection *self)
* @self: a #GtkSingleSelection
* @position: the item to select or #GTK_INVALID_LIST_POSITION
*
* Selects the item at the given position. If the list does not have an item at
* @position or #GTK_INVALID_LIST_POSITION is given, the behavior depends on the
* value of the GtkSingleSelection:autoselect property: If it is set, no change
* will occur and the old item will stay selected. If it is unset, the selection
* will be unset and no item will be selected.
* Selects the item at the given position.
*
* If the list does not have an item at @position or
* #GTK_INVALID_LIST_POSITION is given, the behavior depends on the
* value of the #GtkSingleSelection:autoselect property: If it is set,
* no change will occur and the old item will stay selected. If it is
* unset, the selection will be unset and no item will be selected.
**/
void
gtk_single_selection_set_selected (GtkSingleSelection *self,
@ -618,8 +620,10 @@ gtk_single_selection_set_selected (GtkSingleSelection *self,
/**
* gtk_single_selection_get_selected_item:
* @self: a #GtkSingleSelection
*
* Gets the selected item. If no item is selected, %NULL is returned.
*
* Gets the selected item.
*
* If no item is selected, %NULL is returned.
*
* Returns: (transfer none): The selected item
*/
@ -703,9 +707,9 @@ gtk_single_selection_get_can_unselect (GtkSingleSelection *self)
* If %TRUE, unselecting the current item via
* gtk_selection_model_unselect_item() is supported.
*
* Note that setting GtkSingleSelection:autoselect will cause the
* Note that setting #GtkSingleSelection:autoselect will cause the
* unselecting to not work, so it practically makes no sense to set
* both at the same time the same time..
* both at the same time the same time.
**/
void
gtk_single_selection_set_can_unselect (GtkSingleSelection *self,

4
gtk/gtkstringlist.c
View File

@ -466,11 +466,11 @@ gtk_string_list_new (const char * const *strings)
* Changes @self by removing @n_removals strings and adding @additions
* to it.
*
* This function is more efficient than gtk_string_list_insert() and
* This function is more efficient than gtk_string_list_append() and
* gtk_string_list_remove(), because it only emits
* #GListModel::items-changed once for the change.
*
* This function takes a ref on each item in @additions.
* This function copies the strings in @additions.
*
* The parameters @position and @n_removals must be correct (ie:
* @position + @n_removals must be less than or equal to the length