QCommenceField Class Reference

Form.Field object interface. More...

#include <QCommenceDB.h>

Inheritance diagram for QCommenceField:

Inheritance graph

List of all members.

Public Slots

void reset (void)
 Return a QDomElement previousValue.
bool isField (void)
 TRUE Field Indicator.
bool isConnection (void)
 FALSE Connection Indicator.
virtual QString name ()
 Field Text Name (passthru).
virtual QString fieldName ()
 Field Text Name (convenience).
virtual long index (void)
 Return the index number of this field.
virtual QString label (void)
 Field Text Label (passthru).
virtual QString value (void)
 Get Field Text Value (passthru).
virtual void append (QString i_value, QString i_delimeter=", ")
 Append text to a field with a delimiter.
virtual void value (QString i_value)
 Set Field Text Value.
virtual void value (QDate i_value)
 Set Field Date Value.
virtual void value (QDateTime i_value)
 Set Field by DateTime value.
virtual void value (long i_value)
 Set Field Integer Value.
virtual void value (double i_value)
 Set Field Double Value.
virtual QString var (QString i_fieldName)
 Get Field Var Value.
virtual void var (QString i_fieldName, QString i_value)
 Set Field Var Value.
virtual void delVar (QString i_fieldName)
 Delete a Var field from the field.
virtual QCommenceFieldDefdefinition (void)
 Get the Field Definition Object.
virtual bool onEnter (void)
 Execute on-enter functions.
virtual bool onLeave (void)
 Execute on-leave functions.
virtual bool onChange (void)
 Execute the onChange code.
virtual bool undo (void)
 Undo Changes.
virtual bool isDirty (void)
 Return TRUE if this field is dirty.
virtual QString previousValue (void)
 Return the previousValue.
QString changeLog (void)
 Generate a change-log string for the field.

Signals

void enter (QString o_fieldName, QString o_fieldValue)
 Field Enter Signal.
void leave (QString o_fieldName, QString o_fieldValue)
 Field Leave Signal.
void change (QString o_fieldName, QString o_fieldValue)
 Field Change Signal.

Public Member Functions

 QCommenceField (void)
 Copy Constructor.
 QCommenceField (QCocDispatch *i_unknown, QCommenceForm *i_parent, QString i_name)
 Default Constructor.
virtual ~QCommenceField ()
 Destructor.
virtual QDate toDate (void)
 Conversion Convenience Function.
virtual QTime toTime (void)
 Conversion Convenience Function.
QDomElement deValue (QDomDocument &doc, QDomNode &parent)
 Return a QDomElement value.

Protected Member Functions

QCommenceFormform (void)
 Return the parent Form object.

Private Attributes

QString m_name
 Field Name Cache.
QString m_label
 Field Label Cache.
QPointer< QCommenceFieldDefm_definition
 Field Definition Cache.
bool m_gotPreviousValue
 Field Previous Value.
QString m_previousValue
QString m_enterValue
 Field Enter Value.


Detailed Description

Form.Field object interface.

inline_dotgraph_13.dot

This is the Dumont-Enhanced Commence Field object. This object is designed to wrap a Commence Form.Field object and then add some natural extensions. These extensions include providing access to the field type properties and default values (all of which are already available through the regular API) and then provide some additional features such as field-on-change-events, undo() abilities and a changeLog() facilities which provides a text representation of how the field has changed.

One interesting aspect of the Dumont.Field object is the var() functions. These functions turn a regular field into a multi-value field using a name/value pair commonly found in .ini type files. Generally this functionality is applied to Memo type fields where a large, multi-line text area is available. This is a step in the direction of overcomming the Commence 100-field limit on the database by allowing a single Memo field to contain a variable number of additional fields.

Connections to the field objects is made from the Dumont Form object. Usually, this is most easily accomplished by implementing the following code at the top of all of your form scripts:

