DumontEXE 0.0.1
Public Slots | Public Member Functions | Private Attributes
cmcForm Class Reference

Form
. More...

#include <cmcForm.h>

Inheritance diagram for cmcForm:

List of all members.

Public Slots

bool abort ()
 Cause the form to abort
.
bool applyWorkgroupPermissions ()
 Apply Workgroup Permissions.
void backColor (long color)
 Set the current background color
.
long backColor ()
 Return the current background color
.
bool cancel ()
 Cause the form to cancel
.
void caption (QString caption)
 Set the form caption
.
QString caption ()
 Return the current form caption
.
cmcCategoryDefcategoryDef ()
 Return the forms category definition
.
QString categoryName ()
 Return the Category name of this Form
.
cmcFormFieldcfyField ()
 Return the clarifyField
.
void changeConnection (QString connName, QString toCategory, QString value)
 ChangeConnection Call-back slot
.
void changeField (QString fieldName, QString fieldValue)
 ChangeField Call-back slot
.
QString changeLog ()
 Retrieve the Change Log string from this form
.
QString clarifiedItemName ()
 Clarified Item Name.
cmcConnectioncon (QString conCatName)
 Get a Connection by its "FieldName"
.
cmcConnectionconnection (QString conName, QString catName)
 Get a Connection object by name
.
cmcConnectionconnection (QString conCatName)
 Get a Connection by its "FieldName"
.
cmcFormControl * control (QString controlName)
 Get a control from the form
.
bool deleteItem ()
 Delete the Item
.
cmcFormFieldfield (QString fieldName)
 Get a Field object by Name
.
cmcFormFieldfield (long index)
 Field by Index
.
QString fieldName ()
 Return the current field name
.
QString fieldValue ()
 Return the current field value
.
cmcFormFieldfld (QString fieldName)
 Field Alias
.
cmcRowSetgetChangeLogAddRowSet ()
 Get the Change Log category Definition
.
cmcFormFieldguidField ()
 Return the guid field
.
bool isAdd ()
 Return true/false if this form is in Add Mode
.
bool isConnection (QString fieldName)
 Check for Connection Name
.
bool isDelete ()
 Return true/false is the form is in Delete mode
.
bool isDirty ()
 Report if any field or connection on the form is dirty or not
.
bool isField (QString fieldName)
 Check for Field Name
.
bool isPrevNext ()
 Return true/false if the form is from a prev/next event
.
bool isShared ()
 Return true/false if this item is shared
.
QString itemClarify ()
 Return the Item Clarify text value
.
QString itemGuid ()
 Return the guid of this item
.
QString itemName ()
 Return the Item Name text value
.
QString itemThid ()
 Return the cmcID of this item
.
cmcFormFieldkeyField ()
 Return the keyField
.
cmcMeInfomeInfo ()
 Short-cut to MeInfo
.
void moveToField (QString fieldName)
 Move to the requested Field name
.
void moveToTab (QString tabName)
 Move to the requested Tab name
.
void multiDateDialogExec (const QString defaultDate="")
 Return a multi-date dialog
.
QString name ()
 Return the name of something
.
bool onActiveXControlEvent (QString controlID, QString eventName, QString parameterArray)
 Fire Form_OnActiveXControlEvent event
.
bool onCancel ()
 Fire Form_OnCancel event
.
bool onChange (QString controlID)
 Fire Form_OnChange() event
.
bool onClick (QString controlID)
 Fire Form_OnClick event
.
bool onEnterControl (QString controlID)
 Fire Form_OnEnterControl event
.
bool onEnterField (QString fieldName)
 Fire Form_OnEnterField event
.
bool onEnterTab (QString tabName)
 Fire Form_OnEnterTab event
.
bool onKeyPress (QString controlID, long keyAscii)
 Fire Form_OnKeyPress event
.
bool onLeaveControl (QString controlID)
 Fire Form_OnLeaveControl event
.
bool onLeaveField (QString fieldName)
 Fire Form_OnLeaveField event
.
bool onLeaveTab (QString tabName)
 Fire Form_OnLeaveTab event
.
bool onLoad ()
 Fire Form_OnLoad event
.
bool onSave ()
 Fire Form_OnSave event
.
void reopen ()
 Perform reload function
.
cmcRuntime * runtime ()
 Get the Form.Runtime object
.
bool save ()
 Cause the form to Save
.
void setDelete (bool state)
 Set the form Delete state.
void setDirty (bool state)
 Set Dirty State.
void setShared (bool state)
 Set the shared flag on the form
.
void setValue (QString value)
 Set the value of the currently selected field
.
QString tabName ()
 Return the current Tab name
.
cmcFormFieldthidField ()
 return the cmcID field

QString toXml (QString fieldList)
 Convert the form fields and connections and their values to an xml document
.
void undo ()
 Restore a form back to its original state
.
cmcFormFieldvarField ()
 Return the varField
.

Public Member Functions

cmcDateDialog * multiDateDialog (const QString defaultDate="")
 Return a new multi-date dialog
.
void prevNext ()
 Perform the prevNext functions
.
void resetFields ()
 Reset fields to their 'unknown' values
.

Private Attributes

QPointer< cmcActiveViewInfom_avi
 Active View Info
.
QPointer< cmcCategoryDefm_categoryDef
 categoryDef pointer cache

