From 291b86e66de3d7b73384f8751050acbdd2187ddb Mon Sep 17 00:00:00 2001 From: Jonas Bernoulli Date: Fri, 15 Nov 2024 21:34:44 +0100 Subject: [PATCH] manual: Document inapt-if* slots --- docs/transient.org | 40 ++++++++++++++++++++++++++---------- docs/transient.texi | 50 +++++++++++++++++++++++++++++++++++---------- lisp/transient.el | 4 ++-- 3 files changed, 70 insertions(+), 24 deletions(-) diff --git a/docs/transient.org b/docs/transient.org index ed88cf9..ef4c23c 100644 --- a/docs/transient.org +++ b/docs/transient.org @@ -981,9 +981,9 @@ constructor of that class. - Likewise ~:level~ is equivalent to {{{var(LEVEL)}}}. -- Other important keywords include the ~:if...~ keywords. These - keywords control whether the group is available in a certain - situation. +- Other important keywords include the ~:if...~ and ~:inapt-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 @@ -1733,10 +1733,10 @@ object should not affect later invocations. The ~:info~ keyword argument replaces the ~:description~ keyword used for other suffix classes. Other keyword arguments that you might want to - set, include ~:face~, predicate keywords (such as ~:if~), and ~:format~. - By default the value of ~:format~ includes ~%k~, which for this class is - replaced with the empty string or spaces, if keys are being padded in - the containing group. + set, include ~:face~, predicate keywords (such as ~:if~ and ~:inapt-if~), + and ~:format~. By default the value of ~:format~ includes ~%k~, which for + this class is replaced with the empty string or spaces, if keys are + being padded in the containing group. Magit defines additional classes, which can serve as examples for the fancy things you can do without modifying Transient. Some of these @@ -2087,10 +2087,14 @@ They are defined here anyway to allow sharing certain methods. ** Predicate Slots -Suffix and group objects share some predicate slots that control -whether a group or suffix should be available depending on some state. -Only one of these slots can be used at the same time. It is undefined -what happens if you use more than one. +Suffix and group objects share two sets of predicate slots that +control whether a group or suffix should be available depending on +some state. Only one slot from each set can be used at the same +time. It is undefined which slot is honored if you use more than +one. + +Predicates from the first group control whether the suffix is present +in the menu at all. - ~if~ Enable if predicate returns non-~nil~. - ~if-not~ Enable if predicate returns ~nil~. @@ -2101,6 +2105,20 @@ what happens if you use more than one. - ~if-derived~ Enable if major-mode derives from value. - ~if-not-derived~ Enable if major-mode does not derive from value. +Predicates from the second group control whether the suffix can be +invoked. The suffix is shown in the menu regardless, but when it +is considered "inapt", then it is grayed out to indicated that it +currently cannot be invoked. + +- ~inapt-if~ Inapt if predicate returns non-~nil~. +- ~inapt-if-not~ Inapt if predicate returns ~nil~. +- ~inapt-if-non-nil~ Inapt if variable's value is non-~nil~. +- ~inapt-if-nil~ Inapt if variable's value is ~nil~. +- ~inapt-if-mode~ Inapt if major-mode matches value. +- ~inapt-if-not-mode~ Inapt if major-mode does not match value. +- ~inapt-if-derived~ Inapt if major-mode derives from value. +- ~inapt-if-not-derived~ Inapt if major-mode does not derive from value. + By default these predicates run when the prefix command is invoked, but this can be changes, using the ~refresh-suffixes~ prefix slot. See [[*Prefix Slots]]. diff --git a/docs/transient.texi b/docs/transient.texi index 5432f7c..8aa4b9e 100644 --- a/docs/transient.texi +++ b/docs/transient.texi @@ -1168,9 +1168,9 @@ consistency, or @var{DESCRIPTION} otherwise, because it looks better. Likewise @code{:level} is equivalent to @var{LEVEL}. @item -Other important keywords include the @code{:if...} keywords. These -keywords control whether the group is available in a certain -situation. +Other important keywords include the @code{:if...} and @code{:inapt-if...} +keywords. These keywords control whether the group is available +in a certain situation. For example, one group of the @code{magit-rebase} transient uses @code{:if magit-rebase-in-progress-p}, which contains the suffixes that are @@ -1980,10 +1980,10 @@ suffix specifications take this form: The @code{:info} keyword argument replaces the @code{:description} keyword used for other suffix classes. Other keyword arguments that you might want to -set, include @code{:face}, predicate keywords (such as @code{:if}), and @code{:format}. -By default the value of @code{:format} includes @code{%k}, which for this class is -replaced with the empty string or spaces, if keys are being padded in -the containing group. +set, include @code{:face}, predicate keywords (such as @code{:if} and @code{:inapt-if}), +and @code{:format}. By default the value of @code{:format} includes @code{%k}, which for +this class is replaced with the empty string or spaces, if keys are +being padded in the containing group. @end itemize Magit defines additional classes, which can serve as examples for the @@ -2390,10 +2390,14 @@ E.g., @code{\\(--\\(topo\\|author-date\\|date\\)-order\\)}. @node Predicate Slots @section Predicate Slots -Suffix and group objects share some predicate slots that control -whether a group or suffix should be available depending on some state. -Only one of these slots can be used at the same time. It is undefined -what happens if you use more than one. +Suffix and group objects share two sets of predicate slots that +control whether a group or suffix should be available depending on +some state. Only one slot from each set can be used at the same +time. It is undefined which slot is honored if you use more than +one. + +Predicates from the first group control whether the suffix is present +in the menu at all. @itemize @item @@ -2414,6 +2418,30 @@ what happens if you use more than one. @code{if-not-derived} Enable if major-mode does not derive from value. @end itemize +Predicates from the second group control whether the suffix can be +invoked. The suffix is shown in the menu regardless, but when it +is considered "inapt", then it is grayed out to indicated that it +currently cannot be invoked. + +@itemize +@item +@code{inapt-if} Inapt if predicate returns non-@code{nil}. +@item +@code{inapt-if-not} Inapt if predicate returns @code{nil}. +@item +@code{inapt-if-non-nil} Inapt if variable's value is non-@code{nil}. +@item +@code{inapt-if-nil} Inapt if variable's value is @code{nil}. +@item +@code{inapt-if-mode} Inapt if major-mode matches value. +@item +@code{inapt-if-not-mode} Inapt if major-mode does not match value. +@item +@code{inapt-if-derived} Inapt if major-mode derives from value. +@item +@code{inapt-if-not-derived} Inapt if major-mode does not derive from value. +@end itemize + By default these predicates run when the prefix command is invoked, but this can be changes, using the @code{refresh-suffixes} prefix slot. See @ref{Prefix Slots}. diff --git a/lisp/transient.el b/lisp/transient.el index 6d0ff40..33e4799 100644 --- a/lisp/transient.el +++ b/lisp/transient.el @@ -766,8 +766,8 @@ the prototype is stored in the clone's `prototype' slot.") :documentation "Inapt if major-mode does not derive from value.")) "Abstract superclass for group and suffix classes. -It is undefined what happens if more than one `if*' predicate -slot is non-nil." +It is undefined which predicates are used if more than one `if*' +predicate slots or more than one `inapt-if*' slots are non-nil." :abstract t) (defclass transient-suffix (transient-child)