Prefix Slots

Value and Scope

• default-value The default value of the prefix. Use the keyword argument :value (sic) to set this slot in the definition of a prefix.

• init-value A function that is responsible for setting the object’s value. If bound, then this is called with the object as the only argument. Usually this is not bound, in which case the object’s primary transient-init-value method is called instead.

• history-key If multiple prefix commands should share a single value, then this slot has to be set to the same value for all of them. You probably don’t want that.

• remember-value When a suffix command is invoked, which can consume the prefix’s value (which depends on the suffix slot transient and the prefix slots transient-suffix and transient-non-suffix), then the value is automatically pushed to the prefix’s value history.

  This slot allows additionally setting or even saving the value, so that it becomes the initial value when the menu is invoked again.

  Beside nil, the value can be one of these symbols:

  • export Set the value when it is exported. That is the time when the value would ordinarily just be pushed to the history stack.
  • exit Set the value when the menu is exited, except when that is done using a command whose sole purpose is to quit the menu.
  • quit Set the value when the menu is quit, using a command whose sole purpose is to do so.

  The value can also be a list of one or more of these symbols and optionally also the symbol save.

  • save Instead of merely setting the value, save it, so that it will be used in future Emacs sessions. At least one other symbol has to be used together with this.

  The value can also be a (quoted) variable, whose value is a list of symbols as described above. Ideally an option should be used, since not all users will find the automatic saving of the value desirable.

• incompatible A list of lists. Each sub-list specifies a set of mutually exclusive arguments. Enabling one of these arguments causes the others to be disabled. An argument may appear in multiple sub-lists. Arguments must me given in the same form as used in the argument or argument-format slot of the respective suffix objects, usually something like --switch or --option=%s. For options and transient-switches suffixes it is also possible to match against a specific value, as returned by transient-infix-value, for example, --option=one.

• scope For some transients it might be necessary to have a sort of secondary value, called a “scope”. See transient-define-prefix.

Behavior

• transient-suffix, transient-non-suffix and transient-switch-frame play a part when determining whether the currently active transient prefix command remains active/transient when a suffix or arbitrary non-suffix command is invoked. See Transient State.
• refresh-suffixes Normally suffix objects and keymaps are only setup once, when the prefix is invoked. Setting this to t, causes them to be recreated after every command. This is useful when using :if... predicates, and those need to be rerun for some reason. Doing this is somewhat costly, and there is a risk of losing state, so this is disabled by default and still considered experimental.
• environment A function used to establish an environment while initializing, refreshing or redisplaying a transient prefix menu. This is useful to establish a cache, in case multiple suffixes require the same expensive work. The provided function is called with at least one argument, the function for which it establishes the environment. It must funcall that function with no arguments. During initialization the second argument is the prefix object being initialized. This slot is still experimental.

Appearance

• display-action determines how this prefix is displayed, overriding transient-display-buffer-action. It should have the same type.
• mode-line-format is this prefix’s mode line format, overriding transient-mode-line-format. It should have the same type.
• column-widths is only respected inside transient-columns groups and allows aligning columns across separate instances of that. A list of integers.
• variable-pitch controls whether alignment is done pixel-wise to account for use of variable-pitch characters, which is useful, e.g., when using emoji.

Documentation

• show-help, man-page or info-manual can be used to specify the documentation for the prefix and its suffixes. The command transient-help uses the function transient-show-help (which see) to lookup and use these values.
• suffix-description can be used to specify a function which provides fallback descriptions for suffixes that lack a description. This is intended to be temporarily used when implementing of a new prefix command, at which time transient-command-summary-or-name is a useful value.
• description a short string describing the prefix, which users can opt-in to be displayed at the top of the menu buffer. This should be more concise than the first line of the docstring, which is used as a fallback if no description is provided.

Internal

These slots are mostly intended for internal use. They should not be set in calls to transient-define-prefix.

• prototype When a transient prefix command is invoked, then a clone of that object is stored in the global variable transient--prefix and the prototype is stored in the clone’s prototype slot.
• command The command, a symbol. Each transient prefix command consists of a command, which is stored in a symbol’s function slot and an object, which is stored in the transient--prefix property of the same symbol.
• level The level of the prefix commands. The suffix commands whose layer is equal or lower are displayed. See Enabling and Disabling Suffixes.
• value The likely outdated value of the prefix. Instead of accessing this slot directly you should use the function transient-get-value, which is guaranteed to return the up-to-date value.
• history and history-pos are used to keep track of historic values. Unless you implement your own transient-infix-read method you should not have to deal with these slots.
• unwind-suffix is used internally to ensure transient state is properly exited, even in case of an error.