Form_Toolbar Class Properties and Methods

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:

 

BufferMode = 2

Optimistic record locking. Records are not locked until they are updated.

Caption = “Form_Toolbar”

 

DataSession = 2

Form uses a private data session by default.

Height = 330

 

MDIForm = .T.

 

Name = “form_toolbar”

 

Custom Properties:

 

cFindFields = “”

Can be used to identify the fields to be used in the toolbar Find form. Contains a comma-delimited list of fields in the order in which the fields should appear on the form.

cFindForm = “find”

Contains the name of the Find form or form class.

cFindForm_ClassLibrary = “progen”

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

cFindForm_SQL_AltCaptions = “”

When the SQL Find form is used, specifies captions to be used on the form (semi-colon delimited list) instead of captions from the data dictionary. The captions should be entered into the property in the order in which the associated parameters parameters (Find<field name> variables) will be displayed on the Find form. Captions can be entered selectively, meaning that only those captions that should be different than the captions that would be used by default from the data dictionary need to be specified.

cFindUserForm = “finduser”

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

cFindUserForm_ClassLibrary = “prosec”

Contains the name of the class library that contains the Find User form class if cFindUserForm contains the name of a form class.

cInitialSelectedAlias = “”

If an alias is not specified in the InitialSelectedAlias property of the DE, this property can be used to specify the ISA of the form.

cListCaptions = “”

Comma-delimited list of field captions used by the toolbar List form.

cListCaptions_Alt = “”

Used instead of cListCaptions if cListFields_Alt is filled-in when a Find or Locate is performed in a Related Forms situation and a List is displayed because more than one record matched the search criteria.

cListFields = “”

Comma-delimited list of fields used by the toolbar List form.

cListFields_Alt = “”

Used instead of cListFields if filled-in when a Find or Locate is performed in a Related Forms situation and a List is displayed because more than one record matched the search criteria.

cListForm = “list”

Contains the name of the List form or form class.

cListForm_ClassLibrary = “progen”

Contains the name of the class library that contains the List form class if cListForm contains the name of a form class.

cListSQLFields = “”

Used where a subset of the records in the ISA table would normally be displayed using a filter in the toolbar List form. To use a SQL cursor instead, this property contains the Fields clause of a SELECT command that is equivalent to the cListFields entry.

cListSQLFields_Alt = “”

Used instead of cListSQLFields if it is filled-in when a Find or Locate is performed in a Related Forms situation and a List is displayed because more than one record matched the search criteria.

cListTags = “”

Comma-delimited list of index tags by the toolbar List form.

cListTags_Alt = “”

Used instead of cListTags if cListFields_Alt is filled-in when a Find or Locate is performed in a Related Forms situation and a List is displayed because more than one record matched the search criteria.

cNotBlankFields = “”

Comma-delimited list of fields that are required to have a non-empty value. The check is performed upon saving. If the field is not in the Initial Selected Alias cursor, preface the field name with the cursor’s alias and a “.”.

cOrderForm = “order”

Contains the name of the Order form or form class.

cOrderForm_ClassLibrary = “progen”

Contains the name of the class library that contains the Order form class if cOrderForm contains the name of a form class.

cPrintCommand = “”

Command to be executed when the toolbar Print button is clicked.

cPrintReport = “”

Report to be run when the toolbar Print button is clicked.

cRFForeignKeyExpr = “”

If the form is a Related Forms child form, will contain the foreign key expression.

cRFForeignKeyFlds = “”

If the form is a Related Forms child form, will contain a comma-delimited list of foreign key fields.

cRFForeignKeyTag = “”

If the form is a Related Forms child form, will contain the name of the foreign key tag.

cRFParentAlias = “”

If the form is a Related Forms child form, will contain the alias of the parent table.

cRFParentPKFlds = “”

If the form is a Related Forms child form, will contain a comma-delimited list of the parent table’s primary key fields.

cRulesID = “”

Created for the developer, is passed to certain methods of the form as well as Business Rules Object (PreSave, PostSave, etc.). Can be used to pass information necessary to perform the function.

cToolbar = “toolbar_all”

The name of the toolbar class from which a toolbar will be instantiated when the form is run.

cToolbar_ClassLibrary = “proforms”

Contains the name of the class library that contains the toolbar class specified in cToolbar.

cUpdateAliases = “”

Comma-delimited list of the aliases other than the ISA that should be updated upon saving. For use with MTE (multiple table editing).

External_cFindFields = “”

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

External_cParentFilterExpr = “”

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

External_lAllowNoOrder = .F.

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

External_lCancel = .F.

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

External_lOrderChildOnly = .F.

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

