Chapter 33: Programming Improvements

Microsoft Visual FoxPro now includes new programming features designed to improve developer productivity. These features include Access and Assign methods that let you execute code when the value of a property is queried or when you attempt to change the property's value, support for more graphic file formats, and new language to simplify programming tasks. Also, many of the file name manipulation functions available in Foxtools.fll, a Visual FoxPro API library, have been added to Visual FoxPro.

This chapter covers:

• Access and Assign Methods
• GIF and JPEG Graphics Support
• New and Enhanced Language
• Year 2000 Date Support

Access and Assign Methods

Visual FoxPro has been enhanced to support Access and Assign methods. These user-defined methods let you execute code when the value of a property is queried, or when you attempt to change the property's value.

The code in an Access method is executed when the value of a property is queried, typically by using the property in an object reference, storing the value of the property to a variable, or displaying the value of property with a question mark (?).

The code in an Assign method is executed when you attempt to change the value of a property, typically by using the STORE or = command to assign a new value to the property.

Access and Assign methods are executed when property values are queried or changed at run time only. Querying or changing property values at design time doesn't execute Access and Assign methods.

Note   Because the value you attempt to assign to the property is passed to the Assign method, you must include a PARAMETERS or LPARAMETERS statement in the Assign method to accept the value.

Access and Assign methods can be created independently — you can create an Access method without an Assign method, or an Assign method without an Access method.

Access and Assign methods can be created for properties created programmatically within a DEFINE CLASS statement, or interactively for a form or class with the Form and Class designers. Access and Assign methods

Note   Access and Assign methods can also be created for all native Visual FoxPro properties. For example, you can create an Access method for the Left property of a form, allowing you to execute code whenever the form's Left property is queried. You can create an Assign method for a native Visual FoxPro property that is read-only (for example, the ParentClass property), but the method will never be executed.

Benefits of Access and Assign Methods

Access and Assign methods provide the following benefits:

• You can create a public interface for a class or object that separates the interface from the implementation.
• You can easily implement property validation.
• You can easily protect properties in subclassed ActiveX controls.

Creating Access and Assign Methods

Enhancements to the DEFINE CLASS command and the Form and Class designers allow you to create Access and Assign methods both programmatically and interactively.

New DEFINE CLASS Suffixes

Two suffixes, _ACCESS and _ASSIGN, have been added to the DEFINE CLASS command to create Access and Assign methods. Appending one of these keywords to a function or procedure name creates an Access or Assign method for a property with the same name as the function or procedure.

For example, the following code example uses DEFINE CLASS to create a custom class named MyClass. A user-defined property, MyProperty, is created for the class. An Access method for MyProperty is then created with the PROCEDURE statement.

When the property value is queried, the code in the procedure (WAIT WINDOW 'This is the Access method') is executed. An Assign method for MyProperty is also created, again with a PROCEDURE statement. When an attempt is made to change the property value, the code in the procedure (WAIT WINDOW 'This is the Assign method') is executed.

Note the use of an LPARAMETERS statement to accept the value passed to the Assign method. This example also demonstrates how you can create read-only properties.

DEFINE CLASS MyClass AS Custom
   MyProperty = 100 && A user-defined property

   PROCEDURE MyProperty_ACCESS && Access method
      WAIT WINDOW 'This is the Access method';
          +  ' ' + PROGRAM( )
      RETURN THIS.MyProperty
   ENDPROC

   PROCEDURE MyProperty_ASSIGN && Assign method
      LPARAMETERS tAssign  && Required to accept value
      WAIT WINDOW 'This is the Assign method';
          + ' ' + PROGRAM( )
   ENDPROC
ENDDEFINE

This next example demonstrates how you can add an Assign method for a native Visual FoxPro property and perform simple validation on the property value you attempt to set. Note that in this example an Assign method is created without a corresponding Access method.

DEFINE CLASS is used to create a Form class named frmMyForm. An Assign method named Left_ASSIGN is created with a PROCEDURE statement. The code in the Assign method is executed whenever an attempt is made to assign a value to the form's Left property.

If you attempt to change the Left property value to a negative value, a message is displayed and the Left property value is left unchanged. If you attempt to change the Left property value to a non-negative value, the form's Left property is set to that value.

