Code Templates UI Specification
Author: Miloslav Metelka
$Revision: 1.6 $
$Date: 2005/10/11 12:46:40 $
Code Templates allow to paste code snippets into the document at caret position.
They work in a similar way like Abbreviations functionality which the Code Templates
will replace.
Code Template Parameters
The code template is represented by a string that contains parameters ${...}.
Example:
for (Iterator ${iterator} = ${collection instanceof="java.util.Collection"}.iterator(); ${iterator}.hasNext();} {
${cursor}${iterator}.next();
}
${cursor} defines a place where the caret
should be located after parameter's editing is finished.
$$ stands for single
$.
Each parameter has a name and its first occurrence can have an arbitrary number of additional hints:
${parmname hint1=value1 hint2=value2}.
For example ${collection instanceof="java.util.Collection"} defines
that the particular parameter's type should be an instance of the given type
and that the chosen default value (typicall local or instance variable)
should satisfy that condition.
The value of the hint can be omitted which means that the value
of the hint is "true". For example ${ind index}
is equal to ${ind index="true"}.
Enclosing of the value of the hint in quotes is optional
e.g. ${ind index=true} will work too.
\" represents a quote inside the quoted string value of the hint.
The hints present an important mechanism of how to extend the parameter's semantics.
Each language editor has its own set of recognized hints.
It is expected that the number of hints will grow in the future releases.
Generic parameter hints:
| Hint Name |
Hint Value Example |
Hint Description |
default |
"my-default-value" |
Explicit default value that will be used unless
a more appropriate value will be found by the code templates infrastructure.
|
editable |
true/false |
By default each parameter is editable. Non-editable parameters
only make sense if the infrastructure is always able to provide
desired value for the given parameter.
Currently the use of this hint is limited but it will gain
importance once certain additional hints will be introduced
in future releases.
|
Java parameter hints:
| Hint Name |
Hint Value Example |
Hint Description |
index |
<none> |
${ind index} defines that the default
value of the parameter should be an unused variable in the given context
named i
(or j if i is used already etc.).
|
array |
<none> |
${arr array} defines that the default
value of the parameter should be an array variable.
|
instanceof |
"java.util.Collection" |
Java type that the parameter must be instance of. Besides class names
there can be e.g. array String[]
or generics java.util.List<String>.
|
Note: Only the first occurrence of a particular parameter should be accompanied
with the hints. Hints of subsequent occurrences will be ignored.
Predefined Code Templates
Besides the possibility to define custom code templates
there is a list of predefined code templates for each mime-type.
The list includes present abbreviations and adds some new code templates
(for example iteration over arrays and collections for java).
Pasting of Code Template into Editor Document
There are two types of code template pasting:
- Code completion will show matching code templates according to typed prefix.
- Once the abbreviation of the particular code template is typed
and SPACE is pressed then the code template will be pasted.
Once Code Completion window gets opened it will contain
the code templates matching the typed prefix.
Scenario:
- User opens e.g. a java class source file.
- User types "
for" into the body of some method and presses Ctrl+SPACE
to open the code completion window.
- Completion Window appears.
- User can narrow the number of displayed code templates by typing additional letters of the particular code template's abbreviation.
- User can also scroll in the completion scrollpane and select the desired code template
and press Enter to paste the selected code template into document.
Scenario:
- User types the abbreviation of the code template e.g. "
forc"
followed by SPACE.
- If there is a matching code template it will be pasted
into the document at the caret position.
Scenario:
- User pastes the code template (either by code completion or by abbreviation).
- If there are parameters in the pasted code template then the infrastructure
will mark all the parameters (the default values pasted into the code)
with an extra background color and it will select the first parameter.
- User can modify the default parameter's value.
- The user can navigate forward between parameters by TAB key
(or by Shift+TAB in backward direction).
- Once the last parameter was changed the next TAB will jump to the position
of the
${cursor} parameter or (in case if the mentioned parameter is not
defined in the code template's text) right after the end of the pasted code template's text.
- Parameters' switching is circullar. Values of the parameters can be modified
in any order.
- The user can press ESCAPE at any time to stop changing of the parameters' values
and switching back into normal editing mode.
Typing anywhere outside of the parameter's boundaries
also restores the normal editing mode.
- Pressing ENTER at any time will stop editing of the parameters
and position the caret to the to the position of the
${cursor}
parameter.
- Currently the undo/redo functionality Ctrl+Z/Y is disabled
during the parameters' editing mode due to
technical limitations of the present implementation.
Once the parameters editing mode gets finished the normal undo/redo functionality
continues to work.
It is expected that this deficiency will be eliminated in the future releases.
Figure: Completion Popup Window shows code template items according
to the current caret position.
There is a preliminary icon used.
Note: Normally the code template items would be merged with other
completion items related to the given context.
Figure: Documentation popup window shows html documentation
of the selected code template in the completion popup window.
Code Templates Options
Similar to abbreviations editing there could be a dialog
displaying a list of the code templates:
+-------------------------------------------------------------+
|Java Editor - Code Templates |
+-------------------------------------------------------------+
| |
| +------------------------------------------+ [Add... ] |
| |Abbreviation |Description | |
| +------------------------------------------+ [Edit...] |
| |ab |abstract | |
| |bo |boolean | [Remove ] |
| |fora |Iterates over array | |
| |forc |Iterates over collection | |
| | | | |
| | | | |
| | | | |
| | | | |
| +------------------------------------------+ |
| |
| +-------+-+ |
| Expand With: |Space |v| |
| +-------+-+ |
| |
+-------------------------------------------------------------+
Expand With can have four values Shift+Space, Space, Tab or Enter.
The default should be Shift+Space.
When Edit... would be pressed the following dialog would appear:
+-------------------------------------------------------------+
|Edit Code Template |
+-------------------------------------------------------------+
| |
| +-------------------------+ |
| Abbreviation: |ab | [ OK ] |
| +-------------------------+ |
| [Cancel] |
| +-------------------------+ |
| Description: | | |
| +-------------------------+ |
| |
| +-------------------------+ |
| Text: | | |
| | | |
| | | |
| +-------------------------+ |
| |
| [ OK ] [Cancel] |
| |
+-------------------------------------------------------------+
- Improved icon for the code template
- Highlighting of the editable parameters
and the parameter being currently edited (colors, framing etc.)
- Discuss and finalize the look under the new options.
