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 Gio.ListModel of Ide.CompletionProposal. Plugins have an opportunity to refine results as the user continues to provide input.

Note

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