| **Navigation:**  [[clarion 7 faqs.htm|How To's and Troubleshooting]] > How to... >====== How to Add Embedded Source Code ====== | [[how to add drag and drop to a list box.htm|{{btn_prev_n.gif|Previous page}}]][[clarion 7 faqs.htm|{{btn_home_n.gif|Return to chapter overview}}]][[how to add hot key display to a menu item.htm|{{btn_next_n.gif|Next page}}]] | | || 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 define embedded source point .htm|#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. {{tipbox.jpg|TipBox.jpg}} You may configure the Embeditor's temporary source file with the Application and Editor tabs of the Application Options dialog. Choose **Tools** {{c6h0013.jpg|C6H0013.jpg}} **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 {{nextembbut.jpg|NextEmbbut.jpg}} to scroll to the next embed point. {{prevembbut.jpg|PrevEmbbut.jpg}} scrolls to the previous embed point; {{nextfembbut.jpg|NextFEmbbut.jpg}} scrolls to the next filled embed point; {{prevfembbut.jpg|PrevFEmbbut.jpg}} 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. {{notebox.jpg|NoteBox.jpg}} 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 {{saveclose.jpg|SaveClose.jpg}} 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 **[[gen72.htm|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. {{tipbox.jpg|TipBox.jpg}} You may sort the embed points in alphabetical order or in logical order with the Application tab of the Application Options dialog. Choose Setup {{c6h0013.jpg|C6H0013.jpg}} 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. {{tipbox.jpg|TipBox.jpg}} You may configure the available list of embed points with the Application tab of the Application Options dialog. Choose **Tools** {{c6h0013.jpg|C6H0013.jpg}} **Application Options**. {{tipbox.jpg|TipBox.jpg}} 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. {{tipbox.jpg|TipBox.jpg}} 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 {{saveclose.jpg|SaveClose.jpg}} 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. {{moveup.jpg|MoveUp.jpg}} and {{movedown.jpg|MoveDown.jpg}} 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 {{cut.jpg|cut.jpg}}** **to cut, or press the {{copy.jpg|copy.jpg}}** **button to copy. 3.Again, highlight a line in the tree diagram. 4.Press the {{paste.jpg|paste.jpg}} 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 **{{c6h0013.jpg|C6H0013.jpg}}** 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 {{saveclose.jpg|SaveClose.jpg}}. 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 **{{c6h0013.jpg|C6H0013.jpg}}** 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.