This dialogue box is displayed when either the Snippets | New
Snippet or Snippets | Edit Snippet menu options are
selected. It is used to enter details of a new user defined code snippet
or to edit the details of an existing user-defined snippet.
If a new snippet is being added all controls are blank or set to default
values. When an existing snippet is being edited the controls are
populated with the snippet's existing properties.
Editing the snippet
The dialogue has multiple tabs. All but the Code tab are optional
– others can be used to provide additional information about the
snippet. However, if you plan to test compile the snippet you must ensure
that the snippet's dependencies and units are properly set up on the
References tab.
Code Tab
This tab gathers all the information needed to define a snippet. All the
fields are required. They are:
Name
Enter a name for the snippet in the edit box. The name must be a valid
Unicode Pascal identifier. It must also be unique within the user
database, it may duplicate names in the main database.
It is customary to name functions or procedures using the routine's
name. Overloaded routines are often named by suffixing the routine
name with '_A', '_B', '_C' and so on.
Display Name
Enter a display name for the snippet. When present this name will be
displayed in the main display instead of the snippet's name entered
above. This name may contain any characters and does not have to be
unique.
This is an optional entry. If it is not supplied the value of the
Name control is used as the display name.
The display name is useful where the entry in Name field does
not display well. For example overloaded snippets named
"Foo" may have names "Foo_A", "Foo_B",
"Foo_C" etc., which are not too friendly. To improve this
you could use display names like "Foo (Integer overload)",
"Foo (string overload)", "Foo (Integer,string
overload)" etc.
Description
Enter a description of the code snippet in the
markup editor. You can use more than
one paragraph of text. You have the choice of styling the text and
using hyperlinks.
The description field should not contain "}" characters
since the field's text is used in comments in exported Pascal code and
the "}" character will terminate the comment early.
The description can be previewed using the Preview button.
Clicking this button also validates markup if you have used it.
Select the category to which the snippet belongs from the drop down
list.
Source code
Enter the snippet's source code in this text box. The format of the
source code is important unless you are using the freeform snippet
kind. Learn more.
Syntax highlight this snippet as Pascal code
Tick this box if your snippet is written in Pascal and you would like
the source to be syntax highlighted. Otherwise clear the box. Note
that the built in highlighter only understands Pascal code and will
not render code in other languages correctly.
If you prefer to turn off syntax highlighting completely go to the Syntax Highlighter tab of the Preferences dialogue box, click the Use Predefined
Styles button and select the No Highliter option.
References Tab
Use this tab to specify the snippets and units that are associated with
the snippet being edited. If it is intended to test compile the snippet
then the Dependencies and Units list boxes must be
completed if the snippet depends on a Delphi unit or if it uses another
snippet from the database.
The available controls are:
Cross-references list box
Use this list box to specify any other snippets to be cross-referenced
from this snippet. Check the boxes next to desired snippets. Cross
references are for information only. All snippets are listed, except
for the one being edited.
To deselect all cross-references right click the list box and select
the Deselect All Cross-References option from the context
menu.
User defined snippets are displayed in blue.
Dependencies list box
Specify any other snippets that this snippet depends upon by checking
the boxes next to the desired snippets in this list box. If this
snippet is to be test compiled then any other snippets it requires
must be specified here or the test compile will fail. The exception is
that unit snippets never have any
dependencies.
To deselect all dependencies right click the list box and select the
Deselect All Dependencies option from the context menu.
You can use the context menu to to see all dependencies for the
snippet being edited. This displayed the
Dependencies dialogue box.
All entries checked in the Dependencies list box are
included, along with all their own dependencies, and so on. You must
not create a circular dependency; the Dependencies dialogue
box will help you detect them.
The available entries in this list box will vary according to the
snippet kind and the kind of snippets
it can depend on. For example, constant
snippets can't depend on routine
snippets and unit snippets can't depend
on anything, so the list is empty.
Freeform snippets are never
included.
User defined snippets are displayed in blue.
Units list box
Select any units that this snippet requires in order to compile using
this list box. Required units must be specified if test compilation is
to be attempted. A selection of common units is provided, along with
any units already associated with the snippet.
If the unit you need is not in the list box simply enter its name in
the edit box next to the Add Unit button and click the
button.
Each unit you use is remembered and will appear in the list box in
future. If the list box is getting too full you can remove most units
by right clicking them and selecting Delete Selected Unit
from the context menu. Note that the SysUtils,
Classes, Windows and Graphics
units cannot be deleted.
The list box's context menu also gives options to restore the unit
list to it's "factory" default and to deselect all the units
in the list.
Units are "used" in the order they appear in the list. If
this order causes namespace clashes you should prefix ambiguous
identifiers in the source code with the unit name, e.g.
Graphics.TBitmap.
If you intend to test compile your snippet with Delphi XE2 or later
you will need to make sure the appropriate compiler is configured to
search the namespaces containing the units you list here. Do this in
the Configure Compilers dialogue
box. Use the Namespaces tab to enter the required namespaces.
Click the Defaults button to use a set of namespaces that
works with many of the commonly used units. You can see a list of
namespaces with the units they contain in the Unit Scope Names topic of the Embarcadero RADStudio
documentation.
If any unit is not part of the Delphi RTL or VCL you will need to let
the compiler know where to find the unit. Use the Search
Paths tab of the Configure
Compilers dialogue box to specify the required path. You need to
do this for each compiler separately.
Notes:Unit snippets
must declare their used units in the unit source code, so this list
box is disabled when the snippet kind is unit.
Extra Information Tab
This tab is used to provide additional descriptive information about the
snippet. Use it for information that supplements the snippet's
description or for crediting authors etc.
Enter the required information in the Extra informationmarkup editor. You can enter either plain
text of formatted text and hyperlinks using the custom
REML markup language.
The information can be previewed using the Preview button.
Clicking this button also validates markup if you have used it.
Compile Results Tab
Use this tab to specify any known compiler results for the snippet. You
can specify the required compiler in several ways:
Manually, one compiler at a time using the Set a compile
results list box. Click the drop down button next to the required
compiler then choose the required compile result from the drop down
menu, i.e. one of Success, Warning, Error and
Unknown. To use the keyboard to modify compile results proceed
as follows:
Move the keyboard focus to the list box using the
Tab key.
Select the required compiler using the
Up and
Down keys.
Press Space to drop down the menu.
Select the required result with the
Up and
Down keys.
Press Enter to select the compile
result or Cancel to abort.
Click the Set All To Success button to set every compiler's
result to "success" (green LED).
Click the Set All To Query button to set every compiler's
result "query" (grey LED).
Use the Test Compile button to compile the snippet and set
the compile results accordingly. This button is disabled if no
compilers are configured or if the snippet is
freeform.
If one or more compilers report warnings or errors, a link appears
below the Test Compile button that can be clicked to display
details of the warnings or errors.
You can display the unit used to perform the test compilation by
clicking the View Test Unit button. This can be useful when
tracking down errors.
Commiting the edit
Clicking OK causes the edited snippet to be validated. If an
error is found the control where the error is located is selected and an
error message is displayed. If the snippet is valid the dialogue box
closes and the user database is updated.