Form_ Class Properties and Methods

The Form_ class is a subclass of the Visual FoxPro Form base class. One of the main purposes of the Form_ class is to establish a VPM Enterprise Form base class from which all other VPM Enterprise form classes are created.

Because Visual FoxPro base classes cannot be modified, it is good practice to create your own base classes from the Visual FoxPro base classes. Then, you create all your subclasses from your own base classes. If you do that, you will have the ability to modify your base classes as needed, and your modifications will be inherited by your subclasses.

Properties

The following table lists the class properties. The properties listed include the standard Visual FoxPro class properties that the VPM Enterprise class uses and the VPM Enterprise custom properties. Where appropriate, the Comments column of the table describes a property and provides suggestions for its use.

 

Property & Initial Value

Comments

Standard Properties Used:

 

Caption = “Form_”

 

FontSize = 9

 

Height = 330

 

MaxButton = .F.

 

Name = “form_”

 

ShowTips = .T.

 

Width = 461

 

Custom Properties:

 

cActiveFormDateTime = “”

Contains the current date and time the form was run. The Active Forms array also contains this entry. When a form is reactivated, this property can be used to find the form’s row in the Active Forms array.

cCloseForms = “”

A comma-delimited list of the forms that should be closed when the current form is closed. In the list, forms are identified by the value in their Name property.

cConditionBuilderForm = “condition_builder”

Contains the name of the Condition Builder form or form class.

cConditionBuilderForm_Class Library = “progen”

Contains the name of the class library that contains the Condition Builder form class if cConditionBuilderForm contains the name of a form class.

cCSAltFormName = “”

Alternate form name used with Control Security. Used when the first twelve characters of the value in the form’s Name property are not unique.

cDataHandlerClass = “prodatahandler”

Contains the name of the class from which the data handler object is instantiated.

cDataHandlerClass_ClassLibrary = “prodatahandler”

Contains the name of the class library that contains the class specified in cDataHandlerClass.

cDoNotCreateTagsInForm_Aliases = “”

A comma-delimited list of view and cursoradapter aliases for which index tags should not be created automatically in the form’s Load method. Tags are defined in the SDATADDIT table through the Data Builder/Manager.

cFieldDescriptionForm = “f3text”

Contains the name of the Field Description form or form class.

cFieldDescriptionForm_Class Library = “progen”

Contains the name of the class library that contains the Field Description form class if cFieldDescriptionForm contains the name of a form class.

cFindForm_SQL = “find_sql”

Contains the name of the SQL Find form or form class.

cFindForm_SQL_ClassLibrary = “progen”

Contains the name of the class library that contains the SQL Find form class if cFindForm_SQL contains the name of a form class.

cInitialTag = “”

The name of the tag that should be used as the master tag for the ISA cursor.

cNewObjectForm = “newobject”

Contains the name of the New Object form or form class.

cNewObjectForm_ClassLibrary = “prorpt”

Contains the name of the class library that contains the New Object form class if cNewObjectForm contains the name of a form class.

cOriginalCaption = “”

Used to make sure that the original form caption is displayed in the status bar.

cPicklistForm_Date = “f2date_month”

Contains the name of the Picklist (Date) form or form class.

cPicklistForm_Date_ClassLibrary = “progen”

Contains the name of the class library that contains the Picklist (Date) form class if cPicklistForm_Date contains the name of a form class.

cPicklistForm_Referential = “f2ref”

Contains the name of the Picklist (Referential) form or form class.

cPicklistForm_Referential_ClassLibrary = “progen”

Contains the name of the class library that contains the Picklist (Referential) form class if cPicklistForm_Referential contains the name of a form class.

cPicklistForm_Set = “f2set”

Contains the name of the Picklist (Set) form or form class.

cPicklistForm_Set_ClassLibrary = “progen”

Contains the name of the class library that contains the Picklist (Set) form class if cPicklistForm_Set contains the name of a form class.

cReportManagerForm_EditAnd Run = “report_manager”

Contains the name of the Report Manager (Edit and Run) form or form class.

cReportManagerForm_EditAnd Run_ClassLibrary = “prorpt”

Contains the name of the class library that contains the Report Manager (Edit and Run) form class if cReportManagerForm_EditAndRun contains the name of a form class.

cReportManagerForm_RunOnly = “report_manager_run”

Contains the name of the Report Manager (Run Only) form or form class.

cReportManagerForm_RunOnly_ ClassLibrary = “prorpt”

