Difference between revisions of "KeyMacs plugin"

From Code::Blocks
m
m
Line 30: Line 30:
 
used in the Code::Blocks menu system.
 
used in the Code::Blocks menu system.
  
    Click on OK to accept the KeyMac definition.
+
Click on OK to accept the KeyMac definition.
  
    You will now see a MyMac menu entry at the bottom of the Menu=>Plugins=>KeyMacs
+
You will now see a MyMac menu entry at the bottom of the Menu=>Plugins=>KeyMacs
    menu panel with the command keys Ctrl-Alt-M.
+
menu panel with the command keys Ctrl-Alt-M.
  
    Either clicking on the MyMac menu item, invoking it with the command keys,
+
Either clicking on the MyMac menu item, invoking it with the command keys,
    or choosing it from the KeyMacros context menu should produce "//      "
+
or choosing it from the KeyMacros context menu should produce "//      "
    as a new comment line in your edit window.
+
as a new comment line in your edit window.
  
    ----------------------
+
----------------------
    Recording and playback
+
Recording and playback
    ----------------------
+
----------------------
    KeyMac contain a "Record Macro" facility that stores each keystroke for
+
KeyMac contain a "Record Macro" facility that stores each keystroke for
    later use by the "Play Macro" menu item.
+
later use by the "Play Macro" menu item.
  
    When played back at least once, the keystrokes are stored in the KeyMacs
+
When played back at least once, the keystrokes are stored in the KeyMacs
    Editor by the label "Scratch".
+
Editor by the label "Scratch".
  
    The Scratch macro is over written on each playback. If you wish to save
+
The Scratch macro is over written on each playback. If you wish to save
    it, you must use the KeyMacs editor to rename "Scratch" to something else.
+
it, you must use the KeyMacs editor to rename "Scratch" to something else.
  
    Recorded keymacs must be edited for accuracy. They may contain suprious,
+
Recorded keymacs must be edited for accuracy. They may contain suprious,
    unwanted keystrokes. A '{' brace recored in the macro, for example, cannot be
+
unwanted keystrokes. A '{' brace recored in the macro, for example, cannot be
    played back accurately until it's surrounded by braces "{{}".
+
played back accurately until it's surrounded by braces "{{}".
    "!", "^", "+", cannot be played back as characters until they too are
+
"!", "^", "+", cannot be played back as characters until they too are
    surrounded by braces; else they play back as the Alt, Ctrl, and Shift
+
surrounded by braces; else they play back as the Alt, Ctrl, and Shift
    prefix for any key that follow them. Eg., "^c" is not the characters '^' and
+
prefix for any key that follow them. Eg., "^c" is not the characters '^' and
    'c', but the copy operation Ctrl-C. The character sequence must appear as
+
'c', but the copy operation Ctrl-C. The character sequence must appear as
    "{^}c".
+
"{^}c".
  
    -----------------
+
-----------------
    Named Key Symbols
+
Named Key Symbols
    -----------------
+
-----------------
    At the bottom of the KeyMacs editor is a list of key symbols (KeySyms) which
+
At the bottom of the KeyMacs editor is a list of key symbols (KeySyms) which
    represent functions performed for the user by KeyMacs. For example, {ENTER}
+
represent functions performed for the user by KeyMacs. For example, {ENTER}
    emulates the user depressing then releasing the Enter key.
+
emulates the user depressing then releasing the Enter key.
  
    Other KeySyms, like {ALTDOWN}, depress the Alt keys but do not release them
+
Other KeySyms, like {ALTDOWN}, depress the Alt keys but do not release them
    until an opposite KeySym, like {ALTUP}, appears in the key macro stream.
+
until an opposite KeySym, like {ALTUP}, appears in the key macro stream.
    These "paired" KeySyms can cause havoc if not entered as matching pairs.
+
These "paired" KeySyms can cause havoc if not entered as matching pairs.
    Eg., {CTRLDOWN}{RIGHT}{RIGHT}{CTRLUP} moves two words to the right.