QString m_categoryName
 Form.CategoryName cache Value
.
QPointer< cmcDatabasem_db
 database pointer cache

QPointer< cmcMultiDateDialog > m_mdd
 multiDateDialog

QString m_name
 Form.Name cache Value
.
bool m_prevNext
 Remember if onSave or onCancel was called
.
bool m_reopen
 Flag to indicate that the form is to be reopened
.

Detailed Description

Form
.

This object wraps a regular Commence form.

Standard Commence Form Properties
Standard Commence Form Methods
Standard Commence Form Events
Enhanced Form Properties and Methods

Definition at line 110 of file cmcForm.h.


Member Function Documentation

bool abort ( ) [slot]

Cause the form to abort
.

This executes the abort operation on the form.

vbScript Example:

Definition at line 589 of file cmcForm.cpp.

bool applyWorkgroupPermissions ( ) [slot]

Apply Workgroup Permissions.

This procedure looks at the "Item Shared" attributes of the item and applys workgroup share permissions. The Workgroup Permissions are applied as follows:

Note:
This procedure does not deal with *delete* permissions. The reason is we simply don't allow deletions in our databases, due to a variety of reasons, mostly because of no un-delete functionality.
Public
Public Permissions represents a rule that *all* active users are applied to both read item permissions, and write item permissions. This essentially gives everyone total access to this item.
Protected
Protected Permissions means that *all* active users can read an item, but only the originator and select users or user groups can write to that same item. This makes the permissions somewhat granular. If individual users have been set, they will be applied to the write group. If a group has been set, all members of that group will be applied to the write permissions. The individual members list will take precedence over the group list.
Private
Private Permissions means that only the author of this item may read and write to it.
Group
I can't remember what I was thinking here.
None
This disables this engine on this item, and the user is allowed to apply his own permissions to the item.

Definition at line 455 of file cmcForm.cpp.

long backColor ( ) [slot]

Return the current background color
.

This returns the long-int value of the current form background color.

vbScript Example:

Definition at line 379 of file cmcForm.cpp.

void backColor ( long  color) [slot]

Set the current background color
.

This sets the background color of the for to the long-int value.

vbScript Example:

Definition at line 384 of file cmcForm.cpp.

bool cancel ( ) [slot]

Cause the form to cancel
.

This executes the Cancel operation on the form.

vbScript Example:

Definition at line 550 of file cmcForm.cpp.

QString caption ( ) [slot]

Return the current form caption
.

This Returns the current form Caption.

vbScript Example:

Definition at line 388 of file cmcForm.cpp.

void caption ( QString  caption) [slot]

Set the form caption
.

This sets the form Caption value.

vbScript Example:

Definition at line 393 of file cmcForm.cpp.

cmcCategoryDef * categoryDef ( ) [slot]

Return the forms category definition
.

Definition at line 649 of file cmcForm.cpp.

QString categoryName ( void  ) [slot]

Return the Category name of this Form
.

Return the category name that this form is associated with.

vbScript Example:
   dim cursor: set cursor = dfrm.DB.getCursor( 0, dfrm.categoryName, 0 )

Definition at line 134 of file cmcForm.cpp.

cmcFormField * cfyField ( ) [slot]

Return the clarifyField
.

vbScript Example
 Sub DoSomething()
   dim oCfy: set oCfy = dfrm.cfyField
   oCfy.Value = "this is a test"      ' set the clarify field to "this is a test"
 End Sub

Definition at line 205 of file cmcForm.cpp.

void changeConnection ( QString  connName,
QString  toCategory,
QString  value 
) [slot]

ChangeConnection Call-back slot
.

This is a change-connection call-back slot. This method gets called anytime a connection content changes and the cursor focus is moved to the next field or connection. This method requires that the Form Animation functions be called during form execution.

Definition at line 1216 of file cmcForm.cpp.

void changeField ( QString  fieldName,
QString  fieldValue 
) [slot]

ChangeField Call-back slot
.

This is a change-field call-back slot. This method gets called anytime a field content changes and the cursor focus is moved to the next field. This method requires that the Form Animation functions be called during form execution.

Definition at line 1209 of file cmcForm.cpp.

QString changeLog ( ) [slot]

Retrieve the Change Log string from this form
.

vbScript Example:
See also:
Change Log Engine

Definition at line 946 of file cmcForm.cpp.

QString clarifiedItemName ( ) [slot]

Clarified Item Name.

This returns the item name with the clarify field value included in the case that this item

Definition at line 165 of file cmcForm.cpp.

cmcConnection * con ( QString  conCatName) [slot]

Get a Connection by its "FieldName"
.

This is an alias function for obtaining a regular Connection field. It is intended to make the code a little more readable.

vbScript Example
 Sub Form_OnEnterField(ByRef FieldName)
   dim oxEmployee: set oxEmployee = dfrm.con("pRD Employee")
 End Sub

Definition at line 907 of file cmcForm.cpp.

cmcConnection * connection ( QString  conName,
QString  catName 
) [slot]

Get a Connection object by name
.

This returns a Connection object from the Form. Optionally, a "FieldName" value can be provided which gives this connection a 'default' field property.