DEFINE CLASS frmMyForm AS Form

   PROCEDURE Left_ASSIGN && Assign method
      LPARAMETERS tAssign  && Required to accept value
      
      DO CASE
         CASE tAssign < 0 && Left value negative
            WAIT WINDOW 'Value must be greater than 0'
         OTHERWISE  && Left value not negative
            THIS.Left = tAssign
      ENDCASE
   ENDPROC
ENDDEFINE

See DEFINE CLASS for further information about the syntax used to create Access and Assign methods.

The Form and Class Designers

To create an Access or Assign method in the Form Designer

1. Choose New Property from the Form menu.

   The New Property dialog box is displayed.

   

2. Enter the name of the property to create in the Name text box, and then select the Access Method check box or Assign Method check box (or both).
   
   
3. Choose Add to create a property for the form, and to create Access or Assign methods for the property.

To create an Access or Assign method for an intrinsic Visual FoxPro property in the Form Designer

1. Choose New Method from the Form menu.

   The New Method dialog box is displayed.

2. Enter the name of the intrinsic property followed with _Access or _Assign in the Name text box. For example, to create an Access method for the Left property, enter Left_Access in the Name text box.
   
   
3. Choose Add to create an Access or Assign methods for the intrinsic property.

Note   In the Form Designer, you can create properties with Access and Assign methods only for a form or formset. To create properties with Access and Assign methods for a control or object, use the Class Designer to create the control or object class. In the Class Designer, add properties with Access and Assign methods to the control or object, and then add the control or object class to the Form in the Form Designer.

To create an Access or Assign method for a class in the Class designer

1. Choose New Property from the Class menu.

   The New Property dialog box is displayed.

2. Enter the name of the property to create in the Name textbox, then select the Access Method check box or Assign Method check box (or both).
   
   
3. Choose Add to create a property for the class, and to create Access or Assign methods for the property.

For more information about creating Access or Assign methods , see the New Property Dialog Box topic.

THIS_ACCESS Method

A new global class method, THIS_ACCESS, has been added to Visual FoxPro 6.0. The code in a THIS_ACCESS method is executed whenever you attempt to change the value of a member of an object or a member of an object is queried.

A THIS_ACCESS method is created in code within a DEFINE CLASS command, or in the New Method or Edit Properties dialog boxes for .vcx visual class libraries. A THIS_ACCESS method must always return an object reference, otherwise an error is generated. The THIS object reference is typically returned. A THIS_ACCESS method must also include a parameter to accept the name of the member of the object that is changed or queried.

The following simple example demonstrates how to create a THIS_ACCESS method in code within a DEFINE CLASS command. When this example is run as a program, 'Caption' is displayed twice, first when the Caption property is assigned a value, and again when the Caption property value is queried. The value of the Caption property ('abc') is then displayed.

CLEAR
oTempObj = CREATEOBJECT('MyForm')  && Instantiate the Form
oTempObj.Caption = 'abc'  && Assign a value, triggers THIS_ACCESS
? oTempObj.Caption  && Query a value, triggers THIS_ACCESS

DEFINE CLASS MyForm AS Form
   PROCEDURE THIS_ACCESS
      LPARAMETER cMemberName  && Object member name

      IF cMemberName = 'caption'
         ? cMemberName  && Display the object member name
      ENDIF
      RETURN THIS
   ENDPROC
ENDDEFINE

Note that THIS_ACCESS is not intended to be a global replacement for Access and Assign methods - it only provides information about which object member is accessed or queried. Unlike an Access or Assign method, THIS_ACCESS does not provide control over values returned to specific object members.

Access and Assign Programming Notes

The following sections describe programming information for Access and Assign methods.

Scoping

Access and Assign methods are protected by default - you cannot access or make changes to an Access or Assign method from outside of the class in which the Access or Assign method is created.

Include the HIDDEN keyword when you create an Access or Assign method to prevent access and changes to the properties from outside of the class definition. Only methods and events within the class definition can access the hidden properties. While protected properties can be accessed by subclasses of the class definition, hidden properties can only be accessed from within the class definition.

Note   If you don't include the HIDDEN keyword, you can subclass Access and Assign methods.

Debugging

You can view the code for Access and Assign methods in the Trace window of the Debugger window. However, Access and Assign methods cannot be executed from within the Watch and Local windows of the Debugger window.

Passing Arrays to Assign Methods

Arrays are passed to Access and Assign methods in the same manner as standard Visual FoxPro procedures.

