DumontEXE 0.0.1
cmcFormField.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_FIELD_H_422FD07F_0597_4cbb_A034_9AE85166472E
00026 #define CDA_FORM_FIELD_H_422FD07F_0597_4cbb_A034_9AE85166472E
00027 
00028 #include <QDate>
00029 #include <QTime>
00030 
00031 #include "cmcApi.h"
00032 #include "cmcField.h"
00033 
00034 namespace cmcDatabaseApi {
00035 
00036 class cmcForm;
00037 class cmcFieldDef;
00038 
00039 /*!
00040 ** \brief Form Field
00041 **
00042 **
00043 */
00044 class cmcFormField:
00045   public cmcField
00046 {
00047   Q_OBJECT
00048   public:
00049 
00050     cmcFormField( const cmcFormField & copy );
00051 
00052     /*!
00053     ** \brief Normal Constructor
00054     **
00055     **
00056     **
00057     */
00058     cmcFormField
00059     (
00060       /*! string ~ the name of the field \n\n */
00061       const QString & fieldName,
00062 
00063       /*! dispatch ~ pointer to the Commence field interface \n\n */
00064       IDispatch * dispatch,
00065 
00066       /*! application ~ pointer to the hosting application \n\n */
00067       cmcApplication * application,
00068 
00069       /*! form ~ pointer to the parent form \n\n */
00070       cmcForm * parentForm
00071 
00072     );
00073 
00074     virtual ~cmcFormField();
00075 
00076     cmcApi * api();
00077 
00078   public slots:
00079 
00080     /*!
00081     ** \brief Field Text Label (passthru) \n
00082     **
00083     ** This returns the 'Label' of the Form field.  This is a passthrough function
00084     **  that transfers control directly to the Commence Form.Field object and
00085     **  therefore returns the same data as the standard Form.Field("Name").Label call.
00086     **
00087     ** \par vbScript example:
00088     ** \code
00089     ** msgbox dfrm.Field("calendarKey").Label
00090     ** \endcode
00091     **
00092     ** \note This value is cached so that repeated lookups do not make repeated
00093     **  calls into the Commence API.
00094     **
00095     */
00096     virtual QString label();
00097 
00098     /*!
00099     ** \brief Get Field Text Value (passthru) \n
00100     **
00101     ** This returns the 'Value' of the Form field.  This is a passthrough function
00102     **  that transfers control directly to the Commence Form.Field object and
00103     **  therefore returns the same data as the standard Form.Field("Name").Value
00104     **  call.
00105     **
00106     ** \par vbScript example:
00107     ** \code
00108     ** msgbox dfrm.Field("calendarKey").Value
00109     ** \endcode
00110     **
00111     */
00112     virtual QString value();
00113 
00114     /*!
00115     ** \brief Set Field Text Value \n
00116     **
00117     ** This sets the 'Value' of the Form field.  This is a passthrough function
00118     **  that transfers control directly to the Commence Form.Field object and
00119     **  therefore sets the same data as the standard Form.Field("FieldName").Value = "xyz"
00120     **  call.
00121     **
00122     ** \note This function also tests the new value against the current value, and if
00123     **        there is no change then no updates will be performed on the database.
00124     **        This can help reduce the number of updates the database has to sync
00125     **        around the workgroup in the event no real data is changing on the field.
00126     **        This is particularily useful when scripted-updates are occuring on 
00127     **        various text-type-memo fields that the user doesn't update, but the script
00128     **        updates automatically.  The script can just update the field value 
00129     **        blindly and if there is an actual data field change, then, and only then
00130     **        will that change be written to the commence field, thus reducing the amount
00131     **        of data that has to get synced around the workgroup.
00132     **
00133     ** \par vbScript example:
00134     ** \code
00135     ** dfrm.Field("calendarKey").Value = "new value"
00136     ** \endcode
00137     **
00138     */
00139     virtual void value( QString value );
00140 
00141     /*!
00142     ** \brief Set a Boolean \n
00143     **
00144     ** This sets the Form.Field boolean value to "1" or "0" depending on 
00145     **  value.
00146     **
00147     ** \par vbScript Example ~ Setting a boolean field value
00148     ** \code
00149     **   dfrm.Field("Active").value = True
00150     ** \endcode
00151     **
00152     */
00153     virtual void value
00154     (
00155       /*! boolean ~ True/False of field value */
00156       bool value
00157     );
00158 
00159     /*!
00160     ** \brief Execute on-enter functions \n
00161     **
00162     ** This function is intended to be called by the parent form to indicate
00163     **  that the field has become active in the user interface and may 
00164     **  possibly be edited.
00165     **
00166     ** This function fires a signal enter().
00167     **
00168     */
00169     virtual bool onEnter();
00170 
00171     /*!
00172     ** \brief Execute on-leave functions \n
00173     **
00174     ** This function is intended to be called by the parent form to indicate
00175     **  that the field has become inactive in the user interface and is
00176     **  no longer being edited.
00177     **
00178     ** This function fires a signal leave().
00179     **
00180     */
00181     virtual bool onLeave();
00182 
00183     /*!
00184     ** \brief Execute the onChange code \n
00185     **
00186     ** This routine does whatever on-change things need to be done to this field
00187     **  item.  There may be nothing.  A signal does get fired indicating that
00188     **  this field has a change event.  This is an internal function that gets 
00189     **  called when the user calls the onLeave() function and there is a data-delta
00190     **  in the before and after values - indicating that a change has been made.
00191     **
00192     ** This function fires a signal change().
00193     **
00194     */
00195     virtual bool onChange();
00196 
00197   signals:
00198 
00199     /*!
00200     ** \brief Field Enter Signal \n
00201     **
00202     ** This signal get sent from this field whenever the onEnter()
00203     **  event is called.  This is an internal Qt signal() that is
00204     **  designed to be hooked into by an upper-level object.  For
00205     **  instance, the QCommenceForm object hooks in to this signal
00206     **  so that the hosting form can be informed when any field is
00207     **  entered into.
00208     **
00209     ** This is an internal function and is not meant to be called from vbScript.
00210     **
00211     */
00212     void enter(  QString fieldName, QString fieldValue );
00213 
00214     /*!
00215     ** \brief Field Leave Signal \n
00216     **
00217     ** This signal gets sent from this field whenever the onLeave()
00218     **  event is called.  This is an internal Qt signal() that is
00219     **  designed to be hooked into by an upper-level object.  For 
00220     **  instance, the QCommenceForm object hooks in to this signal so
00221     **  that the hosting form can be informed when any field is
00222     **  left from.
00223     **
00224     ** This is an internal function and is not meant to be called from vbScript.
00225     **
00226     */
00227     void leave(  QString fieldName, QString fieldValue );
00228 
00229     /*!
00230     ** \brief Field Change Signal \n
00231     **
00232     ** This signal gets sent from this field whenever the value() changes
00233     **  between the onEnter() and onLeave() events.  This is an internal Qt
00234     **  signal() that is designed to be hooked into by an upper-level
00235     **  object.  For instance, the QCommenceForm object hooks
00236     **  in to this signal so that the hosting form can be informed when
00237     **  any field is changed.
00238     **
00239     ** This is an internal function and is not meant to be called from vbScript.
00240     **
00241     */
00242     void change( QString fieldName, QString fieldValue );
00243 
00244 
00245   protected:
00246 
00247     /*!
00248     ** \brief Return the parent Form object \n
00249     **
00250     ** This function returns a pointer to this field's parent Form.  It is
00251     **  private because nothing on this field should be being called 
00252     **  except through the form anyway, so providing a pointer to that
00253     **  said form is problemmatic and probably a pointer crash issue.  It's 
00254     **  only used internally, and is provided so that this field can access
00255     **  the database and conversation API.  This method should *not* be called
00256     **  from vbScript.
00257     **
00258     */
00259     cmcForm * form();
00260 
00261   private:
00262 
00263     /*!
00264     ** \brief API pointer \n
00265     **
00266     **
00267     */
00268     cmcApi * m_api;
00269 
00270     /*!
00271     ** \brief Field Enter Value \n
00272     **
00273     ** This is a cache of the field value when the onEnter() function gets called
00274     **  It is used in the onLeave() function to examine the field value to determine
00275     **  if it has changed.
00276     **
00277     ** \sa onEnter, onLeave, onChange
00278     */
00279     QString m_enterValue;
00280 
00281 }; // endclass cmcFormField:
00282 
00283 } // endnamespace cmcDatabaseApi
00284 
00285 #endif // #ifndef CDA_FIELD_H
00286 
 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