| **Navigation:**  [[welcome to my product .htm|User's Guide and Tutorials]] > Writing Clarion Code >====== Source/Text Editor ====== | [[project system lesson.htm|{{btn_prev_n.gif|Previous page}}]][[welcome to my product .htm|{{btn_home_n.gif|Return to chapter overview}}]][[formula editor.htm|{{btn_next_n.gif|Next page}}]] |
|  ||

This lesson introduces the Source/Text Editor.

If you allow the Application Generator to write most of your source code, you will probably only use the Text Editor to write your embedded source code (see Application '[[lesson 15 customizing the application source embeds.htm|Embedded Source Code]]). If you write your source code "from scratch," you will probably use the Text Editor extensively to create and manage your code. The Text Editor features the following to help you accomplish either purpose:

·Multiple Document Windows, in which you may edit as many documents as your system allows.

·Color coded syntax highlighting, which makes reading individual code lines easier. The color coding is fully customizable.

·Always available Search and Replace.

·Auto-indent, to make reading and writing code easier.

·Next Error and Previous Error locator.

·Current cursor position (row and column), displays on the status bar.

·Configuration options to customize the Text Editor to fit your needs.

·F1 hyperlink sensitive help for all Clarion Language statements.

·Code folding and code completion options.

·Ability to create user-defined [[icsharpcode sharpdevelop gui optionpanels codetemplatepanel.htm|macros]].

** **

**Opening the Text Editor**

**Anytime you view a source code document with Clarion, you use the Text Editor. Here are several ways to open a source code document:**

** **

·In the IDE Menu, choose **File** {{blttria.jpg|BLTTRIA.jpg}} **New** {{blttria.jpg|BLTTRIA.jpg}} **File** to open the //New File// dialog. Select the appropriate **Category** and type of file in the **Quick Starts**. This opens a blank source code document. After editing, when you close the file, you can navigate to your target directory and fill in the name of your new file in this standard dialog. Then press the **Save** button.

·Choose **File** {{blttria.jpg|BLTTRIA.jpg}} **Open **{{blttria.jpg|BLTTRIA.jpg}} **File**, select the Clarion **Files of type** source, then DOUBLE-CLICK a source code file in the standard Open File dialog.

·Use the **Start Page** to view your most recently edited files. Select the **Source Files **section, and click on a source code file entry.

·In the //Solution Explorer//, DOUBLE-CLICK on any source (.CLW) file to open it.

·After a compile that generates errors, DOUBLE-CLICK on any entry in the //Errors Pad//.

·In the //Application Tree// dialog, RIGHT-CLICK a procedure, then choose **Source** to open the Embeditor (Text Editor in a special embedded source mode).

·In the //Application Tree// dialog, RIGHT-CLICK a procedure, then choose **Module** to edit a generated source module.

For the Icons used in the Source and Text Editor, see the [[icon quick reference guide.htm|Icon Quick Reference Guide]] help topic.

**Managing Text Editor Windows**

Each source code file appears in a separate document window. This section provides a summary of actions you can take to change the layout of these windows:

{{texteditor.jpg|TextEditor.jpg}}

**The Editor's document window features color-coded syntax highlighting.**

**Close a window**

Choose **File** {{blttria.jpg|BLTTRIA.jpg}} **Close** {{blttria.jpg|BLTTRIA.jpg}} **File** from the main menu, or press the "X" in the client area, or RIGHT-CLICK on the tab, and select **Close**, or press CTRL+F4.

**Activate a window**

Click anywhere within the window, or select the document name from the **Window** menu. Alternatively, press CTRL+F6, or CTRL+SHIFT+F6 until the window you wish is active.

**Move a window**

Drag the document window's tab with the mouse, and dock it where desired.

**Resize a window**

Drag its border with the mouse.

**Maximize a window**

Press the maximize button on the IDE title bar; or choose **Maximize** from the window's system menu.

**Iconize a window**

Press the minimize button on the IDE's title bar; or choose **Minimize** from the window's system menu.

**Restore iconized**

To restore an iconized document window, DOUBLE-CLICK the IDE tray icon; or choose **Restore** from the icon's system menu.

**Cycle to next window**

To switch to the next window, press CTRL+F6 or CTRL+SHIFT+F6.

**Feature Tour**

**Full visual control**

Control your display colors, line numbers, rulers, and enable or disable the features that you need.

{{envcolors.jpg|EnvColors.jpg}}

**Configurable with different file extensions**

The Text Editor has built-in configurations for over 9 different extension groups, including Clarion!

{{fileext.jpg|FileExt.jpg}}

**Support for code folding**

{{folded.jpg|folded.jpg}}

**Code Completion**

The new Text Editor can assist you with completing language constructs and classes

{{codecompletion.jpg|codecompletion.jpg}}

**Code Templates**

Code Templates or Snippets can be added and used anywhere in the Editor!

{{codetemplates.jpg|CodeTemplates.jpg}}

**Customizable Smart Indentation**

The Text Editor offers two text indentation modes. Smart indentation is fully customizable.

{{smartindent.jpg|smartindent.jpg}}

**Quick Class Browser**

The optional Quick Class Browser allows a quick jump to any CLASS method or PROCEDURE:

{{quickclassbrowser.jpg|QuickClassBrowser.jpg}}

**Go to'options**

You can jump to any method or procedure's definition or declaration, rename it, and identify the references.

{{goto.jpg|GoTo.jpg}}

**Powerful Search and Replace options.**

The Text Editor has a versatile and flexible Search/Replace interface, where you can search an individual file, or an entire project or drive/directory:

{{searchreplace.jpg|SearchReplace.jpg}}

**Built in special XML Editor and Code Completion**

Finally, there is a special XML editor and menu system:

{{xml.jpg|xml.jpg}}

**Customizations**

We suggest that before you start with any serious editing session that you first browse and explore the Text Editor Options. With very little effort, you'll find a comfort setting that will ensure success and optimize your productivity.

To access the Text Editor Options, select **Tools > Options > Text Editor **from the main IDE menu:

{{editoroptions.jpg|EditorOptions.jpg}}

Nearly everything you need to customize the editor is contained in this section.

In the **General** section, you can set the custom font type and size used by the editor, and enable or disable the code folding and Quick Class Browser.

The **Markers and Rulers** section controls rulers, line number display and style, and visual display and limits of tabs, spaces and the editor cursor (caret).

The **Behavior** section controls your indentation options, caret behavior, and mouse wheel direction.

**Clarion Specific Options** give you added control to the Smart Indentation mode, and includes other auto-formatting features.

The** Code Completion** section allows you to enable or disable its use, and adds other options as to storage and code completion behavior.

The **XML Options** and **Schema** sections control the XML editor add on behavior in general.

Finally the **Highlighting** section displays all built-in file extensions and their highlighting schemes. This area is very detailed and specific for many elements within the text editor.

**Using the Quick Class Browser**

When viewing any Clarion source file in the Text Editor, it is often necessary to locate program dependencies. In other words, one source file might contain a procedure that is calling another procedure.

The Text Editor enables a Quick Class Browser, and enabled or disabled in the **Tools > Options > Text Editor > General** dialog.

{{qcbsetting.jpg|QCBSetting.jpg}}

This utility is anchored on top of the Text Editor as shown here:

{{quickclassbrowser2.jpg|QuickClassBrowser2.jpg}}

The left drop list displays all global declarations, and is useful whenever the program's global section is active:

{{globaldeclaration.jpg|GlobalDeclaration.jpg}}

When the global source is active, a list of global classes, files and record structures are listed. Clicking on any element will jump directly to that structure.

Once a structure has been targeted in the global section, the drop list on the right displays the sub elements of the target structure. For example, if a FILE is selected, the drop list on the right will display all elements in that structure that are not part of another structure. In most cases, this would be KEYs, MEMOs, and BLOBs.

If a RECORD structure is selected, a list of Fields are displayed:

{{qcbfields.jpg|QCBFields.jpg}}

Finally, each of the program's module will display a complete list of prototypes:

{{qcblist.jpg|QCBList.jpg}}

This tool is very handy locating all prototypes and references, and when used with the "Find References" option, can be an invaluable debugging technique.

**Code Completion**

Code Completion is a feature provided by the Clarion text editor that involves predicting a word or phrase that the user wants to type in without the user actually typing it in completely.

{{codecompletion2.jpg|codecompletion2.jpg}}

Code Completion can be used to find a desired method. In the code sample shown above, typing "SELF." displays a popup of valid methods that can be used here.

The same also applies for language statements. For example:

{{codecompletion3.jpg|CodeCompletion3.jpg}}

The word INSTRING, followed by an open parentheses, displays a popup of 3 valid choices that match the INSTRING function.

**Code Snippet Wizards**

In addition to the Quick Class Browser and Code Completion as powerful language tools, there is also support in the Text Editor for Code Templates (or Code Snippets). We use the term "Snippets" here as not to confuse them with the Code Templates used in the Application Generator.

Here is how they work. After assigning the target file extension group, a template name and optional description is added or assigned to the extension group. For each name, a section of custom code is added. Pressing a hot key at any place in the editor activates this list of code templates.

Code Snippets are configured in the **Tools > Options > Coding** section as shown below:

Code Templates are assigned by file extension. Built into the IDE are preset Code Templates for HTML, CS (C Sharp), and VB (Visual Basic).

To add the Clarion extensions to the Code Template section.

1.Press the **Add New Group** button.

2.In the Extensions prompt, add the clarion source extensions (.clw;.inc)

3.Press the **Add** button. In the **Edit Template** dialog, add the //Template// code word, and an optional //Description//.

4.Finally, in the text area below, enter the actual code sequence.

Here are a few sample entries:

{{codetemplates3.jpg|CodeTemplates3.jpg}}

This list can be as extensive as you like. You will probably want to add the construct that you use more often, and also include the more complex code sequences.

To apply (use) the code templates in your target source, press **CTRL + J** at any time. You will see a display similar to the Code Completion popup:

{{codetemplates4.jpg|CodeTemplates4.jpg}}

**Go to Definition/Declaration**

Another powerful feature included in the Text Editor is its ability to recall any method's definition and corresponding declaration.

To see this, you can right click on any PROCEDURE definition or declaration in any CLASS. For example:

{{gotodeclaration.jpg|GoToDeclaration.jpg}}

In the popup menu shown above, if you click on "GoTo Definition":

{{gotodefinition.jpg|GoToDefinition.jpg}}

This feature is very handy in large projects and multiple source files, as the GoTo will span files.

**Search Features**

The Clarion Text Editor has a very powerful Search and Replace dialog. To activate it at any time from within the editor, press **CTRL + F**.

This dialog serves both Find and Replace options. Clicking on the Replace toolbar button adds an additional **Replace with:** prompt.

You can search single or multiple documents using this dialog, and optionally replace the target search string.

For example, in the following code project, I am looking for all instances of //Init//

In the **Find what **prompt**, e**nter //Init//. You can also select a previous search string from the drop list.

{{findwhat.jpg|FindWhat.jpg}}

The **Look in** option sets the range of the current search. You can search in the active open document only, the selected elements of an active document, all open documents, the entire active project or entire solution (where multiple projects are possible). Press the ellipsis button to select an external folder to search. If you are searching in a target folder, check the **Include sub-folders** box to allow the search to cascade into any sub-folders.

{{lookin.jpg|LookIn.jpg}}

If your **Look in** option is a folder, the **Look at these file types: **prompt is enabled. Enter the file type extensions to search into. Use a semicolon to separate multiple extensions.

You can also limit your search using the **Match Whole word** only or **Match Case** before clicking on the Find Next button.

The last decision is the type of search to execute. //Standard// search looks for the exact string in the Find dialog. //Regular Expressions// searches based on the result of a valid expression entered. Basically, a regular expression is a pattern describing a certain amount of text. Their name comes from the mathematical theory on which they are based. Your regular expressions require the C# syntax. //Wildcards// allows the use of wildcard characters in the search string.

After the search above, here are our search results:

{{searchresults.jpg|SearchResults.jpg}}

398 occurrences may not be effective. Let's narrow it down a little more:

{{searchresults2.jpg|SearchResults2.jpg}}

Or maybe we just need to add a little more to the search term:

{{searchresults3.jpg|SearchResults3.jpg}}

**Code Folding**

Another popular editor feature in this release is the use of Code Folding.

Code Folding is popular with many developers because it allows them to collapse sections of source code while working in other parts of it. This allows you to manage larger amounts of code within one window.

You enable or disable code folding by accessing the option in **Tools > Options > Text Editor > General:**

{{codefolding.jpg|CodeFolding.jpg}}

The + and ' icons control the code folding. When code is folded, you can move your mouse over the ellipsis button to see a partial popup of the folded contents.

**Indentation**

Indentation within the Text Editor is controlled in the **Tools > Options > Text Editor > Behavior** dialog.

{{indentation.jpg|Indentation.jpg}}

The new Text Editor has three indentation modes.

//None// provides no indentation at all. As you press the Enter Key, the editor caret (the blinking cursor) is always returned to column 1.

//Automatic//

With Indentation set to Automatic ,the Text Editor keeps a running indent. When you press the Enter key, spaces and tabs are inserted to line up the insert point under the start of the previous line.

//Smart//

After a keyword statement, the next line is indented by the tab size set above. After certain keywords (break, return etc.) the next line is "non-indented".

Other rules for Smart indentation include:

·Indent statements from the CODE keyword position. The default is "on".

{{smart1a.jpg|smart1a.jpg}}

·Treats any expression that ends with a colon ":" as a label in the CODE section (The default is off, where colons are treated as an actual procedure call). You need to have the caret position at the beginning of the target statement, and then press Enter.

{{smart1.jpg|smart1.jpg}}

·Indent a line after the Enter key is pressed at the end of the line. The default is on.

{{smart2.jpg|smart2.jpg}}

·Indent pasted text if several lines were pasted. The default is "off".

{{smart3.jpg|smart3.jpg}}

·Preferred indentation to a specified column number. If a recognized keyword should not be indented relative to the parent, it will be indented to the preferred column. The default setting is column 21.

·Automatic comment indentation. The default is off.

{{smart4.jpg|smart4.jpg}}

See the **Clarion Specific options** dialog to control each of the options described above.