X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/d14a1e28567de23c586bc80017073d0c39f8d18f..6c3c55cf30584177001a3fdbfe0a011cac3f8996:/wxPython/src/_config.i?ds=inline diff --git a/wxPython/src/_config.i b/wxPython/src/_config.i index 86e640d191..4ee0060a0f 100644 --- a/wxPython/src/_config.i +++ b/wxPython/src/_config.i @@ -45,15 +45,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 @@ -73,39 +85,54 @@ public: }; - // sets the config object, returns the previous pointer - static wxConfigBase *Set(wxConfigBase *pConfig); - - // get the config object, creates it on demand unless DontCreateOnDemand - // was called - static wxConfigBase *Get(bool createOnDemand = TRUE); - - // 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(); + %apply SWIGTYPE *DISOWN { 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.", ""); + %clear wxConfigBase *config; - // should Get() try to create a new log object if the current one is NULL? - static void DontCreateOnDemand(); + DocDeclStr( + static wxConfigBase *, Get(bool createOnDemand = true), + "Returns the current global config object, creating one if neccessary.", ""); + + 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.", ""); + + + 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); - // retrieve the current path (always as absolute path) - virtual const wxString& GetPath() const; + 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.", ""); + + 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 { - // 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; @@ -114,6 +141,15 @@ public: 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; @@ -122,7 +158,13 @@ public: 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; @@ -131,6 +173,14 @@ public: 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; @@ -142,39 +192,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 - 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 { + 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; } + + 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; } - 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; @@ -182,115 +258,193 @@ public: } - // 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); + // write the value (return True on success) + 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 - virtual bool DeleteEntry(const wxString& key, - bool bDeleteGroupIfEmpty = TRUE); + // it was the last key in it and the second parameter is 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, + "", ""); + +}; - // 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: - // 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); //---------------------------------------------------------------------------