QCommenceConnection Class Reference

Form.Connection object interface. More...

#include <QCommenceDB.h>

Inheritance diagram for QCommenceConnection:

Inheritance graph

List of all members.

Public Slots

void reset (void)
 Reset the connection back to its 'untouched' state.
QString xml (void)
QString conName (void)
QString toCategory (void)
virtual long index (void)
 Return the index number of this field.
bool isField (void)
 FALSE Field Indicator.
bool isConnection (void)
 TRUE Connection Indicator.
QString name (void)
 Return the 'Name' of the connection.
QString fieldName ()
 Connection Field name.
QString conCatName ()
virtual QCommenceConnectionDefdefinition (void)
 Get the Field Definition String.
long connectedItemCount ()
 Return the number of items connected.
long cic ()
 Return the number of items connected.
long unconnectedItemCount (void)
 Return the Unconnected Item Count.
void currentSelection (long i_selection)
 Set the Current Selection.
long currentSelection (void)
 Get the Current Selection.
QString itemName (void)
 Get Item Name value.
QString itemClarifyField (void)
 Get Item Clarify value.
void clear (void)
 Clear Items by Filter.
void clearAll (void)
 Clear Items regardless of filter.
void clearConnection (QString i_itemName, QString i_itemClarify="")
 Clear Connection based on Name/Clarify.
void setConnection (QString i_itemName, QString i_itemClarify="")
 Set a Connection based on Name/Clarify.
QString value (void)
 Get ALL column(0) values.
QString value (long i_index)
 Get a single row value for column(0).
QString value (long i_index, long i_column)
 Get a single row value for a specific column.
virtual QString previousValue (void)
 Return the previousValue.
QString fieldValue (QString fieldName)
 Return a FieldValue.
QString fieldValue (QString itemName, QString fieldName)
 Return a Field Value of a particular item.
QString fieldValue (QString compareField, QString compareValue, QString fieldName)
 Return a Field Value of a particular item by a different field.
QString varValue (QString i_fieldName, QString i_varName)
 Return index number of a particular field.
void setFilterKeyword (QString i_keyword, QString i_text, long flags)
QString filterKeyword (QString i_keyword)
 Return one of the filter keywords.
void defaultField (QString i_fieldName)
QString defaultField (void)
bool isDirty (void)
 Return TRUE/FALSE if the connection is dirty.
QString changeLog (void)
void undo (void)
QString fieldName (long i_index)
virtual bool onEnter (void)
 Return a list of connection field names.
virtual bool onLeave (void)
 Execute on-leave functions.
virtual bool onChange (void)

Signals

void enter (QString o_connection, QString o_category, QString o_value)
void leave (QString o_connection, QString o_category, QString o_value)
void change (QString o_connection, QString o_category, QString o_value)

Public Member Functions

 QCommenceConnection (void)
 Copy Constructor.
 QCommenceConnection (QCocDispatch *i_unknown, QCommenceForm *i_parent, QString i_conName="", QString i_fieldName="")
 Regular Constructor.
virtual ~QCommenceConnection ()
 Default Destructor.
QDomElement domElement (QDomDocument &doc, QDomNode &parent)

Protected Member Functions

QCommenceFormform (void)
 Return the parent Form object.

Private Attributes

QPointer< QCommenceConnectionDefm_definition
QString m_conName
QString m_toCategory
QStringList m_fieldList
QString m_defaultField
bool m_gotPreviousValue
QString m_previousValue
QString m_enterValue


Detailed Description

Form.Connection object interface.

inline_dotgraph_7.dot

This is the Dumont-Enhanced Commence Connection object. This object is designed to wrap a Commence Form.Connection object and then add some natural extensions. These extensions include providing access to the field-type definition() of any target field in the connection, undo() and onChange() event handling and so on.

Note:
Please note one thing about the Commence.Connection field. The currentSelection() method operates on a 1-based index method. This is very different from the Cursor and RowSet objects since they operate on a zero-based index principal. Please make a mental note of this when interfacing with this object. The index-base is noted where relavent. For scripting compatibility the Dumont Form.Connection object employs a 1-base index interface on the currentSelection() routines.

Definition at line 2616 of file QCommenceDB.h.


Constructor & Destructor Documentation

QCommenceConnection::QCommenceConnection ( void   )  [inline]

Copy Constructor.

Definition at line 2628 of file QCommenceDB.h.

QCommenceConnection::QCommenceConnection ( QCocDispatch i_unknown,
QCommenceForm i_parent,
QString  i_conName = "",
QString  i_fieldName = "" 
)

Regular Constructor.

This constructor is used from the QCommenceForm.connection() request. The constructor includes the definition of the connection Name and a default target field name. The conName() is that part of the definition that doesn't include the target category. The defaultField() is used to shorthand access to a particular column of data.

Definition at line 870 of file QCommenceDB.cpp.

QCommenceConnection::~QCommenceConnection (  )  [virtual]

Default Destructor.

Definition at line 920 of file QCommenceDB.cpp.


Member Function Documentation

void QCommenceConnection::change ( QString  o_connection,
QString  o_category,
QString  o_value 
) [signal]

QString QCommenceConnection::changeLog ( void   )  [slot]

See also:
Change Log Engine

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

Definition at line 1442 of file QCommenceDB.cpp.

long QCommenceConnection::cic (  )  [slot]

Return the number of items connected.

This is an alias for connectedItemCount.

Definition at line 979 of file QCommenceDB.cpp.

void QCommenceConnection::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 1052 of file QCommenceDB.cpp.

void QCommenceConnection::clearAll ( void   )  [slot]

Clear Items regardless of filter.

This disconnects all connected items regardless of the connection filter.

