Clarion Community Help

Adding Embedded Source to a Procedure

·RIGHT-CLICK the procedure in the Application Tree, then choose Embeds from the popup menu (or press the Embeds button in the Application Tree) 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

·In the Procedure Properties, select the Embeds tab 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 in the online Template Language help.

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 the icon in the Application Tree.

In order to effectively embed code, you should understand the surrounding template generated code.

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, code completion,and the Data / Tables Pad.

·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, with the exception of Code templates, which are only modifiable with the Embedded Source dialog.

1.  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 shading and optional comments 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 Setup Application Options. See Configuring the Environment'Action for Legacy embeds and Editor.

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 lesson 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.Press the Save and Close Button to save your changes and Exit the Embeditor.

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

2.  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 Tools Application Options from the menu.

2.Filter the embed points by choosing from the View menu or by pressing buttons on the toolbar. Choose from:

Text Buttons (not on toolbar):

Insert

Opens the Select Embed Type dialog, which allows you to add handwritten source code, call a procedure, and/or choose a code template.

Properties

Allows you to edit the embedded code. If it is hand written code, then the Text Editor appears. If it's a code template, the prompts dialog for the code template appears.

Delete

Allows you to delete embedded code you previously added.

Move Up/Down

Moves the embedded code item up or down another (modifying the Priority). Each executes in the order they appear at an embed point.

Priority

Sets 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.

Filled

Press this button to call the Embeditor, allowing you to only show embed points that actually have had source code entered into them.

Source

Press this button to call the Embeditor, allowing you to see your embedded source in context.

Expand All

Fully expand the embeds list.

Contract All

Fully contract the embeds list.

Expand Filled

Expand only the filled embeds.

Toolbar Buttons

Show Filled Only

Show only filled embeds.

Show Priority Labels

Show template generated embed point labels so you can precisely interleave your code with template generated code.

Show Legacy Embeds

Show Clarion 2.x embed points.

You may set the default for legacy embed points with the Application tab of the Application Options dialog. Choose Setup Application Options. See Configuring the Environment'Action for Legacy embeds.

Show Window Embeds

Available only when editing embeds for a control, this button allows you to expand the view to show embeds for the window.

3.Locate an embed point by typing its name in the locator field near the top of the dialog, or by choosing from Navigate menu or by pressing buttons on the toolbar. Choose from:

Previous Filled

Scroll to the next filled embed point.

Next Filled

Scroll to the next filled embed point.

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.

4.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.

3.  Custom (hand-code) embedded source with the Text Editor

1.Press the Insert button in the Embeds dialog. The Select Embed Type window is displayed.

2.Select Source in the Select Embed Type dialog.

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

This opens the Text Editor (see Text Editor for more information). The display includes access to the Data / Tables Pad from which you can select variable names and field names. Simply CLICK on an item in the toolbox and DRAG it to the window to insert its fully qualified name at the insertion point.

4.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!

5.Press the Save and Close button to close the Editor and save changes.

6.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.

4.  Call a Procedure

1.Press the Insert button in the Embeds dialog. The Select Embed Type window is displayed.

2.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.

3.In the Embed: Procedure Call dialog, type a name for the procedure or choose an existing procedure from the 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. See Defining Procedure Properties.

4.Press the OK button to close the dialog.

5.  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. See the Code Templates section in the online help for descriptions of the Code templates included with this package.

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. The Priority spin control and the and buttons change the order of one or more embedded source items; execution occurs in the order they are listed.

There are also Delete and Properties buttons, plus standard 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 OK.

Selected procedures are identified with a check mark.

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. See the Advanced Programming Resources PDF for more information on TXA file format.

6.In Clarion choose Application Import Text.

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

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

Next: Lesson 16 - SQL, ODBC and ADO application support