Additional KeyCode Support...

About SheepShaver, a PPC Mac emulator for Windows, MacOS X, and Linux that can run System 7.5.3 to MacOS 9.0.4.

Moderators: Cat_7, Ronald P. Regensburg, ClockWise

Post Reply
InitCursor
Student Driver
Posts: 12
Joined: Tue Aug 02, 2022 7:09 pm

Additional KeyCode Support...

Post by InitCursor »

For SheepShaver, is there any plan to implement support for additional keycodes -- like the Enter key (Mac Extended Keyboard)? Or, has there ever been any discussion about adding a user-configurable section in the GUI that would support this kind of functionality (vs. changing the keycodes files and rebulding -- or however it is done today)?

For example, IIRC, on non-extended keyboards, Fn+Return was the equivalent for the numeric keypad Enter key.

I have worked around the missing Enter key on Windows SheepShaver using the Keyboard Extender v2.0.3 Control Strip module (to set up a persistent Enter Key button). But, it would be great if Fn+Return worked.
User avatar
Ronald P. Regensburg
Expert User
Posts: 7333
Joined: Thu Feb 09, 2006 10:24 pm
Location: Amsterdam, Netherlands

Re: Additional KeyCode Support...

Post by Ronald P. Regensburg »

I am the one who maintains the keycode files for the latest SDL2 builds with SDL2 scancode to Mac keycode translations. It contains the translation for the Enter key, SDL2 scan code 88 to Mac keycode 76.

If you use the latest SDL2 SheepShaver build and if you use the latest keycode file and if your keyboard has an Enter key, the Enter key should work in SheepShaver.

