Keyboard

Enhanced keyboard and IME diagnostics tool

Starting with version 2411, a new self-service command-line tool hosted in Windows Virtual Delivery Agent (VDA) is supported by Citrix Workspace app for Mac to diagnose keyboard and Input Method Editor (IME) related issues. This tool meets various user requirements, provides platform versatility, and caters to personalized needs. The keyboard and IME functions depend on different configurations and capabilities in VDAs and Citrix Workspace apps. Incorrect settings in the VDA or client side might result in unexpected input behavior.

With this tool, you can easily identify issues that were previously difficult to find.

• Checks for consistency between VDA policy and client keyboard layout sync mode.
• Checks for client keyboard layout and VDA keyboard layout, and provides best practices.
• Checks the remote language bar setting and provides best practices.
• Checks system shortcut pass-through configurations, accessibility permissions, and full screen mode status to suggest best practices.

Prerequisites:

• Citrix Workspace app for Mac 2411 or higher.
• Virtual Delivery Agent 2411 or higher.

The command line tool is hosted in Windows VDA as CtxKbImeDiagnostics.exe. The interfaces are as follows:

Keyboard layout synchronization

Keyboard layout synchronization enables you to switch between the preferred keyboard layouts on the client device. This feature is disabled by default. After you enable this feature, the client keyboard layout automatically synchronizes to the virtual apps and desktops.

To enable keyboard layout synchronization, go to Preferences > Keyboard and select “Use local keyboard layout, rather than the remote server keyboard layout.”

Note:

1. Using the local keyboard layout option activates the client IME (Input Method Editor). Users working in Japanese, Chinese, or Korean can use the server IME. They must disable the local keyboard layout option by clearing the option in Preferences > Keyboard. The session will revert to the keyboard layout provided by the remote server when they connect to the next session.
2. The feature works in the session only when the toggle in the client is turned on and the corresponding feature enabled on the VDA. A menu item,”Use Client Keyboard Layout,” in Devices > Keyboard > International is added to show the enabled state.

Starting with version 2210, Citrix Workspace app for Mac supports three different keyboard layout synchronization modes:

• Sync only once - when session starts – Based on the CTXIME value in the Config file, the client keyboard layout is synchronized to the server when the session launches. Any changes you make to the client keyboard layout during the session do not take effect immediately. To apply the changes, sign out and sign in to the app. The Sync only once - when session starts mode is the default keyboard layout for the Citrix Workspace app on Mac.

• Allow dynamic sync - This option synchronizes the client keyboard layout to the server when you change the client keyboard layout.

• Don’t sync - Indicates that the client uses the keyboard layout present on the server.

Prerequisites

• Enable the Unicode Keyboard Layout Mapping feature on the Windows VDA. For more information, see Knowledge Center article CTX226335.

• Enable the Dynamic Keyboard layout sync feature on the Linux VDA. For more information, see Dynamic keyboard layout synchronization.

• When using Windows Server 2016 or Windows Server 2019, navigate to the HKEY_LOCAL_MACHINE\Software\Citrix\ICA\IcaIme registry path and add a DWORD value with the key name DisableKeyboardSync and set the value to 0.

Configure keyboard layout

Citrix Workspace app for Mac provides the UI to configure the three different keyboard layout synchronization modes.

To configure keyboard layout synchronization using the GUI:

1. From the Citrix Workspace app icon in the menu bar, click the account icon in the top-right corner and navigate to Preferences > Keyboard.

   The Keyboard layout synchronization settings appear.

2. Select from one of the following options:

   • Sync only once - when session starts - Indicates that the keyboard layout is synced to the VDA only once at the session launch. Unicode keyboard input mode is the recommended option for the Sync only once – when the session starts
   • Allow dynamic sync - Indicates that the keyboard layout is synced dynamically to the VDA when the client keyboard is changed in a session. Unicode keyboard input mode is the recommended option for the Allow dynamic sync mode.
   • Don’t sync - Indicates that the client uses the keyboard layout present on the server, irrespective of the keyboard layout that is selected in the client. Scancode keyboard input mode is the recommended option for Don’t sync. You must make sure that the client keyboard layout is the same as the keyboard layout on the VDA if you select Unicode for the Don’t Sync option.

