You can see the last GtkSourceCompletion API
There are five important objects (for the developer) to manage completion:
Optionally there are some predefined objects you can use:
GscCompletion is the main completion object who manages all providers, triggers, events and the popup widget (itself). This object do not complete anything, you must register a GscProvider to which the manager will delegate the completion work when a GscTrigger raise a completion event.
The usual workflow can be sum up as below :
Multiple triggers can be registered for a unique instance of GscCompletion and multiple providers can be registered for one or various triggers. The completion will use the appropriate one depending on the received event. For example, you may implement providers for autocompletion, snippets or symbols but only show snippets when the user-request trigger call for completion and previously written words when autocompletion-trigger call for completion.
A provider must to provide data when it is called. The provider only provide data, does not decide when, the completion controls that with the asociated triggers.
GtkSourceCompletion supports to change the default functionality when you selects a proposal. By example, if we want to display the last open documents, we could follow those steps :
This example creates two providers and two triggers. Register the document words provider for autocompletion trigger and user request trigger but the test provider is only registered for autocompletion trigger. Internally the manager ref the objects and, if you don't need the providers nor triggers, you can unref it and the manager will unref too when it or the view will be detroyed then they will be destroyed too.
/*Creating the providers*/ GscDocumentwordsProvider *prov = gsc_documentwords_provider_new(GTK_TEXT_VIEW(view)); GscProviderTest *prov_test = gsc_provider_test_new(GTK_TEXT_VIEW(view)); /*Creating the completion manager*/ GscCompletion *comp = gsc_completion_new(GTK_TEXT_VIEW(view)); /*Creating the triggers*/ GscTriggerCustomkey *ur_trigger = gsc_trigger_customkey_new(comp,"User Request Trigger","<Control>Return"); GscTriggerAutowords *ac_trigger = gsc_trigger_autowords_new(comp); /*First register the triggers*/ gsc_completion_register_trigger(comp,GSC_TRIGGER(ur_trigger)); gsc_completion_register_trigger(comp,GSC_TRIGGER(ac_trigger)); /*Register the providers for the triggers (prov_test only for autocompletion trigger)*/ gsc_completion_register_provider(comp,GSC_PROVIDER(prov),GSC_TRIGGER (ac_trigger)); gsc_completion_register_provider(comp,GSC_PROVIDER(prov_test),GSC_TRIGGER (ac_trigger)); gsc_completion_register_provider(comp,GSC_PROVIDER(prov),GSC_TRIGGER (ur_trigger)); /*We activate the completion mechanism*/ gsc_completion_activate(comp); /* The manager saves references internally. We unref the objects and the manager will free it when you destroy the manager or the view. */ g_object_unref(prov); g_object_unref(prov_test); g_object_unref(ur_trigger); g_object_unref(ac_trigger);
GscInfo is the object used to show calltips, help, etc. Currently there is not a mechanism like GscCompletion to use triggers and providers. You must to use the GscInfo by hand, when you want.
GscInfo supports to change the default widget (a GtkLabel) by a custom widget like a text view, a box with a browser and buttons etc. What you want. GscInfo manages its position under/upper the GtkTextView cursor and can adjust its height and width if you want (and if the custom widget returns the correct width).
A simple example can be:
GscInfo *info = gsc_info_new(); /*Adjust height and width with a max value*/ gsc_info_set_adjust_height(info,TRUE,100000); gsc_info_set_adjust_width(info,TRUE,100000); ..... /*Sets the calltip*/ gsc_info_set_markup(info, "My calltip"); /*Position to cursor*/ gsc_info_move_to_cursor(info,GTK_TEXT_VIEW(view)); /*Show the calltip*/ gtk_widget_show(GTK_WIDGET(info));
There are two ways of changing the default info widget.
GscCompletion has an special function to filter the current proposals. Think in python class completion. You can create a python-provider and, when the user writes a dot, you show all class members. Then the user writes some chars like .set_ then you can filter the current proposals to show only proposals starting by set_ without reload the class members again.
The function is:
gsc_completion_filter_proposals (GscCompletion *self, GscCompletionFilterFunc func, gpointer user_data)
GscCompletion will call to func for all proposals and the function will return TRUE if the proposal must to be shown or FALSE if not.
You will need to create some Gsc objects like providers, triggers or proposals. In the Gsc source package you can find the tools folder where I have created some python scrits to auto generate this objects skeletons easily.