GtkSourceView 3 Reference Manual: GtkSourceCompletionContext

## GtkSourceCompletionContext GtkSourceCompletionContext — The context of a completion |

## Functions

void | gtk_source_completion_context_add_proposals ()
void | gtk_source_completion_context_get_iter ()
GtkSourceCompletionActivation | gtk_source_completion_context_get_activation ()

## Properties

GtkSourceCompletionActivation | activation | Read / Write / Construct
GtkSourceCompletion * | completion | Read / Write / Construct Only
GtkTextIter * | iter | Read / Write

## Signals

void | cancelled | Action

## Types and Values

enum | GtkSourceCompletionActivation
| GtkSourceCompletionContext

## Object Hierarchy

        GObject
        ╰── GInitiallyUnowned
            ╰── GtkSourceCompletionContext

## Includes

    #include <gtksourceview/gtksource.h>

## Description

Initially, the completion window is hidden. For a completion to occur, it has to be activated. The different possible activations are listed in GtkSourceCompletionActivation. When an activation occurs, a GtkSourceCompletionContext object is created, and the eligible providers are asked to add proposals with `gtk_source_completion_context_add_proposals()`.

If no proposals are added, the completion window remains hidden, and the context is destroyed.

On the other hand, if proposals are added, the completion window becomes visible, and the user can choose a proposal. If the user is not happy with the shown proposals, he or she can insert or delete characters, to modify the completion context and therefore hoping to see the proposal he or she wants. This means that when an insertion or deletion occurs in the GtkTextBuffer when the completion window is visible, the eligible providers are again asked to add proposals. The “activation” remains the same in this case.

When the completion window is hidden, the interactive completion is triggered only on insertion in the buffer, not on deletion. Once the completion window is visible, then on each insertion or deletion, there is a new population and the providers are asked to add proposals. If there are no more proposals, the completion window disappears. So if you want to keep the completion window visible, but there are no proposals, you can insert a dummy proposal named "No proposals". For example, the user types progressively the name of a function, and some proposals appear. The user types a bad character and there are no proposals anymore. What the user wants is to delete the last character, and see the previous proposals. If the completion window disappears, the previous proposals will not reappear on the character deletion.

A GtkTextIter is associated with the context, this is where the completion takes place. With this GtkTextIter, you can get the associated GtkTextBuffer with `gtk_text_iter_get_buffer()`.

## Functions

### gtk_source_completion_context_add_proposals ()

    void
    gtk_source_completion_context_add_proposals
                                   (GtkSourceCompletionContext *context,
                                    GtkSourceCompletionProvider *provider,
                                    GList *proposals,
                                    gboolean finished);

Providers can use this function to add proposals to the completion. They can do so asynchronously by means of the `finished` argument. Providers must ensure that they always call this function with `finished` set to `TRUE` once each population (even if no proposals need to be added). Population occurs when the `gtk_source_completion_provider_populate()` function is called.

#### Parameters

context | a GtkSourceCompletionContext. |
provider | a GtkSourceCompletionProvider. | [type GtkSource.CompletionProvider]
proposals | The list of proposals to add. | [allow-none][element-type GtkSource.CompletionProposal]
finished | Whether the provider is finished adding proposals. |

### gtk_source_completion_context_get_iter ()

    void
    gtk_source_completion_context_get_iter
                                   (GtkSourceCompletionContext *context,
                                    GtkTextIter *iter);

Get the iter at which the completion was invoked. Providers can use this to determine how and if to match proposals.

#### Parameters

context | a GtkSourceCompletionContext. |
iter | a GtkTextIter. | [out]

### gtk_source_completion_context_get_activation ()

    GtkSourceCompletionActivation
    gtk_source_completion_context_get_activation
                                   (GtkSourceCompletionContext *context);

Get the context activation.

#### Parameters

context | a GtkSourceCompletionContext. |

#### Returns

The context activation.

## Types and Values

### enum GtkSourceCompletionActivation

#### Members

GTK_SOURCE_COMPLETION_ACTIVATION_NONE | None. |
GTK_SOURCE_COMPLETION_ACTIVATION_INTERACTIVE | Interactive activation. By default, it occurs on each insertion in the GtkTextBuffer. This can be blocked temporarily with `gtk_source_completion_block_interactive()`. |
GTK_SOURCE_COMPLETION_ACTIVATION_USER_REQUESTED | User requested activation. By default, it occurs when the user presses Control+space. |

### GtkSourceCompletionContext

    typedef struct _GtkSourceCompletionContext GtkSourceCompletionContext;

## Property Details

### The `“activation”` property

      “activation”               GtkSourceCompletionActivation

The completion activation

Flags: Read / Write / Construct

Default value: GTK_SOURCE_COMPLETION_ACTIVATION_USER_REQUESTED

### The `“completion”` property

      “completion”               GtkSourceCompletion *

The GtkSourceCompletion associated with the context.

Flags: Read / Write / Construct Only

### The `“iter”` property

      “iter”                     GtkTextIter *

The GtkTextIter at which the completion is invoked.

Flags: Read / Write

## Signal Details

### The `“cancelled”` signal

    void
    user_function (GtkSourceCompletionContext *arg0,
                   gpointer                    user_data)

Emitted when the current population of proposals has been cancelled. Providers adding proposals asynchronously should connect to this signal to know when to cancel running proposal queries.

#### Parameters

user_data | user data set when the signal handler was connected. |

Flags: Action