DumontEXE 0.0.1
cmcItem.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_CMC_ITEM_H_422FD07F_0597_4cbb_A034_9AE85166472E
00026 #define CDA_CMC_ITEM_H_422FD07F_0597_4cbb_A034_9AE85166472E
00027 
00028 #include <QObject>
00029 #include <QString>
00030 #include <QPointer>
00031 
00032 #include "cmcObject.h"
00033 #include "cmcApplication.h"
00034 #include "cmcCursor.h"
00035 #include "cmcRowSet.h"
00036 #include "cmcItemField.h"
00037 #include "cmcItems.h"
00038 
00039 namespace cmcDatabaseApi {
00040 
00041 class cmcItemField;
00042 class cmcItems;
00043 
00044 /*!
00045 ** \brief Commence Item
00046 **
00047 ** This object represents a single item in the Commence database.  This
00048 **  object uses symantics similar to the cmcForm object.  Fields
00049 **  values are accessed using the well recognized cmcField object, and
00050 **  connections are accessed using the well recognized cmcConnection
00051 **  object.  However, what this object is actually doing is accessing
00052 **  the item information using standard cursors and rowsets through
00053 **  the regular Commence API.
00054 **
00055 ** While this object uses the cmcCursor API to gain access to the
00056 **  Commence item data, it does not use related columns to get to
00057 **  connection data.  Instead, when a connection is requested, this
00058 **  object manufactures a list of cmcItem objects, whereby each
00059 **  object represents an item in the connection field.  This makes
00060 **  manipulating multiple items with multiple connections to 
00061 **  multiple items a breeze.  What should be noted, however is that
00062 **  the cmcItems collection is designed to reflect the well-known
00063 **  interface of the Form.Connection() interface.  This means that
00064 **  working with this new wrapper will be familiar.
00065 **
00066 ** Manipulating multiple items with multiple connections may be
00067 **  easy with this object, but it is not without penalties.  For
00068 **  instance, each cmcItem object opens a cursor on the requested
00069 **  item, and this cursor stays open the whole time the object is
00070 **  in existance.  Therefore, resources from the Commence database
00071 **  can be quickly consumed beyond functionality if too many items
00072 **  are opened at the same time.  The same is not quite true for
00073 **  connections, however.  When requesting a connection on an item
00074 **  a single cursor/rowset is opened for all connected items, and
00075 **  these individual items refer back to this common rowset.
00076 **
00077 */
00078 class cmcItem:
00079   public cmcObject
00080 {
00081   Q_OBJECT
00082   public:
00083 
00084     /*!
00085     ** \brief Copy Constructor \n
00086     **
00087     */
00088     cmcItem( const cmcItem & copy );
00089 
00090     /*!
00091     ** \brief General Constructor \n
00092     **
00093     */
00094     cmcItem
00095     (
00096       /*! string ~ category name */
00097       const QString & categoryName,
00098 
00099       /*! long ~ flags (defaults to zero) */
00100       long flags,
00101 
00102       /*! application ~ reference */
00103       cmcApplication * application,
00104 
00105       /*! object ~ parent */
00106       QObject * parent = NULL
00107 
00108     );
00109 
00110     /*!
00111     ** \brief Construct a commence item linked to a shared rowset \n
00112     **
00113     */
00114     cmcItem
00115     (
00116       /*! rowset ~ Pointer to originating rowset */
00117       cmcRowSet * rowset,
00118 
00119       /*! long ~ index number into rowset */
00120       long index,
00121 
00122       /*! application ~ pointer to originating application */
00123       cmcApplication * application,
00124 
00125       /*! object ~ parent object */
00126       QObject * parent = NULL
00127     );
00128 
00129     virtual ~cmcItem();
00130 
00131     /*!
00132     ** \brief Set Default Columns \n
00133     **
00134     ** This will set default columns on the cursor.  This insures that
00135     **  there are a few internal system columns that are always assigned
00136     **  to the item even if the user doesn't do it.  This eleviates
00137     **  the user from having to worry about internal columns.
00138     **
00139     */
00140     void setColumnDefault();
00141 
00142   public slots:
00143 
00144     /*!
00145     ** \brief Return the Category name of this Form \n
00146     **
00147     ** Return the category name that this form is associated with.
00148     **
00149     ** \par vbScript Example:
00150     ** \code
00151     **   dim cursor: set cursor = dfrm.DB.getCursor( 0, dfrm.categoryName, 0 )
00152     ** \endcode
00153     */
00154     QString categoryName();
00155 
00156     /*!
00157     ** \brief Return the Item Name text value \n
00158     **
00159     ** String, name of the current item. May be empty when adding an item and 
00160     **  the name field has not yet been entered.
00161     **
00162     ** \par vbScript Example:
00163     ** \code
00164     **   if( dfrm.ItemName = "Accounting Department" ) then
00165     **     msgbox "I was told there would be no math!"
00166     **   end if
00167     ** \endcode
00168     */
00169     QString itemName();
00170 
00171     /*!
00172     ** \brief Return the Item Clarify text value \n
00173     **
00174     ** \sa clarifyKey
00175     **
00176     */
00177     QString itemClarify();
00178 
00179     /*!
00180     ** \brief Return a Clarified Item Name \n
00181     **
00182     ** If this category uses clarified field values, then this function
00183     **  will return a properly formatted clarified item name.  If this
00184     **  category does not employ a clarify field, then just the key field
00185     **  value is returned.
00186     **
00187     ** When providing a Clarified Item Name value, you must pad the 'Name'
00188     **  field with spaces to equal 50 spaces, then append the clarify
00189     **  separator, and finally append the clarify field value.  This
00190     **  function takes care of all that automatically. 
00191     **
00192     ** \sa \ref clarifiedItemNames
00193     **
00194     ** \returns Clarified item name formatted string .or. just the item
00195     **           name if the category does not employ clarified item names.
00196     */
00197     QString clarifiedItemName
00198     (
00199       /*! bool ~ Full Pad Request, defaults to false.  A Full Pad means
00200                  that if the key/clarify combination is shorter than 
00201                  50 characters + seperator + 40 characters, then additional
00202                  spaces will be added to the field.  It is not clear at this
00203                  time if this extra pad space is necessary, but it is 
00204                  being implemented here just in case.  */
00205       bool fullPad = false
00206     );
00207 
00208     /*!
00209     ** \brief Return the keyField \n
00210     **
00211     ** Every category has a key field.  This is the same as the 'Name' field.  This method
00212     **  provides direct access to this name field.
00213     **
00214     ** \note This FieldName value defaults to 'catnameKey' - see the definition in the source
00215     **  code for clarification.
00216     **
00217     ** \par vbScript Example
00218     ** \code
00219     ** Sub DoSomething()
00220     **   dim oKey: set oKey = dfrm.keyField
00221     **   oKey.Value = "this is a test"      ' set the name field to "this is a test"
00222     ** End Sub
00223     ** \endcode
00224     **
00225     */
00226     cmcItemField * keyField();
00227 
00228     /*!
00229     ** \brief Return the clarifyField \n
00230     **
00231     ** 
00232     **
00233     ** \par vbScript Example
00234     ** \code
00235     ** Sub DoSomething()
00236     **   dim oCfy: set oCfy = dfrm.cfyField
00237     **   oCfy.Value = "this is a test"      ' set the clarify field to "this is a test"
00238     ** End Sub
00239     ** \endcode
00240     */
00241     cmcItemField * cfyField();
00242 
00243     /*!
00244     ** \brief Return the varField \n
00245     **
00246     ** The varField is a memo field that is designated as part of the 
00247     **  100-field-limit extension project.  Typically the var field name
00248     **  is comprised from the category Name plus "Var".  For instance,
00249     **  examples include; calendarVar, personVar, projectVar, matterVar...
00250     **  and so on.
00251     **
00252     ** \par vbScript Example
00253     ** \code
00254     ** Sub DoSomething()
00255     **   dim oVar: set oVar = dfrm.varField
00256     **   oVar.var("cmcID") = "12345"      ' set the cmcID element in var to "12345"
00257     **   oVar.var("dateOn") = now
00258     ** End Sub
00259     ** \endcode
00260     **
00261     */
00262     cmcItemField * varField();
00263 
00264     /*!
00265     ** \brief Return the guid field \n
00266     **
00267     ** The guid field is a special field defined in the category that can be used
00268     **  to store a guid of this item.  It should be a text(40) field.  It can be
00269     **  indexed and/or used as a clarify field to aid in the identification
00270     **  of items by ID.  If this field exists in the category definition then the
00271     **  guid will *not* be stored in the varField() if it also exists.
00272     **
00273     ** \sa guid, thidField, varField
00274     */
00275     cmcItemField * guidField();
00276 
00277     /*!
00278     ** \brief return the cmcID field \n
00279     **
00280     ** The cmcID field is a special field defined in the category that can be used
00281     **  to store the cmcID of this item.  It should be a text(20) field.  It can be
00282     **  indexed and/or used as a clarify field to aid in the identification
00283     **  of items by ID.  If this field exists in the category definition then the
00284     **  cmcID will *not* be stored in the varField() if it also exists.
00285     **
00286     ** \sa cmcID, guidField, varField
00287     */
00288     cmcItemField * thidField();
00289 
00290     /*!
00291     ** \brief Return the cmcID of this item \n
00292     **
00293     ** This function returns the currently assigned itemThid (THID) of this item.  Please
00294     **  note that this function ONLY works when this category contains an actual
00295     **  varField field where the \c THID can be stored .AND. this form is .NOT.
00296     **  in "isAdd == True" mode.  Both of those conditions must be true to get
00297     **  at the \c THID value for this item.  If not, then "unknown" is returned
00298     **  instead.
00299     **
00300     ** Alternatively, if you do not want to have the THID stored in a varField()
00301     **  type of field, you can define a field "thid Text(20)" (a 20-character
00302     **  text field called "cmcID") in the category and then the THID will be
00303     **  automatically stored there.  This can have the advantage of using the
00304     **  cmcID field as the clarify field and creating an index for it and so
00305     **  on.  The disadvantage of using a cmcID field as a clarify field is the
00306     **  cmcID field then shows up in the Tools|Global Search results and also
00307     **  shows up in some other places... and that may be undesirable.
00308     **
00309     ** One thing to note about the cmcID value is that not only is it not available
00310     **  until a new item has been saved to disk, but the cmcID value is actually
00311     **  not portable across multiple databases.  For instance, if an item is
00312     **  moved from one database to another, then even though, technically the
00313     **  cmcID is likely to still be unique, it does not necessarily represent
00314     **  the correct actual cmcID value of that item - simply because it was
00315     **  exported from one database and imported into another.  For this reason,
00316     **  and probably others that haven't been completely realized yet, the 
00317     **  cmcID valus is of marginal value, and probably should not be relied
00318     **  on in a production database.  Instead, the guid() value should be used
00319     **  when trying to uniquely identify items in Commence.
00320     **
00321     ** \par vbScript Example:
00322     ** \code
00323     ** msgbox dfrm.itemThid ' shows '4:80006401:0000365E'
00324     ** \endcode
00325     **
00326     ** \sa guid
00327     */
00328     QString itemThid();
00329 
00330     /*!
00331     ** \brief Extended Field \n
00332     **
00333     **
00334     */
00335     cmcSubField * extField( QString fieldName );
00336 
00337     /*!
00338     ** \brief Return the guid of this item \n
00339     **
00340     ** This function returns the currently assigned guid of this item, or a 
00341     **  new guid for this item if one does not exist yet.
00342     **
00343     ** In order for this function to work properly, there must be a varField() 
00344     **  defined for this category or a special guid field.  If there is no 
00345     **  varField() then this function returns
00346     **  the string value of "nothing".
00347     **
00348     ** If the varField() exists but no guid has been assigned, then this 
00349     **  function will create a new guid value and cause it to be automatically
00350     **  stored in the varField().  The advantage of using this guid function
00351     **  over the itemThid() function is that this value can be generated immediately
00352     **  for new items before they are saved to the category, wheras the itemThid()
00353     **  value is only available after the item has been saved.  Once a guid is
00354     **  generated for an item, because it is stored in the varField() it will
00355     **  remain static and unique for that particular item for the life of that item.
00356     **
00357     ** Alternatively, if you do not want to have the guid stored in a varField()
00358     **  type of field, you can define a field "guid Text(40)" (a 40-character
00359     **  text field called "catNameGuid") in the category and then the guid will be
00360     **  automatically stored there.  This can have the advantage of using the
00361     **  guid field as the clarify field and creating an index for it and so
00362     **  on.  The disadvantage of using a guid field as a clarify field is the
00363     **  guid field then shows up in the Tools|Global Search results and also
00364     **  shows up in some other places... and that may be undesirable.
00365     **
00366     ** \note One pecularity with this method of item identification is that it
00367     **  is all hapening 'outside' of the Commence database engine as a post-process.
00368     **  This means these methods are not without their pitfalls.  One comes from
00369     **  the menu item "Edit | Copy Item".  This menu option causes a new commence 
00370     **  item to be created from an existing one, meaning all the contents of the var
00371     **  field are copied as well.  This is potentially problemmatic because some
00372     **  of this 'item management' code depends on 'initial values' in this var
00373     **  field and other fields.  Extra steps have been taken to insure that
00374     **  the itemThid() and itemGuid() values are unique per item, but care should be
00375     **  taken by the database administrator to insure that things are working
00376     **  as expected.  Especially when the var field is used to store other 
00377     **  values outside the scope of the DumontDLL.
00378     **
00379     ** \par vbScript Example:
00380     ** \code
00381     ** msgbox dfrm.guid ' shows '{623316da-e9cc-4f42-a9fb-f2938920dcb5}'
00382     ** \endcode
00383     **
00384     ** \sa itemThid
00385     */
00386     QString itemGuid();
00387 
00388     /*!
00389     ** \brief Return true/false if this form is in Add Mode \n
00390     **
00391     ** This pass-through function returns true/false if the form is in add mode.
00392     **
00393     ** \par vbScript Example:
00394     ** \code
00395     ** \endcode
00396     */
00397     bool isAdd(); // dispid = 0x07
00398 
00399     /*!
00400     ** \brief Return true/false is the form is in Delete mode \n
00401     **
00402     ** This function returns the delete flag on the form.  The delete flag
00403     **  gets set when the deleteItem() function is called.
00404     **
00405     **
00406     */
00407     bool isDelete();
00408 
00409     /*!
00410     ** \brief Return true/false if this item is shared \n
00411     **
00412     ** This pass-through function returns true/false if the form item is currently
00413     **  shared.
00414     **
00415     ** \par vbScript Example:
00416     ** \code
00417     ** \endcode
00418     */
00419     bool isShared();
00420 
00421     /*!
00422     ** \brief Set the shared flag on the form \n
00423     **
00424     ** This sets and resets the form/item Shared value
00425     **
00426     ** \par vbScript Example
00427     ** \code
00428     ** Sub MakeItemShared()
00429     **   dfrm.setShared True
00430     ** End Sub
00431     **
00432     ** Sub MakeItemUnshared()
00433     **   dfrm.setShared False
00434     ** End Sub
00435     ** \endcode
00436     **
00437     */
00438     void setShared
00439     (
00440       bool state
00441     );
00442 
00443     /*!
00444     ** \brief Delete the Item \n
00445     **
00446     ** This function executes a specially tailored delete type of method
00447     **  on this item.  This is not just a regular item delete like what
00448     **  you get when you hit ctrl-D on a form or a view.  This deletion
00449     **  function is designed to provide tracability and recoverability
00450     **  (as in 'undelete') on deleted items.
00451     **
00452     ** In order for this method to work properly several things have to be 
00453     **  available to Dumont.  First, the item has to have a varField where 
00454     **  deletion info can be stored.  The type of info that gets stored
00455     **  there is as follows:
00456     **
00457     ** \code
00458     ** deletedOn=20071114074022           ' date and time of the deletion
00459     ** deletedBy=MWP:80011002:00223233    ' who requested the deletion
00460     ** \endcode
00461     **
00462     ** When an item is stamped in this fashion it can be easily filtered
00463     **  from various views by adding a "varField Does Not Contain deletedOn"
00464     **  type of filter.  This gives the operator the illusion that the
00465     **  item has actually been deleted from his computer. The downside of 
00466     **  this implementation is that it requires an extra filter be added
00467     **  to all your views and connections in order for them to appear
00468     **  proper to the user.  Also, this requires that the user has write
00469     **  permissions on this particular item.
00470     **
00471     ** But, even if the user does not have write permissions over this particular
00472     **  item, in parallel with stamping the item with deletion info, a changeLog 
00473     **  item is also generated for the deletion request.  Note, I say request 
00474     **  because once the server gets a hold of it, the server may decide this 
00475     **  item shouldn't be deleted afterall - that implementation is left up to 
00476     **  the system integrator (that's the *you* part of this relationship).
00477     **
00478     ** If the user does not have write permissions on the item, then no
00479     **  deletion stamping will be performed on it, and the item will remain
00480     **  in his views.  However, a changeLog item will still be created and
00481     **  saved, and when the server picks up the changeLog deletion request
00482     **  and decides to delete the item anyway then eventually when the
00483     **  user syncs with the workgroup the item will disappear.  This actually
00484     **  allows users to delete items they don't have write permissions on,
00485     **  and there is a trace-log of the deletion!  Nice, eh?
00486     **
00487     ** Here is an actual example of a change log that was generated on an item
00488     **  deletion request.
00489     **
00490     ** \par example changeLog item:
00491     ** \code
00492     ** <!DOCTYPE changeLog>
00493     ** <changeLog version="3.8.98.3" formName="Docket General" action="Delete" categoryName="Calendar" >
00494     **    <itemName>Petryk.M/lit2</itemName>
00495     **    <logOn>20071114112236</logOn>
00496     **    <logBy>MWP:7:80006401:000026F7</logBy>
00497     **    <cmcID>nothing</cmcID>
00498     **    <guid>{55028c01-4b13-4718-9681-c8b832d55360}</guid>
00499     **    <field name="calendarVar" >
00500     **       <from>cmcID=nothing&#xd;
00501     ** guid={55028c01-4b13-4718-9681-c8b832d55360}&#xd;
00502     ** createdOn=20071114112228&#xd;
00503     ** createdBy=MWP:7:80006401:000026F7&#xd;
00504     ** changedOn=20071114112228&#xd;
00505     ** changedBy=MWP:7:80006401:000026F7&#xd;
00506     ** dragFrom=20071118080000&#xd;
00507     ** mdd=0001200711180020110000</from>
00508     **       <to>cmcID=nothing&#xd;
00509     ** guid={55028c01-4b13-4718-9681-c8b832d55360}&#xd;
00510     ** createdOn=20071114112228&#xd;
00511     ** createdBy=MWP:7:80006401:000026F7&#xd;
00512     ** changedOn=20071114112228&#xd;
00513     ** changedBy=MWP:7:80006401:000026F7&#xd;
00514     ** dragFrom=20071118080000&#xd;
00515     ** mdd=0001200711180020110000&#xd;
00516     ** deletedOn=20071114112236&#xd;
00517     ** deletedBy=MWP:7:80006401:000026F7</to>
00518     **    </field>
00519     ** </changeLog>
00520     ** \endcode
00521     **
00522     ** There is enough information in this change log item to be able to 
00523     **  locate the originating source item and user that made the request 
00524     **  for deletion.
00525     **
00526     ** None-the-less, varField or not, this function is designed to tag 
00527     **  the item appropriately so that it may be deleted responsibly, by 
00528     **  the server, or some other authorized administrator.  And, if you
00529     **  set the server up properly then you can archive your items off 
00530     **  in some sort of a historical storage for later retrieval if the
00531     **  users desire.
00532     **
00533     ** The second thing that is required for this 'service' to function
00534     **  properly is the guid() method within Dumont.  This method must
00535     **  be functioning properly so that a unique guid for this item can be
00536     **  generated and made available to the rest of the system.  Yes, I
00537     **  know its possible to build a system that does not require guid's,
00538     **  and you should be able to use this item deletion feature without
00539     **  them, but, frankly, the pitfalls of implementing such a system
00540     **  are great.  For instance, say your category does not allow 
00541     **  duplicates, but certainly allows changes.  Now, someone wants
00542     **  an item deleted, and you are using the 'Name' field to track the
00543     **  item (since it's unique, right?).  You delete the item, a log is
00544     **  created on the 'Name' field, and you're done.  Meanwhile, on or
00545     **  about the same time, someone else changes the 'Name' value of this
00546     **  item.  Their 'sync' packet makes it to the server first so it
00547     **  goes ahead and changes the item name.  Then your packet comes in
00548     **  and requests the item be deleted, but it does it by 'Name' value,
00549     **  right?  See the problem?  The server can't delete the item or 
00550     **  archive it or anything because it can't find it because the name
00551     **  has changed!  Bottom line?  Use the guid() feature of the Dumont
00552     **  project.  It's easy and it will make your life happy, and you'll
00553     **  be rewarded with a new house and a nice car a wonderful spouse
00554     **  and a dog that actually listens to you.  I have all these things
00555     **  and it's because I started using guid's on all my Commence items...
00556     **  really, really!
00557     **
00558     ** Keep in mind that all that is happening here is the item is being
00559     **  *tagged* for deletion.  The actual item deletion occurs on the server
00560     **  where the entire process can be controlled.
00561     **
00562     */
00563     bool deleteItem();
00564 
00565     /*!
00566     ** \brief Cause the form to Save \n
00567     **
00568     ** This executes the Save operation on the form.
00569     **
00570     ** \par vbScript Example:
00571     ** \code
00572     ** \endcode
00573     */
00574     bool save();
00575 
00576     /*!
00577     ** \brief Report if any field or connection on the form is dirty or not \n
00578     **
00579     ** This function loops through all the fields and connections on 
00580     **  the form and reports true if any of them have been changed from 
00581     **  their original values.
00582     **
00583     ** \par vbScript Example:
00584     ** \code
00585     ** if( dfrm.isDirty ) then
00586     **   msgbox "the following changes are: " & dfrm.changeLog
00587     ** end if
00588     ** \endcode
00589     */
00590     bool isDirty();
00591 
00592     /*!
00593     ** \brief Restore a form back to its original state \n
00594     **
00595     ** This performs an 'undo' on all Fields and Connections.  It loops through each
00596     **  field and each connection and calls their respective undo().
00597     **
00598     ** \par vbScript Example:
00599     ** \code
00600     ** \endcode
00601     */
00602     void undo();
00603 
00604     /*!
00605     ** \brief Return the forms category definition \n
00606     **
00607     **
00608     */
00609     cmcCategoryDef * categoryDef();
00610 
00611     /*!
00612     ** \brief Get a Field object by Name \n
00613     **
00614     ** \note This object does *not* fail if an improper field name is provided.  Rather,
00615     **  it returns an object that is missing its field-object pointer.  The object
00616     **  that gets returned can be tested for validity using the isValid() function call.
00617     **
00618     ** \par vbScript Example ~ Fetching a field by name
00619     ** \code
00620     ** sub FixFieldInfo()
00621     **   dim oFName: set oFName = dfrm.field("First Name")
00622     **   dim oLName: set oLName = dfrm.field("Last Name")
00623     **   dim oBName: set oBName = dfrm.field("Bad Field Name")
00624     **
00625     **   if( oFName is nothing ) then msgbox "First Name is: " & oFName.value else msgbox "Bad Field Name"
00626     **   if( oLName is nothing ) then msgbox "Last Name is: "  & oLName.value else msgbox "Bad Field Name"
00627     **   if( oBName is nothing ) then msgbox "Bad Name is: "   & oFName.value else msgbox "Bad Field Name"
00628     ** end sub
00629     ** \endcode
00630     **
00631     ** \return \ref cmcItemField "Field" object from the form collection
00632     */
00633     cmcItemField * field
00634     (
00635       const QString & fieldName
00636     );
00637 
00638     /*!
00639     ** \brief Field Alias \n
00640     **
00641     **
00642     */
00643     cmcItemField * fld
00644     (
00645       const QString & fieldName
00646     );
00647 
00648     /*!
00649     ** \brief Field by Index \n
00650     **
00651     **
00652     */
00653     cmcItemField * field
00654     (
00655       long index
00656     );
00657 
00658     /*!
00659     ** \brief Field by Index \n
00660     **
00661     **
00662     */
00663     cmcItemField * fld
00664     (
00665       long index
00666     );
00667 
00668     /*!
00669     ** \brief Get a Items Collection by name \n
00670     **
00671     ** This function returns an cmcItems collection by name.  This 
00672     **  function is designed to act just like the Form.Connection
00673     **  function except it returns an object that manipulates 
00674     **  connection-related items through the cursor/rowset.  It
00675     **  makes manipulating connection items a breeze.
00676     **
00677     ** \par vbScript Example ~ manipulating connection items
00678     ** \code
00679     ** Sub FormatReport( PrimaryItemName )
00680     **
00681     **   dim retVal: 
00682     **   retVal = "Generated Report" & vbCrLf & _
00683     **            "----------------"
00684     **
00685     **   dim primaryItem
00686     **   set primaryItem = dapp.db.getItem( "Calendar", PrimaryItemName )
00687     **
00688     **   dim attendees
00689     **   set attendees = primaryItem.connection( "Attendees", "Contacts", "Attends" )
00690     **
00691     **   dim i: for i = 0 to attendees.count - 1
00692     **
00693     **     dim attendee
00694     **     set attendee = attendees.item(i)
00695     **
00696     **     '
00697     **     ' List some basic contact info
00698     **     '
00699     **     retVal = retVal & vbCrLf & _
00700     **       "Attendee: " & attendee.field("Full Name").value & vbCrLf & _
00701     **       "Position: " & attendee.field("Position").value  & vbCrLf & _
00702     **       "Phone:    " & attendee.field("Primary Phone").value
00703     **
00704     **     '
00705     **     ' Get some employer info
00706     **     '
00707     **     dim employer
00708     **     set employer = attendee.connection( "Employed by", "Company", "Employs" )
00709     **     if( employer.count > 0 ) then
00710     **       retVal = retVal & vbCrLf & _
00711     **         "Employer: " & employer.item(0).field("Company Name").value & vbCrLf & _
00712     **         "Website:  " & employer.item(0).field("Website").value
00713     **     end if
00714     **
00715     **     '
00716     **     ' Get other projects this attendee is working on
00717     **     '
00718     **     dim projects
00719     **     set projects = attendee.connection( "Working on", "Projects", "Working" )
00720     **     dim j: for j = 0 to projects.count - 1
00721     **       retVal = retVal & vbCrLf & _
00722     **         "Project Name: " & projects.item(j).field("Project Name").value & vbCrLf & _
00723     **         "Due Date:     " & projects.item(j).field("Due Date").value     & vbCrLf & _
00724     **         "Target Value: " & projects.item(j).field("Target Value").value
00725     **     next
00726     **
00727     **   next
00728     **
00729     ** End Sub ' FormatReport()
00730     ** \endcode
00731     */
00732     cmcItems * connection
00733     (
00734       const QString & connectionName,
00735       const QString & targetCategoryName,
00736       const QString & reverseConnectionName = ""
00737     );
00738 
00739     /*!
00740     ** \brief get Items collection by name \n
00741     **
00742     **
00743     */
00744     cmcItems * con
00745     (
00746       const QString & connectionName,
00747       const QString & targetCategoryName,
00748       const QString & reverseConnectionName = ""
00749     );
00750 
00751     /*!
00752     ** \brief Get a Connection by its "FieldName" \n
00753     **
00754     ** This is an overloaded function to return a cmcConnection when all we have is
00755     **  the "FieldName" as it is provided by the vbScript Form_onEnterField(FieldName) function
00756     **  call.  Normally when dealing with Form Events, all that is provided is a FieldName
00757     **  value which can represent a connection field or a standard text field.  The
00758     **  application (code) has to try to determine which one it is.  Dumont has the
00759     **  built-in services to make this an easy task.  It is possible to pass that simple
00760     **  FieldName value to the connection method and receive a \ref cmcConnection 
00761     **  connection object.
00762     **
00763     ** What this function also makes available is the ability to set field and connection names
00764     **  using the vbScript 'Const' keyword.  Both field names and connection names can be
00765     **  declared this way and then used to reference the connection by name.  This can have
00766     **  the advantage of really cleaning up a bunch of code redundancies.
00767     **
00768     ** \par vbScript Example:
00769     ** \code
00770     ** '
00771     ** ' These declarations were formerly not possible because the .connection.
00772     ** '  object required two parameters.
00773     ** '
00774     ** Const FN_KEY      = "contactsKey"
00775     ** Const FN_CFY      = "contactsCfy"
00776     ** Const FN_FIRST    = "First Name"
00777     ** Const FN_LAST     = "Last Name"
00778     ** Const FN_PHONE    = "Main Phone"
00779     ** Const CN_EMPLOYER = "Employed by Company"
00780     ** Const FN_EMPLKEY  = "companyKey"
00781     ** Const FN_BUSPHONE = "Business Phone"
00782     **
00783     ** Sub Form_OnEnterField(ByRef FieldName)
00784     **   '
00785     **   ' Do the Dumont OnEnterField stuff
00786     **   '
00787     **   dfrm.onEnterField FieldName
00788     **
00789     **   '
00790     **   ' If this is a connection object then deal with it
00791     **   '
00792     **   if( dfrm.isConnection(FieldName) ) then
00793     **     dim conn: set conn = dfrm.connection(FieldName)
00794     **     msgbox "You have " & conn.ConnectedItemCount & " connected items"
00795     **
00796     **     '
00797     **     ' Use the Const values to access the controls
00798     **     '
00799     **     dfrm.field(FN_KEY).value = _
00800     **       dfrm.field(FN_LAST)   & ", "   & _
00801     **       dfrm.field(FN_FIRST)  & " of " & _
00802     **       dfrm.connection(CN_EMPLOYER).fieldValue(FN_EMPLKEY) ' note: connection referred by NAME
00803     **
00804     **     dfrm.field(FN_PHONE).value = _
00805     **       dfrm.connection(CN_EMPLOYER).fieldValue(FN_BUSPHONE) ' note: connection referred by NAME
00806     **
00807     **   end if
00808     ** End Sub
00809     ** \endcode
00810     **
00811     ** \sa \ref cmcConnectionDefs "ConnectionDefs", \ref cmcConnection "Connection", isConnection, isField
00812     */
00813     cmcItems * connection
00814     (
00815       const QString & conCatName
00816     );
00817 
00818     /*!
00819     ** \brief Get a Connection by its "FieldName" \n
00820     **
00821     ** This is an alias function for obtaining a regular Connection field.  It is 
00822     **  intended to make the code a little more readable.
00823     **
00824     ** \par vbScript Example
00825     ** \code
00826     ** Sub Form_OnEnterField(ByRef FieldName)
00827     **   dim oxEmployee: set oxEmployee = dfrm.con("pRD Employee")
00828     ** End Sub
00829     ** \endcode
00830     **
00831     */
00832     cmcItems * con
00833     (
00834       const QString & conCatName
00835     );
00836 
00837     cmcItems * connection
00838     (
00839       long index
00840     );
00841 
00842     /*!
00843     ** \brief Check for Connection Name \n
00844     **
00845     ** This returns TRUE when the FieldName provided is a connection field.  This
00846     **  helps to identify an object as a connection when all we have is a field name 
00847     **  as provided by the vbScript Form_onEnterField(FieldName) function.
00848     **
00849     ** \par vbScript Example:
00850     ** \code
00851     ** Sub Form_OnEnterField(ByVal FieldName)
00852     **   If( dfrm.isField(FieldName) ) then
00853     **     msgbox FieldName + " is a field"
00854     **   End If
00855     **   If( dfrm.isConnection(FieldName) ) then
00856     **     msgbox FieldName + " is a Connection"
00857     **   End If
00858     ** End Sub
00859     ** \endcode
00860     **
00861     ** \sa isField
00862     **
00863     */
00864     bool isConnection
00865     (
00866       const QString & fieldName
00867     );
00868 
00869     /*!
00870     ** \brief Check for Field Name \n
00871     **
00872     ** This takes a field name as a parameter and returns 'true' if the field name equates to
00873     **  an actual field in the category.  If the field name provided is a connection name, or
00874     **  is not listed then this function returns false.
00875     **
00876     ** \par vbScript Example:
00877     ** \code
00878     ** Sub Form_OnEnterField(ByVal FieldName)
00879     **   If( dfrm.isField(FieldName) ) then
00880     **     msgbox FieldName + " is a field"
00881     **   End If
00882     **   If( dfrm.isConnection(FieldName) ) then
00883     **     msgbox FieldName + " is a Connection"
00884     **   End If
00885     ** End Sub
00886     ** \endcode
00887     **
00888     ** \sa isConnection
00889     **
00890     */
00891     bool isField
00892     (
00893       const QString & fieldName
00894     );
00895 
00896     /*!
00897     ** \brief Retrieve the Change Log string from this form \n
00898     **
00899     ** \par vbScript Example:
00900     ** \code
00901     ** \endcode
00902     **
00903     ** \sa \ref ChangeLogEngine
00904     */
00905     QString changeLog();
00906 
00907     /*!
00908     ** \brief Get the Change Log category Definition \n
00909     **
00910     ** This is an internal function that will seek-out the change log category
00911     **  definition and verify it for compatibility.  If the category definition
00912     **  looks good then a pointer to it is returned.  If it does not look good
00913     **  then a message window is opened with a few details of the problem.
00914     **
00915     */
00916     cmcRowSet * getChangeLogAddRowSet();
00917 
00918     /*!
00919     ** \brief Item Cursor \n
00920     **
00921     */
00922     cmcCursor * cursor();
00923 
00924     long setColumn( const QString & fieldName );
00925 
00926     /*!
00927     ** \brief Set a Connection \n
00928     **
00929     ** This sets the connection on this item.
00930     **
00931     */
00932     long setColumn
00933     (
00934       /*! string ~ Forward Connection Name */
00935       const QString & connectionName,
00936 
00937       /*! string ~ Target Category Name */
00938       const QString & categoryName,
00939 
00940       /*! string ~ Reverse Connection Name */
00941       const QString & fieldName = ""
00942     );
00943 
00944     /*!
00945     ** \brief Item Edit Row Set \n
00946     **
00947     **
00948     */
00949     cmcRowSet * rowset();
00950 
00951     /*!
00952     ** \brief Load an Item by Key value \n
00953     **
00954     */
00955     bool loadByKey( const QString & itemKey );
00956 
00957 
00958     /*!
00959     ** \brief Load by Guid \n
00960     **
00961     **
00962     */
00963     bool loadByGuid
00964     (
00965       /*! string ~ item guid */
00966       const QString & itemGuid
00967     );
00968 
00969     /*!
00970     ** \brief Load an item by field value \n
00971     **
00972     **
00973     */
00974     bool loadByField
00975     (
00976       /*! string ~ field name \n\n */
00977       const QString & fieldName,
00978 
00979       /*! string ~ qualifier \n\n */
00980       const QString & qualifier,
00981 
00982       /*! string ~ field value \n\n */
00983       const QString & value,
00984 
00985       /*! bool ~ Not Flag (default to false) \n\n */
00986       bool notFlag = false,
00987 
00988       /*! bool ~ Case Sensitivity (defaults to false) \n\n */
00989       bool caseSensitive = false
00990     );
00991 
00992     long row();
00993 
00994   private:
00995 
00996     long m_isDirty;
00997     long m_isShared;
00998     long m_isAdd;
00999     long m_flags;
01000 
01001     QPointer<cmcCursor> m_cursor;
01002     QPointer<cmcRowSet> m_rowset;
01003 
01004     long m_row;
01005 
01006     /*!
01007     ** \brief Form.CategoryName cache Value \n
01008     **
01009     */
01010     QString m_categoryName;
01011 
01012     bool m_isDelete;
01013 
01014     /*!
01015     ** \brief categoryDef pointer cache \n
01016     **
01017     */
01018     QPointer<cmcCategoryDef> m_categoryDef;
01019 
01020 }; // endclass cmcItem:
01021 
01022 } // endnamespace cmcDatabaseApi
01023 
01024 #endif // #ifndef CDA_ERROR_H
01025 
 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