Limitations

• Using the keyboard layouts listed in “Supported Keyboard Layouts in Mac” works while using this feature. When you change the client keyboard layout to a non-compatible layout, the layout might be synced on the VDA side, but functionality can’t be confirmed.

• Remote apps that run with elevated privileges can’t be synchronized with the client keyboard layout. To work around this issue, manually change the keyboard layout on the VDA or disable UAC.

• When a user is working within an RDP session, it’s not possible to change the keyboard layout using the Alt + Shift shortcuts when RDP is deployed as an app. As a workaround, you can use the language bar in the RDP session to switch the keyboard layout.

Keyboard layout support for Windows VDA

Keyboard layout support for Linux VDA, Swiss French

By default, the keyboard layout synchronization feature is turned on. To control this feature alone, open the Config file in the ~/Library/Application Support/Citrix Receiver/ folder, locate the “EnableIMEEnhancement” setting and turn the feature on or off by setting the value to “true” or “false,” respectively.

Note:

The setting change takes effect after restarting the session.

Keyboard input mode enhancements

Citrix Workspace app for Mac provides the UI to configure the keyboard input mode.

To configure keyboard input mode by using the GUI, do the following:

1. From the Citrix Workspace app icon in the menu bar, click the account icon in the top-right corner and navigate to Preferences > Keyboard.

   The Keyboard input mode settings appear

2. Select from one of the following options:

   • Scancode – Sends the key position from the client-side keyboard to VDA and VDA generates the corresponding character. Applies server-side keyboard layout.
   • Unicode - Sends the key from the client-side keyboard to VDA and VDA generates the same character in VDA. Applies client-side keyboard layout.

This enhancement is enabled by default.

For example, consider a scenario where you’re using a US international keyboard layout and the VDA is using the Russian keyboard layout. When you choose Scancode and type the key next to Caps Lock, the scancode “1E” is sent to the VDA. The VDA then uses “1E” to display the character “ф”. If you choose Unicode and type the key next to Caps Lock, the character “a” is sent to the VDA. So, even if the VDA uses the Russian keyboard layout, the character “a” appears on the screen.

Citrix recommends the following keyboard input mode for the different keyboard layout sync options:

• Scancode mode for Don’t Sync option.

• Unicode mode for Allow dynamic sync and Sync only once - when session starts

Note:

The keyboard configuration changes take effect once you reconnect to the application.

You can change the configuration of Keyboard input mode in the Citrix Workspace app UI. However, for best performance, use the Citrix-recommended modes for different scenarios, physical keyboards, and client devices.

Language bar

You can choose to show or hide the remote language bar in an application session using the GUI. The language bar displays the preferred input language in a session. In earlier releases, you might change this setting using only the registry keys on the VDA. Starting with Citrix Workspace for Mac version 1808, you can change the settings using the Preferences dialog. The language bar appears in a session by default.

Note:

This feature is available in sessions running on VDA 7.17 and later.

Configure showing or hiding the remote language bar

1. Open Preferences.
2. Click Keyboard.
3. Click or unclick Show the remote language bar for the published applications.

Note:

The setting changes take effect immediately. You can change the settings in an active session. The remote language bar does not appear in a session if there’s only one input language.

Support synchronization for more keyboard layouts

Starting with the 2304 version, Citrix Workspace app for Mac supports keyboard layout synchronization for the following layouts or Input Method Editors (IMEs):

• English ABC
• English ABC - India
• Chinese, Traditional: Zhuyin - Traditional
• Chinese, Traditional: Sucheng - Traditional
• Google Japanese IME
• Sougou Chinese IME

Support for non-English-language Input Method Editors (IME) keyboard layouts

Support for non-English language IME keyboard layouts continues to work uninterrupted after the Carbon APIs are deprecated with the Cocoa APIs.

Windows special keys

Citrix Workspace app for Mac provides several options and easier ways to substitute special keys such as function keys in Windows applications with Mac keys. Use the Keyboard tab to configure the options you want to use, as follows:

• Send Control character using: Lets you choose whether to send Command-character keystroke combinations as Ctrl+character key combinations in a session. Select “Command or Control” from the pop-up menu to send familiar Command-character or Ctrl-character keystroke combinations on the Mac as Ctrl+character key combinations to the PC. If you select Control, you must use Ctrl-character keystroke combinations.
• Send Alt character using: Lets you choose how to replicate the Alt key within a session. If you select Command-Option, you can send Command-Option and keystroke combinations as Alt+ key combinations within a session. Alternatively, if you select Command, you can use the Command key as the Alt key.
• Send Windows logo key using Command (right): Lets you send the Windows logo key to your remote desktops and applications when you press the Command key on the right side of the keyboard. If this option is disabled, the right Command key has the same behavior as the left Command key according to the above two settings in the preferences panel. However, you can still send the Windows logo key using the Keyboard menu; choose Keyboard > Send Windows Shortcut > Start.
• Send special keys unchanged: Lets you disable the conversion of special keys. For example, the combination Option-1 (on the numeric keypad) is equivalent to the special key F1. You can change this behavior and set this special key to represent 1 (the number one on the keypad) in the session. To do this, select the “Send special keys unchanged” checkbox. By default, this checkbox isn’t selected so Option-1 is sent to the session as F1.

You send the function and other special keys to a session using the Keyboard menu.

If your keyboard includes a numeric keypad, you can also use the following keystrokes:

Windows shortcuts and key combinations

Remote sessions recognize most Mac keyboard combinations for text input, such as Option-G to input the copyright symbol ©. Some keystrokes you make during a session, however, do not appear on the remote application or desktop. The Mac operating system interprets them. This can result in keys triggering Mac responses instead.

You might also want to use certain Windows keys, such as Insert, that many Mac keyboards do not have. Similarly, some Windows 8 keyboard shortcuts display charms and app commands, and snap and switch apps. Mac keyboards do not mimic these shortcuts. However, these can be sent to the remote desktop or application using the Keyboard menu.

Keyboards and the ways keys are configured can differ widely between machines. Citrix Workspace app for Mac therefore offers several choices to ensure that keystrokes can be forwarded correctly to hosted applications and desktops. These keystrokes are listed in the table. The default behavior is described. If you adjust the defaults (using the Citrix Workspace app or other preferences), different keystroke combinations might be forwarded and other behavior might be observed on the Remote PC Access.

Important

Certain key combinations listed in the table aren’t available when using newer Mac keyboards. In most of these cases, keyboard input can be sent to the session using the Keyboard menu.

Conventions used in the table:

• Letter keys are capitalized and do not imply that the Shift key must be pressed simultaneously.
• Hyphens between keystrokes indicate that keys must be pressed together (for example, Control-C).
• Character keys create text input and include all letters, numbers, and punctuation marks. Special keys do not create input by themselves but act as modifiers or Controllers. Special keys include Control, Alt, Shift, Command, Option, arrow keys, and function keys.
• Menu instructions relate to the menus in the session.
• Depending on the configuration of the user device, some key combinations might not work as expected, and alternative combinations are listed.
• Fn refers to the Fn (Function) key on a Mac keyboard. The function key refers to F1 to F12 on either a PC or Mac keyboard.

Use Input Method Editors (IME) and international keyboard layouts

Citrix Workspace app for Mac allows you to use an Input Method Editor (IME) on either the user device or on the server.

When client-side IME is enabled, users can compose text at the insertion point rather than in a separate window.

Citrix Workspace app for Mac also allows users to specify the keyboard layout they want to use.

To enable client-side IME

1. From the Citrix Viewer menu bar, choose Keyboard > International > Use Client IME.
2. Ensure that the server-side IME is set to direct input or alphanumeric mode.
3. Use the Mac IME to compose text.

To indicate explicitly the starting point when composing text

• From the Citrix Viewer menu bar, choose Keyboard > International > Use Composing Mark.

To use server-side IME

• Ensure that the client-side IME is set to alphanumeric mode.

Mapped server-side IME input mode keys

