GNOME.org
 

[gtksourceview] docs: add documentation for new completion API

commit f2d9f13b235745f6e7502bfccdb9f7e0d7235779
Author: Christian Hergert <chergert redhat com>
Date:   Wed Mar 10 13:38:30 2021 -0800

    docs: add documentation for new completion API

 docs/reference/gtksourceview-5.0-sections.txt |  62 +++++------
 gtksourceview/gtksourcecompletioncontext.c    |  26 +++++
 gtksourceview/gtksourcecompletionproposal.c   |  18 +++-
 gtksourceview/gtksourcecompletionprovider.c   | 141 +++++++++++++++++++++++++-
 4 files changed, 208 insertions(+), 39 deletions(-)
---
diff --git a/docs/reference/gtksourceview-5.0-sections.txt b/docs/reference/gtksourceview-5.0-sections.txt
index 3ea1e2e4..fac3e8b5 100644
--- a/docs/reference/gtksourceview-5.0-sections.txt
+++ b/docs/reference/gtksourceview-5.0-sections.txt
@@ -57,19 +57,19 @@ gtk_source_sort_flags_get_type
 <SECTION>
 <FILE>completion</FILE>
 GtkSourceCompletion
-GTK_SOURCE_COMPLETION_ERROR
-GtkSourceCompletionError
 <SUBSECTION>
+gtk_source_completion_get_view
+gtk_source_completion_get_buffer
+gtk_source_completion_show
+gtk_source_completion_hide
 gtk_source_completion_add_provider
 gtk_source_completion_remove_provider
-gtk_source_completion_get_providers
-gtk_source_completion_start
-gtk_source_completion_hide
-gtk_source_completion_get_info_window
-gtk_source_completion_get_view
-gtk_source_completion_create_context
 gtk_source_completion_block_interactive
 gtk_source_completion_unblock_interactive
+gtk_source_completion_get_page_size
+gtk_source_completion_set_page_size
+gtk_source_completion_fuzzy_match
+gtk_source_completion_fuzzy_highlight
 <SUBSECTION Standard>
 GTK_SOURCE_IS_COMPLETION
 GTK_SOURCE_IS_COMPLETION_CLASS
@@ -79,18 +79,23 @@ GTK_SOURCE_COMPLETION_GET_CLASS
 GTK_SOURCE_TYPE_COMPLETION
 GtkSourceCompletionClass
 gtk_source_completion_get_type
-gtk_source_completion_error_quark
-GTK_SOURCE_TYPE_COMPLETION_ERROR
-gtk_source_completion_error_get_type
 </SECTION>
 
 <SECTION>
 <FILE>completioncontext</FILE>
 GtkSourceCompletionActivation
 GtkSourceCompletionContext
-gtk_source_completion_context_add_proposals
-gtk_source_completion_context_get_iter
 gtk_source_completion_context_get_activation
+gtk_source_completion_context_get_bounds
+gtk_source_completion_context_get_buffer
+gtk_source_completion_context_get_busy
+gtk_source_completion_context_get_completion
+gtk_source_completion_context_get_empty
+gtk_source_completion_context_get_language
+gtk_source_completion_context_get_start_iter
+gtk_source_completion_context_get_view
+gtk_source_completion_context_get_word
+gtk_source_completion_context_set_proposals_for_provider
 <SUBSECTION Standard>
 GTK_SOURCE_IS_COMPLETION_CONTEXT
 GTK_SOURCE_IS_COMPLETION_CONTEXT_CLASS
@@ -108,16 +113,6 @@ gtk_source_completion_activation_get_type
 <FILE>completionproposal</FILE>
 GtkSourceCompletionProposal
 GtkSourceCompletionProposalInterface
-gtk_source_completion_proposal_get_label
-gtk_source_completion_proposal_get_markup
-gtk_source_completion_proposal_get_text
-gtk_source_completion_proposal_get_icon
-gtk_source_completion_proposal_get_icon_name
-gtk_source_completion_proposal_get_gicon
-gtk_source_completion_proposal_get_info
-gtk_source_completion_proposal_changed
-gtk_source_completion_proposal_hash
-gtk_source_completion_proposal_equal
 <SUBSECTION Standard>
 GTK_SOURCE_IS_COMPLETION_PROPOSAL
 GTK_SOURCE_COMPLETION_PROPOSAL
