AuroraMiddleware/gtk
1
0
Fork 1
mirror of https://gitlab.gnome.org/GNOME/gtk.git synced 2024-11-14 20:51:07 +00:00
Code Issues Projects Releases Wiki Activity

Merge branch 'doc-links' into 'master'

Browse Source 
Doc links

See merge request GNOME/gtk!2361
This commit is contained in:
Matthias Clasen 2020-08-04 00:35:40 +00:00
commit b4050482ec
16 changed files with 107 additions and 81 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
docs/reference/gtk/gtk-markdown-to-docbook
View File

@ -180,7 +180,7 @@ def ConvertToDocbook(infile, outfile):
else:
division='chapter'
input_format = "markdown" + "".join(MarkdownExtensions)
output_format = "docbook"
output_format = "docbook4"
subprocess.check_call(["pandoc", infile, "-o", outfile,
"--from=" + input_format,
"--to=" + output_format,

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

18
docs/reference/gtk/question_index.md
View File

@ -48,7 +48,7 @@ the question you have, this list is a good place to start.
5. Why does my program leak memory, if I destroy a widget immediately
after creating it ?
If `GtkFooi` isn't a toplevel window, then
If `GtkFoo` isn't a toplevel window, then
foo = gtk_foo_new ();
g_object_unref (foo);
@ -63,7 +63,7 @@ the question you have, this list is a good place to start.
foo = gtk_foo_new ();
g_object_ref_sink (foo);
When you immediately add a widget to a container, it takes care of assuming
the initial floating reference and you don't have to worry about reference
counting at all ... just remove the widget from the container to get rid of it.
@ -80,7 +80,7 @@ the question you have, this list is a good place to start.
7. How do I internationalize a GTK program?
Most people use <[GNU gettext](https://www.gnu.org/software/gettext/),
Most people use [GNU gettext](https://www.gnu.org/software/gettext/),
already required in order to install GLib. On a UNIX or Linux system with
gettext installed, type `info gettext` to read the documentation.
@ -108,7 +108,7 @@ the question you have, this list is a good place to start.
Code using these macros ends up looking like this:
#include &lt;gi18n.h&gt;
#include <gi18n.h>
static const char *global_variable = N_("Translate this string");
@ -162,7 +162,7 @@ the question you have, this list is a good place to start.
if (g_file_get_contents (filename, &amp;text, &amp;length, NULL))
{
utf8_text = g_convert (text, length, "UTF-8", "ISO-8859-1",
NULL, NULL, &amp;error);
NULL, NULL, &error);
if (error != NULL)
{
fprintf ("Couldn't convert file %s to UTF-8\n", filename);
@ -188,9 +188,9 @@ the question you have, this list is a good place to start.
Even if your toolchain can't handle UTF-8 directly, you can still
encode string literals in UTF-8 by using octal or hexadecimal escapes
like `\\212` or `\\xa8` to encode each byte. This is portable, but
like `\212` or `\xa8` to encode each byte. This is portable, but
modifying the escaped strings is not very convenient. Be careful when
mixing hexadecimal escapes with ordinary text; `"\\xa8abcd" is a string
mixing hexadecimal escapes with ordinary text; `"\xa8abcd" is a string
of length 1 !
- Runtime conversion
@ -203,7 +203,7 @@ the question you have, this list is a good place to start.
Here is an example showing the three approaches using the copyright
sign © which has Unicode and ISO-8859-1 codepoint 169 and is represented
in UTF-8 by the two bytes 194, 169, or `"\\302\\251"` as a string literal:
in UTF-8 by the two bytes 194, 169, or `"\302\251"` as a string literal:
g_print ("direct UTF-8: ©");
g_print ("escaped UTF-8: \302\251");
@ -444,7 +444,7 @@ the question you have, this list is a good place to start.
So pack both a #GtkCellRendererPixbuf and a #GtkCellRendererText into the
column.
28. I can set data easily on my #GtkTreeStore/#GtkListStore models using
28. I can set data easily on my #GtkTreeStore or #GtkListStore models using
gtk_list_store_set() and gtk_tree_store_set(), but can't read it back?
Both the #GtkTreeStore and the #GtkListStore implement the #GtkTreeModel

2
docs/reference/gtk/resources.md
View File

@ -33,7 +33,7 @@ good ways to contact the GTK developers, apart from GitLab issues,
are
- the #gtk IRC channel on irc.gnome.org
- the gtk tag on the <[GNOME Discourse instance](https://discourse.gnome.org/tag/gtk)
- the gtk tag on the [GNOME Discourse instance](https://discourse.gnome.org/tag/gtk)
You should not send patches by email, as they will inevitably get lost,
or forgotten. Always open a merge request.

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,

6
gtk/gtkfilter.c
View File

@ -38,7 +38,7 @@
* ones that the function returns %TRUE for.
*
* Filters may change what items they match through their lifetime. In that
* case, they will emit the #GtkFilter:changed signal to notify that previous
* case, they will emit the #GtkFilter::changed signal to notify that previous
* filter results are no longer valid and that items should be checked again
* via gtk_filter_match().
*
@ -141,7 +141,7 @@ gtk_filter_match (GtkFilter *self,
* Gets the known strictness of @filters. If the strictness is not known,
* %GTK_FILTER_MATCH_SOME is returned.
*
* This value may change after emission of the #GtkFilter:changed signal.
* This value may change after emission of the #GtkFilter::changed signal.
*
* This function is meant purely for optimization purposes, filters can
* choose to omit implementing it, but #GtkFilterListModel uses it.
@ -161,7 +161,7 @@ gtk_filter_get_strictness (GtkFilter *self)
* @self: a #GtkFilter
* @change: How the filter changed
*
* Emits the #GtkFilter:changed signal to notify all users of the filter that
* Emits the #GtkFilter::changed signal to notify all users of the filter that
* the filter changed. Users of the filter should then check items again via
* gtk_filter_match().
*

8
gtk/gtkfilterlistmodel.c
View File

@ -786,6 +786,9 @@ gtk_filter_list_model_get_model (GtkFilterListModel *self)
* interesting around 10,000 to 100,000 items.
*
* By default, incremental filtering is disabled.
*
* See gtk_filter_list_model_get_pending() for progress information
* about an ongoing incremental filtering operation.
**/
void
gtk_filter_list_model_set_incremental (GtkFilterListModel *self,
@ -837,8 +840,6 @@ gtk_filter_list_model_get_incremental (GtkFilterListModel *self)
*
* Returns the number of items that have not been filtered yet.
*
* When incremental filtering is not enabled, this always returns 0.
*
* You can use this value to check if @self is busy filtering by
* comparing the return value to 0 or you can compute the percentage
* of the filter remaining by dividing the return value by the total
@ -850,6 +851,9 @@ gtk_filter_list_model_get_incremental (GtkFilterListModel *self)
* percentage = pending / (double) g_list_model_get_n_items (model);
* ]|
*
* If no filter operation is ongoing - in particular when
* #GtkFilterListModel:incremental is %FALSE - this function returns 0.
*
* Returns: The number of items not yet filtered
**/
guint

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,

12
gtk/gtksortlistmodel.c
View File

@ -61,6 +61,10 @@
* #GtkSortListModel is a list model that takes a list model and
* sorts its elements according to a #GtkSorter.
*
* The model can be set up to do incremental sorting, so that
* sorting long lists doesn't block the UI. See
* gtk_sort_list_model_set_incremental() for details.
*
* #GtkSortListModel is a generic model and because of that it
* cannot take advantage of any external knowledge when sorting.
* If you run into performance issues with #GtkSortListModel, it
@ -978,6 +982,9 @@ gtk_sort_list_model_get_sorter (GtkSortListModel *self)
* interesting around 10,000 to 100,000 items.
*
* By default, incremental sorting is disabled.
*
* See gtk_sort_list_model_get_pending() for progress information
* about an ongoing incremental sorting operation.
*/
void
gtk_sort_list_model_set_incremental (GtkSortListModel *self,
@ -1032,8 +1039,9 @@ gtk_sort_list_model_get_incremental (GtkSortListModel *self)
*
* If you want to estimate the progress, you can use code like this:
* |[<!-- language="C" -->
* double progress = 1.0 - (double) gtk_sort_list_model_get_pending (self)
* / MAX (1, g_list_model_get_n_items (G_LIST_MODEL (sort)));
* pending = gtk_sort_list_model_get_pending (self);
* model = gtk_sort_list_model_get_model (self);
* progress = 1.0 - pending / (double) MAX (1, g_list_model_get_n_items (model));
* ]|
*
* If no sort operation is ongoing - in particular when

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