lAddWhenNoChildRecs = .F.

If the form is Related Forms child form, automatically add a record when the form is activated and there are no records to be displayed or the last record is deleted.

lAddWhenNoRecs = .T.

If the form is not a Related Forms child form, automatically add a record when the form is activated and there are no records to be displayed or the last record is deleted.

lAllowCopy = .T.

Enables the Copy toolbar button.

lAllowDelete = .T.

Enables the Delete toolbar button.

lAllowEdits = .T.

If .F., disables the New, Copy, More, Save and Cancel toolbar buttons. Used when not editing data through the form.

lAllowFilter = .T.

Enables the Filter toolbar button.

lAllowFind = .T.

Enables the Find toolbar button.

lAllowGroupDelete = .T.

Enables the Group Delete toolbar button.

lAllowList = .T.

Enables the List toolbar button.

lAllowLocate = .T.

Enables the Locate toolbar button.

lAllowMore = .T.

Enables the More toolbar button.

lAllowNew = .T.

Enables the New toolbar button.

lAllowNoOrder = .T.

On the Order form, adds the “Do not use an index” selection, which will allow records to be displayed in record number order.

lAllowOrder = .T.

Enables the Order toolbar button.

lAllowParentMode = .T.

Enables the Parent Mode toolbar button.

lAllowPrint = .T.

Enables the Print toolbar button.

lAskToCopyChildMessage = .F.

If .T., and the lCopyChildWithParent property is set to .T., causes a message to be displayed when the current parent record is about to be copied. The message asks the user if they want to also copy the child records. If .F., and the lCopyChildWithParent property is set to .T., the child records are automatically copied.

Note: The child copy functionality will only work if the PK field of the parent contains a generated key.

lAskToDeleteMessage = .T.

If .T., causes a message to be displayed when the current record is about to be deleted. The message asks the user if they want to delete the record. If .F., the deletion is automatically performed.

lAskToGroupDeleteMessage = .T.

If .T., causes a message to be displayed when the Group Delete condition is about to be used to delete a group of records. The message asks the user if they want to continue with the deletions. If .F., the deletions are automatically performed.

lAskToSaveMessage = .T.

If .T., causes a message to be displayed when the record pointer is about to be moved off the current record. The message asks the user if they want to save the changes that have been made. If .F., changes are automatically saved.

lAutoSaveOnReactivation = .F.

When changes are made on a form and the form is deactivated, the user is prompted upon reactivation as to whether they want to save those changes. If .T., the user is not prompted and the changes are automatically saved.

lBlankOutPKFlds = .T.

If .T., causes the PK field(s) to be blanked-out on a copy. Normally, the PK field(s) should be blanked-out because the user will need to enter unique values. However, on a Related Pages form, records added on child pages should not have the PK fields blanked-out in order for the relation to be retained with the parent record.

lCopyChildWithParent = .F.

When set to .T. on a OTM form, allows child records to be copied along with a parent record. Used in conjunction with the lAskToCopyChildMessage property.

lEditableGrid = .F.

Is set to .T. by the Grid Builder because of special functionality required when editing data through a grid.

lEditMode = .F.

If .T., enables edit mode functionality.

lEditModeOn = .F.

Will be set to .T. when in edit mode and .F. when not.

lEditMultTable_PKChanged = .F.

Used with multiple-table editing to identify when the PK of the ISA cursor has been changed.

lFilter = .F.

Is set to .T. when the user has clicked the toolbar Filter button and a filter has been set.

lFindForm_SQL_NoEntriesOK = .F.

When the SQL Find form is used with a form, specifies whether the user can leave all parameters empty. Doing so causes the List form to come up showing all records.

lFindForm_SQLOverride = .F.

If .T., causes the standard Find form to be used instead of the SQL Find form even though the cursor is a parameterized view or cursoradapter. This causes only the records in the cursor to be searched.

lFKUpdate = .F.

Set to .T. when the Add New option on the right-click menu or the Add button on the F2 Picklist form is clicked. This causes the FK field to be updated with the PK of the new Picklist cursor record.

lFKUpdateOneAdd = .F.

If .T. and the Add New option on the right-click menu or the Add button on the F2 Picklist form is clicked, the Picklist cursor editing form is automatically closed after the initial new record is saved or cancelled.

lFKUpdateRequeryView = .F.

Set to .T. when the Add New or Edit option on the right-click menu or the Add or Edit button on the F2 Picklist form is clicked. This causes the requery/refresh of the FK field’s lookup cursor upon form reactivation.

lMessageOnAutoAdd = .T.

When set to .T., causes a message to be displayed when a record is automatically added when there are no records.

