Statistics
| Revision:

root / tmp / org.txm.practically.rcp / Instructions.txt @ 729

History | View | Annotate | Download (8 kB)

1 486 mdecorde
---how to record
2 486 mdecorde
---how to play
3 486 mdecorde
---gotchas
4 486 mdecorde
----commands you can't use
5 486 mdecorde
----recording modes
6 486 mdecorde
---sharing
7 486 mdecorde
8 486 mdecorde
Practically Macro
9 486 mdecorde
================================================================================
10 486 mdecorde
Practically Macro is an attempt to add simple editor scripting to the Eclipse platform; it is not an attempt at scripting the Eclipse platform in general.  I believe that editor scripting, while similar to general scripting, is fundamentally a different problem.  The intent of this plug-in is to enable users to record/create editor macros in a lightweight manner that can be used temporarily or easily shared with others.  I have tried to do this in a way that uses public API and public assumptions, and I've mostly been able to do so.  In my opinion, every character entered or navigation button pressed should generate a command that can be recorded.  However, Eclipse doesn't generate commands for everything, so I've done the best I can.
11 486 mdecorde
12 486 mdecorde
Requirements
13 486 mdecorde
--------------------------------------------------------------------------------
14 486 mdecorde
Eclipse 3.4 or greater; will not run correctly at 3.3.  Requires the workbench.  Shouldn't require jdt.
15 486 mdecorde
16 486 mdecorde
Recording a macro
17 486 mdecorde
--------------------------------------------------------------------------------
18 486 mdecorde
Start recording a macro by typing Alt+Ctrl+R or clicking the "Record Macro" button on the main toolbar.  The Record button is only enabled when a text editor has input focus.  Once record mode is invoked, the record button will appear depressed.
19 486 mdecorde
Actions that will be captured by recording a macro are Eclipse commands and keystrokes.  Mouse activity is not captured and should be avoided in the editor window.
20 486 mdecorde
Once you are done recording a macro, click the "Record Macro" button again.  If you have recorded any macro contents, a Save dialog will pop up allowing you to supply a name/id/description for the macro.  You can cancel if you don't want to keep the macro.  To allow the macro to be persisted across Eclipse invocations or to allow mapping the command to a keystroke, you must supply an ID.  If you only supply a name, the macro can be used during the Eclipse session only.  You can modify/add an ID later in the session.
21 486 mdecorde
22 486 mdecorde
Playing a macro
23 486 mdecorde
--------------------------------------------------------------------------------
24 486 mdecorde
To play a macro, use the drop down menu on the "Play Macro" button.  You can use the "Play command..." button to execute any Eclipse command or macro that is already defined.  If there are user macros defined with ids, they will show up in a menu called "Macros".  Only the last few will be available, and they will be ordered by last used time.  If there are commands that do not have associated ids, they will show up in the submenu named "Temporary Macros", ordered by last used time.  After you have execute a macro, clicking the Play button will execute the last executed macro.
25 486 mdecorde
26 486 mdecorde
Gotchas
27 486 mdecorde
-------------------------------------------------------------------------------
28 486 mdecorde
This plug-in is built on top of the Eclipse platform. Unfortunately, the Eclipse command structure is not designed with macro recording in mind.  What this means is that not all commands are recordable, and some behavior may be a little sketchy.  However, you can edit a macro after recording, so you should be able to patch up behavior that isn't desirable.  The lack of an official Eclipse strategy means that there is no guide to what commands should be recordable, so I don't impose any artificial limitations.
29 486 mdecorde
Here are some types of actions that make sense to record as part of a macro:
30 486 mdecorde
1)typing characters (see note below)
31 486 mdecorde
2)navigation characters (ex. arrows, page down)
32 486 mdecorde
3)find dialog (I've supplied my own since the standard dialog isn't public)
33 486 mdecorde
4)incremental find (with some hacking)
34 486 mdecorde
5)previously recorded macros
35 486 mdecorde
6)other commands that don't pop up dialogs (ex. file save, find next, organize imports, toggle insert mode)
36 486 mdecorde
37 486 mdecorde
Here are some types of actions that almost certainly won't work correctly:
38 486 mdecorde
1) Commands that bring up dialogs (ex. Go to line)
39 486 mdecorde
2) Wizards and other dialogs (ex. Open File)
40 486 mdecorde
3) ctrl+space intellisense
41 486 mdecorde
4) invoking code templates like "foreach"
42 486 mdecorde
43 486 mdecorde
Special notes
44 486 mdecorde
Certain keystrokes are handled specially by the language editor.  However, these editors don't generate commands associated with their behavior, so they are difficult to interpret.  For example, in a Java file, if you type in a '<', a '>' will be inserted and the cursor will be placed between the two symbols.  Also, the editor is put into a special edit mode so that if you backspace, both characters are deleted.  However, there is no set of commands generated that accomplishes these tasks.  Instead, the editor document captures the initial '<' via a VerifyKeyListener and then does the inserts and sets the mode directly on the document.  Therefore, if you have this setting ("Automatically Close") turned on and type a '<', then the macro will not have any commands corresponding to some of these operations.  You can edit the macro afterward, but that may be inconvenient.  I've added another mode on the Options page that records keys as raw key events and plays them back.  This preserves the behavior of special characters like '<', but is more difficult to edit and may not be sharable with users on other platforms.
45 486 mdecorde
46 486 mdecorde
Editing macros
47 486 mdecorde
------------------------------------------------------------------------------------------
48 486 mdecorde
You can edit macros you have recorded via the Window->Preferences->PracticallyMacro Options->Editor Macro Definitions page.  From this page, you can delete existing macros or edit macros.  Select a macro and click the Edit... button.  From the edit dialog, you can reorder commands in the macro, remove commands, add new commands, and edit commands that have data associated with them (ex. the Find command).
49 486 mdecorde
The Edit dialog also allows you to add a new macro id to a command that didn't previously have an associated id (thus turning it into a persistent command), or alter the id of an existing command.
50 486 mdecorde
51 486 mdecorde
Sharing macros
52 486 mdecorde
---------------------------------------------------------------------------------------------
53 486 mdecorde
From the Editor Macro Definitions page you can export or import macros.  Macros exported to a file can be imported via the import dialog into another eclipse (with the Practically Macro plugins installed, as well as any required plugins/commands).  Macros with ids that already exist in the current Eclipse will be skipped (i.e. they will not replace the current command with that ID).  Also, from the export dialog you can copy the XML from the text box and put that directly into a plugin.xml definition with the following extension point:
54 486 mdecorde
   <extension point="PracticallyMacro.defineMacro">