Contains the name of the class library that contains the Report Manager (Run Only) form class if cReportManagerForm_RunOnly contains the name of a form class.

cReportSetupForm = “reportsetup”

Contains the name of the Report Setup form or form class.

cReportSetupForm_ClassLibrary = “prorpt”

Contains the name of the class library that contains the Report Setup form class if cReportSetupForm contains the name of a form class.

cRightClick_Menu = “S”+_SCREEN.oApp.cCurPre+”FFRM.MPR”

The name of the shortcut menu to be run when the form is right-clicked.

cSetList = “”

Used by the SetPush and SetPop methods to hold a string that contains a list of SET command settings.

cWindowAlternate = “”

Used to identify the menu item name of the Window menu. It is used when an application’s Window menu item name is not “Window”, as in VFP for languages other than English.

External_aPicklist[1,0]

Used to pass information to and retrieve information from a form that is brought up from this form.

External_aPicklistFilterVariables [1,2]

Used to pass information to and retrieve information from a form that is brought up from this form.

External_cAltCaptions = “”

Used to pass information to and retrieve information from a form that is brought up from this form.

External_cConditionBuilderExpr = “”

Used to pass information to and retrieve information from a form that is brought up from this form.

External_cFieldDescriptionLabel = “”

Used to pass information to and retrieve information from a form that is brought up from this form.

External_cFieldDescriptionText = “”

Used to pass information to and retrieve information from a form that is brought up from this form.

External_cListCaptions = “”

Used to pass information to and retrieve information from a form that is brought up from this form.

External_cListFields = “”

Used to pass information to and retrieve information from a form that is brought up from this form.

External_cListSQLFields = “”

Used to pass information to and retrieve information from a form that is brought up from this form.

External_cListTags = “”

Used to pass information to and retrieve information from a form that is brought up from this form.

External_cParentAlias = “”

Used to pass information to and retrieve information from a form that is brought up from this form.

External_cParentExpr = “”

Used to pass information to and retrieve information from a form that is brought up from this form.

External_cPicklistAddEditForm = “”

Used to pass information to and retrieve information from a form that is brought up from this form.

External_cPicklistCaptions = “”

Used to pass information to and retrieve information from a form that is brought up from this form.

External_cPicklistFields = “”

Used to pass information to and retrieve information from a form that is brought up from this form.

External_cPicklistFormCaption = “”

Used to pass information to and retrieve information from a form that is brought up from this form.

External_cPicklistTags = “”

Used to pass information to and retrieve information from a form that is brought up from this form.

External_lFieldDescriptionCancel Edit = .F.

Used to pass information to and retrieve information from a form that is brought up from this form.

External_lFieldDescriptionOK = .F.

Used to pass information to and retrieve information from a form that is brought up from this form.

External_lNoEntriesOK = .F.

Used to pass information to and retrieve information from a form that is brought up from this form.

External_lPicklistAdd = .F.

Used to pass information to and retrieve information from a form that is brought up from this form.

External_lPicklistEdit = .F.

Used to pass information to and retrieve information from a form that is brought up from this form.

External_lPicklistFromValid = .F.

Used to pass information to and retrieve information from a form that is brought up from this form.

External_lRecordFound = .F.

Used to pass information to and retrieve information from a form that is brought up from this form.

External_nFieldDescriptionControlHeight = 0

Used to pass information to and retrieve information from a form that is brought up from this form.

External__nFieldDescription ControlLeft = 0

Used to pass information to and retrieve information from a form that is brought up from this form.

External__nFieldDescription ControlTop = 0

Used to pass information to and retrieve information from a form that is brought up from this form.

External__nFieldDescriptionFormLeft = 0

Used to pass information to and retrieve information from a form that is brought up from this form.

External__nFieldDescriptionFormTop = 0

Used to pass information to and retrieve information from a form that is brought up from this form.

External_nListRows = 0

Used to pass information to and retrieve information from a form that is brought up from this form.

External_nListWidth = 0

Used to pass information to and retrieve information from a form that is brought up from this form.

External_nParentDS = 0

Used to pass information to and retrieve information from a form that is brought up from this form.

External_nParentRec = 0

Used to pass information to and retrieve information from a form that is brought up from this form.

External_nPicklistArea = 0

Used to pass information to and retrieve information from a form that is brought up from this form.

External_nPicklistFKControl Height = 0

Used to pass information to and retrieve information from a form that is brought up from this form.

External_nPicklistFKControlLeft = 0

Used to pass information to and retrieve information from a form that is brought up from this form.

External_nPicklistFKControlTop = 0

Used to pass information to and retrieve information from a form that is brought up from this form.

External_nPicklistFKFormLeft = 0

Used to pass information to and retrieve information from a form that is brought up from this form.

External_nPicklistFKFormTop = 0

Used to pass information to and retrieve information from a form that is brought up from this form.

External_nPicklistFormWidth = 0

Used to pass information to and retrieve information from a form that is brought up from this form.

External_nPicklistRows = 0

Used to pass information to and retrieve information from a form that is brought up from this form.

External_nPicklistSelection = 0

Used to pass information to and retrieve information from a form that is brought up from this form.

External_nPicklistSetCharacters = 0

Used to pass information to and retrieve information from a form that is brought up from this form.

External_ParentVal = .F.

Used to pass information to and retrieve information from a form that is brought up from this form.

I_lOverrideCaption = .F.

Used by multilingual functionality to bypass the translation of the Caption property value.

I_lOverrideFont = .F.

Used by multilingual functionality to bypass the translation of the Font property values.

I_lOverrideIcon = .F.

Used by multilingual functionality to bypass the translation of the Icon property value.

I_lOverridePicture = .F.

Used by multilingual functionality to bypass the translation of the Picture property value.

lCalledModalForm = .F.

Used with the cCloseForms functionality to prevent a modal form from closing the form that called it.

lCascadePosition = .T.

If .T., when the form is initially opened determines if there is another instance of this form already on the desktop, and if so, displays this form “cascaded” from the position of the top-most instance.

lCenterWindow = .T.

If .T., the form is centered when activated and the lRestoreWindowPos property is set to .F. or lRestoreWindowPos is .T. but no entry has yet been made in the main.ini file.

lCloseF2RefTable = .T.

If .T., the cursor with the alias F2RefTable is closed when the form is closed. This cursor is opened by the validation routine as well as the Picklist routine.

lFirst = .T.

Used in the form’s Activate event to only add the form’s caption to the Window menu upon the form’s initial activation.

lFirstShow = .T.

Used in the form’s Show event to run the code that handles the application window’s Closable setting only upon the form’s initial activation.

lGridFocusCommandButton = .F.

See oGrid_SetFocus.

lInstantiateDataHandlerObject = .T.

If .T., the data handler object is instantiated when the form is initially opened.

lNoActivityRecord = .F.

If set to .T., prevents the creation of an Activity record when the form is run.

lNoFieldValidation = .F.

Used internally to temporarily turn off field validation in certain circumstances.

lNoGridValidation = .F.

Used internally to temporarily bypass a grid’s Valid code in certain circumstances.

lNoStatusBarMessage = .F.

If set to .T., prevents the display of the form’s caption in the status bar.

lPicklistCancel = .F.

Used internally when a selection has been made on the Picklist form.

lRestoreWindowPos = .T.

If .T., the coordinates of the form are stored in the main.ini file. When the form is activated, the form is positioned according to the coordinates stored in main.ini. If lCenterWindow and lRestoreWindowPos are set to .F., the form is positioned according the values in the form’s Top and Left properties.

lRestoreWindowPos_Form_ = .T.

If .T., causes the position of the form to be restored at the end of the Form_ Activate code.

lScreenClosable = .F.

Used to save the initial _SCREEN.Closable property setting.

lScreenClosableWhenFormIs Modal = .F.

If the form is modal and lScreenClosableWhenFormIsModal is .F., make _SCREEN not closable (change its Closable property to .F.) as long as the form is open.

lTestForm_Save = .F.

Saves the application object’s lTestForm property setting so that it can be temporarily changed and then reset.

lTrans_Form_ = .T.

If .T. and the multilingual functionality is being used, will perform property translations in the Init method of the Form_ class.

nActiveFormRow = 0

Contains the number of the form’s row in the Active Forms array.

nFormInstanceNumber_Start = 1

When more than one instance of a form is active at the same time an identifying instance number is added to the form’s caption. This property value identifies the starting instance number for the second instance. For example, by default the caption of the second instance of the form would contain <caption> (1), the third instance would contain <caption> (2), and so on.

nSaveDSID = 0

Used to make sure the form’s original data session is reselected when the form is reactivated.

nSaveLeft = 0

Used to position the form in its original position after having previously been moved out of sight.

oDDTVRecord_<alias>

Created at runtime to hold the SDATADDTV record objects that are created by the SetControlProperties method.

oGrid_SetFocus = .F.

Used to store the object reference of a control that is created at runtime that allows the focus to be moved off a grid.