vbScript Typical Field Object Access
 $Object Form
 Option Explicit
 
 '
 ' Setup the Dumont environment.  Important, do not access any dfrm.Field
 '  objects until inside Form_onLoad()!  Until Form_onLoad() is called the
 '  Field.Value is unavailable and accessing it prematurely causes breakage of 
 '  the dfrm.Field("").undo code as well as other imbedded functionality.
 '
 dim ddll: set ddll = createObject("DumontDLL")  ' connect to Dumont
 dum dfrm: set dfrm = ddll.Form(Form)            ' Wrap the Commence form

 dim oFirstName  : set oFirstName  = dfrm.Field("First Name") ' Wrap a Commmence field with Dumont
 dim oLastName   : set oLastName   = dfrm.Field("Last Name")
 dim oMiddleName : set oMiddleName = dfrm.Field("Middle Name")

Definition at line 1980 of file QCommenceDB.h.


Constructor & Destructor Documentation

QCommenceField::QCommenceField ( void   )  [inline]

Copy Constructor.

Definition at line 1992 of file QCommenceDB.h.

QCommenceField::QCommenceField ( QCocDispatch i_unknown,
QCommenceForm i_parent,
QString  i_name 
)

Default Constructor.

The constructor records the current value() of the field immediately upon initialization. This is why it is important to NOT call upon a field object until the Commence Form object has entered into the Form_onLoad function. By then the Form object system is fully initialized and it is safe to call upon the Dumont Field wrapper.

Definition at line 482 of file QCommenceDB.cpp.

QCommenceField::~QCommenceField (  )  [virtual]

Destructor.

Definition at line 516 of file QCommenceDB.cpp.


Member Function Documentation

void QCommenceField::append ( QString  i_value,
QString  i_delimeter = ", " 
) [virtual, slot]

Append text to a field with a delimiter.

This method takes care of appending text to a field. One of the problems of appending text is that if the delimiter is the vbCrLf string it cannot be easily appended to the end of a line for a seperator. The string really has to be examined first to see if it has any content and then a delimiter can be used. This routine takes care of all of that.

Definition at line 561 of file QCommenceDB.cpp.

void QCommenceField::change ( QString  o_fieldName,
QString  o_fieldValue 
) [signal]

Field Change Signal.

This signal gets sent from this field whenever the value() changes between the onEnter() and onLeave() events. This is an internal Qt signal() that is designed to be hooked into by an upper-level object. For instance, the QCommenceForm object hooks in to this signal so that the hosting form can be informed when any field is changed.

This is an internal function and is not meant to be called from vbScript.

QString QCommenceField::changeLog ( void   )  [slot]

Generate a change-log string for the field.

This is a convenience function designed to format a change-log string for use in... well... anywhere. The format of the output is <<"FieldName" from "previousValue" to "newValue">>. The QCommenceForm object uses this method to document changes to fields on a form. It is generally used in conjunction with the isDirty() method to determine if there were any changes to the field and generates a log value if so.

This method can be called directly from vbScript as follows:

vbScript Example:
 msgbox dfrm.Field("First Name").changeLog
See also:
QCommenceForm::changeLog(), Change Log Engine

Returns:
Formatted ChangeLog or an empty string if there were no changes

Definition at line 751 of file QCommenceDB.cpp.

QCommenceFieldDef * QCommenceField::definition ( void   )  [virtual, slot]

Get the Field Definition Object.

This method makes a DDE request to retrieve the field definition string. This string value is then cached and used for the various field definition function calls to avoid having to make multiple calls into the Commence API.

Definition at line 690 of file QCommenceDB.cpp.

void QCommenceField::delVar ( QString  i_fieldName  )  [virtual, slot]

Delete a Var field from the field.

The method deletes a var element from the var field. This is useful when you need to clean up a var field and remove some values completely. This is entirely different from setting a var field to "" since doing that merely causes the var field to be SET to nothing, rather than removed entirely.

vbScript Example
 dfrm.Field("calendarVar").delVar "createdOn"

Definition at line 680 of file QCommenceDB.cpp.

QDomElement QCommenceField::deValue ( QDomDocument &  doc,
QDomNode &  parent 
)

Return a QDomElement value.

This returns a QDomElement as the current value of this field.

Definition at line 779 of file QCommenceDB.cpp.

