How To Use Keymap Preference in Blender
The system of keymap preference in Blender is complex a little.
GOAL
Today’s goal is to summarize how to customize keymaps in Blender. The main contents are how to change keymaps, save and import/export key configuration presets. This article doesn’t contain how to use keymap editor or details of UI.
Environment
Blender 2.83 (Python 3.7.4)
Windows 10
What is keymap preference?
The following is an excerpt from the Blender manual.
The keymap editor lets you adjust your keymap via:
Presets: Predefined keymaps which come with Blender and can be added to.
from “Keymap” in Blender 2.92 Manual
Preferences: Keymaps may define their own preferences to change the functionality or add additional key bindings.
Key Map Items: You may add/remove/edit individual keymap entries.
How to change keymap
Keymaps can be changed in each keymap editor.
The system saves the difference from the default Blender keymaps, and the keymaps changed by user are restorable.
The “Restore” button is displayed next to the keymap category name to which user-changed keymaps belongs. And the remove button of user-changed keymap item is change to restore button “←”.
How to save the changed keymap
You can save the changed keymap with “+(Add)” or “Export” button.
If export key configuration, the current keymap is saves as a python file.
If add keyconfig preset, save the current keymap as a python file in the keyconfig directory (C:\Users\<User name>\AppData\Roaming\Blender Foundation\Blender\2.83\scripts\presets\keyconfig).
How to add new keymap preset
User can import key configuration python file with “Import” button. The imported python file is put to the keyconfig directory (C:\Users\<User name>\AppData\Roaming\Blender Foundation\Blender\2.83\scripts\presets\keyconfig).
Important point
How keymap changes works?
Why changes in one key configuration preset makes changes of the keymap in all key configuration presets?
That’s because changes by keymap editor (hereinafter referred to as additional changes) are temporary and defined independently from the key configuration presets. The additional changes are applied to keymap in addition to the current preset.
See the image of the order of process below.
The concept of key configuration presets
It is easy to understand if you think a key configuration preset overwrites blender default keymaps instead of change whole keymaps. If only a part of keymaps are defined in the preset, the defined keymaps are rewritten but keymaps not contained to the preset are still same as the blender default keymaps.
So if user changes the keymaps after adding presets, the changes are regarded as additional changes and the changes aren’t saved in the preset.
What is the meaning of “Restore” button?
“Restore” button resets keymap to the current key configuration preset not to blender default. In short, “Restore” means to remove additional changes.
How to create a custom preset with “+(Add)” or “Export”
Select one preset and change keymaps as you like by keymap editor. The final keymap(current keymap) should be what you’d like to save as a new preset. Then click “+(Add)” and name the new preset or “Export” the key configuration.
Then restore changed keymaps.
“+(Add)” saves only the different keymaps from the default keymaps
When user “Add” preset, the different keymaps from blender default keymaps are only saved.
Please see python files generated in the the keyconfig directory (C:\Users\<User name>\AppData\Roaming\Blender Foundation\Blender\2.83\scripts\presets\keyconfig). The keyconfig_data list contains only keymap-categories where modified keymaps are.
Example of preset python file
keyconfig_data = \
[("3D View",
{"space_type": 'VIEW_3D', "region_type": 'WINDOW'},
{"items":
[("view3d.cursor3d", {"type": 'RIGHTMOUSE', "value": 'PRESS', "shift": True}, None),
("transform.translate",
{"type": 'EVT_TWEAK_R', "value": 'ANY', "shift": True},
{"properties":
[("cursor_transform", True),
("release_confirm", True),
],
},
),
("view3d.localview", {"type": 'NUMPAD_SLASH', "value": 'PRESS'}, None),
("view3d.localview", {"type": 'SLASH', "value": 'PRESS'}, None),
# omitted
],
},
)]
if __name__ == "__main__":
import os
from bl_keymap_utils.io import keyconfig_import_from_data
keyconfig_import_from_data(os.path.splitext(os.path.basename(__file__))[0], keyconfig_data)If you’d like to save all keymaps, use “Export” with “All keymaps” checkbox on.
All Keymaps:
from Blender manual
When disabled, only the keymaps and categories that have been modified by the user will be exported. In addition, add-ons may register keymaps to their respective functions, however, these keymaps are not exported unless changed by the user.
What is the difference between “+(Add)” and “Export”?
They are almost same in source code level, as below. “Add” (wm.keyconfig_preset_add operator) calls “Export” (preferences.keyconfig_export operator) and sets the preset to current key configuration preset.
In other words, the only difference is that the new created key configuration is added into blender key configuration presets in “Add” process, while just preset python file is saved in “Export” process.
# The definition of "Inport keymap" operation
# from "Blender 2.83\2.83\scripts\startup\bl_operators\userpref.py"
class PREFERENCES_OT_keyconfig_export(Operator):
"""Export key configuration to a python script"""
bl_idname = "preferences.keyconfig_export" # the id name of this operation
bl_label = "Export Key Configuration..."
# omitted
def execute(self, context):
from bl_keymap_utils.io import keyconfig_export_as_data
if not self.filepath:
raise Exception("Filepath not set")
if not self.filepath.endswith(".py"):
self.filepath += ".py"
wm = context.window_manager
keyconfig_export_as_data(
wm,
wm.keyconfigs.active,
self.filepath,
all_keymaps=self.all,
)
return {'FINISHED'}# The definition of "Add keymap" operation
# from "Blender 2.83\2.83\scripts\startup\bl_operators\presets.py"
class AddPresetKeyconfig(AddPresetBase, Operator):
"""Add or remove a Key-config Preset"""
bl_idname = "wm.keyconfig_preset_add"
bl_label = "Add Keyconfig Preset"
preset_menu = "USERPREF_MT_keyconfigs"
preset_subdir = "keyconfig"
def add(self, _context, filepath):
bpy.ops.preferences.keyconfig_export(filepath=filepath) #call preferences.keyconfig_export here
bpy.utils.keyconfig_set(filepath)