General Autocompletion

Autocompletion is the functionality of the QScintilla editor to show suggestions for words from an autocompletion source while you are typing characters into the editor. The suggestions are shown in an autocompletion window.

Basic options

In this paragraph, we’ll go through some basic options that you need to configure to use autocompletions.

 

Autocompletion source

First of all, you need to tell your editor from which source it should take the autocompletions. This is done with the following function:

self.__editor.setAutocompletionSource(source)

These are the source parameter options:

  • QsciScintilla.AcsNone      No source, autocompletions are disabled. This is the default.
  • QsciScintilla.AcsAll       Use all available sources, this means APIs and the document.
  • QsciScintilla.AcsDocument  Use the editor’s document as the source.
  • QsciScintilla.AcsAPIs      Use the predefined APIs as the source.

To query the source, call the autoCompletionSource() function.

When you use the editor’s document as a source, it means that all of the words in the editor are used as a source for autocompletion. When the user types new words into the editor, the autocompletion engine uses them too.

You can also provide a list with strings as source for the autocompletion engine. A simple Python-list is not sufficient. Instead, you will need to do the following things:

  • – Create an instance from the QsciAPIs class.
  • – Plug this object into your lexer.
  • – Add strings to the QsciAPIs-object.

We will discuss more details later.

 

Autocompletion threshold

This option sets how many characters have to be typed before the autocompletion window is shown:

self.__editor.setAutoCompletionThreshold(nr_of_chars)

To query, call the autoCompletionThreshold() function.

 

Autocompletion case sensitivity

To set the case sensitivity, use the function:

self.__editor.setAutoCompletionCaseSensitivity(case_sensitivity)
  • False    Autocompletion is case IN-sensitive. This means that the letters in the word you are typing do not have to match the case of the words in the autocompletion source.
  • True     Autocompletion is case sensitive. If you type a word that is in the autocompletion sources but does not match the case of the autocompletion source word, the word will not appear in the suggestion window.

 

Word replacement

This option selects whether the characters to the right of the cursor (until a separator is reached) are overwritten when selecting an autocompletion:

self.__editor.setAutoCompletionReplaceWord(replace)
  • False    The characters to the right of the cursor are not overwritten.

     
  • True     The characters to the right of the cursor are overwritten.

 

Single option behaviour

This option selects what happens when there is only one autocompletion option available in the autocompletion window.

self.__editor.setAutoCompletionUseSingle(single_option)
  • QsciScintilla.AcusNever      The autocompletion window is displayed if there is a single entry in the autocompletion list.
  • QsciScintilla.AcusExplicit   The single entry is automatically used only if the user manually executes a manual autocompletion function, like autoCompleteFromDocument(), … , but not when a user is typing.
  • QsciScintilla.AcusAlways     The single entry in the autocompletion list is always entered automatically.

 

Word separators

Unknown functionality.

 

QsciAPIs – a source for autocompletion

As you’ve discovered in the previous paragraph, you’ve got two possible sources for the autocompletion engine: the editor’s document itself and a string-list in the QsciAPIs-object – and you can activate or deactive each source independently.

This paragraph is all about the QsciAPIs-object. You will learn how to make and fill this object with strings.

Do you remember this figure from the introduction?

 
As shown in the figure, you should first create the QsciAPIs-object and plug it into your lexer.

1. Make a QsciAPIs-object

Making the object is pretty simple:

self.__api = QsciAPIs(self.__lexer)

The moment you create the object, you plug it into the lexer immediately. That’s why you pass it your lexer as a parameter.

 

2. Fill the QsciAPIs-object

This is how you add strings to the QsciAPIs-object:

autocompletions = [
    "test_autocompletion",
    "add(int arg_1, float arg_2) Add two integers together",
    "subtract(int arg_1, test arg_2)",
    "subtract(float arg_1, float arg_2)",
    "subtract(test arg_1, test arg_2)",
    "divide(float div_1, float div_2)",
    "some_func(arg_3)"
]

for ac in autocompletions:
    self.__api.add(ac)

 

3. Prepare the QsciAPIs-object

Last but not least, you should “prepare” the QsciAPIs-object:

self.__api.prepare()

 

Removing info from the QsciAPIs-object

If you want to remove an entry from the QsciAPIs-object, use the following function:

self.__api.remove(entry)

The parameter entry should be a string you’ve previously added to the object.

Please note that it is not possible to add or remove entries once you’ve “prepared” the QsciAPIs-object. You ‘ll have to create a new QsciAPIs-instance and add the information again!

 

Manual autocompletion trigger

Sometimes the user wants to display the autocompletion window with a manual trigger. This is achieved with the following functions (you can perhaps link these functions to a key-press, mouse click, …):

  • self.__editor.autoCompleteFromAll():      An autocompletion list is displayed with all available sources (APIs and the document) used.
     
  • self.__editor.autoCompleteFromAPIs():     An autocompletion list is displayed with with only the QsciAPIs-object used as source.
     
  • self.__editor.autoCompleteFromDocument(): An autocompletion list is displayed with with only the document used as source.

 

Autocompletion look and feel

Colors

Unlike Call Tip windows (see next page), you can’t independently change the background or foreground color of an Autocompletion window. In fact, Autocompletion windows inherit them from the parent widget. From the figure below, you can see that the Autocompletion window inherits from the QFrame parent (QFrame is the editor’s parent):

Adding images

First register an image with the editor:

img = QPixmap("marker_image.png")
self.__editor.registerImage(1, img)

To show the image in the autocomplete window, add a reference to it in the list of strings:

autocompletions = [
    "test_autocompletion",
    "autocompletion_with_image?1", # "?1" references to image nr. 1
    "another_autocompletion"
]

The reference is nothing more than a question mark ‘?’ followed by the number of the registered image. The reference should be at the end of the string entry (or in between the name and opening parenthesis when it’s a function).