void QCommenceField::enter ( QString  o_fieldName,
QString  o_fieldValue 
) [signal]

Field Enter Signal.

This signal get sent from this field whenever the onEnter() event is called. This is an internal Qt signal() that is designed to be hooked into by an upper-level object. For instance, the QCommenceForm object hooks in to this signal so that the hosting form can be informed when any field is entered into.

This is an internal function and is not meant to be called from vbScript.

QString QCommenceField::fieldName ( void   )  [virtual, slot]

Field Text Name (convenience).

This function is identical to the name function. It is provided as a matter of convenience and api consistency. Useing FieldName is easy to remember because the form scripts use FieldName in many of their functions. This makes the source code much more readable. It, therefore, can be used as follows:

vbScript Example - FieldName to FieldName comparison
 Sub Form_OnEnterField(ByRef FieldName)

   if( oFirstName.FieldName = FieldName ) then
     msgBox "you are on the " & FieldName & " field"
   end if

 End Sub

Definition at line 548 of file QCommenceDB.cpp.

QCommenceForm * QCommenceField::form ( void   )  [protected]

Return the parent Form object.

This function returns a pointer to this field's parent Form. It is private because nothing on this field should be being called except through the form anyway, so providing a pointer to that said form is problemmatic and probably a pointer crash issue. It's only used internally, and is provided so that this field can access the database and conversation API. This method should *not* be called from vbScript.

Definition at line 685 of file QCommenceDB.cpp.

long QCommenceField::index ( void   )  [virtual, slot]

Return the index number of this field.

Definition at line 809 of file QCommenceDB.cpp.

bool QCommenceField::isConnection ( void   )  [slot]

FALSE Connection Indicator.

This is a convenicen function that returns always FALSE for field objects.

Definition at line 536 of file QCommenceDB.cpp.

bool QCommenceField::isDirty ( void   )  [virtual, slot]

Return TRUE if this field is dirty.

This function returns TRUE when the current field value() does not equal the previousValue().

Definition at line 741 of file QCommenceDB.cpp.

bool QCommenceField::isField ( void   )  [slot]

TRUE Field Indicator.

This is a convenience function that returns always TRUE for field objects.

Definition at line 531 of file QCommenceDB.cpp.

QString QCommenceField::label ( void   )  [virtual, slot]

Field Text Label (passthru).

This returns the 'Label' of the Form field. This is a passthrough function that transfers control directly to the Commence Form.Field object and therefore returns the same data as the standard Form.Field("Name").Label call.

vbScript example:
 msgbox dfrm.Field("calendarKey").Label
Note:
This value is cached so that repeated lookups do not make repeated calls into the Commence API.

Definition at line 554 of file QCommenceDB.cpp.

void QCommenceField::leave ( QString  o_fieldName,
QString  o_fieldValue 
) [signal]

Field Leave Signal.

This signal gets sent from this field whenever the onLeave() event is called. This is an internal Qt signal() that is designed to be hooked into by an upper-level object. For instance, the QCommenceForm object hooks in to this signal so that the hosting form can be informed when any field is left from.

This is an internal function and is not meant to be called from vbScript.

QString QCommenceField::name ( void   )  [virtual, slot]

Field Text Name (passthru).

This returns the 'Name' of the Form field. This is a passthrough function that transfers control directly to the Commence Form.Field object and therefore returns the same data as the standard Form.Field("Name").Name call.

vbScript example:
 msgbox dfrm.Field("calendarKey").Name   ' shows "calendarKey"

Definition at line 541 of file QCommenceDB.cpp.

bool QCommenceField::onChange ( void   )  [virtual, slot]

Execute the onChange code.

This routine does whatever on-change things need to be done to this field item. There may be nothing. A signal does get fired indicating that this field has a change event. This is an internal function that gets called when the user calls the onLeave() function and there is a data-delta in the before and after values - indicating that a change has been made.

This function fires a signal change().

Definition at line 722 of file QCommenceDB.cpp.

bool QCommenceField::onEnter ( void   )  [virtual, slot]

Execute on-enter functions.

This function is intended to be called by the parent form to indicate that the field has become active in the user interface and may possibly be edited.