Note:
This object does *not* fail if an improper connection name is provided. Rather, it returns an object that is missing its connection-object pointer. The object that gets returned can be tested for validity using the isValid() function call.
vbScript Example:
 Sub ConnectStaff()

   dim ocStaff: set ocStaff = dfrm.connection("Relates to","Staff")
   if( ocStaff.isValid ) then
     ocStaff.SetConnection("Jim","Accounting")
     ocStaff.SetConnection("Tony","Owner")
   end if

   dim ocFail: set ocFail = dfrm.connection("this will","fail")
   if( ocFail.isValid ) then
     ocFail.SetConnection("ok, now","I'm suprised")
     ocFail.SetConnection("this shouldn't","get here!")
   end if

 End Sub

Definition at line 779 of file cmcForm.cpp.

cmcConnection * connection ( QString  conCatName) [slot]

Get a Connection by its "FieldName"
.

This is an overloaded function to return a cmcConnection when all we have is the "FieldName" as it is provided by the vbScript Form_onEnterField(FieldName) function call. Normally when dealing with Form Events, all that is provided is a FieldName value which can represent a connection field or a standard text field. The application (code) has to try to determine which one it is. Dumont has the built-in services to make this an easy task. It is possible to pass that simple FieldName value to the connection method and receive a cmcConnection connection object.

What this function also makes available is the ability to set field and connection names using the vbScript 'Const' keyword. Both field names and connection names can be declared this way and then used to reference the connection by name. This can have the advantage of really cleaning up a bunch of code redundancies.

vbScript Example:
 '
 ' These declarations were formerly not possible because the .connection.
 '  object required two parameters.
 '
 Const FN_KEY      = "contactsKey"
 Const FN_CFY      = "contactsCfy"
 Const FN_FIRST    = "First Name"
 Const FN_LAST     = "Last Name"
 Const FN_PHONE    = "Main Phone"
 Const CN_EMPLOYER = "Employed by Company"
 Const FN_EMPLKEY  = "companyKey"
 Const FN_BUSPHONE = "Business Phone"

 Sub Form_OnEnterField(ByRef FieldName)
   '
   ' Do the Dumont OnEnterField stuff
   '
   dfrm.onEnterField FieldName

   '
   ' If this is a connection object then deal with it
   '
   if( dfrm.isConnection(FieldName) ) then
     dim conn: set conn = dfrm.connection(FieldName)
     msgbox "You have " & conn.ConnectedItemCount & " connected items"

     '
     ' Use the Const values to access the controls
     '
     dfrm.field(FN_KEY).value = _
       dfrm.field(FN_LAST)   & ", "   & _
       dfrm.field(FN_FIRST)  & " of " & _
       dfrm.connection(CN_EMPLOYER).fieldValue(FN_EMPLKEY) ' note: connection referred by NAME

     dfrm.field(FN_PHONE).value = _
       dfrm.connection(CN_EMPLOYER).fieldValue(FN_BUSPHONE) ' note: connection referred by NAME

   end if
 End Sub
See also:
ConnectionDefs, Connection, isConnection, isField

Definition at line 861 of file cmcForm.cpp.

cmcFormControl * control ( QString  controlName) [slot]

Get a control from the form
.

vbScript Example:

Definition at line 927 of file cmcForm.cpp.

bool deleteItem ( ) [slot]

Delete the Item
.

This function executes a specially tailored delete type of method on this item. This is not just a regular item delete like what you get when you hit ctrl-D on a form or a view. This deletion function is designed to provide tracability and recoverability (as in 'undelete') on deleted items.

In order for this method to work properly several things have to be available to Dumont. First, the item has to have a varField where deletion info can be stored. The type of info that gets stored there is as follows:

 deletedOn=20071114074022           ' date and time of the deletion
 deletedBy=MWP:80011002:00223233    ' who requested the deletion

When an item is stamped in this fashion it can be easily filtered from various views by adding a "varField Does Not Contain deletedOn" type of filter. This gives the operator the illusion that the item has actually been deleted from his computer. The downside of this implementation is that it requires an extra filter be added to all your views and connections in order for them to appear proper to the user. Also, this requires that the user has write permissions on this particular item.

But, even if the user does not have write permissions over this particular item, in parallel with stamping the item with deletion info, a changeLog item is also generated for the deletion request. Note, I say request because once the server gets a hold of it, the server may decide this item shouldn't be deleted afterall - that implementation is left up to the system integrator (that's the *you* part of this relationship).

If the user does not have write permissions on the item, then no deletion stamping will be performed on it, and the item will remain in his views. However, a changeLog item will still be created and saved, and when the server picks up the changeLog deletion request and decides to delete the item anyway then eventually when the user syncs with the workgroup the item will disappear. This actually allows users to delete items they don't have write permissions on, and there is a trace-log of the deletion! Nice, eh?

Here is an actual example of a change log that was generated on an item deletion request.