+
Eg., {CTRLDOWN}{RIGHT}{RIGHT}{CTRLUP} moves two words to the right.
  
    KeySyms which cause movement may contain a numeric parameter. Eg, {RIGHT 4}
+
KeySyms which cause movement may contain a numeric parameter. Eg, {RIGHT 4}
    will move the cursor 4 positions to the right.
+
will move the cursor 4 positions to the right.
  
 
     {WAIT 5} will pause for 5 milliseconds.
 
     {WAIT 5} will pause for 5 milliseconds.
Line 79: Line 79:
 
     {ASC} is not available for *nix since XWindows does not support it.
 
     {ASC} is not available for *nix since XWindows does not support it.
  
    ------------
+
------------
    Special keys
+
Special keys
    ------------
+
------------
    !, ^, +, represent the keystrokes Alt, Ctrl, and Shift respectively.
+
!, ^, +, represent the keystrokes Alt, Ctrl, and Shift respectively.
    They provide a modifier for the character key that follows it. When KeyMacs
+
They provide a modifier for the character key that follows it. When KeyMacs
    sees a "!c", it interprets it as an Alt-c; a "+v" as a Shift-v; a "^t" as a
+
sees a "!c", it interprets it as an Alt-c; a "+v" as a Shift-v; a "^t" as a
    Ctrl-t. KeyMacs depresses the modifier key, depresses the char key, releases
+
Ctrl-t. KeyMacs depresses the modifier key, depresses the char key, releases
    the char key, then releases the modifier key.
+
the char key, then releases the modifier key.
  
    The brace set '{' and  '}' are used to deliniate KeySyms. To use them as
+
The brace set '{' and  '}' are used to deliniate KeySyms. To use them as
    characters in a macro, they must be surrounded by braces themselves. Ie.,
+
characters in a macro, they must be surrounded by braces themselves. Ie.,
    {{} and {}} correctly represent the left and right brace as characters.
+
{{} and {}} correctly represent the left and right brace as characters.
  
    ---------------------
+
---------------------
    Quirks & restrictions.
+
Quirks & restrictions.
    ---------------------
+
---------------------
    Key macros must begin execution from within an editor window. Once invoked
+
Key macros must begin execution from within an editor window. Once invoked
    from within an editor, macro keys may be injected into other windows, such as
+
from within an editor, macro keys may be injected into other windows, such as
    the find dialog. The sequence "^fPecan{ENTER}" would invoke the find dialog,
+
the find dialog. The sequence "^fPecan{ENTER}" would invoke the find dialog,
    insert the chars "Pecan" into the find text control, then execute the find by
+
insert the chars "Pecan" into the find text control, then execute the find by
    depressing and releasing the enter key.
+
depressing and releasing the enter key.
  
    Macros not checked as "Menued Macro" in the KeyMacs editor simply remain in
+
Macros not checked as "Menued Macro" in the KeyMacs editor simply remain in
    the databse for future reference. They can, of course, be deleted.
+
the databse for future reference. They can, of course, be deleted.
  
    The macro database resides in the users home directory as cbKeyMacs.ini. The
+
The macro database resides in the users home directory as cbKeyMacs.ini. The
    first section contains the macro definition. The second section specifies
+
first section contains the macro definition. The second section specifies
    weither the macro is "menued" or not.
+
weither the macro is "menued" or not.
  
    KeyMacs can execute other KeyMacs via their menu command key. Be careful.
+
KeyMacs can execute other KeyMacs via their menu command key. Be careful.
    This can cause and infinte loop if two macros invoke one another. To avoid
+
This can cause and infinte loop if two macros invoke one another. To avoid
    this, a KeyMac that invokes another KeyMac should itself have no command keys.
+
this, a KeyMac that invokes another KeyMac should itself have no command keys.
  
    A Keymac that is invoked by another KeyMac may execute asynchronously. Invoked
