Top |
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 |
void | activate-proposal | Action |
void | hide | Action |
void | move-cursor | Action |
void | move-page | Action |
void | populate-context | Action |
void | show | Action |
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.
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> |
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.
gboolean gtk_source_completion_remove_provider (GtkSourceCompletion *completion
,GtkSourceCompletionProvider *provider
,GError **error
);
Remove provider
from the completion.
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.
list of GtkSourceCompletionProvider.
[element-type GtkSource.CompletionProvider][transfer none]
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.
completion |
||
providers |
a list of GtkSourceCompletionProvider, or |
[element-type GtkSource.CompletionProvider][nullable] |
context |
The GtkSourceCompletionContext with which to start the completion. |
[transfer floating] |
void
gtk_source_completion_hide (GtkSourceCompletion *completion
);
Hides the completion if it is active (visible).
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.
GtkSourceView *
gtk_source_completion_get_view (GtkSourceCompletion *completion
);
The GtkSourceView associated with completion
, or NULL
if the view has been
destroyed.
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.
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]
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.
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.
#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.
An error code used with GTK_SOURCE_COMPLETION_ERROR
in a GError returned
from a completion-related function.
The GtkSourceCompletionProvider is already bound to the GtkSourceCompletion object. |
||
The GtkSourceCompletionProvider is not bound to the GtkSourceCompletion object. |
“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
“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
“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 selectedproposal 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
“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
“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
“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
“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
“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
“view”
property“view” GtkSourceView *
The GtkSourceView bound to the completion object.
Owner: GtkSourceCompletion
Flags: Read / Write / Construct Only
“activate-proposal”
signalvoid 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.
completion |
The GtkSourceCompletion who emits the signal |
|
user_data |
user data set when the signal handler was connected. |
Flags: Action
“hide”
signalvoid user_function (GtkSourceCompletion *completion, gpointer user_data)
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. |
Flags: Action
“move-cursor”
signalvoid 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 thenormal 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. |
Flags: Action
“move-page”
signalvoid 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+Leftis for going to the previous provider.
Control+Rightis for going to the next provider.
Control+Homeis for displaying all the providers.
Control+Endis 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. |
Flags: Action
“populate-context”
signalvoid 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.
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
“show”
signalvoid user_function (GtkSourceCompletion *completion, gpointer user_data)
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. |
Flags: Action