Components All New MacOS Windows Linux iOS
Examples Mac & Win Server Client Guides Statistic FMM Blog Deprecated Old

HotKey.Register

Registers a global hot key based on the virtual key code and modifiers.

Component Version macOS Windows Linux Server iOS SDK
HotKey 5.0 ✅ Yes ✅ Yes ❌ No ❌ No ❌ No
MBS( "HotKey.Register"; Code; Modifiers { ; Exclusive; FileName; ScriptName; Local; Name; Tag } )   More

Parameters

Parameter Description Example Flags
Code The virtual key code of the key to watch. Can be number or name of key. "F5"
Modifiers The keyboard modifiers to look for. Can be number of text. Text can include command, shift, alpha, option and control.
Added in 6.2 for Windows: RightShift, RightOption and RightControl.
"control"
Exclusive Pass 1 to register exclusive or 0 for non exclusive. 0 Optional
FileName The database file name where the script is located. "test.fmp12" Optional
ScriptName The script name. "MyScript" Optional
Local Pass 1 to have hotkey only run script if FileMaker is frontmost. Else pass 0 (default) to have a global hotkey. 0 Optional
Name The name for the hotkey.
e.g. you can use this property to later decide in a script what to do.
"Test Hotkey" Optional
Tag The tag for the hotkey.
e.g. you can use this property to later decide in a script what to do.
Optional

Result

Returns reference or error.

Description

Registers a global hot key based on the virtual key code and modifiers.
Only one such combination can exist for the current application, i.e. multiple entities in the same application cannot register for the same hot key combination. The same hot key can, however, be registered by multiple applications. This means that multiple applications can potentially be notified when a particular hot key is requested.
You can request exclusive registration for your process by passing 1 for exclusive parameter.
Please use HotKey.SetScript to assign a script for the hotkey or use parameters here.

Added Windows support with version 5.2.

MacOS key codes we map for you:
Return, Tab, Space, Delete, Escape, Command, Shift, CapsLock, Option, Control, RightShift, RightOption, RightControl, Function, F17, VolumeUp, VolumeDown, Mute, F18, F19, F20, F5, F6, F7, F3, F8, F9, F11, F13, F16, F14, F10, F12, F15, Help, Home, PageUp, ForwardDelete, F4, End, F2, PageDown, F1, LeftArrow, RightArrow, DownArrow, UpArrow, Left, Right, Down, Up, A, S, D, F, H, G, Z, X, C, V, B, Q, W, E, R, Y, T, 1, 2, 3, 4, 6, 5, Equal, 9, 7, Minus, 8, 0, RightBracket, O, U, LeftBracket, I, P, L, J, Quote, K, Semicolon, Backslash, Comma, Slash, N, M, Period, Grave, KeypadDecimal, KeypadMultiply, KeypadPlus, KeypadClear, KeypadDivide, KeypadEnter, KeypadMinus, KeypadEquals, Keypad0, Keypad1, Keypad2, Keypad3, Keypad4, Keypad5, Keypad6, Keypad7, Keypad8, Keypad9.

