EVOLVE is a wrap-around shell for Multi-Edit that works with the XBase language you program in. It watches as you work, adjusting itself to your style where appropriate. EVOLVE automates many of the tedious programming chores that take up so much of your time. Frequently used source code statements are automatically expanded; source files are located for you without hesitation; database structures are viewed with the touch of a key.

Evolve supports many XBase as well as a few non-XBase dialects that have been diverging from the original roots of dBASE since the mid 1980's. Much of the dialect specific support contained in Evolve's macros are identical between XBase languages. However, there are instances where it is necessary to make certain exceptions and these are generally noted in this help guide. The following dialects are supported in Evolve. Additional [and more detailed] information can be found in the following topics: Installation, Configuration, and Passive Productivity and Template Editing.

The primary configuration of Evolve includes the main configuration dialog screen accessed by selecting the Configuration tool bar option, selecting Configuration from the menu or by running the EVCONFIG macro. Since Evolve is highly dependent on Multi-Edit, it's a good idea to totally familiarize yourself with installation and set up issues as well. Other areas that may help you achieve more productivity gains can be found in the manipulation of preprocessor constants located in EVOLVE.SH. While it is likely that all the set up and configuration options in Evolve's configuration dialog will handle most of the customization desired, you may want to browse through EVOLVE.SH to see if there are other items that could be modified to help improve your development productivity.

Within the Filename Extension Setup dialog, Multi-Edit allows you to attach “language styles”. The language style provides configuration fields that enable you to enter keywords, comment styles, and punctuation marks for syntax highlighting purposes. It is important to Evolve that a language style be selected if (and only if) you want Multi-Edit to highlight syntax key words for you. In this case, the language style in Multi-Edit need not be configured with key words. Evolve itself will handle this for you automatically and will adjust the keywords based upon the dialect you select in the Evolve configuration dialog screen. This will make it possible to see key words such as SCAN…ENDSCAN highlighted when the dBASE dialect is selected, and commands such as WHILE…END highlighted when Clipper is selected. Evolve will create and select the proper language styles depending on the dialect you configure Evolve for.

If you desire your own syntax highlighting scheme, you may use any of the above listed language types for custom syntax highlighting configured with your own list of preferred keywords and comment styles. Evolve will automatically add language styles that don't exist and will also fill in the reserved words and comment characters appropriate for the dialect. Once a language style has been added by Evolve, you may then customize the reserved words and other information for the language style using Multi-Edit's installation menu. Evolve will not write over your changes to language styles.

If you ever have the need to reset an Evolve-based language style back to the default settings, simply use Multi-Edit's Languages dialog and delete the style. The next time that style is called for by Evolve, it will be re-created automatically.

Since Multi-Edit includes a complete file extension support system, Evolve has been designed to embrace these features and depend on the resources that provide support for syntax color highlighting and other resident capabilities. The ability to enable Evolve's specialized features only while editing file extensions you identify is founded in the setup and configuration capabilities of Multi-Edit.

Evolve Is Private To Each Window

Evolve utilizes Multi-Edit's internal file extension configuration so that its features are active only in editing windows that have file extensions configured in Multi-Edit. Because of this, it is necessary to identify all of the file extensions you intend to edit with Evolve capabilities, under one extension entry (e.g., for example - PRG;WFM, etc). This is done in Multi-Edit's Tools | Customize | General | Filename Extensions menu.

Multi-Edit's Language Style

Within the filename extension setup, Multi-Edit allows you to attach “language styles”. The language style provides configuration fields that enable you to enter keywords, comment styles, and punctuation marks for syntax highlighting purposes. Evolve requires that a language style be selected if (and only if) you want Multi-Edit to highlight syntax key words for you and set the assignment operator [e.g., the equals sign]. In this case, the language style in Multi-Edit need not be configured with key words. Evolve itself will handle this for you automatically and will adjust the keywords based upon the dialect you select in the Evolve configuration dialog screen. This will make it possible to see key words such as SCAN…ENDSCAN highlighted when the dBASE dialect is selected, and commands such as WHILE…END highlighted when Clipper is selected. Evolve will create and select the proper language styles depending on the dialect you select in Evolve's configuration screen.

If you desire your own syntax highlighting scheme, you may use any of the above listed language types for custom syntax highlighting configured with your own list of preferred keywords and comment styles. Evolve will automatically add language styles that don't exist and will also fill in the reserved words and comment characters appropriate for the dialect. Once a language style has been added by Evolve, you may then customize the reserved words and other information for the language style using Multi-Edit's installation menu. Evolve will not write over your changes once these have been customized.

The EV.CFG file is one of two Evolve configuration files and its purpose is to store and maintain commenting templates and source code report formats. It contains various elements that provide customization to suit your particular commenting and reporting style. Important to the goal of Evolve is that there may be multiple EV.CFG files. Perhaps a different one for each directory you write applications in. Multiple CFG files provide the ability for you to have project sensitive configurations for comment headers, copyright notices, and other information that may vary from project to project.

How Evolve Finds The Right EV.CFG File

When Evolve looks in the current directory for EV.CFG, it looks to see if EV.CFG exists and if not found it does a second scan for EVxxx.CFG (where xxx is the multi-user network ID) also in the current directory. The second scan enables you to create multiple CFG files in the same directory that are dependent on the network user ID for utilization.

The EV.CFG file is installed, by default, to the ME directory where it is used by Evolve as the default CFG file. If you want different CFG formats (e.g., perhaps different default application titles for program headers), you need to make a copy of EV.CFG in the directory where you are working on a specific project. Evolve will use the EV.CFG file found in the current directory first.

Network users will find that as a last resort, Evolve looks for the default EV.CFG file in the USER_ID path before looking to the ME path. This allows you to have different default CFG files for each user on a network in addition to different directory level configurations for each user.

A sample of the format of the CFG file is shown below and may be configured to support your own style of header comment blocks for programs, procedures, and functions. Additionally, the format used for source code printing is established in this file. The CFG File is a standard text file so it can be easily modified at any time with Multi-Edit. The design of Evolve permits modification to this file during an edit session. All changes to this file will become active in Evolve immediately. See the default EV.CFG file that is shipped with Evolve for more header possibilities.

A Sample EV.CFG is shown below:

