Revision 2399 tmp/org.txm.practically.rcp/doc/overall.html

overall.html (revision 2399)
1 1
<html>
2 2
<h1>Practically Macro</h1>
3
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.
3
Practically Macro is an attempt to add simple editor scripting to the
4
Eclipse platform; it is not an attempt at scripting the Eclipse platform
5
in general. I believe that editor scripting, while similar to general
6
scripting, is fundamentally a different problem. The intent of this
7
plug-in is to enable users to record/create editor macros in a
8
lightweight manner that can be used temporarily or easily shared with
9
others. I have tried to do this in a way that uses public API and public
10
assumptions, and I've mostly been able to do so. In my opinion, every
11
character entered or navigation button pressed should generate a command
12
that can be recorded. However, Eclipse doesn't generate commands for
13
everything, so I've done the best I can.
4 14

  
5 15
<h2>Requirements</h2>
6
Eclipse 3.4 or greater; will not run correctly at 3.3.  Requires the workbench.  Shouldn't require jdt.  
16
Eclipse 3.4 or greater; will not run correctly at 3.3. Requires the
17
workbench. Shouldn't require jdt.
7 18

  
8 19
<h2>Recording a macro</h2>
9
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.  
10
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.
11
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. 
20
Start recording a macro by typing Alt+Ctrl+R or clicking the "Record
21
Macro" button on the main toolbar. The Record button is only enabled
22
when a text editor has input focus. Once record mode is invoked, the
23
record button will appear depressed. Actions that will be captured by
24
recording a macro are Eclipse commands and keystrokes. Mouse activity is
25
not captured and should be avoided in the editor window. Once you are
26
done recording a macro, click the "Record Macro" button again. If you
27
have recorded any macro contents, a Save dialog will pop up allowing you
28
to supply a name/id/description for the macro. You can cancel if you
29
don't want to keep the macro. To allow the macro to be persisted across
30
Eclipse invocations or to allow mapping the command to a keystroke, you
31
must supply an ID. If you only supply a name, the macro can be used
32
during the Eclipse session only. You can modify/add an ID later in the
33
session.
12 34

  
13 35
<h2>Playing a macro</h2>
14
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.
36
To play a macro, use the drop down menu on the "Play Macro" button. You
37
can use the "Play command..." button to execute any Eclipse command or
38
macro that is already defined. If there are user macros defined with
39
ids, they will show up in a menu called "Macros". Only the last few will
40
be available, and they will be ordered by last used time. If there are
41
commands that do not have associated ids, they will show up in the
42
submenu named "Temporary Macros", ordered by last used time. After you
43
have execute a macro, clicking the Play button will execute the last
44
executed macro.
15 45

  
16 46
<h2>Gotchas</h2>
17
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.<br>
18
Here are some types of actions that make sense to record as part of a macro:<br>
19
<ul>typing characters (see note below)</ul>
20
<ul>navigation characters (ex. arrows, page down)</ul>
21
<ul>find dialog (I've supplied my own since the standard dialog isn't public)</ul>
22
<ul>incremental find (with some hacking)</ul>
23
<ul>previously recorded macros</ul>
24
<ul>other commands that don't pop up dialogs (ex. file save, find next, organize imports, toggle insert mode)</ul>
25
<br> 
26
Here are some types of actions that almost certainly won't work correctly:<br>
27
<ul>Commands that bring up dialogs (ex. Go to line)</ul>
28
<ul>Wizards and other dialogs (ex. Open File)</ul>
29
<ul>ctrl+space intellisense</ul>
30
<ul>invoking code templates like "foreach"</ul>
47
This plug-in is built on top of the Eclipse platform. Unfortunately, the
48
Eclipse command structure is not designed with macro recording in mind.
49
What this means is that not all commands are recordable, and some
50
behavior may be a little sketchy. However, you can edit a macro after
51
recording, so you should be able to patch up behavior that isn't
52
desirable. The lack of an official Eclipse strategy means that there is
53
no guide to what commands should be recordable, so I don't impose any
54
artificial limitations.
55
<br> Here are some types of actions that make sense to record as
56
part of a macro:
57
<br>
58
<ul>typing characters (see note below)
59
</ul>
60
<ul>navigation characters (ex. arrows, page down)
61
</ul>
62
<ul>find dialog (I've supplied my own since the standard dialog
63
	isn't public)
64
</ul>
65
<ul>incremental find (with some hacking)
66
</ul>
67
<ul>previously recorded macros
68
</ul>
69
<ul>other commands that don't pop up dialogs (ex. file save, find
70
	next, organize imports, toggle insert mode)