Windows key codes we map for you:
0, 1, 2, 3, 4, 5, 6, 7, 8, 9, A, B, C, D, E, F, G, H, I, J, K, L, M, N, O, P, Q, R, S, T, U, V, W, X, Y, Z, LBUTTON, RBUTTON, CANCEL, MBUTTON, XBUTTON1, XBUTTON2, BACK, TAB, CLEAR, RETURN, SHIFT, CONTROL, MENU, PAUSE, CAPITAL, KANA, HANGEUL, HANGUL, JUNJA, FINAL, HANJA, KANJI, ESCAPE, CONVERT, NONCONVERT, ACCEPT, MODECHANGE, SPACE, PRIOR, NEXT, END, HOME, LEFT, UP, RIGHT, DOWN, LeftArray, UpArrow, RightArrow, DownArrow, SELECT, PRINT, EXECUTE, SNAPSHOT, INSERT, DELETE, HELP, LWIN, RWIN, APPS, SLEEP, NUMPAD0, NUMPAD1, NUMPAD2, NUMPAD3, NUMPAD4, NUMPAD5, NUMPAD6, NUMPAD7, NUMPAD8, NUMPAD9, MULTIPLY, ADD, SEPARATOR, SUBTRACT, DECIMAL, DIVIDE, F1, F2, F3, F4, F5, F6, F7, F8, F9, F10, F11, F12, F13, F14, F15, F16, F17, F18, F19, F20, F21, F22, F23, F24, NUMLOCK, SCROLL, OEM_NEC_EQUAL, OEM_FJ_JISHO, OEM_FJ_MASSHOU, OEM_FJ_TOUROKU, OEM_FJ_LOYA, OEM_FJ_ROYA, LSHIFT, RSHIFT, LCONTROL, RCONTROL, LMENU, RMENU, BROWSER_BACK, BROWSER_FORWARD, BROWSER_REFRESH, BROWSER_STOP, BROWSER_SEARCH, BROWSER_FAVORITES, BROWSER_HOME, VOLUME_MUTE, VOLUME_DOWN, VOLUME_UP, MEDIA_NEXT_TRACK, MEDIA_PREV_TRACK, MEDIA_STOP, MEDIA_PLAY_PAUSE, LAUNCH_MAIL, LAUNCH_MEDIA_SELECT, LAUNCH_APP1, LAUNCH_APP2, OEM_1, OEM_PLUS, OEM_COMMA, OEM_MINUS, OEM_PERIOD, OEM_2, OEM_3, OEM_4, OEM_5, OEM_6, OEM_7, OEM_8, OEM_AX, OEM_102, ICO_HELP, ICO_00, PROCESSKEY, ICO_CLEAR, PACKET, OEM_RESET, OEM_JUMP, OEM_PA1, OEM_PA2, OEM_PA3, OEM_WSCTRL, OEM_CUSEL, OEM_ATTN, OEM_FINISH, OEM_COPY, OEM_AUTO, OEM_ENLW, OEM_BACKTAB, ATTN, CRSEL, EXSEL, EREOF, PLAY, ZOOM, NONAME, PA1, OEM_CLEAR.


With plugin version 6.0 or newer the script name can be a script ID number. In that case the plugin queries the script name for the given script ID. This allows to call scripts by ID and avoid problems if scripts are later renamed.

Notice: FileMaker 19.2 adds a fmplugin extended privileges. If you have such an extended privileges to allow the plugin to trigger scripts, you need to grant permissions for it. If such a privilege is not defined, the plugin is allowed to trigger scripts. See FileMaker product documentation for details.

Examples

Register Control-F5:

Set Field [HotKeys::HotKey ID; MBS("Hotkey.Register"; "F5"; "control")]
Set Variable [$r; Value:MBS("HotKey.SetScript"; HotKeys::HotKey ID; Get(FileName); "HotkeyAction")]

Register key 37 (L on US keyboard) with modifiers:

Set Field [HotKeys::HotKey ID; MBS("Hotkey.Register"; 37; "shift-control-command-option")]
Set Variable [$r; Value:MBS("HotKey.SetScript"; HotKeys::HotKey ID; Get(FileName); "HotkeyAction")]

Register Control-F5 for showing/hiding data viewer:

Set Variable [$hotkey; Value:MBS("HotKey.Register"; "F5"; "control")]
Set Variable [$r; Value:MBS( "HotKey.SetEvaluate"; $hotkey; "MBS(\"Menubar.RunMenuCommand\"; 49297)" )]
// Mac & Windows

Register Control-F5 to write text file on desktop with content of data viewer:

MBS( "HotKey.SetEvaluate";
    MBS("HotKey.Register"; "F5"; "control");
    "MBS( \"Text.WriteTextFile\";
        MBS( \"FM.DataViewerContent\" );
        MBS( \"Path.AddPathComponent\";
            MBS( \"Folders.UserDesktop\" );
            \"Data Viewer \" & substitute(substitute(Get(CurrentTimestamp); \":\"; \"-\"); \"/\"; \"-\") & \".txt\" );
        \"UTF-8\"
    )"
)
// Mac only.

Register Control-F6 to write current script a text file to desktop:

MBS( "HotKey.SetEvaluate";
    MBS("HotKey.Register"; "F6"; "control");
    "MBS( \"Text.WriteTextFile\";
        MBS( \"ScriptWorkspace.ScriptText\" );
        MBS( \"Path.AddPathComponent\";
            MBS( \"Folders.UserDesktop\" );
            \"Script \" & substitute(substitute(MBS( \"ScriptWorkspace.CurrentTab\" ); \":\"; \"-\"); \"/\"; \"-\") & \".txt\" );
        \"UTF-8\"
    )"
)
// Mac only

Register hotkey Control-F7 for Windows to insert XML snippet:

MBS( "HotKey.SetEvaluate"; MBS("HotKey.Register"; "F7"; "control");
"Let ([
xml = \"<fmxmlsnippet type=\\\"FMObjectList\\\"><Step enable=\\\"True\\\" id=\\\"89\\\" name=\\\"# (comment)\\\"><Text>loop counting up from 1 to $count</Text></Step><Step enable=\\\"True\\\" id=\\\"141\\\" name=\\\"Set Variable\\\"><Value><Calculation><![CDATA[\\\"/* add count here */\\\"]]></Calculation></Value><Repetition><Calculation><![CDATA[1]]></Calculation></Repetition><Name>$count</Name></Step><Step enable=\\\"True\\\" id=\\\"141\\\" name=\\\"Set Variable\\\"><Value><Calculation><![CDATA[1]]></Calculation></Value><Repetition><Calculation><![CDATA[1]]></Calculation></Repetition><Name>$index</Name></Step><Step enable=\\\"True\\\" id=\\\"68\\\" name=\\\"If\\\"><Calculation><![CDATA[$index$count]]></Calculation></Step><Step enable=\\\"True\\\" id=\\\"71\\\" name=\\\"Loop\\\"></Step><Step enable=\\\"True\\\" id=\\\"89\\\" name=\\\"# (comment)\\\"><Text>your script steps here</Text></Step><Step enable=\\\"True\\\" id=\\\"89\\\" name=\\\"# (comment)\\\"></Step><Step enable=\\\"True\\\" id=\\\"89\\\" name=\\\"# (comment)\\\"><Text>next</Text></Step><Step enable=\\\"True\\\" id=\\\"141\\\" name=\\\"Set Variable\\\"><Value><Calculation><![CDATA[$index + 1]]></Calculation></Value><Repetition><Calculation><![CDATA[1]]></Calculation></Repetition><Name>$index</Name></Step><Step enable=\\\"True\\\" id=\\\"72\\\" name=\\\"Exit Loop If\\\"><Calculation><![CDATA[$index > $count]]></Calculation></Step><Step enable=\\\"True\\\" id=\\\"73\\\" name=\\\"End Loop\\\"></Step><Step enable=\\\"True\\\" id=\\\"70\\\" name=\\\"End If\\\"></Step></fmxmlsnippet>\";
r = MBS( \"Clipboard.SetFileMakerData\"; \"ScriptStep\"; xml );
r = MBS( \"RemoteControl.PressControlKey\"; 1 );
r = MBS( \"RemoteControl.PressKey\"; \"v\");
r = MBS( \"RemoteControl.PressControlKey\"; 0 )
]; 1 )"; 0 )
// for Windows

See also

Release notes

  • Version 13.1
    • Implemented local Hotkeys for Windows. So if HotKey.Register is passed Local = 1, we run a different code path to monitor keyboard instead of registering global hotkey.

Example Databases

Blog Entries

This function checks for a license.

Created 4th February 2015, last changed 15th May 2020


HotKey.List - HotKey.SetEnabled