Repository navigation
Expand file tree
/
Copy pathKeys.lua
More file actions
910 lines (804 loc) · 35 KB
/
Copy pathKeys.lua
File metadata and controls
910 lines (804 loc) · 35 KB
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
local ADDON, ns = ...
-- The key-binding mode: hover a button, press a key, it is bound.
--
-- === Why it exists when the game has a window for it ===
--
-- The game's keybinding window lists slots: "Action Bar 1, Button 7". To bind
-- a key to the seventh button of the second bar the player has to work out
-- which bar on screen is the second and which button on it is the seventh.
-- They look at the screen, count, go into the list, find the row, click,
-- press the key. Bartender works the same way and is just as awkward.
--
-- Here it is different: the player looks at the button they want and presses
-- a key. No counting, no list, no bar name.
--
-- === What this does to the player's settings ===
--
-- A REAL game binding is set, not ours on top of it. That is a decision, and
-- the reason is this: the addon routes the player's keys to its buttons with
-- an override (see Bind.lua), and a second binding system of our own would
-- mean two places holding the answer to "what does key 1 do". Two places
-- always drift. So the mode writes where the game's window writes, and an
-- addon switched off leaves the player with the keys they bound here.
--
-- === What the mode does not do ===
--
-- Anything in combat. Binding a key is protected and cannot be done
-- mid-fight. So the mode does not enter combat and leaves it by itself.
local Keys = {}
ns.Keys = Keys
-- Keys that mean nothing on their own.
--
-- A modifier is not a key but a prefix to one: a shift pressed with no second
-- key has nothing to bind. Without this list the first touch of shift would
-- bind "SHIFT" to the button, overriding every shift combination at once.
local IGNORED = {
LSHIFT = true, RSHIFT = true,
LCTRL = true, RCTRL = true,
LALT = true, RALT = true,
UNKNOWN = true,
-- Print screen: a key the engine hands to us but the game does not allow
-- to be bound.
PRINTSCREEN = true,
}
Keys.IGNORED = IGNORED
-- A Cyrillic letter -> the Latin letter in the same place on the keyboard.
--
-- === What for ===
--
-- A key is a PLACE on the keyboard, not a letter on it. A player with two
-- layouts presses the same key while the engine names it differently: "E" in
-- the English layout, a Cyrillic letter in the Russian one. Bound from the
-- Russian layout it would work only there, and the player would lose it
-- silently on switching.
--
-- So the letter is brought to Latin by place: the Russian layout's rows laid
-- over QWERTY. The player sees "E" on the button and presses the same key in
-- any layout.
--
-- The Cyrillic in the table below is not words for the player but KEY NAMES
-- arriving from the engine. They are not subject to translation and cannot be
-- read any other way; the markers around it say the exception is deliberate,
-- and tests/test_language.lua reads those markers.
-- [cyrillic: foreign names]
--
-- Both letter cases are listed by name: Lua cannot uppercase Cyrillic - it
-- works on bytes, and a letter here is two of them.
local LATIN = {
["Й"] = "Q", ["й"] = "Q", ["Ц"] = "W", ["ц"] = "W",
["У"] = "E", ["у"] = "E", ["К"] = "R", ["к"] = "R",
["Е"] = "T", ["е"] = "T", ["Н"] = "Y", ["н"] = "Y",
["Г"] = "U", ["г"] = "U", ["Ш"] = "I", ["ш"] = "I",
["Щ"] = "O", ["щ"] = "O", ["З"] = "P", ["з"] = "P",
["Х"] = "[", ["х"] = "[", ["Ъ"] = "]", ["ъ"] = "]",
["Ф"] = "A", ["ф"] = "A", ["Ы"] = "S", ["ы"] = "S",
["В"] = "D", ["в"] = "D", ["А"] = "F", ["а"] = "F",
["П"] = "G", ["п"] = "G", ["Р"] = "H", ["р"] = "H",
["О"] = "J", ["о"] = "J", ["Л"] = "K", ["л"] = "K",
["Д"] = "L", ["д"] = "L", ["Ж"] = ";", ["ж"] = ";",
["Э"] = "'", ["э"] = "'", ["Я"] = "Z", ["я"] = "Z",
["Ч"] = "X", ["ч"] = "X", ["С"] = "C", ["с"] = "C",
["М"] = "V", ["м"] = "V", ["И"] = "B", ["и"] = "B",
["Т"] = "N", ["т"] = "N", ["Ь"] = "M", ["ь"] = "M",
["Б"] = ",", ["б"] = ",", ["Ю"] = ".", ["ю"] = ".",
["Ё"] = "`", ["ё"] = "`", ["І"] = "S", ["і"] = "S",
["Ї"] = "]", ["ї"] = "]", ["Є"] = "'", ["є"] = "'",
["Ґ"] = "\\", ["ґ"] = "\\",
}
-- [/cyrillic]
Keys.LATIN = LATIN
--- Bring a letter to Latin by its place on the keyboard.
--
-- Pure. Anything absent from the table is returned as it is: digits, the F
-- row, the arrows and Latin letters are named the same everywhere.
--
-- @param key any key name
-- @return any
function Keys.Latin(key)
if type(key) ~= "string" then return key end
return LATIN[key] or key
end
--- Every name the engine may use for the key in this chord.
--
-- === The bug this exists for ===
--
-- Keys.Latin solves half the problem: whatever layout the player bound from,
-- the binding is STORED under the Latin name, and the button shows a key the
-- player recognises.
--
-- The other half is the press. The engine names a key by the ACTIVE LAYOUT:
-- press the apostrophe key with Russian on and the engine says the Cyrillic
-- letter that sits there, looks that name up, finds nothing bound to it, and
-- the button does not fire. The player reports it as "the binding works in
-- English and nowhere else", which is exactly what it does.
--
-- So the key is bound under every name its place can answer to. The modifier
-- prefix is kept as it is - it is named the same in every layout.
--
-- Pure, and the order is fixed: the chord itself first, then the rest sorted,
-- so the same chord always yields the same list.
--
-- @param chord any a chord as Keys.Chord assembles it
-- @return table array of chords, the given one first; empty for rubbish
function Keys.Aliases(chord)
if type(chord) ~= "string" or chord == "" then return {} end
-- The prefix is split off by the LAST hyphen rather than the first: the
-- key itself can be a hyphen ("ALT-CTRL--"), and splitting at the first
-- would hand back "CTRL--" as the key.
local prefix, key = chord:match("^(.*-)([^-]*)$")
if key == nil or key == "" then
prefix, key = "", chord
end
-- The place this key sits at, named in Latin. Works from either side:
-- given a Cyrillic name the map answers directly, given a Latin one the
-- key is already the answer.
local place = LATIN[key] or key
local out, seen = { chord }, { [chord] = true }
local others = { place }
for name, latin in pairs(LATIN) do
if latin == place then others[#others + 1] = name end
end
table.sort(others)
for i = 1, #others do
local alias = prefix .. others[i]
if not seen[alias] then
out[#out + 1] = alias
seen[alias] = true
end
end
return out
end
--- Assemble a key chord.
--
-- Pure. The order of the prefixes is not taste: the game assembles them
-- strictly as ALT-CTRL-SHIFT, and a chord assembled otherwise will bind but
-- stay foreign - the keybinding window shows it as a separate row and the
-- player ends up with two bindings for one press.
--
-- @param key any key name from the engine
-- @param shift any whether shift is held
-- @param ctrl any whether ctrl is held
-- @param alt any whether alt is held
-- @return string|nil the chord, or nil when there is nothing to bind
function Keys.Chord(key, shift, ctrl, alt)
if type(key) ~= "string" or key == "" then return nil end
if IGNORED[key] then return nil end
-- The key is NOT converted. What the engine said is what gets bound.
--
-- It used to be brought to Latin here, on the reasoning that a key is a
-- place rather than a letter. The reasoning is sound and the consequence
-- was not: bind from the Russian layout, the engine says the Cyrillic
-- name, we store the Latin one, and the press in that same layout then
-- matches nothing. The player bound a key and it worked in every layout
-- except the one they were using.
--
-- Bartender4 binds exactly what the engine reports, and that is why its
-- bindings work. The place-not-a-letter idea is honoured where it
-- belongs instead - on the OVERRIDE bindings, which carry every name the
-- place can answer to (Keys.Aliases, ns.Apply.Bind).
local chord = ""
if alt then chord = chord .. "ALT-" end
if ctrl then chord = chord .. "CTRL-" end
if shift then chord = chord .. "SHIFT-" end
return chord .. key
end
--- What this button binds.
--
-- The button knows its bar and its index, while the action name is assembled by
-- Bind.For - the same one the key routing uses. One place for both questions:
-- were they to drift, the window would show one key and another would press.
--
-- @param button any
-- @return string|nil
function Keys.Action(button)
if type(button) ~= "table" then return nil end
-- The binding points AT THE BUTTON, not at the game's action slot.
--
-- === Why that matters, and it is what the reference does ===
--
-- LibActionButton-1.0 binds "CLICK <button>:LeftButton" and nothing
-- else. Two things follow from it.
--
-- Several keys may answer to one button, because the game allows an
-- action any number of keys. That is the answer to a keyboard with
-- three layouts on it: the player binds the same physical key once in
-- each, both names land on the same button, and the button fires
-- whichever layout is on. Binding to the game's action slot gave one
-- key only, so the second layout had nowhere to go.
--
-- And the key no longer depends on the player's own bindings staying
-- as they were. A binding on the slot is a binding we share with the
-- game's own bar; a binding on the button is ours.
local name = ns.Bind.ButtonName(button.rackBar, button.rackIndex)
local click = name and ns.Bind.ClickName(name) or nil
if click then return click end
return ns.Bind.For(button.rackBar, button.rackIndex)
end
--============================================================================
-- The mode itself
--============================================================================
-- Whether the mode is on.
local on = false
-- Overlays over the buttons: button -> frame.
local covers = setmetatable({}, { __mode = "k" })
--- Whether the mode is running.
-- @return boolean
function Keys.Shown()
return on == true
end
--- Save the whole binding set.
--
-- Without saving, what was bound lives until logout and then vanishes silently.
local function save()
if type(_G.SaveBindings) ~= "function" then return end
local which = 1
if type(_G.GetCurrentBindingSet) == "function" then
local ok, said = pcall(_G.GetCurrentBindingSet)
if ok and type(said) == "number" then which = said end
end
pcall(_G.SaveBindings, which)
end
--- Bind a key to a button.
--
-- @param button table
-- @param chord string|nil the chord; nil means "clear all"
-- @return boolean whether anything was done
-- Other people's business the game keeps its keys for.
--
-- A list not of keys but of ACTIONS: which key is bound to them is the
-- player's decision - Enter for one, anything else for another.
local RESERVED = { "SCREENSHOT", "OPENCHAT" }
Keys.RESERVED = RESERVED
--- Whether the game keeps this key for itself.
--
-- The binding table arrives as an argument: otherwise none of this could be
-- verified.
--
-- @param key any the key
-- @param bound any function(action) -> key; nil - the real one
-- @return string|nil whose business it is, or nil
function Keys.Reserved(key, bound)
if type(key) ~= "string" or key == "" then return nil end
local ask = bound
if ask == nil and type(_G.GetBindingKey) == "function" then
ask = _G.GetBindingKey
end
if type(ask) ~= "function" then return nil end
for i = 1, #RESERVED do
local ok, said = pcall(ask, RESERVED[i])
if ok and type(said) == "string" and said == key then
return RESERVED[i]
end
end
return nil
end
--- Do what the player keeps this key for.
--
-- A screenshot and opening chat are not our business, but swallowing the key
-- would take them away. The overlay reads the keyboard for itself, so the press
-- never reaches the game.
--
-- @param key any the key
-- @return boolean whether anything was done
function Keys.Serve(key)
local what = Keys.Reserved(key)
if what == nil then return false end
if what == "SCREENSHOT" and type(_G.Screenshot) == "function" then
return pcall(_G.Screenshot) and true or false
end
if what == "OPENCHAT" and type(_G.ChatFrame_OpenChat) == "function" then
return pcall(_G.ChatFrame_OpenChat, "") and true or false
end
return false
end
--- Give keyboard input to exactly one overlay.
--
-- === What this used to be ===
--
-- An overlay enabled input for itself when the mouse arrived and disabled it
-- when the mouse left. That sounds right and does not work.
--
-- The engine does not promise that "left" will arrive: a mouse that skipped
-- two buttons in one frame leaves the first overlay with input enabled. And a
-- key goes to ONE of those reading it, chosen by frame order rather than by
-- the player.
--
-- Symptom: the cursor over one button, the key bound to another. Worse, that
-- other button lost its previous binding, recoverable only by hand.
--
-- Now there is one reader for all of them. The mouse arriving takes input from
-- the previous overlay and gives it to this one, and however many "left"
-- events are lost on the way, the reading overlay is always the one under the
-- mouse.
--
-- The library Bartender4 uses is built the same way: there one reading frame
-- serves every button and the button names itself to it. The difference from
-- our approach is small, and the "the mouse is really on me" check is in both.
--
-- @param frame any the overlay to give input to; nil - take it from all
-- @return boolean whether it was given to anyone
local reading
function Keys.Focus(frame)
if reading and reading ~= frame then
pcall(reading.SetPropagateKeyboardInput, reading, true)
pcall(reading.EnableKeyboard, reading, false)
end
reading = nil
if type(frame) ~= "table" then return false end
pcall(frame.EnableKeyboard, frame, true)
pcall(frame.SetPropagateKeyboardInput, frame, false)
reading = frame
return true
end
--- Learn which key is bound to this button and store it on the button.
--
-- === Why, when the apply already does it ===
--
-- It does, but by too long a road: a full apply rebuilds every bar and gets to
-- the label last. Between the keypress and the label on the button lay that
-- whole road - and it has plenty of places to break: combat, a disabled bar,
-- any error of somebody else's.
--
-- Symptom: pressed F, nothing changed on the button. The key was bound and
-- worked, the label appeared only after a relog, and it looked like "binding
-- does not work".
--
-- Here the road is short and ours: ask the game, write it on the button. The
-- apply still follows - it routes the keys to our buttons - but the label no
-- longer waits for it.
--
-- @param button any the button
-- @return string|nil the key, already abbreviated
function Keys.Learn(button)
if type(button) ~= "table" then return nil end
if type(_G.GetBindingKey) ~= "function" then return nil end
-- BOTH bindings are read, and every key of each.
--
-- A key can be on the button - "CLICK <button>:LeftButton", which is
-- what this addon writes - or on the game's action slot, which is what
-- the player had before installing it. Reading only the first left
-- every existing key invisible: the binding mode showed a dash on
-- every button and looked as though the keys had been wiped.
--
-- Every key, not the first, because a button may now answer to several.
-- Duplicates are dropped: the same key may well sit on both the button
-- and the slot, and a label reading "1, 1" says nothing twice.
local names, seen = {}, {}
local own = ns.Bind.ButtonName(button.rackBar, button.rackIndex)
local click = own and ns.Bind.ClickName(own) or nil
local slot = ns.Bind.For(button.rackBar, button.rackIndex)
for _, action in ipairs({ click, slot }) do
if type(action) == "string" then
local ok, a, b = pcall(_G.GetBindingKey, action)
if ok then
for _, stroke in ipairs({ a, b }) do
if type(stroke) == "string" and stroke ~= "" then
-- The game does the abbreviating: its rules are
-- shorter than ours and the same as on every other
-- button on screen. Each key separately, because
-- the abbreviator takes one name at a time.
local short = stroke
if type(_G.GetBindingText) == "function" then
local okText, brief =
pcall(_G.GetBindingText, stroke, "KEY_")
if okText and type(brief) == "string"
and brief ~= "" then
short = brief
end
end
if not seen[short] then
seen[short] = true
names[#names + 1] = short
end
end
end
end
end
end
if #names == 0 then
button.rackBinding = nil
return nil
end
local said = table.concat(names, ", ")
button.rackBinding = said
return said
end
--- What is on this button, and what presses it.
--
-- === Why a tooltip and not the label ===
--
-- The label on the overlay has room for the keys and nothing else, and in
-- binding mode the icon is covered - so a player looking at a bar of
-- overlays cannot tell which button is which. They end up binding by
-- counting positions, which is exactly the mistake hover binding exists to
-- prevent.
--
-- The game's own tooltip answers the first half: handed the action slot it
-- shows the spell, the macro or the item, the same way it does on any other
-- bar. The keys are added under it, all of them, because a button may now
-- answer to several.
--
-- @param button any the button
-- @param frame any the overlay to anchor to
-- @return boolean whether anything was shown
function Keys.Hint(button, frame)
if type(button) ~= "table" or type(frame) ~= "table" then return false end
local tip = _G.GameTooltip
if type(tip) ~= "table" then return false end
if type(tip.SetOwner) ~= "function" then return false end
if not pcall(tip.SetOwner, tip, frame, "ANCHOR_RIGHT") then return false end
-- What is on it. The slot is asked of the button rather than computed,
-- so a paged bar shows what it is showing now.
local shown = false
local slot = ns.Paint and ns.Paint.Slot and ns.Paint.Slot(button) or nil
if slot and type(tip.SetAction) == "function" then
shown = pcall(tip.SetAction, tip, slot) or false
end
if not shown and type(tip.SetText) == "function" then
-- An empty slot, a pet ability or a stance: the game has no tooltip
-- to hand over, so the button says which it is.
local what = ns.L("Empty")
if button.rackBar == "pet" then what = ns.L("Pet Bar")
elseif button.rackBar == "stance" then what = ns.L("Stance Bar") end
pcall(tip.SetText, tip, what)
end
-- And what presses it. Learn gives every key, shortened and joined.
local keys = Keys.Learn(button)
if type(tip.AddLine) == "function" then
if type(keys) == "string" and keys ~= "" then
pcall(tip.AddLine, tip, ns.L("Keys: ") .. keys, 0.6, 0.8, 1)
else
pcall(tip.AddLine, tip, ns.L("No key yet"), 0.6, 0.6, 0.6)
end
pcall(tip.AddLine, tip,
ns.L("Press a key to add one. Escape clears them all."),
0.6, 0.6, 0.6, true)
end
if type(tip.Show) == "function" then pcall(tip.Show, tip) end
return true
end
--- Take the hint away.
-- @return boolean
function Keys.Unhint()
local tip = _G.GameTooltip
if type(tip) ~= "table" or type(tip.Hide) ~= "function" then
return false
end
return pcall(tip.Hide, tip) or false
end
--- Review the keys of ALL buttons and show them.
--
-- === Why all of them and not the one that was touched ===
--
-- Binding overrides the chord's previous owner: press F on the third button
-- and the seventh, where F used to be, no longer has it. That is correct and
-- is how the game's own keybinding window behaves.
--
-- On screen it was not shown: the third button got F, the seventh kept showing
-- it. Two buttons with one key - and the player believes both until they press.
--
-- The labels on the buttons themselves are refreshed in the same pass: the
-- player binds a key in order to see it ON THE BUTTON, not only on the overlay
-- over it.
--
-- A hundred and twenty buttons in one pass is a frame of work, and it happens
-- only on a keypress, that is, once every few seconds.
--
-- @return number how many buttons were reviewed
function Keys.Refresh()
-- Key routing by the short path, with no bar rebuild. A full apply does
-- everything else besides, and on every keypress that turned into lost
-- frames.
if ns.Bars and type(ns.Bars.BindAll) == "function" then
ns.Bars.BindAll()
end
local seen = 0
for key, list in pairs(ns.Build.buttons) do
local own = ns.Bars.BarSettings(key)
local shown = type(own) ~= "table" or own.showHotkey ~= false
for i = 1, #list do
local button = list[i]
if type(button) == "table" then
-- The routing already wrote the key on the button; show it.
Keys.Paint(button)
if button.rackHotkey then
local said = shown
and ns.Paint.Textual(button.rackBinding) or nil
pcall(button.rackHotkey.SetText, button.rackHotkey,
said or "")
end
seen = seen + 1
end
end
end
return seen
end
function Keys.Assign(button, chord)
local action = Keys.Action(button)
if action == nil then return false end
if type(_G.SetBinding) ~= "function" then return false end
if ns.Build.InCombat() then return false end
-- Clearing: ALL keys bound to this action are removed.
--
-- === Why a loop and not "first and second" ===
--
-- It used to be: ask for the first and the second, remove them. Two is how
-- many the game shows in its keybinding window, but it returns AS MANY AS
-- THERE ARE, and such a removal left a third one on the button. The player
-- pressed Escape, the button showed "-", and the key kept working.
--
-- The loop asks again after each removal: the list afterwards is a
-- different one, and answers remembered in advance no longer fit it. The
-- library Bartender4 uses does the same - the technique is common, not its.
if chord == nil then
if type(_G.GetBindingKey) ~= "function" then return false end
local cleared = false
-- BOTH bindings are cleared: the one on the button, which this addon
-- writes, and the one on the game's action slot, which the player
-- had before it. Escape over a button means "this button has no key
-- any more", and leaving the slot binding would keep the button
-- firing from a key the label no longer shows.
local own = ns.Bind.ButtonName(button.rackBar, button.rackIndex)
local both = { action }
local slot = ns.Bind.For(button.rackBar, button.rackIndex)
if type(slot) == "string" and slot ~= action then
both[#both + 1] = slot
end
for _, which in ipairs(both) do
-- A limit in case the game somehow will not let a key go: a
-- loop that may not end is worse than a button left uncleared.
for _ = 1, 16 do
local ok, stroke = pcall(_G.GetBindingKey, which)
if not ok or type(stroke) ~= "string" or stroke == "" then
break
end
if not pcall(_G.SetBinding, stroke, nil) then break end
cleared = true
end
end
if cleared then
save()
Keys.Learn(button)
end
return cleared
end
-- The new key is ADDED. The button's existing keys are left alone.
--
-- === Why this changed ===
--
-- It used to replace: hover a button, press a key, and whatever was
-- bound there before was cleared. The reasoning was that the gesture
-- means "this button is pressed by this", and that the label shows only
-- the first key, so a second one looked like nothing had happened.
--
-- A keyboard with three layouts on it breaks that reasoning. The same
-- physical key is named differently in each, and the player needs all
-- of those names on one button or the button answers in one layout
-- only. Replacing made the second name impossible to add.
--
-- The game has always allowed an action any number of keys, and
-- Bartender4 lets a player use them. So does this now, and the label
-- shows all of them rather than the first.
--
-- Clearing is still one gesture away: Escape over the button takes them
-- all off at once.
-- Binding overrides the chord's previous owner, and that is correct: a
-- player who pressed "1" on a button wants "1" here, not a message saying
-- it is taken. The previous owner is left without the key - which is how
-- the game's own keybinding window behaves.
--
-- Regression: the game refuses in TWO ways, by dropping and by returning
-- failure. Only the drop was checked, so a refusal passed as success. It
-- refuses on keys it keeps for itself - Enter, for instance. To the player
-- that looked like: pressed Enter, nothing changed, and nobody said why.
local ok, taken = pcall(_G.SetBinding, chord, action)
if not ok then return false end
-- Every other name this PLACE on the keyboard answers to is bound too.
--
-- === Why automatically, and only for these keys ===
--
-- A letter is named the same in every layout. Punctuation is not: the
-- key left of Enter is an apostrophe in one layout and a Cyrillic
-- letter in another, and the engine reports whichever the player's
-- layout makes it. Bound under one name it answers in one layout.
--
-- The player should not have to notice that, nor bind the same key once
-- per layout. So the moment such a key is bound, every name it can
-- arrive under is bound with it - to the same button, which the game
-- allows any number of keys.
--
-- A key with no other names - a letter, a digit, the F row - yields a
-- list of one and nothing extra happens.
--
-- Failures are ignored on purpose: a name the engine will not take is
-- one it would never have sent either.
for _, alias in ipairs(ns.Keys.Aliases(chord)) do
if alias ~= chord then
pcall(_G.SetBinding, alias, action)
end
end
if taken == false then
if ns.Handle and type(ns.Handle.Print) == "function" then
pcall(ns.Handle.Print, ns.Handle,
ns.L("The game keeps that key for itself: it cannot be "
.. "assigned to a button."))
end
return false
end
save()
-- The label right away rather than after a full apply: the player pressed
-- a key and has to see it on the button that same instant.
Keys.Learn(button)
return true
end
--- Create an overlay over a button.
--
-- The overlay is a frame of our own over the button, and it is needed because
-- the button itself is protected: keyboard input cannot be enabled on it,
-- while on our own frame it can. The overlay also blocks the click: in binding
-- mode a click does not cast a spell.
--
-- @param button table
-- @return table|nil
local function cover(button)
if covers[button] then return covers[button] end
if type(CreateFrame) ~= "function" then return nil end
local ok, frame = pcall(CreateFrame, "Frame", nil, button)
if not ok or type(frame) ~= "table" then return nil end
pcall(frame.SetAllPoints, frame, button)
pcall(frame.SetFrameStrata, frame, "DIALOG")
pcall(frame.EnableMouse, frame, true)
-- The keyboard is enabled on the overlay under the mouse and on that one
-- only. Otherwise every overlay would get the key at once: the engine
-- hands a press to each frame reading the keyboard, and it would be bound
-- to whichever button came last in the order.
pcall(frame.EnableKeyboard, frame, false)
pcall(frame.SetPropagateKeyboardInput, frame, false)
ns.Skin.Backdrop(frame, "ink", "accent")
local text = frame:CreateFontString(nil, "OVERLAY",
"GameFontHighlightSmall")
pcall(text.SetPoint, text, "CENTER", frame, "CENTER", 0, 0)
frame.rackText = text
-- The keyboard is read by the overlay under the mouse. There is no notion
-- of a "selected button" here at all: the selection is where the player is
-- looking, and storing it separately would be a second answer to a
-- question the mouse answers by itself.
pcall(frame.SetScript, frame, "OnEnter", function(self)
Keys.Focus(self)
Keys.Paint(button)
Keys.Hint(button, self)
end)
pcall(frame.SetScript, frame, "OnLeave", function()
Keys.Focus(nil)
Keys.Unhint()
end)
pcall(frame.SetScript, frame, "OnKeyDown", function(self, key)
-- Is the mouse really on this overlay?
--
-- Keyboard input is one for all of them and is handed over when the
-- mouse arrives. But between arriving and the press the mouse could
-- have left - button to button, off the screen edge, anywhere - and
-- "left" might never have arrived. Binding a key to a button with no
-- cursor over it is exactly what the player complained about.
if type(self.IsMouseOver) == "function" then
local ok, over = pcall(self.IsMouseOver, self)
if ok and not over then return end
end
-- Keys the game keeps for itself are NOT bound and not swallowed: they
-- do their job.
--
-- A screenshot and opening chat are the two because of which a player
-- ends up with no chat after binding Enter to a button. They are
-- recognised not by key name but by what the PLAYER has bound: their
-- Enter may be anything.
--
-- The library Bartender4 uses does the same.
if Keys.Reserved(key) then
Keys.Serve(key)
return
end
local shift = _G.IsShiftKeyDown and _G.IsShiftKeyDown()
local ctrl = _G.IsControlKeyDown and _G.IsControlKeyDown()
local alt = _G.IsAltKeyDown and _G.IsAltKeyDown()
-- Escape clears the binding rather than leaving the mode: leaving is a
-- command, while right now there is a button under the mouse and the
-- commonest wish here is "take the key off this".
if key == "ESCAPE" then
Keys.Assign(button, nil)
else
local chord = Keys.Chord(key, shift, ctrl, alt)
if chord == nil then return end
Keys.Assign(button, chord)
end
-- Labels BEFORE the apply, not after, and on ALL buttons rather than
-- this one. An apply rebuilds every bar and the labels came last on it;
-- meanwhile binding overrides the chord's previous owner, and that
-- owner's label has to disappear in the same instant.
--
-- Key routing and labels in one short pass. A full apply is
-- deliberately absent: it rebuilds every bar, and on every keypress
-- that cost the player frames.
Keys.Refresh()
end)
-- A mouse click in binding mode does not cast: the overlay catches the
-- mouse. The mouse button itself can still be bound - the engine hands it
-- to the same key handler.
pcall(frame.SetScript, frame, "OnMouseDown", function(_, click)
local shift = _G.IsShiftKeyDown and _G.IsShiftKeyDown()
local ctrl = _G.IsControlKeyDown and _G.IsControlKeyDown()
local alt = _G.IsAltKeyDown and _G.IsAltKeyDown()
local chord = Keys.Chord(Keys.MouseName(click), shift, ctrl, alt)
if chord == nil then return end
Keys.Assign(button, chord)
Keys.Refresh()
end)
covers[button] = frame
return frame
end
--- The name of a mouse button as the binding engine calls it.
--
-- Left and right are not bound at all: they press the button and drag spells,
-- and giving them over to a binding would take both away from the player.
--
-- @param click any
-- @return string|nil
function Keys.MouseName(click)
if type(click) ~= "string" then return nil end
if click == "LeftButton" or click == "RightButton" then return nil end
if click == "MiddleButton" then return "BUTTON3" end
local number = click:match("^Button(%d+)$")
if number then return "BUTTON" .. number end
return nil
end
--- Write on the overlay what the button does now.
-- @param button table
function Keys.Paint(button)
local frame = covers[button]
if type(frame) ~= "table" or type(frame.rackText) ~= "table" then return end
local said = ns.Paint.Textual(button.rackBinding) or "—"
pcall(frame.rackText.SetText, frame.rackText, said)
end
--- Switch the mode on or off.
--
-- @param wanted any
-- @return boolean whether the mode is on after the call
function Keys.Toggle(wanted)
if wanted == nil then wanted = not on end
wanted = wanted and true or false
-- The mode does not enter combat: binding a key is protected, and an
-- overlay promising a binding would be a lie.
if wanted and ns.Build.InCombat() then return on end
on = wanted
-- Keyboard input is taken from everyone: with the mode off there is nobody
-- to read, and an overlay left reading would keep the player's input.
if not on then Keys.Focus(nil) end
for key, list in pairs(ns.Build.buttons) do
for i = 1, #list do
local button = list[i]
if type(button) == "table" then
local frame = on and cover(button) or covers[button]
if frame then
if on then
-- The key is asked again: it may have been changed in
-- the game's own window since last time.
Keys.Learn(button)
Keys.Paint(button)
pcall(frame.Show, frame)
else
-- The keyboard is released in TWO motions: input is
-- disabled and propagation is restored.
--
-- The "do not propagate" flag outlives the keypress on
-- the frame, and an overlay hidden with it would keep
-- holding the player's input. A stolen Enter is a
-- stolen chat.
pcall(frame.SetPropagateKeyboardInput, frame, true)
pcall(frame.EnableKeyboard, frame, false)
pcall(frame.Hide, frame)
end
end
end
end
end
return on
end