# Add Snippet Dialogue Box
Edit Snippet Dialogue Box

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: they are used to enter additional information that can be useful but is not required. However, if you plan to test compile a Pascal snippet you must ensure that the snippet's dependencies are properly set up on the References tab.

### Code Tab

This tab gathers all the information needed to define a snippet. All the fields except Display Name 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, although 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 name entered above. The display name may contain any Unicode character and does not need 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 the 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. More than one paragraph of text can be used. You can enter either plain text or text formatted using CodeSnip's REML markup language.

  The description field should not contain "}" characters since the field's text may be enclosed 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.

- Kind

  Select the kind of snippet from the drop down list.

- Category

  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 page 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 correctly whenever the snippet depends on a Delphi unit or if it relies upon 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 the 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.

- 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 see all dependencies for the snippet being edited. This information is displayed in 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 snippets in this list box will vary according to the snippet kind. For example, constant snippets can't depend on routine snippets and unit snippets can't depend on anything, so the list will be empty. Freeform snippets are never included in the list.

- Units list box

  Use this list box to select any units that this snippet requires in order to compile. 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 ordering 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 using the Namespaces tab of the Configure Compilers dialogue box. You need to do this for each compiler separately. You can find a list of namespaces and 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 information markup editor. You can enter either plain text or text formatted using CodeSnip's 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 compilation results for the snippet. You can specify such results in several ways:

- Manually, one compiler at a time using the Set compile results list box. Click the drop down button next to the required compiler then choose a compilation 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:

  1. Move the keyboard focus to the list box using the Tab key.
  2. Select the required compiler using the Up and Down keys.
  3. Press Space to drop down the menu.
  4. Select the required result with the Up and Down keys.
  5. 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 automatically. 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.

Click Cancel to abort the edit.