DumontEXE 0.0.1
Public Slots | Signals | Protected Member Functions | Private Attributes
cmcConnection Class Reference

Connection. More...

#include <cmcConnection.h>

Inheritance diagram for cmcConnection:

List of all members.

Public Slots

QString changeLog ()
 Get the Connection Change Log
.
long cic ()
 Connected Item Count
.
void clear ()
 Clear Items by Filter
.
void clearAll ()
 Clear Items regardless of filter
.
void clearConnection (const QString &itemName, const QString &itemClarify="")
 Clear Connection based on Name/Clarify
.
QString conName ()
 Connection Name
.
long connectedItemCount ()
 Connected Item Count
.
long currentSelection ()
 Get the Current Selection
.
void currentSelection (long selection)
 Set the Current Selection
.
void defaultField (const QString &fieldName)
 Set the Default Field
.
QString defaultField ()
 Return the Default Field
.
virtual cmcConnectionDefdefinition ()
 Get the Field Definition String
.
QString fieldName ()
 Connection Field name
.
QString fieldName (long index)
 Return a field name by Index
.
QString fieldNames ()
 Return a list of connection field names
.
QString fieldValue (const QString &fieldName)
 Return a FieldValue
.
QString fieldValue (const QString &itemName, const QString &fieldName)
 Return a Field Value of a particular item
.
QString fieldValue (const QString &compareField, const QString &compareValue, const QString &fieldName)
 Return a Field Value of a particular item by a different field
.
QString filterKeyword (const QString &keyword)
 Return one of the filter keywords
.
virtual long index ()
 Return the index number of this field
.
bool isConnection ()
 TRUE Connection Indicator
.
bool isDirty ()
 Return TRUE/FALSE if the connection is dirty
.
bool isField ()
 FALSE Field Indicator
.
QString itemClarifyField ()
 Get Item Clarify value
.
QString itemName ()
 Get Item Name value
.
QString name ()
 Return the 'Name' of the connection
.
virtual bool onChange ()
 Execute on-change function
.
virtual bool onEnter ()
 Execute on-enter functions
.
virtual bool onLeave ()
 Execute on-leave functions
.
virtual QString previousValue ()
 Return the previousValue
.
void reset ()
 Reset the connection back to its 'untouched' state
.
void setConnection (const QString &itemName, const QString &itemClarify="")
 Set a Connection based on Name/Clarify
.
void setFilterKeyword (const QString &keyword, const QString &text, long flags)
 Set the Filter Keyword
.
long uic ()
 Unconnected Item Count
.
long unconnectedItemCount ()
 Return the Unconnected Item Count
.
void undo ()
 Restore to the Previous Operation
.
QString value (long index, long column)
 Get a single row value for a specific column
.
QString value (long index)
 Get a single row value for column(0)
.
QString value ()
 Get ALL column(0) values
.
QString varValue (const QString &fieldName, const QString &varName)
 Return index number of a particular field
.

Signals

void change (const QString &connection, const QString &category, const QString &value)
 Change the Field signal
.
void enter (const QString &connection, const QString &category, const QString &value)
 Enter the Field signal
.
void leave (const QString &connection, const QString &category, const QString &value)
 Leave the Field signal
.

Protected Member Functions

cmcFormform ()
 Return the parent Form object
.

Private Attributes

QString m_conName
 Connection Name cache
.
QString m_defaultField
 Default Field cache
.
QString m_enterValue
 Enter Field value cache
.
QStringList m_fieldList
 Field List cache
.
bool m_gotPreviousValue
 Got Previous Value flag
.
QString m_previousValue
 Previous Value cache
.
QString m_toCategory
 To Category Name cache
.

Detailed Description

Connection.

Definition at line 42 of file cmcConnection.h.


Member Function Documentation

void change ( const QString &  connection,
const QString &  category,
const QString &  value 
) [signal]

Change the Field signal
.

QString changeLog ( ) [slot]

Get the Connection Change Log
.

See also:
Change Log Engine

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

Definition at line 627 of file cmcConnection.cpp.

long cic ( ) [slot]

Connected Item Count
.

This is an alias for the connectedItemCount function.

