DumontEXE 0.0.1
cmcConnection.h
00001 /* ***************************************************************************
00002 **
00003 ** Copyright (C) 2007 Lorimark Solutions, LLC. All rights reserved.
00004 **
00005 ** This file is part of the DumontEXE Scripting Extension Kit
00006 **
00007 ** This file may be used under the terms of the GNU General Public
00008 ** License version 2.0 as published by the Free Software Foundation
00009 ** and appearing in the file LICENSE.GPL included in the packaging of
00010 ** this file.  Please review the following information to ensure GNU
00011 ** General Public Licensing requirements will be met:
00012 ** http://dumont.showoff-db.org/opensource.html
00013 **
00014 ** If you are unsure which license is appropriate for your use, please
00015 ** review the following information:
00016 ** http://dumont.showoff-db.org/licensing.html 
00017 ** or contact the sales department at sales@lorimarksolutions.com.
00018 **
00019 ** This file is provided AS IS with NO WARRANTY OF ANY KIND, INCLUDING THE
00020 ** WARRANTY OF DESIGN, MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE.
00021 **
00022 ** author: Mark Petryk ~ Lorimark Solutions, LLC
00023 ** **************************************************************************/
00024 
00025 #ifndef CDA_CONNECTION_H_422FD07F_0597_4cbb_A034_9AE85166472E
00026 #define CDA_CONNECTION_H_422FD07F_0597_4cbb_A034_9AE85166472E
00027 
00028 #include "cmcApi.h"
00029 
00030 #include <QStringList>
00031 
00032 namespace cmcDatabaseApi {
00033 
00034 class cmcForm;
00035 class cmcConnectionDef;
00036 
00037 /*!
00038 ** \brief Connection
00039 **
00040 **
00041 */
00042 class cmcConnection:
00043   public cmcApi
00044 {
00045   Q_OBJECT
00046   public:
00047 
00048     cmcConnection( const cmcConnection & copy );
00049 
00050     cmcConnection
00051     (
00052       const QString & conName,
00053       IDispatch * dispatch,
00054       cmcForm * parent
00055     );
00056 
00057     virtual ~cmcConnection();
00058 
00059   public slots:
00060 
00061     /*!
00062     ** \brief Reset the connection back to its 'untouched' state \n
00063     **
00064     **
00065     */
00066     void reset();
00067 
00068     /*!
00069     ** \brief Connection Name \n
00070     **
00071     ** \return String ~ Name portion of the Connection Name
00072     */
00073     QString conName();
00074     QString toCategory();
00075 
00076     /*!
00077     ** \brief Return the index number of this field \n
00078     **
00079     **
00080     */
00081     virtual long index();
00082 
00083     /*!
00084     ** \brief FALSE Field Indicator \n
00085     **
00086     ** This is a convenience function that returns always FALSE for
00087     **  connection objects.
00088     **
00089     */
00090     bool isField();
00091 
00092     /*!
00093     ** \brief TRUE Connection Indicator \n
00094     **
00095     ** This is a convenicen function that returns always TRUE for
00096     **  connection objects.
00097     **
00098     */
00099     bool isConnection();
00100 
00101     /*!
00102     ** \brief Return the 'Name' of the connection \n
00103     **
00104     ** This returns the commence connection regular connection name.  This is 
00105     **  essentially a pass-through function returning the same value as a call
00106     **  to Form.Connection("to","Location").name
00107     **
00108     ** \sa conName, toCategory, fullName, conCatName
00109     **
00110     */
00111     QString name();
00112 
00113     /*!
00114     ** \brief Connection Field name \n
00115     **
00116     ** This function returns the connection full Field Name value, consistent with the
00117     **  \c "name + {space} + toCategory" function calls.  The purpose of this function
00118     **  is to provide a quick evaluation of the field name as it compares to a
00119     **  connection field as follows:
00120     **
00121     ** \par vbScript Example - Checking a Connection Name against FieldName
00122     ** \code
00123     ** Sub Form_onEnterField(FieldName)
00124     **   dim oxEmployee: set oxEmployee = dfrm.connection("pRD Employee")
00125     **   if( FieldName = oxEmployee.fieldName ) then
00126     **      msgbox "you have entered the 'pRD Employee' connection!"
00127     **   end if
00128     ** End Sub
00129     ** \endcode
00130     **
00131     */
00132     QString fieldName();
00133 
00134     /*
00135     ** \brief Combined Connection Category Name \n
00136     **
00137     ** \sa conName, toCategory
00138     */
00139     QString conCatName();
00140 
00141 
00142     /*!
00143     ** \brief Get the Field Definition String \n
00144     **
00145     ** This method makes a DDE request to retrieve the field definition string.
00146     **  This string value is then cached and used for the various field definition
00147     **  function calls to avoid having to make multiple calls into the Commence
00148     **  API.
00149     **
00150     */
00151     virtual cmcConnectionDef * definition();
00152 
00153     /*!
00154     ** \brief Connected Item Count \n
00155     **
00156     ** This is a pass-through function provided natively by Commence.  It returns
00157     **  the number of items connected to this conneciton field.
00158     **
00159     ** \par vbScript Example:
00160     ** \code
00161     ** dim oxConn: set oxConn = dfrm.Connection("pRD","Employee)
00162     ** dim i: for i = 1 to oxConn.ConnectedItemCount ' note 1-based index
00163     **   oxConn.CurrentSelection = i
00164     **   ddll.debug "employee name = " & oxConn.FieldValue("employeeKey")
00165     ** next
00166     ** \endcode
00167     **
00168     ** \sa cic
00169     **
00170     ** \return long ~ Number of Connected Items
00171     */
00172     long connectedItemCount();
00173 
00174     /*!
00175     ** \brief Connected Item Count \n
00176     **
00177     ** This is an alias for the \ref connectedItemCount function.
00178     **
00179     ** \sa connectedItemCount
00180     **
00181     ** \return long ~ Number of Connected Items
00182     */
00183     long cic();
00184 
00185     /*!
00186     ** \brief Return the Unconnected Item Count \n
00187     **
00188     ** This is an interesting and aparently unimplemented method on the Connection.
00189     **  By its name it would appear that the function was designed to return the
00190     **  number of items that are NOT connected to this connection.  Calling it,
00191     **  however, always appears to return zero, even though it does not generate
00192     **  any errors.
00193     **
00194     ** \sa uic
00195     **
00196     ** \return long ~ Number of Unconnected Items
00197     */
00198     long unconnectedItemCount();
00199 
00200     /*!
00201     ** \brief Unconnected Item Count \n
00202     **
00203     ** This is an alias for unconnectedItemCount
00204     **
00205     ** \sa unconnectedItemCount
00206     **
00207     ** \return long ~ Number of Unconnected Items
00208     */
00209     long uic();
00210 
00211     /*!
00212     ** \brief Set the Current Selection \n
00213     **
00214     ** This is a pass-through function on the currentSelection.  It sets the 
00215     **  row for the fieldValue queries.
00216     **
00217     ** \note This is a 1-based index, not a zero based index!
00218     **
00219     */
00220     void currentSelection( long selection );
00221 
00222     /*!
00223     ** \brief Get the Current Selection \n
00224     **
00225     ** This is a pass-through function to return the currentSelection row.  If
00226     **  the connectedItemCount() is zero then this function will also return
00227     **  zero.
00228     **
00229     ** \note This is a 1-based index, not a zero based index!
00230     **
00231     */
00232     long currentSelection();
00233 
00234     /*!
00235     ** \brief Get Item Name value \n
00236     **
00237     ** This is a pass-through function to return the Item Name value for
00238     **  the currentSelection if any.
00239     **
00240     */
00241     QString itemName();
00242 
00243     /*!
00244     ** \brief Get Item Clarify value \n
00245     **
00246     ** This is a pass-through function to return the Item Clarify value
00247     **  for the currentSelection if any.
00248     **
00249     */
00250     QString itemClarifyField();
00251 
00252     /*!
00253     ** \brief Clear Items by Filter \n
00254     **
00255     ** This disconnects all connected items that meet the connection filter.  
00256     **  If no filter is defined (via Customize-Database-Connection-Advanced) 
00257     **  then it functions the same as clearAll().
00258     **
00259     */
00260     void clear();
00261 
00262     /*!
00263     ** \brief Clear Items regardless of filter \n
00264     **
00265     ** This disconnects all connected items regardless of the connection filter.
00266     **
00267     */
00268     void clearAll();
00269 
00270     /*!
00271     ** \brief Clear Connection based on Name/Clarify \n
00272     **
00273     ** This disconnects a single, specific item identified by the ItemName and 
00274     **  Clarify strings. Note that the "(-Me-)" keyword can be used for the 
00275     **  ItemName parameter.
00276     **
00277     */
00278     void clearConnection( const QString & itemName, const QString & itemClarify = "" );
00279 
00280     /*!
00281     ** \brief Set a Connection based on Name/Clarify \n
00282     **
00283     ** Connects the item displayed on the form to a single, specific item 
00284     **  identified by the ItemName and Clarify strings. Note that the "(-Me-)" 
00285     **  keyword can be used for the ItemName parameter.
00286     **
00287     */
00288     void setConnection( const QString & itemName, const QString & itemClarify = "" );
00289 
00290     /*!
00291     ** \brief Get ALL column(0) values \n
00292     **
00293     ** This is an extended function that returns all the column(0) values as a 
00294     **  multiline string list.  
00295     **
00296     ** \note This function is not limited by the number of connected items so 
00297     **  be careful where you use it.
00298     **
00299     */
00300     QString value();
00301 
00302     /*!
00303     ** \brief Get a single row value for column(0) \n
00304     **
00305     ** This is an extended function that returns a single row of a column(0)
00306     **  value.
00307     **
00308     ** \note This is a 1-based index, not a zero based index!
00309     **
00310     */
00311     QString value( long index );
00312 
00313     /*!
00314     ** \brief Get a single row value for a specific column \n
00315     **
00316     ** This is an extended function that returns a single row of a column(n)
00317     **  value
00318     **
00319     ** \note The ROW is a 1-based index, not a zero based index!  The column is
00320     **  a zero-based index.
00321     **
00322     */
00323     QString value( long index, long column ); 
00324 
00325 
00326     /*!
00327     ** \brief Return the previousValue \n
00328     **
00329     ** This returns the previous value of the connection.  The previousValue() is 
00330     **  based upon the value of the connection at the time this Connection object was
00331     **  created.  When Dumont is requested for a Connection object, it records the
00332     **  current Commence Connection value and stores that as its previous value.
00333     **  All changes to the Connection value then become the new value, and 
00334     **  referring to the previous value always refers to the absolute beginning
00335     **  value of the connection, not the previous value from the most recent change.
00336     **
00337     */
00338     virtual QString previousValue();
00339 
00340     /*!
00341     ** \brief Return a FieldValue \n
00342     **
00343     ** This is a pass-through function to the Commence.Form.Connection.FieldValue
00344     **  object interface.  It returns a String Value of the target field in the
00345     **  connection.
00346     **
00347     ** \par vbScriptExample
00348     ** \code
00349     ** dim ddll: set ddll = createObject("DumontDLL")
00350     ** dim dfrm: set dfrm = ddll.form(form)
00351     ** dim oEAL: set oEAL = dfrm.field("Employee Attendee List")
00352     ** dim oxAE: set oxAE = dfrm.connection("Attending","Employee")
00353     **
00354     ** sub Form_OnEnterField(FieldName)
00355     **   oEAL.value = ""
00356     **   if( oxAE.connectedItemCount > 0 ) then
00357     **     dim i: for i = 1 to oxAE.connectedItemCount
00358     **       oEAL.value = oEAL.value & oxAE.fieldValue("Initials") & " "
00359     **     next
00360     **   end if
00361     ** end sub
00362     ** \endcode
00363     **
00364     */
00365     QString fieldValue( const QString & fieldName );
00366 
00367     /*!
00368     ** \brief Return a Field Value of a particular item \n
00369     **
00370     ** This scans the item names of all the items on a particular connection and
00371     **  returns the field value of a particular one (the first one).
00372     **
00373     */
00374     QString fieldValue( const QString & itemName, const QString & fieldName );
00375 
00376     /*!
00377     ** \brief Return a Field Value of a particular item by a different field \n
00378     **
00379     ** This function allows the user to quickly scan all the items on a connection
00380     **  for a particular item by the value of some other field.  This is, in essence,
00381     **  a rudimentary filter, but it helps make scanning connection fields pretty
00382     **  simple.
00383     **
00384     ** \par vbScript Example - Reading a field value of a connection of a specific item
00385     ** \code
00386     ** ' assume the following:
00387     ** ' 
00388     ** ' Inventory            
00389     ** ' ------------------   
00390     ** ' inventoryKey (Name)  
00391     ** ' Quantity     
00392     ** ' Min Quantity         
00393     ** ' Max Quantity         
00394     ** ' has -----------------> Inventory Item Loc
00395     ** '                        ------------------
00396     ** '                        guid (Name)
00397     ** '                        Quantity
00398     ** '                        in -------------------> Inventory Loc
00399     ** '                                                ------------------
00400     ** '                                                inventoryLocKey (Name)
00401     ** '                                                Description
00402     ** '
00403     ** ' Key("Beans and Rice")  Freezer 1(10)           Freezer 1
00404     ** ' Quantity(45)           Freezer 2(15)           Freezer 2
00405     ** ' Min(5)                 Freezer 3(20)           Freezer 3
00406     ** ' Max(100)                                       Fridge 1
00407     ** '                                                Fridge 2
00408     ** '                                                Fridge 3
00409     ** '
00410     ** x = dfrm.con("has Inventory Item Loc").fieldValue( "in Inventory Loc", "Freezer 2", "Quantity" )
00411     ** '
00412     ** ' x should be 15
00413     ** '
00414     ** \endcode
00415     **
00416     */
00417     QString fieldValue( const QString & compareField, const QString & compareValue, const QString & fieldName );
00418 
00419     /*!
00420     ** \brief Return index number of a particular field \n
00421     **
00422     ** For each connection, there is a list of fields that can be fetched.  Normally
00423     **  the fields are fetched through the fieldValue( FieldName ) method.  However,
00424     **  it is also possible to fetch field values by their index number.  The 
00425     **  index number of the field is based on its ordinal position in the field
00426     **  list.  This function returns that index number of the field name.
00427     **
00428     */
00429 //    long fieldIndex( QString fieldName );
00430 
00431     /*!
00432     ** \brief Return a var field value \n
00433     **
00434     ** 
00435     **
00436     */
00437     QString varValue( const QString & fieldName, const QString & varName );
00438 
00439     /*!
00440     ** \brief Set the Filter Keyword \n
00441     **
00442     **
00443     **
00444     */
00445     void setFilterKeyword( const QString & keyword, const QString & text, long flags );
00446 
00447     /*!
00448     ** \brief Return one of the filter keywords \n
00449     **
00450     */
00451     QString filterKeyword( const QString & keyword );
00452 
00453     /*!
00454     ** \brief Set the Default Field \n
00455     **
00456     **
00457     **
00458     */
00459     void defaultField( const QString & fieldName );
00460 
00461     /*!
00462     ** \brief Return the Default Field \n
00463     **
00464     **
00465     **
00466     */
00467     QString defaultField();
00468 
00469     /*!
00470     ** \brief Return TRUE/FALSE if the connection is dirty \n
00471     **
00472     **
00473     **
00474     */
00475     bool isDirty();
00476 
00477     /*!
00478     ** \brief Get the Connection Change Log \n
00479     **
00480     **
00481     ** \sa \ref ChangeLogEngine
00482     */
00483     QString changeLog();
00484 
00485     /*!
00486     ** \brief Restore to the Previous Operation \n
00487     **
00488     **
00489     **
00490     */
00491     void undo();
00492 
00493     /*!
00494     ** \brief Return a field name by Index \n
00495     **
00496     **
00497     ** \note This is a zero-based index
00498     **
00499     */
00500     QString fieldName( long index );
00501 
00502     /*!
00503     ** \brief Return a list of connection field names \n
00504     **
00505     **
00506     **
00507     */
00508     QString fieldNames();
00509 
00510     /*!
00511     ** \brief Execute on-enter functions \n
00512     **
00513     ** This function is intended to be called by the parent form to indicate
00514     **  that the connection has become active in the user interface and may 
00515     **  possibly be edited.
00516     **
00517     */
00518     virtual bool onEnter();
00519 
00520     /*!
00521     ** \brief Execute on-leave functions \n
00522     **
00523     ** This function is intended to be called by the parent form to indicate
00524     **  that the connection has become inactive in the user interface and is
00525     **  no longer being edited.
00526     **
00527     */
00528     virtual bool onLeave();
00529 
00530     /*!
00531     ** \brief Execute on-change function \n
00532     **
00533     **
00534     **
00535     */
00536     virtual bool onChange();
00537 
00538 //    long    unconnectedItemCount ( void );
00539 //    void    clarify              ( void );
00540 //    QString fieldName            ( void );
00541 //    void    setActiveItem        ( void );
00542 //    QString categoryName         ( void );
00543 //    long    flags                ( void );
00544 //    void    setActiveDate        ( void );
00545 //    QDate   date                 ( void );
00546 //    void    setActiveDateRange   ( void );
00547 //    QDate   startDate            ( void );
00548 //    void    restoreFilter        ( void );
00549 //    QString keyword              ( void );
00550 //    QString value                ( void );
00551 
00552   signals:
00553 
00554     /*!
00555     ** \brief Enter the Field signal \n
00556     **
00557     **
00558     **
00559     */
00560     void enter( const QString & connection, const QString & category, const QString & value );
00561 
00562     /*!
00563     ** \brief Leave the Field signal \n
00564     **
00565     **
00566     **
00567     */
00568     void leave( const QString & connection, const QString & category, const QString & value );
00569 
00570     /*!
00571     ** \brief Change the Field signal \n
00572     **
00573     **
00574     **
00575     */
00576     void change( const QString & connection, const QString & category, const QString & value );
00577 
00578   protected:
00579 
00580     /*!
00581     ** \brief Return the parent Form object \n
00582     **
00583     ** This function returns a pointer to this field's parent Form.  It is
00584     **  private because nothing on this field should be being called 
00585     **  except through the form anyway, so providing a pointer to that
00586     **  said form is problemmatic and probably a pointer crash issue.  It's 
00587     **  only used internally.
00588     **
00589     */
00590     cmcForm * form();
00591 
00592   private:
00593 
00594     QPointer<cmcConnectionDef> m_definition;
00595 
00596     /*!
00597     ** \brief Connection Name cache \n
00598     **
00599     **
00600     **
00601     */
00602     QString m_conName;
00603 
00604     /*!
00605     ** \brief To Category Name cache \n
00606     **
00607     **
00608     **
00609     */
00610     QString m_toCategory;
00611 
00612     /*!
00613     ** \brief Field List cache \n
00614     **
00615     **
00616     **
00617     */
00618     QStringList m_fieldList;
00619 
00620     /*!
00621     ** \brief Default Field cache \n
00622     **
00623     **
00624     **
00625     */
00626     QString m_defaultField;
00627 
00628 
00629     /*!
00630     ** \brief Got Previous Value flag \n
00631     **
00632     **
00633     **
00634     */
00635     bool m_gotPreviousValue;
00636 
00637     /*!
00638     ** \brief Previous Value cache \n
00639     **
00640     **
00641     */
00642     QString m_previousValue;
00643 
00644     /*!
00645     ** \brief Enter Field value cache \n
00646     **
00647     **
00648     **
00649     */
00650     QString m_enterValue;
00651 
00652 }; // endclass cmcConnection:
00653 
00654 } // endnamespace cmcDatabaseApi
00655 
00656 #endif // #ifndef CDA_CONNECTION_H
00657 
 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