DumontEXE 0.0.1
cmcActiveViewInfo.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_ACTIVE_VIEW_INFO_H_422FD07F_0597_4cbb_A034_9AE85166472E
00026 #define CDA_ACTIVE_VIEW_INFO_H_422FD07F_0597_4cbb_A034_9AE85166472E
00027 
00028 #include <QObject>
00029 #include <QStringList>
00030 #include "cmcObject.h"
00031 
00032 
00033 namespace cmcDatabaseApi {
00034 
00035 class cmcApplication;
00036 
00037 /*!
00038 ** \brief Active View Information
00039 **
00040 ** This object contains the information from the 
00041 ** \ref cmcConversation::getActiveViewInfo "[GetActiveViewInfo()]"
00042 **  DDE call.  The advantage to using this object is that all of the elements of
00043 **  the call are automatically broken up into their constituant parts for 
00044 **  easy access.  
00045 **
00046 ** Further, using this object is easy because it hides the errors that you'll 
00047 **  get when making that call under various conditions.  For instance, if you
00048 **  make this call during a time when a detail form was opened from a script
00049 **  or an agent call or something like that, it will often fail completely 
00050 **  with a vbScript error message.  Worse than that, the conditions under which
00051 **  the DDE request will succeed or fail is rather complicated.  This object 
00052 **  will shield you from those error conditions and simply return an empty object.
00053 **
00054 ** \par vbScript Example:
00055 ** \code
00056 **  dim dexe: set dexe = createObject("Dumont.EXE")
00057 **  dim dfrm: set dfrm = dexe.form(Form)
00058 **  dexe.debug "viewName     " & dfrm.avi.viewName
00059 **  dexe.debug "viewType     " & dfrm.avi.viewType
00060 **  dexe.debug "categoryName " & dfrm.avi.categoryName
00061 **  dexe.debug "itemName     " & dfrm.avi.itemName
00062 **  dexe.debug "fieldName    " & dfrm.avi.fieldName
00063 ** \endcode
00064 **
00065 ** \par Will yeild the following when called from a report:
00066 ** \image html cmcActiveViewInfoReport.png
00067 ** 
00068 ** \par Will yeild the following when called from a form connection field:
00069 ** \image html cmcActiveViewInfoConnection.png
00070 ** 
00071 ** There are a couple of things to note about this very interesting DDE call into
00072 **  the Commence api.  
00073 **
00074 **  \li If a form is loaded from an agent, then making this call simply generates an 
00075 **       error (this object fixes that).  
00076 **  \li When a form is loaded from a connection field from another form, calling this 
00077 **       function ALWAYS seems to produce a 'view type' value of 'Add Item', 
00078 **       regardless of if you're adding an item or not.  In this case it seems only 
00079 **       the 'categoryName', 'itemName' and 'fieldName' component are valid.  
00080 **  \li If a form is opened from a report, then  it seems the only valid components
00081 **       are viewName, viewType, categoryName and itemName.
00082 **  \li This object will query (via DDE) the active view info only one time.  This
00083 **       allows for subsequent calls to the elements of the active view info object
00084 **       to *not* cause additional (and unnecessary) DDE calls.  The advantage is
00085 **       that this object will cache the last active view info until it is queried
00086 **       for a second time.  A query can be initiated by calling \ref query.
00087 **
00088 ** So, none the less, this element of the Commence API is a strange animal.  Hopefully
00089 **  this object will make working with it a little bit easier.
00090 **
00091 **
00092 */
00093 class cmcActiveViewInfo:
00094   public cmcObject
00095 {
00096   Q_OBJECT
00097   public:
00098 
00099     /*!
00100     ** \brief Copy Constructor
00101     **
00102     */
00103     cmcActiveViewInfo( const cmcActiveViewInfo & copy );
00104 
00105     /*!
00106     ** \brief General Constructor
00107     **
00108     */
00109     cmcActiveViewInfo( cmcApplication * application, cmcObject * parent = NULL );
00110 
00111     virtual ~cmcActiveViewInfo();
00112 
00113     QStringList infoList(void);
00114 
00115   public slots:
00116 
00117     /*!
00118     ** \brief Query the active view info
00119     **
00120     ** Normally the active view info item is queried only once for the
00121     **  object that has requested it.  For instance, when you open a form,
00122     **  that form object is instantiated one time at its onset, and all
00123     **  sub-objects (fields, connections, etc) are built as requested and
00124     **  then held in cache memory until the form is released.  This is also
00125     **  true of the cmcActiveViewInfo object.  This means that the active
00126     **  view info will also only be queried only once.  This increases 
00127     **  the efficiency of the application since only one DDE call is made
00128     **  to fetch all the fields of the active view info.
00129     **
00130     ** In some cases, when the active view info is called from the root
00131     **  cmcDatabase object, it may be necessary to force a requery of the
00132     **  active view info object.  Calling query will do that:
00133     **
00134     ** \par vbScript Example:
00135     ** \code
00136     ** dapp.db.avi.query
00137     ** dlog.print dapp.db.avi.categoryName
00138     ** \endcode
00139     **
00140     */
00141     void query();
00142 
00143     /*!
00144     ** \brief Return the entire ActiveViewInfo string
00145     **
00146     ** This returns the entire ViewInfo of the getActiveViewInfo DDE call.  This is the same
00147     **  as the raw-string return value provided by that DDE call.  If the call fails then the
00148     **  value will be a single line of "Request Failed".
00149     **
00150     ** \par vbScript Example:
00151     ** \code
00152     ** dim avi: set avi = dfrm.DB.activeViewInfo
00153     ** msgbox avi.string
00154     ** \endcode
00155     */
00156     QString string();
00157 
00158     /*!
00159     ** \brief Return the View Name component
00160     **
00161     ** This returns the ViewName component of the call to getActiveViewInfo.  This component
00162     **  appears to only be valid when the getActiveViewInfo is called from a view such as a 
00163     **  report or a book or something like that.
00164     **
00165     */
00166     QString viewName();
00167 
00168     /*!
00169     ** \brief Return the View Type component
00170     **
00171     ** This returns the ViewType component of the call to getActiveViewInfo.  This component
00172     **  appears to only be valid when the getActiveViewInfo is called from a view such as a 
00173     **  report or book or something like that.  If this call is made on a detail form that was
00174     **  opened from another detail form's connection control, then this value appears to always
00175     **  be set to "Add Item", regardless if the originating form was in add mode or not.
00176     **
00177     */
00178     QString viewType();
00179 
00180     /*!
00181     ** \brief Return the category Name component
00182     **
00183     ** This returns the active view Category name.
00184     **
00185     */
00186     QString categoryName();
00187 
00188     /*!
00189     ** \brief Return the Item Name component
00190     **
00191     ** This returns the active view Item Name.
00192     **
00193     */
00194     QString itemName();
00195 
00196     /*!
00197     ** \brief Return the Field Name component
00198     **
00199     ** This returns the active view Field name.  This value appears to only be valid when this
00200     **  call is made on a detail form that was opened from another detail form's connection 
00201     **  control.
00202     **
00203     */
00204     QString fieldName();
00205 
00206   private:
00207 
00208     /*!
00209     ** \brief ViewInfo string cache
00210     **
00211     */
00212     QString m_viewInfo;
00213 
00214     /*!
00215     ** \brief ViewInfo stringlist cache
00216     **
00217     */
00218     QStringList m_infoList;
00219 
00220 }; // endclass cmcError:
00221 
00222 } // endnamespace cmcDatabaseApi
00223 
00224 #endif // #ifndef CDA_ACTIVE_VIEW_INFO_H
00225 
 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