New directives for the Beautify tool are available in Visual FoxPro 9

Microsoft Visual FoxPro includes a tool that is named Beautify. The Beautify tool lets you make your code easier to read by providing options to adjust indentation and case. You can globally set these options in the Beautify Options dialog box. These options are used every time that you run the Beautify tool on a code block. However, you may want to override some of these options on a program-by-program basis. You can do this by using Beautify directives.

Beautify directives are specially formatted comments put in code blocks. When you run the Beautify tool on a code block and the Beautify tool encounters these Beautify directives, the Beautify tool performs certain actions.

The Beautify tool can adjust the case of keywords. Keywords in Visual FoxPro are all the reserved words in the Visual FoxPro programming language. For example, one keyword is MODIFY. You can make a code block easier to read and make elements in a code block easier to identify by adjusting the case of all the keywords in the code block. However, this adjustment may sometimes have unexpected side effects. Although Visual FoxPro is a case-insensitive language, some of the tools you may use are case-sensitive. For example, functions in the Windows API must be declared and called in a case-sensitive manner from Visual FoxPro. A Beautify-related problem occurs when you use a function from the Windows API that shares the same name as a Visual FoxPro keyword.

A specific example of a Visual FoxPro keyword that shares the same name as a function from the Windows API is the Visual FoxPro ShowWindow property. When the Beautify tool encounters this Visual FoxPro keyword, the Beautify tool adjusts the case of that keyword based on the settings in the Beautify Options dialog box. To successfully call the Windows API ShowWindow function, Visual FoxPro code must be specifically formatted in Pascal case. References to the Visual FoxPro ShowWindow property can be formatted in any case you want, because Visual FoxPro is case-insensitive. The Beautify tool cannot tell if an occurrence of the keyword ShowWindow in a code block is a reference to the Visual FoxPro property or to the function from the Windows API. If the reference is to the function from the Windows API and if the Beautify tool changes the case of the code, the call to the function will fail when the Visual FoxPro code runs.

In versions of Visual FoxPro earlier than Visual FoxPro 9.0, there was no easy way to prevent the Beautify tool from making this case adjustment. Visual FoxPro 9.0 introduces two new Beautify directives to help resolve this problem:

• *#beautify keyword_nochange
• *#beautify

When a keyword in Visual FoxPro code is wrapped in these directives, the Beautify tool will make no changes to the keyword.

Note These directives take the form of comments. The directives are preceded by an asterisk (*) character. An asterisk (*) character is the default character for full-line comments in Visual FoxPro. This comment format is required for the directive to work. A benefit of this comment format is that even though the directive is only recognized by the Beautify tool in Visual FoxPro 9.0 and later versions, the code will continue to compile in versions of Visual FoxPro earlier than Visual FoxPro 9.0.

The following example demonstrates how to use these Beautify directives in Visual FoxPro 9.0 and later versions:

1. Start Visual FoxPro 9.0.
2. On the Tools menu, click Beautify. The Beautify Options dialog box opens.
   
   Note If Beautify is unavailable on the Tools menu, press CTRL+F2 on your keyboard to open the Command window and to give the Command window focus. Then, try to click Beautify on the Tools menu again.
3. In the Capitalization area, click UPPERCASE in the Keywords list.
4. To close the Beautify Options dialog box, click Run.
5. Open a new Editing window by executing the following line of code in the Command window.

   MODIFY COMMAND BeautifyTest

6. Copy the following lines of code, and then paste the code into the new Editing window.

   *------- <BLOCK 1>
   *
   *#beautify keyword_nochange
   #DEFINE SW_MINIMIZE	6
   DECLARE INTEGER ShowWindow IN WIN32API ;
   	INTEGER nHWND, ;
   	INTEGER nCmdShow
   
   ShowWindow(_VFP.HWND, SW_MINIMIZE)
   *#beautify
   *
   *------- </BLOCK 1>
   
   
   *------- <BLOCK 2>
   *
   #DEFINE SW_MINIMIZE	6
   DECLARE INTEGER ShowWindow IN WIN32API ;
   	INTEGER nHWND, ;
   	INTEGER nCmdShow
   
   ShowWindow(_VFP.HWND, SW_MINIMIZE)
   *
   *------- </BLOCK 2>
   

7. Run the Beautify tool on the code. To do this, click Beautify on the Tools menu, and then click Run.

This example code is separated into two blocks. The blocks are the same except that Block 1 contains the Beautify directives. In Block 1, the case of the ShowWindow keyword is not changed. When the Beautify tool is run, the Beautify tool encounters the *#beautify keyword_nochange directive and leaves the ShowWindow keyword alone.

Block 2 does not contain the Beautify directives. Therefore, in Block 2 the ShowWindow keyword is changed to uppercase. This change makes the code block not valid. To verify this, save and then run the code. When you run the code, the following error will be thrown on the DECLARE line in Block 2:Note These Beautify directives are not in the documentation that accompanies Visual FoxPro 9.0.