lMessageOnAutoChildAdd = .T.

When set to .T., causes a message to be displayed when a record is automatically added when there are no child records.

lMessageOnReactivation = .T.

When lAutoSaveOnReactivation is set to .F., determines whether the user is prompted as to whether changes should be saved.

lMessageOnReactivation_NotThisTime = .F.

If .T., prevents the reactivation message the first time the form is reactivated.

lNoChangeAuditTrail = .F.

If .T., turns off the creation of audit trail records for changes to field values.

lNoDeleteAuditTrail = .F.

If .T., turns off the creation of audit trail records for deleted records.

lNoNewAuditTrail = .F.

If .T., turns off the creation of audit trail records for new records.

lRemoveRelationsOverride = .F.

If .T., causes the opposite behavior of the RemoveRelations method to occur.

lRestoreWindowPos_Form_ Toolbar = .T.

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

lRFAllowOneChildRec = .F.

If .T., is used by the toolbar’s Refresh method to disable the New and Copy buttons in order to limit to one the number of child records on a Related Forms child form.

lRFDisable = .F.

If .T., disables the Related Forms functionality of the form.

lRFParentMode = .F.

On a Related Forms child form, lRFParentMode will be set to .T. when in Parent Mode.

lRFStartWithAdd = .F.

Identifies the situation where there is no record in the ISA that is related to the current record on a Related Form.

lRFStartWithAddMessage = .T.

If .F., will prevent the default message from being displayed when lRFStartWithAdd is set to .T..

lSaveCancelOnly = .F.

Used internally.

lShowNavToolbarInit = .F.

If .T., causes the toolbar to be instantiated from the form’s Init method instead of the Activate method.

lSkipActivate = .F.

When an object is run that is outside the form, like a report or another form, the form’s Activate method will be run when returning. This is not normally desired because of the functionality performed, like asking if you want to save changes. Setting lSkipActivate to .T. will prevent the Activate method functionality from running. The Activate method will reset lSkipActivate to .F..

lSkipRowColChange = .F.

In certain situations, the functionality in the AfterRowColChange method of an editable grid should be bypassed. By default, the functionality is not bypassed.

lStartWithAdd = .F.

If .T., will cause the form to come up on a new record.

lStartWithFind = .F.

If .T., causes the Find form to come up when the form is initially run. The SQL Find form or the standard Find form is brought up depending on whether or not the current cursor is a parameterized view or cursoradapter and the value in the lFindForm_SQLOverride property.

lTrans_Form_ = .F.

When using the multilingual functionality, the translation of properties needs to occur at the end of the Form_Toolbar.Init instead of at the end of the Form_.Init.

lTrans_Form_Toolbar = .T.

See comments for lTrans_Form_.

lUpdateAliases_Add = .F.

If .T. and the New button is clicked, causes a record to be added to the aliases listed in the cUpdateAliases property.

lUpdateAliases_Copy = .F.

If .T. and the Copy button is clicked, causes the current record to be copied in the aliases listed in the cUpdateAliases property.

nListRows = 0

The number of rows to display in the toolbar List form.

nListRows_Alt = 0

Used instead of nListRows if cListFields_Alt is filled-in when a Find or Locate is performed in a Related Forms situation and a List is displayed because more than one record matched the search criteria.

nListWidth = 0

The width of the toolbar List form.

nListWidth_Alt = 0

Used instead of nListWidth if cListFields_Alt is filled-in when a Find or Locate is performed in a Related Forms situation and a List is displayed because more than one record matched the search criteria.

nParentFormRow = 0

In a Related Forms situation, contains the row number in the Active Forms array of the parent form.

nRecordBeforeAddCopy = 0

Holds the record number of the record that was the current record when the New, Copy, or More toolbar button was clicked. If the add or copy is cancelled, the record pointer is positioned to this record and displayed.

nSetFocusToFirst_EditPage = 0

When using the edit mode functionality on a form and the Edit button is clicked, the number in this property determines which page of a pageframe is activated. If zero (the default), the currently active page remains the active page.

nSetFocusToFirst_Page = 1

Used in the SetFocusToFirst method to identify which page of a pageframe should be activated when the New or Copy toolbar button is clicked.

oDisableWhenAddFails = .F.

With an edit mode, SetFocusToFirst places into this property the object reference of the control that will initially have focus. This allows that control, which was enabled so that it could receive focus, to be disabled if the record could not be added.

oFKUpdate = .F.

When a FK field value is to be updated with the PK value of a new Picklist cursor record, this property is used to reference the properties of the control to which the FK field is bound.

oGridFocusParent = .F.