+
A Keymac that is invoked by another KeyMac may execute asynchronously. Invoked
    KeyMacs do not return to the invoking Keymac The invoking KeyMac cannot wait
+
KeyMacs do not return to the invoking Keymac The invoking KeyMac cannot wait
    for the invoked KeyMac. Most likely, the invoked KeyMac is queued up behind
+
for the invoked KeyMac. Most likely, the invoked KeyMac is queued up behind
    the invoking KeyMac, but it might also start its own thread.
+
the invoking KeyMac, but it might also start its own thread.
  
    The context {MENU} keysym opens on my Windows XP2 system at coordinates (0,0).
+
The context {MENU} keysym opens on my Windows XP2 system at coordinates (0,0).
    I've found no way to change this annoying behavior.
+
I've found no way to change this annoying behavior.
  
    KeyMacs injects keys into the focused window keyboard buffer. It attempts to
+
KeyMacs injects keys into the focused window keyboard buffer. It attempts to
    start the KeyMac within the window that invoked the menu. But if you're running
+
start the KeyMac within the window that invoked the menu. But if you're running
    a "focus follows mouse" system, the mouse may change the window focus during
+
a "focus follows mouse" system, the mouse may change the window focus during
    the execution of a KeyMac causing keys to input into the wrong window.
+
the execution of a KeyMac causing keys to input into the wrong window.
    Be careful of the mouse pointer location during invocations of the context menu.
+
Be careful of the mouse pointer location during invocations of the context menu.
  
    On *nix. I have not yet succeeded in moving the mouse pointer back into the
+
On *nix. I have not yet succeeded in moving the mouse pointer back into the
    window owning the KeyMac when the mouse ends outside the owning window.
+
window owning the KeyMac when the mouse ends outside the owning window.
  
    --------------------
+
--------------------
    How do I install it?
+
How do I install it?
    --------------------
+
--------------------
    Compile KeyMacs for MSWindows with KeyMacs.cbp.
+
Compile KeyMacs for MSWindows with KeyMacs.cbp.
    Compile KeyMacs for *nix with KeyMacs(unix).cbp.
+
Compile KeyMacs for *nix with KeyMacs(unix).cbp.
  
    ------------------
+
------------------
    KeySym definitions
+
KeySym definitions
    ------------------
+
------------------
 
     ^, !, + are key modifiers representing CTRL, ALT,SHIFT
 
     ^, !, + are key modifiers representing CTRL, ALT,SHIFT
 
     {ALT UP|DOWN} - Program menu invocation
 
     {ALT UP|DOWN} - Program menu invocation
Line 176: Line 176:
 
     {WAIT}
 
     {WAIT}
  
    ---------------
+
---------------
    Example KeyMacs
+
Example KeyMacs
    ---------------
+
---------------
    Use cmd key Ctrl-Enter to create a new indented line.
+
Use cmd key Ctrl-Enter to create a new indented line.
 
     "{END}{ENTER}"
 
     "{END}{ENTER}"
  
    Use Ctrl-P to enter the C++ pointer sequence (saving alot of mistypes)
+
Use Ctrl-P to enter the C++ pointer sequence (saving alot of mistypes)
 
     "->"
 
     "->"
  
    Use Alt-Ctrl-C to enter the C++ comment sequence
+
Use Alt-Ctrl-C to enter the C++ comment sequence
 
     "{END}{ENTER}//{TAB}"
 
     "{END}{ENTER}//{TAB}"
  
    Use Alt-Ctrl-B to enter a new set of formated braces
+
Use Alt-Ctrl-B to enter a new set of formated braces
 
     "{END}{ENTER}{{}{ENTER 2}{HOME}{}}{UP}{TAB}"
 
     "{END}{ENTER}{{}{ENTER 2}{HOME}{}}{UP}{TAB}"

Revision as of 17:01, 15 January 2007

