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

16
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);
@ -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
*/

58
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)
@ -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.
@ -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] =

24
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,
@ -619,7 +621,9 @@ 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