Commando

The main concept of Commando is having a centralized search field that can be used (extended) by addons. For example Fast Open will be using the Commando to search between project files. But likewise we'll also want to use it to quickly navigate betwee sections (as an alternative to the section list).

Other use cases include:

  • Package Management
  • Contextual File Actions (rename, move, copy, etc)
  • Toolbox navigation

Terminology

  • Commando The core Commando library
  • Search Field The textfield that is used to submit search queries.
  • Search Handler (Handler) -- extendable The Search Handler refers to the module that is actually responsible for generating results based on the user input. As well as processing those results when they are selected.
  • Search Renderer (Renderer) -- extendable The Renderer is a javascript library which will take care of rendering the results as well as communicating input events to the handlers.
  • Result Table The results of the current query as rendered in the user interface.
  • Shortcut Shortcuts are basically favourites that the user can mark while searching. Shortcuts will always be sorted on top in the search results.

User Interface

Commando at its core is just a search field allowing users to search using whatever handlers are registered. A user can switch between handlers by selecting it from a small dropdown selector next to the search field.

The interface will have two display modes, one in which it is integrated into the menubar (See kd-0282, annotation #1_), and one in which it functions as a standalone dialog, much like Fast Open does in Komodo 7.

When the search field is activated from the menu bar (ie. the cursor is placed on the input field) the input should grow (animated) to be approx 1.5x to 2x its regular size in width allowing the result table to float right underneath using the same size as the input.

We'll need to make sure that the buttons to the left of the input (if any) will properly float underneath the input as it expands.

::

+ <!-- HTML: --> -----------------------+ | [I] [search textbox] [P] | |- - - - - - - - - - - - - | | Results.. | +--------------------------+

[I] An icon representing the current handler. This icon is clickable and will show all available handlers in a dropdown list. [P] When a search is in progress an icon will be shown indicating that the search is currently still in progress. When a user hovers their mouse over the results table while a search is in progress all new results will be queued until the user mouses out of the results window. This icon will indicate that state.

Shortcuts UI

Shortcuts will be integrated into the result table and will have an icon indicator to emphasize the fact that these are atypical items.

When hovering over an item in the result table, an "add/remove" (contextual) icon will appear floating to the right of the item that will allow you to manage it.

Shortcuts will always be sorted on top, provided that they match the search query.

::

+----------------------+
| [search textbox]     |
|                      |
| [I] Result 1         |
| Result 2         [A] |   <- Hovered
| Result 3             |

[I] An icon representing the fact that this item is a shortcut. The shortcut name will be shown faded out towards the right of the name. [A] An icon that allows you to add/remove this item as a shortcut.

After clicking on the [A]::

+----------------------+
| [search textbox]     |
|                      |
| [I] Result 1         |
| Result 2         [A] |   <- Depressed
|   [                ] |
| Result 3             |

You may then type the shortcut name in the textbox and press Enter to save it. Shortcut names must be unique across the application; existing shortcuts with the same name will be removed before the new one is added after confirming with the user::

+----------------------+
| [search textbox]     |
|                      |
| [I] Result 1         |
| Result 2         [A] |
|   [ foo            ] |
| [Overwrite] [Cancel] |
| Result 3             |

Behaviour

Searching

When initiating a search, an icon to the right of the search field will indicate that a search is in progress. At this point commando will pass the search criteria to the appropriate handlers. The handler then start searching asynchronously.

Results

Once the handler has (some or all) results ready it passes them back to the renderer. The renderer will then evaluate the searchId to ensure that this is still the active search.

When a user is currently already reviewing results by hovering their mouse over the results table the renderer will queue the new results to be added when the mouse leaves the results table. The "in progress" icon will change to an icon representing the fact that new items are queued.

When a user is actively browsing through results with his keyboard the new results will be inserted as normal at their relative (ordered) positions, and the users scrolling position will be programmatically maintained.

Sorting

The renderer will be entirely in charge of sorting the results. Whenever a user picks a result from the result table the renderer will record a "hit" on the resultId and use this to sort the most popular items on top. Should there be shortcuts amongst the results these will always be sorted on top regardless of the number of hits they have. The handler is however able to imply sorting by giving a "priority" to an entry.

Stopping

Once a user chooses a result, Commando will tell the active Handlers to abort the active search. The user may also press Escape at any time to abort the search.

Implementations

Much of Fast Open will be ported to separate handlers for Commando. It will no longer be an addon in and on itself.

We will aim to implement the following handlers for 9.0:

  • Project files
  • Open file(s)
  • History [#priority]_
  • Symbols [#priority]_
  • Bookmarks [#priority]_
  • Snippets [#priority]_
  • Commands [#priority]_
  • Macro's [#priority]_
  • Everything (all of the above)

.. [#priority] Lower priority - can potentially wait till a later version