The keyboard-driven-input Macro is used to create filtered lists that update as the user types. It also allows navigating the lists, and invoking macros using list items, with the keyboard.

It consists of an edit-text widget wrapped in keyboard widgets. There are keyboard widgets to listen for ((input-accept)), ((input-accept-variant)), and ((input-cancel)) keyboard shortcuts, but there is no default behaviour in response to these events; macros must be written to suit the use-case. There is also no default visualisation of the filtered options list.

Types of keyboard input handled by the keyboard-driven-input macro:

Non-configurable:

The following keyboard events invoke macros defined alongside keyboard-driven-input in $:/core/macros/keyboard-driven-input.

All of the above actions generate or modify data which keyboard-driven-input keeps in tiddlers specified using the macro's parameters. The data can then be accessed not only by the macros invoked by keyboard shortcuts, but also outside of these, e.g. a macro to display the filtered list(s).

Configurable through parameters:

The following keyboard events invoke macros whose names are specified in parameters to keyboard-driven-input. The intended purpose is suggested by the parameter name, but there are no default macros defined within $:/core/macros/keyboard-driven-input.

keyboard-driven-input can be seen in action as part of various core features in TiddlyWiki, e.g.: the search feature, the tag-picker Macro, and dropdown interfaces in the Editor toolbar such as Insert link.

Minimal ingredients for a demonstration

Keeping in mind that the keyboard-driven-input macro does not, by itself, display list results, or do anything with a selected option, a minimal demonstration of the keyboard-driven-input macro requires:

1. a tiddler, containing a filter whose results depend on the user's text input, to generate the options from which the user can select
2. several parameters:
   • a filter to return the title of the tiddler where the filter described in step 1 can be found, and
   • tiddler titles to use for storing state information in response to input events. These tiddlers do not need to exist already. If they do exist, the keyboard-driven-input macro will change their contents.

The search filter(s)

By default, keyboard-driven-input will look for filters in the first-search-filter and second-search-filter fields of a tiddler (whose title is specified by a parameter discussed below).

This filter can refer to a variable called userInput, which shows the contents of the edit-text widget, as stored in a state tiddler (discussed below), at the time of the latest Up or Down event.

Note: If this filter is to be referred to in a context outside the keyboard-driven-input macro (such as in a popup showing the filtered options), the variable userInput has to be defined in those contexts as well (by reading it from a state tiddler).

Minimal parameters

Demonstration setup

I have created a tiddler called kdi-demo-configtid and put the following filter into its first-search-filter field:

[!is[system]search:title<userInput>sort[]].

This filters for non-system tiddlers whose titles contain the text the user has typed.

To use the above filter with keyboard-driven-input, the value of the parameter configTiddlerFilter should be a filter that returns kdi-demo-configtid.

I can select tiddler, storeTitle, and selectionStateTitle fairly arbitrarily (just making sure not to use titles of tiddlers that I do not want changed).

This demonstration can now be invoked with the following macro call:

<$macrocall $name=keyboard-driven-input 
        tiddler="kdi-demo-tiddler"
        storeTitle="kdi-demo-storeTitle" 
        selectionStateTitle="kdi-demo-selectionStateTitle" 
        configTiddlerFilter="[[kdi-demo-configtid]]" 
 />

Demo

Try typing in here:

Observe the changes in the various state tiddlers in the below table. Use Up and Down keys to navigate among filter results. If nothing changes, try a shorter input to widen the filter. If the input has zero length, the list will contain all non-system tiddlers.

The keyboard-driven-input macro has many parameters available, including all the attributes of the enclosed edit-text widget, which make it very flexible in how it is used and how results can be displayed and interacted with.

See also: Customising search results and $:/core/ui/DefaultSearchResultList