Clarion Community Help

RIGHT-CLICK the procedure in the Application Tree, then choose Embeds from the popup menu (or press the Embeds button in the Application Tree dialog) to open the Embedded Source dialog to embed source code using alphabetically or logically ordered named embed points.

or

RIGHT-CLICK the procedure in the Application Tree, then choose Source from the popup menu to open the Embeditor to embed source code within the context of surrounding generated code.

or

RIGHT-CLICK on a control in the Window Designer, then choose Embeds from the popup menu to access the embed points for a single control.

Clarion's templates let you add your own customized code to many predefined points inside the standard code that the templates generate. It's a very efficient way to achieve maximum code reusability and flexibility. The point at which your code is inserted is called an Embed Point. Embed points are available at all the standard events for the window, the window controls, and for many other logical positions within the generated code. The embed points are determined by the templates. You can even add your own embed points if needed. See #EMBED.

Embedding source code in a procedure lets you fully customize the procedure. The Application Generator saves the embedded source in the .app file and integrates it into the template generated source code each time you generate source code.

You can write your own embedded source code or use Code templates to generate the code for you. Once you embed source code in a procedure, the procedure is flagged with an “S” in the Application Tree.

In order to effectively embed code, you should understand the surrounding template generated code. See Learning Clarion and the Template Guide in this help file for more information on the Clarion and ABC Templates and the code they generate.

Several ways to Embed Source Code

Clarion provides several powerful methods for embedding source code. There are advantages to each of these methods as noted below:

·The Embeditor (choose Source from the popup menu) lets you see the embedded source code within the context of the surrounding generated code and gives you the full power of the Text Editor, including text search and replace, copy and paste, the Populate Fields toolbox, and File Import.

·The Embedded Source dialog (choose Embeds from the popup menu) lets you see only the embed points and their code, without the surrounding code. It gives you the full power of the Text Editor, plus a locator to find embed points, plus tools for moving and copying entire embed points with multiple blocks of embedded code, and for generating embedded code with Code templates.