This function fires a signal enter().

Definition at line 701 of file QCommenceDB.cpp.

bool QCommenceField::onLeave ( void   )  [virtual, slot]

Execute on-leave functions.

This function is intended to be called by the parent form to indicate that the field has become inactive in the user interface and is no longer being edited.

This function fires a signal leave().

Definition at line 709 of file QCommenceDB.cpp.

QString QCommenceField::previousValue ( void   )  [virtual, slot]

Return the previousValue.

This returns the previous value of the field. The previousValue() is based upon the value of the field at the time this Field object was created. When Dumont is requested for a Field object, it records the current Commence field value and stores that as its previous value. All changes to the field value then become the new value, and referring to the previous value always refers to the absolute beginning value of the field, not the previous value from the most recent change.

Definition at line 746 of file QCommenceDB.cpp.

void QCommenceField::reset ( void   )  [slot]

Return a QDomElement previousValue.

Return a QDomElement ChangeLog value This returns a xml formatted change log element

Return a XML document value

Return a XML changeLog value

Reset the field back to its 'untouched' state.

Definition at line 503 of file QCommenceDB.cpp.

QDate QCommenceField::toDate ( void   )  [virtual]

Conversion Convenience Function.

This convenience function returns the value() as a QDate object. This is useful in instances where the field type is a Commence Date field and it needs to be reformatted into an actual Qt QDate style object. This is an internal function and it not available to the vbScript interface.

Note:
This function makes no assumptions about the type and data contained in the value() before conversion. The conversion is more or less applied blindly.

Definition at line 660 of file QCommenceDB.cpp.

QTime QCommenceField::toTime ( void   )  [virtual]

Conversion Convenience Function.

This convenience function returns the value() as a QTime object. This is useful in instances where the field type is a Commence Time field and it needs to be reformatted into an actual Qt QTime style object. This is an internal function and it not available to the vbScript interface.

Note:
This function makes no assumptions about the type and data contained in the value() before conversion. The conversion is more or less applied blindly.

Definition at line 665 of file QCommenceDB.cpp.

bool QCommenceField::undo ( void   )  [virtual, slot]

Undo Changes.

This function restores a field to its previousValue() before any changes were applied. This is a one-step change (ie; it does not maintain incremental changes... yet!)

Definition at line 729 of file QCommenceDB.cpp.

void QCommenceField::value ( double  i_value  )  [virtual, slot]

Set Field Double Value.

This is an overloaded function for convenience. It takes a double precision number and converts it to a string.

Definition at line 652 of file QCommenceDB.cpp.

void QCommenceField::value ( long  i_value  )  [virtual, slot]

Set Field Integer Value.

This is an overloaded function for convenience. It takes a long-integer and converts it to a numeric string value.

Definition at line 644 of file QCommenceDB.cpp.

void QCommenceField::value ( QDateTime  i_value  )  [virtual, slot]

Set Field by DateTime value.

This is an overloaded function for convenience. It takes a Qt DateTime and converts it to the appropriate value if the field is a string, or a date field or a time field.

Definition at line 621 of file QCommenceDB.cpp.

void QCommenceField::value ( QDate  i_value  )  [virtual, slot]

Set Field Date Value.

This is an overloaded function for convenience. It takes a Qt date and converts it to a "m/d/yyyy" value.

Definition at line 613 of file QCommenceDB.cpp.

void QCommenceField::value ( QString  i_value  )  [virtual, slot]

Set Field Text Value.

This sets the 'Value' of the Form field. This is a passthrough function that transfers control directly to the Commence Form.Field object and therefore sets the same data as the standard Form.Field("FieldName").Value = "xyz" call.

Note:
This function also tests the new value against the current value, and if there is no change then no updates will be performed on the database. This can help reduce the number of updates the database has to sync around the workgroup in the event no real data is changing on the field. This is particularily useful when scripted-updates are occuring on various text-type-memo fields that the user doesn't update, but the script updates automatically. The script can just update the field value blindly and if there is an actual data field change, then, and only then will that change be written to the commence field, thus reducing the amount of data that has to get synced around the workgroup.
vbScript example:
 dfrm.Field("calendarKey").Value = "new value"