The entire array is passed to an Access or Assign method if you issue SET UDFPARMS TO REFERENCE or preface the array name with @. The first element of the array is passed by value if you issue SET UDFPARMS TO VALUE or enclose the array name by parentheses. Array elements are always passed by value. See SET UDFPARMS for more information about passing values and arrays.

ActiveX Controls

Access and Assign methods are not supported for an ActiveX control's native properties, events, or methods. However, Access and Assign methods are supported for properties, events, and methods for the Visual FoxPro OLE Container in which the ActiveX control is contained.

ResetToDefault Method

Executing the ResetToDefault method for an Access or Assign method changes the code in the Access or Assign method to the default snippet. The result is that the inherited method code, if any, does not get executed. The technique used to ensure that code inherited from the parent class does get executed varies according to the method type.

Place the following code in the subclass of an Access method to execute the code in the parent class:

RETURN DODEFAULT( )

Place the following code in the subclass of an Assign method to execute the code in the parent class:

LPARAMETERS vnewval
DODEFAULT(vnewval)
THIS.<property name> = vnewval

Place the following code in the subclass of a THIS_ACCESS method to execute the code in the parent class:

LPARAMETERS cmember
RETURN DODEFAULT(cmember)

GIF and JPEG Graphics Support

Visual FoxPro has been enhanced to support the GIF (Graphics Interchange Format) and JPEG (Joint Photographic Electronic Group) graphic file formats, widely used throughout the Internet.

In general, any areas that supported .bmp (bitmap) format in previous versions of Visual FoxPro now also support the following graphic file formats.

Note   In Visual FoxPro, cursor, animated cursor, and icon files can be used as graphics files. For example, you can specify an animated cursor file for the Picture property for the Image control (however, the Image control displays the static representation of the cursor).

Graphics support is provided in Visual FoxPro in three areas: language, controls and objects, and the interface.

The Visual FoxPro Language

The following commands and functions have been enhanced to support the new graphic file formats.

GETPICT( )

The Open dialog displayed by issuing the GETPICT( ) function in the Command window has been enhanced, allowing you to quickly locate all the graphic files supported in Visual FoxPro. The Files of Type drop-down list box now includes the following items.

Check the Preview check box to display the currently selected graphics file. In previous versions of Visual FoxPro, it was necessary to choose the Preview button each time a new graphics file was selected. The size of the Picture area has also been increased.

CLEAR RESOURCES

The CLEAR RESOURCES command in Visual FoxPro now clears all cached graphic files, including .gif and .jpg files.

Visual FoxPro Controls and Objects

The following table lists Visual FoxPro controls and objects with properties for which you can specify graphics files. You can now specify .gif, .jpg, cursor, animated cursor, and icon graphic files for these properties, in addition to the .bmp and .dib graphic files supported in previous versions of Visual FoxPro.

The Visual FoxPro Interface

Several of the Visual FoxPro designers allow you to specify graphics files with the Open dialog. The Open dialog for the following designers have been enhanced to include the new graphic file formats.

Form Designer and Class Designer

In the Properties window, by double-clicking the property or choosing the property's dialog button you can display the Open dialog for a property that supports graphic files.

Project Manager

You can add graphics files to a project from the Project Manager All and Other tabs. When the All or Other tab is selected, select the Other Files item and then choose Add. The Open dialog is displayed, allowing you to add a graphics file to the project.

Report Designer

The Report Controls toolbar contains the Picture/OLE Bound Control button. Click this button and drag the cursor over a band in the Report Designer to display the Report Picture dialog box. To display the Open dialog, choose the File dialog button.

New and Enhanced Language Elements

Many new and enhanced language elements have been added to Visual FoxPro. The new language elements listed in this section include Active Documents, Project Manager Hooks, OLE drag-and-drop, Server Improvements, and miscellaneous language.

The enhanced elements are also listed.

In addition, many of the file name manipulation functions available in Foxtools.fll, a Visual FoxPro API library, have been added to Visual FoxPro. It's no longer necessary to use SET LIBRARY TO FOXTOOLS.FLL to call these Foxtools functions; you can call them directly in your Visual FoxPro programs.

This section also describes improvements to Visual FoxPro performance, robustness, and usability.

Improvements to Visual FoxPro Performance

The performance of string concatenation in Visual FoxPro 6.0 has been increased dramatically. String concatenation is typically used to create Web pages with code like the following:

cMyString = cMyString + <html tags>
cMyString = cMyString + <more html tags>
cMyString = cMyString + <even more html tags>