@@ -130,19 +125,16 @@ gtk_source_completion_proposal_get_type
 <FILE>completionprovider</FILE>
 GtkSourceCompletionProvider
 GtkSourceCompletionProviderInterface
-gtk_source_completion_provider_get_name
-gtk_source_completion_provider_get_icon
-gtk_source_completion_provider_get_icon_name
-gtk_source_completion_provider_get_gicon
-gtk_source_completion_provider_populate
-gtk_source_completion_provider_get_activation
-gtk_source_completion_provider_match
-gtk_source_completion_provider_get_info_widget
-gtk_source_completion_provider_update_info
-gtk_source_completion_provider_get_start_iter
-gtk_source_completion_provider_activate_proposal
-gtk_source_completion_provider_get_interactive_delay
+gtk_source_completion_provider_get_title
 gtk_source_completion_provider_get_priority
+gtk_source_completion_provider_is_trigger
+gtk_source_completion_provider_key_activates
+gtk_source_completion_provider_populate_async
+gtk_source_completion_provider_populate_finish
+gtk_source_completion_provider_refilter
+gtk_source_completion_provider_display
+gtk_source_completion_provider_activate
+gtk_source_completion_provider_list_alternates
 <SUBSECTION Standard>
 GTK_SOURCE_IS_COMPLETION_PROVIDER
 GTK_SOURCE_COMPLETION_PROVIDER
diff --git a/gtksourceview/gtksourcecompletioncontext.c b/gtksourceview/gtksourcecompletioncontext.c
index 27e9376e..4c5a7063 100644
--- a/gtksourceview/gtksourcecompletioncontext.c
+++ b/gtksourceview/gtksourcecompletioncontext.c
@@ -31,6 +31,31 @@
 #include "gtksourcecompletionproposal.h"
 #include "gtksourcecompletionprovider.h"
 
