Instrumenta Keys is a keyboard shortcut companion for Instrumenta, bringing customizable keyboard shortcuts to Instrumenta. Since VBA for PowerPoint lacks native keyboard shortcut support, Instrumenta Keys runs independently alongside Instrumenta, enabling users to assign shortcuts via a simple CSV file.
- Fully configurable: Easily customize shortcuts to match your workflow (or import shortcut-files created by others!). On Windows there is a built-in editor for shortcuts.
- Supports both Windows and Mac
- Runs independently: Instrumenta Keys works alongside Instrumenta without modifying its core functionality.
- Compatible with other VBA projects: Designed to integrate with any VBA-based automation, not just Instrumenta.
Instrumenta Keys is highly experimental and is licensed under the MIT license. You may freely use, modify, and distribute it, but use at your own risk. If you integrate this code into your own project—whether for personal or commercial use—please provide proper attribution in line with the MIT license requirements.
As stated in the license: THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
Instrumenta Keys supports Windows and Mac versions of PowerPoint, with distinct implementations for each platform:
- On Windows, Instrumenta Keys uses a single PowerShell script to connect to PowerPoint and respond to keyboard shortcuts.
- On Mac, Instrumenta Keys requires a helper add-in for PowerPoint that enables AppleScript to trigger its features via an external application.
Due to these differences, the following sections provide platform-specific details on installation, shortcut handling, and building from source.
On Windows Instrumenta Keys is a PowerShell script and does not require administrative rights for installation on most enterprise systems.
- Download the binary: Instrumenta Keys.exe
- Run the binary. It will automatically generate a shortcut file for you and minimize to the system tray after a few seconds. Enjoy your shortcuts!
- To open it again, right-click the Instrumenta Keys icon in the system tray and click on Show/Hide window.
Note: A security notice may appear when running the binary, please refer to these instructions from Microsoft to unblock Instrumenta Keys: (1) Open Windows File Explorer and go to the folder where you saved the file; (2) Right-click the file and choose Properties from the context menu; (3) At the bottom of the General tab, select the Unblock checkbox and select OK.
Shortcuts in Instrumenta Keys are stored in the shortcuts.csv file. If this file is missing when you launch Instrumenta Keys, a default version will be created automatically. You can manage and customize your shortcuts using the Shortcut Editor, which you can open in PowerPoint by pressing CTRL+SHIFT+ALT+Q. This editor allows you to modify your shortcuts, import or export shortcut files, and even load shortcut configurations directly from this GitHub page. This makes it easy to use shortcut files shared by others, such as sets tailored to specific consultancy firm standards.
Instructions and a full list of available macros in Instrumenta can be found here
Building your own Instrumenta Keys is very simple:
- Microsoft PowerShell
- PS2EXE module (PowerShell-to-EXE converter)
- Locate the source code in
\src\windows\ - Run the build script in an elevated PowerShell window:
.\build.ps1 - The executable will be generated in
\bin\windows\Instrumenta Keys.exe
To install Instrumenta Keys on Mac, you'll need three components: the helper add-in, an AppleScript file, and external software to trigger the AppleScript using keyboard shortcuts. The helper add-in integrates directly with PowerPoint, enabling Instrumenta's features within the application. External software is required to execute the AppleScript when a key combination is pressed. Due to the complex set-up the execution of shortcuts is a bit slower on Mac (takes about a second), but still functional.
To install the add-in, follow these steps:
-
Download the required files:
- InstrumentaKeysHelper.ppam (PowerPoint add-in)
- InstrumentaKeys.applescript (AppleScript script)
-
Move both files to: ~/Library/Application Scripts/com.microsoft.Powerpoint/
- This folder is located in the Library directory of the current user. If it does not exist, create it manually.
- Install the add-in:
- Open PowerPoint.
- Click Tools in the application menu, then select Add-ins....
- In the Add-Ins dialog box, click the + button, browse for the add-in file, and click Open.
- Click OK to close the dialog box.
- Verify the installation:
- A "[Keys]" page should appear in the PowerPoint ribbon.
- Restart PowerPoint:
- Fully close PowerPoint to apply the changes.
- A reboot may be required in some cases.
- PowerPoint may prompt you to trust the add-in or enable macros, select "Enable Content" or "Enable Macros" if prompted.
Several commercial applications can potentially execute the AppleScript, including Automator, BetterTouchTool, and Keyboard Maestro. While these have not been tested, they might work for triggering Instrumenta's features. However, for this installation, we are using Karabiner-Elements, an open-source project that offers advanced keyboard customization. Karabiner-Elements enables users to remap keys and configure complex interactions, making it a reliable (and free!) solution for linking keyboard shortcuts to AppleScript execution.
- Download Karabiner-Elements from its official website:
https://karabiner-elements.pqrs.org/ - Install the software on your Mac.
- Open the Karabiner-Elements application.
- macOS may request accessibility permissions for Karabiner-Elements to function correctly. Grant the necessary permissions as prompted. You might need to reboot or restart the application.
- Download the default preset keyboard shortcuts:
InstrumentaDefault.json - Open the JSON file in your preferred text editor.
- Select all content and copy it to your clipboard.
- Open Karabiner-Elements Settings, then navigate to "Complex Modifications".
- Click "Add your own rule".
- Select and delete the template JSON, then paste the contents of InstrumentaDefault.json.
- Click "Save".
- (Optional) Navigate to "Devices" and enable "Modify events" for any external keyboards you may have.
- Open PowerPoint and enjoy your keyboard shortcuts!
To customize or add shortcuts, you'll need to modify the JSON file used by Karabiner-Elements. The relevant section in the JSON where the script is executed follows this format: '"/usr/bin/osascript ~/Library/Application\ Scripts/com.microsoft.Powerpoint/InstrumentaKeys.applescript [Macro reference]"'
This command requires a Macro Reference as a command-line argument. Instrumenta provides various built-in macro references that trigger specific functions. InstrumentaDefault.json contains the following shortcuts:
| Shortcut | Instrumenta Macro Reference | Description |
|---|---|---|
| Ctrl + Shift + S | ObjectsSwapPosition | Swap positions of selected objects. |
| Ctrl + Shift + L | ObjectsAlignLefts | Align selected objects to the left. |
| Ctrl + Shift + T | ObjectsAlignTops | Align selected objects to the top. |
| Ctrl + Shift + R | ObjectsAlignRights | Align selected objects to the right. |
| Ctrl + Shift + B | ObjectsAlignBottoms | Align selected objects to the bottom. |
| Ctrl + Shift + E | ObjectsAlignCenters | Align selected objects by their center. |
| Ctrl + Shift + M | ObjectsAlignMiddles | Align selected objects by their middle. |
| Ctrl + Shift + H | ObjectsDistributeHorizontally | Distribute selected objects horizontally. |
| Ctrl + Shift + V | ObjectsDistributeVertically | Distribute selected objects vertically. |
| Ctrl + Shift + Left Arrow | MoveTableColumnLeft | Move the selected table column to the left. |
| Ctrl + Shift + Right Arrow | MoveTableColumnRight | Move the selected table column to the right. |
| Ctrl + Shift + Up Arrow | MoveTableRowUp | Move the selected table row up. |
| Ctrl + Shift + Down Arrow | MoveTableRowDown | Move the selected table row down. |
| Ctrl + Shift + Q | GenerateStickyNote | Create a sticky note in the presentation. |
The full list of available macro references can be found here. Updating the JSON file with your desired shortcuts will allow you to tailor Instrumenta Keys to your workflow.
Instrumenta Keys works fastest when the full PowerPoint Ribbon is visible on the screen, especially the "[Keys]" tab. If the "[Keys]" tab is placed inside the overflow menu (the button with the >>), shortcut execution may be slightly slower. Keeping the tab visible ensures optimal responsiveness when triggering macros via keyboard shortcuts.
Building from source is straightforward and allows you to customize Instrumenta Keys to your needs.
- Open "InstrumentaKeysHelper.pptm" from the
/src/mac/directory in PowerPoint. - Enable the Developer tab in the PowerPoint ribbon through PowerPoint settings.
- All coding is done in the Visual Basic Editor (VBA IDE) of PowerPoint. The
.basfiles in the Modules directory are for reference only and are exported after every build. - You can modify the
.pptmfile, update existing code, or create your own and copy-paste the relevant sections. - To customize the PowerPoint Ribbon, use Office RibbonX Editor to edit the
.pptmfile. - In PowerPoint, save the file as a PowerPoint Add-in (
*.ppam) to generate your own build.
- Open "InstrumentaKeys.applescript" in your preferred text editor.
- Modify the script as needed to align with your specific needs.
I am happy to receive feature requests and code contributions! Let's make the best toolbar together. For feature requests please create new issue and label it as an enhancement (https://github.com/iappyx/Instrumenta/issues/new/choose).
- If you want to contribute, please make sure that the code can be freely used as open source code. Please only update the files in /src/. For security reasons I will not accept updated files in /bin/.
- If you want to share your shortcut csv (Windows) or json (Mac), please add them to /shared-shortcuts/
- If you like this Instrumenta & Instrumenta Keys, please let me and the community know how you are using this in your daily work: iappyx/Instrumenta#5