Sample EV.CFG
[Author]    := John Doe
[Copyright] := Multi Edit Software
[AppTitle]  := Billing Information System
[Cursor]    := {Entry}
[Program Header]
Program
Application:  {AppTitle}
File Name:    {File}
Author:       {Author}
Date created: {DateCreated}         Date updated: {DateUpdated}
Time created: {TimeCreated}         Time updated: {TimeUpdated}
Copyright:    {Yr} by {Copyright}
[Include Header]
Program
Application:  {AppTitle}
Description:  {Entry}
File Name:    {File}
Author:       {Author}
Date created: {DateCreated}         Date updated: {DateUpdated}
Time created: {TimeCreated}         Time updated: {TimeUpdated}
Copyright:    {Yr} by {Copyright}
[Procedure Header]
Procedure
Description:  {Entry}
Author:       {Author}
Date created: {DateCreated}         Date updated: {DateUpdated}
Time created: {TimeCreated}         Time updated: {TimeUpdated}
Copyright:    {Copyright}
Arguments:    {Argument}
See Also:     {Field}
[Function Header]
Function
Description:  {Entry}
Author:       {Author}
Date created: {DateCreated}         Date updated: {DateUpdated}
Time created: {TimeCreated}         Time updated: {TimeUpdated}
Copyright:    {Copyright}
Arguments:    {Argument}
Return Value: {ReturnValue}
See Also:     {Field}
[Print Format]
{h} := Application: {AppTitle}          Page: {Page}
{h} := Source File: {FileName}          Print Date: {DateCreated}
{h} := ----------------------------------------------------------
{h} := Line #   Source
{h} := ----------------------------------------------------------
{b} := {Ln#}  - {Source}
{f} := Author: {Author}                 Copyright: {Copyright}
[eof]

In addition to configuration elements available in the Evolve configuration dialog, there are quite a few “hard coded” preprocessor constants defined in EVOLVE.SH. It is rare that these variables will need to be changed, but they're documented should the need arise.

EVOLVE.SH can be found in the EVOLVE directory and additional details describing changes to this file are discussed in the topic titled Primary Manifest Constants.

Configuration of Evolve is simple and accomplished completely via dialog screens. Much of the control and behavior in Evolve is accomplished through global variables, which are defined in EV_.S, EVOLVE.S, and some are contained in the dialect driver files [such as ev_clipr.s]. Most of the variables may be changed through the Evolve Configuration dialog.

The configuration dialog box can be accessed from the Evolve menu, tool bar, or by using the EVCONFIG command. The variables that are controlled from this dialog provide configuration elements such as the type of comment characters used, the tab level of same-line-comments, certain coding styles, and template expansion controls. The configuration system of Evolve will change the global variables and recompile EV_.S based on the selections made in this dialog.

Configuration support through the EVCONFIG dialog box handles both default and current session changes. Using the 'OK' button applies the changes only to the current session. The 'Save Configuration' button changes the current session and establishes the changes as the start-up default settings.

The configuration format of Evolve enables you to have different configurations for different users on a network. The single-user mode will use the EV_ macro as Evolve's source of configuration for both the key and the global variables that affect the way Evolve behaves. In the case of multi-user environments, the EV_ macro will be replaced with EV_ plus the 3 character User ID. In either case, Evolve will expect the configuration macro to be in the <ME_PATH> directory.

There are a number of primary manifest constants in EVOLVE.SH that you may want to alter to achieve custom performance. Most of these items have to do with areas of Evolve that will generally conform to your needs as shipped. However, tools work best if they work for you, so they have been documented and arranged for easy modification.

The following topics provide additional information concerning modification and performance tuning of Evolve.

In addition to configuration elements available from the Evolve configuration dialog, there are quite a few “hard coded” preprocessor constants defined in EVOLVE.SH. It is rare that you will have to alter the values in these constants, but they're documented in the header file should the need arise. For the most part EVOLVE.SH contains default configuration settings that apply to most XBase development situations. However, we recognize the importance of adaptation [by the tool rather than the programmer] when situations vary. As a result, EVOLVE.SH has been created with various constants so that changes can be made to the behavior of the product without significant understanding of the macro programming language or compiler.

To make a manual configuration change to Evolve, simply edit the EVOLVE.SH file and make the desired modifications to the preprocessor constants. The constants are fairly well commented in the header file, and experimentation with various settings is encouraged. Once the header file has been modified and saved to disk, you will need to recompile the Evolve macros using the EVOLVE.LST recompile file. This file can be found in the Evolve directory and is easily attached to a Windows icon as shown below.

cmacwin.exe -Ievolve;src -Pmac -L evolve\evolve.lst

Use of this recompilation specification is important if you change any of the manifest constants in EVOLVE.SH.

While most of the constants in EVOLVE.SH are self explanatory and well commented, the following items are a bit more complex and have been documented here with additional information.

Some Features May Be Public

Since Evolve is window-dependent with regard to its activeness, we have provided a few constants in EVOLVE.SH that allow you to enable (or disable) some of the popular Evolve key assignments on a public basis (e.g., all windows regardless of file extension). These include the following constants and key assignments which are enabled [by default] in EVOLVE.SH. If you don't want the associated key assignments for these features to be active in all windows regardless of file extension, change the values to zero [0] and recompile the macros.

There are a number of configuration constants in EVOLVE.SH that you may want to change, although it is unlikely. Most of these items have to do with areas of Evolve that will generally conform to your needs as shipped. However, tools work best if they work for you, so they have been documented and arranged in a way that makes it possible to achieve further customization.

To make a manual configuration change to Evolve, simply edit the EVOLVE.SH file and make the desired modifications to the preprocessor constants. Once changed and saved to disk, you will need to recompile the Evolve system using EVUPDATE.BAT. This file can be found in the Evolve directory. EVOLVE.SH includes many different types of constants that control various elements.

If you are going to modify Evolve at this level, please restrict changes to the constants listed in each sub-menu below. Modifying other constants in EVOLVE.SH can sometimes cause problems.

EVc_GENMEMCASE

This manifest constant, when set to zero [0] (the default setting), causes all generated memory variable names derived from field names in a database structure to be generated in proper case format (e.g., cAddress). Other settings for this constant include 1 (all lower case variable names), and 2 (all upper case variable name).

EVc_ENDTEXT

This variable enables the indenting systems to ignore TEXT…ENDTEXT constructs (e.g., text within the construct will never be indented). This constant is set to one [1] by default (ignores the construct). This configuration integer affects real-time and ad hoc indenting features.

EVc_DBFFUNCTIONS

A manifest constant named EVc_DBFFUNCTIONS is included in EVOLVE.SH that enables the addition of third party library function name specifications for purpose of database structure display by pointing and clicking on the function call. This constant simply contains a list of the functions and the number of the argument that holds the file name that you use to open or close databases. Default values for the new constants are shown below.

EVc_DBFFUNCTIONS		' DBUSEAREA(3) NET_USE(1) NETUSE(1) '

EVc_NDXFUNCTIONS

A manifest constant named EVc_NDXFUNCTIONS is included in EVOLVE.SH that enables the addition of third party library function name specifications for purpose of index structure display by pointing and clicking on the function call. This constant simply contains a list of the functions and the number of the argument that holds the file name that you use to open or close your index files. Default values for the new constants are shown below.

EVc_NDXFUNCTIONS	' DBSETINDEX(1) '
EVc_PARENSPACES and EVc_PARENCURSOR

Preprocessor constants exist in EVOLVE.SH that allow you to configure the number of spaces inserted in expanded braces such as parens (), and brackets []. The constants EVc_PARENSPACES, and EVc_PARENCURSOR allow you to control the spaces and cursor position following the expansion of the matching character. Values and the generated results of each value are shown below for configuration of the parenthesis expansion constants.

Preprocessor constants are provided for brackets [] and curly braces {} and behave in the same manner as that shown for the parenthesis.

  EVc_PARENSPACES	EVc_PARENCURSOR	Results
  0			0			()
  1			2			(_)
  2 [default]		2			( _)
  3			2			( _ )

The position of the cursor following the expansion of the closing brace is determined by a second preprocessor constant named EVc_PARENCURSOR. There are also a set of duplicate constants in the header that pertain to bracket ”[]” expansion, however, these constants are set to zero by default.

EVc_RETURNSPACE

This manifest constant provides you with a mechanism to pad additional spaces following the automatic creation of RETURN statements and default return arguments (if any) by the template expansion system. By default, this constant is set to a single space thereby producing “RETURN (…)”. If you remove the space in the #DEFINE statement for EVc_RETURNSPACE (and recompile with EVUPDATE.BAT), the code will be generated without the spaces [i.e., RETURN(…)].

EVc_QTYDOCASE and EVc_QTYELSEIF

One of the great aspects of Evolve is it's ability to be configured to your liking. There are numerous manifest constants contained in EVOLVE.SH, each one providing specific configuration and customization possibilities. One such constant named EVc_QTYDOCASE controls the number of CASE statements generated when you type DOC<space>.

By default, the number is 6 which generates a structure like this:

DO CASE
CASE
CASE
CASE
CASE
CASE
CASE
OTHERWISE
ENDCASE

If you would like more (or fewer) CASE statements you simply need to change the value of EVc_QTYDOCASE to the number of CASE statements desired. Once the value has been changed in the Evolve header file [EVOLVE.SH], you'll need to recompile EV_EXPND.S, or you can simply run EVUPDATE.BAT file. This concept also applies to the quantity of ELSEIF statements generated from the IFI template expansion. The manifest constant that controls the quantity generated is EVc_QTYELSEIF.

In each dialect driver macro, you'll find the supported language definitions stored to a series of global variables. The dialect number, the default index file extension, and other information specific to a given XBase language, are all based on manifest constants in EVOLVE.SH. An example dialect driver for Clipper is shown below.

Dialect Driver Constants
// -----------------------------------------------------------------------
--------------------------------------
// Dialect Specific Constants
// -----------------------------------------------------------------------
--------------------------------------
// CA-Clipper/DOS Support
#define EVc_CLIPR_INDEXEXT	'NTX'	// default index file extension
#define EVc_CLIPR_DATATYPES	'abcnldmox'	// default notation data types
#define EVc_CLIPR_OBJSEARCH	'{%{ *}||{|9*}{static proc}||{proc}||{static func}||{func}||{static meth}}||{%meth}?*'
#define EVc_CLIPR_RESERVED	''
#define EVc_CLIPR_EOLCOMMENT	'//'	// default eol comment style
#define EVc_CLIPR_HEADEREXT	'.CH'	// default header file extension
#define EVc_CLIPR_OPERATOR	':='	// variable assignment operator

These constants exist for each dialect supported by Evolve and they represent an easy way to make subtle changes that are language specific within the supported file extensions of Evolve. The names are self explanatory as well as their purpose. However, caution should be exercised when making modifications to the OBJSEARCH constant. This symbol contains very specific search expressions which could drastically alter the behavior of Evolve. A thorough understanding of Multi-Edit's regular expression syntax is recommended before altering this constant.

Of the most productive features of Multi-Edit and Evolve, template expansion is used most by programmers. Template expansion makes it possible to repetitively generate source fragments by typing just a few characters.

To make the template expansion system work better for you, a new macro file was added to release 6.1 named EV_MPINT.S. It provides a series of programming interface macros that cater mostly to the aspect of template expansion customization and addition of new expansion keywords. The macros for template expansion support include mpiInit() and mpiTemplate().

When Evolve is first loaded, the mpiInit() macro is launched, which simply runs mpiTemplate() with an argument of /I [initialization call]. Thereafter, mpiTemplate() is called every time you press the space bar following the entry of the first word [or character sequence] on a new line. Because this macro is called every time a new “first word” is entered on a line, it provides for a perfect API to the template system.

This mpiTemplate() macro is called from the template expansion macro to test for custom templates that you may have implemented in EV_MPINT.S. As an instructional aid, it includes a sample template named ABC that expands to a code construct in similar fashion to a DO WHILE…ENDDO structure. It demonstrates the ease of creating and integrating a custom template into Evolve's space-triggered template expansion environment.

To add a new template to Evolve, you needn't make any modifications to EV_EXPND.S or any other macro file. Simply duplicate one of the template code segments shown below and modify it to meet the desired results. Note that the characters of the template need to be listed in the string variable named “cTemplates” at the top of the mpiTemplate macro.

Step One: Create The Triggering Character Sequence

The macro code fragment shown below is the first statement in the mpiTemplate() macro. It simply defines a string variable and makes an assignment of a character sequence named ABC. This is intended as an example and may be removed or replaced if desired. The first step in adding a new custom template is to add the triggering character sequence to the string variable cGenText.

Triggering Character Sequences Before New Addition

str 	cGenText,
cTemplates = 'ABC ';

Suppose we want to add a new trigger called MYFUN. The string variable would be modified as shown below. Note the delimiting spaces within the text string.

Triggering Character Sequences After New Addition

str 	cGenText,
cTemplates = 'ABC MYFUN ';

Step Two: Create Code Generation Segment

In this step, we duplicate [or manually enter] a new ELSE IF segment of the mpiTemplate() macro to effectively look for, and respond to the template sequence [in this case, MYFUN<space>. The ABC example is useful as a starting point, but note how [and why] it differs. In this particular example, we are adding an option that generates a function call, rather than a looping construct as the ABC example provides.

New Macro Segment To Generate Code

// MYFUN... ( myFunction(arg1, arg2, arg3) )
} else if( caps(global_str('!EVgPrevWord')) == 'MYFUN ' ) {
	return_int = 1;
	goto_col(global_int('!EVgCurCol') - 
 	length(global_str('!EVgPrevWord')));
	del_chars(length(global_str('!EVgPrevWord')) - 1);
	cGenText = 'myFunction(arg1, arg2, arg3)';
	call WriteLine;
	eol;

The addition of this new ELSE IF segment results in the generation of the following code whenever you type MYFUN<space> at the beginning of a new line. Furthermore, the original key phrase [myfun] is replaced with the generated code.

myFunction(arg1, arg2, arg3)     

Step 3: Recompile EV_MPINT.S

Following any changes to a macro file, the macro must be recompiled before they become activated. From the menu, or from the keyboard, recompile EVMPINT.S, making certain that there are no compiler errors [they'll appear on the message line, depending on the setup attributes of Multi-Edit].

Step 4: Test The New Template Feature

While editing in a buffer window that is supported by Evolve [PRG is most preferred], try typing the new triggering sequence and then press the space bar.

Important Aspects Of The Macro Code

A few of the source code lines in the ELSE IF segment are noteworthy and a thorough understanding of them will help you create superior and custom support for your development environment.

Indicate Successful Expansion – First and foremost, the return_int = 1 statement is important because it informs Evolve's template expansion system that an expansion has taken place in the API, therefore no further search of the internal expansion possibilities are necessary. The result is faster processing of the space character.

Indication Of Successful Expansion

// MYFUN... ( myFunction(arg1, arg2, arg3) )
} else if( caps(global_str('!EVgPrevWord')) == 'MYFUN ' ) {
	return_int = 1;
	goto_col(global_int('!EVgCurCol') - 	length(global_str('!EVgPrevWord')));
	del_chars(length(global_str('!EVgPrevWord')) - 1);
	cGenText = 'myFunction(arg1, arg2, arg3)';
	call WriteLine;
	eol;

Generating The Template Code – Another interesting macro code fragment are the lines responsible for generating code into your program file. First, the code to be generated is assigned to a string variable named cGenText. Then, the WriteLine procedure is called, which takes the pre-assigned memory variable and outputs its contents to the program file buffer.

Generating The Template Code

// MYFUN... ( myFunction(arg1, arg2, arg3) )
} else if( caps(global_str('!EVgPrevWord')) == 'MYFUN ' ) {
	return_int = 1;
	goto_col(global_int('!EVgCurCol') - 	length(global_str('!EVgPrevWord')));
	del_chars(length(global_str('!EVgPrevWord')) - 1);
	cGenText = 'myFunction(arg1, arg2, arg3)';
	call WriteLine;
	eol;

Generating Multiple Lines Of Source Code – If you had the need to generate more than one line of text to the program file buffer, simply re-assign cGenText again, and then call the WriteLine procedure, replicating the same pair of lines until the complete code construct is complete. A good example of this is found in the sample ELSE IF segment that creates the ABC…ENDABC code construct.

// ABC... ( abc...endabc )
} else if( caps(global_str('!EVgPrevWord')) == 'ABC ' ) {
	return_int = 1;
	goto_col(global_int('!EVgCurCol') l;
	length(global_str('!EVgPrevWord')));
	del_chars(length(global_str('!EVgPrevWord')) - 1);
	cGenText = 'Abc ';
	call WriteLine;
	cr;
	goto_col(global_int('!EVgFirstWordCol'));
	cGenText = 'Endabc';
	call WriteLine;
	up;
	eol;

Inserting Blank Lines – Sometimes, it's necessary to create a blank line in the generated source code. While it's possible to simply assign a null string to cGenText and call WriteLine, the quickest and most efficient approach is to use the Multi-Edit primitive called CR.

// ABC... ( abc...endabc )
} else if( caps(global_str('!EVgPrevWord')) == 'ABC ' ) {
	return_int = 1;
	goto_col(global_int('!EVgCurCol') l;	length(global_str('!EVgPrevWord')));
	del_chars(length(global_str('!EVgPrevWord')) - 1);
	cGenText = 'Abc ';
	call WriteLine;
	cr;
	goto_col(global_int('!EVgFirstWordCol'));
	cGenText = 'Endabc';
	call WriteLine;
	up;
	eol;

Moving The Cursor – There are also times when cursor movement is required during the code generation process, and it's relatively straightforward. Multi-Edit includes primitive functions that can be used to change cursor position as demonstrated by the boldfaced macro statements.

// ABC... ( abc...endabc )
} else if( caps(global_str('!EVgPrevWord')) == 'ABC ' ) {
		return_int = 1;
		goto_col(global_int('!EVgCurCol') l;	length(global_str('!EVgPrevWord')));
		del_chars(length(global_str('!EVgPrevWord')) - 1);
		cGenText = 'Abc ';
		call WriteLine;
		cr;
		goto_col(global_int('!EVgFirstWordCol'));
		cGenText = 'Endabc';
		call WriteLine;
		up;
		eol;

Adding comments and marking or un-marking source code with comment characters can be extremely time consuming. EVOLVE assists you in this aspect of development by providing you with just a single tool bar button to handle eight different commenting features. The different behaviors of this single tool bar button are accomplished by applying various block marks to the source code before clicking the button. For example, the commenting support macro behaves a certain way when there is a column mark, and a completely different behavior is derived with a line mark.
Explore the features listed below for more details.

Place a same-line-comment at a designated comment column by simply clicking the comment button with the cursor resting on a line of source code. The comment column is defined in the Evolve configuration dialog and by default is set to 50. In the event that the source code on the line being commented exceeds 50 characters, then the commenting system will position the same-line-comment to the end of the line plus two characters.

FUNCTION __SetGraphics
parameters mode
if mode
		sethires(0)
	else
		settext()
	endif
RETURN(.T.)

If the comment button is utilized while the cursor is positioned on a blank line, the position of the comment will be anchored to the location of the cursor at the time the comment button was clicked. If the comment key is pressed on a line that is already commented with a same-line-comment, the cursor will move to the beginning of the comment text.

Using the column mark, begin a block mark with the first line of text to be included in the commented area. Make sure the column mark is located at the column you want the comment characters to be written. Continue the column mark until the last line in the text to be commented is reached. The column mark need only be a single character in width. Then click the comment button. The block mark will disappear and each line in the block will be commented.

Using a column mark, begin a block mark with the first comment character to be uncommented. Continue the column mark until the last line in the commented area. The column mark need only be a single character in width but must start in the same column as the current comment characters. Then click the comment button. The block mark will disappear and each line in the block will be uncommented.

Using the stream mark, begin a block mark with the first line of text to be included in the commented area. Continue the block mark until the last character in the text to be commented is reached. Then click the comment button. The block will disappear and the beginning and ending of the block will be enclosed in the C style comment.

Using the stream mark, begin a block mark with the beginning C style comment characters. Then continue the block mark until the ending C style character sequence has been marked. Click the comment button. The block will disappear and the marked block will be uncommented. This commenting style is not available in all XBase dialects.

Place the cursor on a source line containing a FUNCTION statement and click the comment button. A comment header will be displayed. The header design and layout is programmable and defined in EV.CFG. More details concerning headers can be found in the Commenting Support section of this guide. Information concerning the layout and programmability of headers can be found in the EV.CFG Configuration File topic.

Place the cursor on a source line containing a PROCEDURE statement and click the comment button. A comment header will be displayed. The header design and layout is programmable and defined in EV.CFG. More details concerning headers can be found in the Commenting Support section of this guide. Information concerning the layout and programmability of headers can be found in the EV.CFG Configuration File topic.

Place the cursor on a source line containing a CLASS or DEFINE CLASS statement and click the comment button. A comment header will be displayed. The header design and layout is programmable and defined in EV.CFG. More details concerning headers can be found in the Commenting Support section of this guide. Information concerning the layout and programmability of headers can be found in the EV.CFG Configuration File topic.

Place the cursor on line one and press the comment key. A comment header will be displayed. The header design and layout is programmable and defined in EV.CFG. More details concerning headers can be found in the Commenting Support section of this guide. Information concerning the layout and programmability of headers can be found in the EV.CFG Configuration File topic.

Most XBase dialects support #INCLUDE capabilities that allow the inclusion of header files into program source. This feature makes it possible for you to pre-configure comment headers for these types of files in a custom format and insert them into your source files in an instant.

To see this feature in operation, place the cursor on the first line of a header file [.H or .CH file extension] and click the comment tool bar item. A default comment header will be displayed instantly. Like Evolve's program headers, #INCLUDE headers are defined in EV.CFG. More details concerning comment headers can be found in the Commenting Support section of this guide. Additional information concerning configuration of comment headers can be found in the topic EV.CFG Configuration File.

The Comment Headers feature makes it possible to create standardized headers that serve as comment blocks for header files, program files, procedures, and functions. The headers are configurable in ordinary text files so they're easy to create and modify while using Multi-Edit.

Additionally, Evolve can support multiple header configurations without re-installing each time you need a different header format. This ability is easily accomplished because Evolve first looks for the configuration file in the current directory, and then looks in the Multi-Edit path. This enables you to create different EV.CFG files in all the directories you develop applications.

When the current directory is scanned for EV.CFG, Evolve looks to see if EV.CFG exists and if not found it does a second scan for EVxxx.CFG (where xxx is the multi-user ID) The second scan enables you to create multiple headers for multi-user environments in the same directory.

The header templates also support meta command words that are linked to information in the configuration file. For example, the template command word {Author} will expand to the author name as set forth in the EV.CFG file. See the example EV.CFG file later in this chapter.

Headers are automatically inserted whenever you create a function or procedure with the template expansion features of Evolve. Additionally, the headers can be inserted manually by positioning the cursor at line 1 in a program file, and pressing 'Ctrl+F7'. Evolve assumes that you want a program header comment since the cursor is at line one, and there are no column or block marks present to indicate a normal comment operation is desired. Additionally, this assumption is made when the cursor is on a FUNCTION or PROCEDURE statement.

The format of the CFG file is shown below and may be configured to your own header commenting layout and style. Note that the larger the header structure, the longer it will take Evolve to read it in and parse the meta command words.

You can also create your own template keywords (meta commands) by simply using a new bracketed word in the static definition area (i.e., the top of the CFG file), the value assigned at the top will be carried to the body of the header and inserted wherever your custom meta command appears. In fact, all commands in the sample CFG file we provided, are meta commands (i.e., they're not hard coded in Evolve) with the exception of the following commands which are system value dependent or source code dependent (e.g., they are automatically created if Evolve can discern their values from your source code).

Meta commands in your header configuration file (EV.CFG) will be ignored if the information they require cannot be discerned from the source code within the body of the construct. Additionally, default entries for {Argument} and {ReturnValue} are entered if these are not detected in the source code. Each will be entered as “None” if not found. The default values are also definable in EVOLVE.SH using a manifest constant.

An additional configuration option allows you to specify a different format for parsed arguments in addition to the one where the meta command {Argument} is utilized. This feature makes it possible to create comment headers that do not include the first argument line continuously replaced as many times as there are arguments for the function. Instead, an alternative argument line can be inserted for arguments number [2] through [n].

By defining a new configuration item in EV.CFG as shown below, the output of the function or procedure header will utilize the defined format whenever the number of arguments parsed exceeds 1.

[Multiple Argument Line]
* {Argument}

The default EV.CFG file provided with Evolve includes this exact definition of the [Multiple Argument Line]. When you create a different header format, it is important that you modify this section of EV.CFG to correspond with your new header format, otherwise multiple argument lines may look awkward. If you prefer multiple argument lines to be the same format as that found in the header definitions, simply delete the [Multiple Argument Line] section from the configuration file.

A meta command exists that enables you to position the cursor to any of the variables defined in the comment header templates. The name of the static command is [CursorPos] and is set to a value in the same manner that all other static commands are set such as [Author], etc. The assignment in EV.CFG looks like this:

[CursorPos] := {Entry}

Wherever the first {Entry} appears in a comment header, the cursor will be repositioned there once the header is inserted. Additionally, Multi-Edit will be switched into overtype mode if characters are detected to the right of the entry point AND the preprocessor constant “EVc_COMMENTOVERTYPE” is set to one [1] in EVOLVE.SH. By default, this is the behavior of Evolve unless you change EVc_COMMENTOVERTYPE to a zero [0] and recompile your macros.

The meta command {Field} enables you to create a “form” based on the header comment templates. Insert this meta command wherever you want the cursor to stop following after the insertion of any of the comment headers available in the EV.CFG file. When this feature is utilized, the cursor is positioned to the first field and Multi-Edit is placed in overtype mode if enabled by setting EVc_COMMENTOVERTYPE to one [1].

With each press of the 'TAB' key, Evolve will continue to re-position the cursor to each {Field} discovered in the comment header template. The order of the entry positions is determined by the same order as discovered in the header during insertion into the source code.

For example, the following excerpt from the default EV.CFG will create a procedure style comment header and move the cursor to the line and column where {Field} appears in the header template, thereby allowing you to enter the various prompted items.

[Program Header]
*****************************************************************
*Program
*Application:	{AppTitle}
*File Name:		{File}
*Author:		{Author}
*Date created:	{DateCreated}	Date updated: {DateUpdated}
*Time created:	{TimeCreated}	Time updated: {TimeUpdated}
*Make File:		{MakeFile}
*Exec File:		{ExecFile}
*Copyright:		{Yr} by {Copyright}
*----------------------------------------------------------------
*Notes:		{Field}
*			{Field}
*			{Field}
*			{Field}
*			{Field}
*****************************************************************

Following insertion of a header with {Field}'s in it, the 'TAB' key will continue to reposition the cursor to the next line. When the last field has been reached, the very next 'TAB' key press will attempt to position the cursor to the first line of the function or procedure being commented. In the case of Program and Include file comment headers, the cursor will finally come to rest at line one of the source buffer.

The Prototype command provides a way to extract a summary listing of all functions and procedures in a source file and instantly convert the listing into a commented summary at the top of the source file.

Programmers familiar with “C” development requirements recognize this as a “prototype” of each function so that it can easily be known what functions are in the source file, and what arguments are required. This is also known as a form of forward declaration of the function which is not required in any XBase dialect [yet].

When you run the Prototype command, a menu listing similar to the Scan menu will appear allowing you to browse through the function listings. From this menu, select “Update Prototype Comment Table” to add the listing as a comment block. If a prototype table already exists in the source file, it will be replaced with a new one, otherwise, the listing will be dropped at the cursor location prior to the execution of the prototype feature.

The prototyping system allows you to display and insert the prototype tables sorted by routine type (e.g., procedure/function/method) and by routine name. This feature is enabled by default but may be disabled by changing the controlling preprocessor constant in EVOLVE.SH named EVc_SORTPROTOTYPE.

The output format from the prototyping system provides an informative header with columns for the routine name and the return value of functions contained in the listing. If you prefer a simpler format found in earlier versions of Evolve, simply change the preprocessor constant named EVc_FANCYPROTOTYPE to a zero [0] and recompile the macros.

In this category of features, active productivity enhancements are discussed. This class of productivity features requires some interaction on your part.

This feature allows you to complete the currently open conditional construct and is accessed through the toolbar or from the menu. It is used at a point where you need to type the ending statement of an indentable code construct.

This macro simply back-dents the cursor one level, and then proceeds to scan up through the source code at the back-dented indent level, looking for the beginning construct statement. It does not parse the source code in reverse, so if your source code is not indented properly, it may fail to find the proper beginning construct resulting in unpredictable behavior.

In the case of the automatic completion of RETURN statements for functions, the return value inserted into the statement is derived from the return value specified in Evolve's configuration. Please refer to the Configuration topic for additional details.

Template files are simply text files that contain the code fragments for each control type. There is one template file for each language supported by CommonTools. The template file naming convention is based on the file extension of the source code files. For example, when writing code in PAS files, the template file name utilized by CommonTools is CTPAS.TEM. For C++, it files, it will likely be CTCPP.TEM or CTC.TEM. For XBase developers, the template file is CTPRG.TEM.

Note: If you develop code in more than one file extension for the same language, copy the original template for that language so that it exists for the additional file extension. As an example, if you customarily program in PAS files and you would like to have CommonTools support source files with extensions of P, copy CTPAS.TEM to CTP.TEM.

Template files are similar to Windows INI files and include template sections identifying each control type. A sample control type and associated template code is shown below.

[MenuObject]
DEFINE MENU .?. OF this..?.
   PROPERTY ;
      text    “.?.”, ;
      helped  “.?.”, ;
      onclick {.?.}

As indicated, each control type is identified with its name in brackets (i.e., [MenuObject]). The control type names should not be changed unless you have reviewed the CommonTools API topic and understand the impact of such a change. The source code following the control type name is the code template that actually expands when the control is selected from the tool bar.

Optionally, the beginning of template files may include certain configuration items such as enabling upper and lower case expansion, or disabling argument prompting.

Template files are searched for by CommonTools in the following manner. If the search turns up nothing for the current file extension, an error message is displayed.

1st	Current [working] directory as CTxxxnnn.TEM where xxx is the file extension and nnn is the user id.
2nd	me_path + user_id + .USR\ + CTxxx.TEM.
3rd	Current [working] directory as CTxxx.TEM.
4th	me_path + CTxxx.TEM.

Control Types refers to the different controls [sometimes called objects] supported by CommonTools. One type of control is a text object [e.g., a string displayed on a form or in a window]. Another type is a spin box [an integer entry field with arrows for incrementing and decrementing the value].

Control types, in most object oriented languages, are universal to some degree, however, the source code necessary to create such objects varies from language to language. The control types supported in CommonTools are representative of many popular languages as well as configurable in the event the support is not specific enough for your development style.

To make a particular control expand to its code equivalent, certain conditions must exist.

First, there must exist a CommonTools template file for the file extension of the current buffer. If you are editing a Pascal source file with a
PAS file extension, the template file CTPAS.TEM must exist in the current working directory, the Multi-Edit directory, or a user directory [for Multi-Edit network installations].

Second, the specified template file must contain a code fragment definition for the desired control type. For some languages, there may not be a way to represent certain control types common to other languages. In these infrequent cases, the template file will contain an entry as shown below.

[MenuObject]
Not Supported…

And third, the line that the cursor is resting on must be a blank line. CommonTools will not expand if the current line already contains text.

Once the code has expanded, CommonTools will position the cursor in an attempt to prompt you for required [or optional] arguments in the source statements. Prompts are identified in a template with .?. character sequences so they're easy to identify. When the first argument is typed, simply press 'TAB' to advance to the next prompt. CommonTools will erase the .?. sequence for you and position the cursor accordingly.

Some aspects of expansion are configurable. See the next topic entitled Expansion Configuration.

It is possible to configure certain behavioral aspects of CommonTools through expansion configuration settings. The topics on the following page provide complete details.

Argument Prompting

This refers to the automatic prompting of arguments once a template has expanded. By default, CommonTools will automatically position the cursor to specific locations in the template to allow completion of required [or optional] parameters in the code fragment. The following example shows a template where prompting has been disabled.

Prompts	- on
***********************************************************
 |CA-Clipper|
***********************************************************

Case Expansion

Templates are expanded in Proper Case format which is how they exist in the template file. Case expansion can be controlled by adding a template configuration line at the beginning of the template file. For example, to force expansion in upper case, the following template configuration line accomplishes this.

Prompts	= proper
***********************************************************
 |CA-Clipper|
***********************************************************

CommonTools has a fixed set of control pushbuttons, however, you may attach many different types of code fragments to each button. If more than one code fragment is present in the template file for the same control type, CommonTools will present each of the fragment names in a pick list so that you can decide which one to choose. Here's an example of a TEM file programmed for multiple code fragments for the Window control type.

[Window - MDI Child]
DEFINE WINDOW .?. MDICHILD FROM .?., .?. TO .?., .?. TITLE .?. ;
             BRUSH .?. CURSOR .?. MENU .?. ICON .?. OF .?.     ;
             VSCROLL HSCROLL COLOR .?., .?. PIXEL STYLE .?.
[Window - MDI Parent]
DEFINE WINDOW .?. FROM .?., .?. TO .?., .?. TITLE .?.          ;
             STYLE .?. MENU .?. BRUSH .?. ICON .?. MDI         ;
             COLOR .?., .?. VSCROLL HSCROLL BORDER .?. OF .?.
[Window - Regular]
DEFINE WINDOW .?. FROM .?., .?. TO .?., .?. TITLE .?.          ;
             COLOR .?., .?. OF .?. BRUSH .?. CURSOR .?.        ;
             ICON .?. MENU .?. STYLE .?. BORDER .?. NOSYSMENU  ;
             NOCAPTION NOICONIZE NOZOOM VSCROLL HSCROLL

The Window type identifies that all of these fragments are of the same class of template. The text to the right of the dash [-] is a description and may include up to 64 characters of text.

An enormous amount of time is spent entering the same pieces of text, time and time again. EVOLVE helps cut down on this repetition by providing automatic expansion of “templates”. To put it simply, a template is an abbreviation that explodes into more complete code fragments.

Template expansion is designed to eliminate keystrokes and to that end, Evolve continually watches for specific character sequences in an attempt to spot words, phrases, and even entire code snippets that can be expanded for you. For example, when you type two 'I' characters back-to-back, Evolve assumes you are typing an immediate IF function “IIF()” function.

Key Assignment: ”, ', {, [ and (

Some commands in XBase languages require the presence of a terminating command such as the ENDIF statement for each IF statements. The same principal applies to certain character sequences as well. For example, unless you were writing a compiler or something similar, you would rarely need a double quote character by itself.

Evolve contains five specific template expanders that automatically add the second character when the first is typed. By default, the key assignments for these expanders are enabled. You may disable these expansion templates in the Evolve's Configuration dialog. The configuration section is entitled Passive Expansion Items.

The Brace Completion system helps you by closing the next logical brace enclosure in a line of source code. For example, once a series of braces have been entered into an expression or command line, Clicking this tool bar item will search back to determine which level of brace enclosure is required to complete the expression. This is very handy when developing complex, multi-line/multi-brace enclosures. For example, given this line of source code:

 Func1( * MyArray[n, * 100.5 (12 / 144), iif(n == 1, 1, 0 

With the cursor positioned at the end of the expression, each click of this tool bar button will complete the next required brace closure yielding a completed expression as shown below.

 Func1( * MyArray[n, * 100.5 (12 / 144), iif(n == 1, 1, 0)]) 

Macro Command: InsertKeyCode

This feature enables you to enter your languages' keyboard control codes or keyboard preprocessor constants by simply pressing the key combination desired. For example, let's assume that you needed to create an argument involving 'Alt+U' but you didn't know the key code. Simply press 'Ctrl+K' followed by 'Alt+U' and Evolve will insert the proper code for the currently configured dialect directly into your source code.

The key code that is entered will vary depending on the dialect that you are using. Dialects that support preprocessor constants will automatically generate the key code constant, whereas, those that do not, will insert the actual key code.

Clipper Developers

To enter a key code preprocessor constant such as those defined in INKEY.CH, simply click the key code tool bar button (which activates the key code dialog) and then press the desired key or key stroke combination. Evolve will insert a key constant at the cursor location in the current PRG file.

Other Dialects

To enter a key control code, simply click on the key code tool bar button (activates the key control expansion dialog) and then press the desired key combination. Evolve will insert a number or standard constant representation at the cursor location in the current PRG file.

Control over what is generated into the program file via the keyboard is stored in the dialect macros (i.e., EV_CLIPR.S, EV_DBASE.S…) and may be modified easily. Make sure you don't create more than 100 keyboard translation elements in each of the two global variables that store the control codes. These variables are named !EVgKeyCodes1 and !EVgKeyCodes2.

Assignment Character Insertion And Formatting

The assignment character insertion and formatting feature in StickyTab makes it easier to enter memory variable or field assignments in a formatted manner. Each time the 'TAB' key is utilized on a line immediately following an assignment statement, Sticky Tab will intercede causing a single 'TAB' press to align beneath the previous equals sign and enter the next equals sign. The following code fragment demonstrates this productivity enhancement.

By pressing the 'TAB' key immediately after entering “nVar”, the Sticky Tab feature inserts the equals sign directly beneath the equals sign on the previous line and positions the cursor to the appropriate entry point. This feature is only triggered when the line immediately above contains an assignment operator such as ”

Local Variable Creation

The StickyTab button and the 'Tab' key can now be used to create local variable declarations for new memory variables in a function, method, procedure or class. Simply type the new variable just as though you normally would, then create a stream block mark around the memory variable [an easy way to do this is to simply double click on the memory variable]. Then press the 'Tab' key or click the StickyTab button [var=].

Evolve will test to see if the local variable highlighted is already declared in the current function. If the variable has not been declared, a LOCAL statement will be inserted at the top of the function for this memory variable. If other LOCAL statements are already present, the new declaration will be created after the last LOCAL statement in the current function.

Key Assignment <SpaceBar>

The expansion of the assignment operator is automatic when Evolve detects a memory variable convention that expounds the data type of the variable with a leading character followed by an upper case character [i.e., cAddress]. This practice of using the leading character of a memory variable to identify it's type is known as dHUNG notation and is considered somewhat of a standard in many languages including C and C++.

For example:

The variable naming convention known as dHung [described above and utilized by Evolve] is shown in the following chart.

Preprocessor Templates

Key Assignment: Various [#in, #ifd<sp>, #ifn<sp>, #el, #en, #u, #d, #c, #t, #xc, #xt]

Hash (#) expansion for preprocessor directives and conditionals includes support for the following code constructs and vary depending on the dialect in use.

If you type any of the above identifiers, Evolve will instantly expand to the full construct and position the cursor to the appropriate entry point. Case consistency is preserved in the expansion unless it has been configured differently. For example, if you type #IN, the resulting expansion will be fully upper cased. Hash (#) directives will expand only once on a given line, at the beginning of the line.

Key Assignment: ii and II

The immediate IIF() expansion template is automatically created when Evolve detects two consecutive letter 'I' characters typed. The cursor will be repositioned after the expansion to enable entry of the arguments. Most XBase languages support this function capability.

Key Assignment: <SpaceBar>

Boolean templates are automatic code expansions for the words .OR., .NOT., and .AND..

Evolve is always on the lookout for a dot[.] followed by the letters “O”, “N”, or “A”. If it detects a period followed by one of these letters, either upper or lower case, it will automatically expand to the appropriate Boolean word and one additional space character. This is known as a Passive Productivity feature.

Further configuration is possible by enabling True and False expansion for .T and .F triggers. This is recommended only if the dialect in use supports constants such as True and False. If your dialect supports #DEFINE preprocessor capabilities, you can create constants to support the use of the words TRUE and FALSE.

Key Assignment: <Spacebar>

Whenever you begin a command line with text that would indicate a code construct is being typed, Evolve will automatically expand the rest of the code necessary to complete a valid statement or series of statements.

The expansion takes place when you press the space bar key after typing specific characters that represent one of the expansion templates. For example, when you type IF '<space>' on a new line, Evolve will enter ENDIF on a new line below, and return the cursor to the line where the IF statement was typed. This is called template editing.

As with all code generation features in Evolve, this one will produce case sensitive source based upon the way you type. For example, if you type the template characters in lower case, the expanded code will also appear in lower case, and so forth for proper and upper case typing. This behavior can be modified to always produce upper case template statements.

To suppress construct template expansion, simply de-select the desired features in the Evolve configuration dialog screen and save the new configuration. See the Configuration section above for more details.

Depending on the dialect in use, some or all of the templates listed below will be available to you. See the chart below for a list of the various automatic templates available in most dialects.

This...			Expands To This...

If <sp>			If
			Endif

Ife <sp>		If
			Else
			Endif

Ifi <sp>		If
			Elseif
			Elseif
			Elseif
			Endif

Pro <sp>		* Header... (if automatic comment headers are enabled)
			Procedure
			Return

This…			Expands To This…
Fun <sp>		* Header...
			Function
			Return(Nil)

Doc <sp>		Do Case
			Case
			Case
			Case
			Otherwise
			Endcase

Dow <sp>		Do While
			Enddo

Tex <sp>		Text
			Endtext

#Ifd <sp>		#Ifdef
			#Endif

#Ifn <sp>		#Ifndef
			#Endif

FoxPro Only:

This...			Expands To This...

For<sp>		        For   = 1 to
			Endfor

Beg <sp>		Begin Transaction
			End Transaction

Sca <sp>		Scan
			Endscan

Pri <sp>		Printjob
			Endprintjob

dBASE Only:

This...			Expands To This...

Beg <sp>		Begin Transaction
			End Transaction

Sca <sp>		Scan
			Endscan

Pri <sp>		Printjob
			Endprintjob

For <sp>		For   = 1 to
			Next

Clipper Only:

This...			Expands To This...

For <sp>		For   := 1 to
			Next

Beg <sp>		Begin Sequence
			End Sequence

Spro <sp>		* Header... (if automatic comment headers are enabled)
			Static Procedure
			Return

Ipro <sp>		* Header... (if automatic comment headers are enabled)
			Init Procedure
			Return

Epro <sp>		* Header... (if automatic comment headers are enabled)
			Exit Procedure
			Return

Sfun <sp>		* Header... (if automatic comment headers are enabled)
			Static Function
			Return(Nil)

Met <sp>		* Header... (if automatic comment headers are enabled)
			Method
			Return(Self)

Smet <sp>		* Header... (if automatic comment headers are enabled)
			Static Method
			Return(Self)

Whi <sp>		While
			End

Cla <sp>		* Header... (if automatic comment headers are enabled)
			Class
			End Class

Cre <sp>		* Header... (if automatic comment headers are enabled)
			Create Class
			Endclass

Con <sp>		* Header... (if automatic comment headers are enabled)
			Constructor
			Return

This class of features provides support that helps you develop and maintain clean looking and easy to read source code.

Macro Command: ALIGN

This macro will align assignment operators and their values.

Using a column mark in Multi-Edit, mark the lines of source code containing the assignment operator statements [i.e., statements such as nVar = 0]. When marking the area, position the cursor to the column that you want all of the ”

Using this feature, source code that originally looks ragged, becomes much more readable.

This feature also supports the processing of +=, -=, *=, =, and /= operators for those language dialects that support them. Furthermore, continuation lines within one of these structures are indented to the level of the first expression following the operator. See the example re-alignment below.

Before...                               After…

MyMemVar += aArray[1, 1] =;             MyMemVar += aArray[1, 1] +;
         .        aArray[2, 1] +;                   aArray[2, 1] +;
         .        aArray[3, 1] +;                   aArray[3, 1] +;
         .   aArray[4, 1] +;                        aArray[4, 1] +;
         .      aArray[5, 1] +;                     aArray[5, 1] +;

Macro Command: INDENT

Evolve's indenting capabilities are supported by a high-speed macro that scans your source code and adjusts all command and comment lines to proper indenting format. To execute this macro, you may run it from the Assist menu, the tool bar, or directly as a Multi-Edit macro command.

Control Structures

Many of the control structures supported by Evolve's indenting system are listed below. Note, however, that there are some differences between the various XBase dialects supported by Evolve. A complete list of the indented control structures are presented in the Code Construct Templates topic.

For ..	Do While ..	While ..	If ..	#Ifdef ..		Begin ..
   ...		  ...	     ...	  ...		...		     ...
Loop		Loop		Loop		Else	#Else			Loop
   ...		  ...	     ...	...		...	     	     ...
Exit		Exit		Exit		...		...		Exit
   ...		  ...	     ...	Elseif	#Endif	Recover
   ...		  ...	     ...					     ...
Next		Enddo		End		Endif				End

Procedures, Methods, and Functions

The following table identifies the indenting style for procedures, functions, and other routine types in all dialects supported by Evolve.

No RETURN Indent Backdent On RETURN Undent After RETURN
Procedure … Procedure … Procedure … Return (untouched) Return Return

Case Constructs

No CASE Indent CASE Indent
Do Case Do Case
Case Case … Case Case … Otherwise Otherwise
Endcase Endcase

In some cases, you will want to leave certain sections of code indented the way that you established them when they were typed. To accomplish this, the extended comments {NoIndent} and {Indent} have been created. By placing a same-line-comment with the extended comment {NoIndent}, indentation will be suspended during the INDENT process thus ignoring all source code lines thereafter until the extended comment {Indent} is encountered. For example:

if ...
replace name with cName,;	// {NoIndent}
		address with cAddress,;
		city with cCity,;
		state with cState,;
		zip with cZip	// {Indent}
	select ...
endif

Support for continuation line indenting is available in both the real-time indenter and ad-hoc indenting facilities. Source lines with a continuation character [;] at the end of the line are indented a second level if this capability is enabled in Evolve's Configuration dialog.

Nested RETURN Statements

Nested RETURN statements have always been a difficult situation with Evolve. In this release, there are some improvements on this topic and this discussion may help you understand the reasons the product behaves as it does.

With the evolution of XBase languages and object oriented programming abilities, we now have to deal [not only with nested RETURNS] but also with nested functions and procedures, sometimes called methods. The indenting possibilities and preferences are enormous, given this new set of parameters. Since it's difficult for Evolve to be “all knowing” and understand exactly what indenting format you want under varying situations, it must follow a specific set of rules.

The rules also vary depending on whether you're discussing the real-time indenting facility, or the ad-hoc indenting system. Each set of features behave differently and there are specific reasons. The ad-hoc [or reindent] macro looks at each line of code in sequential order before making an indenting decision. As a result, it can make better decisions within a specific context. The real-time indenter has less information to work with. To make it smarter would require a significant amount of code parsing each time you press the enter key and this would adversely affect performance.

The rules are relatively simple.

Inside A Function Or Procedure:

If a RETURN statement occurs greater than one indent level from the left margin, and it's inside a FUNCTION, back-denting is disabled. This makes
it possible to maintain back-denting for the last RETURN statement in functions and procedures while disabling RETURN statement back-denting at any higher indent level. Any RETURN statements that occur beyond indent level one are considered nested RETURN's and will not require back-denting.

Inside A Class Construct:

If a RETURN statement occurs greater than two indent levels from the left margin, and it's inside a CLASS construct, back-denting is disabled. This makes it possible to maintain back-denting on the last RETURN statement in a nested method within the CLASS construct. This rule is necessary because the method's RETURN statement will be at indent level 2 or less. Any RETURN statements beyond indent level two will obviously be nested RETURN's within a method and will not require back-denting.

Here is the general format that Evolve follows when indenting code with the re-indent feature as well as real-time indenting.

class myClass of yourClass
   Local mVar
   [code]...
   FUNCTION myMethod()
      [code]...
      IF [code]...
         return (0)
      ENDIF
   return (0)
   [code]...
endclass
function myFunction(cVar, nVar4, dVar, cVar)
   [code]...
   IF [code]...
      return (0)
   else
      IF [code]...
         return (1)
      ENDIF
   ENDIF
return (0)

A Word About Preprocessor Conditionals

In the past, if indenting was on, Evolve indented preprocessor conditionals just like normal conditional statements. However, in Evolve For Windows, there is a new configuration item that enables/disables conditional preprocessor statements. If you nest functions, procedure or classes inside conditional preprocessor statements, we strongly recommend that this new configuration item be disabled [unchecked].

This feature provides an easy way to reformat a multi-line XBase statement. Designed primarily for object oriented statements, it can rearrange [and properly reindent] a multi-line OOP command in an instant.

Simply place a column block mark at the desired indent level for all lines involved in the command and click the reformat icon.

Evolve will align the source code to the selected column and will indent the object oriented statement appropriately. Keywords such as FIELDS, and PROPERTIES trigger yet another indent level during the reformatting process.

In addition to the reformatting of the source code itself, all same-line comments will be repositioned as well.

The default report format is shown below, and may be changed by simply changing EV.CFG. This makes it possible to have different formats for each directory you develop applications in.

[Print Format]
{h} := Application: {AppTitle}			Page: {Page}
{h} := Source File: {FileName}			Print Date: {DateCreated}
{h} := ----------------------------------------------------------
{h} := Line #   Source
{h} := ----------------------------------------------------------
{b} := {Ln#}  - {Source}
{f} := Author: {Author}				Copyright: {Copyright}

The report form may contain three separate form blocks. The HEADER, BODY, and FOOTER. Also note that the format may also contain references to meta commands defined in the static area of the CFG file. For example, you can use the {Author} meta command anywhere in the report form provided it has also been established at the top of the CFG file.

The HEADER and FOOTER may have numerous lines, although from a practical standpoint it is not suggested that you have more than a handful for either headers or footers. The BODY of the report is limited to one line, and since the intent is to print textual information in a sequential order, there is not a great deal of room for creativity in this regard.

More time is spent moving around files, databases, and source libraries than any other process in application development. Evolve addresses this problem by providing a number of ways of navigating as quickly as possible.

Display Current Function Name

Match Construct

This feature allows you to jump forward or backward to the end or beginning of a conditional or looping construct. Using the 'Ctrl+M' key with the cursor placed on an IF statement will cause the cursor to scan forward to the next line at the same indent level. Invoking this feature on anything but the beginning of the construct will cause the search to move up the file.

Object Editing

By simply pointing at a function, procedure or #INCLUDE file name, EVOLVE can find the targeted object, and display it for viewing or editing. Simply place the cursor on the first character of the object and click the object icon. If the object can be found, EVOLVE will present it in a window. If the object is already in memory, such as an #INCLUDE file, EVOLVE will switch to that window.

Source Code Scanner

The Local Scan and Global Scan keys will launch a local and global scan of the current buffer and all buffers respectively. EVOLVE will scan for the word at the current cursor location. This can be a function call, a procedure name, a database name, or any other word found in your source code. The scanner is considered a navigation aid because the resulting scan list can be used as a menu to select an occurrence and have immediate access to that occurrence.

Database Structures

Again, the objects icon will locate and display the database structure of a DBF file by positioning the cursor at a USE or SELECT statement. Additionally, the DBUSEAREA() function is supported for structure display.

Preprocessors have become a helpful and sometimes required aspect of XBase development. If you don't currently use their features, we suggest you become acquainted with the concepts and features in a preprocessor before investigating these unique Evolve features.

Create New Constant

Macro Command: CREATECONSTANT

This feature is a preprocessor constant generator that creates manifest constants while utilizing the text at the cursor position as the basis for transference to a header file in the form of a #DEFINE statement.

To utilize this macro simply place the cursor on a string or integer value that you want to convert to a preprocessor constant, and click the Create New Constant button. Before clicking the button, the cursor should be positioned on the first quote mark of a string to be converted to a manifest constant, or on the first number of an integer value. Optionally, a stream-type block mark can be used to identify the string or number to be changed into a constant, however, in the case of a string, the block mark must include both quotation marks surrounding the text.

A dialog box will display prompts for the constant value that is under the cursor, the constant name that you want to assign, a comment entry (attached as a same-line-comment to the generated #DEFINE statement), and the destination file for the insertion of the #DEFINE. The dialog box also includes a pick list of all #INCLUDE'd files found in the buffer and their paths based on the DOS environment variable INCLUDE. Evolve will set the default destination of the new manifest constant to the current program file. In any case, all prompts in the dialog box can be overridden.

Show Constant Value

Macro Command: SHOWCONSTANT

This feature provides a useful viewing facility for preprocessor constants that may be stored in immediate source files or external header files. This allows you to see the value of a preprocessor constant without actually navigating to the header file or #DEFINE statement that establishes the constant.

For example, with the cursor placed on a known constant that is #DEFINE'd in a header file, click the Show Constant Value tool bar button. Evolve will search the current buffer for the #DEFINE statement, and if unsuccessful, will begin a search of all header files #INCLUDE'd in the current file starting with the last header file first. This feature also searches all current buffers for the #DEFINE statement in the event that the sought after header file is in memory and being altered. The search through all buffers in memory can be disabled in EVOLVE.SH.

List Available Constants

List Available Constants provides a fast way to select and insert a previously defined preprocessor constant. When invoked, this macro looks backwards through the current PRG file and loads each header file identified in a #INCLUDE statement and builds a list of all #DEFINE statements.
You may then choose from the list, inserting the constant at the cursor position.

Database Structures

Macro Command: DISPLAY

This feature is a gateway to many capabilities of Evolve. The DISPLAY command allows you to instantly view the file structure of any DBF file in a scrollable window. Additionally, options to perform other tasks related to database file structures are available once the file structure is on screen. Limited index structure viewing is also supported through the DISPLAY command although the file structure information available differs depending on the type of index being viewed. The index structures currently supported include:

NTX - Clipper indexes
NDX - dBASE Indexes
IDX - FoxPro non-compact indexes
CDX - FoxPro multiple compact indexes
MDX - dBASE multiple indexes

MEM file displays are also possible, however, only the standard MEM file structure utilized in dBASE III Plus and dBASE IV are supported. The various macro command formats supported for the DISPLAY command are shown below.

Macro Command Result

DISPLAY Displays a pick list prompt
DISPLAY [*.DBF] Displays DBF pick list
DISPLAY [*.MEM] Displays MEM pick list
DISPLAY [*.IDX] Displays IDX pick list

Once the database structure is displayed, it is also possible to generate FIELD, LOCAL, PRIVATE, and scatter/gather array structures based on the database structure.

Display DBF File Structures

Accessing a DBF structure is done by using the DISPLAY command, or the objects icon. When using the objects icon, you must position the cursor on a statement that references a DBF file. The following access rules apply and require that the cursor be positioned within these statements if using the objects icon.

DBUSEAREA(.T., "DBFNTX", "SAMPLE.DBF")
USE Sample ALIAS Sample
NET_USE("SAMPLE.DBF")
SAMPLE->field
SELECT Sample	

Position the cursor anywhere on the words shown in bold and the file structure for SAMPLE.DBF will be displayed when you click the objects icon.
Optionally, Evolve automatically displays a database file structure if the alias name is entered into a program file followed by ”→” and a space bar. This gateway will also allow you to select the field name from the structure display and insert it directly into the source code following the alias directive statement.

Display Options

The DISPLAY options include various utilities to create text files from the structure, instant comment blocks, STORE and REPLACE statements, and hard copy output.

If you attempt to access a database file in this manner, and the file cannot be found in the current directory or the specified path in the DBF environment variable, a dialog box will prompt you for a manual selection of the desired database file.

DBF Environment Variable

To facilitate a more complete search for the database file, Evolve first looks in the current directory for the file, and then looks through all paths of the DBF environment variable for databases and index files. For example, the following DOS command establishes a relative directory and one specific directory for database and index file searching.

C> set dbf=data;c:\database

In this case, regardless of the current directory, Evolve will always search the DATA directory for DBF and IDX files.

Build Comment Block

In the DISPLAY window, select this option to instantly create a commented block representing the file structure. The comment block will be inserted at the point where the cursor was last positioned before the DISPLAY command was invoked and the indent level will also assume the last cursor position. Optionally this feature can create a text file of the DBF file structure in a new Multi-Edit window.

Fancy Structure Format

The DBF structure feature that generates comment blocks, printer, and file output provides a fancy format. The output of DBF structures in the above format is enabled through a preprocessor constant named EVc_FANCYSTRUCTURE. This constant is located in EVOLVE.SH. You may disable the fancier output of DBF structures by simply changing this constant to a zero [0] and recompiling the Evolve macros.

Field → MemVar

This option will build source code statements that will STORE the fields of the DBF file into memory variables. The source code will be created where the cursor was last positioned before the DISPLAY command was invoked. The indent level of the generated code will be established at the cursor column. The alias name used is based, by default, on the file name of the database. However, you may specify a different alias name in the Alias: field of the file display dialog box. A sample output is shown below.

MemVar → Field

This option will build source code statements that will REPLACE the fields of the DBF file with memory variables. The source code will be created where the cursor was last positioned before the DISPLAY command was invoked. The alias name used is based, by default, on the file name of the database. However, you may specify a different alias name in the Alias: field of the Display dialog box.

Declare FIELDs

This selection will generate FIELD declarations based on the database structure display for dialects that support this type of syntax.

FIELD 	Name,;	&& Declare fields for SAMPLE.DBF...
		Address,;
		City,;
		State,;
  		Zip

Declare LOCALs

This selection will generate LOCAL declarations based on the database structure display for dialects that support this type of syntax.

LOCAL	cName,;	&& Declare local memvars for SAMPLE...
		cAddress,;
		cCity,;
		cState,;
 		cZip

Declare PRIVATEs

This selection will generate PRIVATE declarations based on the database structure display for dialects that support this type of syntax.

PRIVATE 	cName,;	&& Declare privates for SAMPLE...
		cAddress,;
		cCity,;
		cState,;
 		cZip

Array Scatter

This selection will generate code suitable for the configured dialect that will scatter database fields to an array with an alias name that matches the database. An example using the Clipper dialect is shown below.

aSample := ARRAY(FCOUNT())
AEVAL(aSample, {|xExpression, nField| aSample[nField] := ;
FIELDGET(nField)})
FoxPro:
SCATTER TO aSample
dBASE:
COPY TO aSample

Array Gather

This selection will generate code suitable for the configured dialect that will replace database fields from an array with an alias name that matches the database. An example using the Clipper dialect is shown below.

AEVAL(aSample,{|xExpression,nField|FIELDPUT(nField,xExpression)})
FoxPro:
GATHER FROM aSample
dBASE:
REPLACE FROM aSample

Print Structure

The print option simply outputs a text version of the DBF file structure to the printer.

There are various ways to create functions and procedures. Review the features listed below for more details.

Code Writer

Macro Command: CWRITE

The CodeWriter is, by far, one of the greatest time-savers for programmers that are flying by the seat of their pants. In terms of keystrokes, imagine what is required when you discover that a portion of one function really should have been another function. CodeWriter takes a line-mark style block of source code and converts it into a routine by itself.

The options of this feature allow you to specify the location of the resulting function, the case format of the commands, a comment for the function call, and whether a comment header should be created. For example, assume that the highlighted area in the function named reOpenProject() needs to be moved to a function by itself. Using a Multi-Edit line mark, highlight the source code lines that are to be established as a separate function, and then click the Code Writer icon on the Evolve tool bar or run the Code Writer menu option from the Assist menu.

Marking a line block to convert to a function

FUNCTION reOpenProject
   select Project
   nTemp = recno( |
   use
   use cbproj alias Project
.  select Project           .
.  go nTemp                 .
RETURN (Void)

EVOLVE will respond with a dialog allowing you to select different upper and lower case formats for the new function as well as a function name, and other pertinent information concerning the creation of the function, its position, and possible argument list. The argument list is typed in just as it would appear in your source code, and will be automatically inserted in the function call as well as the function itself. A check box has been provided so that the arguments can be passed to LOCAL variables (i.e., prototyped in the function statement) or as PRIVATE variables in a PARAMETERS statement.

OOP support is also available in the dialog menu so that you can create a “method” and corresponding object message from the marked area. The format used, generally conforms to OOP paradigms and assumes the object message is being sent to itself.

When the prompts have been completed to your satisfaction, pressing Enter or clicking on OK will complete the task and the resulting code will appear.

Evolve features many types of object editing capabilities. Note that an object is a loose term we use to cover items that are referenced in source files that can be isolated for purposes of viewing or editing. The goal of object editing is to increase speed when accessing other files, structures, functions and procedures, without forcing the programmer to leave the point where the object is referenced. It's a hyper-navigator that takes you to specific places in your source code instantly.

This capability makes it possible to simply point at a procedure name [among other things], and immediately bring it up for viewing or editing. This applies to user defined functions as well as #INCLUDE files and even database structures and index files.

Evolve uses a specific search criteria for finding these various resources. For example, when you edit a #INCLUDE file, Evolve looks in all other buffers for the file requested. If it isn't currently being edited in Multi-Edit, it then looks in the current directory. Lastly, it looks in the DOS environment for the INCLUDE environment variable. The table on the following page shows the search logic for each resource type.

INCLUDE Environment Variable

This environment variable, which is usually established for the language or compiler you use, is generally employed to point to a directory where all header files are stored. When attempting to edit a file [using the object editing feature] identified by #INCLUDE, Evolve will first attempt to locate the include file in memory. If not found there, it will then search for the file on disk in the current directory, and lastly, the search will culminate in the directory [or directories] specified in the INCLUDE environment variable.

SET INCLUDE=C:\CLIPPER\INCLUDE;C:\TC\INC

For example, the SET INCLUDE statement shown above configures Evolve to search in Clipper's INCLUDE directory as well as Turbo C's INC directory.
DBF Environment Variable

The DBF environment variable works in similar fashion to the INCLUDE variable in that it provides a search path for Evolve to locate database and index files if they cannot be found in the current directory.

SET DBF=DATA;C:\DATADICT

LIBR Configuration Command

This meta command enables search of a source code file list and it is specified in EV.CFG. The [LIBR] meta command provides a source file list that Evolve will use to search for functions and procedures after it has exhausted the search of all current windows in Multi-Edit. A [LIBR] specification sample is shown below and may include an unlimited number of PRG files, up to 2048 characters.

[Author] 	:= Multi Edit Software, Inc.
[Copyright 	:= MESI
[AppTitle] 	:= Billing Information System
[Libr] 	:= source1.prg, source2.prg, source3.prg

The search for routines will progress through each of the listed files in the CFG file in the order that they are listed. Once the routine is located in one of the listed files, the object will be available for editing. Upon completion of the object edit, the file that contains the routine will appear in a new window.

This feature is useful on a project basis since Evolve always looks in the current directory for an EV.CFG file, then it looks to the ME directory and/or the users directory in the case of a network installation of Multi-Edit. This design allows you to have [LIBR] lists that vary from project to project.

To activate Evolve with regard to any of these features, you must point at a code structure that applies to the desired feature, and click the objects icon.

Universal Object Access

As indicated, this button assignment is sensitive to the code structure found at the point where the cursor presently rests. A list of the various supported code structures for Object Editing are shown below. Some of the code structures supported may not be supported by the XBase language dialect that you are using. However, as in the case of #INCLUDE support, it is possible, and recommended that third-party preprocessors like Pre/DB be used with XBase dialects that don't include these features such as dBASE for DOS and FoxPro.

#INCLUDE "keycodes.h"

Position the cursor anywhere on this line, and the file KEYCODES.H will pop-up in a window.

DBUSEAREA(.T., “DBFNTX”, “SAMPLE.DBF”)
USE Sample ALIAS Sample
SELECT Sample

Position the cursor anywhere on the words shown above in bold and the file structure for SAMPLE.DBF will be displayed.

SET INDEX TO Sample
USE Sample INDEX Sample

Position the cursor anywhere on the words shown above in bold, and the index expression for the SAMPLE index file will be displayed. If more than one index exists in the list, a pick list will be displayed allowing you to select the desired index file.

MyWin()

Position the cursor anywhere on the function name shown above, and the function MyWin() will be displayed in a window.

DO MyProc

Position the cursor anywhere on the procedure name shown above and the procedure MyProc will be displayed in a window.

Objects That Can't Be Found

Utilizing the object editor on functions and procedures that cannot be found will simply produce an error message. The scope of possibilities is just too wide to assume that the missing routine needs to be created.

In the case of #INCLUDE editing, Evolve will prompt for the creation of new #INCLUDE files and even provide a history list of all possible supported INCLUDE DOS paths for the missing file. This feature also creates a program header comment if Automatic Comment Headers is enabled in the Evolve configuration dialog.

Search Criteria

The search criteria used [when you attempt to edit a UDF or procedure] includes a search for the routine in the current window, followed by a search of all other windows open in Multi-Edit. As a last resort, the search culminates by looking through all source files listed in the [LIBR] meta command in EV.CFG.

Macro Command: ASSIST

The ASSIST Menu presents most of the EVOLVE macros in an easy-to-use pop-up menu.

By default, the Assist Menu can be accessed from Multi-Edit's context menu [by clicking the right mouse button], or by running the macro named “ASSIST”. To execute any of the menu options, simply point to the desired feature and press [enter] or use the mouse to click on the menu option.

Additionally, the Assist Menu can be displayed from the Evolve Tool Bar. The Evolve Tool Bar may be displayed or hidden [as you may require from time-to-time] via the Multi-Edit context menu.