GtkSourceCompletion

GtkSourceCompletion — Main Completion Object

Synopsis

#include <gtksourceview/gtksource.h>

                    GtkSourceCompletion;
#define             GTK_SOURCE_COMPLETION_ERROR
enum                GtkSourceCompletionError;

gboolean            gtk_source_completion_add_provider  (GtkSourceCompletion *completion,
                                                         GtkSourceCompletionProvider *provider,
                                                         GError **error);
gboolean            gtk_source_completion_remove_provider
                                                        (GtkSourceCompletion *completion,
                                                         GtkSourceCompletionProvider *provider,
                                                         GError **error);
GList *             gtk_source_completion_get_providers (GtkSourceCompletion *completion);
gboolean            gtk_source_completion_show          (GtkSourceCompletion *completion,
                                                         GList *providers,
                                                         GtkSourceCompletionContext *context);
void                gtk_source_completion_hide          (GtkSourceCompletion *completion);
GtkSourceCompletionInfo * gtk_source_completion_get_info_window
                                                        (GtkSourceCompletion *completion);
GtkSourceView *     gtk_source_completion_get_view      (GtkSourceCompletion *completion);
GtkSourceCompletionContext * gtk_source_completion_create_context
                                                        (GtkSourceCompletion *completion,
                                                         GtkTextIter *position);
void                gtk_source_completion_move_window   (GtkSourceCompletion *completion,
                                                         GtkTextIter *iter);
void                gtk_source_completion_block_interactive
                                                        (GtkSourceCompletion *completion);
void                gtk_source_completion_unblock_interactive
                                                        (GtkSourceCompletion *completion);

Object Hierarchy

  GObject
   +----GtkSourceCompletion

Properties

  "accelerators"             guint                 : Read / Write / Construct
  "auto-complete-delay"      guint                 : Read / Write / Construct
  "proposal-page-size"       guint                 : Read / Write / Construct
  "provider-page-size"       guint                 : Read / Write / Construct
  "remember-info-visibility" gboolean              : Read / Write / Construct
  "select-on-show"           gboolean              : Read / Write / Construct
  "show-headers"             gboolean              : Read / Write / Construct
  "show-icons"               gboolean              : Read / Write / Construct
  "view"                     GtkSourceView*        : Read / Write / Construct Only

Signals

  "activate-proposal"                              : Action
  "hide"                                           : Action
  "move-cursor"                                    : Action
  "move-page"                                      : Action
  "populate-context"                               : Action
  "show"                                           : Action

Description

The completion system helps the user when he writes some text, such as words, command names, functions, and suchlike. Proposals can be shown, to complete the text the user is writing. Each proposal can contain an additional piece of information, that is displayed when the "Details" button is active.

Proposals are created via a GtkSourceCompletionProvider. There can be for example a provider to complete words (see GtkSourceCompletionWords), another provider for the completion of function's names, etc. To add a provider, call gtk_source_completion_add_provider().

When the completion is activated, a GtkSourceCompletionContext object is created. The providers are asked whether they match the context, with gtk_source_completion_provider_match(). If a provider doesn't match the context, it will not be visible in the completion window. On the other hand, if the provider matches the context, its proposals will be displayed.

When several providers match, they are all shown in the completion window, but one can switch between providers: see the "move-page" signal. It is also possible to activate the first proposals with key bindings, see the "accelerators" property.

The GtkSourceCompletionProposal interface represents a proposal. The GtkSourceCompletionItem class is a simple implementation of this interface.

If a proposal contains extra information (see gtk_source_completion_provider_get_info_widget()), it will be displayed in a GtkSourceCompletionInfo window, which appears when the "Details" button is clicked.

A GtkSourceCompletionInfo window can also be used to display calltips. When no proposals are available, it can be useful to display extra information like a function's prototype (number of parameters, types of parameters, etc).

Each GtkSourceView object is associated with a GtkSourceCompletion instance. This instance can be obtained with gtk_source_view_get_completion(). The GtkSourceView class contains also the "show-completion" signal.

A same GtkSourceCompletionProvider object can be used for several GtkSourceCompletion.

Details

GtkSourceCompletion

typedef struct _GtkSourceCompletion GtkSourceCompletion;

GTK_SOURCE_COMPLETION_ERROR

#define GTK_SOURCE_COMPLETION_ERROR		(gtk_source_completion_error_quark ())

Error domain for the completion. Errors in this domain will be from the GtkSourceCompletionError enumeration. See GError for more information on error domains.

enum GtkSourceCompletionError

typedef enum {
	GTK_SOURCE_COMPLETION_ERROR_ALREADY_BOUND = 0,
	GTK_SOURCE_COMPLETION_ERROR_NOT_BOUND
} GtkSourceCompletionError;

An error code used with GTK_SOURCE_COMPLETION_ERROR in a GError returned from a completion-related function.

GTK_SOURCE_COMPLETION_ERROR_ALREADY_BOUND

 The GtkSourceCompletionProvider is already bound to the GtkSourceCompletion object.

