Add Snippet Dialog Box
Edit Snippet Dialog Box

This dialog box is displayed when either the Database | Add Snippet or Database | 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 dialog 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 to uniquely define a snippet. All the fields are required. They are:

• Source code text box.
  Enter the snippet's source code here. The format of the code is important unless you are using the freeform snippet kind.
• Kind drop down list.
  Select the kind of snippet you are editing.
• Description edit box.
  Enter a description of the code snippet here. This 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.
• Name edit box.
  Give the code snippet a name here. Names must be valid Pascal identifiers with the added restriction that they must start with one of the English letters 'A'..'Z', 'a'..'z' or the underscore character. Names must also be unique within the user database, although they 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' etc.
• Category drop down list.
  Select the category to which the snippet belongs.

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.

• Cross-references check list box.
  Use this list 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.
  User defined snippets are displayed in blue.
• Dependencies check list box.
  Specify any other snippets that this snippet depends upon by checking the boxes next to the desired snippets. 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 available entries in this list box will vary according to the snippet kind.
  Routine snippets are not included in this list if the snippet being edited is a constant or type definition. Freeform snippets are never included in this list.
  User defined snippets are displayed in blue.
• View Dependencies button.
  Click this button to see all dependencies for the snippet being edited in the Dependencies dialog box. All entries checked in the Dependencies list box are included, along with all their dependencies, and so on. You must not create a circular dependency; the Dependencies dialog box will help you detect them.
• Units check list box.
  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. More units can be added to the list – see below.
  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.
• Add Unit edit box and button.
  If additional units are required in the Units check list box type the name of the unit in the edit box and click the Add Unit button. The unit will be added to the Units check list box and its check box will be checked.

Extra Information Tab

This tab is used to provide additional descriptive information about the snippet. Information can be specified using a simple markup language called REML.

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:
  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 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 dialog box closes and the user database is updated.

Click Cancel to abort the edit.