Binding Macros to Keys

The default startup project (startup.r3d) defines a set of default key bindings. For example, when you hit the 'm' key, the move tool is activated.

The key binding system of Realsoft 3D implements this behavior. This system contains a list of nodes, each defining two things: a key combination and a macro. Whenever you hit a key, the key binding list is scanned. If a node matching the pressed key is found, the corresponding macro is executed.

Macros can perform various useful tasks. They can activate a tool with the desired options. They can include a sequence of actions. They can rotate the view window, etc.

Defining key bindings using drag & drop

Assume that we want to create lots of NURBS curves using the 'Freehand' option. Activating the curve tool and setting the freehand option is not the fastest way to get the curves created. To solve the problem, you can record a macro, which activates the curve tool with the specified options, and bind the macro to a desired key.

Let's see how this can be achieved.

[Note] Note
We suggest that when creating new key shortcuts in the following tutorials, always use the Alt key as a modifier to avoid confusion with the default key bindings. The Alt modifier has been reserved for the user's own shortcuts.

The 'Key bindings' frame of the select window's Named Macros tab

1. Go to the select window's Named Macros tab and open the 'Key Bindings' frame.

2. Click the 'Key' field and enter the desired key combination, for example 'Alt f'.

Key 'Alt f' entered into the 'Key' field

3. Activate the curve tool and set the 'Freehand' option. Then press the Ctrl key down and drag & drop the curve tool icon into the binding list of the 'Key Bindings' frame.

A new named macro with the name of the dragged tool is automatically created and bound to the specified key. Whenever you hit the key, the curve tool with the freehand option becomes activated.

Defining key bindings manually

In addition to the drag & drop interface, you can use a manual method.

For example, to define the 'freehand curve' binding manually:

1. Set 'Macro/Record' on

2. Click the NURBS/Curve tool and set the 'Freehand' option.

3. Reset macro recording and cancel the NURBS/Curve tool.

You have now recorded a macro. You can verify that the macro works as expected by hitting the 'Ctrl + g' key (which executes the current macro). The NURBS/Curve tool becomes active. Cancel the tool after testing that it works as expected.

4. Go to the Named Macros tab of the select window. Open the 'Named Macros' frame. The 'Name' field contains a string 'current'. All new macros are named as 'current' by default. Activate the 'Name' field and rename the recorded macro to a suitable new name, such as 'freehand curve' and press the enter key. The name of the macro is added to the list (alphabetically sorted) of named macros.

The next step is to bind the new named macro to a suitable key. Make sure you don't have any geometric objects selected. If you have, deselect them.

5. Open the 'Key bindings' frame and click the 'Key' field, enter a suitable key combination (in this case the ALT + f key) and then click the 'Bind' button. The key combination is added to the list, which is alphabetically sorted by key command.

This is exactly what happens when defining bindings using drag & drop.

Context sensitivity

Realsoft 3D key binding system supports context sensitivity. This is implemented using modifiers. For example, if you hit the 'f' key, a named macro called 'forward one frame' is executed. However, if you hold down the Alt key while hitting the 'f' key, another macro (say 'freehand curve') can be executed.

In addition to the standard keyboard modifiers, such as 'Ctrl' or 'Shift', Realsoft 3D automatically defines modifiers such as 'the type of selected objects' or 'name of the current tool'. This increases the flexibility of the binding system greatly: You can define key bindings, which are executed only when a certain tool is activated or a certain type of object is selected.

You can define a context sensitive macro in the following way:

1. Go to the select window's Named Macros tab and open the 'Key Bindings' frame.

Key bindings

2. Make sure there are no geometric objects selected. If you have activated a tool, cancel it.

3. Activate the Key field in the Key Bindings frame by clicking it with the mouse and hit the Alt and the f key. The Key field shows you '<alt>f'.

4. Now hold down the Ctrl key and hit the 'f' again. The 'Key' field now shows you a string '<ctrl>f'. In other words, <ctrl> is a modifier for the 'f' key.

'Alt f' entered into the Key field

5. In addition to the standard keyboard modifiers, such as Ctrl, Shift and Alt, Realsoft 3D allows you to use any key as a modifier for another key. For example, hold down the 'q' key while hitting the 'f' key. The result is a string '<q>f'.