example changeLog item:
 <!DOCTYPE changeLog>
 <changeLog version="3.8.98.3" formName="Docket General" action="Delete" categoryName="Calendar" >
    <itemName>Petryk.M/lit2</itemName>
    <logOn>20071114112236</logOn>
    <logBy>MWP:7:80006401:000026F7</logBy>
    <cmcID>nothing</cmcID>
    <guid>{55028c01-4b13-4718-9681-c8b832d55360}</guid>
    <field name="calendarVar" >
       <from>cmcID=nothing&#xd;
 guid={55028c01-4b13-4718-9681-c8b832d55360}&#xd;
 createdOn=20071114112228&#xd;
 createdBy=MWP:7:80006401:000026F7&#xd;
 changedOn=20071114112228&#xd;
 changedBy=MWP:7:80006401:000026F7&#xd;
 dragFrom=20071118080000&#xd;
 mdd=0001200711180020110000</from>
       <to>cmcID=nothing&#xd;
 guid={55028c01-4b13-4718-9681-c8b832d55360}&#xd;
 createdOn=20071114112228&#xd;
 createdBy=MWP:7:80006401:000026F7&#xd;
 changedOn=20071114112228&#xd;
 changedBy=MWP:7:80006401:000026F7&#xd;
 dragFrom=20071118080000&#xd;
 mdd=0001200711180020110000&#xd;
 deletedOn=20071114112236&#xd;
 deletedBy=MWP:7:80006401:000026F7</to>
    </field>
 </changeLog>

There is enough information in this change log item to be able to locate the originating source item and user that made the request for deletion.

None-the-less, varField or not, this function is designed to tag the item appropriately so that it may be deleted responsibly, by the server, or some other authorized administrator. And, if you set the server up properly then you can archive your items off in some sort of a historical storage for later retrieval if the users desire.

The second thing that is required for this 'service' to function properly is the guid() method within Dumont. This method must be functioning properly so that a unique guid for this item can be generated and made available to the rest of the system. Yes, I know its possible to build a system that does not require guid's, and you should be able to use this item deletion feature without them, but, frankly, the pitfalls of implementing such a system are great. For instance, say your category does not allow duplicates, but certainly allows changes. Now, someone wants an item deleted, and you are using the 'Name' field to track the item (since it's unique, right?). You delete the item, a log is created on the 'Name' field, and you're done. Meanwhile, on or about the same time, someone else changes the 'Name' value of this item. Their 'sync' packet makes it to the server first so it goes ahead and changes the item name. Then your packet comes in and requests the item be deleted, but it does it by 'Name' value, right? See the problem? The server can't delete the item or archive it or anything because it can't find it because the name has changed! Bottom line? Use the guid() feature of the Dumont project. It's easy and it will make your life happy, and you'll be rewarded with a new house and a nice car a wonderful spouse and a dog that actually listens to you. I have all these things and it's because I started using guid's on all my Commence items... really, really!

Keep in mind that all that is happening here is the item is being *tagged* for deletion. The actual item deletion occurs on the server where the entire process can be controlled.

Definition at line 445 of file cmcForm.cpp.

cmcFormField * field ( QString  fieldName) [slot]

Get a Field object by Name
.

Note:
This object does *not* fail if an improper field name is provided. Rather, it returns an object that is missing its field-object pointer. The object that gets returned can be tested for validity using the isValid() function call.
vbScript Example ~ Fetching a field by name
 sub FixFieldInfo()
   dim oFName: set oFName = dfrm.field("First Name")
   dim oLName: set oLName = dfrm.field("Last Name")
   dim oBName: set oBName = dfrm.field("Bad Field Name")

   if( oFName is nothing ) then msgbox "First Name is: " & oFName.value else msgbox "Bad Field Name"
   if( oLName is nothing ) then msgbox "Last Name is: "  & oLName.value else msgbox "Bad Field Name"
   if( oBName is nothing ) then msgbox "Bad Name is: "   & oFName.value else msgbox "Bad Field Name"
 end sub
Returns:
Field object from the form collection

Todo:
Log Field Access Errors

Definition at line 657 of file cmcForm.cpp.

cmcFormField * field ( long  index) [slot]

Field by Index
.

Definition at line 769 of file cmcForm.cpp.

QString fieldName ( void  ) [slot]

Return the current field name
.

Return the currently selected field name.

vbScript Example:
 Sub doInfoPage()
   select case dfrm.FieldName
     case "Customer No":  PrintDetails
     case "Ref ID":       AcquireInvoices
     case "Shipping":     ChargeOff
     case "Past Due":     Alert("This Customer Is Past Due")
   end select
 End Sub

Definition at line 195 of file cmcForm.cpp.

QString fieldValue ( ) [slot]

Return the current field value
.

This pass-through function returns the value of the currently selected field.

vbScript Example:

Definition at line 369 of file cmcForm.cpp.

cmcFormField * fld ( QString  fieldName) [slot]

Field Alias
.

Definition at line 763 of file cmcForm.cpp.

cmcRowSet * getChangeLogAddRowSet ( ) [slot]

Get the Change Log category Definition
.

This is an internal function that will seek-out the change log category definition and verify it for compatibility. If the category definition looks good then a pointer to it is returned. If it does not look good then a message window is opened with a few details of the problem.

Definition at line 1234 of file cmcForm.cpp.

cmcFormField * guidField ( ) [slot]

Return the guid field
.

The guid field is a special field defined in the category that can be used to store a guid of this item. It should be a text(40) field. It can be indexed and/or used as a clarify field to aid in the identification of items by ID. If this field exists in the category definition then the guid will *not* be stored in the varField() if it also exists.

See also:
guid, thidField, varField

Definition at line 215 of file cmcForm.cpp.

bool isAdd ( ) [slot]

Return true/false if this form is in Add Mode
.

