003 info plist

A Detailed Disscussion on the Information Property List

Information Property List (Info.plist) plays a key role to make system to recognize your input sources.

At this time we are going to build a new input method or input mode quickly. Thus, for keyboard layout properties, we may discuss later.

Summary

If you are going to fast deploy your input method, check these 5 keys that required by IMKServer.init(name:bundleIdentifier:):

• LSBackgroundOnly
• InputMethodConnectionName
• InputMethodServerControllerClass
• tsInputMethodIconFileKey
• tsInputMethodCharacterRepertoireKey

Prefixes

• IMK: InputMethodKit properties
• TIS: TextInputSources properties
• ts: Text Services Manager properties

TextInputSources Properties

The following properties can be defined for any kinds of input sources.

TICapsLockLanguageSwitchCapable

Type: Boolean
Optional

The capability of the input source to switch the input language to and from Latin script with Caps Lock.

A checkbox about this feature can be found in "System Preferences - Keyboard - Input Sources".

TISCapsLockIsSwitch

Type: Boolean
Optional

Set to 1 if the input source will accept the Caps Lock key for switching to other input sources.

TISCapsLockResetOnModeSwitch

Type: Boolean
Optional

Set to 1 if the the Cpas Lock status will be reset when the input source is switched.

TISDoubleSpaceSubstitution

Type: String
Optional

A substitute string when the user input double space, with the feature "Add period with double-space" on in "System Preferences - Keyboard - Text".

TISIconIsTemplate

Type: Boolean
Optional

If unset or set to false, the icon file is used as is.

If set to true, the icon file is treated as a template that the system will automatically help change the color for light and dark modes; also an alternative way to have the icon change the color when focusd, without setting tsInputMethodAlternateIconFileKey.

TISInputSourceID

Type: String
Optional

The InputSourceID, a reverse-DNS-style string meant to uniquely identify any input sources.

If not specified, it will be constructed via the following rules:

• Keyboard layout: BundleID + ". keylayout." + keylayoutname
• Input method: BundleID
• Input mode: BundleID + suffix(InputModeID)

where suffix deletes any prefix that matches the BundleID or that ends in .inputmethod..

TISIntendedLanguage

Type: String
Optional

The language that the input source is intended to input.

The string is the language code in the format described by BCP 47.

TISParticipatesInTouchBar

Type: Boolean
Optional

Whether the input source allow the user to use the Touch Bar for candidate selection.

Input Method Properties

The input method properties are supposed to be defined on the top-most level in the Info.plist file.

ComponentInputModeDict

Type: Dictionary
Optional

Two keys are supported in this dictionary: tsInputModeListKey and tsVisibleInputModeOrderedArrayKey.

If you are not going to deploy input modes, omit this.

Details described below.

IMKExtensionDelegateClass

Type: String

The name of an extension delegate class.

Found this in system Japanese input method, not knowing usage.

InputMethodConnectionName

Type: String

IMK uses this name to create an NSConnection object for the client-server connection.

A convention of this name is adding suffix _Connection, not required.

Make sure you use the same name when initializing the IMKServer object.

InputMethodServerControllerClass

InputMethodServerDelegateClass

InputMethodServerDataSourceClass

Type: String
Optional

The name of a class.

Accepts any strings, even the class cannot be found.

Usually the name of a class that inherits from IMKInputController class for InputMethodServerControllerClass.

The other two keys seems optional, found in some system input methods, always the same value of InputMethodServerControllerClass. We never know anything else about those.

Have tried to use the same class for IMKServer.init(name:controllerClass:delegateClass:) but failed.

Special Notes:

If you have suffered that your controller class does nothing, add $(PRODUCT_MODULE_NAME). to form the class name as $(PRODUCT_MODULE_NAME).YourInputControllerClass.

This usually due to the new project layout template of Xcode. Traditional Objective-C projects put the Info.plist file and the ControllerClass definition file at the root of the project, so that there is no need to add any prefix.