Also, object creation and instantiation performance has also been improved, and it typically 10 or more times faster than in previous versions.

Improvements to Visual FoxPro Robustness

Visual FoxPro 6.0 now captures General Protection Faults (GPFs) in ActiveX controls placed on a form, or COM objects instantiated from within Visual FoxPro. A GPF in an ActiveX control or COM object is now treated as a trappable Visual FoxPro error (Error 1440 - OLE object may be corrupt).

Improvements to Visual FoxPro Usability

You can specify the Visual FoxPro editor comment string in the Windows registry. Using the Windows Registry Editor (RegEdit), open the Visual FoxPro 6.0 Options folder, and right-click the folder. Choose New, and then String Value. Enter the name “EditorCommandString” for the name of the new string value. Right-click the string value, and choose Modify. Enter the editor comment string (*!* is the default value used when this registry entry doesn’t exist in the Registry).

The Form menu is now accessible from within the form code window. Also, you can run a form with the CTRL+E keyboard shortcut, even from within a form code window.

Year 2000 Date Support

Visual FoxPro 6.0 has been enhanced to provide better year 2000 date support. This section describes the enhancements made to Visual FoxPro to make it easier to create year 2000 compliant applications.

SET CENTURY TO

The Visual FoxPro 5.0 documentation states that issuing SET CENTURY TO without additional arguments sets the century to the current century. This is only true in the 20th century, because the century is set to 19 regardless of the current century. In Visual FoxPro 6.0, SET CENTURY TO sets the century to the current century. Additionally, the value of SET CENTURY TO in new data sessions is initialized to the current century.

Also, in Visual FoxPro 6.0, the default ROLLOVER value for SET CENTURY has changed to the last two digits of the current year plus 50 years - if the current year is 1998, nYear is 48, the last two digits of 2048 (1998 + 50). In Visual FoxPro 5.0 the default value is 0.

See SET CENTURY for more information.

Strict Date Formats

Normally, Date and DateTime constants or expressions are interpreted based on the current settings of SET DATE and SET CENTURY at the time the constants or expressions are compiled or evaluated. This means that many date constants are ambiguous since they might evaluate to different values depending upon when they were compiled and what date settings were in effect at compilation time.

For example, is the date constant {10/11/12} October 11, 1912, October 11, 2012, November 10, 1912, November 12, 1910, or November 12, 2010?

It all depends on the current settings of SET DATE and SET CENTURY TO. This can introduce errors into existing Visual FoxPro code wherever Date or DateTime constants or expressions are either compiled or are evaluated at run time, such as in report and object expressions. This can introduce year 2000 noncompliance into existing code when the setting of SET CENTURY rolls over into the year 2000 and a four-digit year isn't specified.

To avoid noncompliance, a strict date format is now available in Visual FoxPro 6.0 (and Visual FoxPro 5.0). A strict date always evaluates to the same Date or DateTime value regardless of any date settings. The strict date format is:

^yyyy-mm-dd[,][hh[:mm[:ss]][a|p]]

The caret character (^) always denotes the strict date format and causes Dates and DateTimes to be interpreted in a YMD format. Valid Date and DateTime separators are hyphens, forward slashes, periods, and spaces.

Empty Dates and DateTimes are considered nonambiguous and are always valid. Valid empty Date and DateTime formats include {}, {--}, and {--,:}.

With strict date formats, a greater range of Date and DateTime values are available. In Visual FoxPro 5.0, the smallest date value that can be expressed is {^0100/1/1}, January 1st, 100 A.D. This is because year values less than 100 were always rounded up to the nearest century based on the setting of SET CENTURY.

The smallest valid date in Visual FoxPro 6.0 is {^0001-01-01}, January 1st, 1 A.D. The largest valid date in Visual FoxPro 6.0 is {^9999-12-31}, December 31st, 9999 A.D.

Note that the strict date format ignores the TAIWAN setting for SET DATE, so the year of a strict format Date or DateTime is always in the Western calendar. (Note that this is not true in Visual FoxPro 5.0.)

SET STRICTDATE

A new command, SET STRICTDATE, can be used to enforce year 2000 compliant date constants and date strings.

SET STRICTDATE TO 0

Setting STRICTDATE to 0 means that strict date format checking is off. This is Visual FoxPro 5.0 compatible. 0 is the default setting for the Visual FoxPro run time and ODBC driver. When STRICTDATE is set to 0, invalid Date and DateTimes evaluate to the empty date.