This pass-through function returns true/false if the form is in add mode.

vbScript Example:

Definition at line 349 of file cmcForm.cpp.

bool isConnection ( QString  fieldName) [slot]

Check for Connection Name
.

This returns TRUE when the FieldName provided is a connection field. This helps to identify an object as a connection when all we have is a field name as provided by the vbScript Form_onEnterField(FieldName) function.

vbScript Example:
 Sub Form_OnEnterField(ByVal FieldName)
   If( dfrm.isField(FieldName) ) then
     msgbox FieldName + " is a field"
   End If
   If( dfrm.isConnection(FieldName) ) then
     msgbox FieldName + " is a Connection"
   End If
 End Sub
See also:
isField

Definition at line 917 of file cmcForm.cpp.

bool isDelete ( ) [slot]

Return true/false is the form is in Delete mode
.

This function returns the delete flag on the form. The delete flag gets set when the deleteItem() function is called.

Definition at line 354 of file cmcForm.cpp.

bool isDirty ( ) [slot]

Report if any field or connection on the form is dirty or not
.

This function loops through all the fields and connections on the form and reports true if any of them have been changed from their original values.

vbScript Example:
 if( dfrm.isDirty ) then
   msgbox "the following changes are: " & dfrm.changeLog
 end if

Definition at line 635 of file cmcForm.cpp.

bool isField ( QString  fieldName) [slot]

Check for Field Name
.

This takes a field name as a parameter and returns 'true' if the field name equates to an actual field in the category. If the field name provided is a connection name, or is not listed then this function returns false.

vbScript Example:
 Sub Form_OnEnterField(ByVal FieldName)
   If( dfrm.isField(FieldName) ) then
     msgbox FieldName + " is a field"
   End If
   If( dfrm.isConnection(FieldName) ) then
     msgbox FieldName + " is a Connection"
   End If
 End Sub
See also:
isConnection

Definition at line 922 of file cmcForm.cpp.

bool isPrevNext ( ) [slot]

Return true/false if the form is from a prev/next event
.

This handy function returns true or false if the form is from a previous/next button event.

Definition at line 364 of file cmcForm.cpp.

bool isShared ( void  ) [slot]

Return true/false if this item is shared
.

This pass-through function returns true/false if the form item is currently shared.

vbScript Example:

Definition at line 374 of file cmcForm.cpp.

QString itemClarify ( ) [slot]

Return the Item Clarify text value
.

Definition at line 180 of file cmcForm.cpp.

QString itemGuid ( ) [slot]

Return the guid of this item
.

This function returns the currently assigned guid of this item, or a new guid for this item if one does not exist yet.

In order for this function to work properly, there must be a varField() defined for this category or a special guid field. If there is no varField() then this function returns the string value of "nothing".

If the varField() exists but no guid has been assigned, then this function will create a new guid value and cause it to be automatically stored in the varField(). The advantage of using this guid function over the itemThid() function is that this value can be generated immediately for new items before they are saved to the category, wheras the itemThid() value is only available after the item has been saved. Once a guid is generated for an item, because it is stored in the varField() it will remain static and unique for that particular item for the life of that item.

Alternatively, if you do not want to have the guid stored in a varField() type of field, you can define a field "guid Text(40)" (a 40-character text field called "catNameGuid") in the category and then the guid will be automatically stored there. This can have the advantage of using the guid field as the clarify field and creating an index for it and so on. The disadvantage of using a guid field as a clarify field is the guid field then shows up in the Tools|Global Search results and also shows up in some other places... and that may be undesirable.

Note:
One pecularity with this method of item identification is that it is all hapening 'outside' of the Commence database engine as a post-process. This means these methods are not without their pitfalls. One comes from the menu item "Edit | Copy Item". This menu option causes a new commence item to be created from an existing one, meaning all the contents of the var field are copied as well. This is potentially problemmatic because some of this 'item management' code depends on 'initial values' in this var field and other fields. Extra steps have been taken to insure that the itemThid() and itemGuid() values are unique per item, but care should be taken by the database administrator to insure that things are working as expected. Especially when the var field is used to store other values outside the scope of the DumontDLL.
vbScript Example:
 msgbox dfrm.guid ' shows '{623316da-e9cc-4f42-a9fb-f2938920dcb5}'
See also:
itemThid

Definition at line 310 of file cmcForm.cpp.

QString itemName ( void  ) [slot]

Return the Item Name text value
.

String, name of the current item. May be empty when adding an item and the name field has not yet been entered.

vbScript Example:
   if( dfrm.ItemName = "Accounting Department" ) then
     msgbox "I was told there would be no math!"
   end if

Definition at line 157 of file cmcForm.cpp.

QString itemThid ( ) [slot]

Return the cmcID of this item
.

This function returns the currently assigned itemThid (THID) of this item. Please note that this function ONLY works when this category contains an actual varField field where the THID can be stored .AND. this form is .NOT. in "isAdd == True" mode. Both of those conditions must be true to get at the THID value for this item. If not, then "unknown" is returned instead.

Alternatively, if you do not want to have the THID stored in a varField() type of field, you can define a field "thid Text(20)" (a 20-character text field called "cmcID") in the category and then the THID will be automatically stored there. This can have the advantage of using the cmcID field as the clarify field and creating an index for it and so on. The disadvantage of using a cmcID field as a clarify field is the cmcID field then shows up in the Tools|Global Search results and also shows up in some other places... and that may be undesirable.