GTK_SOURCE_COMPLETION_ERROR_NOT_BOUND

 The GtkSourceCompletionProvider is not bound to the GtkSourceCompletion object.

gtk_source_completion_add_provider ()

gboolean            gtk_source_completion_add_provider  (GtkSourceCompletion *completion,
                                                         GtkSourceCompletionProvider *provider,
                                                         GError **error);

Add a new GtkSourceCompletionProvider to the completion object. This will add a reference provider, so make sure to unref your own copy when you no longer need it.

completion :

 a GtkSourceCompletion.

provider :

 a GtkSourceCompletionProvider.

error :

 a GError. [allow-none]

Returns :

 TRUE if provider was successfully added, otherwise if error is provided, it will be set with the error and FALSE is returned.

gtk_source_completion_remove_provider ()

gboolean            gtk_source_completion_remove_provider
                                                        (GtkSourceCompletion *completion,
                                                         GtkSourceCompletionProvider *provider,
                                                         GError **error);

Remove provider from the completion.

completion :

 a GtkSourceCompletion.

provider :

 a GtkSourceCompletionProvider.

error :

 a GError. [allow-none]

Returns :

 TRUE if provider was successfully removed, otherwise if error is provided, it will be set with the error and FALSE is returned.

gtk_source_completion_get_providers ()

GList *             gtk_source_completion_get_providers (GtkSourceCompletion *completion);

Get list of providers registered on completion. The returned list is owned by the completion and should not be freed.

completion :

 a GtkSourceCompletion.

Returns :

 list of GtkSourceCompletionProvider. [element-type GtkSource.CompletionProvider][transfer none]

gtk_source_completion_show ()

gboolean            gtk_source_completion_show          (GtkSourceCompletion *completion,
                                                         GList *providers,
                                                         GtkSourceCompletionContext *context);

Starts a new completion with the specified GtkSourceCompletionContext and a list of potential candidate providers for completion.

It can be convenient for showing a completion on-the-fly, without the need to add or remove providers to the GtkSourceCompletion.

Another solution is to add providers with gtk_source_completion_add_provider(), and implement gtk_source_completion_provider_match() for each provider.

completion :

 a GtkSourceCompletion.

providers :

 a list of GtkSourceCompletionProvider, or NULL. [element-type GtkSource.CompletionProvider][allow-none]

context :

 The GtkSourceCompletionContext with which to start the completion. [transfer floating]

Returns :

 TRUE if it was possible to the show completion window.

gtk_source_completion_hide ()

void                gtk_source_completion_hide          (GtkSourceCompletion *completion);

Hides the completion if it is active (visible).

completion :

 a GtkSourceCompletion.

gtk_source_completion_get_info_window ()

GtkSourceCompletionInfo * gtk_source_completion_get_info_window
                                                        (GtkSourceCompletion *completion);

The info widget is the window where the completion displays optional extra information of the proposal.

completion :

 a GtkSourceCompletion.

Returns :

 The GtkSourceCompletionInfo window associated with completion. [transfer none]

gtk_source_completion_get_view ()

GtkSourceView *     gtk_source_completion_get_view      (GtkSourceCompletion *completion);

The GtkSourceView associated with completion.

completion :

 a GtkSourceCompletion.

Returns :

 The GtkSourceView associated with completion. [type GtkSource.View][transfer none]

gtk_source_completion_create_context ()

GtkSourceCompletionContext * gtk_source_completion_create_context
                                                        (GtkSourceCompletion *completion,
                                                         GtkTextIter *position);

Create a new GtkSourceCompletionContext for completion. The position where the completion occurs can be specified by position. If position is NULL, the current cursor position will be used.

completion :

 a GtkSourceCompletion.

position :

 a GtkTextIter, or NULL. [allow-none]

Returns :

 a new GtkSourceCompletionContext. The reference being returned is a 'floating' reference, so if you invoke gtk_source_completion_show() with this context you don't need to unref it. [transfer floating]

gtk_source_completion_move_window ()

void                gtk_source_completion_move_window   (GtkSourceCompletion *completion,
                                                         GtkTextIter *iter);

Warning

gtk_source_completion_move_window has been deprecated since version 3.8 and should not be used in newly-written code. Use gtk_source_completion_provider_get_start_iter() instead.

Move the completion window to a specific iter.

completion :

 a GtkSourceCompletion.

iter :

 a GtkTextIter.

gtk_source_completion_block_interactive ()

void                gtk_source_completion_block_interactive
                                                        (GtkSourceCompletion *completion);

Block interactive completion. This can be used to disable interactive completion when inserting or deleting text from the buffer associated with the completion. Use gtk_source_completion_unblock_interactive() to enable interactive completion again.

completion :

 a GtkSourceCompletion.

gtk_source_completion_unblock_interactive ()

void                gtk_source_completion_unblock_interactive
                                                        (GtkSourceCompletion *completion);

Unblock interactive completion. This can be used after using gtk_source_completion_block_interactive() to enable interactive completion again.

completion :

 a GtkSourceCompletion.

Property Details

The "accelerators" property

  "accelerators"             guint                 : Read / Write / Construct

