-
Notifications
You must be signed in to change notification settings - Fork 0
/
Copy pathtransient.info
3661 lines (2873 loc) · 163 KB
/
transient.info
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
This is docBTBFNO.info, produced by makeinfo version 6.8 from
transient.texi.
Copyright (C) 2018–2025 Free Software Foundation, Inc.
You can redistribute this document and/or modify it under the terms
of the GNU General Public License as published by the Free Software
Foundation, either version 3 of the License, or (at your option)
any later version.
This document is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
General Public License for more details.
INFO-DIR-SECTION Emacs misc features
START-INFO-DIR-ENTRY
* Transient: (transient). Transient Commands.
END-INFO-DIR-ENTRY
File: docBTBFNO.info, Node: Top, Next: Introduction, Up: (dir)
Transient User and Developer Manual
***********************************
Transient is the library used to implement the keyboard-driven “menus”
in Magit. It is distributed as a separate package, so that it can be
used to implement similar menus in other packages.
This manual can be bit hard to digest when getting started. A useful
resource to get over that hurdle is Psionic K’s interactive tutorial,
available at <https://github.com/positron-solutions/transient-showcase>.
This manual is for Transient version 0.8.4.
Copyright (C) 2018–2025 Free Software Foundation, Inc.
You can redistribute this document and/or modify it under the terms
of the GNU General Public License as published by the Free Software
Foundation, either version 3 of the License, or (at your option)
any later version.
This document is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
General Public License for more details.
* Menu:
* Introduction::
* Usage::
* Modifying Existing Transients::
* Defining New Commands::
* Classes and Methods::
* FAQ::
* Keystroke Index::
* Command and Function Index::
* Variable Index::
* Concept Index::
* GNU General Public License::
— The Detailed Node Listing —
Usage
* Invoking Transients::
* Aborting and Resuming Transients::
* Common Suffix Commands::
* Saving Values::
* Using History::
* Getting Help for Suffix Commands::
* Enabling and Disabling Suffixes::
* Other Commands::
* Configuration::
Defining New Commands
* Technical Introduction::
* Defining Transients::
* Binding Suffix and Infix Commands::
* Defining Suffix and Infix Commands::
* Using Infix Arguments::
* Using Prefix Scope::
* Current Suffix Command::
* Current Prefix Command::
* Transient State::
Binding Suffix and Infix Commands
* Group Specifications::
* Suffix Specifications::
Classes and Methods
* Group Classes::
* Group Methods::
* Prefix Classes::
* Suffix Classes::
* Prefix Methods::
* Suffix Methods::
* Prefix Slots::
* Suffix Slots::
* Predicate Slots::
Suffix Methods
* Suffix Value Methods::
* Suffix Format Methods::
File: docBTBFNO.info, Node: Introduction, Next: Usage, Prev: Top, Up: Top
1 Introduction
**************
Transient is the library used to implement the keyboard-driven “menus”
in Magit. It is distributed as a separate package, so that it can be
used to implement similar menus in other packages.
This manual can be bit hard to digest when getting started. A useful
resource to get over that hurdle is Psionic K’s interactive tutorial,
available at <https://github.com/positron-solutions/transient-showcase>.
Some things that Transient can do
=================================
• Display current state of arguments
• Display and manage lifecycle of modal bindings
• Contextual user interface
• Flow control for wizard-like composition of interactive forms
• History & persistence
• Rendering arguments for controlling CLI programs
Complexity in CLI programs
==========================
Complexity tends to grow with time. How do you manage the complexity of
commands? Consider the humble shell command ‘ls’. It now has over
_fifty_ command line options. Some of these are boolean flags (‘ls
-l’). Some take arguments (‘ls --sort=s’). Some have no effect unless
paired with other flags (‘ls -lh’). Some are mutually exclusive. Some
shell commands even have so many options that they introduce
_subcommands_ (‘git branch’, ‘git commit’), each with their own rich set
of options (‘git branch -f’).
Using Transient for composing interactive commands
==================================================
What about Emacs commands used interactively? How do these handle
options? One solution is to make many versions of the same command, so
you don’t need to! Consider: ‘delete-other-windows’ vs.
‘delete-other-windows-vertically’ (among many similar examples).
Some Emacs commands will simply prompt you for the next "argument"
(‘M-x switch-to-buffer’). Another common solution is to use prefix
arguments which usually start with ‘C-u’. Sometimes these are sensibly
numerical in nature (‘C-u 4 M-x forward-paragraph’ to move forward 4
paragraphs). But sometimes they function instead as boolean "switches"
(‘C-u C-SPACE’ to jump to the last mark instead of just setting it, ‘C-u
C-u C-SPACE’ to unconditionally set the mark). Since there aren’t many
standards for the use of prefix options, you have to read the command’s
documentation to find out what the possibilities are.
But when an Emacs command grows to have a truly large set of options
and arguments, with dependencies between them, lots of option values,
etc., these simple approaches just don’t scale. Transient is designed
to solve this issue. Think of it as the humble prefix argument ‘C-u’,
_raised to the power of 10_. Like ‘C-u’, it is key driven. Like the
shell, it supports boolean "flag" options, options that take arguments,
and even "sub-commands", with their own options. But instead of
searching through a man page or command documentation, well-designed
transients _guide_ their users to the relevant set of options (and even
their possible values!) directly, taking into account any important
pre-existing Emacs settings. And while for shell commands like ‘ls’,
there is only one way to "execute" (hit ‘Return’!), transients can
"execute" using multiple different keys tied to one of many
self-documenting _actions_ (imagine having 5 different colored return
keys on your keyboard!). Transients make navigating and setting large,
complex groups of command options and arguments easy. Fun even. Once
you’ve tried it, it’s hard to go back to the ‘C-u what can I do here
again?’ way.
File: docBTBFNO.info, Node: Usage, Next: Modifying Existing Transients, Prev: Introduction, Up: Top
2 Usage
*******
* Menu:
* Invoking Transients::
* Aborting and Resuming Transients::
* Common Suffix Commands::
* Saving Values::
* Using History::
* Getting Help for Suffix Commands::
* Enabling and Disabling Suffixes::
* Other Commands::
* Configuration::
File: docBTBFNO.info, Node: Invoking Transients, Next: Aborting and Resuming Transients, Up: Usage
2.1 Invoking Transients
=======================
A transient prefix command is invoked like any other command by pressing
the key that is bound to that command. The main difference to other
commands is that a transient prefix command activates a transient
keymap, which temporarily binds the transient’s infix and suffix
commands, and that those bindings are displayed in a transient menu,
displayed in a popup buffer. Bindings from other keymaps may, or may
not, be disabled while the transient state is in effect.
There are two kinds of commands that are available after invoking a
transient prefix command; infix and suffix commands. Infix commands set
some value (which is then shown in the popup buffer), without leaving
the transient. Suffix commands, on the other hand, usually quit the
transient and they may use the values set by the infix commands, i.e.,
the infix *arguments*.
Instead of setting arguments to be used by a suffix command, infix
commands may also set some value by side-effect, e.g., by setting the
value of some variable.
File: docBTBFNO.info, Node: Aborting and Resuming Transients, Next: Common Suffix Commands, Prev: Invoking Transients, Up: Usage
2.2 Aborting and Resuming Transients
====================================
To quit the transient without invoking a suffix command press ‘C-g’.
Key bindings in transient keymaps may be longer than a single event.
After pressing a valid prefix key, all commands whose bindings do not
begin with that prefix key are temporarily unavailable and grayed out.
To abort the prefix key press ‘C-g’ (which in this case only quits the
prefix key, but not the complete transient).
A transient prefix command can be bound as a suffix of another
transient. Invoking such a suffix replaces the current transient state
with a new transient state, i.e., the available bindings change and the
information displayed in the popup buffer is updated accordingly.
Pressing ‘C-g’ while a nested transient is active only quits the
innermost transient, causing a return to the previous transient.
‘C-q’ or ‘C-z’ on the other hand always exits all transients. If you
use the latter, then you can later resume the stack of transients using
‘M-x transient-resume’.
Key: C-g (transient-quit-seq)
Key: C-g (transient-quit-one)
This key quits the currently active incomplete key sequence, if
any, or else the current transient. When quitting the current
transient, it returns to the previous transient, if any.
Transient’s predecessor bound ‘q’ instead of ‘C-g’ to the quit
command. To learn how to get that binding back see
‘transient-bind-q-to-quit’’s documentation string.
Key: C-q (transient-quit-all)
This command quits the currently active incomplete key sequence, if
any, and all transients, including the active transient and all
suspended transients, if any.
Key: C-z (transient-suspend)
Like ‘transient-quit-all’, this command quits an incomplete key
sequence, if any, and all transients. Additionally, it saves the
stack of transients so that it can easily be resumed (which is
particularly useful if you quickly need to do “something else” and
the stack is deeper than a single transient, and/or you have
already changed the values of some infix arguments).
Note that only a single stack of transients can be saved at a time.
If another stack is already saved, then saving a new stack discards
the previous stack.
Key: M-x transient-resume
This command resumes the previously suspended stack of transients,
if any.
File: docBTBFNO.info, Node: Common Suffix Commands, Next: Saving Values, Prev: Aborting and Resuming Transients, Up: Usage
2.3 Common Suffix Commands
==========================
A few shared suffix commands are available in all transients. These
suffix commands are not shown in the popup buffer by default.
This includes the aborting commands mentioned in the previous
section, as well as some other commands that are all bound to ‘C-x KEY’.
After ‘C-x’ is pressed, a section featuring all these common commands is
temporarily shown in the popup buffer. After invoking one of them, the
section disappears again. Note, however, that one of these commands is
described as “Show common permanently”; invoke that if you want the
common commands to always be shown for all transients.
Key: C-x t (transient-toggle-common)
This command toggles whether the generic commands that are common
to all transients are always displayed or only after typing the
incomplete prefix key sequence ‘C-x’. This only affects the
current Emacs session.
User Option: transient-show-common-commands
This option controls whether shared suffix commands are shown
alongside the transient-specific infix and suffix commands. By
default, the shared commands are not shown to avoid overwhelming
the user with too many options.
While a transient is active, pressing ‘C-x’ always shows the common
commands. The value of this option can be changed for the current
Emacs session by typing ‘C-x t’ while a transient is active.
The other common commands are described in either the previous or in
one of the following sections.
File: docBTBFNO.info, Node: Saving Values, Next: Using History, Prev: Common Suffix Commands, Up: Usage
2.4 Saving Values
=================
After setting the infix arguments in a transient, the user can save
those arguments for future invocations.
Most transients will start out with the saved arguments when they are
invoked. There are a few exceptions, though. Some transients are
designed so that the value that they use is stored externally as the
buffer-local value of some variable. Invoking such a transient again
uses the buffer-local value. (1)
If the user does not save the value and just exits using a regular
suffix command, then the value is merely saved to the transient’s
history. That value won’t be used when the transient is next invoked,
but it is easily accessible (see *note Using History::).
Key: C-x s (transient-set)
This command saves the value of the active transient for this Emacs
session.
Key: C-x C-s (transient-save)
This command saves the value of the active transient persistently
across Emacs sessions.
Key: C-x C-k (transient-reset)
This command clears the set and saved values of the active
transient.
User Option: transient-values-file
This option names the file that is used to persist the values of
transients between Emacs sessions.
---------- Footnotes ----------
(1) ‘magit-diff’ and ‘magit-log’ are two prominent examples, and
their handling of buffer-local values is actually a bit more complicated
than outlined above and even customizable.
File: docBTBFNO.info, Node: Using History, Next: Getting Help for Suffix Commands, Prev: Saving Values, Up: Usage
2.5 Using History
=================
Every time the user invokes a suffix command the transient’s current
value is saved to its history. These values can be cycled through, the
same way one can cycle through the history of commands that read
user-input in the minibuffer.
Key: C-M-p (transient-history-prev)
Key: C-x p
This command switches to the previous value used for the active
transient.
Key: C-M-n (transient-history-next)
Key: C-x n
This command switches to the next value used for the active
transient.
In addition to the transient-wide history, infixes can have their own
history. When an infix reads user-input using the minibuffer, the user
can use the regular minibuffer history commands to cycle through
previously used values. Usually the same keys as those mentioned above
are bound to those commands.
Authors of transients should arrange for different infix commands
that read the same kind of value to also use the same history key (see
*note Suffix Slots::).
Both kinds of history are saved to a file when Emacs is exited.
User Option: transient-save-history
This option controls whether the history of transient commands is
saved when exiting Emacs.
User Option: transient-history-file
This option names the file that is used to persist the history of
transients and their infixes between Emacs sessions.
User Option: transient-history-limit
This option controls how many history elements are kept at the time
the history is saved in ‘transient-history-file’.
File: docBTBFNO.info, Node: Getting Help for Suffix Commands, Next: Enabling and Disabling Suffixes, Prev: Using History, Up: Usage
2.6 Getting Help for Suffix Commands
====================================
Transients can have many suffixes and infixes that the user might not be
familiar with. To make it trivial to get help for these, Transient
provides access to the documentation directly from the active transient.
Key: C-h (transient-help)
This command enters help mode. When help mode is active, typing a
key shows information about the suffix command that the key
normally is bound to (instead of invoking it). Pressing ‘C-h’ a
second time shows information about the _prefix_ command.
After typing a key, the stack of transient states is suspended and
information about the suffix command is shown instead. Typing ‘q’
in the help buffer buries that buffer and resumes the transient
state.
What sort of documentation is shown depends on how the transient was
defined. For infix commands that represent command-line arguments this
ideally shows the appropriate manpage. ‘transient-help’ then tries to
jump to the correct location within that. Info manuals are also
supported. The fallback is to show the command’s documentation string,
for non-infix suffixes this is usually appropriate.
File: docBTBFNO.info, Node: Enabling and Disabling Suffixes, Next: Other Commands, Prev: Getting Help for Suffix Commands, Up: Usage
2.7 Enabling and Disabling Suffixes
===================================
The user base of a package that uses transients can be very diverse.
This is certainly the case for Magit; some users have been using it and
Git for a decade, while others are just getting started now.
For that reason a mechanism is needed that authors can use to
classify a transient’s infixes and suffixes along the
essentials...everything spectrum. We use the term “levels” to describe
that mechanism.
Each suffix command is placed on a level and each transient has a
level (called “transient-level”), which controls which suffix commands
are available. Integers between 1 and 7 (inclusive) are valid levels.
For suffixes, 0 is also valid; it means that the suffix is not displayed
at any level.
The levels of individual transients and/or their individual suffixes
can be changed interactively, by invoking the transient and then
pressing ‘C-x l’ to enter the “edit” mode, see below.
The default level for both transients and their suffixes is 4. The
‘transient-default-level’ option only controls the default for
transients. The default suffix level is always 4. The authors of
transients should place certain suffixes on a higher level, if they
expect that it won’t be of use to most users, and they should place very
important suffixes on a lower level, so that they remain available even
if the user lowers the transient level.
User Option: transient-default-level
This option controls which suffix levels are made available by
default. It sets the transient-level for transients for which the
user has not set that individually.
User Option: transient-levels-file
This option names the file that is used to persist the levels of
transients and their suffixes between Emacs sessions.
Key: C-x l (transient-set-level)
This command enters edit mode. When edit mode is active, then all
infixes and suffixes that are currently usable are displayed along
with their levels. The colors of the levels indicate whether they
are enabled or not. The level of the transient is also displayed
along with some usage information.
In edit mode, pressing the key that would usually invoke a certain
suffix instead prompts the user for the level that suffix should be
placed on.
Help mode is available in edit mode.
To change the transient level press ‘C-x l’ again.
To exit edit mode press ‘C-g’.
Note that edit mode does not display any suffixes that are not
currently usable. ‘magit-rebase’, for example, shows different
suffixes depending on whether a rebase is already in progress or
not. The predicates also apply in edit mode.
Therefore, to control which suffixes are available given a certain
state, you have to make sure that that state is currently active.
Key: C-x a (transient-toggle-level-limit)
This command toggle whether suffixes that are on levels higher than
the level specified by ‘transient-default-level’ are temporarily
available anyway.
Function: transient-set-default-level suffix level
This function sets the default level of the suffix COMMAND to
LEVEL.
If a suffix command appears in multiple menus, it may make sense to
consistently change its level in all those menus at once. For
example, the ‘--gpg-sign’ argument (which is implemented using the
command ‘magit:--gpg-sign’), is bound in all of Magit’s menu which
create commits. Users who sometimes sign their commits would want
that argument to be available in all of these menus, while for
users who never sign it is just unnecessary noise in any menus.
To always make ‘--gpg-sign’ available, use:
(transient-set-default-level 'magit:--gpg-sign 1)
To never make ‘--gpg-sign’ available, use:
(transient-set-default-level 'magit:--gpg-sign 0)
This sets the level in the suffix prototype object for this
command. Commands only have a suffix prototype if they were
defined using one of ‘transient-define-argument’,
‘transient-define-infix’ and ‘transient-define-suffix’. For all
other commands this would signal an error. (This is one of the
reasons why package authors should use one of these functions to
define shared suffix commands, and especially shared arguments.)
If the user changes the level of a suffix in a particular menu,
using ‘C-x l’ as shown above, then that obviously shadows the
default.
It is also possible to set the level of a suffix binding in a
particular menu, either when defining the menu using
‘transient-define-prefix,’ or later using
‘transient-insert-suffix’. If such bindings specify a level, then
that also overrides the default. (Per-suffix default levels is a
new feature, so you might encounter this quite often.)
File: docBTBFNO.info, Node: Other Commands, Next: Configuration, Prev: Enabling and Disabling Suffixes, Up: Usage
2.8 Other Commands
==================
When invoking a transient in a small frame, the transient window may not
show the complete buffer, making it necessary to scroll, using the
following commands. These commands are never shown in the transient
window, and the key bindings are the same as for ‘scroll-up-command’ and
‘scroll-down-command’ in other buffers.
Command: transient-scroll-up arg
This command scrolls text of transient popup window upward ARG
lines. If ARG is ‘nil’, then it scrolls near full screen. This is
a wrapper around ‘scroll-up-command’ (which see).
Command: transient-scroll-down arg
This command scrolls text of transient popup window down ARG lines.
If ARG is ‘nil’, then it scrolls near full screen. This is a
wrapper around ‘scroll-down-command’ (which see).
The following commands are not available by default. If you would
like to use them for all menus, bind them in ‘transient-map’.
Command: transient-copy-menu-text
This command copies the contents of the menu buffer to the kill
ring.
Command: transient-toggle-docstrings
This command toggle between showing suffix descriptions in the menu
(as usual) or showing the first lines of the respective docstrings
in their place. For commands that do not have a docstring, always
display the suffix description. Because there likely isn’t enough
room to display multiple docstrings side-by-side, a single column
is used when displaying docstrings.
File: docBTBFNO.info, Node: Configuration, Prev: Other Commands, Up: Usage
2.9 Configuration
=================
More options are described in *note Common Suffix Commands::, in *note
Saving Values::, in *note Using History:: and in *note Enabling and
Disabling Suffixes::.
Essential Options
-----------------
Also see *note Common Suffix Commands::.
User Option: transient-show-popup
This option controls whether the current transient’s infix and
suffix commands are shown in the popup buffer.
• If ‘t’ (the default) then the popup buffer is shown as soon as
a transient prefix command is invoked.
• If ‘nil’, then the popup buffer is not shown unless the user
explicitly requests it, by pressing an incomplete prefix key
sequence.
• If a number, then the a brief one-line summary is shown
instead of the popup buffer. If zero or negative, then not
even that summary is shown; only the pressed key itself is
shown.
The popup is shown when the user explicitly requests it by
pressing an incomplete prefix key sequence. Unless this is
zero, the popup is shown after that many seconds of inactivity
(using the absolute value).
User Option: transient-show-common-commands
This option controls whether shared suffix commands are shown
alongside the transient-specific infix and suffix commands. By
default, the shared commands are not shown to avoid overwhelming
the user with too many options.
While a transient is active, pressing ‘C-x’ always shows the common
commands. The value of this option can be changed for the current
Emacs session by typing ‘C-x t’ while a transient is active.
User Option: transient-show-during-minibuffer-read
This option controls whether the transient menu continues to be
displayed while the minibuffer is used to read user input.
This is only relevant to commands that do not close the menu, such
as commands that set infix arguments. If a command exits the menu,
and uses the minibuffer, then the menu is always closed before the
minibuffer is entered, irrespective of the value of this option.
When ‘nil’ (the default), hide the menu while the minibuffer is in
use. When ‘t’, keep showing the menu, but allow for the menu
window to be resized, to ensure that completion candidates can be
displayed.
When ‘fixed’, keep showing the menu and prevent it from being
resized, which may make it impossible to display the completion
candidates. If that ever happens for you, consider using ‘t’ or an
integer, as described below.
If the value is ‘fixed’ and the menu window uses the full height of
its frame, then the former is ignored and resizing is allowed
anyway. This is necessary because individual menus may use unusual
display actions different from what
‘transient-display-buffer-action’ specifies (likely to display that
menu in a side-window).
When using a third-party mode, which automatically resizes windows
(e.g., by calling ‘balance-windows’ on ‘post-command-hook’), then
‘fixed’ (or ‘nil’) is likely a better choice than ‘t’.
The value can also be an integer, in which case the behavior
depends on whether at least that many lines are left to display
windows other than the menu window. If that is the case, display
the menu and preserve the size of that window. Otherwise, allow
resizing the menu window if the number is positive, or hide the
menu if it is negative.
User Option: transient-read-with-initial-input
This option controls whether the last history element is used as
the initial minibuffer input when reading the value of an infix
argument from the user. If ‘nil’, there is no initial input and
the first element has to be accessed the same way as the older
elements.
User Option: transient-enable-popup-navigation
This option controls whether navigation commands are enabled in the
transient popup buffer. If the value is ‘verbose’ (the default),
brief documentation about the command under point is additionally
show in the echo area.
While a transient is active the transient popup buffer is not the
current buffer, making it necessary to use dedicated commands to
act on that buffer itself. If this option is non-‘nil’, then the
following features are available:
• ‘<UP>’ moves the cursor to the previous suffix.
• ‘<DOWN>’ moves the cursor to the next suffix.
• ‘M-<RET>’ invokes the suffix the cursor is on.
• ‘mouse-1’ invokes the clicked on suffix.
• ‘C-s’ and ‘C-r’ start isearch in the popup buffer.
By default ‘M-<RET>’ is bound to ‘transient-push-button’, instead
of ‘<RET>’, because if a transient allows the invocation of
non-suffixes, then it is likely, that you would want ‘<RET>’ to do
what it would do if no transient were active."
User Option: transient-display-buffer-action
This option specifies the action used to display the transient
popup buffer. The transient popup buffer is displayed in a window
using ‘(display-buffer BUFFER transient-display-buffer-action)’.
The value of this option has the form ‘(FUNCTION . ALIST)’, where
FUNCTION is a function or a list of functions. Each such function
should accept two arguments: a buffer to display and an alist of
the same form as ALIST. See *note (elisp)Choosing Window::, for
details.
The default is:
(display-buffer-in-side-window
(side . bottom)
(dedicated . t)
(inhibit-same-window . t))
This displays the window at the bottom of the selected frame. For
alternatives see *note (elisp)Buffer Display Action Functions::,
and *note (elisp)Buffer Display Action Alists::.
Note that the buffer that was current before the transient buffer
is shown should remain the current buffer. Many suffix commands
act on the thing at point, if appropriate, and if the transient
buffer became the current buffer, then that would change what is at
point. To that effect ‘inhibit-same-window’ ensures that the
selected window is not used to show the transient buffer.
It may be possible to display the window in another frame, but
whether that works in practice depends on the window-manager. If
the window manager selects the new window (Emacs frame), then that
unfortunately changes which buffer is current.
If you change the value of this option, then you might also want to
change the value of ‘transient-mode-line-format’.
This user option may be overridden if ‘:display-action’ is passed
when creating a new prefix with ‘transient-define-prefix’.
Accessibility Options
---------------------
User Option: transient-force-single-column
This option controls whether the use of a single column to display
suffixes is enforced. This might be useful for users with low
vision who use large text and might otherwise have to scroll in two
dimensions.
Auxiliary Options
-----------------
User Option: transient-mode-line-format
This option controls whether the transient popup buffer has a
mode-line, separator line, or neither.
If ‘nil’, then the buffer has no mode-line. If the buffer is not
displayed right above the echo area, then this probably is not a
good value.
If ‘line’ (the default) or a natural number, then the buffer has no
mode-line, but a line is drawn in its place. If a number is used,
that specifies the thickness of the line. On termcap frames we
cannot draw lines, so there ‘line’ and numbers are synonyms for
‘nil’.
The color of the line is used to indicate if non-suffixes are
allowed and whether they exit the transient. The foreground color
of ‘transient-key-noop’ (if non-suffixes are disallowed),
‘transient-key-stay’ (if allowed and transient stays active), or
‘transient-key-exit’ (if allowed and they exit the transient) is
used to draw the line.
This user option may be overridden if ‘:mode-line-format’ is passed
when creating a new prefix with ‘transient-define-prefix’.
Otherwise this can be any mode-line format. See *note (elisp)Mode
Line Format::, for details.
User Option: transient-semantic-coloring
This option controls whether colors are used to indicate the
transient behavior of commands.
If non-‘nil’, then the key binding of each suffix is colorized to
indicate whether it exits the transient state or not. The color of
the prefix is indicated using the line that is drawn when the value
of ‘transient-mode-line-format’ is ‘line’.
User Option: transient-highlight-mismatched-keys
This option controls whether key bindings of infix commands that do
not match the respective command-line argument should be
highlighted. For other infix commands this option has no effect.
When this option is non-‘nil’, the key binding for an infix
argument is highlighted when only a long argument (e.g.,
‘--verbose’) is specified but no shorthand (e.g., ‘-v’). In the
rare case that a shorthand is specified but the key binding does
not match, then it is highlighted differently.
Highlighting mismatched key bindings is useful when learning the
arguments of the underlying command-line tool; you wouldn’t want to
learn any short-hands that do not actually exist.
The highlighting is done using one of the faces
‘transient-mismatched-key’ and ‘transient-nonstandard-key’.
User Option: transient-substitute-key-function
This function is used to modify key bindings. If the value of this
option is ‘nil’ (the default), then no substitution is performed.
This function is called with one argument, the prefix object, and
must return a key binding description, either the existing key
description it finds in the ‘key’ slot, or the key description that
replaces the prefix key. It could be used to make other
substitutions, but that is discouraged.
For example, ‘=’ is hard to reach using my custom keyboard layout,
so I substitute ‘(’ for that, which is easy to reach using a layout
optimized for lisp.
(setq transient-substitute-key-function
(lambda (obj)
(let ((key (oref obj key)))
(if (string-match "\\`\\(=\\)[a-zA-Z]" key)
(replace-match "(" t t key 1)
key))))
User Option: transient-align-variable-pitch
This option controls whether columns are aligned pixel-wise in the
popup buffer.
If this is non-‘nil’, then columns are aligned pixel-wise to
support variable-pitch fonts. Keys are not aligned, so you should
use a fixed-pitch font for the ‘transient-key’ face. Other key
faces inherit from that face unless a theme is used that breaks
that relationship.
This option is intended for users who use a variable-pitch font for
the ‘default’ face.
User Option: transient-force-fixed-pitch
This option controls whether to force the use of a monospaced font
in popup buffer. Even if you use a proportional font for the
‘default’ face, you might still want to use a monospaced font in
transient’s popup buffer. Setting this option to ‘t’ causes
‘default’ to be remapped to ‘fixed-pitch’ in that buffer.
Developer Options
-----------------
These options are mainly intended for developers.
User Option: transient-detect-key-conflicts
This option controls whether key binding conflicts should be
detected at the time the transient is invoked. If so, this results
in an error, which prevents the transient from being used. Because
of that, conflicts are ignored by default.
Conflicts cannot be determined earlier, i.e., when the transient is
being defined and when new suffixes are being added, because at
that time there can be false-positives. It is actually valid for
multiple suffixes to share a common key binding, provided the
predicates of those suffixes prevent that more than one of them is
enabled at a time.
User Option: transient-highlight-higher-levels
This option controls whether suffixes that would not be available
by default are highlighted.
When non-‘nil’ then the descriptions of suffixes are highlighted if
their level is above 4, the default of ‘transient-default-level’.
Assuming you have set that variable to 7, this highlights all
suffixes that won’t be available to users without them making the
same customization.
Hook Variables
--------------
Variable: transient-exit-hook
This hook is run after a transient is exited.
Variable: transient-setup-buffer-hook
This hook is run when the transient buffer is being setup. That
buffer is current and empty when this hook is runs.
File: docBTBFNO.info, Node: Modifying Existing Transients, Next: Defining New Commands, Prev: Usage, Up: Top
3 Modifying Existing Transients
*******************************
To an extent, transients can be customized interactively, see *note
Enabling and Disabling Suffixes::. This section explains how existing
transients can be further modified non-interactively. Let’s begin with
an example:
(transient-append-suffix 'magit-patch-apply "-3"
'("-R" "Apply in reverse" "--reverse"))
This inserts a new infix argument to toggle the ‘--reverse’ argument
after the infix argument that toggles ‘-3’ in ‘magit-patch-apply’.
The following functions share a few arguments:
• PREFIX is a transient prefix command, a symbol.
• SUFFIX is a transient infix or suffix specification in the same
form as expected by ‘transient-define-prefix’. Note that an infix
is a special kind of suffix. Depending on context “suffixes” means
“suffixes (including infixes)” or “non-infix suffixes”. Here it
means the former. See *note Suffix Specifications::.
SUFFIX may also be a group in the same form as expected by
‘transient-define-prefix’. See *note Group Specifications::.
• LOC is a command, a key vector, a key description (a string as
returned by ‘key-description’), or a list specifying coordinates
(the last element may also be a command or key). For example ‘(1 0
-1)’ identifies the last suffix (‘-1’) of the first subgroup (‘0’)
of the second group (‘1’).
If LOC is a list of coordinates, then it can be used to identify a
group, not just an individual suffix command.
The function ‘transient-get-suffix’ can be useful to determine
whether a certain coordination list identifies the suffix or group
that you expect it to identify. In hairy cases it may be necessary
to look at the definition of the transient prefix command.
These functions operate on the information stored in the
‘transient--layout’ property of the PREFIX symbol. Suffix entries in
that tree are not objects but have the form ‘(LEVEL CLASS PLIST)’, where
PLIST should set at least ‘:key’, ‘:description’ and ‘:command’.
Function: transient-insert-suffix prefix loc suffix &optional keep-other
Function: transient-append-suffix prefix loc suffix &optional keep-other
These functions insert the suffix or group SUFFIX into PREFIX
before or after LOC.
Conceptually adding a binding to a transient prefix is similar to
adding a binding to a keymap, but this is complicated by the fact
that multiple suffix commands can be bound to the same key,
provided they are never active at the same time, see *note
Predicate Slots::.
Unfortunately both false-positives and false-negatives are
possible. To deal with the former use non-‘nil’ KEEP-OTHER. To
deal with the latter remove the conflicting binding explicitly.
Function: transient-replace-suffix prefix loc suffix
This function replaces the suffix or group at LOC in PREFIX with
suffix or group SUFFIX.
Function: transient-remove-suffix prefix loc
This function removes the suffix or group at LOC in PREFIX.
Function: transient-get-suffix prefix loc
This function returns the suffix or group at LOC in PREFIX. The
returned value has the form mentioned above.
Function: transient-suffix-put prefix loc prop value
This function edits the suffix or group at LOC in PREFIX, by
setting the PROP of its plist to VALUE.
Most of these functions do not signal an error if they cannot perform
the requested modification. The functions that insert new suffixes show
a warning if LOC cannot be found in PREFIX without signaling an error.
The reason for doing it like this is that establishing a key binding
(and that is what we essentially are trying to do here) should not
prevent the rest of the configuration from loading. Among these
functions only ‘transient-get-suffix’ and ‘transient-suffix-put’ may
signal an error.
File: docBTBFNO.info, Node: Defining New Commands, Next: Classes and Methods, Prev: Modifying Existing Transients, Up: Top
4 Defining New Commands
***********************
* Menu:
* Technical Introduction::
* Defining Transients::
* Binding Suffix and Infix Commands::
* Defining Suffix and Infix Commands::
* Using Infix Arguments::
* Using Prefix Scope::
* Current Suffix Command::
* Current Prefix Command::
* Transient State::
File: docBTBFNO.info, Node: Technical Introduction, Next: Defining Transients, Up: Defining New Commands
4.1 Technical Introduction
==========================
Taking inspiration from prefix keys and prefix arguments, Transient
implements a similar abstraction involving a prefix command, infix
arguments and suffix commands.