# 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

## 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

# Create a container for all our results. You may consider implementing
# Gio.ListModel directly if performance is of high concern.

item = MyProposal('my proposal')

# Complete the task so that the completion engine calls us back at
# do_populate_finish() to complete the operation.

"""

The goal here is to copmlete the operation by returning our Gio.ListModel
back to the caller.
"""

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.