Definition at line 1087 of file QCommenceDB.cpp.

void QCommenceConnection::clearConnection ( QString  i_itemName,
QString  i_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 1122 of file QCommenceDB.cpp.

QString QCommenceConnection::conCatName (  )  [slot]

Definition at line 952 of file QCommenceDB.cpp.

QString QCommenceConnection::conName ( void   )  [slot]

Definition at line 957 of file QCommenceDB.cpp.

long QCommenceConnection::connectedItemCount ( void   )  [slot]

Return the number of items connected.

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

Definition at line 974 of file QCommenceDB.cpp.

long QCommenceConnection::currentSelection ( void   )  [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 1031 of file QCommenceDB.cpp.

void QCommenceConnection::currentSelection ( long  i_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 989 of file QCommenceDB.cpp.

QString QCommenceConnection::defaultField ( void   )  [slot]

Definition at line 1432 of file QCommenceDB.cpp.

void QCommenceConnection::defaultField ( QString  i_fieldName  )  [slot]

Definition at line 1427 of file QCommenceDB.cpp.

QCommenceConnectionDef * QCommenceConnection::definition ( void   )  [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 931 of file QCommenceDB.cpp.

QDomElement QCommenceConnection::domElement ( QDomDocument &  doc,
QDomNode &  parent 
)

Definition at line 1572 of file QCommenceDB.cpp.

void QCommenceConnection::enter ( QString  o_connection,
QString  o_category,
QString  o_value 
) [signal]

QString QCommenceConnection::fieldName ( long  i_index  )  [slot]

Note:
This is a zero-based index.

Definition at line 969 of file QCommenceDB.cpp.

QString QCommenceConnection::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 947 of file QCommenceDB.cpp.

QString QCommenceConnection::fieldValue ( QString  compareField,
QString  compareValue,
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 1321 of file QCommenceDB.cpp.

QString QCommenceConnection::fieldValue ( QString  itemName,
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 1306 of file QCommenceDB.cpp.

QString QCommenceConnection::fieldValue ( 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 1224 of file QCommenceDB.cpp.

QString QCommenceConnection::filterKeyword ( QString  i_keyword  )  [slot]

Return one of the filter keywords.

Definition at line 1422 of file QCommenceDB.cpp.

QCommenceForm * QCommenceConnection::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.

Definition at line 926 of file QCommenceDB.cpp.

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

Return the index number of this field.

Definition at line 1567 of file QCommenceDB.cpp.

bool QCommenceConnection::isConnection ( void   )  [slot]

TRUE Connection Indicator.

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

Definition at line 915 of file QCommenceDB.cpp.

bool QCommenceConnection::isDirty ( void   )  [slot]

Return TRUE/FALSE if the connection is dirty.

Definition at line 1437 of file QCommenceDB.cpp.

bool QCommenceConnection::isField ( void   )  [slot]

FALSE Field Indicator.

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

Definition at line 910 of file QCommenceDB.cpp.

QString QCommenceConnection::itemClarifyField ( void   )  [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 1044 of file QCommenceDB.cpp.

QString QCommenceConnection::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 1036 of file QCommenceDB.cpp.

void QCommenceConnection::leave ( QString  o_connection,
QString  o_category,
QString  o_value 
) [signal]

QString QCommenceConnection::name ( void   )  [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

Definition at line 942 of file QCommenceDB.cpp.

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

Definition at line 1561 of file QCommenceDB.cpp.

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

Return a list of connection field names.

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 1528 of file QCommenceDB.cpp.

bool QCommenceConnection::onLeave ( void   )  [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 1543 of file QCommenceDB.cpp.

QString QCommenceConnection::previousValue ( void   )  [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 1496 of file QCommenceDB.cpp.

void QCommenceConnection::reset ( void   )  [slot]

Reset the connection back to its 'untouched' state.

Definition at line 899 of file QCommenceDB.cpp.

void QCommenceConnection::setConnection ( QString  i_itemName,
QString  i_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 1173 of file QCommenceDB.cpp.

void QCommenceConnection::setFilterKeyword ( QString  i_keyword,
QString  i_text,
long  flags 
) [slot]

Definition at line 1371 of file QCommenceDB.cpp.

QString QCommenceConnection::toCategory ( void   )  [slot]

Definition at line 962 of file QCommenceDB.cpp.

long QCommenceConnection::unconnectedItemCount ( void   )  [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.

Definition at line 984 of file QCommenceDB.cpp.

void QCommenceConnection::undo ( void   )  [slot]

Definition at line 1458 of file QCommenceDB.cpp.

QString QCommenceConnection::value ( long  i_index,
long  i_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 1522 of file QCommenceDB.cpp.

QString QCommenceConnection::value ( long  i_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 1503 of file QCommenceDB.cpp.

QString QCommenceConnection::value ( void   )  [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 1463 of file QCommenceDB.cpp.

QString QCommenceConnection::varValue ( QString  i_fieldName,
QString  i_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 1364 of file QCommenceDB.cpp.

QString QCommenceConnection::xml ( void   )  [slot]

Definition at line 1683 of file QCommenceDB.cpp.


Member Data Documentation

QString QCommenceConnection::m_conName [private]

Definition at line 3201 of file QCommenceDB.h.

Definition at line 3225 of file QCommenceDB.h.

Definition at line 3193 of file QCommenceDB.h.

Definition at line 3243 of file QCommenceDB.h.

QStringList QCommenceConnection::m_fieldList [private]

Definition at line 3217 of file QCommenceDB.h.

Definition at line 3234 of file QCommenceDB.h.

Definition at line 3235 of file QCommenceDB.h.

Definition at line 3209 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