## GtkSourceCompletion

GtkSourceCompletion — Main Completion Object

## Functions

gboolean | gtk_source_completion_add_provider ()
gboolean | gtk_source_completion_remove_provider ()
GList * | gtk_source_completion_get_providers ()
gboolean | gtk_source_completion_start ()
void | gtk_source_completion_hide ()
GtkSourceCompletionInfo * | gtk_source_completion_get_info_window ()
GtkSourceView * | gtk_source_completion_get_view ()
GtkSourceCompletionContext * | gtk_source_completion_create_context ()
void | gtk_source_completion_block_interactive ()
void | gtk_source_completion_unblock_interactive ()

## Properties

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

## Signals

void | activate-proposal | Action
void | hide | Action
void | move-cursor | Action
void | move-page | Action
void | populate-context | Action
void | show | Action

## Types and Values

| GtkSourceCompletion
#define | GTK_SOURCE_COMPLETION_ERROR
enum | GtkSourceCompletionError

## Object Hierarchy

        GEnum
        ╰── GtkSourceCompletionError
        GObject
        ╰── GtkSourceCompletion

## Implemented Interfaces

GtkSourceCompletion implements GtkBuildable.

## Includes

    #include <gtksourceview/gtksource.h>

## Description

The completion system helps the user when he/she 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 (for example documentation), that is displayed when the "Details" button is clicked.

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 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 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's.

### GtkSourceCompletion as GtkBuildable

The GtkSourceCompletion implementation of the GtkBuildable interface exposes the info window object (see `gtk_source_completion_get_info_window()`) with the internal-child "info_window".

An example of a UI definition fragment with GtkSourceCompletion:

    1
    2
    3
    4
    5
    6
    7
    8

    <object class="GtkSourceCompletion">
      <property name="select_on_show">False</property>
      <child internal-child="info_window">
        <object class="GtkSourceCompletionInfo">
          <property name="border_width">6</property>
        </object>
      </child>
    </object>

## Functions

### 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.

#### Parameters

completion | a GtkSourceCompletion. |
provider | a GtkSourceCompletionProvider. |
error | a GError. |

#### 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.

#### Parameters

completion | a GtkSourceCompletion. |
provider | a GtkSourceCompletionProvider. |
error | a GError. |

#### 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.

#### Parameters

completion | a GtkSourceCompletion. |

#### Returns

list of GtkSourceCompletionProvider.

[element-type GtkSource.CompletionProvider][transfer none]

### gtk_source_completion_start ()

    gboolean
    gtk_source_completion_start (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.

#### Parameters

completion | a GtkSourceCompletion. |
providers | a list of GtkSourceCompletionProvider, or `NULL`. | [element-type GtkSource.CompletionProvider][nullable]
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).

#### Parameters

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.

#### Parameters

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` , or `NULL` if the view has been destroyed.

#### Parameters

completion | a GtkSourceCompletion. |

#### Returns

The GtkSourceView associated with `completion` , or `NULL`.

[nullable][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.

#### Parameters

completion | a GtkSourceCompletion. |
position | a GtkTextIter, or `NULL`. | [nullable]

#### Returns

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

[transfer floating]

### 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.

This function may be called multiple times. It will continue to block interactive completion until `gtk_source_completion_unblock_interactive()` has been called the same number of times.

#### Parameters

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.

#### Parameters

completion | a GtkSourceCompletion. |

## Types and Values

### 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

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

#### Members

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. |

## Property Details

### The `“accelerators”` property

      “accelerators”             guint

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

Alt+1.

Owner: GtkSourceCompletion

Flags: Read / Write / Construct

Allowed values: <= 10

Default value: 5

### The `“auto-complete-delay”` property

      “auto-complete-delay”      guint

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

Owner: GtkSourceCompletion

Flags: Read / Write / Construct

Default value: 250

### The `“proposal-page-size”` property

      “proposal-page-size”       guint

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.

Owner: GtkSourceCompletion

Flags: Read / Write / Construct

Allowed values: >= 1

Default value: 5

### The `“provider-page-size”` property

      “provider-page-size”       guint

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

See the “move-page” signal.

Owner: GtkSourceCompletion

Flags: Read / Write / Construct

Allowed values: >= 1

Default value: 5

### The `“remember-info-visibility”` property

      “remember-info-visibility” gboolean

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

Owner: GtkSourceCompletion

Flags: Read / Write / Construct

Default value: FALSE

### The `“select-on-show”` property

      “select-on-show”           gboolean

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

Owner: GtkSourceCompletion

Flags: Read / Write / Construct

Default value: TRUE

### The `“show-headers”` property

      “show-headers”             gboolean

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

Owner: GtkSourceCompletion

Flags: Read / Write / Construct

Default value: TRUE

### The `“show-icons”` property

      “show-icons”               gboolean

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

Owner: GtkSourceCompletion

Flags: Read / Write / Construct

Default value: TRUE

### The `“view”` property

      “view”                     GtkSourceView *

The GtkSourceView bound to the completion object.

Owner: GtkSourceCompletion

Flags: Read / Write / Construct Only

## Signal Details

### The `“activate-proposal”` signal

    void
    user_function (GtkSourceCompletion *completion,
                   gpointer             user_data)

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.

#### Parameters

completion | The GtkSourceCompletion who emits the signal |
user_data | user data set when the signal handler was connected. |

Flags: Action

### The `“hide”` signal

    void
    user_function (GtkSourceCompletion *completion,
                   gpointer             user_data)

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

#### Parameters

completion | The GtkSourceCompletion who emits the signal |
user_data | user data set when the signal handler was connected. |

Flags: Action

### The `“move-cursor”` signal

    void
    user_function (GtkSourceCompletion *completion,
                   GtkScrollStep        step,
                   int                  num,
                   gpointer             user_data)

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.

#### Parameters

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. |

Flags: Action

### The `“move-page”` signal

    void
    user_function (GtkSourceCompletion *completion,
                   GtkScrollStep        step,
                   int                  num,
                   gpointer             user_data)

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.

#### Parameters

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. |

Flags: Action

### The `“populate-context”` signal

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

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

#### Parameters

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. |

Flags: Action

### The `“show”` signal

    void
    user_function (GtkSourceCompletion *completion,
                   gpointer             user_data)

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

#### Parameters

completion | The GtkSourceCompletion who emits the signal |
user_data | user data set when the signal handler was connected. |

Flags: Action