55 486 mdecorde
       <include the text from the export page here>
56 486 mdecorde
   </extension>
57 486 mdecorde
58 486 mdecorde
59 486 mdecorde
Special macro helper commands
60 486 mdecorde
---------------------------------------------------------------------------------------------
61 486 mdecorde
1)Mark selection start - set a 'mark' at the current selection start, or at the caret pos if no selection
62 486 mdecorde
2)Mark selection end - set a 'mark' at the current selection end, or at the caret pos if no selection
63 486 mdecorde
3)Move cursor to mark - Set the editor cursor to the current mark position
64 486 mdecorde
4)Insert string - this is the workhorse command used to add text. Can contain carriage returns.
65 486 mdecorde
5)Find - perform various kinds of text searching
66 486 mdecorde
6)Styled Text commands - These are commands I've added to the system since they aren't commands by default.  Actions like "move cursor right" are supported by the StyledText widget but aren't mapped as key bindings.
67 486 mdecorde
7)Macro script - You can write whatever scripts you'd like using beanshell.  I pass in several variables for the editor that should be useful.
68 486 mdecorde
69 486 mdecorde
The Mark commands are provided as a way to maintain some state while other operations are performed without requiring scripting.
70 486 mdecorde
For example, to comment a selected area, you could record a sequence of commands like:
71 486 mdecorde
a)mark selection start
72 486 mdecorde
b)move cursor right (puts cursor at end of selection
73 486 mdecorde
c)insert string "*/"
74 486 mdecorde
d)move cursor to mark
75 486 mdecorde
e)insert string "/*"
76 486 mdecorde
77 486 mdecorde
Macro scripting is embryonic and complicated.  There is some help when you are editing the script itself (via "question mark" help).