ADDON: Edit Any Shortcut, Run Saved Searches/Macros

A while back I made an earlier support post asking about configuring hotkeys and a better way to run macros.
Unfortunately this was not possible....until now...
I felt like a challenge on the weekend and so decided to streamline my workflow. The initial dev spike went so well it turned into a fully functional addon and so I am dropping it here in case anyone else wants to try it.
To this end this addon does not edit any core Citavi configuration. If you delete the configuration files and/or the core addon files any changes made will vanish when you restart Citavi.
It also tries to provide helpful messages and functionality to make playing around with the configuration quick and easy if not fun.
Many will not agree, but they should remember it was a lot harder to make this addon! ;)
What it does/has:
Installation:
Create Default Config
On both the menus there is an option to "Create Default Config" which will create a sensible default configuration file in the user folder.
This will NOT apply the configuration to give you a chance to make changes before you apply them. But remember that when you restart Citavi they WILL be applied. (I picked sensible defaults so nothing bad will happen)
To create both configuration files you must use this option in BOTH menus.
If you do not use macros you can happily ignore the entire macro menu.
Reload Config Now
On both the menus there is an option to "Reload Config Now" which will look for and then apply the configuration file associated with that menu.
It will display a window when it is done showing what changes were made. The changes will also appear in the menus themselves.
It will also tell you if you have overwritten an existing shortcut.
If you accidentally overwrite a core Citavi shortcut you can simply edit the configuration to remove the mistake and then restart Citavi - any other change does not require a restart.
NB: If you see the message: "An item with the same key has already been added" this means that two shortcuts have the same "Command" and this is not allowed.
Shortcuts -> List All Shortcuts
Shows a window with all currently configured shortcuts (or at least the ones I can find) and the commands they are bound to. This is to help you avoid over-writing existing shortcuts.
Shortcuts -> Run (or Add) Saved Search
This list shows either the command name (e.g. "RunSearch01" or "AddSearch15") or the name of the saved search bound to that command prefixed by the search number (e.g. "01: my_search"). The ordering is the same alphabetical sort order that citavi uses. I recommend numbering your searches to keep them in order else you shortcuts will change when the order does.
You CAN run the searches from these menus but obviously the idea is to bind shortcuts to them.
The "Run" versions remove any existing filters you might have and applies the search as the only filter. "Add" adds the filter to any existing filters you might have.
You can see how you might use a clever combination of add/run commands with shortcuts to have both core searches and common filters you can apply to any view.
Once you configure shortcuts for these commands this list will also show you the shortcuts you have configured and what searches they belong to.
See the image below for an example.
Shortcuts -> Run (or Add) Saved Search -> Manually Refresh Names
If something has gone wrong and the names of the searches are not correctly displayed, this button should fix that. (but that should not happen...)
Shortcuts -> Run Macro
This works similar to searches but can load, compile and run macros without having to manage an additional window.
The name of the file will appear in this list if it is configured, otherwise the command name. (e.g. "RunMacro01")
Shortcuts for these commands will also appear if you configure them, but you can also just run the macros from the menu also if you prefer.
Most macros can be set to auto-run which means the Macro Editor window is "hidden" and the macro runs in the background and then is closed when done. If there is an error with the macro, it will pop up the macro editor so you can see it.
Should you want the macro window left open, just turn off auto-run.
NB: Due to a limitation in the Citavi code I unfortunately cannot load external references via the addon without writing my own compiler code. If your macro does use external references you should turn off auto-run for that macro and it will instead bring up the macro window with your macro already loaded.
See the image below for an example.
Configuration files
The configuration is not as easy as I would have liked but the only alternative is to build a full configuration interface and I do not have time for that. (Sorry!)
I have tried to make it as simple as I can.
(For those that care, they are YAML files)
As mentioned the structure of the file is very important. If you don't follow it you will get somewhat helpful errors from the YAML processor - don't blame me for the quality! :)
Shortcut configuration file and the Spreadsheet
Each shortcut has three lines which configure it. Note that the structure (spaces, colons and dashes) are important and need to be the same as in the example. The default configuration file helps as you will have many examples to work from.
e.g. A two commands:
Command:
This is the command that will run when the shortcut is pressed.
To find a list of commands, refer to the spreadsheet on sheets "Default Shortcuts" or "All Menu Items". These will show all available commands and the default Citavi shortcut if it exists. The spreadsheet does not contain the new commands the addon has added such as RunSearch01 but there are examples below and in the menus themselves.
The first column shows the Command name with orange headings for each section.
Note that you must COMBINE the orange heading (e.g. "Main.") with the command name (e.g. "Copy") for use in the configuration file.
e.g.
The second column in the spreadsheet shows the menu/button text you would see on the screen. Use this to help identify what each of the commands does by using this and hunting through the Citavi interface. I know, I know...but think of it as an adventure!
NB 1: Some of these commands will not do anything as they are sub-menus or other commands which cannot be executed. Also note some will only work in certain areas of Citavi. Trial and error unfortunately but any command that has a shortcut already will certainly work.
NB 2: Some items appear in multiple sections (e.g. Copy, Undo, Paste) and when you change one, you change them all.
Modifiers:
These are the control, shift and alt keys that can be used with the shortcut.
c = control, s = shift, a =alt.
The configuration does not care about the order and will only search for those letters.
The windows key cannot be used as a modifier due to MS Windows limitations.
ShortcutKey:
The keyboard key that needs to be pressed along with the modifiers to trigger the command. These MUST be one of the items on the 3rd spreadsheet page ("Valid Keys")
Most keys are usable but remember they ARE used for other things so make sure they are free or you want to over-write them!
e.g. The keys you will use the most:
Some keys can be strange and there are notes in the spreadsheet on this.
Macro configuration file
This one is a little easier and is also a YAML file:
MacroNumber:
You have macros numbered 1-20 and this is the first entry "MacroNumber".
MacroFile:
The next is the file location. The location is relative to the user settings folder unless you use a full path.
e.g. Full path example
O:/UserFiles/Macros/RunMacroTest2.cs
NB: You must use "/" characters and not "\" characters when entering the path.
If you make a mistake don't worry: when you try to run a file it cannot find a pop up will tell you were it was looking to find the file allowing you to adjust accordingly.
AutoRun:
This is optional and defaults to false. When true it will run the file in the background and only bring up the macro editor if there was an error.
Unfortunately this was not possible....until now...
I felt like a challenge on the weekend and so decided to streamline my workflow. The initial dev spike went so well it turned into a fully functional addon and so I am dropping it here in case anyone else wants to try it.
To this end this addon does not edit any core Citavi configuration. If you delete the configuration files and/or the core addon files any changes made will vanish when you restart Citavi.
It also tries to provide helpful messages and functionality to make playing around with the configuration quick and easy if not fun.
Many will not agree, but they should remember it was a lot harder to make this addon! ;)
What it does/has:
- Edit any existing Citavi shortcuts or bind new shortcuts to most, if not all, commands in Citavi.
- Adds new commands to run (or add as a filter) 20 saved searches which can be bound to shortcuts.
- Adds new commands to load, compile and optionally auto-run up to 20 Macros.
- Controlled via 2 "simple" configuration files for which defaults can be generated automatically to get you started quickly.
- While existing configuration files are auto-loaded on Citavi start, you can also manually refresh these as you make changes.
- When loading macro configuration, it will check that any files referred to exist and let you know in the results window if it cannot find them.
- An xls spreadsheet listing the commands, keys and default Citavi shortcuts.
- Can list all currently configured shortcuts so you can avoid collisions.
- Source code provided for hackers.
Installation:
- Unzip the Addons.zip file into your Citavi installation directory.
- The default to something like: C:\Program Files (x86)\Citavi 5\
- Make sure that the 6 files have unpacked into a subdirectory called: Addons
- e.g. C:\Program Files (x86)\Citavi 5\AddOns\
- Start Citavi
- You should see two new menus in the top right of the main Citavi window: "Shortcuts" & "Run Macro"
Create Default Config
On both the menus there is an option to "Create Default Config" which will create a sensible default configuration file in the user folder.
This will NOT apply the configuration to give you a chance to make changes before you apply them. But remember that when you restart Citavi they WILL be applied. (I picked sensible defaults so nothing bad will happen)
To create both configuration files you must use this option in BOTH menus.
If you do not use macros you can happily ignore the entire macro menu.
Reload Config Now
On both the menus there is an option to "Reload Config Now" which will look for and then apply the configuration file associated with that menu.
It will display a window when it is done showing what changes were made. The changes will also appear in the menus themselves.
It will also tell you if you have overwritten an existing shortcut.
If you accidentally overwrite a core Citavi shortcut you can simply edit the configuration to remove the mistake and then restart Citavi - any other change does not require a restart.
NB: If you see the message: "An item with the same key has already been added" this means that two shortcuts have the same "Command" and this is not allowed.
Shortcuts -> List All Shortcuts
Shows a window with all currently configured shortcuts (or at least the ones I can find) and the commands they are bound to. This is to help you avoid over-writing existing shortcuts.
Shortcuts -> Run (or Add) Saved Search
This list shows either the command name (e.g. "RunSearch01" or "AddSearch15") or the name of the saved search bound to that command prefixed by the search number (e.g. "01: my_search"). The ordering is the same alphabetical sort order that citavi uses. I recommend numbering your searches to keep them in order else you shortcuts will change when the order does.
You CAN run the searches from these menus but obviously the idea is to bind shortcuts to them.
The "Run" versions remove any existing filters you might have and applies the search as the only filter. "Add" adds the filter to any existing filters you might have.
You can see how you might use a clever combination of add/run commands with shortcuts to have both core searches and common filters you can apply to any view.
Once you configure shortcuts for these commands this list will also show you the shortcuts you have configured and what searches they belong to.
See the image below for an example.
Shortcuts -> Run (or Add) Saved Search -> Manually Refresh Names
If something has gone wrong and the names of the searches are not correctly displayed, this button should fix that. (but that should not happen...)
Shortcuts -> Run Macro
This works similar to searches but can load, compile and run macros without having to manage an additional window.
The name of the file will appear in this list if it is configured, otherwise the command name. (e.g. "RunMacro01")
Shortcuts for these commands will also appear if you configure them, but you can also just run the macros from the menu also if you prefer.
Most macros can be set to auto-run which means the Macro Editor window is "hidden" and the macro runs in the background and then is closed when done. If there is an error with the macro, it will pop up the macro editor so you can see it.
Should you want the macro window left open, just turn off auto-run.
NB: Due to a limitation in the Citavi code I unfortunately cannot load external references via the addon without writing my own compiler code. If your macro does use external references you should turn off auto-run for that macro and it will instead bring up the macro window with your macro already loaded.
See the image below for an example.
Configuration files
The configuration is not as easy as I would have liked but the only alternative is to build a full configuration interface and I do not have time for that. (Sorry!)
I have tried to make it as simple as I can.
(For those that care, they are YAML files)
As mentioned the structure of the file is very important. If you don't follow it you will get somewhat helpful errors from the YAML processor - don't blame me for the quality! :)
Shortcut configuration file and the Spreadsheet
Each shortcut has three lines which configure it. Note that the structure (spaces, colons and dashes) are important and need to be the same as in the example. The default configuration file helps as you will have many examples to work from.
e.g. A two commands:
- Code: Select all
- Command: Main.RunSearch01
Modifiers: cs
ShortcutKey: D1
- Command: ReferenceEditorFilter.ClearFilter
Modifiers: cs
ShortcutKey: Oemtilde
Command:
This is the command that will run when the shortcut is pressed.
To find a list of commands, refer to the spreadsheet on sheets "Default Shortcuts" or "All Menu Items". These will show all available commands and the default Citavi shortcut if it exists. The spreadsheet does not contain the new commands the addon has added such as RunSearch01 but there are examples below and in the menus themselves.
The first column shows the Command name with orange headings for each section.
Note that you must COMBINE the orange heading (e.g. "Main.") with the command name (e.g. "Copy") for use in the configuration file.
e.g.
- Code: Select all
Main.Copy
Main.RunMacro01
Main.RunSearch15
Main.AddSearch01
ReferenceEditorCategoriesAndKeywords.GoTo
ReferenceEditorNavigation.SelectAll
The second column in the spreadsheet shows the menu/button text you would see on the screen. Use this to help identify what each of the commands does by using this and hunting through the Citavi interface. I know, I know...but think of it as an adventure!
NB 1: Some of these commands will not do anything as they are sub-menus or other commands which cannot be executed. Also note some will only work in certain areas of Citavi. Trial and error unfortunately but any command that has a shortcut already will certainly work.
NB 2: Some items appear in multiple sections (e.g. Copy, Undo, Paste) and when you change one, you change them all.
Modifiers:
These are the control, shift and alt keys that can be used with the shortcut.
c = control, s = shift, a =alt.
The configuration does not care about the order and will only search for those letters.
The windows key cannot be used as a modifier due to MS Windows limitations.
ShortcutKey:
The keyboard key that needs to be pressed along with the modifiers to trigger the command. These MUST be one of the items on the 3rd spreadsheet page ("Valid Keys")
Most keys are usable but remember they ARE used for other things so make sure they are free or you want to over-write them!
e.g. The keys you will use the most:
- Code: Select all
D0 ... D9 = Basic Number Keys (Number pad is not supported)
A-Z = Basic Letters
F1 ... F12
etc
Some keys can be strange and there are notes in the spreadsheet on this.
Macro configuration file
This one is a little easier and is also a YAML file:
- Code: Select all
- MacroNumber: 1
MacroFile: Macros/RunMacroTest3.cs
- MacroNumber: 2
MacroFile: Macros/RunMacroTest2.cs
AutoRun: true
MacroNumber:
You have macros numbered 1-20 and this is the first entry "MacroNumber".
MacroFile:
The next is the file location. The location is relative to the user settings folder unless you use a full path.
e.g. Full path example
O:/UserFiles/Macros/RunMacroTest2.cs
NB: You must use "/" characters and not "\" characters when entering the path.
If you make a mistake don't worry: when you try to run a file it cannot find a pop up will tell you were it was looking to find the file allowing you to adjust accordingly.
AutoRun:
This is optional and defaults to false. When true it will run the file in the background and only bring up the macro editor if there was an error.