Adding overview docs and a couple tweaks to the demo.

[wxWidgets.git] / wxPython / src / _config.i

diff --git a/wxPython/src/_config.i b/wxPython/src/_config.i
index f928c662b78a29d847c86649a9954dba400ac2e1..f3f4d306a87930b43b8913014e9158ea931d01f9 100644 (file)
--- a/wxPython/src/_config.i
+++ b/wxPython/src/_config.i
@@ -24,12 +24,14 @@
 
 %{
     static PyObject* __EnumerationHelper(bool flag, wxString& str, long index) {
 
 %{
     static PyObject* __EnumerationHelper(bool flag, wxString& str, long index) {

+        wxPyBlock_t blocked = wxPyBeginBlockThreads();

         PyObject* ret = PyTuple_New(3);
         if (ret) {
             PyTuple_SET_ITEM(ret, 0, PyInt_FromLong(flag));
            PyTuple_SET_ITEM(ret, 1, wx2PyString(str));
             PyTuple_SET_ITEM(ret, 2, PyInt_FromLong(index));
         }
         PyObject* ret = PyTuple_New(3);
         if (ret) {
             PyTuple_SET_ITEM(ret, 0, PyInt_FromLong(flag));
            PyTuple_SET_ITEM(ret, 1, wx2PyString(str));
             PyTuple_SET_ITEM(ret, 2, PyInt_FromLong(index));
         }

+        wxPyEndBlockThreads(blocked);

         return ret;
     }
 %}
         return ret;
     }
 %}


@@ -45,15 +47,27 @@ enum
 
 
 
 
 
 