Number of keyboard accelerators to show for the first proposals. For example, to activate the first proposal, the user can press Alt+1.

Allowed values: <= 10

Default value: 5

The "auto-complete-delay" property

  "auto-complete-delay"      guint                 : Read / Write / Construct

Determines the popup delay (in milliseconds) at which the completion will be shown for interactive completion.

Default value: 250

The "proposal-page-size" property

  "proposal-page-size"       guint                 : Read / Write / Construct

The scroll page size of the proposals in the completion window. In other words, when PageDown or PageUp is pressed, the selected proposal becomes the one which is located one page size backward or forward.

See also the "move-cursor" signal.

Allowed values: >= 1

Default value: 5

The "provider-page-size" property

  "provider-page-size"       guint                 : Read / Write / Construct

The scroll page size of the provider pages in the completion window.

See the "move-page" signal.

Allowed values: >= 1

Default value: 5

The "remember-info-visibility" property

  "remember-info-visibility" gboolean              : Read / Write / Construct

Determines whether the visibility of the info window should be saved when the completion is hidden, and restored when the completion is shown again.

Default value: FALSE

The "select-on-show" property

  "select-on-show"           gboolean              : Read / Write / Construct

Determines whether the first proposal should be selected when the completion is first shown.

Default value: TRUE

The "show-headers" property

  "show-headers"             gboolean              : Read / Write / Construct

Determines whether provider headers should be shown in the proposal list. It can be useful to disable when there is only one provider.

Default value: TRUE

The "show-icons" property

  "show-icons"               gboolean              : Read / Write / Construct

Determines whether provider and proposal icons should be shown in the completion popup.

Default value: TRUE

The "view" property

  "view"                     GtkSourceView*        : Read / Write / Construct Only

The GtkSourceView bound to the completion object.

Signal Details

The "activate-proposal" signal

void                user_function                      (GtkSourceCompletion *completion,
                                                        gpointer             user_data)       : Action

The "activate-proposal" signal is a keybinding signal which gets emitted when the user initiates a proposal activation.

Applications should not connect to it, but may emit it with g_signal_emit_by_name() if they need to control the proposal activation programmatically.

completion :

 The GtkSourceCompletion who emits the signal

user_data :

 user data set when the signal handler was connected.

The "hide" signal

void                user_function                      (GtkSourceCompletion *completion,
                                                        gpointer             user_data)       : Action

Emitted when the completion window is hidden. The default handler will actually hide the window.

completion :

 The GtkSourceCompletion who emits the signal

user_data :

 user data set when the signal handler was connected.

The "move-cursor" signal

void                user_function                      (GtkSourceCompletion *completion,
                                                        GtkScrollStep        step,
                                                        gint                 num,
                                                        gpointer             user_data)       : Action

The "move-cursor" signal is a keybinding signal which gets emitted when the user initiates a cursor movement.

The Up, Down, PageUp, PageDown, Home and End keys are bound to the normal behavior expected by those keys.

When step is equal to GTK_SCROLL_PAGES, the page size is defined by the "proposal-page-size" property. It is used for the PageDown and PageUp keys.

Applications should not connect to it, but may emit it with g_signal_emit_by_name() if they need to control the cursor programmatically.

completion :

 The GtkSourceCompletion who emits the signal

step :

 The GtkScrollStep by which to move the cursor

num :

 The amount of steps to move the cursor

user_data :

 user data set when the signal handler was connected.

The "move-page" signal

void                user_function                      (GtkSourceCompletion *completion,
                                                        GtkScrollStep        step,
                                                        gint                 num,
                                                        gpointer             user_data)       : Action

The "move-page" signal is a keybinding signal which gets emitted when the user initiates a page movement (i.e. switches between provider pages).

Control+Left is for going to the previous provider. Control+Right is for going to the next provider. Control+Home is for displaying all the providers. Control+End is for going to the last provider.

When step is equal to GTK_SCROLL_PAGES, the page size is defined by the "provider-page-size" property.

Applications should not connect to it, but may emit it with g_signal_emit_by_name() if they need to control the page selection programmatically.

completion :

 The GtkSourceCompletion who emits the signal

step :

 The GtkScrollStep by which to move the page

num :

 The amount of steps to move the page

user_data :

 user data set when the signal handler was connected.

The "populate-context" signal

void                user_function                      (GtkSourceCompletion        *completion,
                                                        GtkSourceCompletionContext *context,
                                                        gpointer                    user_data)       : Action

Emitted just before starting to populate the completion with providers. You can use this signal to add additional attributes in the context.

completion :

 The GtkSourceCompletion who emits the signal

context :

 The GtkSourceCompletionContext for the current completion

user_data :

 user data set when the signal handler was connected.

The "show" signal

void                user_function                      (GtkSourceCompletion *completion,
                                                        gpointer             user_data)       : Action

Emitted when the completion window is shown. The default handler will actually show the window.

completion :

 The GtkSourceCompletion who emits the signal

user_data :

 user data set when the signal handler was connected.
Generated by GTK-Doc V1.19.1