oVPMDataHandler = .F.

Used to store the object reference of the data handler object that is created when the form is initially opened.


Methods

The following table lists the class methods. The methods listed include the standard Visual FoxPro class methods that the VPM Enterprise class uses and the VPM Enterprise custom methods. Where appropriate, the Comments column of the table describes a method and provides suggestions for its use.

 

Method

Comments

Standard Methods Used:

 

Activate

Updates the status bar message.

Adds the form’s caption to the Window menu.

Restores the form’s position as stored in the main.ini file.

Deactivate

Resets a property value that allows a form to be tested while in VPM.

Destroy

Removes the form’s row in the Active Forms array.

Removes the form’s caption from the Window menu.

Saves the form’s position to the main.ini file.

Makes sure the close button on the application window (_SCREEN) is not disabled.

Init

Adds a row to the Active Forms array (_SCREEN.oApp.aActiveForms) for the form and stores the form’s object reference and other information in the elements of the new row. See the “Active Forms Array” section below.

Determines if an instance of the form already exists. If so, modifies the form’s caption to include the instance number.

Saves the current date and time in a form property so that when the form is reactivated this property can be used to find the form’s row in the Active Forms array.

Sets the Icon property of the form.

Creates an Activity Tracking record.

Stores the project-specific Window (form) right-click menu name to the cRightClick_Menu property.

Multilingual functionality translates the properties of the form and controls.

Load

Sets the environment of the form’s private data session.

Instantiates the data handler object.

Identifies the cursoradapters that are in the DE. Information about cursoradapters is stored in a temporary cursor for use at a later time.

Creates view and cursoradapter cursor index tags.

Sets the order of the ISA cursor if the cInitialTag property is filled-in.

RightClick

Brings up the right-click shortcut menu that is specified in the cRightClick_Menu property.

Show

If the form is modal and lScreenClosableWhenFormIsModal is .F., makes _SCREEN not closable (changes its Closable property to .F.) as long as the form is open.

Unload

Blanks-out the status bar message.

Closes any forms listed in the property cCloseForms.

Custom Methods:

 

AddToMenu

Adds the form’s caption to the Window submenu.

AdminTool_F2

Brings up the Picklist (F2) form for the active control on the form.

AdminTool_F3

Brings up the Field Description (F3) form for the active control on the form.

Parameters: stcKey, stlAltF3

AdminTool_FieldValidation

Called from the Valid event of controls to validate a value.

Parameters: stcDDDName, stcDDTVName, stcDDFName, stValue, stcRulesID, stcRefFilterExpr, staRefFilterVariables, stlRecordLevel, stcAlias

ControlWhen

Called from the When event of controls to determine whether the control can receive focus.

Parameters: stcWhenExpr, stcFieldSecurityID

CreateTagsInForm

Creates index tags for views and cursoradapters that are in the DE.

FormIcon

If the form’s Icon property is blank, fills-in the property with the name of the icon specified in VPM Enterprise as the default form icon.

IdentifyCursorAdapters

Identifies the cursoradapters that are in the DE. Information about cursoradapters is stored in a temporary cursor for use at a later time.

InstantiateDataHandlerObject

Instantiates the data handler object used by the form.

IsControlOnPage

Determines if a control is on a page of a pageframe or in a container that is on a page of a pageframe. This information is used in the KeyPress event of controls to prevent the user from pressing Ctrl+Tab when a page would be activated, causing the control not to be validated.

Parameter: stoControl

LockRecord

Attempts to lock the current record using the RLOCK function. If the record cannot be locked, handles the retry of the lock. Returns .T. if the lock was placed successfully or .F. if not.

LockWindow

Locks a Windows window at the API level much like VFP’s LockScreen property, when LockScreen doesn’t work.

Parameters: stlLock, stlExpandToVFPMainWindow

RefreshForm

Makes sure the refreshing of controls is not seen until all controls are refreshed.

ReleaseRecordObjects

Called by code in the form’s Destroy event. Releases the objects stored in the oDDTVRecord_<alias> properties that are created by the SetControlProperties method.

RemoveFromMenu

Removes the form’s caption from the Window submenu.

RestoreWindowPos

Positions the form according to the coordinates stored in the mani.ini file.

Parameter: stcEntry

RunConditionBuilderForm

Runs the form specified in the properties cConditionBuilderForm and cConditionBuilderForm_ClassLibrary.

Parameters: stoDataSourceForm, stcTitle, stcFrmRptName, stnPage