One thing to note about the cmcID value is that not only is it not available until a new item has been saved to disk, but the cmcID value is actually not portable across multiple databases. For instance, if an item is moved from one database to another, then even though, technically the cmcID is likely to still be unique, it does not necessarily represent the correct actual cmcID value of that item - simply because it was exported from one database and imported into another. For this reason, and probably others that haven't been completely realized yet, the cmcID valus is of marginal value, and probably should not be relied on in a production database. Instead, the guid() value should be used when trying to uniquely identify items in Commence.

vbScript Example:
 msgbox dfrm.itemThid ' shows '4:80006401:0000365E'
See also:
guid

Definition at line 258 of file cmcForm.cpp.

cmcFormField * keyField ( ) [slot]

Return the keyField
.

Every category has a key field. This is the same as the 'Name' field. This method provides direct access to this name field.

Note:
This FieldName value defaults to 'catnameKey' - see the definition in the source code for clarification.
vbScript Example
 Sub DoSomething()
   dim oKey: set oKey = dfrm.keyField
   oKey.Value = "this is a test"      ' set the name field to "this is a test"
 End Sub

Definition at line 200 of file cmcForm.cpp.

cmcMeInfo * meInfo ( ) [slot]

Short-cut to MeInfo
.

This is a convenience function for acquiring a pointer to the cmcMeInfo MeInfo object. It simply performs a db()-> meInfo() call.

Definition at line 1229 of file cmcForm.cpp.

void moveToField ( QString  fieldName) [slot]

Move to the requested Field name
.

This moves to a specific field within the form. This passes control to the Commence moveToField form method, but it then also includes an additional reference to the new field value so that the Dumont change-logging engine can function properly. Note that if you have implemented your own change log code on your forms in vbScript, you will not receive an Form_onEnter or Form_onLeave field event if you use a Form.MoveToField call in your code. If your vbScript code does not properly detect this field change condition it probably will not log the field changes properly.

vbScript Example:
 Sub Form_OnClick( ByVal ControlID )
   if( ControlID = "CommandButton1" )
     dfrm.moveToField "Account Number" ' change-log engine handled properly!
   end if
 End Sub

One simple solution to implementing a proper change-log function in vbScript, if that code is dependent on the onEnterField and onLeaveField events, is you can wrap the Form.moveToField function in another function as follows:

Wrapping change-log moveToField functions:
 Sub Move2Field( ByRef FieldName )
   Form.MoveToField FieldName
   Form_OnEnterField FieldName
 End Sub

Note that wrapping the moveToField function as shown above is not necessary with Dumont since Dumont makes the same (internal) call to its onEnterField function.

Definition at line 631 of file cmcForm.cpp.

void moveToTab ( QString  tabName) [slot]

Move to the requested Tab name
.

This changes the form's currently selected Tab

vbScript Example:

Definition at line 627 of file cmcForm.cpp.

cmcDateDialog * multiDateDialog ( const QString  defaultDate = "")

Return a new multi-date dialog
.

This method returns a pointer to the form's multi-date dialog. If a multidate dialog has not been manufactured then one is created for return. If one has already been created then that same pointer is returned. This way only one multidate dialog object gets created per form.

Note:
vbScript should not call this function at this point because there seems to be some sort of interface probem when opening this dialog directly from vb. Instead vbScript should call multiDateDialogExec which will both create a new dialog if need be and exec() that dialog properly. Therefore, this method is published in the 'public' section of the Form but not in the 'public slots' section.

Definition at line 143 of file cmcForm.cpp.

void multiDateDialogExec ( const QString  defaultDate = "") [slot]

Return a multi-date dialog
.

Ideally this function should actually return the multi-date dialog itself so that the vbScript programmer can use it himself, but that's not working out so good at the moment. There is still some DumontDLL code required to be able to open a true modal-dialog from a vbScript request.

For the moment what this function does is perform the multiDateDialog stuff on the form directly - which works out anyhow.

vbScript Example:

Definition at line 942 of file cmcForm.cpp.

QString name ( ) [slot]

Return the name of something
.

This will return the name of this form as assigned in the Commence form designer.

vbScript Example:
   msgbox dfrm.name     ' shows "Initial Form" if the name hasn't been changed.

Reimplemented from cmcObject.

Definition at line 126 of file cmcForm.cpp.

bool onActiveXControlEvent ( QString  controlID,
QString  eventName,
QString  parameterArray 
) [slot]

Fire Form_OnActiveXControlEvent event
.

vbScript Example:
 Sub Form_OnActiveXControlEvnet(ByRef ControlID, ByRef EventName, ByRef ParameterArray)
   dfrm.onActiveXControlEvent ControlID, EventName, ParameterArray
 End Sub

Definition at line 1189 of file cmcForm.cpp.

bool onCancel ( ) [slot]

Fire Form_OnCancel event
.

vbScript Example:
 Sub Form_OnCancel()
   dfrm.onCancel
 End Sub

Definition at line 1154 of file cmcForm.cpp.

bool onChange ( QString  controlID) [slot]

Fire Form_OnChange() event
.

The Form_OnChange() event gets fired any time a control is changed, usually in response to the user typing some text in a control field.

