v3.5.1 - key command field not accepting Alt+2 (workaround)

V3.5.1, MacOS / Extended & MacBook keyboards

Take any property that offers key command fields.

Try typing Alt+2 in a key command field. If the field is blank, a printable character will briefly appear (the Euro symbol on my keyboard). If the field already has a control character assigned, that character will flash briefly.

Under v3.4.13 and earlier, this key combination was problematic but could be obtained by allowing the normal character to remain and then typing Alt+2 a second time.

Switch to another keyboard type and try that. In my case, I used the Unicode Hex Input keyboard; I was able to obtain the Alt+2 character with 4 or 4 presses of the Alt+2 key combination.

Thanks for the report. Issue vassalengine.org/tracker/sho … i?id=14126 has been opened.

I have verified that this appears to work without trouble on both Windows and Linux systems.

Is this something that other MacOS users have noticed?

Do other ALT-n key combinations work correctly (Alt-, Alt-3?), or is it just Alt-2?

Is it possible that you have some software or background process configured that is recognising and eating the Alt-2?


I think it is Mac related then - and moreover related to how alternative key combinations are processed
(ie Alt+n generates a special character).

I did a check to find the various key combinations that cause problems , they are:-

Mac Key* British Keyboard
option+2 € (Euro-Symbol)**
option+3 Alt+3 (# is seen momentarily)
option+I “Alt+Dead_Circumflex”
option+U “Alt+Dead_Diaresis”
option+Y ¥ (Y= symbol)**
option+E “Alt+Dead_Acute”
option+` “Alt+Dead_Grave”
option+N “Alt+Dead_Tilde”

Mac Key* US keyboard:
option+2 Alt+2
option+3 £ (GBP symbol)**

(*) Right option key displays Alt+⌥ (MacOS option symbol) when pressed alone
but then combinations work the same as the left option key. For consistency, the right
option key should behave exactly as the left option key.

(**) These key combinations result in the output listed but then the first clears and the previous entry, if any, is restored.


A quick google indicates MacOs is doing some internal shenanigans to generate foreign currency symbols and accented characters using those key combinations. Not sure what we can do about that.

I see (also from a quick google) that it looks tricky. However, most of these Alt+ combos could be configured prior to v3.5, when long and short form key commands shared the same field. What would happen is that the first paired key press would insert a text character, the second would over write that with the correct Alt+ key command (for example, two presses of Option+2 gave € followed by Alt+2). Not that I want the old format back, the separate fields are so much easier to use.

For the benefit of anyone else needing this, I found a workarounds for all the affected Alt+ combos using different keyboards that can be configured on the Mac using the Keyboard preferences control panel. Other keyboards may work, these are first I found that worked.

Key Command : Keyboard that is able to input this code (using Option+ the keyboard character)
Alt+2 : US
Alt+3 : British
Alt+I : Vietnamese Simple Telex
Alt+U : Vietnamese Simple Telex
Alt+E : Vietnamese Simple Telex
Alt+’ : Vietnamese Simple Telex
Alt+N : Vietnamese Simple Telex
Alt+Y : Arabic+QWERTY (crashed Vassal on first attempt but worked thereafter).


Further update:

Configuring a Global Hotkey using the Telex keyboard (above), I found that a double key press was required.

Further trial and error shows that the MacOS “Bangla-QWERTY” keyboard seems to work for all the affected keys but the resulting Global Hotkey still requires two keypresses if the British or US keyboards are selected at the time (and I assume the same for most other types). This is true for Alt+N and the key types that generates +Dead keys from the British/US keyboards. Here it may be better to put the actual shortcut as part of the Button Name (accepting that [Alt+Dead…] will also appear in the button). Alt+2 / Alt+3 I expect to work ok, but if not, use the British/US keyboard for these.


Another curious observation that may help…

Configuring a Key Command on a Mac using British Keyboard (e.g. in a GKC)
Press option+N; generates Alt+Dead_Tilde as reported above.

Now go to an ordinary text field (e.g. button name). Press space (maybe other keys); a tilde (~) character is generated instead.


I am fairly sure this has something to do with the way that Mac Command and Fn keys generate other key strokes. I have not been able to find any useful information on how to handle this properly at the low level I am dealing with. I will keep investigating, but testing is a big problem without hardware!

I’ll get a Snapshot built that records the low-level key events that Java sees int the log file and get you to run that so we can see exactly what those key combos are generating.


Happy to help with testing.

Thanks Mark,

The test build is at vassalengine.org/tracker/sho … i?id=14133



Thanks Mark, much appreciated.

Some spare time activities for me :slight_smile:

Hi Mark,

That’s starting to make some sense.

One Question. I’m seeing what appear to backspaces typed at the end of many of the tests. Where you hitting the backspace key to clear out the field at the end of some tests?


Yes, I was. Thinking about it, I guess that I did not need to do that.

Hi Mark,

The series of KeyEvents being generated by MacOS are markedly different to those generated by Windows. I believe this is mainly due to MacOS intercepting these KeyStrokes and generating alternate characters. For example, the Option-2/Alt-2 sequence is generating a Euro character event.

However, MacOS does seem to be generating a correct and valid KeyReleased event that contains the correct information we want. Too bad Vassal is looking for the correct information in the KeyPressed event :slight_smile:

I have made a change that I think will work. I setting the Key name on both the KeyPressed and the KeyReleased event. For Windows, this makes no difference as they are both the same, they Key name just gets set twice. On Mac, this picks up the correct key on the release of the key. Looking at the logs you sent me, this should work.

If we’re lucky, it might even work to recognise the key when you use it as a Key Command.

We’ll have a new test build soon.

HI Mark,

Please try Test build: vassalengine.org/~uckelman/t … -macos.dmg

Hi Brent,

Thanks for this. Here is what I’ve found…

For Key Command definition, the snapshot fixes all the input errors for the different key combos that I have previously observed, even seemingly (to me) unrelated ones. i.e. fixes Option+character, Fn+F-key, double modifier key presses and makes both Option keys synonymous for input.

In the case of Option+ combos, the alternate character previously retained in the Key Command field (e.g. Euro symbol or “Dead…” string) is now briefly displayed but then replaced with the appropriate Alt+N character.

In general, the Vassal Player seems to be responding to key presses just as before. However, the fix unmasks a couple of anomalies with Option key combo presses:-

1) Double key press required for some Option key combos:
The test I have used is Alt+N on a Global Hotkey to display the Notes window. Previously, I had this defined using Option+N but it showed up as Alt+Dead_Tilde ; despite this it worked- a single key press of Option+N brought up the Notes window.

Using the snapshot build, I re-applied Option+N in the key command field for that Global Hotkey. Now, the shortcut displays as Alt+N but, in the Player, the first keypress is lost and it takes a second press to bring up the window. From testing other key combos, as far as I can tell, this issue applies only to the Option combos that generate Alt+Dead(something) i.e. option+I, option+U, option+E, option+` & option+N. This is the same error that I observed when I managed to input Alt+ characters using various non-english keyboards.

The particular example of the Notes window is consistent behaviour; close the Notes window and it again requires two key presses to re-open. However, there is more to it; if I use Option+I (for example), as a Key Command on a GKC; only the first key press is ignored; repeat presses repeat the action immediately. But, if I open a window the delay is imposed again…the first key press is ignored. This looks to me like some interaction between these special Option+ key presses and a window opening or being brought into focus.

2) Left and Right Option keys are not the same in execution.
Any Option+ key combo that I have tried will display that same in the Key Command field regardless of whether Left or Right Option key (or both) is used to define the key press. However, when the key command is pressed in the Player, it requires that the same Option key is pressed that was used to define the Key Command. In the case of a double option key, it is the first option key pressed to define the KC that is required when triggering that KC.