LSBackgroundOnly

Type: Boolean

Always set to 1, because input methods are background-only applications.

tsInputMethodCharacterRepertoireKey

Type: Array of String

Apple says this is a list of ISO language codes help categorize the input method to the user. However, I found system input methods use ISO script codes (ISO 15924).

tsInputMethodIconFileKey

Type: String

The filename in the bundle or full path to the icon resource. Accepts TIFF and .icns (Apple Icon Image format), as well as PDF that I found some projects using.

tsInputMethodAlternateIconFileKey

Type: String
Optional

Same as tsInputMethodIconFileKey majorly. The icon is used when the user clicks the icon in the menu bar.

Can be the same value as tsInputMethodIconFileKey.

tsInputMethodPaletteIconFileKey

Type: String
Optional

Usage not known yet.

The ComponentInputModeDict

In modern times, Apple introduced some extra keys for this dictionary.

tsInputModeListKey

Type: Dictionary

This is the mandatory key for describing a list of the input modes.

Every entry has its key the identifier of the input mode (InputModeID) and its value a dictionary of its input mode properties.

tsVisibleInputModeOrderedArrayKey

Type: Array of String
Optional

Every item in this list is InputModeID defined in tsInputModeListKey. The order of the items in this list is the order of the input modes listed in "System Preferences".

---

Extra Properties

TISUnifiedUIForInputMethodEnabling

Type: Boolean
Optional

If set to 1, all the input modes of this input method will be enabled or disabled once any one of them is enabled or disabled.

On "System Preferences - Keyboard - Input Sources", you can see only the input method instead of list all modes separately. You are supposed to make you UX for enabling or disabling any one of the input modes.

If set tsInputModePrimaryInScriptKey true for a input mode, it will not be disabled.

Input Mode Properties

TISIconLabels

Type: Dictionary
Optional

Found in some system input methods, not sure what it is. Usually only one entry with key "Primary" and the value is the character on the icon image.

I have tried to use VoiceOver to read the icon, but VoiceOver read nothing.

I do not know if this field can be a universal TextInputSource property.

tsInputModeCharacterRepertoireKey

Type: Array of String
Optional

Same as tsInputMethodCharacterRepertoireKey for input modes.

tsInputModeDefaultStateKey

Type: Boolean

Set to 1 if you want to make the input mode enabled by default when the input method is enabled.

Only one input mode have this property set to 1 is recommended.

tsInputModeIsVisibileKey

Type: Boolean
Optional

If the input mode is not visible, it will not show up in the menu.

tsInputModeJISKeyboardShortcutKey

Type: Integer Optional

Shortcut key on JIS keyboards for the input mode.

Not know more about it yet. Just found in system Japanese input method.

tsInputModeKeyEquivalentKey

Type: String
Optional

A key to quickly switch to this input mode. Usually ASCII characters, case insensitive.

More than one characters will be trim to the first one.

tsInputModeKeyEquivalentModifiersKey

Type: Integer
Optional

Usually with tsInputModeKeyEquivalentKey, adding modifier keys for the keyboard shortcut.

Even other values are accepted, they are useless.

Combine the keys by adding their values.

Modifier Key	value	bit# (0 for right-most)
Command (⌘)	256	8
Shift (⇧)	512	9
Option (⌥)	2048	11
Control (⌃)	4096	12

tsInputModePrimaryInScriptKey

Type: Boolean

Set to 1 if the input method is the primary input method for the script.

At most one should be marked as primary.

tsInputModeScriptKey

Type: String

Input modes are assigned a Mac ScriptCode.

See this header file for full list of ScriptCode (usually the word start with sm):

<SDKFolder>/MacOSX<version>.sdk/System/Library/Frameworks/CoreServices.framework/Versions/A/Frameworks/CarbonCore.framework/Versions/A/Headers/Script.r

tsInputModeMenuIconFileKey

Type: String

Same as tsInputMethodAlternateIconFileKey for input modes.

