Live Templates

From RAD Studio
Jump to: navigation, search

Go Up to Getting Started with RAD Studio


Live Templates are reusable skeleton code statements. A set of Live Templates for Delphi and C++ are accessible in the Code Editor.

You can insert one of these pre-defined code skeletons into your code by double-clicking the template name in the Templates Window. You can also type the template name and press the Tab key to insert the template. The XML files for the RAD Studio Live Templates are located in C:\Program Files (x86)\Embarcadero\Studio\18.0\ObjRepos\en\Code_Templates.

You can add your own code templates to the Templates Window. The names of live templates can either represent the code in the template (such as class) or be the first word in the code (such as try), and some template names are close (but not exact) versions of words you might type (such as forr). Templates that you create (and templates provided by third party add-ins) are saved by default in the C:\Users\<user>\Documents\Embarcadero\Studio\code_templates directory.

Jump Points

Jump points are placeholders for key entry fields that allow you to navigate between elements in a template, using the Tab and Shift+Tab keys.

If a template has one or more editable jump points, the template automatically enters SyncEdit mode after you insert it into your code. Pressing Esc, Enter,or pressing the Tab key from the last jump point exits SyncEdit mode and puts the Code Editor back into regular edit mode.

For example, in the arrayd (Delphi array) template, there are four jump points, with the names name (TMyArray), min (0), max (10), and type (Integer). The first jump point is highlighted and active:

ArrayD.png

To compare the arrayd XML code to the arrayd Live Template itself, open the Templates Window, select the arrayd template and click EditCodeTemplate.jpg Edit code template.

Examples: The try Templates for Delphi and C++

This section shows you the try templates for Delphi and for C++:

Language Template Name Template Description

Delphi

try

try finally (with Create/Free)

C++

try

try catch

Delphi try Template

Here you can see the Templates Window and the popup code summary that is displayed when you mouse-over the Delphi try template. The vertical bars ("|") are special characters, used here to set off jump points in the template ($ can also be used to delimit jump points):

DelphiTryPopup.jpg

Here is the template that is inserted in the Code Editor when you activate the try template for Delphi. The highlighted or outlined jump points are active in Sync Edit, so you can edit all occurrences of a jump point at one time:

TryFinallyDelphi.jpg

Here is the XML file for the Delphi code template try.xml, which displays the Description try finally (with Create/Free). In this template, you can see:

  • The definitions for three jump points (named variable, control, and createparms)
  • The script command that associates Code Completion with the control jump point
 <?xml version="1.0" encoding="utf-8" ?>
 
 <codetemplate	xmlns="http://schemas.borland.com/Delphi/2005/codetemplates"
 				version="1.0.0">
 	<template name="'''try'''" surround="'''true'''" invoke="'''auto'''">
 		<point name="'''variable'''">
 			<text>
 				'''MyClass'''
 			</text>
 			<hint>
 				'''Variable name'''
 			</hint>
 		</point>
 		<point name="control">
 			<script language="'''Delphi'''">
 				'''InvokeCodeCompletion;'''
 			</script>
 			<text>
 				'''Component'''
 			</text>
 			<hint>
 				'''Class name'''
 			</hint>
 		</point>
 		<point name="createparms">
 			<hint>
 				'''constructor parameters'''
 			</hint>
 						<text>
 							'''(Self)'''
 						</text>
 		</point>
 		<description>
 			'''try finally (with Create/Free)'''
 		</description>
 		<author>
 			'''Embarcadero'''
 		</author>
 		<script language="'''Delphi'''" onenter="'''false'''" onleave="'''true'''">
 			'''DeclareVariable(|variable|);'''
 		</script>
 		<code language="'''Delphi'''" context="'''methodbody'''" delimiter="|"><![CDATA['''|variable| := T|control|.Create|createparms|;
 '''try
 '''|selected||*||end|
 '''finally
 '''|*||variable|.Free;
 '''end;'''
 ''']]>
 		</code>
 	</template>
 </codetemplate>

The code for the template is located inside <![CDATA[ ... ]]> in the <code> element. In the template above, the first element is a jump point named variable:

|variable|

You can also see the special characters that indent a line in the code:

|*|

For a double indent, use:

|*||*|

C++ try Template

Here is the popup code summary that is displayed in the Templates Window when you mouse-over the C++ try template. The dollar-signs ($) are special characters used to set off defined and built-in jump points (| can also be used):

TryPopupCPP2.jpg

Here is the Live template that is inserted in the Code Editor when you activate the C++ try template (with Description = 'try catch') :

TryCppAgain.jpg

And here is the actual XML for the C++ try template:

 <?xml version="1.0" encoding="utf-8" ?>
 
 <codetemplate	xmlns="http://schemas.borland.com/Delphi/2005/codetemplates"
 				version="1.0.0">
 	<template name="'''try'''" surround="'''true'''" invoke="'''auto'''">
 		<point name="'''except'''">
 			<text>
 				...
 			</text>
 			<hint>
 				'''exception class to catch'''
 			</hint>
 		</point>
 		<description>
 			'''try catch'''
 		</description>
 		<author>
 			'''Embarcadero'''
 		</author>
 		<code language="'''C'''" context="'''methodbody'''"><![CDATA['''try {
 '''$selected$$*$$end$
 '''} catch ($except$) {
 '''}'''
 ]]>
 		</code>
 	</template>
 </codetemplate>

The actual code for the template is inside the <![CDATA[ ... ]]> in the <code> element.

This template uses the dollar sign ($) as a delimiter character, whereas the Delphi try template uses the vertical bar (|) delimiter character. The following special characters indent a line in the code:

$*$

For a double indent, use:

$*$$*$

XML Description for Live Templates

Live templates are XML files that can contain the following parent element:

 <codetemplate xmlns="http: ... //schemas.borland.com/Delphi/2005/codetemplates" version="1.0.0"> ... 
 </codetemplate>

The <codetemplate> element contains the following child elements:

  • <template> </template> has four attributes (name, invoke, inplace, surround):
    <template name="class" invoke="manual/auto">
    • name (name of the template, required)
    • invoke (how to invoke the template). Possible values are {auto|manual|none}:
      • auto = press Space or Tab key
      • manual = press Tab key
      • none = press Ctrl+J, Ctrl+Space or use the Templates Window
    • inplace - (Boolean) indicates an expansion template
    • surround - (Boolean) enables the template to surround selected text
  • <description>Text </description> – an element of template - contains Text that appears with the template name in the Templates window
  • <author>Author_Name</author> – an element of the template
  • <point> </point> – an element of the template (like description and author), describes a placeholder for an entry field, has a name (required), and contains three attributes (text|hint|script):
    • text – attribute of the point, contains the text that appears in a jump point
    • hint – attribute of the point, contains a popup hint
  • script – attribute of either point or template, most often contains invoke_code_completion(), has a language attribute:
    • language='Delphi' or language='C'
  • <code> </code> – an element of the template; has three attributes:
    • language – can be 'C' or 'Delphi' (required)
    • context - determines when the template is available; examples are typedecl - type |' or 'methodbody - begin | end
    • delimiter='|' or '$' (indicates jump point in the code)
    • Contains:
     <![CDATA[
       The actual code goes here.
       ]]>


Script Function Calls

You can use a large number of function calls in a script element that is associated with either a point or the template itself.

The following list includes existing templates that contain each script call:

  • language="Delphi":
    • InvokeClassCompletion
    • InvokeCodeCompletion (see delphi\trycf.xml)
    • PopulateCase(|expression|) (see delphi\case.xml)
    • DeclareVariable(|variable|) (see delphi\trycf.xml)
    • RemoveTemplate (see delphi\inlinevar.xml)
    • ValidateForTemplate (see delphi\fors.xml)
  • language="C":
    • invoke_code_completion (see c\whiles.xml)
    • populate_case($expr$); (see c\switch.xml)

See Also