DumontEXE 0.0.1
cmcField.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_FIELD_H_422FD07F_0597_4cbb_A034_9AE85166472E
00026 #define CDA_FIELD_H_422FD07F_0597_4cbb_A034_9AE85166472E
00027 
00028 #include <QDate>
00029 #include <QTime>
00030 
00031 #include "cmcApi.h"
00032 
00033 namespace cmcDatabaseApi {
00034 
00035 class cmcForm;
00036 class cmcFieldDef;
00037 class cmcSubField;
00038 
00039 /*!
00040 ** \brief Field
00041 **
00042 **
00043 */
00044 class cmcField:
00045   public cmcObject
00046 {
00047   Q_OBJECT
00048   public:
00049 
00050     cmcField( const cmcField & copy );
00051 
00052     cmcField
00053     (
00054       const QString & fieldName,
00055       cmcApplication * application,
00056       QObject * parent
00057     );
00058 
00059     virtual ~cmcField();
00060 
00061     /*!
00062     ** \brief Return a QDomElement value \n
00063     **
00064     ** This returns a QDomElement as the current value of this field.
00065     **
00066     */
00067 //    QDomElement deValue( QDomDocument & doc, QDomNode & parent );
00068 
00069     /*!
00070     ** \brief Return a QDomElement previousValue \n
00071     **
00072     **
00073     */
00074 //    QDomElement dePreviousValue( QDomDocument & doc, QDomNode & parent );
00075 
00076     /*!
00077     ** \brief Return a QDomElement ChangeLog value \n
00078     **
00079     ** This returns a xml formatted change log element
00080     **
00081     */
00082 //    QDomElement deChangeValue( QDomDocument & doc, QDomNode & parent );
00083 
00084   public slots:
00085 
00086     /*!
00087     ** \brief Field Label \n
00088     **
00089     **
00090     */
00091     virtual QString label()= 0;
00092 
00093     /*!
00094     ** \brief Get Field Text Value (passthru) \n
00095     **
00096     ** This returns the 'Value' of the Form field.  This is a passthrough function
00097     **  that transfers control directly to the Commence Form.Field object and
00098     **  therefore returns the same data as the standard Form.Field("Name").Value
00099     **  call.
00100     **
00101     ** \par vbScript example:
00102     ** \code
00103     ** msgbox dfrm.Field("calendarKey").Value
00104     ** \endcode
00105     **
00106     */
00107     virtual QString value()= 0;
00108 
00109     /*!
00110     ** \brief Set Field Text Value \n
00111     **
00112     ** This sets the 'Value' of the Form field.  This is a passthrough function
00113     **  that transfers control directly to the Commence Form.Field object and
00114     **  therefore sets the same data as the standard Form.Field("FieldName").Value = "xyz"
00115     **  call.
00116     **
00117     ** \note This function also tests the new value against the current value, and if
00118     **        there is no change then no updates will be performed on the database.
00119     **        This can help reduce the number of updates the database has to sync
00120     **        around the workgroup in the event no real data is changing on the field.
00121     **        This is particularily useful when scripted-updates are occuring on 
00122     **        various text-type-memo fields that the user doesn't update, but the script
00123     **        updates automatically.  The script can just update the field value 
00124     **        blindly and if there is an actual data field change, then, and only then
00125     **        will that change be written to the commence field, thus reducing the amount
00126     **        of data that has to get synced around the workgroup.
00127     **
00128     ** \par vbScript example:
00129     ** \code
00130     ** dfrm.Field("calendarKey").Value = "new value"
00131     ** \endcode
00132     **
00133     */
00134     virtual void value( QString value )= 0;
00135 
00136     /*!
00137     ** \brief Set Field Boolean Value \n
00138     **
00139     ** This function sets a boolean value.  Boolean values must receive special 
00140     **  treament since a Form.Field boolean field requires one set of boolean
00141     **  logic, and a RowSet.Field requires another.  Therefore, this routine
00142     **  gets implemented in one of the subclasses.
00143     **
00144     */
00145     virtual void value( bool value )= 0;
00146 
00147     /*!
00148     ** \brief Clear the current value \n
00149     **
00150     */
00151     virtual void clear();
00152 
00153     /*!
00154     ** \brief Conversion Convenience Function \n
00155     **
00156     ** This convenience function returns the value() as a QDate object.
00157     **  This is useful in instances where the field type is a Commence
00158     **  Date field and it needs to be reformatted into an actual Qt QDate
00159     **  style object.  This is an internal function and it not available
00160     **  to the vbScript interface.
00161     **
00162     ** \note This function makes no assumptions about the type and data
00163     **  contained in the value() before conversion.  The conversion is more
00164     **  or less applied blindly.
00165     **
00166     */
00167     virtual QDate toDate();
00168 
00169     /*!
00170     ** \brief Conversion Convenience Function \n
00171     **
00172     ** This convenience function returns the value() as a QTime object.
00173     **  This is useful in instances where the field type is a Commence
00174     **  Time field and it needs to be reformatted into an actual Qt QTime
00175     **  style object.  This is an internal function and it not available
00176     **  to the vbScript interface.
00177     **
00178     ** \note This function makes no assumptions about the type and data
00179     **  contained in the value() before conversion.  The conversion is more
00180     **  or less applied blindly.
00181     **
00182     */
00183     virtual QTime toTime();
00184 
00185     /*!
00186     ** \brief Boolean Conversion \n
00187     **
00188     */
00189     virtual bool isTrue();
00190 
00191     /*!
00192     ** \brief Boolean Conversion \n
00193     **
00194     */
00195     virtual bool isFalse();
00196 
00197     /*!
00198     ** \brief Test for no data \n
00199     **
00200     */
00201     virtual bool isBlank();
00202 
00203     /*!
00204     ** \brief Test for data \n
00205     **
00206     */
00207     virtual bool isNotBlank();
00208 
00209     /*!
00210     ** \brief Test for GUID type of data \n
00211     **
00212     */
00213     virtual bool isGuid();
00214 
00215     /*!
00216     ** \brief Test for Not GUID type of data \n
00217     **
00218     */ 
00219     virtual bool isNotGuid();
00220 
00221     /*!
00222     ** \brief The length of the field \n
00223     **
00224     */
00225     virtual long length();
00226 
00227     /*!
00228     ** \brief Tests for substring \n
00229     **
00230     */
00231     virtual bool contains( const QString & subString );
00232 
00233     /*!
00234     ** \brief Reset the field back to its 'untouched' state. \n
00235     **
00236     **
00237     */
00238     virtual void reset();
00239 
00240     /*!
00241     ** \brief TRUE Field Indicator \n
00242     **
00243     ** This is a convenience function that returns always TRUE for
00244     **  field objects.
00245     **
00246     */
00247     virtual bool isField();
00248 
00249     /*!
00250     ** \brief FALSE Connection Indicator \n
00251     **
00252     ** This is a convenicen function that returns always FALSE for
00253     **  field objects.
00254     **
00255     */
00256     virtual bool isConnection();
00257 
00258     /*!
00259     ** \brief Field Text Name (passthru) \n
00260     **
00261     ** This returns the 'Name' of the Form field.  This is a passthrough function
00262     **  that transfers control directly to the Commence Form.Field object and
00263     **  therefore returns the same data as the standard Form.Field("Name").Name
00264     **  call.
00265     **
00266     ** \par vbScript example:
00267     ** \code
00268     ** msgbox dfrm.Field("calendarKey").Name   ' shows "calendarKey"
00269     ** \endcode
00270     **
00271     */
00272     virtual QString name();
00273 
00274     /*!
00275     ** \brief Field Text Name (convenience) \n
00276     **
00277     ** This function is identical to the name function.  It is provided as a matter
00278     **  of convenience and api consistency.  Using FieldName is easy to remember
00279     **  because the form scripts use FieldName in many of their functions.  This 
00280     **  makes the source code much more readable.  It, therefore, can be used as 
00281     **  follows:
00282     **
00283     ** \par vbScript Example - FieldName to FieldName comparison
00284     ** \code
00285     ** Sub Form_OnEnterField(ByRef FieldName)
00286     **
00287     **   if( oFirstName.FieldName = FieldName ) then
00288     **     msgBox "you are on the " & FieldName & " field"
00289     **   end if
00290     **
00291     ** End Sub
00292     ** \endcode
00293     **
00294     */
00295     virtual QString fieldName();
00296 
00297     /*!
00298     ** \brief Return the index number of this field \n
00299     **
00300     **
00301     */
00302     virtual long index();
00303 
00304     /*!
00305     ** \brief Append text to a field with a delimiter \n
00306     **
00307     ** This method takes care of appending text to a field.  One of the problems of appending
00308     **  text is that if the delimiter is the vbCrLf string it cannot be easily appended
00309     **  to the end of a line for a seperator.  The string really has to be examined first
00310     **  to see if it has any content and then a delimiter can be used.  This routine takes
00311     **  care of all of that.
00312     **
00313     */
00314     virtual void append( QString appendValue, QString separator = ", " );
00315 
00316     /*!
00317     ** \brief Set Field Date Value \n
00318     **
00319     ** This is an overloaded function for convenience.  It takes a Qt date and
00320     **  converts it to a "m/d/yyyy" value.
00321     **
00322     */
00323     virtual void value( QDate value );
00324 
00325     /*!
00326     ** \brief Set Field Integer Value \n
00327     **
00328     ** This is an overloaded function for convenience.  It takes a long-integer
00329     **  and converts it to a numeric string value.
00330     **
00331     */
00332     virtual void value( long value );
00333 
00334     /*!
00335     ** \brief Set Field Double Value \n
00336     **
00337     ** This is an overloaded function for convenience.  It takes a double
00338     **  precision number and converts it to a string.
00339     **
00340     */
00341     virtual void value( double value );
00342 
00343     /*!
00344     ** \brief Get First line of Memo \n
00345     **
00346     ** This is a handy function that returns the first line from a memo
00347     **  field.  This function assumes there is a crLf imbedded in the
00348     **  field value somewhere, and if there is not, then the whole line
00349     **  is returned.  An optional length can be specified to limit 
00350     **  the number of characters returned, no matter what.
00351     **
00352     */
00353     virtual QString line
00354     (
00355       /*! long ~ line index number (zero based) */
00356       long lineNumber,
00357 
00358       /*! long ~ max characters (defaults to all) */
00359       long maxChar = -1
00360     );
00361 
00362     /*!
00363     ** \brief Unpack a packed Date/Time \n
00364     **
00365     */
00366     virtual QString unpackDateTime();
00367 
00368     /*!
00369     ** \brief Get Field Var Value \n
00370     **
00371     ** This gets a Var value from the Form field.  This function takes the raw 
00372     **  text value of a field and turns it into a multi-value Var field.  The format
00373     **  follows the typical format of a .ini style settings file, with name/value
00374     **  pairs.  Var fields are normally contained within a Commence Memo type of 
00375     **  field.  The syntax is as follows:
00376     **
00377     ** \par vbScript example:
00378     ** \code
00379     **  a memo field containing:
00380     **   cmcID=0:80006401:844F7302
00381     **   createdOn=20060805195512
00382     **   createdBy=MHS:A:80006401:00000BCE
00383     **   changedOn=20060805195512
00384     **   changedBy=MHS:A:80006401:00000BCE
00385     **
00386     ** can be accessed with the following:
00387     ** msgbox dfrm.Field("calendarVar").var("createdOn") ' 20060805195512
00388     ** \endcode
00389     **
00390     ** This is a step to overcoming the 100-field barrier in Commence.
00391     **
00392     */
00393     virtual QString var( QString fieldName );
00394 
00395     /*!
00396     ** \brief Set Field Var Value \n
00397     **
00398     ** This sets a Var value in a Form field.  This function takes the raw
00399     **  text value of a field and turns it into a multi-value Var field.  The format
00400     **  follows the typical format of a .ini style settings file, with name/value
00401     **  pairs.  Var fields are normally contained within a Commence Memo type of
00402     **  field.  The syntax is as follows:
00403     **
00404     ** \par vbScript example:
00405     ** \code
00406     **  a memo field containing:
00407     **   cmcID=0:80006401:844F7302
00408     **   createdOn=20060805195512
00409     **   createdBy=MHS:A:80006401:00000BCE
00410     **   changedOn=20060805195512
00411     **   changedBy=MHS:A:80006401:00000BCE
00412     **
00413     ** can be accessed with the following:
00414     ** dfrm.Field("calendarVar").var("createdOn") = ddll.packDateTime
00415     ** \endcode
00416     **
00417     ** This is a step to overcoming the 100-field barrier in Commence.
00418 
00419     */
00420     virtual void var( QString fieldName, QString newValue );
00421 
00422     /*!
00423     ** \brief Delete a Var field from the field \n
00424     **
00425     ** The method deletes a var element from the var field.  This is useful when
00426     **  you need to clean up a var field and remove some values completely.  This
00427     **  is entirely different from setting a var field to "" since doing that 
00428     **  merely causes the var field to be SET to nothing, rather than removed 
00429     **  entirely.
00430     **
00431     ** \par vbScript Example
00432     ** \code
00433     ** dfrm.Field("calendarVar").delVar "createdOn"
00434     ** \endcode
00435     **
00436     */
00437     virtual void delVar( QString fieldName );
00438 
00439     /*!
00440     ** \brief Sub Field \n
00441     **
00442     */
00443     virtual cmcSubField * subField( QString fieldName );
00444 
00445     /*!
00446     ** \brief Get the Field Definition Object \n
00447     **
00448     ** This method makes a DDE request to retrieve the field definition string.
00449     **  This string value is then cached and used for the various field definition
00450     **  function calls to avoid having to make multiple calls into the Commence
00451     **  API.
00452     **
00453     */
00454     virtual cmcFieldDef * definition();
00455 
00456     /*!
00457     ** \brief Undo Changes \n
00458     **
00459     ** This function restores a field to its previousValue() before any changes
00460     **  were applied.  This is a one-step change (ie; it does not maintain
00461     **  incremental changes... yet!)
00462     **
00463     */
00464     virtual bool undo();
00465 
00466     /*!
00467     ** \brief Return TRUE if this field is dirty \n
00468     **
00469     ** This function returns TRUE when the current field value() does not equal the
00470     **  previousValue().
00471     **
00472     */
00473     virtual bool isDirty();
00474 
00475     /*!
00476     ** \brief Return the previousValue \n
00477     **
00478     ** This returns the previous value of the field.  The previousValue() is 
00479     **  based upon the value of the field at the time this Field object was
00480     **  created.  When Dumont is requested for a Field object, it records the
00481     **  current Commence field value and stores that as its previous value.
00482     **  All changes to the field value then become the new value, and 
00483     **  referring to the previous value always refers to the absolute beginning
00484     **  value of the field, not the previous value from the most recent change.
00485     **
00486     */
00487     virtual QString previousValue();
00488 
00489     /*!
00490     ** \brief Generate a change-log string for the field \n
00491     **
00492     ** This is a convenience function designed to format a change-log string
00493     **  for use in... well... anywhere.  The format of the output is <<"FieldName"
00494     **  from "previousValue" to "newValue">>.  The QCommenceForm object uses this
00495     **  method to document changes to fields on a form.  It is generally used in
00496     **  conjunction with the isDirty() method to determine if there were any
00497     **  changes to the field and generates a log value if so.
00498     **
00499     ** This method can be called directly from vbScript as follows:
00500     **
00501     ** \par vbScript Example:
00502     ** \code
00503     ** msgbox dfrm.Field("First Name").changeLog
00504     ** \endcode
00505     **
00506     ** \sa QCommenceForm::changeLog(), \ref ChangeLogEngine
00507     */
00508     virtual QString changeLog();
00509 
00510   protected:
00511 
00512     /*!
00513     ** \brief Return the parent Form object \n
00514     **
00515     ** This function returns a pointer to this field's parent Form.  It is
00516     **  private because nothing on this field should be being called 
00517     **  except through the form anyway, so providing a pointer to that
00518     **  said form is problemmatic and probably a pointer crash issue.  It's 
00519     **  only used internally, and is provided so that this field can access
00520     **  the database and conversation API.  This method should *not* be called
00521     **  from vbScript.
00522     **
00523     */
00524     cmcForm * form();
00525 
00526     /*!
00527     ** \brief Field Label Cache \n
00528     **
00529     ** The field label is not going to change once the connection to the
00530     **  field has been established, so we cache it here so as to reduce
00531     **  the number of calls into the Commence API to retreive this
00532     **  information.
00533     **
00534     ** \sa label
00535     **
00536     */
00537     QString m_label;
00538 
00539     /*!
00540     ** \brief Field Definition Cache \n
00541     **
00542     ** The field definition is not going to change once the connection to the
00543     **  field has been established, so we cache it here so as to reduce
00544     **  the number of calls into the Commence API to retreive this
00545     **  information.
00546     **
00547     ** \sa definition, type, isShared, isMandatory, isRecurring, 
00548     ** \sa isSelection, maxChars, defaultString
00549     **
00550     */
00551     QPointer<cmcFieldDef> m_definition;
00552 
00553     /*!
00554     ** \brief Field Previous Value \n
00555     **
00556     ** This is a cache of the field value when this field object was first accessed.
00557     **  This value is used in the isDirty() functions and changeLog() functions
00558     **
00559     ** \sa previousValue, undo
00560     **
00561     */
00562     bool    m_gotPreviousValue;
00563     QString m_previousValue;
00564 
00565   private:
00566 
00567 }; // endclass cmcField:
00568 
00569 } // endnamespace cmcDatabaseApi
00570 
00571 #endif // #ifndef CDA_FIELD_H
00572 
 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