I noticed a couple of other other issues also that I think existed before:-

3)Hot-key press ignored when focus is on a piece for the first time
A similar but different issue to (1). It applies to any hotkey key presses.
To replicate; select a piece that hasn’t yet been selected in this game session (possibly “selected recently”); press a hotkey; it is ignored. Second and subsequent presses of any HotKey work, including if the piece is de-selected and returned to later. A entire series of pieces can be selected in turn or group-selected for the first time that session and the first hotkey press will be ignored each time; if at any point a piece is re-visited and a Hotkey is pressed whilst on that piece, that hotkey action will execute as expected.

4) Ctrl+character outputs that character to chat input field
For example, when Ctrl+1 is pressed, the numeric character appears in the chat input field (unless the chatter output window is the one in focus, in which case no character is generated). This is the case whether or not the Ctrl+1 character is a Hoy Key. It seems to apply to Ctrl+ numbers and symbols; it doesn’t apply to Ctrl+ alphabet characters. Option+ keys do not do this either, unless the cursor is in the Chatter input field, in which case an alternate character is generated.

I wonder if at some point someone has confused Ctrl and Option keys, intending that Alternate characters are always generated to chatter whether pressed on a map or in the chatter input field. This would beg a question about the conflict between Option/Alt+ for generating text vs as Key Commands, but it might explain what I’m observing.

Happy to run a new key press test or whatever helps.


Thanks for that Mark.

We are making progress, I was only really working on getting the correct key sequence to show up in the KeyStroke fields to start with. I think we have achieved that. The fact that the additional characters generated (like the Euro character for Alt-2) show up briefly, then dissappear is expected, it is similar to what happens of you define Ctrl-V, the pasted text shows up, then is replaced by Ctrl-V.

I am not surprised that some of the sequences are behaving strangely on the recognition end. That would have been too much to ask for! Vassal works primarily on Key Presses, but our testing shows that Macs only generate sensible key info on the key releases for the combo keys.

I’ll have to review how the key recognition works in more detail and I have your original logs which have all the info I need for now.

Get back to you soon.