DumontEXE 0.0.1
Public Slots | Protected Member Functions | Protected Attributes
cmcField Class Reference

Field. More...

#include <cmcField.h>

Inheritance diagram for cmcField:

List of all members.

Public Slots

virtual void append (QString appendValue, QString separator=", ")
 Append text to a field with a delimiter
.
virtual QString changeLog ()
 Generate a change-log string for the field
.
virtual void clear ()
 Clear the current value
.
virtual bool contains (const QString &subString)
 Tests for substring
.
virtual cmcFieldDefdefinition ()
 Get the Field Definition Object
.
virtual void delVar (QString fieldName)
 Delete a Var field from the field
.
virtual QString fieldName ()
 Field Text Name (convenience)
.
virtual long index ()
 Return the index number of this field
.
virtual bool isBlank ()
 Test for no data
.
virtual bool isConnection ()
 FALSE Connection Indicator
.
virtual bool isDirty ()
 Return TRUE if this field is dirty
.
virtual bool isFalse ()
 Boolean Conversion
.
virtual bool isField ()
 TRUE Field Indicator
.
virtual bool isGuid ()
 Test for GUID type of data
.
virtual bool isNotBlank ()
 Test for data
.
virtual bool isNotGuid ()
 Test for Not GUID type of data
.
virtual bool isTrue ()
 Boolean Conversion
.
virtual QString label ()=0
 Return a QDomElement value
.
virtual long length ()
 The length of the field
.
virtual QString line (long lineNumber, long maxChar=-1)
 Get First line of Memo
.
virtual QString name ()
 Field Text Name (passthru)
.
virtual QString previousValue ()
 Return the previousValue
.
virtual void reset ()
 Reset the field back to its 'untouched' state.
.
virtual cmcSubFieldsubField (QString fieldName)
 Sub Field
.
virtual QDate toDate ()
 Conversion Convenience Function
.
virtual QTime toTime ()
 Conversion Convenience Function
.
virtual bool undo ()
 Undo Changes
.
virtual QString unpackDateTime ()
 Unpack a packed Date/Time
.
virtual QString value ()=0
 Get Field Text Value (passthru)
.
virtual void value (bool value)=0
 Set Field Boolean Value
.
virtual void value (QString value)=0
 Set Field Text Value
.
virtual void value (QDate value)
 Set Field Date Value
.
virtual void value (long value)
 Set Field Integer Value
.
virtual void value (double value)
 Set Field Double Value
.
virtual void var (QString fieldName, QString newValue)
 Set Field Var Value
.
virtual QString var (QString fieldName)
 Get Field Var Value
.

Protected Member Functions

cmcFormform ()
 Return the parent Form object
.

Protected Attributes

QPointer< cmcFieldDefm_definition
 Field Definition Cache
.
bool m_gotPreviousValue
 Field Previous Value
.
QString m_label
 Field Label Cache
.

Detailed Description

Field.

Definition at line 44 of file cmcField.h.


Member Function Documentation

