92674bfc5f66bbb1e00930353def02cd25469104
[blender.git] / release / scripts / modules / bpy_extras / keyconfig_utils.py
1 # ##### BEGIN GPL LICENSE BLOCK #####
2 #
3 #  This program is free software; you can redistribute it and/or
4 #  modify it under the terms of the GNU General Public License
5 #  as published by the Free Software Foundation; either version 2
6 #  of the License, or (at your option) any later version.
7 #
8 #  This program is distributed in the hope that it will be useful,
9 #  but WITHOUT ANY WARRANTY; without even the implied warranty of
10 #  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
11 #  GNU General Public License for more details.
12 #
13 #  You should have received a copy of the GNU General Public License
14 #  along with this program; if not, write to the Free Software Foundation,
15 #  Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
16 #
17 # ##### END GPL LICENSE BLOCK #####
18
19 # <pep8 compliant>
20
21 # bpy.type.KeyMap: (km.name, km.space_type, km.region_type, [...])
22
23 #    ('Script', 'EMPTY', 'WINDOW', []),
24
25
26 KM_HIERARCHY = [
27     ('Window', 'EMPTY', 'WINDOW', []),  # file save, window change, exit
28     ('Screen', 'EMPTY', 'WINDOW', [     # full screen, undo, screenshot
29         ('Screen Editing', 'EMPTY', 'WINDOW', []),    # re-sizing, action corners
30         ('Header', 'EMPTY', 'WINDOW', []),            # header stuff (per region)
31     ]),
32
33     ('View2D', 'EMPTY', 'WINDOW', []),    # view 2d navigation (per region)
34     ('View2D Buttons List', 'EMPTY', 'WINDOW', []),  # view 2d with buttons navigation
35
36     ('User Interface', 'EMPTY', 'WINDOW', []),
37
38     ('3D View', 'VIEW_3D', 'WINDOW', [  # view 3d navigation and generic stuff (select, transform)
39         ('Object Mode', 'EMPTY', 'WINDOW', []),
40         ('Mesh', 'EMPTY', 'WINDOW', []),
41         ('Curve', 'EMPTY', 'WINDOW', []),
42         ('Armature', 'EMPTY', 'WINDOW', []),
43         ('Metaball', 'EMPTY', 'WINDOW', []),
44         ('Lattice', 'EMPTY', 'WINDOW', []),
45         ('Font', 'EMPTY', 'WINDOW', []),
46
47         ('Pose', 'EMPTY', 'WINDOW', []),
48
49         ('Vertex Paint', 'EMPTY', 'WINDOW', []),
50         ('Weight Paint', 'EMPTY', 'WINDOW', []),
51         ('Weight Paint Vertex Selection', 'EMPTY', 'WINDOW', []),
52         ('Face Mask', 'EMPTY', 'WINDOW', []),
53         ('Image Paint', 'EMPTY', 'WINDOW', []),  # image and view3d
54         ('Sculpt', 'EMPTY', 'WINDOW', []),
55
56         ('Particle', 'EMPTY', 'WINDOW', []),
57
58         ('Knife Tool Modal Map', 'EMPTY', 'WINDOW', []),
59         ('Paint Stroke Modal', 'EMPTY', 'WINDOW', []),
60         ('Paint Curve', 'EMPTY', 'WINDOW', []),
61
62         ('Object Non-modal', 'EMPTY', 'WINDOW', []),  # mode change
63
64         ('View3D Walk Modal', 'EMPTY', 'WINDOW', []),
65         ('View3D Fly Modal', 'EMPTY', 'WINDOW', []),
66         ('View3D Rotate Modal', 'EMPTY', 'WINDOW', []),
67         ('View3D Move Modal', 'EMPTY', 'WINDOW', []),
68         ('View3D Zoom Modal', 'EMPTY', 'WINDOW', []),
69         ('View3D Dolly Modal', 'EMPTY', 'WINDOW', []),
70
71         ('3D View Generic', 'VIEW_3D', 'WINDOW', []),    # toolbar and properties
72     ]),
73
74     ('Graph Editor', 'GRAPH_EDITOR', 'WINDOW', [
75         ('Graph Editor Generic', 'GRAPH_EDITOR', 'WINDOW', []),
76     ]),
77     ('Dopesheet', 'DOPESHEET_EDITOR', 'WINDOW', [
78         ('Dopesheet Generic', 'DOPESHEET_EDITOR', 'WINDOW', []),
79     ]),
80     ('NLA Editor', 'NLA_EDITOR', 'WINDOW', [
81         ('NLA Channels', 'NLA_EDITOR', 'WINDOW', []),
82         ('NLA Generic', 'NLA_EDITOR', 'WINDOW', []),
83     ]),
84     ('Timeline', 'TIMELINE', 'WINDOW', []),
85
86     ('Image', 'IMAGE_EDITOR', 'WINDOW', [
87         ('UV Editor', 'EMPTY', 'WINDOW', []),  # image (reverse order, UVEdit before Image)
88         ('Image Paint', 'EMPTY', 'WINDOW', []),  # image and view3d
89         ('UV Sculpt', 'EMPTY', 'WINDOW', []),
90         ('Image Generic', 'IMAGE_EDITOR', 'WINDOW', []),
91     ]),
92
93     ('Outliner', 'OUTLINER', 'WINDOW', []),
94
95     ('Node Editor', 'NODE_EDITOR', 'WINDOW', [
96         ('Node Generic', 'NODE_EDITOR', 'WINDOW', []),
97     ]),
98     ('Sequencer', 'SEQUENCE_EDITOR', 'WINDOW', [
99         ('SequencerCommon', 'SEQUENCE_EDITOR', 'WINDOW', []),
100         ('SequencerPreview', 'SEQUENCE_EDITOR', 'WINDOW', []),
101     ]),
102     ('Logic Editor', 'LOGIC_EDITOR', 'WINDOW', []),
103
104     ('File Browser', 'FILE_BROWSER', 'WINDOW', [
105         ('File Browser Main', 'FILE_BROWSER', 'WINDOW', []),
106         ('File Browser Buttons', 'FILE_BROWSER', 'WINDOW', []),
107     ]),
108
109     ('Info', 'INFO', 'WINDOW', []),
110
111     ('Property Editor', 'PROPERTIES', 'WINDOW', []),  # align context menu
112
113     ('Text', 'TEXT_EDITOR', 'WINDOW', [
114         ('Text Generic', 'TEXT_EDITOR', 'WINDOW', []),
115     ]),
116     ('Console', 'CONSOLE', 'WINDOW', []),
117     ('Clip', 'CLIP_EDITOR', 'WINDOW', [
118         ('Clip Editor', 'CLIP_EDITOR', 'WINDOW', []),
119         ('Clip Graph Editor', 'CLIP_EDITOR', 'WINDOW', []),
120         ('Clip Dopesheet Editor', 'CLIP_EDITOR', 'WINDOW', []),
121     ]),
122
123     ('Grease Pencil', 'EMPTY', 'WINDOW', [  # grease pencil stuff (per region)
124         ('Grease Pencil Stroke Edit Mode', 'EMPTY', 'WINDOW', []),
125     ]),
126     ('Mask Editing', 'EMPTY', 'WINDOW', []),
127     ('Frames', 'EMPTY', 'WINDOW', []),    # frame navigation (per region)
128     ('Markers', 'EMPTY', 'WINDOW', []),    # markers (per region)
129     ('Animation', 'EMPTY', 'WINDOW', []),    # frame change on click, preview range (per region)
130     ('Animation Channels', 'EMPTY', 'WINDOW', []),
131
132     ('View3D Gesture Circle', 'EMPTY', 'WINDOW', []),
133     ('Gesture Straight Line', 'EMPTY', 'WINDOW', []),
134     ('Gesture Zoom Border', 'EMPTY', 'WINDOW', []),
135     ('Gesture Border', 'EMPTY', 'WINDOW', []),
136
137     ('Standard Modal Map', 'EMPTY', 'WINDOW', []),
138     ('Transform Modal Map', 'EMPTY', 'WINDOW', []),
139     ('Eyedropper Modal Map', 'EMPTY', 'WINDOW', []),
140     ('Eyedropper ColorBand PointSampling Map', 'EMPTY', 'WINDOW', []),
141 ]
142
143
144 # -----------------------------------------------------------------------------
145 # Add-on helpers to properly (un)register their own keymaps.
146
147 # Example of keymaps_description:
148 keymaps_description_doc = """
149 keymaps_description is a tuple (((keymap_description), (tuple of keymap_item_descriptions))).
150 keymap_description is a tuple (name, space_type, region_type, is_modal).
151 keymap_item_description is a tuple ({kw_args_for_keymap_new}, (tuple of properties)).
152 kw_args_for_keymap_new is a mapping which keywords match parameters of keymap.new() function.
153 tuple of properties is a tuple of pairs (prop_name, prop_value) (properties being those of called operator).
154
155 Example:
156
157 KEYMAPS = (
158     # First, keymap identifiers (last bool is True for modal km).
159     (('Sequencer', 'SEQUENCE_EDITOR', 'WINDOW', False), (
160     # Then a tuple of keymap items, defined by a dict of kwargs for the km new func, and a tuple of tuples (name, val)
161     # for ops properties, if needing non-default values.
162         ({"idname": export_strips.SEQExportStrip.bl_idname, "type": 'P', "value": 'PRESS', "shift": True, "ctrl": True},
163          ()),
164     )),
165 )
166 """
167
168
169 def addon_keymap_register(wm, keymaps_description):
170     """
171     Register a set of keymaps for addons.
172
173     """ + keymaps_description_doc
174     kconf = wm.keyconfigs.addon
175     if not kconf:
176         return  # happens in background mode...
177     for km_info, km_items in keymaps_description:
178         km_name, km_sptype, km_regtype, km_ismodal = km_info
179         kmap = [k for k in kconf.keymaps
180                 if k.name == km_name and k.region_type == km_regtype and
181                 k.space_type == km_sptype and k.is_modal == km_ismodal]
182         if kmap:
183             kmap = kmap[0]
184         else:
185             kmap = kconf.keymaps.new(km_name, region_type=km_regtype, space_type=km_sptype, modal=km_ismodal)
186         for kmi_kwargs, props in km_items:
187             kmi = kmap.keymap_items.new(**kmi_kwargs)
188             kmi.active = True
189             for prop, val in props:
190                 setattr(kmi.properties, prop, val)
191
192
193 def addon_keymap_unregister(wm, keymaps_description):
194     """
195     Unregister a set of keymaps for addons.
196
197     """ + keymaps_description_doc
198     # NOTE: We must also clean up user keyconfig, else, if user has customized one of add-on's shortcut, this
199     #       customization remains in memory, and comes back when re-enabling the addon, causing a segfault... :/
200     kconfs = wm.keyconfigs
201     for kconf in (kconfs.user, kconfs.addon):
202         for km_info, km_items in keymaps_description:
203             km_name, km_sptype, km_regtype, km_ismodal = km_info
204             kmaps = (k for k in kconf.keymaps
205                      if k.name == km_name and k.region_type == km_regtype and
206                      k.space_type == km_sptype and k.is_modal == km_ismodal)
207             for kmap in kmaps:
208                 for kmi_kwargs, props in km_items:
209                     idname = kmi_kwargs["idname"]
210                     for kmi in kmap.keymap_items:
211                         if kmi.idname == idname:
212                             kmap.keymap_items.remove(kmi)
213             # NOTE: We won't remove addons keymaps themselves, other addons might also use them!
214
215
216 # -----------------------------------------------------------------------------
217 # Utility functions
218
219 def km_exists_in(km, export_keymaps):
220     for km2, kc in export_keymaps:
221         if km2.name == km.name:
222             return True
223     return False
224
225
226 def keyconfig_merge(kc1, kc2):
227     """ note: kc1 takes priority over kc2
228     """
229     merged_keymaps = [(km, kc1) for km in kc1.keymaps]
230     if kc1 != kc2:
231         merged_keymaps.extend((km, kc2) for km in kc2.keymaps if not km_exists_in(km, merged_keymaps))
232
233     return merged_keymaps
234
235
236 def _export_properties(prefix, properties, kmi_id, lines=None):
237     from bpy.types import OperatorProperties
238
239     if lines is None:
240         lines = []
241
242     def string_value(value):
243         if isinstance(value, str) or isinstance(value, bool) or isinstance(value, float) or isinstance(value, int):
244             return repr(value)
245         elif getattr(value, '__len__', False):
246             return repr(list(value))
247
248         print("Export key configuration: can't write ", value)
249         return ""
250
251     for pname in properties.bl_rna.properties.keys():
252         if pname != "rna_type":
253             value = getattr(properties, pname)
254             if isinstance(value, OperatorProperties):
255                 _export_properties(prefix + "." + pname, value, kmi_id, lines)
256             elif properties.is_property_set(pname):
257                 value = string_value(value)
258                 if value != "":
259                     lines.append("kmi_props_setattr(%s, '%s', %s)\n" % (prefix, pname, value))
260     return lines
261
262
263 def _kmistr(kmi, is_modal):
264     if is_modal:
265         kmi_id = kmi.propvalue
266         kmi_newfunc = 'new_modal'
267     else:
268         kmi_id = kmi.idname
269         kmi_newfunc = 'new'
270     s = ["kmi = km.keymap_items.%s(\'%s\', \'%s\', \'%s\'" % (kmi_newfunc, kmi_id, kmi.type, kmi.value)]
271
272     if kmi.any:
273         s.append(", any=True")
274     else:
275         if kmi.shift:
276             s.append(", shift=True")
277         if kmi.ctrl:
278             s.append(", ctrl=True")
279         if kmi.alt:
280             s.append(", alt=True")
281         if kmi.oskey:
282             s.append(", oskey=True")
283     if kmi.key_modifier and kmi.key_modifier != 'NONE':
284         s.append(", key_modifier=\'%s\'" % kmi.key_modifier)
285
286     s.append(")\n")
287
288     props = kmi.properties
289
290     if props is not None:
291         _export_properties("kmi.properties", props, kmi_id, s)
292
293     if not kmi.active:
294         s.append("kmi.active = False\n")
295
296     return "".join(s)
297
298
299 def keyconfig_export(wm, kc, filepath):
300
301     f = open(filepath, "w")
302
303     f.write("import bpy\n")
304     f.write("import os\n\n")
305     f.write("def kmi_props_setattr(kmi_props, attr, value):\n"
306             "    try:\n"
307             "        setattr(kmi_props, attr, value)\n"
308             "    except AttributeError:\n"
309             "        print(\"Warning: property '%s' not found in keymap item '%s'\" %\n"
310             "              (attr, kmi_props.__class__.__name__))\n"
311             "    except Exception as e:\n"
312             "        print(\"Warning: %r\" % e)\n\n")
313     f.write("wm = bpy.context.window_manager\n")
314     # keymap must be created by caller
315     f.write("kc = wm.keyconfigs.new(os.path.splitext(os.path.basename(__file__))[0])\n\n")
316
317     # Generate a list of keymaps to export:
318     #
319     # First add all user_modified keymaps (found in keyconfigs.user.keymaps list),
320     # then add all remaining keymaps from the currently active custom keyconfig.
321     #
322     # This will create a final list of keymaps that can be used as a "diff" against
323     # the default blender keyconfig, recreating the current setup from a fresh blender
324     # without needing to export keymaps which haven't been edited.
325
326     class FakeKeyConfig:
327         keymaps = []
328     edited_kc = FakeKeyConfig()
329     for km in wm.keyconfigs.user.keymaps:
330         if km.is_user_modified:
331             edited_kc.keymaps.append(km)
332     # merge edited keymaps with non-default keyconfig, if it exists
333     if kc != wm.keyconfigs.default:
334         export_keymaps = keyconfig_merge(edited_kc, kc)
335     else:
336         export_keymaps = keyconfig_merge(edited_kc, edited_kc)
337
338     for km, kc_x in export_keymaps:
339
340         km = km.active()
341
342         f.write("# Map %s\n" % km.name)
343         f.write("km = kc.keymaps.new('%s', space_type='%s', region_type='%s', modal=%s)\n\n" %
344                 (km.name, km.space_type, km.region_type, km.is_modal))
345         for kmi in km.keymap_items:
346             f.write(_kmistr(kmi, km.is_modal))
347         f.write("\n")
348
349     f.close()
350
351
352 def keyconfig_test(kc):
353
354     def testEntry(kc, entry, src=None, parent=None):
355         result = False
356
357         idname, spaceid, regionid, children = entry
358
359         km = kc.keymaps.find(idname, space_type=spaceid, region_type=regionid)
360
361         if km:
362             km = km.active()
363             is_modal = km.is_modal
364
365             if src:
366                 for item in km.keymap_items:
367                     if src.compare(item):
368                         print("===========")
369                         print(parent.name)
370                         print(_kmistr(src, is_modal).strip())
371                         print(km.name)
372                         print(_kmistr(item, is_modal).strip())
373                         result = True
374
375                 for child in children:
376                     if testEntry(kc, child, src, parent):
377                         result = True
378             else:
379                 for i in range(len(km.keymap_items)):
380                     src = km.keymap_items[i]
381
382                     for child in children:
383                         if testEntry(kc, child, src, km):
384                             result = True
385
386                     for j in range(len(km.keymap_items) - i - 1):
387                         item = km.keymap_items[j + i + 1]
388                         if src.compare(item):
389                             print("===========")
390                             print(km.name)
391                             print(_kmistr(src, is_modal).strip())
392                             print(_kmistr(item, is_modal).strip())
393                             result = True
394
395                 for child in children:
396                     if testEntry(kc, child):
397                         result = True
398
399         return result
400
401     # -------------------------------------------------------------------------
402     # Function body
403
404     result = False
405     for entry in KM_HIERARCHY:
406         if testEntry(kc, entry):
407             result = True
408     return result