vbScript Example:
 Sub Form_OnChange(ByRef ControlID)
   dfrm.onChange ControlID
 End Sub

Definition at line 1199 of file cmcForm.cpp.

bool onClick ( QString  controlID) [slot]

Fire Form_OnClick event
.

vbScript Example:
 Sub Form_OnClick(ByRef ControlID)
   dfrm.onClick ControlID
 End Sub

Definition at line 1194 of file cmcForm.cpp.

bool onEnterControl ( QString  controlID) [slot]

Fire Form_OnEnterControl event
.

vbScript Example:
 Sub Form_OnEnterControl(ByVal ControlID)
   dfrm.onEnterControl ControlID
 End Sub

Definition at line 1179 of file cmcForm.cpp.

bool onEnterField ( QString  fieldName) [slot]

Fire Form_OnEnterField event
.

vbScript Example:
 Sub Form_OnEnterField(ByVal FieldName)
   dfrm.onEnterField FieldName
 End Sub

Definition at line 1169 of file cmcForm.cpp.

bool onEnterTab ( QString  tabName) [slot]

Fire Form_OnEnterTab event
.

vbScript Example:
 Sub Form_OnEnterTab(ByVal FieldName)
   dfrm.onEnterTab FieldName
 End Sub

Definition at line 1159 of file cmcForm.cpp.

bool onKeyPress ( QString  controlID,
long  keyAscii 
) [slot]

Fire Form_OnKeyPress event
.

Anytime any key is pressed in any Field or Control this event gets fired. This event does not get fired for Connection fields.

vbScript Example:
 Sub Form_OnKeyPress(ByRef ControlID, KeyAscii)
   dfrm.onKeyPress ControlID, KeyAscii
 End Sub

Definition at line 1204 of file cmcForm.cpp.

bool onLeaveControl ( QString  controlID) [slot]

Fire Form_OnLeaveControl event
.

 Sub Form_OnLeaveControl(ByVal ControlID)
   dfrm.onLeaveControl ControlID
 End Sub

Definition at line 1184 of file cmcForm.cpp.

bool onLeaveField ( QString  fieldName) [slot]

Fire Form_OnLeaveField event
.

vbScript Example:
 Sub Form_OnLeaveField(ByVal FieldName)
   dfrm.onLeaveField FieldName
 End Sub

Definition at line 1174 of file cmcForm.cpp.

bool onLeaveTab ( QString  tabName) [slot]

Fire Form_OnLeaveTab event
.

vbScript Example:
 Sub Form_OnLeaveTab(ByVal FieldName)
   dfrm.onLeaveTab FieldName
 End Sub

Definition at line 1164 of file cmcForm.cpp.

bool onLoad ( ) [slot]

Fire Form_OnLoad event
.

vbScript Example:
 Sub Form_OnLoad()
   dfrm.onLoad
 End Sub

Definition at line 951 of file cmcForm.cpp.

bool onSave ( ) [slot]

Fire Form_OnSave event
.

The DumontDLL onSave event includes a few procedures for automatically stamping items with change-log information and assigning guid's and THID's and whatnot. You should review the source to see what's going on here.

 Sub Form_OnSave()
   dfrm.onSave
 End Sub

Definition at line 956 of file cmcForm.cpp.

void prevNext ( )

Perform the prevNext functions
.

This internal function takes care of all the things that need to be taken care of if the prevNext buttons are used. For starters, it clears the fields of all their values. If the form is actually being closed, then clearing the fields is somewhat redundant. But, since we don't know if the form is actually being closed or if one of the prevNext keys was used we have to clear all the field values so that they pick up the proper values for the new item.

Then, this routine takes care of 'handling' the prevNext keys. There are quite a few manuvers that have to be taken to properly handle the prevNext keys, especially when multiple form types are in use. When multiple forms are in use then the current form really needs to be closed and a new one opened, on the same item. This is an exceptionally difficult thing to do.

Definition at line 153 of file cmcForm.cpp.

void reopen ( ) [slot]

Perform reload function
.

This method performs the automatic-form-reload function. It checks to see if the flag is set and if so applys a secretAgent to cause the form to be reloaded.

Definition at line 1224 of file cmcForm.cpp.

void resetFields ( )

Reset fields to their 'unknown' values
.

This loops through all the fields and connections on the form and resets their values so that it appears as if the form was just loaded. This is used in conjunction with the prev/next functionality so that if the form is moved to another item, the fields and connections can accurately reflect their contents.

Definition at line 149 of file cmcForm.cpp.

cmcRuntime * runtime ( ) [slot]

Get the Form.Runtime object
.

vbScript Example:

Definition at line 932 of file cmcForm.cpp.

bool save ( ) [slot]

Cause the form to Save
.

This executes the Save operation on the form.

vbScript Example:

Definition at line 512 of file cmcForm.cpp.

void setDelete ( bool  state) [slot]

Set the form Delete state.

Definition at line 359 of file cmcForm.cpp.

void setDirty ( bool  state) [slot]

Set Dirty State.

This sets or resets the form dirty state.

Definition at line 640 of file cmcForm.cpp.

void setShared ( bool  state) [slot]

Set the shared flag on the form
.

This sets and resets the form/item Shared value