See also:
connectedItemCount
Returns:
long ~ Number of Connected Items

Definition at line 148 of file cmcConnection.cpp.

void clear ( void  ) [slot]

Clear Items by Filter
.

This disconnects all connected items that meet the connection filter. If no filter is defined (via Customize-Database-Connection-Advanced) then it functions the same as clearAll().

Definition at line 226 of file cmcConnection.cpp.

void clearAll ( ) [slot]

Clear Items regardless of filter
.

This disconnects all connected items regardless of the connection filter.

Definition at line 261 of file cmcConnection.cpp.

void clearConnection ( const QString &  itemName,
const QString &  itemClarify = "" 
) [slot]

Clear Connection based on Name/Clarify
.

This disconnects a single, specific item identified by the ItemName and Clarify strings. Note that the "(-Me-)" keyword can be used for the ItemName parameter.

Definition at line 296 of file cmcConnection.cpp.

QString conName ( ) [slot]

Connection Name
.

Returns:
String ~ Name portion of the Connection Name

Definition at line 120 of file cmcConnection.cpp.

long connectedItemCount ( ) [slot]

Connected Item Count
.

This is a pass-through function provided natively by Commence. It returns the number of items connected to this conneciton field.

vbScript Example:
 dim oxConn: set oxConn = dfrm.Connection("pRD","Employee)
 dim i: for i = 1 to oxConn.ConnectedItemCount ' note 1-based index
   oxConn.CurrentSelection = i
   ddll.debug "employee name = " & oxConn.FieldValue("employeeKey")
 next
See also:
cic
Returns:
long ~ Number of Connected Items

Definition at line 143 of file cmcConnection.cpp.

long currentSelection ( ) [slot]

Get the Current Selection
.

This is a pass-through function to return the currentSelection row. If the connectedItemCount() is zero then this function will also return zero.

Note:
This is a 1-based index, not a zero based index!

Definition at line 205 of file cmcConnection.cpp.

void currentSelection ( long  selection) [slot]

Set the Current Selection
.

This is a pass-through function on the currentSelection. It sets the row for the fieldValue queries.

Note:
This is a 1-based index, not a zero based index!

Definition at line 163 of file cmcConnection.cpp.

void defaultField ( const QString &  fieldName) [slot]

Set the Default Field
.

Definition at line 612 of file cmcConnection.cpp.

QString defaultField ( ) [slot]

Return the Default Field
.

Definition at line 617 of file cmcConnection.cpp.

cmcConnectionDef * definition ( ) [virtual, slot]

Get the Field Definition String
.

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 94 of file cmcConnection.cpp.

void enter ( const QString &  connection,
const QString &  category,
const QString &  value 
) [signal]

Enter the Field signal
.

QString fieldName ( void  ) [slot]

Connection Field name
.

This function returns the connection full Field Name value, consistent with the "name + {space} + toCategory" function calls. The purpose of this function is to provide a quick evaluation of the field name as it compares to a connection field as follows:

vbScript Example - Checking a Connection Name against FieldName
 Sub Form_onEnterField(FieldName)
   dim oxEmployee: set oxEmployee = dfrm.connection("pRD Employee")
   if( FieldName = oxEmployee.fieldName ) then
      msgbox "you have entered the 'pRD Employee' connection!"
   end if
 End Sub

Definition at line 110 of file cmcConnection.cpp.

QString fieldName ( long  index) [slot]

Return a field name by Index
.

Note:
This is a zero-based index

Definition at line 132 of file cmcConnection.cpp.

QString fieldNames ( ) [slot]

Return a list of connection field names
.

Definition at line 137 of file cmcConnection.cpp.

QString fieldValue ( const QString &  fieldName) [slot]

Return a FieldValue
.

This is a pass-through function to the Commence.Form.Connection.FieldValue object interface. It returns a String Value of the target field in the connection.

vbScriptExample
 dim ddll: set ddll = createObject("DumontDLL")
 dim dfrm: set dfrm = ddll.form(form)
 dim oEAL: set oEAL = dfrm.field("Employee Attendee List")
 dim oxAE: set oxAE = dfrm.connection("Attending","Employee")

 sub Form_OnEnterField(FieldName)
   oEAL.value = ""
   if( oxAE.connectedItemCount > 0 ) then
     dim i: for i = 1 to oxAE.connectedItemCount
       oEAL.value = oEAL.value & oxAE.fieldValue("Initials") & " "
     next
   end if
 end sub

Note:
There is a peculiarity of the Commence Connection object in that if you set a connection value, and then try to immediately read it back again, you will get no data. This is because the value of the currentSelection() is still at zero, which is inaccurate. I suppose it's possible for the currentSelection() to remain at zero (remember, connection selection indexes are '1' based) after setting a connection, but this is really an invalid state, and somewhat confusing for the software engineer who is trying to figure out why he can't read back a value he just set. In any case, what we do here is reset the currentSelection() back to 1, where it should be, any time we try to read the value of a connection, and there are connected items, and the currentSelection() is zero. This effectively masks the problem.

Definition at line 397 of file cmcConnection.cpp.

QString fieldValue ( const QString &  itemName,
const QString &  fieldName 
) [slot]

Return a Field Value of a particular item
.

This scans the item names of all the items on a particular connection and returns the field value of a particular one (the first one).

Definition at line 479 of file cmcConnection.cpp.

QString fieldValue ( const QString &  compareField,
const QString &  compareValue,
const QString &  fieldName 
) [slot]

Return a Field Value of a particular item by a different field
.

This function allows the user to quickly scan all the items on a connection for a particular item by the value of some other field. This is, in essence, a rudimentary filter, but it helps make scanning connection fields pretty simple.

vbScript Example - Reading a field value of a connection of a specific item
 ' assume the following:
 ' 
 ' Inventory            
 ' ------------------   
 ' inventoryKey (Name)  
 ' Quantity     
 ' Min Quantity         
 ' Max Quantity         
 ' has -----------------> Inventory Item Loc
 '                        ------------------
 '                        guid (Name)
 '                        Quantity
 '                        in -------------------> Inventory Loc
 '                                                ------------------
 '                                                inventoryLocKey (Name)
 '                                                Description
 '
 ' Key("Beans and Rice")  Freezer 1(10)           Freezer 1
 ' Quantity(45)           Freezer 2(15)           Freezer 2
 ' Min(5)                 Freezer 3(20)           Freezer 3
 ' Max(100)                                       Fridge 1
 '                                                Fridge 2
 '                                                Fridge 3
 '
 x = dfrm.con("has Inventory Item Loc").fieldValue( "in Inventory Loc", "Freezer 2", "Quantity" )
 '
 ' x should be 15
 '

Definition at line 496 of file cmcConnection.cpp.

QString filterKeyword ( const QString &  keyword) [slot]

Return one of the filter keywords
.

Definition at line 607 of file cmcConnection.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.

Definition at line 89 of file cmcConnection.cpp.

long index ( ) [virtual, slot]

Return the index number of this field
.

Reimplemented from cmcObject.

Definition at line 749 of file cmcConnection.cpp.

bool isConnection ( ) [slot]

TRUE Connection Indicator
.

This is a convenicen function that returns always TRUE for connection objects.

Definition at line 84 of file cmcConnection.cpp.

bool isDirty ( ) [slot]

Return TRUE/FALSE if the connection is dirty
.

Definition at line 622 of file cmcConnection.cpp.

bool isField ( ) [slot]

FALSE Field Indicator
.

This is a convenience function that returns always FALSE for connection objects.

Definition at line 79 of file cmcConnection.cpp.

QString itemClarifyField ( ) [slot]

Get Item Clarify value
.

This is a pass-through function to return the Item Clarify value for the currentSelection if any.

Definition at line 218 of file cmcConnection.cpp.

QString itemName ( void  ) [slot]

Get Item Name value
.

This is a pass-through function to return the Item Name value for the currentSelection if any.

Definition at line 210 of file cmcConnection.cpp.

void leave ( const QString &  connection,
const QString &  category,
const QString &  value 
) [signal]

Leave the Field signal
.

QString name ( ) [slot]

Return the 'Name' of the connection
.

This returns the commence connection regular connection name. This is essentially a pass-through function returning the same value as a call to Form.Connection("to","Location").name

See also:
conName, toCategory, fullName, conCatName

Reimplemented from cmcObject.

Definition at line 105 of file cmcConnection.cpp.

bool onChange ( ) [virtual, slot]

Execute on-change function
.

Definition at line 742 of file cmcConnection.cpp.

bool onEnter ( ) [virtual, slot]

Execute on-enter functions
.

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

Definition at line 710 of file cmcConnection.cpp.

bool onLeave ( ) [virtual, slot]

Execute on-leave functions
.

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

Definition at line 723 of file cmcConnection.cpp.

QString previousValue ( ) [virtual, slot]

Return the previousValue
.

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

Definition at line 676 of file cmcConnection.cpp.

void reset ( ) [slot]

Reset the connection back to its 'untouched' state
.

Definition at line 68 of file cmcConnection.cpp.

void setConnection ( const QString &  itemName,
const QString &  itemClarify = "" 
) [slot]

Set a Connection based on Name/Clarify
.

Connects the item displayed on the form to a single, specific item identified by the ItemName and Clarify strings. Note that the "(-Me-)" keyword can be used for the ItemName parameter.

Definition at line 347 of file cmcConnection.cpp.

void setFilterKeyword ( const QString &  keyword,
const QString &  text,
long  flags 
) [slot]

Set the Filter Keyword
.

Definition at line 554 of file cmcConnection.cpp.

long uic ( ) [slot]

Unconnected Item Count
.

This is an alias for unconnectedItemCount

See also:
unconnectedItemCount
Returns:
long ~ Number of Unconnected Items

Definition at line 158 of file cmcConnection.cpp.

long unconnectedItemCount ( ) [slot]

Return the Unconnected Item Count
.

This is an interesting and aparently unimplemented method on the Connection. By its name it would appear that the function was designed to return the number of items that are NOT connected to this connection. Calling it, however, always appears to return zero, even though it does not generate any errors.

See also:
uic
Returns:
long ~ Number of Unconnected Items

Definition at line 153 of file cmcConnection.cpp.

void undo ( ) [slot]

Restore to the Previous Operation
.

Definition at line 644 of file cmcConnection.cpp.

QString value ( ) [slot]

Get ALL column(0) values
.

This is an extended function that returns all the column(0) values as a multiline string list.

Note:
This function is not limited by the number of connected items so be careful where you use it.

Definition at line 650 of file cmcConnection.cpp.

QString value ( long  index,
long  column 
) [slot]

Get a single row value for a specific column
.

This is an extended function that returns a single row of a column(n) value

Note:
The ROW is a 1-based index, not a zero based index! The column is a zero-based index.

Definition at line 703 of file cmcConnection.cpp.

QString value ( long  index) [slot]

Get a single row value for column(0)
.

This is an extended function that returns a single row of a column(0) value.

Note:
This is a 1-based index, not a zero based index!

Definition at line 684 of file cmcConnection.cpp.

QString varValue ( const QString &  fieldName,
const QString &  varName 
) [slot]

Return index number of a particular field
.

For each connection, there is a list of fields that can be fetched. Normally the fields are fetched through the fieldValue( FieldName ) method. However, it is also possible to fetch field values by their index number. The index number of the field is based on its ordinal position in the field list. This function returns that index number of the field name.

Return a var field value

Definition at line 544 of file cmcConnection.cpp.


Member Data Documentation

QString m_conName [private]

Connection Name cache
.

Definition at line 602 of file cmcConnection.h.

QString m_defaultField [private]

Default Field cache
.

Definition at line 626 of file cmcConnection.h.

QString m_enterValue [private]

Enter Field value cache
.

Definition at line 650 of file cmcConnection.h.

QStringList m_fieldList [private]

Field List cache
.

Definition at line 618 of file cmcConnection.h.

bool m_gotPreviousValue [private]

Got Previous Value flag
.

Definition at line 635 of file cmcConnection.h.

QString m_previousValue [private]

Previous Value cache
.

Definition at line 642 of file cmcConnection.h.

QString m_toCategory [private]

To Category Name cache
.

Definition at line 610 of file cmcConnection.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