Skip to content

Commit

Permalink
Update using.md
Browse files Browse the repository at this point in the history
  • Loading branch information
ManuelSchneid3r authored Dec 22, 2023
1 parent ab65893 commit a07bfb5
Showing 1 changed file with 28 additions and 27 deletions.
55 changes: 28 additions & 27 deletions src/_pages/using.md
Original file line number Diff line number Diff line change
Expand Up @@ -12,54 +12,55 @@ As you would expect from a launcher, the main use case is to type a query into a
### Plugins

Albert is an plugin based keyboard launcher.
A plugin is a physical module that can be loaded/unloaded at runtime.
This may be a native plugin (which is a shared library) or a plugin provided by a plugin provider.
E.g. a Python plugin (which is a Python module) provided by the Python plugin provider.
Due to this recursive nature nested plugins are available only if their provider is loaded.
A plugin is a module that can be loaded/unloaded while the launcher is running.
They could be native plugins (shared libraries) or provided by plugin providers, such as Python modules from the Python plugin provider.
Nested plugins are only accessible if their provider is loaded.

Users can enable/disable or load/unload plugins in the `Plugins` tab in the settings or using the plugin items provided by the builtin plugin query handler.
Enabled plugins will be loaded automatically on start.
If a plugin provides a graphical interface for configuration you will find it in the `Plugins` tab.
Use the plugin items to get there quickly.
Some plugins also provide more elaborate usage information there.
Users can enable/disable or load/unload plugins via the Plugins tab in settings or using the built-in plugin query handler.
Enabled plugins load automatically at launch.
Plugins with graphical interfaces for configuration can be accessed via the Plugins tab.
Some plugins offer more detailed usage information there.

### Extensions

Each plugin can provide multiple [extensions](https://albertlauncher.github.io/reference/classalbert_1_1Extension.html).
An extension may be a frontend, a plugin provider, a fallback provider or any of the query handling extensions.
While frontends and plugin providers are advanced topics, fallback providers, global- and triggered query handlers are central to the purpose of the app.
The next section sheds some light on them.
Each plugin can provide various [extensions](https://albertlauncher.github.io/reference/classalbert_1_1Extension.html), like frontends, plugin providers, fallback providers or query handlers.
While frontends and plugin providers are advanced topics, fallback providers, global- and triggered query handlers are central to the app's functionality.

### Queries

The core of the app is the query engine which parses user input and decides the mode of a query.

If the query is prefixed by a trigger defined by any of the trigger query handlers the coresponding handler will handle the query exclusively.
This allows the handler to display matches as soon as they are available.
This is a remarkable technical advantage of triggered queries, but there are other reasons why plugins may provide only triggered handlers as well, such as:
Ecology, economy, runtime, amount of output, order more important than content, etc.
If there is no such trigger the query will be delegated to all global query handlers (multithreaded).

Queries without triggers are delegated to all global query handlers (multithreaded).
As soon as the handlers finished the matches are sorted by match score and usage history and displayed.
In any case a separate set of results, the fallbacks, is provided by fallback handlers.

Additionally, fallback handlers offer a separate set of results: the fallback items.

## The user interface

Note that the frontend is modular and there are currently two official frontends.
The 'Widgets Box Model' is implemented using Qt Widgets Toolkit which allows resource saving, low latency user interfaces, but has limitations considering customization.
The 'QML Box Model' is build using QML (Qt Modeling Language, OpenGL rendering) which provides rich customization features, but suffers glitches on some systems.
Both of them have its strengths and weaknesses so there has not been a clear favorite yet.
Since both frontends have the same design concept this guide should be suitalble for both of them (Please report a bug if not).
There are currently two official interfaces:
The 'Widgets Box Modeland the 'QML Box Model'.
The former uses the Qt Widgets Toolkit, prioritizing resource efficiency and low-latency UIs but has limitations considering customization.
The latter, built on QML, provides rich customization features, but suffers glitches on some systems.
Since both interfacea have the same design concept this guide applies to both of them (Please report a bug if not).

### The input line

Besides the obvious purpose the input line provides the input hint and contains the settings button.
Besides its primary function, the input line provides an input hint and contains the settings button.

The input hint is displayed after the text you entered.
On empty triggered queries the input hint displays the synopsis of the query handler if it provides any.
Else it displays the text of the input action of the selected item if it provides any.
In all other cases the input hint remains empty.

The settings button is hidden in the top right corner of the input line.
It shows up if it is hovered by the mouse cursor or the current query is busy processing.
The input hint, displayed after the entered text, varies based on the context.
For empty triggered queries, it shows the query handler's synopsis, if available, otherwhise it shows the input action text of the selected item, if available, or is empty.

The settings button, located in the top right corner, appears on hover or when the current query is processing.

### The results list

Expand All @@ -84,12 +85,12 @@ Any vertical navigation is handled by the results list or the actions list if ac

### Input history

The content of the input line is stored in the input history when the window hides.
This input history can be used to quickly search former queries.
If the input has been changed manually the content serves as pattern for substring matching of the history entries.
The content entered into the input line is stored in the input history when the window is hidden.
This input history can be used to search former queries.
When the input has been manually altered, it functions as a pattern for substring matching within the history entries.
Note that the empty pattern matches any former query (browsing instead of search).
When the results list is hidden or the first item is selected <kbd>⬆</kbd> searches the input history.
When holding <kbd>Shift</kbd> this condition is not required and <kbd>⬇</kbd> can be used too for bidirectional browsing
When holding <kbd>Shift</kbd> this condition is not required and <kbd>⬇</kbd> can be used too for bidirectional iteration.

### Key map

Expand Down

0 comments on commit a07bfb5

Please sign in to comment.