KeyMacs
Dragscroll.png
Developer(s): Pecan
Maintainer(s): Pecan
Version: 0.2

KeyMacs (or Keyboard Macros) plugin enables Recording, Playback, and editing of keystroke macros.


What is KeyMacs?


KeyMacs is a Code::Blocks plugin providing the user an ability to group sequences of keystokes as a macro (KeyMac). The KeyMac can be executed by either the main Plugin menu, a menu command key, or the context menu.

The KeyMac "{END}{ENTER}//{TAB 2}", for example, will move the cursor to the end of the current line, start a new line, enter the C++ comment sequence and two tabs.

The KeyMacs can be created in the KeyMac editor or the Record Macro menu. The editor can be accessed via MainMenu => Plugins => KeyMacs => EditMacros.

Within the editor, click the New button. A new empty "Untitled" macro is created. Click on "Untitled" and rename it, for example, MyMac. Hit enter to confirm the rename.

   {END}{ENTER}//{TAB 2}

Enter the above keymac into the right hand text window . Click within the "Menued Macro" check box to cause KeyMacs to add MyMac as an entry on the Pugins=>KeyMacs=>submenu.

Within the Command Key edit box, enter the keystrokes "Ctrl-Alt-M". These are the command (hot) keys that will be placed on the menu entry for MyMac. This key sequence should be unique, not conficting with any other menu key sequence used in the Code::Blocks menu system.

Click on OK to accept the KeyMac definition.

You will now see a MyMac menu entry at the bottom of the Menu=>Plugins=>KeyMacs menu panel with the command keys Ctrl-Alt-M.

Either clicking on the MyMac menu item, invoking it with the command keys, or choosing it from the KeyMacros context menu should produce "// " as a new comment line in your edit window.


Recording and playback


KeyMac contain a "Record Macro" facility that stores each keystroke for later use by the "Play Macro" menu item.

When played back at least once, the keystrokes are stored in the KeyMacs Editor by the label "Scratch".

The Scratch macro is over written on each playback. If you wish to save it, you must use the KeyMacs editor to rename "Scratch" to something else.

Recorded keymacs must be edited for accuracy. They may contain suprious, unwanted keystrokes. A '{' brace recored in the macro, for example, cannot be played back accurately until it's surrounded by braces "{{}". "!", "^", "+", cannot be played back as characters until they too are surrounded by braces; else they play back as the Alt, Ctrl, and Shift prefix for any key that follow them. Eg., "^c" is not the characters '^' and 'c', but the copy operation Ctrl-C. The character sequence must appear as "{^}c".


Named Key Symbols


At the bottom of the KeyMacs editor is a list of key symbols (KeySyms) which represent functions performed for the user by KeyMacs. For example, {ENTER} emulates the user depressing then releasing the Enter key.

Other KeySyms, like {ALTDOWN}, depress the Alt keys but do not release them until an opposite KeySym, like {ALTUP}, appears in the key macro stream. These "paired" KeySyms can cause havoc if not entered as matching pairs. Eg., {CTRLDOWN}{RIGHT}{RIGHT}{CTRLUP} moves two words to the right.

KeySyms which cause movement may contain a numeric parameter. Eg, {RIGHT 4} will move the cursor 4 positions to the right.

   {WAIT 5} will pause for 5 milliseconds.
   {ASC 0191} will enter the char represented by ascii 191 into the editor.
   {ASC} is not available for *nix since XWindows does not support it.

Special keys


!, ^, +, represent the keystrokes Alt, Ctrl, and Shift respectively. They provide a modifier for the character key that follows it. When KeyMacs sees a "!c", it interprets it as an Alt-c; a "+v" as a Shift-v; a "^t" as a Ctrl-t. KeyMacs depresses the modifier key, depresses the char key, releases the char key, then releases the modifier key.

The brace set '{' and '}' are used to deliniate KeySyms. To use them as characters in a macro, they must be surrounded by braces themselves. Ie., {{} and {}} correctly represent the left and right brace as characters.