The object reference of the Grid Focus button’s parent object.

oListGrid = .F.

The object reference of a List Grid that is on the form.

oListGridParent = .F.

The object reference of the List Grid’s parent object.

oOnFormContainer = .F.

The object reference of the On-Form Toolbar container.

RFChildValue = “”

If this property contains a value, finds the record that has a matching PK value. See comment in RelatedForms_PositionParent method.

RFParentValue = “”

In a Related Forms situation, contains the PK value of the parent record.

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

If the form is using a toolbar, makes pressing <Escape> the same as clicking the Cancel button.

If the property lSkipActivate is set to .T., bypasses the remaining Activate method code.

Makes the Initial Selected Alias cursor the active cursor.

Refreshes the menu.

Prompts the user to save changes if changes were made prior to the form’s deactivation.

Determines if in a Related Form situation. If so, positions the record pointer.

If no records in parent match current child or if no records, automatically goes into “add mode”.

Refreshes the toolbar if the form is using one.

If the form is being activated for the first time, restores the form’s position.

Determines if the form should come up in the “add mode” (lStartWithAdd = .T.) or bring up the Find form (lStartWithFind = .T.).

Deactivate

Disables the Escape key functionality described in Activate method.

Destroy

Disables the Escape key functionality described in Activate method.

Releases the toolbar.

Removes relations.

Init

Displays the toolbar specified in the cToolbar and cToolbar_ClassLibrary properties.

Adds Related Forms info to the Active Forms array.

If using the multilingual functionality, translates the properties of the form and its objects.

 QueryUnload

Writes out the contents of the current control to the buffer.

Makes the Initial Selected Alias cursor the active cursor.

If in the add mode but nothing has been entered, cancels the add.

If changes have been made, asks the user if they want to save those changes.

Removes the Grid Focus button that was added in the Init method of the editable grid or List Grid.

Releases the object references that are stored in form properties.

Custom Methods:

 

AddNew

Selects the active cursor and adds a record. The new record is then displayed on the form.

AskToSave

Prompts the user to save changes if necessary.

Child_CopyWithParent

This method does not contain any code in this class. See the comments for this method in the Form_Toolbar_OneToMany class.

Copy

Selects the active cursor and copies the current record. The new record is then displayed on the form.

Delete

Selects the active cursor and deletes the current record.

EnableDisableControls

Enables and disables a container object’s controls depending on:

·       Whether the Edit Mode functionality is being used,

·       The form’s lAllowEdits property setting,

·       Each control’s lEnabledOnlyWhenNew property setting, and

·       The contents of each control’s cEnabledOnlyWhenNewExpression property.

Parameters: stoStartObject, stlMakeEnabled, stlMakeDisabled

EnableDisableToolbar Controls

Used to conditionaly enable and disable controls on the form and its toolbar through developer code as well as the contents of each control’s cEnabledExpression property.

See the comments in this method in the Form_Toolbar class in VPMForms.vcx for a detailed explanation of how to use this method.

Parameters: stnPrePost, stnReason

Filter

Brings up the Condition Builder form where the user can build a filter expression which is used to exclude records that do not meet the condition criteria.

Find

Brings up a form where the user can enter search values. If the current cursor is a table cursor or a non-parameterized view or cursoradapter, the standard Find form is brought up where values can be entered for any field in the master tag and primary key tag or the fields specified in the cFindFields property. If the current cursor is a parameterized view or cursoradapter, the SQL Find form is brought up where values can be entered for fields identified by Find<field name> filter variables.

First

Moves the record pointer in the current cursor to the first record.

FKUpdate

Updates the value in a FK field when a record is added to the Picklist cursor through the form brought up by the Add New option on the right-click menu or the Add button on the F2 Picklist form.

Parameter: stoFKUpdate

FKUpdateRequeryView

Repopulates the FK field’s lookup cursor upon form reactivation after the Add/Edit form has been closed.

GetConditionPageNumber

If more than one page of a Related Pages pageframe displays data from the same cursor, normally, any conditions that are created in the Condition Builder (Filter, Group Delete, or Locate) are shown only for the page for which the Condition Builder was brought up. This method allows the Condition Builder to show the same list of conditions for each page that uses a common cursor. It also allows those pages to share a single set of fields from which the user can select, those specified in the Condition Field List Builder.

 

For example, if page 2 and page 3 both display fields from the same cursor, those pages can share the same list of conditions as well as the list of fields from which the user can select. In that case, this method would contain:

 

LPARAMETERS stcCalledBy

RETURN IIF(ThisForm.pgfRelated.ActivePage = ;

   3,2,ThisForm.pgfRelated.ActivePage)

 