If your keyboard is an ANSI keyboard, using the keycodes file will translate one key (`/~) incorrectly. See the ReadMe included with this keycode files download for how to correct that: http://ronaldpr.home.xs4all.nl/keycodes ... y_2022.zip

Edit 1: If you use an US English keyboard layout on an ANSI keyboard, you do not need a keycodes file. With that setup I would expect the Enter key to work as expected.

Edit 2: If you use a keyboard without separate Enter key, how do you "Enter" in Windows?

Edit 3: I know of no SDL2 scancode for the Fn key
InitCursor
Student Driver
Posts: 12
Joined: Tue Aug 02, 2022 7:09 pm

Re: Additional KeyCode Support...

Post by InitCursor »

Hi -

Thanks for the reply!

My question relates to the "Enter" key at the lower right of the numeric keypad of Apple keyboards -- extended, etc. The Enter key is not the same as the Return key, and I am not asking about the Enter/Return key on the standard PC keyboard.

You can find the Apple ADB keymaps/keyboards here: Apple Extended Keyboard

More information here: Wikipedia - Enter Key

And, yes, as you point out, I now realize that the Fn key on the PC keyboard is completely masked from the keyboard driver. So, that won't work. But, given that SheepShaver is a Mac emulator, then it should include the Mac's "Enter" key in the lower right. There should be an easy way to send a Mac Enter key using a standard PC keyboard -- maybe Ctrl+Return or Cmd (Alt)+Return. I'm not sure what is available -- I am new to SS.

This problem occurs because there is no Apple "Enter" key on the PC keyboard. It probably needs to be virtualized through an intuitive key combination.
User avatar
adespoton
Forum All-Star
Posts: 3736
Joined: Fri Nov 27, 2009 5:11 am
Location: Emaculation.com
Contact:

Re: Additional KeyCode Support...

Post by adespoton »

InitCursor wrote: Fri Aug 05, 2022 5:49 pm Hi -

Thanks for the reply!

My question relates to the "Enter" key at the lower right of the numeric keypad of Apple keyboards -- extended, etc. The Enter key is not the same as the Return key, and I am not asking about the Enter/Return key on the standard PC keyboard.

You can find the Apple ADB keymaps/keyboards here: Apple Extended Keyboard

More information here: Wikipedia - Enter Key

And, yes, as you point out, I now realize that the Fn key on the PC keyboard is completely masked from the keyboard driver. So, that won't work. But, given that SheepShaver is a Mac emulator, then it should include the Mac's "Enter" key in the lower right. There should be an easy way to send a Mac Enter key using a standard PC keyboard -- maybe Ctrl+Return or Cmd (Alt)+Return. I'm not sure what is available -- I am new to SS.

This problem occurs because there is no Apple "Enter" key on the PC keyboard. It probably needs to be virtualized through an intuitive key combination.
Isn't the "Enter" key just the PC keypad "Enter" key?

Fn key pre-modifies the keycodes coming out of the keyboard driver. So Fn-Return should indeed be the Enter key. I don't think the issue is with the SDL keycode file... all the characters (except Fn, because it's not a keycode) appear to be there. The trick is to figure out how to trigger them with your specific keyboard.

Maybe https://js4code.com/keycode-detector would help?
User avatar
Ronald P. Regensburg
Expert User
Posts: 7333
Joined: Thu Feb 09, 2006 10:24 pm
Location: Amsterdam, Netherlands

Re: Additional KeyCode Support...

Post by Ronald P. Regensburg »

Yes, I know what is the Enter key on a Mac extended keyboard and I know it is not the same as the Return key.

I assume you use one of the most recent (26-01-2022 or 12-07-2022) SheepShaver builds for Windows and that you use the most recent keycodes file. That keycodes file is included in the 26-01-2022 SheepShaver for Windows download or separately here: http://ronaldpr.home.xs4all.nl/keycodes ... y_2022.zip.
If not, upgrade your setup and enable the use of the keycodes file in the GUI.

Do you have a keyboard with numeric pad with Enter key? That key should work as Enter key (not as Return key) in SheepShaver.

If it does not work as it should, also not while using the keycodes file, then there are other possibilities to get an Enter key in SheepShaver.

The Fn key has a Mac keycode (63) but I have not been able to find a SDL2 scancode for that key, so a physical Fn key cannot be used in SheepShaver.

It is possible to map one of the other (modifier) keys on your keyboard to the Mac Fn key, but then you cannot use that modifier key for anything else. If you have no other use for the Fn key, it would be simpler to map that key directly to the Mac Enter key.
InitCursor
Student Driver
Posts: 12
Joined: Tue Aug 02, 2022 7:09 pm

Re: Additional KeyCode Support...

Post by InitCursor »

OK - thanks. Sorry for the duplicate info. Your earlier comments implied that you seemed to be interpreting "Enter" and "Return" as the same key or misunderstood my question.
I think I have the latest SheepShaver build - July 2022. I downloaded it a few days ago. The GUI.exe About says it is version 2.5.
The SheepShaver.exe has no version resource or internal About.
It would be very helpful to include standard Windows version resources/abouts in the builds of the Windows .exe files.
I do not have a numeric keypad on my laptop keyboard -- hence this issue.
If there are important files that users need (like keycode files, etc.), it would be helpful if they were included in each build. I did look for the keycode file in the July build, didn't see it and didn't know that I had to get it from the January build.
If there is keycode support for different configurations, it would be helpful to add those settings to the Keyboard/Mouse in Gui.exe. I spent a bunch of time searching and it wasn't exactly clear what I was supposed to do.
Also, generally speaking, the downloads are not secure. Is it possible to serve the content from a secure/https server to avoid browser and download errors/warnings?

I just downloaded the keycodes file and am in a hurry at the moment, but I will try to see if I can get it working later tonight. It would be helpful if the comments in the keycodes files included their respective IDs. I won't be able to use the Fn key (no external scan code), but I may be able to figure something else out. Adding the Enter key to a non-extended/no-keypad keyboard is something that would be very helpful for many cross-over retro Mac enthusiasts.

Thanks again for your reply and helpful info - I really appreciate all the work on SheepShaver. It's great!
User avatar
Ronald P. Regensburg
Expert User
Posts: 7333
Joined: Thu Feb 09, 2006 10:24 pm
Location: Amsterdam, Netherlands

Re: Additional KeyCode Support...

Post by Ronald P. Regensburg »

The keycode files should indeed better be included with each build, especially since the January 2022 and later builds are incompatible with earlier keycode file versions.

Version 2.5 applies to all builds since SDL2 is used. SheepShaver and BasiliskII builds for all hosts (Windows, macOS, Linux) are identified by the build date. The developer does not distribute ready built binaries, so forum members (Cat_7 for Windows) compile from source for other forum members to use. But any user with more than average computer skills can compile his/her own build from source.

The keycodes download is from a secure server. I copied the old http address, but it is automatically redirected to the https address. I should have added the "s" in the link.

I am not sure what you mean with "keycode support for different configurations". The SheepShaver for Windows setup guide shows in a screenshot how to use the keycodes file. Normally, one only needs to use the keycodes file with other than US English keyboard layouts.

I will not distribute a separate keycodes file with access to an Enter key on a keyboard without Enter key. But if you tell me which key you want to sacrifice for an Enter key, I can tell you how to edit the keycodes file.

BTW: If you want to use Enter (not Return) in Windows, hoe do you do that on your laptop keyboard?
emendelson
Forum All-Star
Posts: 1476
Joined: Tue Oct 14, 2008 12:12 am

Re: Additional KeyCode Support...

Post by emendelson »

This little Windows utility (written in the AutoIt scripting language) will send Windows Keypad-Enter (= Mac Enter) to BasiliskII or SheepShaver if one of them is running (if both are running, it will send the keystroke to BasiliskII). To use it conveniently from the keyboard, create a desktop or start menu shortcut for it, and then assign a shortcut key to the shortcut (search the web for the method if necessary). For example, you could assign Ctrl-Shift-M to the utility, and then Ctrl-Shift-M will send Enter to BII or SS.

http://www.columbia.edu/~em36/KeyPadEnter.exe

If your browser gives you a 404 error, look in the address bar and make sure it says http:// and not https://

The program is code-signed, but many anti-malware programs will mistakenly flag any AutoIt-based software as dangerous, and your browser may warn you that the program is a security risk. If you don't trust the program, please don't waste your time asking if it's dangerous or not. Simply don't download it and don't use it.

Or download the AutoIt source code here, study the seven lines of code for potential security risks, and compile your own copy using AutoIt:

http://www.columbia.edu/~em36/KeyPadEnter.au3
User avatar
Ronald P. Regensburg
Expert User
Posts: 7333
Joined: Thu Feb 09, 2006 10:24 pm
Location: Amsterdam, Netherlands

Re: Additional KeyCode Support...

Post by Ronald P. Regensburg »

Not sure why one would make it unnecessary complex with an extra utility.

If the physical keyboard has a numeric pad with Enter key, there is no problem. The key will work in SheepShaver as Enter key.
If the physical keyboard does not have an Enter key, as is the case here, a different key can be assigned in the keycodes file to be the Enter key in SheepShaver.

Edit: For instance: As the control key is not much used in MacOS, the right control key could be assigned to be the Enter key.
emendelson
Forum All-Star
Posts: 1476
Joined: Tue Oct 14, 2008 12:12 am

Re: Additional KeyCode Support...

Post by emendelson »

Ronald P. Regensburg wrote: Sat Aug 06, 2022 8:31 pm Not sure why one would make it unnecessary complex with an extra utility.

If the physical keyboard has a numeric pad with Enter key, there is no problem. The key will work in SheepShaver as Enter key.
If the physical keyboard does not have an Enter key, as is the case here, a different key can be assigned in the keycodes file to be the Enter key in SheepShaver.

Edit: For instance: As the control key is not much used in MacOS, the right control key could be assigned to be the Enter key.
Yes, this is needlessly complex, and is completely needless with a full-size keyboard. It's only merit is that it works without editing the keycodes file.
InitCursor
Student Driver
Posts: 12
Joined: Tue Aug 02, 2022 7:09 pm

Re: Additional KeyCode Support...

Post by InitCursor »

1. If the 12-7-2022.zip SheepShaver file had included the keycodes, I would probably not be asking these questions. ;) Just letting you know so that you can fix this issue.
2. On Windows 11, the download was not secure and was flagged as an error/dangerous. So, if you feel your webserver should be redirecting to https and Isn't, it is likely because either your .htaccess file in the root site directory or the httpd.conf mod-rewrite declarations in /etc/httpd/conf (or thereabouts) are incorrect. I would not have reported this problem if mod_rewrite had properly redirected the url. Also, as you say, for modern browsers, it is a good idea to post links as https downloads for the most compatibility (whether or not there are back-end webserver issues with mod_rewrite).
3. If the intention is for SheepShaver to be transparent, self-documenting and to support Mac emulation for all users, then it would be very helpful to include some mention in keycodes of the Enter key issue for non-extended keyboards. Given that the keycode configurations are addressed by number in the preferences, it would also be helpful to add a "Custom" configuration at the end of the file so that users have a sandbox to add or change codes without changing the default configurations. For example, the "Custom" configuration could easily include the Enter key (with related explanation) for non-extended PC keyboards (many out in the world), especially on laptops.

Thanks for the help and replies.
User avatar
Ronald P. Regensburg
Expert User
Posts: 7333
Joined: Thu Feb 09, 2006 10:24 pm
Location: Amsterdam, Netherlands

Re: Additional KeyCode Support...

Post by Ronald P. Regensburg »

I have no influence on how the server works, it belongs to a major Dutch ISP. It was my fault to give a wrong link. The link without redirection is: https://ronaldpr.home.xs4all.nl/keycode ... y_2022.zip
(The browsers I normally use, Safari and Firefox on macOS, handle the "wrong" link with redirection graciously without warnings.)

I will ask Cat_7 to include the keycodes files in all January 2022 and later SheepShaver and BasiliskII for Windows downloads.

As far as I recall, you are the first one to ask for the Enter key in the 16 years that I am involved with these emulators here. I suppose most people use the Return key instead.

It is not possible to have more than one keyboard configuration in the keycodes files. SheepShaver and BasiliskII look for the matching driver string. The table following that string is used.

Editing the keycodes file is simple, it is just a plain text file and pretty much self-explanatory. But I can give you a custom keycodes file if you answer these two questions:
1. Is your keyboard an ANSI or ISO keyboard?
You can recognise the keyboard type by the shape of the Return key. On ANSI keyboards the key is a horizontal bar, on ISO keyboards the key has the shape of a "L" upside down.
2. Which key do you want to use as Enter key?

Or, alternatively, you can use emendelson's utility.
emendelson
Forum All-Star
Posts: 1476
Joined: Tue Oct 14, 2008 12:12 am

Re: Additional KeyCode Support...

Post by emendelson »

And which application makes different use of the Return and Enter keys? I've never encountered one...

And to add to what Ronald says, if you download my utility, you have to accept the warning about the insecure download. My university web server does not support https:// access for individual web sites. If you don't trust the software, no one is forcing you to use it.
InitCursor
Student Driver
Posts: 12
Joined: Tue Aug 02, 2022 7:09 pm

Re: Additional KeyCode Support...

Post by InitCursor »

1. Windows 11/Edge is not being redirected by the server and flags the non-secure download as suspect. There could be a webserver reality bubble or Edge issue, or it's just .htaccess and mod_rewrite. YMMV. See this image: Edge Warnings

2. Glad to hear the keycodes file will be included as standard from now on. It could also use a little more supportive documentation and a custom config would also be very helpful. I wasted time on this issue because of missing files and documentation -- preventable UX issues. And, it's still not working because I have taken time to explain the problem multiple times.

3. People can't "use the Return key instead," because it is a different key and doesn't work for the intended purpose, as we established earlier. There are plenty of modern PC keyboards that do not have a numeric keypad with (non-0x0d) Enter key in the lower right corner, including high-end laptops like the one I use. And, respectfully, whether or not it is in your experience to encounter a particular kind of request, instead of negating every point of valid feedback, telling users "it works for me," saying documentation is included that isn't, and asking "OMG, what app even does that?," you guys might want to consider being a little more open to relevant user/beta feedback. I like and appreciate this project, but the keycode issue is an important omission and warrants improvement, including, as above: remembering to include build artifacts, creating additional configs and improving the documentation -- especially if you want all users to be able to fully support their Mac emulation experience, which is the point of the project. The current minimalist definition could easily be expanded and the GUI.exe needs a better keycode tab to address all of these issues, including intuitive keyboard layout selection and key mappings, automatically detecting when the user doesn't have an extended keyboard and offering them common alternating mappings or configs.

4. The app in question is MPW - Macintosh Programmer's Workshop - the major software development platform for the Mac. So, who is the outlier here - me, or people who work on an emulator for the Mac for 16 years and are unaware of its major development tools? :P ;) Just kidding -- but try to expand your ecosystem understanding. Philosophically, it shouldn't matter which app it is, the engineering challenge is to provide full emulation support without self-limited or omitted use case definitions so that there is built-in, intuitive flexibility for all users.

In the case of MPW, you can click on the MPW text in the upper left to execute shell commands and I added the control strip module. I will figure out how to get the key working so that I don't have to click.

5. It would be a very good idea to get a formal web domain for your combined projects and all of its related downloads, get a free certificate from Let's Encrypt, and correctly configure it for https delegation. It would make everything much more discoverable and manageable. Hosting has minimal cost and, given the number of SS/Basilisk users, it would be easy to fund - or find a corporate or academic sponsor. Ask Apple, Ask Google, Ask Columbia (maybe they would offer you dedicated domain hosting vs. columbia.edu/x... etc. Apple might even want to participate and release historical images, artifacts, developer tools, documentation, etc. directly to your downloads area (instead of getting them from who knows where with multiple kinds of file formats and compression...or versions of that compression, if the files even work or were properly encoded). It's very problematic and is begging for community standardization. Stop limping along in a fragmented, insecure, gum-and-bailing-wire, 3-wheeled jalopy of content delivery.

Thanks for the help and suggestions. I'll figure it out from here.
User avatar
Ronald P. Regensburg
Expert User
Posts: 7333
Joined: Thu Feb 09, 2006 10:24 pm
Location: Amsterdam, Netherlands

Re: Additional KeyCode Support...

Post by Ronald P. Regensburg »

The keycodes file is normally only needed for users that use other than US-English keyboard layouts. How to enable it is explained in the setup guide. The ReadMe with the keycodes files mentions one situation in which the keycodes file needs to be edited.

You have a specific need for an Enter key in the emulator while using a keyboard without Enter key.
You can use emendelson's utility or you can ask me for a custom keycodes file. For the custom keycodes file I will need answers to the two questions I asked above.
InitCursor
Student Driver
Posts: 12
Joined: Tue Aug 02, 2022 7:09 pm

Re: Additional KeyCode Support...

Post by InitCursor »

Thanks. I appreciate the offer, but do not need a custom keycode file or a special utility. I fixed the issue with the existing keycode file.

From the user beta-feedback perspective, this functionality is not well-explained and needs a more user-friendly implementation, including better integration in the GUI launcher.
RPR wrote:You have a specific need for an Enter key in the emulator while using a keyboard without Enter key.
Correct -- and any user who wants to customize their keycodes needs to use this feature, not just ones who have a non-US English keyboard.

Also, there is a bug/programming assumption that limits users' ability to customize this file/feature. SheepShaver is assuming that there will only be, at most, 1 configuration with each unique or applicable driver name. I copied/pasted a template config, made my custom config for the Enter Key as R-CTRL, and added it as the 6th configuration.

However, in SheepShaver_prefs, despite explicitly declaring:

Code: Select all

keyboardtype 6
SheepShaver.exe wouldn't use it because it had a duplicate "windows" driver name.

So, instead of using the user-declared configuration from prefs, SheepShaver is defaulting to the first valid configuration or matching driver name it finds among the existing/declared configs (or the first 5 -- that I wanted to leave unmodified in case I want to revert, etc.). In order to make config 6 work, I had to comment out "windows" so that the driver declared in my config was not duplicated in the earlier one. SheepShaver shouldn't care how many times a driver is redeclared in a config and should respect the user preference entry. (And, I'm still not sure if it's actually using my preference choice or just using the one with the only matching driver.)

Execution should probably go something like this:
1. Check user prefs and select keycode config, if valid.
2. If not valid/no matching driver, then fall back to the best-fit/valid configuration
3. Log an error and throw a Mac dialog at startup saying "The user-specified keycode configuration in SheepShaver_prefs could not be used because: [reason]. Configuration [n] was used instead. Check the keycodes file and correct the error."

Please fix this issue so that SheepShaver respects the user-selected preference, regardless of any driver name duplication.

Otherwise, I now have a working Mac Numeric Keypad Enter Key. I wish this process had been easier.
User avatar
Ronald P. Regensburg
Expert User
Posts: 7333
Joined: Thu Feb 09, 2006 10:24 pm
Location: Amsterdam, Netherlands

Re: Additional KeyCode Support...

Post by Ronald P. Regensburg »

We use the SS/BII fork by developer kanjitalk755. I suggest that you contact him. Maybe you can contribute by developing yourself the changes you suggest and then open a pull request. https://github.com/kanjitalk755/macemu
InitCursor
Student Driver
Posts: 12
Joined: Tue Aug 02, 2022 7:09 pm

Re: Additional KeyCode Support...

Post by InitCursor »

Ronald P. Regensburg wrote: Tue Aug 09, 2022 7:59 am I am the one who maintains the keycode files for the latest SDL2 builds with SDL2 scancode to Mac keycode translations.
As an integral maintainer for the project/keycode functionality and a global mod for the support forum, it would be great if you could flag the code author and add it to the db.
User avatar
Ronald P. Regensburg
Expert User
Posts: 7333
Joined: Thu Feb 09, 2006 10:24 pm
Location: Amsterdam, Netherlands

Re: Additional KeyCode Support...

Post by Ronald P. Regensburg »

Personally, I do not see the need to make the adjustments you suggest. It would be useful only for the very few, so far only you, who need a true Enter key on a limited keyboard. Simple editing of the keycodes file can provide a solution.

Note:
1. The keyboardtype setting only affects the keyboard shown in Key Caps application. It does not affect the keyboard behaviour.
2. The keycodes file can have only one entry for each driver string, as you noticed.
3. The emulator looks for only one specific driver string.
(The sdl cocoa/sdl windows/sdl x11 strings are for the current SDL2 versions. All other strings match other/older versions of BII/SS and are left in the file for backward compatibility.)

This would all need to be changed.

I will point out this topic to kanjitalk755. He is a forum member.
kanjitalk755
Apple Corer
Posts: 218
Joined: Thu Nov 09, 2017 12:06 pm

Re: Additional KeyCode Support...

Post by kanjitalk755 »

I would suggest using the --config command line option to switch between preference files with different "keycodefiles".
User avatar
Ronald P. Regensburg
Expert User
Posts: 7333
Joined: Thu Feb 09, 2006 10:24 pm
Location: Amsterdam, Netherlands

Re: Additional KeyCode Support...

Post by Ronald P. Regensburg »

Yes, thank you. I did not think of that possibility although it is mentioned in the SheepShaver for Windows setup guide:
Start SheepShaver with the argument --config prefs_file_name
InitCursor
Student Driver
Posts: 12
Joined: Tue Aug 02, 2022 7:09 pm

Re: Additional KeyCode Support...

Post by InitCursor »

Or...just fix the buggy implementation so that users can add custom keycodes templates and indicate them with a simple number in the common prefs. Users shouldn't have to switch out the entire prefs file just to get a simple keycode change. And, little would have to be changed. If the user declares the pref, use it, otherwise, use the default mode (instead of ignoring the user-selected preferences and making hard-coded assumptions about unique driver identification). If the user declares a preference, why should the app care about unique driver identification?

Or in other words:
CHECK PREF USING EXISTING PREF-CHECKING CODE
IF EXISTS, LOAD USER-DEFINED SELECTION
IF DRIVER MISMATCH, THROW ERROR DIALOG AND RUN DEFAULT
IF NO PREF, RUN DEFAULT
Post Reply