Previous: , Up: Defining New Commands   [Contents][Index]


4.5 Transient State

Invoking a transient prefix command "activates" the respective transient, i.e. it puts a transient keymap into effect, which binds the transient’s infix and suffix commands.

The default behavior while a transient is active is as follows:

But these are just the defaults. Whether a certain command deactivates or "exits" the transient is configurable. There is more than one way in which a command can be "transient" or "non-transient"; the exact behavior is implemented by calling a so-called "pre-command" function. Whether non-suffix commands are allowed to be called is configurable per transient.

The available pre-command functions are documented below. They are called by transient--pre-command, a function on pre-command-hook and the value that they return determines whether the transient is exited. To do so the value of one of the constants transient--exit or transient--stay is used (that way we don’t have to remember if t means "exit" or "stay").

Additionally these functions may change the value of this-command (which explains why they have to be called using pre-command-hook), call transient-export, transient--stack-zap or transient--stack-push; and set the values of transient--exitp, transient--helpp or transient--editp.

4.5.1 Pre-commands for Infixes

The default for infixes is transient--do-stay. This is also the only function that makes sense for infixes.

Function: transient--do-stay

Call the command without exporting variables and stay transient.

4.5.2 Pre-commands for Suffixes

The default for suffixes is transient--do-exit.

Function: transient--do-exit

Call the command after exporting variables and exit the transient.

Function: transient--do-call

Call the command after exporting variables and stay transient.

Function: transient--do-replace

Call the transient prefix command, replacing the active transient.

This is used for suffixes that are prefixes themselves, i.e. for sub-prefixes.

4.5.3 Pre-commands for Non-Suffixes

The default for non-suffixes, i.e commands that are bound in other keymaps beside the transient keymap, is transient--do-warn. Silently ignoring the user-error is also an option, though probably not a good one.

If you want to let the user invoke non-suffix commands, then use transient--do-stay as the value of the prefix’s transient-non-suffix slot.

Function: transient--do-warn

Call transient-undefined and stay transient.

Function: transient--do-noop

Call transient-noop and stay transient.

4.5.4 Special Pre-Commands

Function: transient--do-quit-one

If active, quit help or edit mode, else exit the active transient.

This is used when the user pressed C-g.

Function: transient--do-quit-all

Exit all transients without saving the transient stack.

This is used when the user pressed C-q.

Function: transient--do-suspend

Suspend the active transient, saving the transient stack.

This is used when the user pressed C-z.


Previous: , Up: Defining New Commands   [Contents][Index]