tsInputModeAlternateMenuIconFileKey

Type: String
Optional

Same as tsInputMethodAlternateIconFileKey for input modes.

Although some tech notes say that this key is required, system input methods do not use this key.

tsInputModePaletteIconFileKey

Type: String
Optional

Same as tsInputMethodPaletteIconFileKey for input modes.

Examples

Input Method Only

<plist version="1.0">
    <dict>
        <key>InputMethodConnectionName</key>
        <string>MyInputMethod_Connection</string>
        <key>InputMethodServerControllerClass</key>
        <string>$(PRODUCT_MODULE_NAME).MyInputMethodController</string>
        <key>LSBackgroundOnly</key>
        <true />
        <key>TICapsLockLanguageSwitchCapable</key>
        <true />
        <key>TISIconIsTemplate</key>
        <true />
        <key>TISIntendedLanguage</key>
        <string>zh</string>
        <key>TISParticipatesInTouchBar</key>
        <true />
        <key>tsInputMethodCharacterRepertoireKey</key>
        <array>
            <string>Hans</string>
            <string>Hant</string>
        </array>
        <key>tsInputMethodIconFileKey</key>
        <string>my_icon.tiff</string>
    </dict>
</plist>

Input Method with A List of Input Modes

<plist version="1.0">
    <dict>
        <key>ComponentInputModeDict</key>
        <dict>
            <key>tsInputModeListKey</key>
            <dict>
                <key>com.example.inputmethod.YourInputMode_1</key>
                <dict>
                    <key>TISDoubleSpaceSubstitution</key>
                    <string>。</string>
                    <key>TISIntendedLanguage</key>
                    <string>zh-Hans</string>
                    <key>tsInputModeCharacterRepertoireKey</key>
                    <array>
                        <string>Hans</string>
                    </array>
                    <key>tsInputModeIsVisibleKey</key>
                    <true />
                    <key>tsInputModeMenuIconFileKey</key>
                    <string>my_icon1.tiff</string>
                    <key>tsInputModePrimaryInScriptKey</key>
                    <true />
                    <key>tsInputModeScriptKey</key>
                    <string>smSimpChinese</string>
                </dict>
                <key>com.example.inputmethod.YourInputMode_2</key>
                <dict>
                    <key>TISDoubleSpaceSubstitution</key>
                    <string>。</string>
                    <key>TISIntendedLanguage</key>
                    <string>zh-Hant</string>
                    <key>tsInputModeCharacterRepertoireKey</key>
                    <array>
                        <string>Hant</string>
                    </array>
                    <key>tsInputModeIsVisibleKey</key>
                    <true />
                    <key>tsInputModeMenuIconFileKey</key>
                    <string>my_icon2.tiff</string>
                    <key>tsInputModePrimaryInScriptKey</key>
                    <false />
                    <key>tsInputModeScriptKey</key>
                    <string>smTradChinese</string>
                </dict>
            </dict>
            <key>tsVisibleInputModeOrderedArrayKey</key>
            <array>
                <string>com.example.inputmethod.YourInputMode_1</string>
                <string>com.example.inputmethod.YourInputMode_2</string>
            </array>
        </dict>
        <key>InputMethodConnectionName</key>
        <string>MyInputMethod_Connection</string>
        <key>InputMethodServerControllerClass</key>
        <string>$(PRODUCT_MODULE_NAME).MyInputMethodController</string>
        <key>LSBackgroundOnly</key>
        <true />
        <key>TICapsLockLanguageSwitchCapable</key>
        <true />
        <key>TISIconIsTemplate</key>
        <true />
        <key>TISIntendedLanguage</key>
        <string>zh</string>
        <key>TISParticipatesInTouchBar</key>
        <true />
        <key>tsInputMethodCharacterRepertoireKey</key>
        <array>
            <string>Hans</string>
            <string>Hant</string>
        </array>
        <key>tsInputMethodIconFileKey</key>
        <string>my_icon.tiff</string>
    </dict>
</plist>