WxExtLib - ConfigEntry.h
00001: // -*- c++ -*-
00002: /*
00003: -------------------------------------------------------------------------
00004: This file is part of WxWidgetsExtensions library.
00005: -------------------------------------------------------------------------
00006:
00007: WxExtLib (WxWidgetsExtensions) library
00008: -----------------------------
00009:
00010: COPYRIGHT NOTICE:
00011:
00012: WxExtLib library Copyright (c) 2003-2007 Daniel Käps
00013:
00014: The WxWidgetsExtensions library and associated documentation files (the
00015: "Software") is provided "AS IS". The author(s) disclaim all
00016: warranties, expressed or implied, including, without limitation, the
00017: warranties of merchantability and of fitness for any purpose. The
00018: author(s) assume no liability for direct, indirect, incidental,
00019: special, exemplary, or consequential damages, which may result from
00020: the use of or other dealings in the Software, even if advised of the
00021: possibility of such damage.
00022:
00023: Permission is hereby granted, free of charge, to any person obtaining
00024: a copy of this Software, to deal in the Software without restriction,
00025: including without limitation the rights to use, copy, modify, merge,
00026: publish, distribute, sublicense, and/or sell copies of the Software,
00027: and to permit persons to whom the Software is furnished to do so,
00028: subject to the following conditions:
00029:
00030: 1. The origin of this source code must not be misrepresented.
00031: 2. Altered versions must be plainly marked as such and must not be
00032: misrepresented as being the original source.
00033: 3. This Copyright notice may not be removed or altered from any
00034: source or altered source distribution.
00035:
00036: End of WxExtLib library Copyright Notice
00037:
00038: -------------------------------------------------------------------------
00039:
00040: RATIONALE
00041:
00042: 1) programming related:
00043: a) use of config entry objects brings more security against
00044: typing mistakes of section/key name strings
00045: b) type safety at the level of accessing the config variables
00046: via config-entry objects
00047: c) names of access can differ from names in the config, this way
00048: we could easily keep legacy names in the config while using
00049: other possibly better names in the program to access them
00050: d) default values can be centralized in config entry objects and
00051: therefore duplication of default values can be avoided
00052:
00053: 2) runtime related:
00054: if all entries are stored in a list, we can:
00055: a) enumerate all entries and write default values for each
00056: to the config at once, so the user can have an overview of
00057: all sections/keys and their defaults
00058: b) write all values at once (e.g. upon program termination)
00059:
00060: moreover, we could:
00061: c) check the range of e.g. integer and long variables,
00062: and we could open a message box/or return a string containing
00063: information about invalid entries
00064: d) implement undefined default value handling if
00065: section/key value is empty
00066: e) read-cache entries: e.g. don't reget an entry if it was
00067: read no more than 500 msec before
00068: f) write-cache entries
00069: g) write entries only if a change is detected, or if some
00070: modification flag is set,
00071: - to speed up writing
00072: - to avoid overwriting changes made by the user while the
00073: program is running
00074:
00075: IMPLEMENTATION
00076:
00077: TODO
00078:
00079: */
00080: //-------------------------------------------------------------------------
00081:
00082: #ifndef _INCLUDED_ConfigEntry_h
00083: #define _INCLUDED_ConfigEntry_h
00084:
00085: #include "WxExtLibConfig.h"
00086:
00087: #if defined(__GNUG__) && (!defined(__APPLE__)) && (!defined(M_NoPragmaInterface))
00088: # pragma interface "ConfigEntry.h"
00089: #endif
00090:
00091: #include <wx/defs.h>
00092: #include <wx/confbase.h>
00093: #include <wx/datetime.h>
00094:
00095: #include "WxMisc.h"
00096:
00097: //-------------------------------------------------------------------------
00098:
00099: #define M_IsDefineExportMagic 1
00100: # include "WxExtLibAliases.h"
00101: #undef M_IsDefineExportMagic
00102:
00103: //-------------------------------------------------------------------------
00104:
00105: class wxConfigEntry;
00106:
00107: WX_DEFINE_ARRAY_PTR(wxConfigEntry *, CConfigEntryArray);
00108:
00109: class wxConfigEntryManager
00110: {
00111: public:
00112: wxConfigEntryManager();
00113: ~wxConfigEntryManager();
00114:
00115: void addConfigEntry (wxConfigEntry * ConfigEntry);
00116:
00117: // NOTE currently, setAssociatedConfig() must be called before
00118: // calls to addConfigEntry(). It won't have an effect for previously
00119: // added wxConfigEntry objects
00120: void setAssociatedConfig (wxConfigBase * ConfigBase);
00121: wxConfigBase * getAssociatedConfig ();
00122:
00123: // this reads all entries (not that an entry is re-read only if
00124: // some time passed after last read and if it was not modified
00125: // in the memory)
00126: bool readAllConfigEntries ();
00127: // writes all modified entries to the wxConfig object
00128: bool writeAllConfigEntries ();
00129: // writes all default entries
00130: bool setDefaultValues ();
00131:
00132: protected:
00133: CConfigEntryArray m_ConfigEntryArray;
00134: wxConfigBase * m_ConfigBase;
00135: };
00136:
00137: //-------------------------------------------------------------------------
00138:
00139: // DECLARE_ConfigEntry:
00140: // - declaration of wxConfigEntry-type object together
00141: // with get and set accessors:
00142: #define DECLARE_ConfigEntry(TValue, TConfigEntry,Name) \
00143: TConfigEntry m_##Name; \
00144: TValue get##Name() \
00145: { \
00146: return m_##Name.get(); \
00147: } \
00148: void get##Name(TValue & Value) \
00149: { \
00150: m_##Name.get(Value); \
00151: } \
00152: void set##Name(const TValue & Value) \
00153: { \
00154: m_##Name.set(Value); \
00155: } \
00156:
00157: //-------------------------------------------------------------------------
00158:
00159: // wxConfigEntry:
00160: // Notes:
00161: // - MessageString is intended to return information
00162: // e.g. about missing or wrong entries (otherwise the user
00163: // doesn't know if something is wrong because missing
00164: // or wrong entries are silently replaced with the default);
00165: // (however, it is not yet used).
00166: // TODO:
00167: // - m_ReadMinimalTimeInterval should be made variable; also, it should
00168: // be possible to selectively deactivate this functionality
00169: class wxConfigEntry
00170: {
00171: public:
00172: wxConfigEntry ();
00173: virtual ~wxConfigEntry ();
00174:
00175: virtual void setEntryPath (const wxString & EntryPath);
00176: virtual void getEntryPath (wxString & EntryPath);
00177:
00178: virtual void setDontReread (bool IsDontReread);
00179: virtual void setDontWrite (bool IsDontWrite);
00180: virtual void setForcedWrite (bool IsForcedWrite);
00181:
00182: //-- functions called by wxConfigEntryManager:
00183: // write (write operation to config object is done
00184: // only if the entry was modified by the program or did
00185: // not exist in the wxConfig before)
00186: // - for MessageString, see class notes
00187: virtual bool write (wxString & MessageString) = 0;
00188: // read: an entry is re-read only if
00189: // - some time (see MinRereadIntervalMS)
00190: // is passed after last read
00191: // - and the value was not modified by the program via a set()
00192: // operation (see derived classed) and is not written yet
00193: // (In this case, the value in the memory will override the
00194: // value in the wxConfig).
00195: // - for MessageString, see class notes
00196: virtual bool read (wxString & MessageString) = 0;
00197: // set to the default value
00198: virtual void setToDefault () = 0;
00199:
00200: // setAssociatedConfig() will be called by wxConfigEntryManager
00201: // during wxConfigEntryManager::addConfigEntry()
00202: virtual void setAssociatedConfig (wxConfigBase * ConfigBase);
00203:
00204: //-- for use by derived classes:
00205: bool readInternal (wxString & String);
00206: bool readInternal (long & Long);
00207: bool readInternal (double & Double);
00208: bool readInternal (bool & Boolean);
00209: bool writeInternal (const wxString & String);
00210: bool writeInternal (long Long);
00211: bool writeInternal (double Double);
00212: bool writeInternal (bool Boolean);
00213:
00214: void setReadState ();
00215: bool getIsReadRequired ();
00216: void setWriteState ();
00217: bool getIsWriteRequired ();
00218:
00219: protected:
00220: // wxStopWatch m_LastReadTimeMS;
00221: wxMinimalTimeInterval m_ReadMinimalTimeInterval;
00222:
00223: // minimal time that must pass until an entry is actually re-read
00224: // from the wxConfig object
00225: enum { MinRereadIntervalMS = 1000 };
00226:
00227: // read, write and modification states:
00228: bool m_IsDontReread;
00229: bool m_IsDontWrite;
00230: bool m_IsForcedWrite;
00231:
00232: bool m_IsAlreadyRead;
00233: bool m_IsChangePending;
00234: bool m_IsSetPending;
00235:
00236: wxConfigBase * m_ConfigBase;
00237: wxString m_EntryPath;
00238: };
00239:
00240: //-------------------------------------------------------------------------
00241:
00242: class wxIntegerConfigEntry : public wxConfigEntry
00243: {
00244: public:
00245: wxIntegerConfigEntry();
00246:
00247: void init (const wxString & EntryPath,
00248: int MinInteger, int MaxInteger, int DefaultInteger);
00249: void setRangeAndDefault (int MinInteger, int MaxInteger, int DefaultInteger);
00250:
00251: // The interface for the program: simply call get() and set()
00252: // as required. The wxConfigEntry and wxConfigEntryManager will
00253: // executed read() from the wxConfig as necessary (note that,
00254: // currently, modified entries are written only after calling
00255: // writeAllConfigEntries())
00256: virtual void get (int & Integer);
00257: virtual int get ();
00258: virtual void get (unsigned int & UInt);
00259: virtual void get (long & Long);
00260: virtual void get (unsigned long & ULong);
00261: // NOTE set() does not check the range of the provided Integer -
00262: // (min, max) checking is done only for what is read from the wxConfig
00263: // (it is assumed that the program does not provide invalid values)
00264: virtual void set (const int & Integer);
00265:
00266: // overloaded read(), write(): called by wxConfigEntryManager
00267: // - for MessageString, see class notes
00268: virtual bool write (wxString & MessageString);
00269: virtual bool read (wxString & MessageString);
00270: virtual void setToDefault ();
00271:
00272: protected:
00273: // range of allowed integers:
00274: int m_MinInteger;
00275: int m_MaxInteger;
00276: // default value if key in the wxConfig is not present or invalid
00277: int m_DefaultInteger;
00278:
00279: int m_CurrentValue;
00280: };
00281:
00282: //-------------------------------------------------------------------------
00283:
00284: class wxBooleanConfigEntry : public wxConfigEntry
00285: {
00286: public:
00287: wxBooleanConfigEntry ();
00288:
00289: void init (const wxString & EntryPath, bool DefaultBoolean);
00290: void setDefault (bool DefaultBoolean);
00291:
00292: // The interface for the program: simply call get() and set()
00293: // as required. The wxConfigEntry and wxConfigEntryManager will
00294: // executed read() from the wxConfig as necessary (note that,
00295: // currently, modified entries are written only after calling
00296: // writeAllConfigEntries())
00297: virtual void get (bool & Boolean);
00298: virtual bool get ();
00299: virtual void set (const bool & Boolean);
00300:
00301: #if defined(__WXMSW__)
00302: // for convenience in MFC based programs:
00303: virtual void get (BOOL & Boolean);
00304: virtual void set (const BOOL & Boolean);
00305: #endif
00306:
00307: // overloaded read(), write(): called by wxConfigEntryManager
00308: // - for MessageString, see class notes
00309: virtual bool write (wxString & MessageString);
00310: virtual bool read (wxString & MessageString);
00311: virtual void setToDefault ();
00312:
00313: protected:
00314: // default value if key in the wxConfig is not present or invalid
00315: bool m_DefaultBoolean;
00316:
00317: bool m_CurrentValue;
00318: };
00319:
00320: //-------------------------------------------------------------------------
00321:
00322: class wxStringConfigEntry : public wxConfigEntry
00323: {
00324: public:
00325: wxStringConfigEntry();
00326:
00327: void init (const wxString & EntryPath, const wxString & DefaultString);
00328: void setDefault (const wxString & DefaultString);
00329:
00330: // The interface for the program: simply call get() and set()
00331: // as required. The wxConfigEntry and wxConfigEntryManager will
00332: // executed read() from the wxConfig as necessary (note that,
00333: // currently, modified entries are written only after calling
00334: // writeAllConfigEntries())
00335: virtual void get (wxString & String);
00336: virtual wxString get ();
00337: virtual void set (const wxString & String);
00338:
00339: // overloaded read(), write(): called by wxConfigEntryManager
00340: // - for MessageString, see class notes
00341: virtual bool write (wxString & MessageString);
00342: virtual bool read (wxString & MessageString);
00343: virtual void setToDefault ();
00344:
00345: protected:
00346: // default value if key in the wxConfig is not present or invalid
00347: wxString m_DefaultString;
00348:
00349: wxString m_CurrentValue;
00350: };
00351:
00352: //-------------------------------------------------------------------------
00353:
00354: class wxDoubleConfigEntry : public wxConfigEntry
00355: {
00356: public:
00357: wxDoubleConfigEntry();
00358:
00359: void init (const wxString & EntryPath,
00360: double MinDouble, double MaxDouble, double DefaultDouble);
00361: void setRangeAndDefault (double MinDouble, double MaxDouble, double DefaultDouble);
00362:
00363: // The interface for the program: simply call get() and set()
00364: // as required. The wxConfigEntry and wxConfigEntryManager will
00365: // executed read() from the wxConfig as necessary (note that,
00366: // currently, modified entries are written only after calling
00367: // writeAllConfigEntries())
00368: virtual void get (double & Double);
00369: virtual double get ();
00370: // virtual void get (float & Float);
00371: // NOTE set() does not check the range of the provided Double -
00372: // (min, max) checking is done only for what is read from the wxConfig
00373: // (it is assumed that the program does not provide invalid values)
00374: virtual void set (const double & Double);
00375:
00376: // overloaded read(), write(): called by wxConfigEntryManager
00377: // - for MessageString, see class notes
00378: virtual bool write (wxString & MessageString);
00379: virtual bool read (wxString & MessageString);
00380: virtual void setToDefault ();
00381:
00382: protected:
00383: // range of allowed integers:
00384: double m_MinDouble;
00385: double m_MaxDouble;
00386: // default value if key in the wxConfig is not present or invalid
00387: double m_DefaultDouble;
00388:
00389: double m_CurrentValue;
00390: };
00391:
00392: //-------------------------------------------------------------------------
00393:
00394: class wxDateTimeConfigEntry : public wxConfigEntry
00395: {
00396: public:
00397: wxDateTimeConfigEntry();
00398:
00399: void init (const wxString & EntryPath,
00400: const wxDateTime & MinDateTime,
00401: const wxDateTime & MaxDateTime,
00402: const wxDateTime & DefaultDateTime);
00403: void setRangeAndDefault (const wxDateTime & MinDateTime, const wxDateTime & MaxDateTime,
00404: const wxDateTime & DefaultDateTime);
00405:
00406: // The interface for the program: simply call get() and set()
00407: // as required. The wxConfigEntry and wxConfigEntryManager will
00408: // executed read() from the wxConfig as necessary (note that,
00409: // currently, modified entries are written only after calling
00410: // writeAllConfigEntries())
00411: virtual void get (wxDateTime & DateTime);
00412: virtual wxDateTime get ();
00413: virtual void set (const wxDateTime & DateTime);
00414:
00415: // overloaded read(), write(): called by wxConfigEntryManager
00416: // - for MessageString, see class notes
00417: virtual bool write (wxString & MessageString);
00418: virtual bool read (wxString & MessageString);
00419: virtual void setToDefault ();
00420:
00421: bool readDateTime(wxDateTime & DateTime);
00422:
00423: protected:
00424: // default value if key in the wxConfig is not present or invalid
00425: wxDateTime m_MinDateTime;
00426: wxDateTime m_MaxDateTime;
00427: wxDateTime m_DefaultDateTime;
00428:
00429: wxDateTime m_CurrentValue;
00430: };
00431:
00432: //-------------------------------------------------------------------------
00433:
00434: #define M_IsUndefExportMagic 1
00435: # include "WxExtLibAliases.h"
00436: #undef M_IsUndefExportMagic
00437:
00438: //-------------------------------------------------------------------------
00439:
00440: #endif
00441: