Providing Completion Proposals¶
Builder has a robust completion engine that allows for efficent access to results.
Plugins should implement the
Ide.CompletionProvider interface to provide a
Plugins have an opportunity to refine results as the user continues to provide input.
You can learn more about the implementation at https://blogs.gnome.org/chergert/2018/06/09/a-new-completion-engine-for-builder/
Example Completion Provider¶
# my_plugin.py import gi from gi.repository import GObject from gi.repository import Gio from gi.repository import Ide class MyCompletionProvider(GLib.Object, Ide.CompletionProvider): def do_populate_async(self, context, cancellable, callback, data): """ @context: an Ide.CompletionContext containing state for the completion request @cancellable: a Gio.Cancellable that can be used to cancel the request @callback: a callback to execute after proposals are generated @data: closure data (unnecessary for us since PyGObject handles it) """ # Create a task for our async operation task = Ide.Task.new(self, cancellable, callback) # Create a container for all our results. You may consider implementing # Gio.ListModel directly if performance is of high concern. task.proposals = Gio.ListStore(type(Ide.CompletionProposal)) item = MyProposal('my proposal') task.proposals.append(item) # Complete the task so that the completion engine calls us back at # do_populate_finish() to complete the operation. task.return_boolean(True) def do_populate_finish(self, task): """ @task: the task we created in do_populate_async() The goal here is to copmlete the operation by returning our Gio.ListModel back to the caller. """ if task.propagate_boolean(): return task.proposals def do_display_proposal(self, row, context, typed_text, proposal): """ We need to update the state of @row using the info from our proposal. This is called as the user moves through the result set. @row: the Ide.CompletionListBoxRow to display @context: the Ide.CompletionContext @typed_text: what the user typed @proposal: the proposal to display using @row """ row.set_icon_name() row.set_left('Left hand side') row.set_right('Right hand side') row.set_center(proposal.title) # You might find fuzzy highlighting useful for creating Pango markup markup = Ide.Completion.fuzzy_highlight(proposal.title, typed_text) # If you have Pango markup, you can use set_center_markup() row.set_center_markup(markup) def do_activate_proposal(self, context, proposal, key): """ @proposal: the proposal to be activated @key: the Gdk.EventKey representing what the user pressed to activate the row you may want to use this to alter what is inserted (such as converting . to -> in a C/C++ language provider). This is where we do the work to insert the proposal. You may want to check out the snippet engine to use snippets instead, as some of the providers do which auto-complete parameters. """ buffer = context.get_buffer() # Start a "user action" so that all the changes are coalesced into a # single undo action. buffer.begin_user_action() # Delete the typed text if any has_selection, begin, end = context.get_bounds() if has_selection: buffer.delete(begin, end) # Now insert our proposal buffer.insert(begin, proposal.title, len(proposal.title)) # Complete the user action buffer.begin_end_action() def do_refilter(self, context, proposals): """ If you can refilter the results based on updated typed text, this is where you would adjust @proposals to do that. @proposals is the Gio.ListModel returned from do_populate_finish(). """ typed_text = context.get_word() # filter results... return True class MyProposal(GObject.Object, Ide.CompletionProposal): def __init__(self, title): super().__init__() self.title = title
There are a number of additional things you can implement in your provider. See the IdeCompletionProvider implementation for a description of the interface.
Examples from Builder¶
- Includes completion provider for header includes in C/C++ files
- Jedi completion provider for Python completions
- Ctags completion provider for lightning-fast ctags completion
- Clang completion provider for a fast, caching, completion provider based on libclang
- Vala completion provider for completions in the Vala language