transient-active-prefix: New function

CHANGELOG

@@ -1,4 +1,8 @@
 # -*- mode: org -*-
+* v0.7.4    UNRELEASED
+
+- Added new function ~transient-active-prefix~.
+
 * v0.7.3    2024-07-13
 
 - Refactored code responsible for inserting columns.

docs/transient.org

@@ -1285,16 +1285,32 @@ function, which for infix arguments serves about the same purpose as
   values.  In complex cases it might be necessary to use this variable
   instead, i.e., if you need access to information beside the value.
 
+- Variable: transient-current-command ::
+
+  The transient from which this suffix command was invoked.  The
+  returned value is a symbol, the transient prefix command.
+
 - Variable: transient-current-prefix ::
 
   The transient from which this suffix command was invoked.  The
   returned value is a ~transient-prefix~ object, which holds information
   associated with the transient prefix command.
 
-- Variable: transient-current-command ::
+- Variable: transient-active-prefix ::
 
-  The transient from which this suffix command was invoked.  The
-  returned value is a symbol, the transient prefix command.
+  This function returns the active transient object.  Return ~nil~ if
+  there is no active transient, if the transient buffer isn't shown,
+  and while the active transient is suspended (e.g., while the
+  minibuffer is in use).
+
+  Unlike ~transient-current-prefix~, which is only ever non-~nil~ in code
+  that is run directly by a command that is invoked while a transient
+  is current, this function is also suitable for use in asynchronous
+  code, such as timers and callbacks (this function's main use-case).
+
+  If optional PREFIXES is non-~nil~, it must be a list of prefix command
+  symbols, in which case the active transient object is only returned
+  if it matches one of the PREFIXES."
 
 ** Transient State
 #+cindex: transient state

docs/transient.texi

@@ -1488,15 +1488,31 @@ values.  In complex cases it might be necessary to use this variable
 instead, i.e., if you need access to information beside the value.
 @end defvar
 
+@defvar transient-current-command
+The transient from which this suffix command was invoked.  The
+returned value is a symbol, the transient prefix command.
+@end defvar
+
 @defvar transient-current-prefix
 The transient from which this suffix command was invoked.  The
 returned value is a @code{transient-prefix} object, which holds information
 associated with the transient prefix command.
 @end defvar
 
-@defvar transient-current-command
-The transient from which this suffix command was invoked.  The
-returned value is a symbol, the transient prefix command.
+@defvar transient-active-prefix
+This function returns the active transient object.  Return @code{nil} if
+there is no active transient, if the transient buffer isn't shown,
+and while the active transient is suspended (e.g., while the
+minibuffer is in use).
+
+Unlike @code{transient-current-prefix}, which is only ever non-@code{nil} in code
+that is run directly by a command that is invoked while a transient
+is current, this function is also suitable for use in asynchronous
+code, such as timers and callbacks (this function's main use-case).
+
+If optional PREFIXES is non-@code{nil}, it must be a list of prefix command
+symbols, in which case the active transient object is only returned
+if it matches one of the PREFIXES."
 @end defvar
 
 @node Transient State

lisp/transient.el

@@ -1591,6 +1591,31 @@ This is bound while the suffixes are drawn in the transient buffer.")
 
 ;;; Identities
 
+(defun transient-active-prefix (&optional prefixes)
+  "Return the active transient object.
+
+Return nil if there is no active transient, if the transient buffer
+isn't shown, and while the active transient is suspended (e.g., while
+the minibuffer is in use).
+
+Unlike `transient-current-prefix', which is only ever non-nil in code
+that is run directly by a command that is invoked while a transient
+is current, this function is also suitable for use in asynchronous
+code, such as timers and callbacks (this function's main use-case).
+
+If optional PREFIXES is non-nil, it must be a list of prefix command
+symbols, in which case the active transient object is only returned
+if it matches one of the PREFIXES."
+  (and transient--showp
+       transient--prefix
+       (or (not prefixes)
+           (memq (oref transient--prefix command) prefixes))
+       (or (memq 'transient--pre-command pre-command-hook)
+           (and (memq t pre-command-hook)
+                (memq 'transient--pre-command
+                      (default-value 'pre-command-hook))))
+       transient--prefix))
+
 (defun transient-prefix-object ()
   "Return the current prefix as an object.