Quirks & restrictions.


Key macros must begin execution from within an editor window. Once invoked from within an editor, macro keys may be injected into other windows, such as the find dialog. The sequence "^fPecan{ENTER}" would invoke the find dialog, insert the chars "Pecan" into the find text control, then execute the find by depressing and releasing the enter key.

Macros not checked as "Menued Macro" in the KeyMacs editor simply remain in the databse for future reference. They can, of course, be deleted.

The macro database resides in the users home directory as cbKeyMacs.ini. The first section contains the macro definition. The second section specifies weither the macro is "menued" or not.

KeyMacs can execute other KeyMacs via their menu command key. Be careful. This can cause and infinte loop if two macros invoke one another. To avoid this, a KeyMac that invokes another KeyMac should itself have no command keys.

A Keymac that is invoked by another KeyMac may execute asynchronously. Invoked KeyMacs do not return to the invoking Keymac The invoking KeyMac cannot wait for the invoked KeyMac. Most likely, the invoked KeyMac is queued up behind the invoking KeyMac, but it might also start its own thread.

The context {MENU} keysym opens on my Windows XP2 system at coordinates (0,0). I've found no way to change this annoying behavior.

KeyMacs injects keys into the focused window keyboard buffer. It attempts to start the KeyMac within the window that invoked the menu. But if you're running a "focus follows mouse" system, the mouse may change the window focus during the execution of a KeyMac causing keys to input into the wrong window. Be careful of the mouse pointer location during invocations of the context menu.

On *nix. I have not yet succeeded in moving the mouse pointer back into the window owning the KeyMac when the mouse ends outside the owning window.


How do I install it?


Compile KeyMacs for MSWindows with KeyMacs.cbp. Compile KeyMacs for *nix with KeyMacs(unix).cbp.


KeySym definitions


   ^, !, + are key modifiers representing CTRL, ALT,SHIFT
   {ALT UP|DOWN} - Program menu invocation
   {BACKSPACE} or {BS}
   {DEL}
   {DELETE}
   {DOWN}
   {END}
   {ENTER}
   {ESC} or {ESCAPE}
   {F1} {F2} {F3} {F4} {F5} {F6} {F7} {F8} {F9} {F10} {F11} {F12}
   {HOME}
   {INS} or {INSERT}
   {LEFT} {RIGHT}
   {PGDN} {PGUP}
   {SPACE}
   {TAB}
   {UP}
   {PRINTSCREEN}
   {SCROLLLOCK}
   {NUMLOCK}
   {CTRLBREAK}
   {PAUSE}
   {CAPSLOCK}
   {NUMPAD0}
   {NUMPAD1} {NUMPAD2} {NUMPAD3} {NUMPAD4} {NUMPAD5} {NUMPAD6} {NUMPAD7}
   {NUMPAD8} {NUMPAD9} {NUMPADMULT} {NUMPADADD} {NUMPADSUB} {NUMPADDOT}
   {NUMPADDIV} {NUMPADENTER UP|DOWN}
   {MENU} - context menu
   {LCTRL} {RCTRL}
   {LALT} {RALT}
   {LSHIFT} {RSHIFT}
   {SLEEP}
   {CTRLDOWN} {CTRLUP}
   {ALTDOWN} {ALTUP}
   {SHIFTDOWN} {SHIFTUP}
   {ASC 0nnn}
   {WAIT}

Example KeyMacs


Use cmd key Ctrl-Enter to create a new indented line.

   "{END}{ENTER}"

Use Ctrl-P to enter the C++ pointer sequence (saving alot of mistypes)

   "->"

Use Alt-Ctrl-C to enter the C++ comment sequence

   "{END}{ENTER}//{TAB}"

Use Alt-Ctrl-B to enter a new set of formated braces

   "{END}{ENTER}{{}{ENTER 2}{HOME}{}}{UP}{TAB}"