-// abstract base class wxConfigBase which defines the interface for derived
-// classes
-//
-// wxConfig organizes the items in a tree-like structure (modeled after the
-// Unix/Dos filesystem). There are groups (directories) and keys (files).
-// There is always one current group given by the current path.
-//
-// Keys are pairs "key_name = value" where value may be of string or integer
-// (long) type (TODO doubles and other types such as wxDate coming soon).
+DocStr(wxConfigBase,
+"wx.ConfigBase class defines the basic interface of all config
+classes. It can not be used by itself (it is an abstract base class)
+and you will always use one of its derivations: wx.Config or
+wx.FileConfig.
+
+wx.ConfigBase organizes the items in a tree-like structure, modeled
+after the Unix/Dos filesystem. There are groups that act like
+directories and entries, key/value pairs that act like files.  There
+is always one current group given by the current path.  As in the file
+system case, to specify a key in the config class you must use a path
+to it.  Config classes also support the notion of the current group,
+which makes it possible to use relative paths.
+
+Keys are pairs \"key_name = value\" where value may be of string,
+integer floating point or boolean, you can not store binary data
+without first encoding it as a string.  For performance reasons items
+should be kept small, no more than a couple kilobytes.
+", "");
+
+

 class wxConfigBase {
 public:
 //      wxConfigBase(const wxString& appName = wxPyEmptyString,       **** An ABC
 class wxConfigBase {
 public:
 //      wxConfigBase(const wxString& appName = wxPyEmptyString,       **** An ABC


@@ -73,39 +87,54 @@ public:
     };
 
 
     };
 
 

-    // sets the config object, returns the previous pointer
-    static wxConfigBase *Set(wxConfigBase *pConfig);
+    %disownarg( wxConfigBase *config );
+    DocDeclStr(
+        static wxConfigBase *, Set(wxConfigBase *config),
+        "Sets the global config object (the one returned by Get) and returns a
+reference to the previous global config object.", "");
+    %cleardisown( wxConfigBase *config );

 
 

-    // get the config object, creates it on demand unless DontCreateOnDemand
-    // was called
-    static wxConfigBase *Get(bool createOnDemand = True);
+    DocDeclStr(
+        static wxConfigBase *, Get(bool createOnDemand = true),
+        "Returns the current global config object, creating one if neccessary.", "");
+    

 
 

-    // create a new config object: this function will create the "best"
-    // implementation of wxConfig available for the current platform, see
-    // comments near definition wxUSE_CONFIG_NATIVE for details. It returns
-    // the created object and also sets it as ms_pConfig.
-    static wxConfigBase *Create();
+    DocDeclStr(
+        static wxConfigBase *, Create(),
+        "Create and return a new global config object.  This function will
+create the \"best\" implementation of wx.Config available for the
+current platform.", "");
+    

 
 

-    // should Get() try to create a new log object if the current one is NULL?
-    static void DontCreateOnDemand();
+    
+    DocDeclStr(
+        static void , DontCreateOnDemand(),
+        "Should Get() try to create a new log object if there isn't a current
+one?", "");
+    

 
 
 
 
 
 

-    // set current path: if the first character is '/', it's the absolute path,
-    // otherwise it's a relative path. '..' is supported. If the strPath
-    // doesn't exist it is created.
-    virtual void SetPath(const wxString& strPath);
+    DocDeclStr(
+        virtual void , SetPath(const wxString& path),
+        "Set current path: if the first character is '/', it's the absolute
+path, otherwise it's a relative path. '..' is supported. If the
+strPath doesn't exist it is created.", "");
+    

 
 

-    // retrieve the current path (always as absolute path)
-    virtual const wxString& GetPath() const;
+    DocDeclStr(
+        virtual const wxString& , GetPath() const,
+        "Retrieve the current path (always as absolute path)", "");
+    

 
 
 
 

-
-
-    // Each of these enumeration methods return a 3-tuple consisting of
-    // the continue flag, the value string, and the index for the next call.

     %extend {
     %extend {

-        // enumerate subgroups
+        DocAStr(GetFirstGroup,
+                "GetFirstGroup() -> (more, value, index)",                
+                "Allows enumerating the subgroups in a config object.  Returns a tuple
+containing a flag indicating there are more items, the name of the
+current item, and an index to pass to GetNextGroup to fetch the next
+item.", "");

         PyObject* GetFirstGroup() {
             bool     cont;
             long     index = 0;
         PyObject* GetFirstGroup() {
             bool     cont;
             long     index = 0;


@@ -114,6 +143,15 @@ public:
             cont = self->GetFirstGroup(value, index);
             return __EnumerationHelper(cont, value, index);
         }
             cont = self->GetFirstGroup(value, index);
             return __EnumerationHelper(cont, value, index);
         }

+
+
+        
+        DocAStr(GetNextGroup,
+                "GetNextGroup(long index) -> (more, value, index)",                
+                "Allows enumerating the subgroups in a config object.  Returns a tuple
+containing a flag indicating there are more items, the name of the
+current item, and an index to pass to GetNextGroup to fetch the next
+item.", "");

         PyObject* GetNextGroup(long index) {
             bool     cont;
             wxString value;
         PyObject* GetNextGroup(long index) {
             bool     cont;
             wxString value;


@@ -122,7 +160,13 @@ public:
             return __EnumerationHelper(cont, value, index);
         }
 
             return __EnumerationHelper(cont, value, index);
         }
 

-        // enumerate entries
+        
+        DocAStr(GetFirstEntry,
+                "GetFirstEntry() -> (more, value, index)",
+                "Allows enumerating the entries in the current group in a config
+object.  Returns a tuple containing a flag indicating there are more
+items, the name of the current item, and an index to pass to
+GetNextGroup to fetch the next item.", "");        

         PyObject* GetFirstEntry() {
             bool     cont;
             long     index = 0;
         PyObject* GetFirstEntry() {
             bool     cont;
             long     index = 0;


@@ -131,6 +175,14 @@ public:
             cont = self->GetFirstEntry(value, index);
             return __EnumerationHelper(cont, value, index);
         }
             cont = self->GetFirstEntry(value, index);
             return __EnumerationHelper(cont, value, index);
         }

+
+
+        DocAStr(GetNextEntry,
+                "GetNextEntry(long index) -> (more, value, index)",
+                "Allows enumerating the entries in the current group in a config
+object.  Returns a tuple containing a flag indicating there are more
+items, the name of the current item, and an index to pass to
+GetNextGroup to fetch the next item.", "");        

         PyObject* GetNextEntry(long index) {
             bool     cont;
             wxString value;
         PyObject* GetNextEntry(long index) {
             bool     cont;
             wxString value;


@@ -142,39 +194,65 @@ public:
 
 
 
 
 
 

-    // get number of entries/subgroups in the current group, with or without
-    // it's subgroups
-    virtual size_t GetNumberOfEntries(bool bRecursive = False) const;
-    virtual size_t GetNumberOfGroups(bool bRecursive = False) const;
+    DocDeclStr(
+        virtual size_t , GetNumberOfEntries(bool recursive = false) const,
+        "Get the number of entries in the current group, with or without its
+subgroups.", "");
+    
+    DocDeclStr(
+        virtual size_t , GetNumberOfGroups(bool recursive = false) const,
+        "Get the number of subgroups in the current group, with or without its
+subgroups.", "");
+    

 
 

-    // returns True if the group by this name exists
-    virtual bool HasGroup(const wxString& strName) const;
+    
+    DocDeclStr(
+        virtual bool , HasGroup(const wxString& name) const,
+        "Returns True if the group by this name exists", "");
+    

 
 

-    // same as above, but for an entry
-    virtual bool HasEntry(const wxString& strName) const;
+    DocDeclStr(
+        virtual bool , HasEntry(const wxString& name) const,
+        "Returns True if the entry by this name exists", "");
+    

 
 

-    // returns True if either a group or an entry with a given name exist
-    bool Exists(const wxString& strName) const;
+    DocDeclStr(
+        bool , Exists(const wxString& name) const,
+        "Returns True if either a group or an entry with a given name exists", "");
+    

 
     // get the entry type
 
     // get the entry type

-    virtual EntryType GetEntryType(const wxString& name) const;
+    DocDeclStr(
+        virtual EntryType , GetEntryType(const wxString& name) const,
+        "Get the type of the entry.  Returns one of the wx.Config.Type_XXX values.", "");
+    

 
 
 
 

-    // Key access.  Returns the value of key if it exists, defaultVal otherwise
-    wxString Read(const wxString& key, const wxString& defaultVal = wxPyEmptyString);
+    DocDeclStr(
+        wxString , Read(const wxString& key, const wxString& defaultVal = wxPyEmptyString),
+        "Returns the value of key if it exists, defaultVal otherwise.", "");
+    

 
     %extend {
 
     %extend {

+        DocStr(ReadInt,
+               "Returns the value of key if it exists, defaultVal otherwise.", "");

         long ReadInt(const wxString& key, long defaultVal = 0) {
             long rv;
             self->Read(key, &rv, defaultVal);
             return rv;
         }
         long ReadInt(const wxString& key, long defaultVal = 0) {
             long rv;
             self->Read(key, &rv, defaultVal);
             return rv;
         }

+
+        DocStr(ReadFloat,
+               "Returns the value of key if it exists, defaultVal otherwise.", "");

         double ReadFloat(const wxString& key, double defaultVal = 0.0) {
             double rv;
             self->Read(key, &rv, defaultVal);
             return rv;
         }
         double ReadFloat(const wxString& key, double defaultVal = 0.0) {
             double rv;
             self->Read(key, &rv, defaultVal);
             return rv;
         }

-        bool ReadBool(const wxString& key, bool defaultVal = False) {
+        
+        DocStr(ReadBool,
+               "Returns the value of key if it exists, defaultVal otherwise.", "");
+        bool ReadBool(const wxString& key, bool defaultVal = false) {

             bool rv;
             self->Read(key, &rv, defaultVal);
             return rv;
             bool rv;
             self->Read(key, &rv, defaultVal);
             return rv;


@@ -183,114 +261,203 @@ public:
 
 
     // write the value (return True on success)
 
 
     // write the value (return True on success)

-    bool Write(const wxString& key, const wxString& value);
-    %name(WriteInt)bool Write(const wxString& key, long value);
-    %name(WriteFloat)bool Write(const wxString& key, double value);
-    %name(WriteBool)bool Write(const wxString& key, bool value);
-
-
-    // permanently writes all changes
-    virtual bool Flush(bool bCurrentOnly = False);
-
-    // renaming, all functions return False on failure (probably because the new
-    // name is already taken by an existing entry)
-    // rename an entry
-    virtual bool RenameEntry(const wxString& oldName,
-                             const wxString& newName);
-    // rename a group
-    virtual bool RenameGroup(const wxString& oldName,
-                             const wxString& newName);
+    DocDeclStr(
+        bool , Write(const wxString& key, const wxString& value),
+        "write the value (return True on success)", "");
+
+    DocDeclStrName(
+        bool, Write(const wxString& key, long value),
+        "write the value (return True on success)", "",
+        WriteInt);
+
+    DocDeclStrName(
+        bool, Write(const wxString& key, double value),
+        "write the value (return True on success)", "",
+        WriteFloat);
+
+    DocDeclStrName(
+        bool, Write(const wxString& key, bool value),
+        "write the value (return True on success)", "",
+        WriteBool);
+
+
+    DocDeclStr(
+        virtual bool , Flush(bool currentOnly = false),
+        "permanently writes all changes", "");
+    
+
+    DocDeclStr(
+        virtual bool , RenameEntry(const wxString& oldName,
+                                   const wxString& newName),
+        "Rename an entry.  Returns False on failure (probably because the new
+name is already taken by an existing entry)", "");
+    
+    DocDeclStr(
+        virtual bool , RenameGroup(const wxString& oldName,
+                                   const wxString& newName),
+        "Rename a group.  Returns False on failure (probably because the new
+name is already taken by an existing entry)", "");
+    

 
     // deletes the specified entry and the group it belongs to if
     // it was the last key in it and the second parameter is True
 
     // deletes the specified entry and the group it belongs to if
     // it was the last key in it and the second parameter is True

-    virtual bool DeleteEntry(const wxString& key,
-                             bool bDeleteGroupIfEmpty = True);
+    DocDeclStr(
+        virtual bool , DeleteEntry(const wxString& key,
+                                   bool deleteGroupIfEmpty = true),
+        "Deletes the specified entry and the group it belongs to if it was the
+last key in it and the second parameter is True", "");
+    
+
+    DocDeclStr(
+        virtual bool , DeleteGroup(const wxString& key),
+        "Delete the group (with all subgroups)", "");
+    
+
+    DocDeclStr(
+        virtual bool , DeleteAll(),
+        "Delete the whole underlying object (disk file, registry key, ...)
+primarly intended for use by deinstallation routine.", "");
+    
+
+
+    DocDeclStr(
+        void , SetExpandEnvVars(bool doIt = true),
+        "We can automatically expand environment variables in the config
+entries this option is on by default, you can turn it on/off at any
+time)", "");
+    
+    DocDeclStr(
+        bool , IsExpandingEnvVars() const,
+        "Are we currently expanding environment variables?", "");
+    
+
+    DocDeclStr(
+        void , SetRecordDefaults(bool doIt = true),
+        "Set whether the config objec should record default values.", "");
+    
+    DocDeclStr(
+        bool , IsRecordingDefaults() const,
+        "Are we currently recording default values?", "");
+    
+
+    DocDeclStr(
+        wxString , ExpandEnvVars(const wxString& str) const,
+        "Expand any environment variables in str and return the result", "");
+    
+
+    DocDeclStr(
+        wxString , GetAppName() const,
+        "", "");
+    
+    DocDeclStr(
+        wxString , GetVendorName() const,
+        "", "");
+    
+
+    DocDeclStr(
+        void , SetAppName(const wxString& appName),
+        "", "");
+    
+    DocDeclStr(
+        void , SetVendorName(const wxString& vendorName),
+        "", "");
+    
+
+    DocDeclStr(
+        void , SetStyle(long style),
+        "", "");
+    
+    DocDeclStr(
+        long , GetStyle() const,
+        "", "");
+    
+    %property(AppName, GetAppName, SetAppName, doc="See `GetAppName` and `SetAppName`");
+    %property(EntryType, GetEntryType, doc="See `GetEntryType`");
+    %property(FirstEntry, GetFirstEntry, doc="See `GetFirstEntry`");
+    %property(FirstGroup, GetFirstGroup, doc="See `GetFirstGroup`");
+    %property(NextEntry, GetNextEntry, doc="See `GetNextEntry`");
+    %property(NextGroup, GetNextGroup, doc="See `GetNextGroup`");
+    %property(NumberOfEntries, GetNumberOfEntries, doc="See `GetNumberOfEntries`");
+    %property(NumberOfGroups, GetNumberOfGroups, doc="See `GetNumberOfGroups`");
+    %property(Path, GetPath, SetPath, doc="See `GetPath` and `SetPath`");
+    %property(Style, GetStyle, SetStyle, doc="See `GetStyle` and `SetStyle`");
+    %property(VendorName, GetVendorName, SetVendorName, doc="See `GetVendorName` and `SetVendorName`");
+};

 
 

-    // delete the group (with all subgroups)
-    virtual bool DeleteGroup(const wxString& key);

 
 

-    // delete the whole underlying object (disk file, registry key, ...)
-    // primarly for use by desinstallation routine.
-    virtual bool DeleteAll();
+//---------------------------------------------------------------------------

 
 

+DocStr(wxConfig,
+"This ConfigBase-derived class will use the registry on Windows,
+and will be a wx.FileConfig on other platforms.", "");

 
 

-    // we can automatically expand environment variables in the config entries
-    // (this option is on by default, you can turn it on/off at any time)
-    bool IsExpandingEnvVars() const;
-    void SetExpandEnvVars(bool bDoIt = True);
+class wxConfig : public wxConfigBase {
+public:
+    DocCtorStr(
+        wxConfig(const wxString& appName = wxPyEmptyString,
+                 const wxString& vendorName = wxPyEmptyString,
+                 const wxString& localFilename = wxPyEmptyString,
+                 const wxString& globalFilename = wxPyEmptyString,
+                 long style = wxCONFIG_USE_LOCAL_FILE | wxCONFIG_USE_GLOBAL_FILE),
+        "", "");
+    
+    ~wxConfig();
+};

 
 

-    // recording of default values
-    void SetRecordDefaults(bool bDoIt = True);
-    bool IsRecordingDefaults() const;

 
 

-    // does expansion only if needed
-    wxString ExpandEnvVars(const wxString& str) const;

 
 

-    // misc accessors
-    wxString GetAppName() const;
-    wxString GetVendorName() const;

 
 

-    // Used wxIniConfig to set members in constructor
-    void SetAppName(const wxString& appName);
-    void SetVendorName(const wxString& vendorName);
+DocStr(wxFileConfig,
+       "This config class will use a file for storage on all platforms.", "");

 
 

-    void SetStyle(long style);
-    long GetStyle() const;
+class wxFileConfig : public wxConfigBase {
+public:
+    DocCtorStr(
+        wxFileConfig(const wxString& appName = wxPyEmptyString,
+                     const wxString& vendorName = wxPyEmptyString,
+                     const wxString& localFilename = wxPyEmptyString,
+                     const wxString& globalFilename = wxPyEmptyString,
+                     long style = wxCONFIG_USE_LOCAL_FILE | wxCONFIG_USE_GLOBAL_FILE),
+        "", "");
+    
+    ~wxFileConfig();

 };
 
 
 //---------------------------------------------------------------------------
 
 };
 
 
 //---------------------------------------------------------------------------
 

-// a handy little class which changes current path to the path of given entry
-// and restores it in dtor: so if you declare a local variable of this type,
-// you work in the entry directory and the path is automatically restored
-// when the function returns
-// Taken out of wxConfig since not all compilers can cope with nested classes.
+DocStr(wxConfigPathChanger,
+"A handy little class which changes current path to the path of given
+entry and restores it in the destructoir: so if you declare a local
+variable of this type, you work in the entry directory and the path is
+automatically restored when the function returns.", "");
+

 class wxConfigPathChanger
 {
 public:
 class wxConfigPathChanger
 {
 public:

-  // ctor/dtor do path changing/restorin
-  wxConfigPathChanger(const wxConfigBase *pContainer, const wxString& strEntry);
- ~wxConfigPathChanger();
-
-  // get the key name
-  const wxString& Name() const { return m_strName; }
+    DocCtorStr(
+        wxConfigPathChanger(const wxConfigBase *config, const wxString& entry),
+        "", "");
+    
+    ~wxConfigPathChanger();
+
+    DocDeclStr(
+        const wxString& , Name() const,
+        "Get the key name", "");   

 };
 
 
 //---------------------------------------------------------------------------
 
 };
 
 
 //---------------------------------------------------------------------------
 

-// This will be a wxRegConfig on Win32 and wxFileConfig otherwise.
-class wxConfig : public wxConfigBase {
-public:
-    wxConfig(const wxString& appName = wxPyEmptyString,
-             const wxString& vendorName = wxPyEmptyString,
-             const wxString& localFilename = wxPyEmptyString,
-             const wxString& globalFilename = wxPyEmptyString,
-             long style = 0);
-    ~wxConfig();
-};
-

 
 

-// Sometimes it's nice to explicitly have a wxFileConfig too.
-class wxFileConfig : public wxConfigBase {
-public:
-    wxFileConfig(const wxString& appName = wxPyEmptyString,
-                 const wxString& vendorName = wxPyEmptyString,
-                 const wxString& localFilename = wxPyEmptyString,
-                 const wxString& globalFilename = wxPyEmptyString,
-                 long style = 0);
-    ~wxFileConfig();
-};
-
-
-//---------------------------------------------------------------------------

 
 

+DocDeclStr(
+    wxString , wxExpandEnvVars(const wxString &sz),
+    "Replace environment variables ($SOMETHING) with their values. The
+format is $VARNAME or ${VARNAME} where VARNAME contains alphanumeric
+characters and '_' only. '$' must be escaped ('\$') in order to be
+taken literally.", "");

 
 

-//  Replace environment variables ($SOMETHING) with their values. The format is
-//  $VARNAME or ${VARNAME} where VARNAME contains alphanumeric characters and
-//  '_' only. '$' must be escaped ('\$') in order to be taken literally.
-wxString wxExpandEnvVars(const wxString &sz);

 
 
 //---------------------------------------------------------------------------
 
 
 //---------------------------------------------------------------------------