vbScript Example
 Sub MakeItemShared()
   dfrm.setShared True
 End Sub

 Sub MakeItemUnshared()
   dfrm.setShared False
 End Sub

Definition at line 398 of file cmcForm.cpp.

void setValue ( QString  value) [slot]

Set the value of the currently selected field
.

This sets the value of the currently selected field. This, of course, assumes that the currently selected control is a Field controls and not a connection control.

vbScript Example:

Definition at line 441 of file cmcForm.cpp.

QString tabName ( ) [slot]

Return the current Tab name
.

Return the current Tab name.

vbScript Example:
 Sub HandlePage
   select case dfrm.TabName
     case "Main": doMainPage
     case "Info": doInfoPage
     case "Tank": doTankPage
   end select
 End Sub

Definition at line 190 of file cmcForm.cpp.

cmcFormField * thidField ( ) [slot]

return the cmcID field

The cmcID field is a special field defined in the category that can be used to store the cmcID of this item. It should be a text(20) field. It can be indexed and/or used as a clarify field to aid in the identification of items by ID. If this field exists in the category definition then the cmcID will *not* be stored in the varField() if it also exists.

See also:
cmcID, guidField, varField

Definition at line 220 of file cmcForm.cpp.

QString toXml ( QString  fieldList) [slot]

Convert the form fields and connections and their values to an xml document
.

This is a routine that will produce a very long string which is an xml-compliant representation of the form field and connection values. The xml output is, in essence, an export of this category item.

vbScript Example
 Sub Form_OnClick(ByVal ControlID)
   if( ControlID = "CommandButton1" ) then
     msgbox dfrm.toXml("*")
   end if
 End Sub
Sample Output
 <!DOCTYPE QCommenceForm>
 <item formName="Dumont" categoryName="Dumont" itemName="test" itemClarify="" >
    <field0 name="Name" >test</field0>
    <field1 name="Build" >5</field1>
    <field2 name="Data" ></field2>
    <field3 name="Description" ></field3>
    <field4 name="dumontVar" >guid={9027b2d3-4f52-4842-99f5-bc3499e9fd33}
 this is a test
 this is multi-line text.</field4>
    <field5 name="Parameters" ></field5>
    <field6 name="Result" ></field6>
    <field7 name="Run from Disk" >0</field7>
    <field8 name="Script" ></field8>
    <connection1 name="pRD->Employee" >
       <item1>
          <key>Ben</key>
          <clarify></clarify>
       </item1>
       <item2>
          <key>Claudia</key>
          <clarify></clarify>
       </item2>
       <item3>
          <key>Mark</key>
          <clarify></clarify>
       </item3>
       <item4>
          <key>Bryon</key>
          <clarify></clarify>
       </item4>
    </connection1>
    <connection2 name="pWR->Employee" >
       <item1>
          <key>Mark</key>
          <clarify></clarify>
       </item1>
    </connection2>
 </item>

Todo:
finish for( int i=0; i<categoryDef()-> fieldDefs()-> count()-1; i++ ) { cmcFieldDef * fieldDef = categoryDef()-> fieldDefs()-> get(i); field(fieldDef-> name())-> deValue( doc, root ); }

for( int i=0; i<categoryDef()-> connectionDefs()-> count(); i++ ) { cmcConnectionDef * connectionDef = categoryDef()-> connectionDefs()-> get(i); cmcConnection * conn = connection(connectionDef-> name());

conn-> domElement( doc, root ); }

Definition at line 225 of file cmcForm.cpp.

void undo ( ) [slot]

Restore a form back to its original state
.

This performs an 'undo' on all Fields and Connections. It loops through each field and each connection and calls their respective undo().

vbScript Example:

Definition at line 645 of file cmcForm.cpp.

cmcFormField * varField ( ) [slot]

Return the varField
.

The varField is a memo field that is designated as part of the 100-field-limit extension project. Typically the var field name is comprised from the category Name plus "Var". For instance, examples include; calendarVar, personVar, projectVar, matterVar... and so on.

vbScript Example
 Sub DoSomething()
   dim oVar: set oVar = dfrm.varField
   oVar.var("cmcID") = "12345"      ' set the cmcID element in var to "12345"
   oVar.var("dateOn") = now
 End Sub

Definition at line 210 of file cmcForm.cpp.


Member Data Documentation

QPointer<cmcActiveViewInfo> m_avi [private]

Active View Info
.

Reimplemented from cmcObject.

Definition at line 1563 of file cmcForm.h.

QPointer<cmcCategoryDef> m_categoryDef [private]

categoryDef pointer cache

Definition at line 1585 of file cmcForm.h.

QString m_categoryName [private]

Form.CategoryName cache Value
.

Definition at line 1551 of file cmcForm.h.

QPointer<cmcDatabase> m_db [private]

database pointer cache

Definition at line 1579 of file cmcForm.h.

QPointer<cmcMultiDateDialog> m_mdd [private]

multiDateDialog

Definition at line 1573 of file cmcForm.h.

QString m_name [private]

Form.Name cache Value
.

Definition at line 1545 of file cmcForm.h.

bool m_prevNext [private]

Remember if onSave or onCancel was called
.

Definition at line 1591 of file cmcForm.h.

bool m_reopen [private]

Flag to indicate that the form is to be reopened
.

Definition at line 1559 of file cmcForm.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