Definition at line 595 of file QCommenceDB.cpp.

QString QCommenceField::value ( void   )  [virtual, slot]

Get Field Text Value (passthru).

This returns the 'Value' of the Form field. This is a passthrough function that transfers control directly to the Commence Form.Field object and therefore returns the same data as the standard Form.Field("Name").Value call.

vbScript example:
 msgbox dfrm.Field("calendarKey").Value

Definition at line 573 of file QCommenceDB.cpp.

void QCommenceField::var ( QString  i_fieldName,
QString  i_value 
) [virtual, slot]

Set Field Var Value.

This sets a Var value in a Form field. This function takes the raw text value of a field and turns it into a multi-value Var field. The format follows the typical format of a .ini style settings file, with name/value pairs. Var fields are normally contained within a Commence Memo type of field. The syntax is as follows:

vbScript example:
  a memo field containing:
   cmcID=0:80006401:844F7302
   createdOn=20060805195512
   createdBy=MHS:A:80006401:00000BCE
   changedOn=20060805195512
   changedBy=MHS:A:80006401:00000BCE

 can be accessed with the following:
 dfrm.Field("calendarVar").var("createdOn") = ddll.packDateTime
This is a step to overcoming the 100-field barrier in Commence.

Definition at line 675 of file QCommenceDB.cpp.

QString QCommenceField::var ( QString  i_fieldName  )  [virtual, slot]

Get Field Var Value.

This gets a Var value from the Form field. This function takes the raw text value of a field and turns it into a multi-value Var field. The format follows the typical format of a .ini style settings file, with name/value pairs. Var fields are normally contained within a Commence Memo type of field. The syntax is as follows:

vbScript example:
  a memo field containing:
   cmcID=0:80006401:844F7302
   createdOn=20060805195512
   createdBy=MHS:A:80006401:00000BCE
   changedOn=20060805195512
   changedBy=MHS:A:80006401:00000BCE

 can be accessed with the following:
 msgbox dfrm.Field("calendarVar").var("createdOn") ' 20060805195512
This is a step to overcoming the 100-field barrier in Commence.

Definition at line 670 of file QCommenceDB.cpp.


Member Data Documentation

Field Definition Cache.

The field definition is not going to change once the connection to the field has been established, so we cache it here so as to reduce the number of calls into the Commence API to retreive this information.

See also:
definition, type, isShared, isMandatory, isRecurring,

isSelection, maxChars, defaultString

Definition at line 2550 of file QCommenceDB.h.

QString QCommenceField::m_enterValue [private]

Field Enter Value.

This is a cache of the field value when the onEnter() function gets called It is used in the onLeave() function to examine the field value to determine if it has changed.

See also:
onEnter, onLeave, onChange

Definition at line 2573 of file QCommenceDB.h.

Field Previous Value.

This is a cache of the field value when this field object was first accessed. This value is used in the isDirty() functions and changeLog() functions

See also:
previousValue, undo

Definition at line 2561 of file QCommenceDB.h.

QString QCommenceField::m_label [private]

Field Label Cache.

The field label is not going to change once the connection to the field has been established, so we cache it here so as to reduce the number of calls into the Commence API to retreive this information.

See also:
label

Definition at line 2536 of file QCommenceDB.h.

QString QCommenceField::m_name [private]

Field Name Cache.

The field name is not going to change once the connection to the field has been established, so we cache it here so as to reduce the number of calls into the Commence API to retreive this information.

See also:
name

Definition at line 2523 of file QCommenceDB.h.

Definition at line 2562 of file QCommenceDB.h.


The documentation for this class was generated from the following files:




~ ~ ~ ~ ~ ~
Source Code without Comments is like a Cranberry Garland
without the berries. Comment your Code!
 
Commence Database User Support Group Forum
http://newsgroup.showoff-db.org/
~ ~ ~ ~ ~ ~
Author: Mark Petryk
Lorimark Solutions, LLC
mark@lorimarksolutions.com