Next: Suffix Specifications, Up: Binding Suffix and Infix Commands [Contents][Index]
The suffix and infix commands of a transient are organized in groups. The grouping controls how the descriptions of the suffixes are outlined visually but also makes it possible to set certain properties for a set of suffixes.
Several group classes exist, some of which organize suffixes in subgroups. In most cases the class does not have to be specified explicitly, but see Group Classes.
Groups are specified in the call to transient-define-prefix
, using
vectors. Because groups are represented using vectors, we cannot use
square brackets to indicate an optional element and instead use curly
brackets to do the latter.
Group specifications then have this form:
[{LEVEL} {DESCRIPTION} {KEYWORD VALUE}... ELEMENT...]
The LEVEL is optional and defaults to 4. See Enabling and Disabling Suffixes.
The DESCRIPTION is optional. If present, it is used as the heading of the group.
The KEYWORD-VALUE pairs are optional. Each keyword has to be a
keyword symbol, either :class
or a keyword argument supported by the
constructor of that class.
:description
, is equivalent to specifying
DESCRIPTION at the very beginning of the vector. The recommendation
is to use :description
if some other keyword is also used, for
consistency, or DESCRIPTION otherwise, because it looks better.
:level
is equivalent to LEVEL.
:if...
keywords. These
keywords control whether the group is available in a certain
situation.
For example, one group of the magit-rebase
transient uses :if
magit-rebase-in-progress-p
, which contains the suffixes that are
useful while rebase is already in progress; and another that uses
:if-not magit-rebase-in-progress-p
, which contains the suffixes that
initiate a rebase.
These predicates can also be used on individual suffixes and are only documented once, see Predicate Slots.
:hide
, if non-nil
, is a predicate that controls
whether the group is hidden by default. The key bindings for
suffixes of a hidden group should all use the same prefix key.
Pressing that prefix key should temporarily show the group and its
suffixes, which assumes that a predicate like this is used:
(lambda () (eq (car transient--redisplay-key) ?\C-c)) ; the prefix key shared by all bindings
:setup-children
, if non-nil
, is a function that takes
one argument, a potentially list of children, and must return a list
of children or an empty list. This can either be used to somehow
transform the group’s children that were defined the normal way, or
to dynamically create the children from scratch.
The returned children must have the same form as stored in the
prefix’s transient--layout
property, but it is often more convenient
to use the same form as understood by transient-define-prefix
,
described below. If you use the latter approach, you can use the
transient-parse-suffixes
and transient-parse-suffix
functions to
transform them from the convenient to the expected form. Depending
on the used group class, transient-parse-suffixes
’s SUFFIXES must be
a list of group vectors (for transient-columns
) or a list of suffix
lists (for all other group classes).
If you explicitly specify children and then transform them using
:setup-children
, then the class of the group is determined as usual,
based on explicitly specified children.
If you do not explicitly specify children and thus rely solely on
:setup-children
, then you must specify the class using :class
.
For backward compatibility, if you fail to do so, transient-column
is used and a warning is displayed. This warning will eventually
be replaced with an error.
(transient-define-prefix my-finder-by-keyword () "Select a keyword and list matching packages." ;; The real `finder-by-keyword' is more convenient ;; of course, but that is not the point here. [:class transient-columns :setup-children (lambda (_) (transient-parse-suffixes 'my-finder-by-keyword (let ((char (1- ?A))) (mapcar ; a list ... (lambda (partition) (vconcat ; of group vectors ... (mapcar (lambda (elt) (let ((keyword (symbol-name (car elt)))) ; ... where each suffix is a list (list (format "%c" (cl-incf char)) keyword (lambda () (interactive) (finder-list-matches keyword))))) partition))) (seq-partition finder-known-keywords 7)))))])
:pad-keys
argument controls whether keys of all suffixes
contained in a group are right padded, effectively aligning the
descriptions.
The ELEMENTs are either all subgroups, or all suffixes and strings. (At least currently no group type exists that would allow mixing subgroups with commands at the same level, though in principle there is nothing that prevents that.)
If the ELEMENTs are not subgroups, then they can be a mixture of lists, which specify commands, and strings. Strings are inserted verbatim into the buffer. The empty string can be used to insert gaps between suffixes, which is particularly useful if the suffixes are outlined as a table.
Inside group specifications, including inside contained suffix
specifications, nothing has to be quoted and quoting anyway is
invalid. The value following a keyword, can be explicitly unquoted
using ,
. This feature is experimental and should be avoided.
The form of suffix specifications is documented in the next node.
Next: Suffix Specifications, Up: Binding Suffix and Infix Commands [Contents][Index]