Citrix Workspace app for Mac provides keyboard mappings for server-side Windows IME input mode keys that aren’t available on Mac keyboards. On Mac keyboards, the Option key is mapped to the following server-side IME input mode keys, depending on the server-side locale:

To use international keyboard layouts

• Ensure both client-side and server-side keyboard layouts are set to the same locale as the default server-side input language.

Restore default keyboard settings

If you had previously modified the keyboard preferences in the Citrix Workspace app, you can now restore the default keyboard settings. To restore the keyboard settings to its default values, open the Citrix Workspace app and navigate to Preferences > Keyboard. Then, click Restore Defaults and click Yes to confirm.

Deprecation of International menu from the keyboard settings

Previously, you can enable or disable the Use Client IME, Use Composing Mark and Use Client keyboard layout features in the Citrix viewer by navigating to Devices > Keyboard>International.

From the 2311 version, the International menu for the keyboard settings in the Citrix Viewer is deprecated. From this version, the client-side IME is enabled by default.

Support for system shortcuts on HDX desktop sessions

Previously, the system keyboard shortcuts such as Option-Command-ESC, Command-Space bar, Command-Tab, Control-Command-Q, Shift-Command-Q, Control Up/Down/Left/Right took effect only on macOS locally since they were consumed by macOS at first.

Starting with the 2402 version, Citrix Workspace app for Mac supports passing the macOS system keyboard shortcuts to the VDA (HDX session) in window mode and full-screen mode. This feature allows you to set preferences on how the system shortcut must take effect on macOS locally or the HDX desktop session in window or full-screen mode.

The following options in the keyboard settings allow you to control the system shortcuts:

• Local device: The system shortcuts can take effect only on macOS locally. It does not affect the HDX session. The Local device option is the default option.

• Fullscreen HDX session only: The system shortcuts take effect on HDX sessions when the session is in full-screen mode. If the session is in window mode or there are no active sessions, then the system shortcuts have no effect on HDX sessions.

• Active HDX session: The system shortcuts take effect on HDX sessions when the session is in window mode and full-screen mode. If there is no active HDX session or the active session window on the front, then the system shortcuts can take effect only on the macOS locally.

To enable the system shortcuts to take effect on the HDX session, open the HDX session. In the Citrix Viewer menu bar, navigate to Devices > Keyboard > System shortcuts take effect on and select Fullscreen HDX session only or Active HDX session.

Note:

When enabling system shortcuts for HDX sessions, you are prompted to provide accessibility access to Citrix Viewer to use this feature. To provide accessibility access to Citrix Viewer, click Open System Settings in the dialog box and enable accessibility access to Citrix Viewer. For more information, see Allow accessibility apps to access your Mac in the Apple support article.

Alternatively, you can enable the system shortcuts to take effect on HDX sessions in full-screen or window mode by navigating to Preferences > Keyboard. Select Fullscreen HDX session only or Active HDX session options from the System shortcuts take effect on drop-down menu.

Enhancement to the keyboard Settings

Starting with the 2405 version, Citrix Workspace app now provides an improved keyboard settings user interface (UI) by categorizing setting options and adding helpful tip icons.

The following settings are now available as secondary options under the Unicode input mode setting:

• Send Control character using
  • This setting specifies an alternative key to act as the Control key (often used for shortcuts like Ctrl+C for copy) within the virtual session. On different keyboards or operating systems, the Control key might be in different locations, so this setting allows customization to maintain consistency for a better user experience.
• Send Alt character using
  • This setting specifies which key can act as the Alt key (used for accessing alternate functions of keys, like Alt+Tab for switching windows).
• Send Windows logo key using Command (right)
  • This setting specifies the right Command key on a Mac keyboard to function as the Windows logo key. This setting is particularly useful for macOS users who use the Command key frequently but need the functionality of the Windows logo key when using Windows or applications that recognize it.
• Send special keys unchanged (press Command (left) for some keys)
  • This setting keeps certain special keys (like function keys, escape, etc.) unchanged in their function, except when the left Command key is pressed. It allows for a hybrid approach where the default behavior of special keys is retained, but pressing the left Command key modifies their behavior if needed.