void append ( QString  appendValue,
QString  separator = ", " 
) [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 142 of file cmcField.cpp.

QString changeLog ( ) [virtual, 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 272 of file cmcField.cpp.

void clear ( void  ) [virtual, slot]

Clear the current value
.

Definition at line 75 of file cmcField.cpp.

bool contains ( const QString &  subString) [virtual, slot]

Tests for substring
.

Definition at line 122 of file cmcField.cpp.

cmcFieldDef * definition ( ) [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 240 of file cmcField.cpp.

void delVar ( QString  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 225 of file cmcField.cpp.

QString 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. Using 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 132 of file cmcField.cpp.

cmcForm * form ( ) [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.

Reimplemented in cmcFormField.

Definition at line 235 of file cmcField.cpp.

long index ( ) [virtual, slot]

Return the index number of this field
.

Reimplemented from cmcObject.

Definition at line 137 of file cmcField.cpp.

bool isBlank ( ) [virtual, slot]

Test for no data
.

Definition at line 90 of file cmcField.cpp.

bool isConnection ( ) [virtual, slot]

FALSE Connection Indicator
.

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

Definition at line 85 of file cmcField.cpp.

bool isDirty ( ) [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 262 of file cmcField.cpp.

bool isFalse ( ) [virtual, slot]

Boolean Conversion
.

Definition at line 159 of file cmcField.cpp.

bool isField ( ) [virtual, slot]

TRUE Field Indicator
.

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

Definition at line 80 of file cmcField.cpp.

bool isGuid ( ) [virtual, slot]

Test for GUID type of data
.

Definition at line 100 of file cmcField.cpp.

bool isNotBlank ( ) [virtual, slot]

Test for data
.

Definition at line 95 of file cmcField.cpp.

bool isNotGuid ( ) [virtual, slot]

Test for Not GUID type of data
.

Definition at line 112 of file cmcField.cpp.

bool isTrue ( ) [virtual, slot]

Boolean Conversion
.

Definition at line 154 of file cmcField.cpp.

virtual QString label ( ) [pure virtual, slot]

Return a QDomElement value
.

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

Return a QDomElement previousValue

Return a QDomElement ChangeLog value

This returns a xml formatted change log element

Field Label

Implemented in cmcFormField, cmcItemField, and cmcSubField.

long length ( ) [virtual, slot]

The length of the field
.

Definition at line 117 of file cmcField.cpp.

QString line ( long  lineNumber,
long  maxChar = -1 
) [virtual, slot]

Get First line of Memo
.

This is a handy function that returns the first line from a memo field. This function assumes there is a crLf imbedded in the field value somewhere, and if there is not, then the whole line is returned. An optional length can be specified to limit the number of characters returned, no matter what.

Parameters:
lineNumberlong ~ line index number (zero based)
maxCharlong ~ max characters (defaults to all)

Definition at line 194 of file cmcField.cpp.

QString name ( ) [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"

Reimplemented from cmcObject.

Definition at line 127 of file cmcField.cpp.

QString previousValue ( ) [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 267 of file cmcField.cpp.

void reset ( ) [virtual, slot]

Reset the field back to its 'untouched' state.
.

Definition at line 63 of file cmcField.cpp.

cmcSubField * subField ( QString  fieldName) [virtual, slot]

Sub Field
.

Definition at line 230 of file cmcField.cpp.

QDate toDate ( ) [virtual, slot]

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 179 of file cmcField.cpp.

QTime toTime ( ) [virtual, slot]

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 184 of file cmcField.cpp.

bool undo ( ) [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 250 of file cmcField.cpp.

QString unpackDateTime ( ) [virtual, slot]

Unpack a packed Date/Time
.

Definition at line 189 of file cmcField.cpp.

void value ( long  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 169 of file cmcField.cpp.

virtual QString value ( ) [pure 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

Implemented in cmcFormField, cmcItemField, and cmcSubField.

void value ( double  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 174 of file cmcField.cpp.

void value ( QDate  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 164 of file cmcField.cpp.

virtual void value ( bool  value) [pure virtual, slot]

Set Field Boolean Value
.

This function sets a boolean value. Boolean values must receive special treament since a Form.Field boolean field requires one set of boolean logic, and a RowSet.Field requires another. Therefore, this routine gets implemented in one of the subclasses.

Implemented in cmcFormField, cmcItemField, and cmcSubField.

virtual void value ( QString  value) [pure 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"

Implemented in cmcFormField, cmcItemField, and cmcSubField.

QString var ( QString  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 215 of file cmcField.cpp.

void var ( QString  fieldName,
QString  newValue 
) [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 220 of file cmcField.cpp.


Member Data Documentation

QPointer<cmcFieldDef> m_definition [protected]

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 551 of file cmcField.h.

bool m_gotPreviousValue [protected]

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 562 of file cmcField.h.

QString m_label [protected]

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 537 of file cmcField.h.


The documentation for this class was generated from the following files:
 All Classes Namespaces Functions Variables Enumerations Enumerator Properties




~ ~ ~ ~ ~ ~
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