DumontEXE 0.0.1
cmcCategoryDef.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_CATEGORY_DEF_H_422FD07F_0597_4cbb_A034_9AE85166472E
00026 #define CDA_CATEGORY_DEF_H_422FD07F_0597_4cbb_A034_9AE85166472E
00027 
00028 #include <QPointer>
00029 #include <QStringList>
00030 
00031 #include "cmcObject.h"
00032 #include "cmcFieldDef.h"
00033 
00034 namespace cmcDatabaseApi {
00035 
00036 class cmcApplication;
00037 class cmcCategoryDefs;
00038 class cmcFieldDefs;
00039 class cmcFieldDef;
00040 class cmcConnectionDefs;
00041 class cmcConnectionDef;
00042 class cmcFormDefs;
00043 class cmcFormDef;
00044 class cmcViewDefs;
00045 class cmcViewDef;
00046 
00047 /*!
00048 ** \brief Category Definition
00049 **
00050 **
00051 */
00052 class cmcCategoryDef:
00053   public cmcObject
00054 {
00055   Q_OBJECT
00056   Q_PROPERTY( QString catName           READ catName                                   DESIGNABLE false SCRIPTABLE true  STORED true                          )
00057   Q_PROPERTY( long    maxItems          READ maxItems                                  DESIGNABLE false SCRIPTABLE true  STORED true                          )
00058   Q_PROPERTY( bool    isShared          READ isShared                                  DESIGNABLE false SCRIPTABLE true  STORED true                          )
00059   Q_PROPERTY( bool    duplicatesAllowed READ duplicatesAllowed                         DESIGNABLE false SCRIPTABLE true  STORED true                          )
00060   Q_PROPERTY( bool    hasClarifyField   READ hasClarifyField                           DESIGNABLE false SCRIPTABLE true  STORED false                         )
00061   Q_PROPERTY( bool    hasVarField       READ hasVarField                               DESIGNABLE false SCRIPTABLE true  STORED false                         )
00062   Q_PROPERTY( bool    hasThidField      READ hasThidField                              DESIGNABLE false SCRIPTABLE true  STORED false                         )
00063   Q_PROPERTY( bool    hasGuidField      READ hasGuidField                              DESIGNABLE false SCRIPTABLE true  STORED false                         )
00064   Q_PROPERTY( QString keyFieldName      READ keyFieldName                              DESIGNABLE true  SCRIPTABLE true  STORED true                          )
00065   Q_PROPERTY( QString cfyFieldName      READ cfyFieldName                              DESIGNABLE true  SCRIPTABLE true  STORED true                          )
00066   Q_PROPERTY( QString cfySeparator      READ cfySeparator                              DESIGNABLE true  SCRIPTABLE true  STORED true                          )
00067   Q_PROPERTY( QString thidFieldName     READ thidFieldName     WRITE setThidFieldName  DESIGNABLE true  SCRIPTABLE true  STORED true  RESET rstThidFieldName  )
00068   Q_PROPERTY( QString guidFieldName     READ guidFieldName     WRITE setGuidFieldName  DESIGNABLE true  SCRIPTABLE true  STORED true  RESET rstGuidFieldName  )
00069   Q_PROPERTY( QString varFieldName      READ varFieldName      WRITE setVarFieldName   DESIGNABLE true  SCRIPTABLE true  STORED true  RESET rstVarFieldName   )
00070   Q_PROPERTY( bool    isPublished       READ isPublished       WRITE setIsPublished    DESIGNABLE true  SCRIPTABLE true  STORED true  RESET rstIsPublished    )
00071 
00072   public:
00073 
00074     /*!
00075     ** \brief Copy Constructor \n
00076     **
00077     */
00078     cmcCategoryDef( const cmcCategoryDef & copy );
00079 
00080     /*!
00081     ** \brief Standard Constructor \n
00082     **
00083     **
00084     */
00085     cmcCategoryDef( const QString & categoryName, cmcApplication * application, cmcCategoryDefs * parent );
00086 
00087     /*!
00088     ** \brief Primary Destructor \n
00089     **
00090     ** This destructor handles cleanup of the object.
00091     **
00092     */
00093     virtual ~cmcCategoryDef();
00094 
00095     /*!
00096     ** \brief Category Definition String \n
00097     **
00098     ** This is the category definition string as returned by the DDE call to to
00099     **  [GetCategoryDefinition(CategoryName)].  This string is delimited by vbCrLf.
00100     **
00101     ** This value gets cached on first call, meaning if the category definition 
00102     **  changes after this call (unlikely), then this value will be invalid.
00103     **
00104     */
00105     QStringList stringList();
00106 
00107   public slots:
00108 
00109 
00110     /*!
00111     ** \brief Category Name \n
00112     **
00113     ** This is an overloaded function of name().  It is provided for convenience because
00114     **  many of the other objects in the system refer to the 'categoryName' and having
00115     **  a consistent interface makes the objects easier to work with.
00116     **
00117     */
00118     QString categoryName();
00119 
00120     /*!
00121     ** \brief Return a specially modified categoryName \n
00122     **
00123     ** This returns a specially modified category name.  This method is designed 
00124     **  to be used by the keyFieldName, cfyFieldName and varFieldName functions.
00125     **  When applied, this function will return the following results:
00126     **
00127     ** \par 
00128     ** \code
00129     **                                               (typical)             (typical)
00130     **  category name      -  simplified result     Clarify Field         Var Field
00131     ** -------------------   -------------------   -------------------   ---------------------
00132     **  Person                person                personCfy             personVar
00133     **  Company               company               companyCfy            companyVar
00134     **  Calendar              calendar              calendarCfy           calendarVar
00135     **  New Opportunity       newOpportunity        newOpportunityCfy     newOpportunityVar
00136     **  Test Category         testCategory          testCategoryCfy       testCategoryVar
00137     **  A Category Name       aCategoryName         aCategoryNameCfy      aCategoryNameVar
00138     ** \endcode
00139     **
00140     ** There are some specific advantages for using names formatted thusly.  For instance
00141     **  if drag-and-drop is being employed on the calendar, then it is important
00142     **  to carefully structure your field names so that fields that are identically
00143     **  named between, say, People and Calendar are fields you WANT identically named.
00144     **  Because, if you drag a person from a People report on to a calendar, then a new
00145     **  calendar item will be created, and all identical fields and connections will be
00146     **  copied from the People category item to the Calendar category item.  This is fine
00147     **  for fields you want automatically copied, but it is rather problemmatic for fields
00148     **  you don't want copied such as ID fields and VAR fields and what-not.  Using the
00149     **  catNameKey/catNameCfy/catNameVar field naming convention prevents this sort of
00150     **  automatic copying for these critical internal fields.
00151     **
00152     */
00153     QString catName();
00154 
00155     /*!
00156     ** \brief Definition String \n
00157     **
00158     **
00159     */
00160     QString string();
00161 
00162     /*!
00163     ** \brief Maximum number of Items \n
00164     **
00165     ** This value always returns 500,000 since that is the upper limit of the 
00166     **  Commence category item count.
00167     **
00168     */
00169     long maxItems();
00170 
00171     /*!
00172     ** \brief Category 'Is Shared' flag \n
00173     **
00174     ** This indicates TRUE if the category is shared or FALSE if not.
00175     **
00176     */
00177     bool isShared();
00178 
00179     /*!
00180     ** \brief Category 'Allows Duplicates' flag \n
00181     **
00182     ** This indicates TRUE if the category allows duplicates or FALSE if not.
00183     **
00184     */
00185     bool duplicatesAllowed();
00186 
00187     /*!
00188     ** \brief Category 'has clarify' information \n
00189     **
00190     ** This indicates TRUE if the cateogy has clarify field information or FALSE
00191     **  if not.
00192     **
00193     */
00194     bool hasClarifyField();
00195 
00196     /*!
00197     ** \brief Has Clarify Field \n
00198     **
00199     */
00200     bool hasCfyField();
00201 
00202     /*!
00203     ** \brief Category 'has var' field \n
00204     **
00205     **
00206     */
00207     bool hasVarField();
00208 
00209     /*!
00210     ** \brief Return TRUE if this category has a cmcID field \n
00211     **
00212     **
00213     */
00214     bool hasThidField();
00215 
00216     /*!
00217     ** \brief Return TRUE if this category has a guid field \n
00218     **
00219     **
00220     */
00221     bool hasGuidField();
00222 
00223     /*!
00224     ** \brief Return the category Key Field Name \n
00225     **
00226     ** This is a short-hand function for getting the keyFieldName on the Form.  Every
00227     **  category always has a keyField - also known as the 'Name' field, and this
00228     **  function returns that field that IS the Name field.
00229     **
00230     ** \par vbScript Example:
00231     ** \code
00232     ** dim ddll: set ddll = createObject("DumontDLL")
00233     ** dim dfrm: set dfrm = ddll.Form(Form)
00234     ** dim oKFN:     oKFN = dfrm.keyFieldName
00235     ** msgbox "Field " & oKFN & " is " & dfrm.Field(oKFN).Value
00236     ** \endcode
00237     **
00238     ** \sa keyField, cfyField, varField
00239     */
00240     QString keyFieldName();
00241 
00242     /*!
00243     ** \brief Return the category Clarify field name \n
00244     **
00245     ** This returns the category Clarify field name.  Note that categories are not 
00246     **  required to have a clarify field - it's just a good idear, especially if
00247     **  the category allows duplicates, and in those cases the clarify field should
00248     **  certainly be set to something that allows one item to be distinguished from
00249     **  another.
00250     **
00251     ** The return value of this function will depend on a couple of conditions.
00252     **  Even if an actual, defined, clarify field does not exist for this category,
00253     **  it will attempt to find a possible clarify field by looking for the
00254     **  following fields in the following order:
00255     **
00256     **  \li -Defined Clarify Field-
00257     **  \li "Clarify"
00258     **  \li "catNameCfy"
00259     **
00260     ** For instance, first the category is checked for an actual defined clarify
00261     **  field.  If one is not found, then the field "Clarify" is searched for in
00262     **  the list of fields.  If that field is not found, then the special
00263     **  "catNameCfy" field is searched for in the list of fields.  The "catNameCfy"
00264     **  field is a special field that is developed from a composite of the
00265     **  category name plus the three letter extension "Cfy" using the catName() 
00266     **  function.  
00267     **
00268     **
00269     ** \par vbScript Example:
00270     ** \code
00271     ** dim ddll: set ddll = createObject("DumontDLL")
00272     ** dim dfrm: set dfrm = ddll.Form(Form)
00273     ** dim oCFN:     oCFN = dfrm.cfyFieldName
00274     ** msgbox "Field " & oCFN & " is " & dfrm.Field(oCFN).Value
00275     ** \endcode
00276     **
00277     */
00278     QString cfyFieldName();
00279 
00280     /*!
00281     ** \brief Clarify Field Name \n
00282     **
00283     */
00284     QString clarifyFieldName();
00285 
00286     /*!
00287     ** \brief Clarify Seperator \n
00288     **
00289     ** If this category has a clarify field defined, then this value will indicate the
00290     **  clarify field seperator.  This value is used when building 'clarified item'
00291     **  connections and settings.
00292     **
00293     */
00294     QString cfySeparator();
00295 
00296     /*!
00297     ** \brief Clarify Separator \n
00298     **
00299     */
00300     QString clarifySeparator();
00301 
00302     /*!
00303     ** \brief THID Field Name \n
00304     **
00305     **
00306     */
00307     QString thidFieldName();
00308     
00309     /*!
00310     ** \brief Set THID Field Name \n
00311     **
00312     **
00313     */
00314     void setThidFieldName( const QString & name );
00315     
00316     /*!
00317     ** \brief Reset THID Field Name \n
00318     **
00319     **
00320     */
00321     void rstThidFieldName();
00322 
00323     /*!
00324     ** \brief GUID Field Name \n
00325     **
00326     **
00327     */
00328     QString guidFieldName();
00329     
00330     /*!
00331     ** \brief Set GUID Field Name \n
00332     **
00333     **
00334     */
00335     void setGuidFieldName(const QString & name );
00336     
00337     /*!
00338     ** \brief Reset GUID Field Name \n
00339     **
00340     **
00341     */
00342     void rstGuidFieldName();
00343 
00344     /*!
00345     ** \brief Return the category Var field name \n
00346     **
00347     ** This returns the category Var field name.  This Var field is that special field
00348     **  that is used to extend the 100-field limit of the Commence categories.  This
00349     **  field should ALWAYS be a Memo type field so that a long, multi-line text value
00350     **  can be placed on it.
00351     **
00352     ** Dumont assumes the 'name' of this field is a programmed construct of the category
00353     **  name followed by the 'Var' extension.  For instance, if the category name is
00354     **  "Calendar", then the var field name would be "calendarVar".  If the category
00355     **  name is "Person", then the var field name would be "personVar".  And, if the 
00356     **  category name is "Rolodex Files", then the var field name would be 
00357     **  "rolodexFilesVar".  The purpose for this naming convention (besides being consistent)
00358     **  is to prevent field values from one category var field propagating to the 
00359     **  var field of another category on a drag/drop operation.  For instance, if a 
00360     **  person were to be dragged to the calendar, the entire contents of the var field
00361     **  would be dragged along with that item if both the calendar and person categories
00362     **  had their var field defined as "Var".  Therefore, var field names are distinguished
00363     **  for each category by name.
00364     **
00365     ** \par vbScript Example:
00366     ** \code
00367     ** dim oVFN:     oVFN = dfrm.varFieldName
00368     ** msgbox "Field " & dfrm.varFieldName & " is " & dfrm.Field(dfrm.varFieldName).Value
00369     ** \endcode
00370     **
00371     */
00372     QString varFieldName();
00373 
00374     /*!
00375     ** \brief Set VAR Field Name \n
00376     **
00377     **
00378     */
00379     void setVarFieldName( const QString & name );
00380 
00381     /*!
00382     ** \brief Reset VAR Field Name \n
00383     **
00384     **
00385     */
00386     void rstVarFieldName();
00387 
00388     /*!
00389     ** \brief Return if the category is published or not \n
00390     **
00391     ** Published categories are those that are included in XML export/import
00392     **  files.
00393     **
00394     */
00395     bool isPublished();
00396 
00397     /*!
00398     ** \brief Set Is Published \n
00399     **
00400     **
00401     */
00402     void setIsPublished( bool state );
00403 
00404     /*!
00405     ** \brief Reset Is Published \n
00406     **
00407     **
00408     */
00409     void rstIsPublished();
00410 
00411     long colCount();
00412     long columnCount();
00413 
00414     /*!
00415     ** \brief Get Field Defs collection \n
00416     **
00417     **
00418     */
00419     cmcFieldDefs * fieldDefs();
00420 
00421     /*!
00422     ** \brief Get a Field Def by Name \n
00423     **
00424     **
00425     */
00426     cmcFieldDef * fieldDef( const QString & name );
00427     cmcFieldDef * fieldDefs( const QString & name )
00428     { return( fieldDef(name) ); }
00429 
00430     /*!
00431     ** \brief Get a Field Def by Index \n
00432     **
00433     **
00434     */
00435     cmcFieldDef * fieldDef( long index );
00436     cmcFieldDef * fieldDefs( long index )
00437     { return( fieldDef(index) ); }
00438 
00439     /*!
00440     ** \brief Connection Defs collection \n
00441     **
00442     **
00443     */
00444     cmcConnectionDefs * connectionDefs();
00445 
00446     /*!
00447     ** \brief Get a Connection Def by Name \n
00448     **
00449     **
00450     */
00451     cmcConnectionDef * connectionDef( const QString & name );
00452     cmcConnectionDef * connectionDefs( const QString & name )
00453     { return( connectionDef(name) ); }
00454 
00455     /*!
00456     ** \brief Get a Connection Def by Index \n
00457     **
00458     **
00459     */
00460     cmcConnectionDef * connectionDef( long index );
00461     cmcConnectionDef * connectionDefs( long index )
00462     { return( connectionDef(index) ); }
00463 
00464     /*!
00465     ** \brief Form Defs collection \n
00466     **
00467     **
00468     */
00469     cmcFormDefs * formDefs();
00470 
00471     /*!
00472     ** \brief Get a Form Def by Name \n
00473     **
00474     **
00475     */
00476     cmcFormDef * formDef( const QString & name );
00477     cmcFormDef * formDefs( const QString & name )
00478     { return( formDef(name) ); }
00479 
00480     /*!
00481     ** \brief Get a Form Def by Index \n
00482     **
00483     **
00484     */
00485     cmcFormDef * formDef( long index );
00486     cmcFormDef * formDefs( long index )
00487     { return( formDef(index) ); }
00488 
00489 
00490 
00491 
00492     /*!
00493     ** \brief Form Defs collection \n
00494     **
00495     **
00496     */
00497     cmcViewDefs * viewDefs();
00498 
00499     /*!
00500     ** \brief Get a Form Def by Name \n
00501     **
00502     **
00503     */
00504     cmcViewDef * viewDef( const QString & name );
00505     cmcViewDef * viewDefs( const QString & name )
00506     { return( viewDef(name) ); }
00507 
00508     /*!
00509     ** \brief Get a Form Def by Index \n
00510     **
00511     **
00512     */
00513     cmcViewDef * viewDef( long index );
00514     cmcViewDef * viewDefs( long index )
00515     { return( viewDef(index) ); }
00516 
00517 
00518     /*!
00519     ** \brief Check for Connection Name \n
00520     **
00521     ** This returns TRUE when the FieldName provided is a connection field.  This
00522     **  helps to identify an object as a connection when all we have is a field name 
00523     **  as provided by the vbScript Form_onEnterField(FieldName) function.
00524     **
00525     ** \par vbScript Example:
00526     ** \code
00527     ** Sub Form_OnEnterField(ByVal FieldName)
00528     **   If( dfrm.isField(FieldName) ) then
00529     **     msgbox FieldName + " is a field"
00530     **   End If
00531     **   If( dfrm.isConnection(FieldName) ) then
00532     **     msgbox FieldName + " is a Connection"
00533     **   End If
00534     ** End Sub
00535     ** \endcode
00536     **
00537     ** \sa isField
00538     **
00539     */
00540     bool isConnection
00541     (
00542       QString fieldName
00543     );
00544 
00545     /*!
00546     ** \brief Check for Field Name \n
00547     **
00548     ** This takes a field name as a parameter and returns 'true' if the field name equates to
00549     **  an actual field in the category.  If the field name provided is a connection name, or
00550     **  is not listed then this function returns false.
00551     **
00552     ** \par vbScript Example:
00553     ** \code
00554     ** Sub Form_OnEnterField(ByVal FieldName)
00555     **   If( dfrm.isField(FieldName) ) then
00556     **     msgbox FieldName + " is a field"
00557     **   End If
00558     **   If( dfrm.isConnection(FieldName) ) then
00559     **     msgbox FieldName + " is a Connection"
00560     **   End If
00561     ** End Sub
00562     ** \endcode
00563     **
00564     ** \sa isConnection
00565     **
00566     */
00567     bool isField
00568     (
00569       QString fieldName
00570     );
00571 
00572 
00573 
00574 
00575   signals:
00576 
00577   protected:
00578 
00579   private:
00580 
00581     /*!
00582     ** \brief Static Definition \n
00583     **
00584     **
00585     */
00586     QStringList m_definition;
00587 
00588     /*!
00589     ** \brief Field Definiton Collection \n
00590     **
00591     **
00592     */
00593     QPointer<cmcFieldDefs> m_cmcFieldDefs;
00594 
00595     /*!
00596     ** \brief Connection Definition Collection \n
00597     **
00598     **
00599     */
00600     QPointer<cmcConnectionDefs> m_cmcConnectionDefs;
00601 
00602     /*!
00603     ** \brief Form Definition Collection \n
00604     **
00605     **
00606     */
00607     QPointer<cmcFormDefs> m_cmcFormDefs;
00608 
00609     /*!
00610     ** \brief View Definition Collection \n
00611     **
00612     **
00613     */
00614     QPointer<cmcViewDefs> m_cmcViewDefs;
00615 
00616 }; // endclass cmcCategoryDef
00617 
00618 } // namespace cmcDatabaseApi
00619 
00620 #endif // #ifndef CDA_CATEGORY_DEF_H_422FD07F_0597_4cbb_A034_9AE85166472E
00621 
 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