locator — Locator dialog and functionality

Implements widget, which appears, when you press Ctrl+L and it’s functionality

Contains definition of AbstractCommand and AbstractCompleter interfaces

exception enki.core.locator.InvalidCmdArgs

Bases: exceptions.UserWarning

class enki.core.locator.AbstractCommand

Bases: QObject

Base class for Locator commands.

Inherit it to create own commands. Than add your command with Locator.addCommandClass()

Public attributes:

  • command - Command text (first word), i.e. f for Open and s for Save
  • signature - Command signature. Shown in the Help. Example: [f] PATH [LINE]
  • description - Command description. Shown in the Help. Example: Open file. Globs are supported
  • isDefaultCommand - If True, command is executed if no other command matches. Must be True for only 1 command. Currently it is FuzzyOpen
  • isDefaultPathCommand - If True, command is executed if no other command matches and text looks like a path. Must be True for only 1 command. Currently it is Open
  • isDefaultNumericCommand - If True, command is executed if no other command matches and text looks like a number. Must be True for only 1 command. Currently it is GotoLine
command = NotImplemented
signature = NotImplemented
description = NotImplemented
isDefaultCommand = False
isDefaultPathCommand = False
isDefaultNumericCommand = False

Signal is emitted by the command after completer has changed.

Locator will call completer() method again after this signal. Use this signal only for commands for which completer is changed dynamically, i.e. FuzzyOpen loads project files asyncronously. For the majority of commands it is enough to implement completer() method.


Terminate the command if necessary.

Default implementation does nothing

static isAvailable()

Check if command is available now.

i.e. SaveAs command is not available, if no files are opened


Set command arguments.

This method can be called multiple times while the user edits the command. Raise InvalidCmdArgs if the arguments are invalid.


:enki.core.locator.AbstractCompleter instance for partially typed command.

Return None, if your command doesn’t have completer, or if completion is not available now.


This method is called after completer.load() method has finished. Completer instance created in completer() is passed as parameter.

The command can use loaded data from the completer now.


Item in the completion tree has been clicked.

Update internal state. After this call Locator will execute the command if isReadyToExecute or update line edit text with lineEditText() otherwise.


Get text for Locator dialog line edit.

This method is called after internal command state has been updated with onItemClicked()


Check if command is ready to execute.

It is ready, when it is complete (contains all mandatory arguments) and arguments are valid


Execute the command

class enki.core.locator.AbstractCompleter

Completer for Locator.


  • inline completion
  • command(s) description
  • status and any other information from command
  • list of possible completions

If mustBeLoaded class attribute is True, load() method will be called in a thread.

mustBeLoaded = False

Load necessary data in a thread. This method must often check stopEvent threading.Event and return if it is set.


Row count for TreeView


Column count for tree view. Default is 1

text(row, column)

Text for TreeView item

icon(row, column)

Icon for TreeView item. Default is None

isSelectable(row, column)

Check if item is selectable with arrow keys


Inline completion.

Shown after cursor. Appedned to the typed text, if Tab is pressed


Row had been clicked by mouse. Get inline completion, which will be inserted after cursor


Item, which shall be auto-selected when completer is applied.

If not None, shall be (row, column)

Default implementation returns None

class enki.core.locator.StatusCompleter(text)

Bases: enki.core.locator.AbstractCompleter

AbstractCompleter implementation, which shows status message


AbstractCompleter method implementation

Return count of available commands

text(row, column)

AbstractCompleter method implementation

Return command description


Split text onto words Return list of (word, endIndex)

class enki.core.locator.Locator

Bases: QObject


Add new command to the locator. Shall be called by plugins, which provide locator commands


Remove command from the locator. Shall be called by plugins when terminating it