+/**
+ * SECTION:completioncontext
+ * @Title: GtkSourceCompletionContext
+ * @Short_description: The context of a completion
+ * @See_also: #GtkSourceCompletion, #GtkSourceCompletionProvider, and
+ *   #GtkSourceCompletionProposal.
+ *
+ * #GtkSourceCompletionContext contains information about an attept to display
+ * completion proposals to the user based on typed text in the #GtkSourceView.
+ *
+ * When typing, #GtkSourceCompletion may use registered
+ * #GtkSourceCompletionProvider to determine if there may be results which
+ * could be displayed. If so, a #GtkSourceCompletionContext is created with
+ * information that is provided to the #GtkSourceCompletionProvider to populate
+ * results which might be useful to the user.
+ *
+ * #GtkSourceCompletionProvider are expected to provide #GListModel with
+ * #GtkSourceCompletionProposal which may be joined together in a list of
+ * results for the user. They are also responsible for how the contents are
+ * displayed using #GtkSourceCompletionCell which allows for some level of
+ * customization.
+ *
+ * Since: 5.0
+ */
+
 struct _GtkSourceCompletionContext
 {
        GObject parent_instance;
@@ -820,6 +845,7 @@ _gtk_source_completion_context_complete_finish (GtkSourceCompletionContext  *sel
 
 /**
  * gtk_source_completion_context_get_busy:
+ * @self: a #GtkSourceCompletionContext
  *
  * Gets the "busy" property. This is set to %TRUE while the completion
  * context is actively fetching proposals from registered
diff --git a/gtksourceview/gtksourcecompletionproposal.c b/gtksourceview/gtksourcecompletionproposal.c
index b66e2f83..9e9b3a35 100644
--- a/gtksourceview/gtksourcecompletionproposal.c
+++ b/gtksourceview/gtksourcecompletionproposal.c
@@ -19,12 +19,26 @@
  * SPDX-License-Identifier: LGPL-2.1-or-later
  */
 
-
-
 #include "config.h"
 
 #include "gtksourcecompletionproposal.h"
 
+/**
+ * SECTION:completionproposal
+ * @Title: GtkSourceCompletionProposal
+ * @Short_description: interface for completion proposals
+ *
+ * This interface is used to denote that an object is capable of being
+ * a completion proposal for #GtkSourceCompletion.
+ *
+ * Currently, no method or functions are required but additional methods
+ * may be added in the future. Proposals created by
+ * #GtkSourceCompletionProvider can use %G_IMPLEMENT_INTERFACE to
+ * implement this with %NULL for the interface init function.
+ *
+ * Since: 5.0
+ */
+
 G_DEFINE_INTERFACE (GtkSourceCompletionProposal, gtk_source_completion_proposal, G_TYPE_OBJECT)
 
 static void
diff --git a/gtksourceview/gtksourcecompletionprovider.c b/gtksourceview/gtksourcecompletionprovider.c
index 35a5cd6e..193ab26c 100644
--- a/gtksourceview/gtksourcecompletionprovider.c
+++ b/gtksourceview/gtksourcecompletionprovider.c
@@ -19,8 +19,6 @@
  * SPDX-License-Identifier: LGPL-2.1-or-later
  */
 
-
-
 #include "config.h"
 
 #include "gtksourcecompletioncontext.h"
@@ -28,6 +26,20 @@
 #include "gtksourcecompletionproposal.h"
 #include "gtksourcecompletionprovider.h"
 
+/**
+ * SECTION:completionprovider
+ * @title: GtkSourceCompletionProvider
+ * @short_description: Completion provider interface
+ *
+ * You must implement this interface to provide proposals to #GtkSourceCompletion
+ *
+ * In most cases, implementations of this interface will want to use
+ * #GtkSourceCompletion.populate_async to asynchronously populate the results
+ * to avoid blocking the main loop.
+ *
+ * Since: 5.0
+ */
+
 G_DEFINE_INTERFACE (GtkSourceCompletionProvider, gtk_source_completion_provider, G_TYPE_OBJECT)
 
 static void
@@ -112,6 +124,19 @@ gtk_source_completion_provider_default_init (GtkSourceCompletionProviderInterfac
        iface->activate = fallback_activate;
 }
 
+/**
+ * gtk_source_completion_provider_get_title:
+ * @self: a #GtkSourceCompletionProvider
+ *
+ * Gets the title of the completion provider, if any.
+ *
+ * Currently, titles are not displayed in the completion results, but may be
+ * at some point in the future when non-%NULL.
+ *
+ * Returns: (transfer full) (nullable): a title for the provider or %NULL
+ *
+ * Since: 5.0
+ */
 char *
 gtk_source_completion_provider_get_title (GtkSourceCompletionProvider *self)
 {
@@ -123,6 +148,21 @@ gtk_source_completion_provider_get_title (GtkSourceCompletionProvider *self)
        return NULL;
 }
 
+/**
+ * gtk_source_completion_provider_get_priority:
+ * @self: a #GtkSourceCompletionProvider
+ * @context: a #GtkSourceCompletionContext
+ *
+ * This function should return the priority of @self in @context.
+ *
+ * The priority is used to sort groups of completion proposals by
+ * provider so that higher priority providers results are shown
+ * above lower priority providers.
+ *
+ * Lower value indicates higher priority.
+ *
+ * Since: 5.0
+ */
 int
 gtk_source_completion_provider_get_priority (GtkSourceCompletionProvider *self,
                                              GtkSourceCompletionContext  *context)
@@ -136,6 +176,20 @@ gtk_source_completion_provider_get_priority (GtkSourceCompletionProvider *self,
        return 0;
 }
 
+/**
+ * gtk_source_completion_provider_is_trigger:
+ * @self: a #GtkSourceCompletionProvider
+ * @iter: a #GtkTextIter
+ * @ch: a #gunichar of the character inserted
+ *
+ * This function is used to determine of a character inserted into the text
+ * editor should cause a new completion request to be triggered.
+ *
+ * An example would be period '.' which might indicate that the user wants
+ * to complete method or field names of an object.
+ *
+ * Since: 5.0
+ */
 gboolean
 gtk_source_completion_provider_is_trigger (GtkSourceCompletionProvider *self,
                                            const GtkTextIter           *iter,
@@ -150,6 +204,23 @@ gtk_source_completion_provider_is_trigger (GtkSourceCompletionProvider *self,
        return FALSE;
 }
 
+/**
+ * gtk_source_completion_provider_key_activates:
+ * @self: a #GtkSourceCompletionProvider
+ * @context: a #GtkSourceCompletionContext
+ * @proposal: a #GtkSourceCompletionProposal
+ * @keyval: a keyval such as %GDK_KEY_period
+ * @state: a #GdkModifierType or 0
+ *
+ * This function is used to determine if a key typed by the user should
+ * activate @proposal (resulting in committing the text to the editor).
+ *
+ * This is useful when using languages where convention may lead to less
+ * typing by the user. One example may be the use of "." or "-" to expand
+ * a field access in the C programming language.
+ *
+ * Since: 5.0
+ */
 gboolean
 gtk_source_completion_provider_key_activates (GtkSourceCompletionProvider *self,
                                               GtkSourceCompletionContext  *context,
@@ -167,6 +238,24 @@ gtk_source_completion_provider_key_activates (GtkSourceCompletionProvider *self,
        return FALSE;
 }
 
+/**
+ * gtk_source_completion_provider_populate_async:
+ * @self: a #GtkSourceCompletionProvider
+ * @context: a #GtkSourceCompletionContext
+ * @cancellable: (nullable): a #GCancellable or %NULL
+ * @callback: a callback to execute upon completion
+ * @user_data: closure data for @callback
+ *
+ * Asynchronously requests that the provider populates the completion
+ * results for @context.
+ *
+ * For providers that would like to populate a #GListModel while those
+ * results are displayed to the user,
+ * gtk_source_completion_context_set_proposals_for_provider() may be used
+ * to reduce latency until the user sees results.
+ *
+ * Since: 5.0
+ */
 void
 gtk_source_completion_provider_populate_async (GtkSourceCompletionProvider *self,
                                                GtkSourceCompletionContext  *context,
@@ -203,6 +292,21 @@ gtk_source_completion_provider_populate_finish (GtkSourceCompletionProvider  *se
        return GTK_SOURCE_COMPLETION_PROVIDER_GET_IFACE (self)->populate_finish (self, result, error);
 }
 
+/**
+ * gtk_source_completion_provider_refilter:
+ * @self: a #GtkSourceCompletionProvider
+ * @context: a #GtkSourceCompletionContext
+ * @model: a #GListModel
+ *
+ * This function can be used to filter results previously provided to
+ * the #GtkSourceCompletionContext by the #GtkSourceCompletionProvider.
+ *
+ * This can happen as the user types additionl text onto the word so
+ * that previously matched items may be removed from the list instead of
+ * generating new #GListModel of results.
+ *
+ * Since: 5.0
+ */
 void
 gtk_source_completion_provider_refilter (GtkSourceCompletionProvider *self,
                                          GtkSourceCompletionContext  *context,
@@ -216,6 +320,23 @@ gtk_source_completion_provider_refilter (GtkSourceCompletionProvider *self,
                GTK_SOURCE_COMPLETION_PROVIDER_GET_IFACE (self)->refilter (self, context, model);
 }
 
+/**
+ * gtk_source_completion_provider_display:
+ * @self: a #GtkSourceCompletionProvider
+ * @context: a #GtkSourceCompletionContext
+ * @proposal: a #GtkSourceCompletionProposal
+ * @cell: a #GtkSourceCompletionCell
+ *
+ * This function requests that the #GtkSourceCompletionProvider prepares
+ * @cell to display the contents of @proposal. Based on @cells column
+ * type, you may want to display different information.
+ *
+ * This allows for columns of information among completion proposals
+ * resulting in better alignment of similar content (icons, return types,
+ * method names, and parameter lists).
+ *
+ * Since: 5.0
+ */
 void
 gtk_source_completion_provider_display (GtkSourceCompletionProvider *self,
                                         GtkSourceCompletionContext  *context,
@@ -231,6 +352,22 @@ gtk_source_completion_provider_display (GtkSourceCompletionProvider *self,
                GTK_SOURCE_COMPLETION_PROVIDER_GET_IFACE (self)->display (self, context, proposal, cell);
 }
 
+/**
+ * gtk_source_completion_provider_activate:
+ * @self: a #GtkSourceCompletionProvider
+ * @context: a #GtkSourceCompletionContext
+ * @proposal: a #GtkSourceCompletionProposal
+ *
+ * This function requests @proposal to be activated by the
+ * #GtkSourceCompletionProvider.
+ *
+ * What the provider does to activate the proposal is specific to that
+ * provider. Many providers may choose to insert a #GtkSourceSnippet with
+ * edit points the user may cycle through.
+ *
+ * See also: #GtkSourceSnippet, #GtkSourceSnippetChunk, gtk_source_view_push_snippet()
+ * Since: 5.0
+ */
 void
 gtk_source_completion_provider_activate (GtkSourceCompletionProvider *self,
                                          GtkSourceCompletionContext  *context,
[Date Prev][Date Next]   [Thread Prev][Thread Next]   [Thread Index] [Date Index] [Author Index]