SET STRICTDATE TO 1

Setting STRICTDATE to 1 requires that all Date and DateTime constants be in the strict date format. Any Date or DateTime constant that is not in the strict format or evaluates to an invalid value generates an error, either during compilation, at run time, or during an interactive Visual FoxPro session. 1 is the default setting for an interactive Visual FoxPro session.

SET STRICTDATE TO 2

Identical to setting STRICTDATE to 1, but also generates a compilation error (2033 – CTOD and CTOT can produce incorrect results) whenever CTOD( ) and CTOT( ) functions appear in code.

Because the values returned by CTOD( ) and CTOT( ) rely on SET DATE and SET CENTURY to interpret the date string they contain, they are prone to year 2000 noncompliance errors. Use DATE( ) and DATETIME( ) with the optional numeric arguments to create Date and DateTime constants and expressions.

This setting is most useful during debugging sessions to trap for code that may contain year 2000 compliance errors.

Strict Date Format Errors

The following new errors have been added to Visual FoxPro 6.0, and can be generated when SET STRICTDATE is set to 1 or 2.

Error 2032: Ambiguous Date/DateTime constant.

This error occurs when a Date or DateTime did not adhere to the strict format. The following conditions will produce this error:

• The caret (^) is missing.
  
  
• The date separators are not the required hyphen, forward slash, period, or space separators.
  
  
• The year field contains less than four characters ({^98-02-16}).
  
  
• The month or day field is empty ({^1998-02}).

Error 2033: CTOD and CTOT can produce incorrect results.

This error occurs for the same reasons as error 2032, but CTOD( ) and CTOT( ) may be non-compliant or ambiguous. Use the DATE( ) or DATETIME( ) functions instead.

Error 2034: Date/DateTime evaluated to an invalid value.

A Date or DateTime is not in the valid Date or DateTime format, or is outside the valid Date or DateTime range.

When SET STRICTDATE is set to 0, invalid Date and DateTime constants evaluate to the empty Date or DateTime. When SET STRICTDATE is set to 1 or 2, invalid date constants, such as {^2000-02-31}, February 31^st, or {^2000-01-01,25:00}, 25 o'clock, generate this error.

Examples of invalid Dates and DateTimes include:

• {^2000-02-31}, February 31st, 2000.
  
  
• {^2000-01-01,25:00} 25 o'clock.
  
  
• {^2000-01-01, 14a}, 14 A.M.

Error 2035: Date/DateTime contains illegal characters.

The Date or DateTime constant contains characters that are not supported in Date and DateTime constants.

When SET STRICTDATE is set to 0, the Date or DateTime constant containing the illegal characters evaluates to the empty Date or DateTime. When SET STRICTDATE is set to 1 or 2, the Date or DateTime constant containing the illegal characters generates this error.

Note that the StrictDateEntry property isn't affected by the setting of SET STRICTDATE. The StrictDateEntry property remains unchanged in Visual FoxPro 6.0.

Options Dialog

The General tab of the Options dialog box now includes a Year 2000 Compliance drop-down list box, which specifies the setting of SET STRICTDATE. Like all other Options dialog items, the value is set for the current Visual FoxPro session, and choosing Set As Default saves the setting to the Windows registry for the next Visual FoxPro session.

DATE( ) and DATETIME( ) Functions

The DATE( ) and DATETIME( ) functions now support optional numeric arguments that let you create year 2000 compliant Date or DateTime values. The enhancements to these functions now provide a preferable method for creating Date and DateTime values; it's no longer necessary to use character manipulation functions to create Date and DateTime values.

FDATE( ) Function

The FDATE( ) function now supports an optional argument that lets you determine the time when a file was last modified without using character manipulation functions. For example, in previous versions of Visual FoxPro, it was necessary to write code like the following to determine when the Visual FoxPro resource file was last modified:

tLastModified = CTOT(DTOC(FDATE('Foxuser.dbf')) + ' ' ;
   + FTIME('Foxuser.dbf') 

This code can now be replaced with the following:

tLastModified = FDATE('Foxuser.dbf', 1)

Century Property

The default for the Century property in Visual FoxPro 6.0 is 1 – On. The century portion of the date is displayed in a text box. In previous versions of Visual FoxPro, the default is 2 – the SET CENTURY setting determines if the century portion of the date is displayed.