71
</ul>
72
<br> Here are some types of actions that almost certainly won't
73
work correctly:
74
<br>
75
<ul>Commands that bring up dialogs (ex. Go to line)
76
</ul>
77
<ul>Wizards and other dialogs (ex. Open File)
78
</ul>
79
<ul>ctrl+space intellisense
80
</ul>
81
<ul>invoking code templates like "foreach"
82
</ul>
31 83

  
32 84
<h3>Special notes</h3>
33
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.
34
<br><bold>In general, I recommend running in 'Command' mode and 'typing through' special keystroke modes while recording a macro.</bold>
85
Certain keystrokes are handled specially by the language editor.
86
However, these editors don't generate commands associated with their
87
behavior, so they are difficult to interpret. For example, in a Java
88
file, if you type in a '<', a '>' will be inserted and the cursor will
89
be placed between the two symbols. Also, the editor is put into a
90
special edit mode so that if you backspace, both characters are deleted.
91
However, there is no set of commands generated that accomplishes these
92
tasks. Instead, the editor document captures the initial '<' via a
93
VerifyKeyListener and then does the inserts and sets the mode directly
94
on the document. Therefore, if you have this setting ("Automatically
95
Close") turned on and type a '<', then the macro will not have any
96
commands corresponding to some of these operations. You can edit the
97
macro afterward, but that may be inconvenient. I've added another mode
98
on the Options page that records keys as raw key events and plays them
99
back. This preserves the behavior of special characters like '<', but is
100
more difficult to edit and may not be sharable with users on other
101
platforms.
102
<br>
103
<bold>In general, I recommend running in 'Command' mode and
104
'typing through' special keystroke modes while recording a macro.</bold>
35 105

  
36 106
<h2>Editing macros</h2>
37
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).
38
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.
107
You can edit macros you have recorded via the
108
Window->Preferences->PracticallyMacro Options->Editor Macro Definitions
109
page. From this page, you can delete existing macros or edit macros.
110
Select a macro and click the Edit... button. From the edit dialog, you
111
can reorder commands in the macro, remove commands, add new commands,
112
and edit commands that have data associated with them (ex. the Find
113
command). The Edit dialog also allows you to add a new macro id to a
114
command that didn't previously have an associated id (thus turning it
115
into a persistent command), or alter the id of an existing command.
39 116

  
40 117
<h2>Sharing macros</h2>
41
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).  
118
From the Editor Macro Definitions page you can export or import macros.
119
Macros exported to a file can be imported via the import dialog into
120
another eclipse (with the Practically Macro plugins installed, as well
121
as any required plugins/commands).
42 122

  
43 123
<h2>Scripting</h2>
44
Macro scripting is provided by plugins via an extension point.  See the help for different script types on pref or edit pages for those plugins.  There is no innate scripting provided by the base Practically Macro plugin, but there is a default beanshell plugin paired with the main plugin.  
124
Macro scripting is provided by plugins via an extension point. See the
125
help for different script types on pref or edit pages for those plugins.
126
There is no innate scripting provided by the base Practically Macro
127
plugin, but there is a default beanshell plugin paired with the main
128
plugin.
45 129
</html>

Also available in: Unified diff