6. Now activate the Move tool of the toolbar (it's in the Transformation tab), click the 'Key' field and hit the 'f' key. The result is a string '[Move]f'. A macro bound to this key string will be executed by the 'f' key only when the Move tool is activated.

7. Finally, select the 'root' object in the Geometric Objects tab of the Select window and return back to the Named Macros tab. Now click the 'Key' field, hold down the Ctrl key and hit the 'f' key. This produces a combination '[Move][Level]<ctrl>f'. A macro bound to this combination is executed only when the Move tool is activated, a level object is selected, Ctrl is pressed and the 'f' key is hit.

The actual key binding system is simple to describe. When you hit a key, the system attempts to find a key binding, which matches the key string produced by currently set modifiers (such as '<ctrl>f'). If found, the associated named macro is executed.

Note that keyboard modifiers are closed inside angle brackets '<>' whereas current tool and selected object modifiers are enclosed in normal brackets '[]'. Modifiers enclosed with '[]' are optional. If no binding is found, optional modifiers are removed one by one to check matches with more general bindings. For example, if you hit the 'p' key while a 'sphere' object is selected, the binding '[sphere]p' is searched first. If not found, a plain 'p' binding is searched. This may sound complicated, but it allows you to define very powerful and flexible context sensitive key bindings. Let's see how this all works in practice.

Move with collision detection

Let's imagine that you need the Move tool with the 'Collision Detection' option very often, so that you want to define a key binding which allows you to activate the tool efficiently.

1. Activate macro recording.

2. Click the Move tool and set the 'Collision Deformation' option.

Record a macro, which activates the Move tool and sets its Collision Deformation option

3. Disable macro recording and cancel the Move tool. You have now recorded a macro, which activates the Move tool and sets its Collision Deformation option.

4. Go to the Named Macros tab in the Select window, open the 'Named Macros' frame and rename the 'current' macro as 'move+collide' and press the Enter key.

5. Make sure you don't have any objects selected (we don't want to create an Object sensitive binding this time). Also, make sure the Move tool is canceled (we don't want to create a Tool sensitive binding). Then click the 'Key' field of the 'Key bindings' frame, press Alt down and hit the 'c' key. Then click the 'Bind' button.

Rename 'current' as 'move+collide'

You have now bound the 'move+collide' macro to the '<Alt>c' key, and you should see the string '<Alt>c move+collide' in the key bindings list.

6. Create a couple of SDS spheres, select one of them and hit the '<Alt>c' key to activate the move tool with collision deformations.

'Move+collide' macro bound to '<alt>c' key combination

Tool sensitive bindings

Let's assume that you create curves a lot and you often need to use the 'Closed' option of the NURBS Curve tool. So, let's define a key binding which allows you to activate the 'closed' option for the NURBS curve simply by hitting the key '<Alt>c'.

[Note] Note
The idea here is that '<Alt>c' should set the 'closed' option only when the curve tool is activated. Otherwise it should activate the move tool with collision detection as defined in the previous example.

1. Activate the NURBS Curve tool. The control bar now shows you the curve specific options.

2. Set macro recording on. Note that macro recording is activated AFTER starting the curve tool.

3. Set the 'Closed' check box.

Record a macro which sets the 'Closed' option for the NURBS curve tool

4. End macro recording. You have now recorded a macro, which just sets the 'Closed' option.

5. Go to the Named Macros tab of the Select window. Open the 'Named Macros' frame and rename the recorded current macro as 'closed curve' in the 'Name' field and press the Enter key.

6. Without canceling the NURBS curve tool, open the 'Key bindings' frame and click the 'Key' field. Now enter the combination '<Alt>c'. You should now see the string '[Nurbs]<alt>c' string in the 'Key' field. Click the 'Bind' button.

'Closed curve' macro bound to [Nurbs]<alt>c key

Now, cancel the curve tool and activate it again. The closed option is not set by default. Use the '<Alt>c' key combination to get the 'Closed' option set.

Note that the 'Move+collide' binding still works provided that the curve tool is not selected.

Context sensitivity and edit mode

The key binding system is also sensitive to the editing mode of the selected objects. For example, you can bind the 'b' key to the 'Break' tool whenever a NURBS curve is selected and is in the Edit mode. If the selected curve is not in the Edit mode, the 'b' key can execute another tool, for example the Bend tool.

The context sensitivity is implemented by concatenating the 'edit mode' to the key string as a modifier.

Some objects can define several edit modes. For example, SDS objects have three edit modes: point, edge and face. Each mode can have its own key bindings. For example, 's' can activate 'subdivide' in the Face editing mode. In Edge mode, the 's' can activate the 'Split edge' tool.

Another example is a set of bindings to the Tab key, which cycles through all edit modes of an SDS object. This can be achieved by defining the following four bindings:

 

[sds]

Tab

sds:edit points

[Point]

[sds]

Tab

sds:edit edges

[Edge]

[sds]

Tab

sds:edit faces

[Face]

[sds]

Tab

sds:object

In other words, when you hit the 'Tab' key when a SDS object in 'object' mode is selected, the Edit Points mode is entered. If you hit the Tab key again, the macro 'sds:edit edges' is executed, and so on.

Multiple key bindings

You can bind more than one macro to the same key combination. In this case, Realsoft 3D cycles through the macros.

Let's assume you need to switch between smooth and polygonal SDS objects and you would like the '<Alt>p' key to toggle the polygonal option on and off. This is naturally a SDS specific key binding: '<Alt>p' should only toggle the polygonal option when a SDS object is selected.

The default startup project defines these macros already so we don't repeat the recording steps here.

1. Create a SDS sphere and select it (we want to define a SDS specific binding).

2. Go to the Named Macros tab of the Select window and open the 'Named Macros' and the 'Key bindings' frames.

3. Select the 'sds:polygonal' named macro, click the 'Key' field and hit the key 'p' while holding the Alt key down. Then click the 'Bind' button.

4. Select the sds:smooth' named macro and click the 'Bind' button again.

You have now bound two macros to a single key.

Two macros bound to a single key

5. Hit the key '<Alt>p' a couple of times while the SDS sphere is selected. The sphere surface toggles between polygonal and smooth shapes.

Any number of macros can be bound to a single key this way. The key binding system remembers the last executed binding and next time you hit the same key, the next macro in the macro list is executed.

Saving/loading key bindings

Key bindings are saved with projects. They are included in the Macros section of Realsoft 3D files. You can use the pull down menu File/Save as Startup to save the current project with the modified key bindings to your startup file.

If you want to save only the macros and key bindings, select File/Save As and set the Macros section. This saves both the named macros and the key bindings.