The parameter stcCalledBy identifies the method that called this method (LOCATE, FILTER, or GROUPDELETE) in case the sharing of conditions is dependent upon the function being performed.

 

Parameter: stcCalledBy

GroupDelete

Brings up the Condition Builder form where the user can build an expression which will be used to delete records that meet the condition criteria.

IdentifyDataChanged Aliases

Returns a string containing a comma-delimited list of the aliases that should be checked by the DataChanged method of the data handler for the existence of modified records. The aliases listed are in addition to the current cursor. By default the string that is returned is the string stored in the cUpdateAliases property.

Last

Moves the record pointer in the current cursor to the last record.

List

Brings up the List form where the user can select a record from the current cursor. The selected record becomes the record displayed on the form.

Locate

Brings up the Condition Builder form where the user can build an expression that is used to find a record that matches the condition criteria.

Next

Moves the record pointer in the current cursor to the next record.

Order

Brings up a form where the user can select a new master (controlling) index tag.

Print_Toolbar

Runs the report specified in the property cPrintReport. If cPrintReport is empty, runs the command specified in the property cPrintCommand. If cPrintCommand is empty, brings up the Report Manager.

Prior

Moves the record pointer in the current cursor to the prior record.

RefreshToolbar

Runs the Refresh event of the form’s toolbar, whether an on-form toolbar or a standard toolbar.

RelatedForms_Activate

Positions the record pointer to the last recorded position when a form is reactivated.

Updates the cActiveFormDateTime property and then sorts the array _SCREEN.oApp.aActiveForms in descending order.

Checks for a Related Forms situation. If found, the records displayed by the form are set appropriately.

Parameter: stlCurRecChanged

RelatedForms_

ChangeParent

When in Parent Mode on a Related Forms child form, moves the record pointer in the parent form’s ISA cursor when the First, Prior, Next or Last toolbar button is clicked.

Parameter: stcMode

RelatedForms_Inactive

Called when this form is a Related Forms child form and a related Related Forms parent form is the active form. It is called to aid in positioning the current (parent) record pointer to the first record that matches the current child record

Parameter: stcFKTag

RelatedForms_Init

Fills-in Related Forms information in the form’s row in the Active Forms array.

RelatedForms_

PositionChild

Finds the first child record related to the current parent record. If there is no master tag and no FK tag has been specified, the related form situation cannot be implemented. If there are no child records that match the current parent record, lets the user know that they will be placed in the add mode.

Parameter: stlGoLast

RelatedForms_

PositionParent

If the RFChildValue property contains a value, finds the record that has a matching PK value.

RelatedForms_

SavePosition

Saves the record number of the ISA cursor in the form’s row in the Active Forms array. This information is used when this form is reactivated, a related form is activated or a related form is reactivated.

RemoveRelations

Removes relations when the form is closed. The default behavior is to only remove the relations when the form is modeless, uses the default datasession, and does not have the cursors closed automatically through the AutoCloseTables property. The opposite of the default behavior will be performed if the lRemoveRelationsOverride property is set to .T.. The relations that are removed are those that have been set from the ISA and cUpdateAliases cursors.

Restore

Cancels all changes made to the current record in the current cursor and other cursors specified in cUpdateAliases. Also cancels the New and Copy operations.

Parameter: stlCancel

RunFindForm

Runs the form specified in the properties cFindForm and cFindForm_ClassLibrary.

Parameter: stoDataSourceForm

RunFindUserForm

Runs the form specified in the properties cFindUserForm and cFindUserForm_ClassLibrary.

RunListForm

Runs the form specified in the properties cListForm and cListForm_ClassLibrary.

Parameters: stoDataSourceForm, stlFromFind

RunOrderForm

Runs the form specified in the properties cOrderForm and cOrderForm_ClassLibrary.

Parameter: stoDataSourceForm

Save

Saves the current record and records in additional cursors that are specified in the property cUpdateAliases.

Select_Active

Makes sure the active (ISA) cursor is selected.

SetFocusToFirst

Sets focus to the first control on the form or page.

Parameter: stlStartEditMode

ShowNavToolbar

Displays the toolbar specified in the parameters.

Parameters: stcToolbar, stcToolbar_ClassLibrary, stcFormName, stlBypassRefresh, stnCalledFrom

WriteBuffer

Called prior to updating (writing) the current record to disk. All changes must be committed to the buffer before updating. If the focus has not been moved off a control where a change has been made when clicking on the toolbar, this method commits that change to the buffer.

Parameter: stlCancel

 

More:

Form_SingleRecord Class Properties and Methods