RunFieldDescriptionForm

Runs the form specified in the properties cFieldDescriptionForm and cFieldDescriptionForm_ClassLibrary.

RunNewObjectForm

Runs the form specified in the properties cNewObjectForm and cNewObjectForm_ClassLibrary.

Parameters: stcObjType, stcObjName, stcObjLocation

RunPicklistForm

Depending on the stcPicklistType parameter value (DATE, REFERENTIAL, or SET), runs the appropriate Picklist form as specified in the properties:

·       cPicklistForm_Date and cPicklistForm_Date_ClassLibrary, or

·       cPicklistForm_Referential and cPicklistForm_Referential_ClassLibrary, or

·       cPicklistForm_Set and cPicklistForm_Set_ClassLibrary.

Parameters: stcPicklistType, stoActiveControl

RunReportManagerForm

Runs the form specified in the properties cReportManagerForm_EditAndRun and cReportManagerForm_EditAndRun_ClassLibrary  or cReportManagerForm_RunOnly and cReportManagerForm_RunOnly_ClassLibrary.

Parameter: stoDataSourceForm

RunReportSetupForm

Runs the form specified in the properties cReportSetupForm and cReportSetupForm_ClassLibrary.

Parameters: stoDataSourceForm, stcParam

RunSQLFindForm

Runs the form specified in the properties cFindForm_SQL and cFindForm_SQL_ClassLibrary.

Parameters: stoDataSourceForm, stoControl

SaveWindowPos

Saves the form’s coordinates (Top and Left properties) to the main.ini file.

Parameter: stcEntry

SetControlProperties

Sets the values of selected control properties, including the Enabled (through Control Security), cAlias, cName_DDD, cName_DDTV, cName_DDF, and cRightClick_Menu.

Finds the SDATADDF and SDATADDTV records for this control and fills-in properties specific to this control, including the oDDFRecord and oDDTVRecord properties. Also stores the SDATADDTV record object to the form property oDDTVRecord_<alias>, where <alias> is the alias specified in the control’s ControlSource property.

Parameter: stoControl

SetDataSessionEnvironment

Issues the environment settings that are scoped to the data session.

SetInitialTag

Sets the order (controlling tag) of the ISA cursor to the tag specified in the form’s cInitialTag property.

SetPop

Restores the status of a SET command whose status was set by the SetPush method.

Parameter: stcSetCommand

SetPush

Changes the status of a SET command whose status can be set to either ON or OFF. The status prior to the change is stored so that it can be restored when the SetPop method is called at a later time.

Parameters: stcSetCommand, stcSetStatus

Active Forms Array

The purpose of the Active Forms Array is to store information about the forms that are active at any given point in time. It contains information related to the Related Forms functionality, multiple instance functionality and the display of form captions on the Window submenu.

The following table describes each column in the Active Forms Array.

 

Col

Type

Initial Value

Description

1

Char.

ThisForm.cActiveFormDateTime

Form’s activation time, representing the year, month, day and seconds since midnight. Format: yyyymmddsssss.sss

2

Object

.NULL.

Form’s object reference.

3

Char.

“”

The PK value of the ISA cursor’s record in the SDATADDTV table.

4

Char.

“”

Alias of the ISA cursor.

5

Numeric

0

Record number of the last record selected in the ISA cursor. Zero if at end-of-file.

6

Numeric

ThisForm.DataSessionID

Form’s Data Session ID.

7

Char.

“”

ISA cursor’s PK tag name.

8

Char.

“”

ISA cursor’s PK tag expression.

9

Char.

“”

Comma-delimited list of the fields in the ISA cursor’s PK tag expression.

10

 Char.

“”

List of the FKs that are in the PK of the ISA cursor. Format for each FK: nnn<Reference cursor SDATADDTV PK value>nnnn,<FK tag name>,<FK field 1>,<FK field 2>, ... , where “nnn” and “nnnn” are the lengths of the strings that follow.

11

Char.

“”

List of the FKs that are not in the PK of the ISA cursor. Same format as column 10.

12

Char.

“”

Filter expression in use on the ISA cursor when the form’s RelatedForms_Init method is run.

13

Varies

“”

If the form is a child form, contains the parent form’s ISA cursor PK value.

14

Char.

“”

If the form is a child form, contains the ISA cursor’s FK tag expression.

15

Char

ThisForm.Name

The form’s name.

16

Numeric

ThisForm.nFormInstanceNumber_Start

The form’s instance number.

 

More:

Form_Mover Class Properties and Methods