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.

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.

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-return

Call the command after exporting variables and return to parent prefix. If there is no parent prefix, then call transient--do-exit.

Function: transient--do-call

Call the command after exporting variables and stay transient.

The following pre-commands are suitable for sub-prefixes. Only the first should ever explicitly be set as the value of the transient slot.

Function: transient--do-recurse

Call the transient prefix command, preparing for return to active transient.

Whether we actually return to the parent transient is ultimately under the control of each invoked suffix. The difference between this pre-command and transient--do-replace is that it changes the value of the transient-suffix slot to transient--do-return.

If there is no parent transient, then only call this command and skip the second step.

Function: transient--do-replace

Call the transient prefix command, replacing the active transient.

Unless transient--do-recurse is explicitly used, this pre-command is automatically used for suffixes that are prefixes themselves, i.e., for sub-prefixes.

Function: transient--do-suspend

Suspend the active transient, saving the transient stack.

This is used by the command transient-suspend and optionally also by “external events” such as handle-switch-frame. Such bindings should be added to transient-predicate-map.

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.

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]