DumontEXE 0.0.1
cmcForm.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_FORM_H_422FD07F_0597_4cbb_A034_9AE85166472E
00026 #define CDA_FORM_H_422FD07F_0597_4cbb_A034_9AE85166472E
00027 
00028 #include "cmcApi.h"
00029 #include "cmcApplication.h"
00030 
00031 namespace cmcDatabaseApi {
00032 
00033 class cmcDateDialog;
00034 class cmcFormField;
00035 class cmcConnection;
00036 class cmcFormControl;
00037 class cmcRuntime;
00038 class cmcMeInfo;
00039 class cmcActiveViewInfo;
00040 class cmcMultiDateDialog;
00041 
00042 /*!
00043 ** \brief Form \n
00044 **
00045 ** This object wraps a regular Commence form.
00046 **
00047 ** \par Standard Commence Form Properties
00048 ** \li \ref name()                   "Name"
00049 ** \li \ref categoryName()           "CategoryName"
00050 ** \li \ref itemName()               "ItemName"
00051 ** \li \ref tabName()                "TabName"
00052 ** \li \ref fieldName()              "FieldName"
00053 ** \li \ref cmcObject::application() "Application"
00054 ** \li \ref isAdd()                  "IsAdd"
00055 ** \li \ref isShared()               "IsShared"
00056 ** \li \ref fieldValue()             "FieldValue"
00057 **
00058 ** \par Standard Commence Form Methods
00059 ** \li \ref moveToTab()              "MoveToTab"
00060 ** \li \ref moveToField()            "MoveToField"
00061 ** \li \ref setShared()              "SetShared"
00062 ** \li \ref save()                   "Save"
00063 ** \li \ref cancel()                 "Cancel"
00064 ** \li \ref abort()                  "Abort"
00065 ** \li \ref setValue()               "SetValue"
00066 ** \li \ref field()                  "Field"
00067 ** \li \ref connection()             "Connection"
00068 **
00069 ** \par Standard Commence Form Events
00070 ** \li \ref onLoad()                 "OnLoad"
00071 ** \li \ref onSave()                 "OnSave"
00072 ** \li \ref onCancel()               "OnCancel"
00073 ** \li \ref onEnterTab()             "OnEnterTab"
00074 ** \li \ref onLeaveTab()             "OnLeaveTab"
00075 ** \li \ref onEnterField()           "OnEnterField"
00076 ** \li \ref onLeaveField()           "OnLeaveField"
00077 ** \li \ref onEnterControl           "OnEnterControl"
00078 ** \li \ref onLeaveControl           "OnLeaveControl"
00079 ** \li \ref onActiveXControlEvent    "OnActiveXControlEvent"
00080 ** \li \ref onClick                  "OnClick"
00081 ** \li \ref onChange                 "OnChange"
00082 ** \li \ref onKeyPress               "OnKeyPress"
00083 **
00084 ** \par Enhanced Form Properties and Methods
00085 ** \li \ref backColor()              "BackColor"
00086 ** \li \ref caption()                "Caption"
00087 ** \li \ref categoryDef()            "CategoryDef"
00088 ** \li \ref cfyField()               "CfyField"
00089 ** \li \ref changeConnection()       "ChangeConnection"
00090 ** \li \ref changeField()            "ChangeField"
00091 ** \li \ref changeLog()              "ChangeLog"
00092 ** \li \ref deleteItem()             "DeleteItem"
00093 ** \li \ref fld()                    "Fld"
00094 ** \li \ref guidField()              "GuidField"
00095 ** \li \ref isConnection()           "IsConnection"
00096 ** \li \ref isDirty()                "IsDirty"
00097 ** \li \ref isField()                "IsField"
00098 ** \li \ref isPrevNext()             "IsPrevNext"
00099 ** \li \ref itemClarify()            "ItemClarify"
00100 ** \li \ref itemGuid()               "ItemGuid"
00101 ** \li \ref itemThid()               "ItemThid"
00102 ** \li \ref keyField()               "KeyField"
00103 ** \li \ref meInfo()                 "MeInfo"
00104 ** \li \ref multiDateDialogExec()    "MultiDateDialogExec"
00105 ** \li \ref thidField()              "ThidField"
00106 ** \li \ref undo()                   "Undo"
00107 ** \li \ref varField()               "VarField"
00108 **
00109 */
00110 class cmcForm:
00111   public cmcApi
00112 {
00113   Q_OBJECT
00114 //  Q_CLASSINFO( "DestroyObject", "yes" )
00115   public:
00116 
00117     cmcForm( const cmcForm & copy );
00118 
00119     cmcForm
00120     (
00121       IDispatch * dispatch,
00122       cmcApplication * application = NULL,
00123       QObject * parent = NULL
00124     );
00125 
00126     virtual ~cmcForm();
00127 
00128     /*!
00129     ** \brief Return a new multi-date dialog \n
00130     **
00131     ** This method returns a pointer to the form's multi-date dialog.  If a multidate
00132     **  dialog has not been manufactured then one is created for return.  If one has 
00133     **  already been created then that same pointer is returned.  This way only one 
00134     **  multidate dialog object gets created per form.
00135     **
00136     ** \note vbScript should not call this function at this point because there seems
00137     **  to be some sort of interface probem when opening this dialog directly from
00138     **  vb.  Instead vbScript should call multiDateDialogExec which will both create
00139     **  a new dialog if need be and exec() that dialog properly.  Therefore, this method
00140     **  is published in the 'public' section of the Form but not in the 'public slots'
00141     **  section.
00142     **
00143     */
00144     cmcDateDialog * multiDateDialog
00145     (
00146       const QString defaultDate = "" 
00147     );
00148 
00149     /*!
00150     ** \brief Reset fields to their 'unknown' values \n
00151     **
00152     ** This loops through all the fields and connections on the form and resets their
00153     **  values so that it appears as if the form was just loaded.  This is used in
00154     **  conjunction with the prev/next functionality so that if the form is moved to
00155     **  another item, the fields and connections can accurately reflect their contents.
00156     **
00157     */
00158     void resetFields();
00159 
00160     /*!
00161     ** \brief Perform the prevNext functions \n
00162     **
00163     ** This internal function takes care of all the things that need to be taken care
00164     **  of if the prevNext buttons are used.  For starters, it clears the fields of all
00165     **  their values.  If the form is actually being closed, then clearing the fields
00166     **  is somewhat redundant.  But, since we don't know if the form is actually being
00167     **  closed or if one of the prevNext keys was used we have to clear all the field
00168     **  values so that they pick up the proper values for the new item.
00169     **
00170     ** Then, this routine takes care of 'handling' the prevNext keys.  There are quite
00171     **  a few manuvers that have to be taken to properly handle the prevNext keys, 
00172     **  especially when multiple form types are in use.  When multiple forms are in use
00173     **  then the current form really needs to be closed and a new one opened, on the
00174     **  same item.  This is an exceptionally difficult thing to do.
00175     **
00176     */
00177     void prevNext();
00178 
00179   public slots:
00180 
00181     /*!
00182     ** \brief Return the name of something \n
00183     **
00184     ** This will return the name of this form as assigned in the Commence form designer.
00185     **
00186     ** \par vbScript Example:
00187     ** \code
00188     **   msgbox dfrm.name     ' shows "Initial Form" if the name hasn't been changed.
00189     ** \endcode
00190     */
00191     QString name(); // dispid = 0x01
00192 
00193     /*!
00194     ** \brief Return the Category name of this Form \n
00195     **
00196     ** Return the category name that this form is associated with.
00197     **
00198     ** \par vbScript Example:
00199     ** \code
00200     **   dim cursor: set cursor = dfrm.DB.getCursor( 0, dfrm.categoryName, 0 )
00201     ** \endcode
00202     */
00203     QString categoryName(); // dispid = 0x02
00204 
00205     /*!
00206     ** \brief Return the Item Name text value \n
00207     **
00208     ** String, name of the current item. May be empty when adding an item and 
00209     **  the name field has not yet been entered.
00210     **
00211     ** \par vbScript Example:
00212     ** \code
00213     **   if( dfrm.ItemName = "Accounting Department" ) then
00214     **     msgbox "I was told there would be no math!"
00215     **   end if
00216     ** \endcode
00217     */
00218     QString itemName(); // dispid = 0x03
00219 
00220     /*!
00221     ** \brief Clarified Item Name
00222     **
00223     ** This returns the item name with the clarify field value included
00224     **  in the case that this item
00225     **
00226     **
00227     */
00228     QString clarifiedItemName();
00229 
00230     /*!
00231     ** \brief Return the Item Clarify text value \n
00232     **
00233     **
00234     */
00235     QString itemClarify();
00236 
00237     /*!
00238     ** \brief Return the current Tab name \n
00239     **
00240     ** Return the current Tab name.
00241     **
00242     ** \par vbScript Example:
00243     ** \code
00244     ** Sub HandlePage
00245     **   select case dfrm.TabName
00246     **     case "Main": doMainPage
00247     **     case "Info": doInfoPage
00248     **     case "Tank": doTankPage
00249     **   end select
00250     ** End Sub
00251     ** \endcode
00252     */
00253     QString tabName(); // dispid = 0x04
00254 
00255     /*!
00256     ** \brief Return the current field name \n
00257     **
00258     ** Return the currently selected field name.
00259     **
00260     ** \par vbScript Example:
00261     ** \code
00262     ** Sub doInfoPage()
00263     **   select case dfrm.FieldName
00264     **     case "Customer No":  PrintDetails
00265     **     case "Ref ID":       AcquireInvoices
00266     **     case "Shipping":     ChargeOff
00267     **     case "Past Due":     Alert("This Customer Is Past Due")
00268     **   end select
00269     ** End Sub
00270     ** \endcode
00271     */
00272     QString fieldName();
00273 
00274     /*!
00275     ** \brief Return the keyField \n
00276     **
00277     ** Every category has a key field.  This is the same as the 'Name' field.  This method
00278     **  provides direct access to this name field.
00279     **
00280     ** \note This FieldName value defaults to 'catnameKey' - see the definition in the source
00281     **  code for clarification.
00282     **
00283     ** \par vbScript Example
00284     ** \code
00285     ** Sub DoSomething()
00286     **   dim oKey: set oKey = dfrm.keyField
00287     **   oKey.Value = "this is a test"      ' set the name field to "this is a test"
00288     ** End Sub
00289     ** \endcode
00290     **
00291     */
00292     cmcFormField * keyField();
00293 
00294     /*!
00295     ** \brief Return the clarifyField \n
00296     **
00297     ** 
00298     **
00299     ** \par vbScript Example
00300     ** \code
00301     ** Sub DoSomething()
00302     **   dim oCfy: set oCfy = dfrm.cfyField
00303     **   oCfy.Value = "this is a test"      ' set the clarify field to "this is a test"
00304     ** End Sub
00305     ** \endcode
00306     */
00307     cmcFormField * cfyField();
00308 
00309     /*!
00310     ** \brief Return the varField \n
00311     **
00312     ** The varField is a memo field that is designated as part of the 
00313     **  100-field-limit extension project.  Typically the var field name
00314     **  is comprised from the category Name plus "Var".  For instance,
00315     **  examples include; calendarVar, personVar, projectVar, matterVar...
00316     **  and so on.
00317     **
00318     ** \par vbScript Example
00319     ** \code
00320     ** Sub DoSomething()
00321     **   dim oVar: set oVar = dfrm.varField
00322     **   oVar.var("cmcID") = "12345"      ' set the cmcID element in var to "12345"
00323     **   oVar.var("dateOn") = now
00324     ** End Sub
00325     ** \endcode
00326     **
00327     */
00328     cmcFormField * varField();
00329 
00330     /*!
00331     ** \brief Return the guid field \n
00332     **
00333     ** The guid field is a special field defined in the category that can be used
00334     **  to store a guid of this item.  It should be a text(40) field.  It can be
00335     **  indexed and/or used as a clarify field to aid in the identification
00336     **  of items by ID.  If this field exists in the category definition then the
00337     **  guid will *not* be stored in the varField() if it also exists.
00338     **
00339     ** \sa guid, thidField, varField
00340     */
00341     cmcFormField * guidField();
00342 
00343     /*!
00344     ** \brief return the cmcID field \n
00345     **
00346     ** The cmcID field is a special field defined in the category that can be used
00347     **  to store the cmcID of this item.  It should be a text(20) field.  It can be
00348     **  indexed and/or used as a clarify field to aid in the identification
00349     **  of items by ID.  If this field exists in the category definition then the
00350     **  cmcID will *not* be stored in the varField() if it also exists.
00351     **
00352     ** \sa cmcID, guidField, varField
00353     */
00354     cmcFormField * thidField();
00355 
00356     /*!
00357     ** \brief Convert the form fields and connections and their values to an xml document \n
00358     **
00359     ** This is a routine that will produce a very long string which is an xml-compliant
00360     **  representation of the form field and connection values.  The xml output is,
00361     **  in essence, an export of this category item.
00362     **
00363     ** \par vbScript Example
00364     ** \code
00365     ** Sub Form_OnClick(ByVal ControlID)
00366     **   if( ControlID = "CommandButton1" ) then
00367     **     msgbox dfrm.toXml("*")
00368     **   end if
00369     ** End Sub
00370     ** \endcode
00371     **
00372     ** \par Sample Output
00373     ** \code
00374     ** <!DOCTYPE QCommenceForm>
00375     ** <item formName="Dumont" categoryName="Dumont" itemName="test" itemClarify="" >
00376     **    <field0 name="Name" >test</field0>
00377     **    <field1 name="Build" >5</field1>
00378     **    <field2 name="Data" ></field2>
00379     **    <field3 name="Description" ></field3>
00380     **    <field4 name="dumontVar" >guid={9027b2d3-4f52-4842-99f5-bc3499e9fd33}
00381     ** this is a test
00382     ** this is multi-line text.</field4>
00383     **    <field5 name="Parameters" ></field5>
00384     **    <field6 name="Result" ></field6>
00385     **    <field7 name="Run from Disk" >0</field7>
00386     **    <field8 name="Script" ></field8>
00387     **    <connection1 name="pRD->Employee" >
00388     **       <item1>
00389     **          <key>Ben</key>
00390     **          <clarify></clarify>
00391     **       </item1>
00392     **       <item2>
00393     **          <key>Claudia</key>
00394     **          <clarify></clarify>
00395     **       </item2>
00396     **       <item3>
00397     **          <key>Mark</key>
00398     **          <clarify></clarify>
00399     **       </item3>
00400     **       <item4>
00401     **          <key>Bryon</key>
00402     **          <clarify></clarify>
00403     **       </item4>
00404     **    </connection1>
00405     **    <connection2 name="pWR->Employee" >
00406     **       <item1>
00407     **          <key>Mark</key>
00408     **          <clarify></clarify>
00409     **       </item1>
00410     **    </connection2>
00411     ** </item>
00412     ** \endcode
00413     ** 
00414     */
00415     QString toXml
00416     (
00417       QString fieldList
00418     );
00419 
00420     /*!
00421     ** \brief Return the cmcID of this item \n
00422     **
00423     ** This function returns the currently assigned itemThid (THID) of this item.  Please
00424     **  note that this function ONLY works when this category contains an actual
00425     **  varField field where the \c THID can be stored .AND. this form is .NOT.
00426     **  in "isAdd == True" mode.  Both of those conditions must be true to get
00427     **  at the \c THID value for this item.  If not, then "unknown" is returned
00428     **  instead.
00429     **
00430     ** Alternatively, if you do not want to have the THID stored in a varField()
00431     **  type of field, you can define a field "thid Text(20)" (a 20-character
00432     **  text field called "cmcID") in the category and then the THID will be
00433     **  automatically stored there.  This can have the advantage of using the
00434     **  cmcID field as the clarify field and creating an index for it and so
00435     **  on.  The disadvantage of using a cmcID field as a clarify field is the
00436     **  cmcID field then shows up in the Tools|Global Search results and also
00437     **  shows up in some other places... and that may be undesirable.
00438     **
00439     ** One thing to note about the cmcID value is that not only is it not available
00440     **  until a new item has been saved to disk, but the cmcID value is actually
00441     **  not portable across multiple databases.  For instance, if an item is
00442     **  moved from one database to another, then even though, technically the
00443     **  cmcID is likely to still be unique, it does not necessarily represent
00444     **  the correct actual cmcID value of that item - simply because it was
00445     **  exported from one database and imported into another.  For this reason,
00446     **  and probably others that haven't been completely realized yet, the 
00447     **  cmcID valus is of marginal value, and probably should not be relied
00448     **  on in a production database.  Instead, the guid() value should be used
00449     **  when trying to uniquely identify items in Commence.
00450     **
00451     ** \par vbScript Example:
00452     ** \code
00453     ** msgbox dfrm.itemThid ' shows '4:80006401:0000365E'
00454     ** \endcode
00455     **
00456     ** \sa guid
00457     */
00458     QString itemThid();
00459 
00460     /*!
00461     ** \brief Return the guid of this item \n
00462     **
00463     ** This function returns the currently assigned guid of this item, or a 
00464     **  new guid for this item if one does not exist yet.
00465     **
00466     ** In order for this function to work properly, there must be a varField() 
00467     **  defined for this category or a special guid field.  If there is no 
00468     **  varField() then this function returns
00469     **  the string value of "nothing".
00470     **
00471     ** If the varField() exists but no guid has been assigned, then this 
00472     **  function will create a new guid value and cause it to be automatically
00473     **  stored in the varField().  The advantage of using this guid function
00474     **  over the itemThid() function is that this value can be generated immediately
00475     **  for new items before they are saved to the category, wheras the itemThid()
00476     **  value is only available after the item has been saved.  Once a guid is
00477     **  generated for an item, because it is stored in the varField() it will
00478     **  remain static and unique for that particular item for the life of that item.
00479     **
00480     ** Alternatively, if you do not want to have the guid stored in a varField()
00481     **  type of field, you can define a field "guid Text(40)" (a 40-character
00482     **  text field called "catNameGuid") in the category and then the guid will be
00483     **  automatically stored there.  This can have the advantage of using the
00484     **  guid field as the clarify field and creating an index for it and so
00485     **  on.  The disadvantage of using a guid field as a clarify field is the
00486     **  guid field then shows up in the Tools|Global Search results and also
00487     **  shows up in some other places... and that may be undesirable.
00488     **
00489     ** \note One pecularity with this method of item identification is that it
00490     **  is all hapening 'outside' of the Commence database engine as a post-process.
00491     **  This means these methods are not without their pitfalls.  One comes from
00492     **  the menu item "Edit | Copy Item".  This menu option causes a new commence 
00493     **  item to be created from an existing one, meaning all the contents of the var
00494     **  field are copied as well.  This is potentially problemmatic because some
00495     **  of this 'item management' code depends on 'initial values' in this var
00496     **  field and other fields.  Extra steps have been taken to insure that
00497     **  the itemThid() and itemGuid() values are unique per item, but care should be
00498     **  taken by the database administrator to insure that things are working
00499     **  as expected.  Especially when the var field is used to store other 
00500     **  values outside the scope of the DumontDLL.
00501     **
00502     ** \par vbScript Example:
00503     ** \code
00504     ** msgbox dfrm.guid ' shows '{623316da-e9cc-4f42-a9fb-f2938920dcb5}'
00505     ** \endcode
00506     **
00507     ** \sa itemThid
00508     */
00509     QString itemGuid();
00510 
00511     /*!
00512     ** \brief Return true/false if this form is in Add Mode \n
00513     **
00514     ** This pass-through function returns true/false if the form is in add mode.
00515     **
00516     ** \par vbScript Example:
00517     ** \code
00518     ** \endcode
00519     */
00520     bool isAdd(); // dispid = 0x07
00521 
00522     /*!
00523     ** \brief Return true/false is the form is in Delete mode \n
00524     **
00525     ** This function returns the delete flag on the form.  The delete flag
00526     **  gets set when the deleteItem() function is called.
00527     **
00528     **
00529     */
00530     bool isDelete();
00531 
00532     /*!
00533     ** \brief Set the form Delete state
00534     **
00535     **
00536     */
00537     void setDelete( bool state );
00538 
00539     /*!
00540     ** \brief Return true/false if the form is from a prev/next event \n
00541     **
00542     ** This handy function returns true or false if the form is from
00543     **  a previous/next button event.
00544     **
00545     */
00546     bool isPrevNext();
00547 
00548     /*!
00549     ** \brief Return the current field value \n
00550     **
00551     ** This pass-through function returns the value of the currently selected
00552     **  field.
00553     **
00554     ** \par vbScript Example:
00555     ** \code
00556     ** \endcode
00557     */
00558     QString fieldValue();
00559 
00560     /*!
00561     ** \brief Return true/false if this item is shared \n
00562     **
00563     ** This pass-through function returns true/false if the form item is currently
00564     **  shared.
00565     **
00566     ** \par vbScript Example:
00567     ** \code
00568     ** \endcode
00569     */
00570     bool isShared();
00571 
00572     /*!
00573     ** \brief Return the current background color \n
00574     **
00575     ** This returns the long-int value of the current form background color.
00576     **
00577     ** \par vbScript Example:
00578     ** \code
00579     ** \endcode
00580     */
00581     long backColor();
00582 
00583     /*!
00584     ** \brief Set the current background color \n
00585     **
00586     ** This sets the background color of the for to the long-int value.
00587     **
00588     ** \par vbScript Example:
00589     ** \code
00590     ** \endcode
00591     */
00592     void backColor
00593     (
00594       long color
00595     );
00596 
00597     /*!
00598     ** \brief Return the current form caption \n
00599     **
00600     ** This Returns the current form Caption.
00601     **
00602     ** \par vbScript Example:
00603     ** \code
00604     ** \endcode
00605     */
00606     QString caption();
00607 
00608     /*!
00609     ** \brief Set the form caption \n
00610     **
00611     ** This sets the form Caption value.
00612     **
00613     ** \par vbScript Example:
00614     ** \code
00615     ** \endcode
00616     */
00617     void caption
00618     (
00619       QString caption
00620     );
00621 
00622     /*!
00623     ** \brief Set the shared flag on the form \n
00624     **
00625     ** This sets and resets the form/item Shared value
00626     **
00627     ** \par vbScript Example
00628     ** \code
00629     ** Sub MakeItemShared()
00630     **   dfrm.setShared True
00631     ** End Sub
00632     **
00633     ** Sub MakeItemUnshared()
00634     **   dfrm.setShared False
00635     ** End Sub
00636     ** \endcode
00637     **
00638     */
00639     void setShared
00640     (
00641       bool state
00642     );
00643 
00644     /*!
00645     ** \brief Set the value of the currently selected field \n
00646     **
00647     ** This sets the value of the currently selected field.  This, of course,
00648     **  assumes that the currently selected control is a Field controls and
00649     **  not a connection control.
00650     **
00651     ** \par vbScript Example:
00652     ** \code
00653     ** \endcode
00654     */
00655     void setValue
00656     (
00657       QString value
00658     ); // dispid = 0x0d
00659 
00660     /*!
00661     ** \brief Delete the Item \n
00662     **
00663     ** This function executes a specially tailored delete type of method
00664     **  on this item.  This is not just a regular item delete like what
00665     **  you get when you hit ctrl-D on a form or a view.  This deletion
00666     **  function is designed to provide tracability and recoverability
00667     **  (as in 'undelete') on deleted items.
00668     **
00669     ** In order for this method to work properly several things have to be 
00670     **  available to Dumont.  First, the item has to have a varField where 
00671     **  deletion info can be stored.  The type of info that gets stored
00672     **  there is as follows:
00673     **
00674     ** \code
00675     ** deletedOn=20071114074022           ' date and time of the deletion
00676     ** deletedBy=MWP:80011002:00223233    ' who requested the deletion
00677     ** \endcode
00678     **
00679     ** When an item is stamped in this fashion it can be easily filtered
00680     **  from various views by adding a "varField Does Not Contain deletedOn"
00681     **  type of filter.  This gives the operator the illusion that the
00682     **  item has actually been deleted from his computer. The downside of 
00683     **  this implementation is that it requires an extra filter be added
00684     **  to all your views and connections in order for them to appear
00685     **  proper to the user.  Also, this requires that the user has write
00686     **  permissions on this particular item.
00687     **
00688     ** But, even if the user does not have write permissions over this particular
00689     **  item, in parallel with stamping the item with deletion info, a changeLog 
00690     **  item is also generated for the deletion request.  Note, I say request 
00691     **  because once the server gets a hold of it, the server may decide this 
00692     **  item shouldn't be deleted afterall - that implementation is left up to 
00693     **  the system integrator (that's the *you* part of this relationship).
00694     **
00695     ** If the user does not have write permissions on the item, then no
00696     **  deletion stamping will be performed on it, and the item will remain
00697     **  in his views.  However, a changeLog item will still be created and
00698     **  saved, and when the server picks up the changeLog deletion request
00699     **  and decides to delete the item anyway then eventually when the
00700     **  user syncs with the workgroup the item will disappear.  This actually
00701     **  allows users to delete items they don't have write permissions on,
00702     **  and there is a trace-log of the deletion!  Nice, eh?
00703     **
00704     ** Here is an actual example of a change log that was generated on an item
00705     **  deletion request.
00706     **
00707     ** \par example changeLog item:
00708     ** \code
00709     ** <!DOCTYPE changeLog>
00710     ** <changeLog version="3.8.98.3" formName="Docket General" action="Delete" categoryName="Calendar" >
00711     **    <itemName>Petryk.M/lit2</itemName>
00712     **    <logOn>20071114112236</logOn>
00713     **    <logBy>MWP:7:80006401:000026F7</logBy>
00714     **    <cmcID>nothing</cmcID>
00715     **    <guid>{55028c01-4b13-4718-9681-c8b832d55360}</guid>
00716     **    <field name="calendarVar" >
00717     **       <from>cmcID=nothing&#xd;
00718     ** guid={55028c01-4b13-4718-9681-c8b832d55360}&#xd;
00719     ** createdOn=20071114112228&#xd;
00720     ** createdBy=MWP:7:80006401:000026F7&#xd;
00721     ** changedOn=20071114112228&#xd;
00722     ** changedBy=MWP:7:80006401:000026F7&#xd;
00723     ** dragFrom=20071118080000&#xd;
00724     ** mdd=0001200711180020110000</from>
00725     **       <to>cmcID=nothing&#xd;
00726     ** guid={55028c01-4b13-4718-9681-c8b832d55360}&#xd;
00727     ** createdOn=20071114112228&#xd;
00728     ** createdBy=MWP:7:80006401:000026F7&#xd;
00729     ** changedOn=20071114112228&#xd;
00730     ** changedBy=MWP:7:80006401:000026F7&#xd;
00731     ** dragFrom=20071118080000&#xd;
00732     ** mdd=0001200711180020110000&#xd;
00733     ** deletedOn=20071114112236&#xd;
00734     ** deletedBy=MWP:7:80006401:000026F7</to>
00735     **    </field>
00736     ** </changeLog>
00737     ** \endcode
00738     **
00739     ** There is enough information in this change log item to be able to 
00740     **  locate the originating source item and user that made the request 
00741     **  for deletion.
00742     **
00743     ** None-the-less, varField or not, this function is designed to tag 
00744     **  the item appropriately so that it may be deleted responsibly, by 
00745     **  the server, or some other authorized administrator.  And, if you
00746     **  set the server up properly then you can archive your items off 
00747     **  in some sort of a historical storage for later retrieval if the
00748     **  users desire.
00749     **
00750     ** The second thing that is required for this 'service' to function
00751     **  properly is the guid() method within Dumont.  This method must
00752     **  be functioning properly so that a unique guid for this item can be
00753     **  generated and made available to the rest of the system.  Yes, I
00754     **  know its possible to build a system that does not require guid's,
00755     **  and you should be able to use this item deletion feature without
00756     **  them, but, frankly, the pitfalls of implementing such a system
00757     **  are great.  For instance, say your category does not allow 
00758     **  duplicates, but certainly allows changes.  Now, someone wants
00759     **  an item deleted, and you are using the 'Name' field to track the
00760     **  item (since it's unique, right?).  You delete the item, a log is
00761     **  created on the 'Name' field, and you're done.  Meanwhile, on or
00762     **  about the same time, someone else changes the 'Name' value of this
00763     **  item.  Their 'sync' packet makes it to the server first so it
00764     **  goes ahead and changes the item name.  Then your packet comes in
00765     **  and requests the item be deleted, but it does it by 'Name' value,
00766     **  right?  See the problem?  The server can't delete the item or 
00767     **  archive it or anything because it can't find it because the name
00768     **  has changed!  Bottom line?  Use the guid() feature of the Dumont
00769     **  project.  It's easy and it will make your life happy, and you'll
00770     **  be rewarded with a new house and a nice car a wonderful spouse
00771     **  and a dog that actually listens to you.  I have all these things
00772     **  and it's because I started using guid's on all my Commence items...
00773     **  really, really!
00774     **
00775     ** Keep in mind that all that is happening here is the item is being
00776     **  *tagged* for deletion.  The actual item deletion occurs on the server
00777     **  where the entire process can be controlled.
00778     **
00779     */
00780     bool deleteItem();
00781 
00782     /*!
00783     ** \brief Apply Workgroup Permissions
00784     **
00785     ** This procedure looks at the "Item Shared" attributes of the item
00786     **  and applys workgroup share permissions.  The Workgroup Permissions
00787     **  are applied as follows:
00788     **
00789     ** \note This procedure does not deal with *delete* permissions.  The
00790     **  reason is we simply don't allow deletions in our databases, due to
00791     **  a variety of reasons, mostly because of no un-delete functionality.
00792     **
00793     ** \par Public
00794     ** Public Permissions represents a rule that *all* active users are
00795     **  applied to both read item permissions, and write item permissions.
00796     **  This essentially gives everyone total access to this item.
00797     **
00798     ** \par Protected
00799     **  Protected Permissions means that *all* active users can read an item, 
00800     **   but only the originator and select users or user groups can write to 
00801     **   that same item.  This makes the permissions somewhat granular.  If
00802     **   individual users have been set, they will be applied to the write
00803     **   group.  If a group has been set, all members of that group will be
00804     **   applied to the write permissions.  The individual members list will
00805     **   take precedence over the group list.
00806     **
00807     ** \par Private
00808     **  Private Permissions means that only the author of this item may read
00809     **   and write to it.
00810     **
00811     ** \par Group
00812     **  I can't remember what I was thinking here.
00813     **
00814     ** \par None
00815     **  This disables this engine on this item, and the user is allowed to 
00816     **   apply his own permissions to the item.
00817     **
00818     */
00819     bool applyWorkgroupPermissions();
00820 
00821     /*!
00822     ** \brief Cause the form to Save \n
00823     **
00824     ** This executes the Save operation on the form.
00825     **
00826     ** \par vbScript Example:
00827     ** \code
00828     ** \endcode
00829     */
00830     bool save();
00831 
00832     /*!
00833     ** \brief Cause the form to cancel \n
00834     **
00835     ** This executes the Cancel operation on the form.
00836     **
00837     ** \par vbScript Example:
00838     ** \code
00839     ** \endcode
00840     */
00841     bool cancel();
00842 
00843     /*!
00844     ** \brief Cause the form to abort \n
00845     **
00846     ** This executes the abort operation on the form.
00847     **
00848     ** \par vbScript Example:
00849     ** \code
00850     ** \endcode
00851     */
00852     bool abort();
00853 
00854     /*!
00855     ** \brief Move to the requested Tab name \n
00856     **
00857     ** This changes the form's currently selected Tab
00858     **
00859     ** \par vbScript Example:
00860     ** \code
00861     ** \endcode
00862     */
00863     void moveToTab
00864     (
00865       QString tabName
00866     );
00867 
00868     /*!
00869     ** \brief Move to the requested Field name \n
00870     **
00871     ** This moves to a specific field within the form.  This passes control
00872     **  to the Commence moveToField form method, but it then also includes
00873     **  an additional reference to the new field value so that the Dumont
00874     **  change-logging engine can function properly.  Note that if you have
00875     **  implemented your own change log code on your forms in vbScript, you
00876     **  will not receive an Form_onEnter or Form_onLeave field event if you
00877     **  use a Form.MoveToField call in your code.  If your vbScript code does
00878     **  not properly detect this field change condition it probably will not 
00879     **  log the field changes properly.
00880     **
00881     ** \par vbScript Example:
00882     ** \code
00883     ** Sub Form_OnClick( ByVal ControlID )
00884     **   if( ControlID = "CommandButton1" )
00885     **     dfrm.moveToField "Account Number" ' change-log engine handled properly!
00886     **   end if
00887     ** End Sub
00888     ** \endcode
00889     **
00890     ** One simple solution to implementing a proper change-log function in
00891     **  vbScript, if that code is dependent on the onEnterField and onLeaveField
00892     **  events, is you can wrap the Form.moveToField function in another function
00893     **  as follows:
00894     **
00895     ** \par Wrapping change-log moveToField functions:
00896     ** \code
00897     ** Sub Move2Field( ByRef FieldName )
00898     **   Form.MoveToField FieldName
00899     **   Form_OnEnterField FieldName
00900     ** End Sub
00901     ** \endcode
00902     **
00903     ** Note that wrapping the moveToField function as shown above is not necessary
00904     **  with Dumont since Dumont makes the same (internal) call to its onEnterField
00905     **  function.
00906     **
00907     */
00908     void moveToField
00909     (
00910       QString fieldName
00911     );
00912 
00913     /*!
00914     ** \brief Report if any field or connection on the form is dirty or not \n
00915     **
00916     ** This function loops through all the fields and connections on 
00917     **  the form and reports true if any of them have been changed from 
00918     **  their original values.
00919     **
00920     ** \par vbScript Example:
00921     ** \code
00922     ** if( dfrm.isDirty ) then
00923     **   msgbox "the following changes are: " & dfrm.changeLog
00924     ** end if
00925     ** \endcode
00926     */
00927     bool isDirty();
00928 
00929     /*!
00930     ** \brief Set Dirty State
00931     **
00932     ** This sets or resets the form dirty state.
00933     **
00934     */
00935     void setDirty( bool state );
00936 
00937     /*!
00938     ** \brief Restore a form back to its original state \n
00939     **
00940     ** This performs an 'undo' on all Fields and Connections.  It loops through each
00941     **  field and each connection and calls their respective undo().
00942     **
00943     ** \par vbScript Example:
00944     ** \code
00945     ** \endcode
00946     */
00947     void undo();
00948 
00949     /*!
00950     ** \brief Return the forms category definition \n
00951     **
00952     **
00953     */
00954     cmcCategoryDef * categoryDef();
00955 
00956     /*!
00957     ** \brief Get a Field object by Name \n
00958     **
00959     ** \note This object does *not* fail if an improper field name is provided.  Rather,
00960     **  it returns an object that is missing its field-object pointer.  The object
00961     **  that gets returned can be tested for validity using the isValid() function call.
00962     **
00963     ** \par vbScript Example ~ Fetching a field by name
00964     ** \code
00965     ** sub FixFieldInfo()
00966     **   dim oFName: set oFName = dfrm.field("First Name")
00967     **   dim oLName: set oLName = dfrm.field("Last Name")
00968     **   dim oBName: set oBName = dfrm.field("Bad Field Name")
00969     **
00970     **   if( oFName is nothing ) then msgbox "First Name is: " & oFName.value else msgbox "Bad Field Name"
00971     **   if( oLName is nothing ) then msgbox "Last Name is: "  & oLName.value else msgbox "Bad Field Name"
00972     **   if( oBName is nothing ) then msgbox "Bad Name is: "   & oFName.value else msgbox "Bad Field Name"
00973     ** end sub
00974     ** \endcode
00975     **
00976     ** \return \ref cmcField "Field" object from the form collection
00977     */
00978     cmcFormField * field
00979     (
00980       QString fieldName
00981     );
00982 
00983     /*!
00984     ** \brief Field Alias \n
00985     **
00986     **
00987     */
00988     cmcFormField * fld
00989     (
00990       QString fieldName
00991     );
00992 
00993     /*!
00994     ** \brief Field by Index \n
00995     **
00996     **
00997     */
00998     cmcFormField * field
00999     (
01000       long index
01001     );
01002 
01003     /*!
01004     ** \brief Get a Connection object by name \n
01005     **
01006     ** This returns a \ref cmcConnection "Connection" object from the Form.  
01007     **  Optionally, a "FieldName" value can be provided which gives this connection
01008     **  a 'default' field property.
01009     **
01010     ** \note This object does *not* fail if an improper connection name is provided.  Rather,
01011     **  it returns an object that is missing its connection-object pointer.  The object
01012     **  that gets returned can be tested for validity using the isValid() function call.
01013     **
01014     ** \par vbScript Example:
01015     ** \code
01016     ** Sub ConnectStaff()
01017     **
01018     **   dim ocStaff: set ocStaff = dfrm.connection("Relates to","Staff")
01019     **   if( ocStaff.isValid ) then
01020     **     ocStaff.SetConnection("Jim","Accounting")
01021     **     ocStaff.SetConnection("Tony","Owner")
01022     **   end if
01023     **
01024     **   dim ocFail: set ocFail = dfrm.connection("this will","fail")
01025     **   if( ocFail.isValid ) then
01026     **     ocFail.SetConnection("ok, now","I'm suprised")
01027     **     ocFail.SetConnection("this shouldn't","get here!")
01028     **   end if
01029     **
01030     ** End Sub
01031     ** \endcode
01032     */
01033     cmcConnection * connection
01034     (
01035       QString conName,
01036       QString catName
01037     );
01038 
01039     cmcConnection * con
01040     (
01041       QString conName,
01042       QString catName
01043     );
01044 
01045     /*!
01046     ** \brief Get a Connection by its "FieldName" \n
01047     **
01048     ** This is an overloaded function to return a cmcConnection when all we have is
01049     **  the "FieldName" as it is provided by the vbScript Form_onEnterField(FieldName) function
01050     **  call.  Normally when dealing with Form Events, all that is provided is a FieldName
01051     **  value which can represent a connection field or a standard text field.  The
01052     **  application (code) has to try to determine which one it is.  Dumont has the
01053     **  built-in services to make this an easy task.  It is possible to pass that simple
01054     **  FieldName value to the connection method and receive a \ref cmcConnection 
01055     **  connection object.
01056     **
01057     ** What this function also makes available is the ability to set field and connection names
01058     **  using the vbScript 'Const' keyword.  Both field names and connection names can be
01059     **  declared this way and then used to reference the connection by name.  This can have
01060     **  the advantage of really cleaning up a bunch of code redundancies.
01061     **
01062     ** \par vbScript Example:
01063     ** \code
01064     ** '
01065     ** ' These declarations were formerly not possible because the .connection.
01066     ** '  object required two parameters.
01067     ** '
01068     ** Const FN_KEY      = "contactsKey"
01069     ** Const FN_CFY      = "contactsCfy"
01070     ** Const FN_FIRST    = "First Name"
01071     ** Const FN_LAST     = "Last Name"
01072     ** Const FN_PHONE    = "Main Phone"
01073     ** Const CN_EMPLOYER = "Employed by Company"
01074     ** Const FN_EMPLKEY  = "companyKey"
01075     ** Const FN_BUSPHONE = "Business Phone"
01076     **
01077     ** Sub Form_OnEnterField(ByRef FieldName)
01078     **   '
01079     **   ' Do the Dumont OnEnterField stuff
01080     **   '
01081     **   dfrm.onEnterField FieldName
01082     **
01083     **   '
01084     **   ' If this is a connection object then deal with it
01085     **   '
01086     **   if( dfrm.isConnection(FieldName) ) then
01087     **     dim conn: set conn = dfrm.connection(FieldName)
01088     **     msgbox "You have " & conn.ConnectedItemCount & " connected items"
01089     **
01090     **     '
01091     **     ' Use the Const values to access the controls
01092     **     '
01093     **     dfrm.field(FN_KEY).value = _
01094     **       dfrm.field(FN_LAST)   & ", "   & _
01095     **       dfrm.field(FN_FIRST)  & " of " & _
01096     **       dfrm.connection(CN_EMPLOYER).fieldValue(FN_EMPLKEY) ' note: connection referred by NAME
01097     **
01098     **     dfrm.field(FN_PHONE).value = _
01099     **       dfrm.connection(CN_EMPLOYER).fieldValue(FN_BUSPHONE) ' note: connection referred by NAME
01100     **
01101     **   end if
01102     ** End Sub
01103     ** \endcode
01104     **
01105     ** \sa \ref cmcConnectionDefs "ConnectionDefs", \ref cmcConnection "Connection", isConnection, isField
01106     */
01107     cmcConnection * connection
01108     (
01109       QString conCatName
01110     );
01111 
01112     /*!
01113     ** \brief Get a Connection by its "FieldName" \n
01114     **
01115     ** This is an alias function for obtaining a regular Connection field.  It is 
01116     **  intended to make the code a little more readable.
01117     **
01118     ** \par vbScript Example
01119     ** \code
01120     ** Sub Form_OnEnterField(ByRef FieldName)
01121     **   dim oxEmployee: set oxEmployee = dfrm.con("pRD Employee")
01122     ** End Sub
01123     ** \endcode
01124     **
01125     */
01126     cmcConnection * con
01127     (
01128       QString conCatName
01129     );
01130 
01131     cmcConnection * connection
01132     (
01133       long index
01134     );
01135 
01136     /*!
01137     ** \brief Check for Connection Name \n
01138     **
01139     ** This returns TRUE when the FieldName provided is a connection field.  This
01140     **  helps to identify an object as a connection when all we have is a field name 
01141     **  as provided by the vbScript Form_onEnterField(FieldName) function.
01142     **
01143     ** \par vbScript Example:
01144     ** \code
01145     ** Sub Form_OnEnterField(ByVal FieldName)
01146     **   If( dfrm.isField(FieldName) ) then
01147     **     msgbox FieldName + " is a field"
01148     **   End If
01149     **   If( dfrm.isConnection(FieldName) ) then
01150     **     msgbox FieldName + " is a Connection"
01151     **   End If
01152     ** End Sub
01153     ** \endcode
01154     **
01155     ** \sa isField
01156     **
01157     */
01158     bool isConnection
01159     (
01160       QString fieldName
01161     );
01162 
01163     /*!
01164     ** \brief Check for Field Name \n
01165     **
01166     ** This takes a field name as a parameter and returns 'true' if the field name equates to
01167     **  an actual field in the category.  If the field name provided is a connection name, or
01168     **  is not listed then this function returns false.
01169     **
01170     ** \par vbScript Example:
01171     ** \code
01172     ** Sub Form_OnEnterField(ByVal FieldName)
01173     **   If( dfrm.isField(FieldName) ) then
01174     **     msgbox FieldName + " is a field"
01175     **   End If
01176     **   If( dfrm.isConnection(FieldName) ) then
01177     **     msgbox FieldName + " is a Connection"
01178     **   End If
01179     ** End Sub
01180     ** \endcode
01181     **
01182     ** \sa isConnection
01183     **
01184     */
01185     bool isField
01186     (
01187       QString fieldName
01188     );
01189 
01190     /*!
01191     ** \brief Get a control from the form \n
01192     **
01193     ** \par vbScript Example:
01194     ** \code
01195     ** \endcode
01196     */
01197     cmcFormControl * control
01198     (
01199       QString controlName
01200     );
01201 
01202     /*!
01203     ** \brief Get the Form.Runtime object \n
01204     **
01205     ** \par vbScript Example:
01206     ** \code
01207     ** \endcode
01208     */
01209     cmcRuntime * runtime();
01210     cmcRuntime * RT();
01211 
01212     /*!
01213     ** \brief Return a multi-date dialog \n
01214     **
01215     ** Ideally this function should actually return the multi-date dialog itself so that
01216     **  the vbScript programmer can use it himself, but that's not working out so good
01217     **  at the moment.  There is still some DumontDLL code required to be able to open
01218     **  a true modal-dialog from a vbScript request.
01219     **
01220     ** For the moment what this function does is perform the multiDateDialog stuff on the
01221     **  form directly - which works out anyhow.
01222     **
01223     ** \par vbScript Example:
01224     ** \code
01225     ** \endcode
01226     */
01227     void multiDateDialogExec
01228     (
01229       const QString defaultDate = ""
01230     );
01231 
01232     /*!
01233     ** \brief Retrieve the Change Log string from this form \n
01234     **
01235     ** \par vbScript Example:
01236     ** \code
01237     ** \endcode
01238     **
01239     ** \sa \ref ChangeLogEngine
01240     */
01241     QString changeLog();
01242 
01243     /*!
01244     ** \brief Fire Form_OnLoad event \n
01245     **
01246     ** \par vbScript Example:
01247     ** \code
01248     ** Sub Form_OnLoad()
01249     **   dfrm.onLoad
01250     ** End Sub
01251     ** \endcode
01252     **
01253     */
01254     bool onLoad();
01255 
01256     /*!
01257     ** \brief Fire Form_OnSave event \n
01258     **
01259     ** The DumontDLL onSave event includes a few procedures for automatically 
01260     **  stamping items with change-log information and assigning guid's and 
01261     **  THID's and whatnot.  You should review the source to see what's going
01262     **  on here.
01263     **
01264     ** \code
01265     ** Sub Form_OnSave()
01266     **   dfrm.onSave
01267     ** End Sub
01268     ** \endcode
01269     */
01270     bool onSave();
01271 
01272     /*!
01273     ** \brief Fire Form_OnCancel event \n
01274     **
01275     ** \par vbScript Example:
01276     ** \code
01277     ** Sub Form_OnCancel()
01278     **   dfrm.onCancel
01279     ** End Sub
01280     ** \endcode
01281     */
01282     bool onCancel();
01283 
01284     /*!
01285     ** \brief Fire Form_OnEnterTab event \n
01286     **
01287     ** \par vbScript Example:
01288     ** \code
01289     ** Sub Form_OnEnterTab(ByVal FieldName)
01290     **   dfrm.onEnterTab FieldName
01291     ** End Sub
01292     ** \endcode
01293     */
01294     bool onEnterTab
01295     (
01296       QString tabName
01297     );
01298 
01299     /*!
01300     ** \brief Fire Form_OnLeaveTab event \n
01301     **
01302     ** \par vbScript Example:
01303     ** \code
01304     ** Sub Form_OnLeaveTab(ByVal FieldName)
01305     **   dfrm.onLeaveTab FieldName
01306     ** End Sub
01307     ** \endcode
01308     **
01309     */
01310     bool onLeaveTab
01311     (
01312       QString tabName
01313     );
01314 
01315     /*!
01316     ** \brief Fire Form_OnEnterField event \n
01317     **
01318     ** \par vbScript Example:
01319     ** \code
01320     ** Sub Form_OnEnterField(ByVal FieldName)
01321     **   dfrm.onEnterField FieldName
01322     ** End Sub
01323     ** \endcode
01324     **
01325     */
01326     bool onEnterField
01327     (
01328       QString fieldName
01329     );
01330 
01331     /*!
01332     ** \brief Fire Form_OnLeaveField event \n
01333     **
01334     ** \par vbScript Example:
01335     ** \code
01336     ** Sub Form_OnLeaveField(ByVal FieldName)
01337     **   dfrm.onLeaveField FieldName
01338     ** End Sub
01339     ** \endcode
01340     **
01341     */
01342     bool onLeaveField
01343     (
01344       QString fieldName
01345     );
01346 
01347     /*!
01348     ** \brief Fire Form_OnEnterControl event \n
01349     **
01350     ** \par vbScript Example:
01351     ** \code
01352     ** Sub Form_OnEnterControl(ByVal ControlID)
01353     **   dfrm.onEnterControl ControlID
01354     ** End Sub
01355     ** \endcode
01356     **
01357     */
01358     bool onEnterControl
01359     (
01360       QString controlID
01361     );
01362 
01363     /*!
01364     ** \brief Fire Form_OnLeaveControl event \n
01365     **
01366     ** \code
01367     ** Sub Form_OnLeaveControl(ByVal ControlID)
01368     **   dfrm.onLeaveControl ControlID
01369     ** End Sub
01370     ** \endcode
01371     **
01372     */
01373     bool onLeaveControl
01374     (
01375       QString controlID
01376     );
01377 
01378     /*!
01379     ** \brief Fire Form_OnActiveXControlEvent event \n
01380     **
01381     ** \par vbScript Example:
01382     ** \code
01383     ** Sub Form_OnActiveXControlEvnet(ByRef ControlID, ByRef EventName, ByRef ParameterArray)
01384     **   dfrm.onActiveXControlEvent ControlID, EventName, ParameterArray
01385     ** End Sub
01386     ** \endcode
01387     **
01388     */
01389     bool onActiveXControlEvent
01390     (
01391       QString controlID,
01392       QString eventName,
01393       QString parameterArray
01394     );
01395 
01396     /*!
01397     ** \brief Fire Form_OnClick event \n
01398     **
01399     ** \par vbScript Example:
01400     ** \code
01401     ** Sub Form_OnClick(ByRef ControlID)
01402     **   dfrm.onClick ControlID
01403     ** End Sub
01404     ** \endcode
01405     **
01406     */
01407     bool onClick
01408     (
01409       QString controlID
01410     );
01411 
01412     /*!
01413     ** \brief Fire Form_OnChange() event \n
01414     **
01415     ** The Form_OnChange() event gets fired any time a control is changed,
01416     **  usually in response to the user typing some text in a control field.
01417     **
01418     ** \par vbScript Example:
01419     ** \code
01420     ** Sub Form_OnChange(ByRef ControlID)
01421     **   dfrm.onChange ControlID
01422     ** End Sub
01423     ** \endcode
01424     */
01425     bool onChange
01426     (
01427       QString controlID
01428     );
01429 
01430     /*!
01431     ** \brief Fire Form_OnKeyPress event \n
01432     **
01433     ** Anytime any key is pressed in any Field or Control this event gets
01434     **  fired.  This event does not get fired for Connection fields.
01435     **
01436     ** \par vbScript Example:
01437     ** \code
01438     ** Sub Form_OnKeyPress(ByRef ControlID, KeyAscii)
01439     **   dfrm.onKeyPress ControlID, KeyAscii
01440     ** End Sub
01441     ** \endcode
01442     */
01443     bool onKeyPress
01444     (
01445       QString controlID, 
01446       long keyAscii
01447     );
01448 
01449     /*!
01450     ** \brief ChangeField Call-back slot \n
01451     **
01452     ** This is a change-field call-back slot.  This method gets called anytime
01453     **  a field content changes and the cursor focus is moved to the next field.
01454     **  This method requires that the \ref FormAnimation functions be called during
01455     **  form execution.
01456     **
01457     */
01458     void changeField
01459     (
01460       QString fieldName,
01461       QString fieldValue
01462     );
01463 
01464     /*!
01465     ** \brief ChangeConnection Call-back slot \n
01466     **
01467     ** This is a change-connection call-back slot.  This method gets called anytime
01468     **  a connection content changes and the cursor focus is moved to the next
01469     **  field or connection.  This method requires that the \ref FormAnimation 
01470     **  functions be called during form execution.
01471     **
01472     */
01473     void changeConnection
01474     (
01475       QString connName,
01476       QString toCategory,
01477       QString value
01478     );
01479 
01480     /*
01481     ** \brief Reopen the form immediately after is closes \n
01482     **
01483     ** This method is designed to allow a form to be closed and then immediately
01484     **  reopened.  
01485     **
01486     ** Why would we want to do this?  Here's one possibility: If you have created 
01487     **  multiple forms on the same category, and each of those forms opens due to
01488     **  some sort of filter criteria, you can no longer safely use the prev/next
01489     **  keys to navigate through items.  Reason being, if one item requires one
01490     **  form type, and then next item requires a different form type, then you
01491     **  would end up on an item with the wrong form type.  This could be disasterous
01492     **  depending on how you've scripted your forms.  
01493     **
01494     ** This method, therefore, allows you to instruct Dumont to open this very 
01495     **  same item, using the DDE call [EditItem()].  Upon doing so, Commence will
01496     **  automatically select the appropriate form to view that same item.
01497     **
01498     */
01499     void setReopen
01500     (
01501       bool state
01502     );
01503 
01504     /*!
01505     ** \brief Perform reload function \n
01506     **
01507     ** This method performs the automatic-form-reload function.  It checks to see if
01508     **  the flag is set and if so applys a secretAgent to cause the form to be 
01509     **  reloaded.
01510     **
01511     */
01512     void reopen();
01513 
01514 
01515     /*!
01516     ** \brief Short-cut to MeInfo \n
01517     **
01518     ** This is a convenience function for acquiring a pointer to the \ref cmcMeInfo MeInfo
01519     **  object.  It simply performs a db()-> meInfo() call.
01520     **
01521     */
01522     cmcMeInfo * meInfo();
01523 
01524     /*!
01525     ** \brief Get the Change Log category Definition \n
01526     **
01527     ** This is an internal function that will seek-out the change log category
01528     **  definition and verify it for compatibility.  If the category definition
01529     **  looks good then a pointer to it is returned.  If it does not look good
01530     **  then a message window is opened with a few details of the problem.
01531     **
01532     */
01533     cmcRowSet * getChangeLogAddRowSet();
01534 
01535   signals:
01536 
01537   protected:
01538 
01539   private:
01540 
01541     /*!
01542     ** \brief Form.Name cache Value \n
01543     **
01544     */
01545     QString m_name;
01546 
01547     /*!
01548     ** \brief Form.CategoryName cache Value \n
01549     **
01550     */
01551     QString m_categoryName;
01552 
01553     /*!
01554     ** \brief
01555     **
01556     ** Flag to indicate that the form is to be reopened \n
01557     **
01558     */
01559     bool m_reopen;
01560 
01561     QString m_itemName;
01562 
01563     QPointer<cmcActiveViewInfo> m_avi;
01564 
01565     bool m_isDelete;
01566 
01567     bool m_isDirty;
01568 
01569     /*!
01570     ** \brief multiDateDialog \n
01571     **
01572     */
01573     QPointer<cmcMultiDateDialog> m_mdd;
01574 
01575     /*!
01576     ** \brief database pointer cache \n
01577     **
01578     */
01579     QPointer<cmcDatabase> m_db;
01580 
01581     /*!
01582     ** \brief categoryDef pointer cache \n
01583     **
01584     */
01585     QPointer<cmcCategoryDef> m_categoryDef;
01586 
01587     /*!
01588     ** \brief Remember if onSave or onCancel was called \n
01589     **
01590     */
01591     bool m_prevNext;
01592 
01593 }; // endclass cmcForm:
01594 
01595 } // endnamespace cmcDatabaseApi
01596 
01597 #endif // #ifndef CDA_FORM_H
01598 
 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