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 '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 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 New 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 Open 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 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:

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

Close a window

Choose File Close 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.

Configurable with different file extensions

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

Support for code folding

Code Completion

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

Code Templates

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

Customizable Smart Indentation

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

Quick Class Browser

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

Go to'options

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

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:

Built in special XML Editor and Code Completion

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

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:

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.

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

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

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:

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

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.

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:

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:

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:

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:

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

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, enter Init. You can also select a previous search string from the drop list.

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.

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:

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

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

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:

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.

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

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

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

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

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

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