·The Embeds button for a control (choose Embeds from the Window Designer's popup menu) gives you the power of the Embedded Source dialog focused on the embed points for a single control.

Source code embedded with the Embeditor is fully accessible with the Embedded Source dialog and vice versa.

Using the Embeditor

1.From the Application Tree, RIGHT-CLICK the procedure, then choose Source from the popup menu.

The Embeditor generates a temporary source file with optional comments and shading to identify all the embed points for the selected procedure. You may insert source code into the embed points simply by typing the new source statements into the unshaded or white area.

You may configure the Embeditor's temporary source file with the Application and Editor tabs of the Application Options dialog. Choose Tools Application Options.

The Embeditor is the Text Editor opened in a special mode which allows you to not only edit all the embed points in your procedure, but to edit them within the context of template-generated code. The Embeditor displays all possible embed points for the procedure within the context of all the possible code that may be generated for the procedure. Notice the distinction here–Embeditor does not show you the code that will be generated, but all the code which could be generated, if you placed code into every available embed point.

2.Press to scroll to the next embed point.

scrolls to the previous embed point; scrolls to the next filled embed point; scrolls to the previous filled embed point.

3.Place the insertion point in the unshaded area, then type your source code.

The full power of the Text Editor is at your disposal. See the Text Editor help topic for more information.

The Embeditor automatically indents your source code at least as far as the embed point comments. You may indent farther (to the right), but you may not indent less (to the left).

4.Choose from the toolbar menu, then save when prompted.

The Embeditor automatically puts your source into the appropriate embed point and sets the priority for the embedded code.

Embedded Source Dialog

1.From the Application Tree, RIGHT-CLICK the procedure, then choose Embeds from the popup menu.

This opens the Embedded Source dialog, providing access to all the embed points in the procedure. You can also get here from the Embeds button on the Procedure Properties window, but the popup menu is quicker.

You may sort the embed points in alphabetical order or in logical order with the Application tab of the Application Options dialog. Choose Setup Application Options from the menu.

Filter the embed points list by choosing from all available embeds or only “filled” embeds. Locate an embed point by typing its name in the locator field near the top of the dialog.

You may configure the available list of embed points with the Application tab of the Application Options dialog. Choose Tools Application Options.

To embed code associated with a specific control, open the Window Designer, RIGHT-CLICK the control and choose Embeds from the popup menu. Only those embed points associated with the selected control are listed.

2.Select an embed point then press the Insert button.

This opens the Select Embed Type dialog. There are three ways to create the embedded source code: hand-coding with the text editor, calling another procedure, or embedding a Code template.

You may combine one or more of these three methods at a single embed point–that is, a single embed point accepts multiple “blocks” of embedded code. You can control the execution sequence of each block of code relative to any other code in the embed point by setting its priority. Lower priority numbers execute before higher priority numbers.

The Embedded Source dialog displays the embedded source in the order it generates and executes.

To “hand-code” embedded source with the Text Editor

1.Select SOURCE in the Select Embed Type dialog.

2.Press the Select button to start the Text Editor with a blank source code window.

This opens the Text Editor. The display includes a Populate Field toolbox from which you can select variable names and field names. Simply CLICK on an item in the toolbox to insert its fully qualified name at the insertion point.

3.Write your custom code in the source code window.

Don't forget to use the on-line help for explanations and examples of Clarion Language syntax and techniques. Copy and paste directly from the help examples!

4.Choose from the toolbar menu, then save when prompted.

5.Optionally set the Priority for the embedded source.

The Priority of each block within an embed point controls the execution sequence of the code relative to any other code in the same embed point. Lower priority numbers execute before higher priority numbers. Set the custom priority number in the spin box. Standard template generated code generally takes the default priority, so you can place your code before or after the template generated code by setting a lower or higher priority number.

Call a Procedure

1.Select Call a Procedure in the Select Embed Type dialog.

A dialog named for the embed point opens to accept the name of the procedure to call.

2.In the Procedure to Call field, type a name for the procedure or choose an existing procedure from the drop-down list.

Typing a new name tells the Application Generator to add the procedure to the Application Tree as a “To Do” item. If another procedure with the same name already exists, the Application Generator generates code to call it.

You define the functionality of the other procedure separately.

3.Press the OK button to close the dialog.

Use a Code template to generate the embedded code

1.In the Select Embed Type dialog, select a Code template then press the Select button.

Code templates are the items indented beneath the Class folders.

This displays a Prompts for… dialog box.

2.Read the instructions and explanations in the dialog.

Each code template includes explanatory text on its proper use and how to fill in the necessary options.

3.Fill in or choose from the options in the Prompts for… dialog.

4.Press the OK button to close the dialog.

Managing Embedded Source

The Embedded Source dialog contains several tools that let you control the sequence in which embedded source is listed and executed. and buttons to change the order of multiple embedded source items; execution occurs in the order they are listed.

There are also Delete and Properties buttons, plus Cut, Copy, and Paste buttons for maintenance. To Cut and Paste (or Copy and Paste) embedded source from one embed point to another:

1.In the Embedded Source dialog, highlight a line in the tree diagram.

Highlighting an embed point line (folder icon) selects all the embedded source at this embed point for subsequent cut and paste operations. Highlighting a single embed source item selects only that item.

2.Press the to cut, or press the button to copy.

3.Again, highlight a line in the tree diagram.

4.Press the button to paste.

Copying Embedded Source Between Procedures

Occasionally you will create two or more procedures that are very similar and that require lots of embedded source code. Rather than retype the embedded source in the similar procedures, you can copy the embedded source as follows:

1.Develop and test the embedded code in your first procedure.

2.Choose Application Selective Export.

3.Specify a .TXA file to receive the exported procedures, then press OK.

4.Select all the similar procedures for export, then press .

Selected procedures for export are colored in red.

5.With your favorite text editor, open the .TXA file and copy the embed definitions from the finished procedure to the other similar procedures, then save the .TXA file.

The embed definitions commence with the [EMBED] line.

6.In Clarion Win32, choose File Import Txa.

7.Specify the .TXA file, then press Open.

The import replaces the procedures in the the .APP with the procedures from the .TXA, with the embedded source code intact.