DumontEXE 0.0.1
cmcApplication.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_APPLICATION_H_422FD07F_0597_4cbb_A034_9AE85166472E
00026 #define CDA_APPLICATION_H_422FD07F_0597_4cbb_A034_9AE85166472E
00027 
00028 #include <QPointer>
00029 #include <QDomDocument>
00030 #include <QThread>
00031 #include <QProcess>
00032 
00033 class QSettings;
00034 
00035 #include "cmcApi.h"
00036 #include "cmcDatabase.h"
00037 
00038 namespace cmcDatabaseApi {
00039 
00040 class cmcCategoryDefs;
00041 class cmcCategoryDef;
00042 class cmcCda;
00043 class cmcTreeModel;
00044 class cmcStringList;
00045 class cmcApplication;
00046 class cmcQueue;
00047 
00048 /*!
00049 ** \brief Commence Application object
00050 **
00051 ** This object represents the Commence Application wrapper object. This is the primary
00052 **  reference to the Commence database, when accessing anything from an external
00053 **  script or program.  When the user registers his Commence database with the
00054 **  DumontROT, it is this object that actually gets registered.  When the user
00055 **  then, later, requests a handle to one of the registered databases, he receives
00056 **  a pointer to this object.
00057 **
00058 ** All of the basic Commence Application object functions are supported 
00059 **  transparently for software compatibility.
00060 **
00061 ** The following is a demonstration of using the Commence.Application object to
00062 **  access various properties of the Commence database, and also demonstrates
00063 **  how the Running Object Table (ROT) can be used to gain access to various
00064 **  registered databases.  For detail on using the Running Object Table, refer
00065 **  to the cmcRot object. and also refer to the \ref ROT function call.
00066 **
00067 ** \par vbScript Example ~ Accessing the Dumont ROT
00068 ** \code
00069 ** '
00070 ** ' A vbScript example program to access more than one database.  In order for this
00071 ** '  script to run, the application must be registered in the cmcRot table.
00072 ** '
00073 ** dim dexe: set dexe = createObject("Dumont.EXE")      ' hook dumont
00074 ** dim dapp: set dapp = dexe.application("dumont_test") ' request a database by name
00075 ** 
00076 ** '
00077 ** ' Print everything if possible
00078 ** '
00079 ** if( not dapp is nothing ) then
00080 **   dexe.debug "dapp.currentScriptLevel: " & dapp.currentScriptLevel
00081 **   dexe.debug "dapp.databaseDirectory:  " & dapp.databaseDirectory
00082 **   dexe.debug "dapp.databaseName:       " & dapp.databaseName
00083 **   dexe.debug "dapp.defaultScriptLevel: " & dapp.defaultScriptLevel
00084 **   dexe.debug "dapp.name:               " & dapp.name
00085 **   dexe.debug "dapp.programDirectory:   " & dapp.programDirectory
00086 **   dexe.debug "dapp.programName:        " & dapp.programName
00087 **   dexe.debug "dapp.sameDatabase:       " & dapp.sameDatabase
00088 ** end if
00089 ** \endcode
00090 **
00091 ** \image html Application.DatabaseName.png
00092 **
00093 */
00094 class cmcApplication:
00095   public cmcApi
00096 {
00097   Q_OBJECT
00098   Q_PROPERTY( long    currentScriptLevel READ currentScriptLevel                             DESIGNABLE true SCRIPTABLE true  STORED false                             )
00099   Q_PROPERTY( QString databaseDirectory  READ databaseDirectory                              DESIGNABLE true SCRIPTABLE true  STORED false                             )
00100   Q_PROPERTY( QString databaseName       READ databaseName                                   DESIGNABLE true SCRIPTABLE true  STORED true                              )
00101   Q_PROPERTY( long    defaultScriptLevel READ defaultScriptLevel                             DESIGNABLE true SCRIPTABLE true  STORED false                             )
00102   Q_PROPERTY( QString name               READ name                                           DESIGNABLE true SCRIPTABLE true  STORED false                             )
00103   Q_PROPERTY( QString programDirectory   READ programDirectory                               DESIGNABLE true SCRIPTABLE true  STORED false                             )
00104   Q_PROPERTY( QString programName        READ programName                                    DESIGNABLE true SCRIPTABLE true  STORED false                             )
00105   Q_PROPERTY( QString version            READ version                                        DESIGNABLE true SCRIPTABLE true  STORED true                              )
00106   public:
00107 
00108     /*
00109     ** \brief Copy Constructor \n
00110     **
00111     **
00112     */
00113     cmcApplication( const cmcApplication & copy );
00114 
00115     /*
00116     ** \brief Default Constructor \n
00117     **
00118     **
00119     */
00120     cmcApplication
00121     ( 
00122       /*! IDispatch ~ pointer to the COM interface dispatch program. \n */
00123       IDispatch * dispatch,
00124 
00125       /*! String ~ Dumont Category Name.  Defaults to 'Dumont'.  This can be overridden by
00126                     the registering application. \n */
00127       const QString & dumontCategoryName = "Dumont",
00128 
00129       /*~ QObject ~ pointer to the parent object. */
00130       QObject * parent = NULL
00131     );
00132 
00133     /*
00134     ** \brief Default Destructor \n
00135     **
00136     **
00137     */
00138     virtual ~cmcApplication();
00139 
00140   public slots:
00141 
00142     /*
00143     ** \brief Return the CDA container \n
00144     **
00145     ** The cda container is just a convenient place where we can store a bunch
00146     **  of cda related functionality.
00147     **
00148     */
00149     cmcCda * cda();
00150 
00151     /*!
00152     ** \brief
00153     **
00154     **
00155     */
00156     virtual cmcCdaItem * cdaItem();
00157 
00158     /*!
00159     ** \brief Return the Application Name \n
00160     **
00161     ** The Application Name is slightly different than the databaseName() function call, 
00162     **  or the cmcApplication::name() function call.  The application name is a generic name
00163     **  that can be assigned to this instance of this application that is universal across
00164     **  the entire workgroup.
00165     **
00166     ** When requesting an application instance from the ROT, the specific database name
00167     **  in the databaseName() list can be used, the databasePath() can be used, or the 
00168     **  applicationName() function call can be used.  This allows external scripts to be 
00169     **  written to call upon a database by this generic name rather a database name that
00170     **  might be unique for each client installation.
00171     **
00172     ** \sa setApplicationName
00173     */
00174     QString applicationName();
00175 
00176     /*!
00177     ** \brief Contains the script level set by the script \n
00178     **
00179     ** To change the script level (which controls the VBScript objects supported by Commence), 
00180     **  assign the desired level to this property. The level must be greater than 0 and less than or 
00181     **  equal to DefaultScriptLevel 
00182     **
00183     ** \par vbScriptExample
00184     ** \code
00185     ** dim dexe: set dexe = createObject("Dumont.EXE") ' fetch Dumont
00186     ** dim dapp: set dapp = dexe.app(Application)      ' wrap the Application Object
00187     ** dexe.debug "Level: " & dapp.currentScriptLevel  ' show the current level
00188     ** dapp.currentScript Level = 5                    ' change the level
00189     ** dexe.debug "Level: " & dapp.currentScriptLevel  ' show the new level
00190     ** \endcode
00191     **
00192     ** \sa isScriptLevelSupported, defaultScriptLevel
00193     **
00194     */
00195     virtual long currentScriptLevel( long level = -1 );
00196 
00197     /*!
00198     ** \brief DOS path of active Commence Database \n
00199     **
00200     ** ie., c:\\commence\\data\\
00201     **
00202     */
00203     virtual QString databaseDirectory();
00204 
00205     /*!
00206     ** \brief Name of the active Commence database \n
00207     **
00208     ** This returns the name of the database.  This is the same name that is registered 
00209     **  in the Commence 'Open/Manage Database' dialog window.  Given the example image
00210     **  shown, the following code will produce these results:
00211     **
00212     **
00213     */
00214     virtual QString databaseName();
00215 
00216     /*!
00217     ** \brief Maximum script level \n
00218     **
00219     ** contains the maximum script level supported by this version of Commence
00220     **
00221     */
00222     virtual long defaultScriptLevel();
00223 
00224     /*!
00225     ** \brief Application name \n
00226     **
00227     ** usually Commence
00228     **
00229     */
00230     virtual QString name();
00231 
00232     /*!
00233     ** \brief Commence program directory \n
00234     **
00235     ** often c:\\commence, but more likely C:\\Program Files\\Commence
00236     **
00237     */
00238     virtual QString programDirectory();
00239 
00240     /*!
00241     ** \brief Commence .exe file name \n
00242     **
00243     ** often c:\\commence\\commence.exe
00244     **
00245     */
00246     virtual QString programName();
00247 
00248     /*!
00249     ** \brief Return the current Version of Commence \n
00250     **
00251     ** This function is provided for support for the Commence documentation.
00252     **  Note that the actual function call is wrong, according to the documentation
00253     **  and the actual call should be "Version" not "GetVersion".  Making this
00254     **  call dispatches automatically to the correct "Version" call.
00255     **
00256     */
00257     virtual QString getVersion();
00258 
00259     /*!
00260     ** \brief Return the current Version of Commence \n
00261     **
00262     ** This returns the current version of Commence.
00263     **
00264     */
00265     virtual QString version();
00266 
00267     /*!
00268     ** \brief Is Script Level Supported \n
00269     **
00270     **
00271     **
00272     */
00273     virtual bool isScriptLevelSupported();
00274 
00275     /*!
00276     ** \brief TRUE if database name hasn't changed \n
00277     **
00278     ** After Commence has opened, and registered itself with Dumont, it is possible for the
00279     **  user to open another database.  That basically invalidates the Application object that
00280     **  initially got registered with Dumont.  This function checks the name of the open
00281     **  database against the name of the database when the item was first registered.  If
00282     **  it is the same, then this function returns true.
00283     **
00284     ** This function is used in the cmcRot::application() routines when fetching a handle to
00285     **  a Commence application from the running object table.  If the database relative to that
00286     **  ROT entry has changed then the handle will be removed from the table, and an empty
00287     **  object pointer will be returned back to the caller.
00288     **
00289     */
00290     virtual bool sameDatabase();
00291 
00292     /*!
00293     ** \brief Access the Database API \n
00294     **
00295     ** This returns a wrapped commence database object.
00296     **
00297     ** \sa db
00298     */
00299     virtual cmcDatabase * database();
00300 
00301     /*!
00302     ** \brief Access the Category Defs collection \n
00303     **
00304     **
00305     */
00306     virtual cmcCategoryDefs * categoryDefs();
00307 
00308     /*!
00309     ** \brief Access a specific category definition by Name \n
00310     **
00311     **
00312     */
00313     virtual cmcCategoryDef * categoryDef( const QString & categoryName );
00314 
00315     /*!
00316     ** \brief Access a specific category definition by Index \n
00317     **
00318     **
00319     */
00320     virtual cmcCategoryDef * categoryDef( long index );
00321 
00322     virtual cmcTreeModel * applicationModel();
00323 
00324     virtual cmcStringList * stringList( const QString & listName );
00325 
00326     /*!
00327     ** \brief Launch an Application from a queue \n
00328     **
00329     */
00330     cmcQueue * getQueue
00331     (
00332       /*! string ~ name of the queue to use for the app */
00333       const QString & queueName
00334     );
00335 
00336     /*!
00337     ** \brief data.ini Workgroup/Enable flag \n
00338     **
00339     **
00340     */
00341     long workgroupEnable();
00342 
00343     /*!
00344     ** \brief Shared DB ID \n
00345     **
00346     **
00347     */
00348     long sharedDbId();
00349 
00350     /*!
00351     ** \brief Sync Files \n
00352     **
00353     **
00354     */
00355     long syncFiles();
00356 
00357     /*!
00358     ** \brief Share Default \n
00359     **
00360     **
00361     */
00362     long shareDefault();
00363 
00364     /*!
00365     ** \brief Is Server \n
00366     **
00367     ** Returns TRUE if this application is a SERVER database
00368     **
00369     */
00370     bool isServer();
00371 
00372     /*!
00373     ** \brief Is Client \n
00374     **
00375     ** Returns TRUE if this application is a CLIENT database
00376     **
00377     */
00378     bool isClient();
00379 
00380     /*!
00381     ** \brief Number of Workgroup Entries \n
00382     **
00383     **
00384     */
00385     long workgroupNumEntries();
00386 
00387     /*!
00388     ** \brief Backup String \n
00389     **
00390     */
00391     QString backup( long index );
00392 
00393     /*!
00394     ** \brief Server ID \n
00395     **
00396     */
00397     long serverId();
00398 
00399     /*!
00400     ** \brief Sync Valid \n
00401     **
00402     **
00403     */
00404     long syncValid();
00405 
00406     /*!
00407     ** \brief Activate the application \n
00408     **
00409     ** This brings the application to the foreground.
00410     **
00411     */
00412     void activate();
00413 
00414     /*!
00415     ** \brief Application Title \n
00416     **
00417     ** This indicates the application title.  This is the title that
00418     **  is shown in the main Commence window. This value depends on
00419     **  the name of the database, plus the Server/Client profile.
00420     **
00421     ** \par Title Examples
00422     ** \code
00423     ** Commence/SERVER - KES.sv3
00424     ** Commence/CLIENT - KES.mwp
00425     ** Commence/SERVER - Contact Manager
00426     ** Commence - My Standalone Database
00427     ** \endcode
00428     **
00429     */
00430     QString title();
00431 
00432     /*!
00433     ** \brief .ini File Name \n
00434     **
00435     */
00436     QString iniFilename();
00437 
00438     /*!
00439     ** \brief CheckOut All Form Scripts \n
00440     **
00441     ** This will check out all form scripts into the database
00442     **  directory under the location db\\Dumont.
00443     **
00444     */
00445     bool checkOutAllFormScripts();
00446 
00447     /*!
00448     ** \brief Update Common Code \n
00449     **
00450     ** This is a utility function that is designed to loop through
00451     **  entries in the Dumont category that are considered to be
00452     **  common code scripts, and locates them throughout the database
00453     **  and updates them.
00454     **
00455     */
00456     bool updateCommonCode();
00457 
00458     /*!
00459     ** \brief Return Dumont Category Name \n
00460     **
00461     ** This returns the current value of the Dumont Category Name.
00462     **
00463     */
00464     QString dumontCategoryName() { return( m_dumontCategoryName ); }
00465 
00466   signals:
00467 
00468   protected:
00469 
00470   private:
00471 
00472     /*
00473     ** This is the name of the dumont category.  Normally this is
00474     **  is defaulted to 'Dumont' but it can be overridden by the
00475     **  registering application.  The dumont category contains all
00476     **  kinds of program settings which dumont relies upon.
00477     **
00478     */
00479     QString m_dumontCategoryName;
00480 
00481     /*!
00482     ** \brief CDA Cache \n
00483     **
00484     **
00485     */
00486     QPointer<cmcCda> m_cda;
00487 
00488     /*!
00489     ** \brief Pointer to database object \n
00490     **
00491     */
00492     QPointer<cmcDatabase> m_database;
00493 
00494     /*!
00495     ** \brief Pointer to categoryDefs object \n
00496     **
00497     */
00498     QPointer<cmcCategoryDefs> m_categoryDefs;
00499 
00500     /*!
00501     ** \brief  Application Model \n
00502     **
00503     **
00504     */
00505     QPointer<cmcTreeModel> m_appModel;
00506 
00507 }; // endclass cmcApplication:
00508 
00509 } // namespace CommenceDatabaseApi
00510 
00511 #endif // #ifndef CDA_APPLICATION_H
00512 
 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