.. wxPython Phoenix documentation

   This file was generated by Phoenix's sphinx generator and associated
   tools, do not edit by hand.

   Copyright: (c) 2011-2020 by Total Control Software
   License:   wxWindows License

.. include:: headings.inc



.. _wx.FileConfig:

==========================================================================================================================================
|phoenix_title|  **wx.FileConfig**
==========================================================================================================================================

:ref:`wx.FileConfig`  implements :ref:`wx.ConfigBase`  interface for storing and retrieving configuration information using plain text files.          

The files have a simple format reminiscent of Windows ``INI`` files with lines of the form  ``"key = value"``   defining the keys and lines of special form   ``"[group]"``   indicating the start of each group. 

This class is used by default for Config on Unix platforms but may also be used explicitly if you want to use files and not the registry even under Windows. 





         



.. seealso:: :meth:`wx.FileConfig.Save`     







|

|class_hierarchy| Class Hierarchy
=================================

.. raw:: html

   <div id="toggleBlock" onclick="return toggleVisibility(this)" class="closed" style="cursor:pointer;">
   <img id="toggleBlock-trigger" src="_static/images/closed.png"/>
   Inheritance diagram for class <strong>FileConfig</strong>:
   </div>
   <div id="toggleBlock-summary" style="display:block;"></div>
   <div id="toggleBlock-content" style="display:none;">
   <p class="graphviz">
   <center><img src="_static/images/inheritance/wx.FileConfig_inheritance.png" alt="Inheritance diagram of FileConfig" usemap="#dummy" class="inheritance"/></center>
   <script type="text/javascript">toggleVisibilityOnLoad(document.getElementById('toggleBlock'))</script>
   <map id="dummy" name="dummy"> <area shape="rect" id="node1" href="wx.FileConfig.html" title="wx.FileConfig" alt="" coords="11,160,119,189"/> <area shape="rect" id="node2" href="wx.ConfigBase.html" title="wx.ConfigBase" alt="" coords="5,83,124,112"/> <area shape="rect" id="node3" href="wx.Object.html" title="wx.Object" alt="" coords="21,5,108,35"/> </map> 
   </p>
   </div>

|


|method_summary| Methods Summary
================================

================================================================================ ================================================================================
:meth:`~wx.FileConfig.__init__`                                                  Constructor allowing to choose the file names to use.
:meth:`~wx.FileConfig.DeleteAll`                                                 Delete the whole underlying object (disk file, registry key, ...).
:meth:`~wx.FileConfig.DeleteEntry`                                               Deletes the specified entry and the group it belongs to if it was the last key in it and the second parameter is ``True``.
:meth:`~wx.FileConfig.DeleteGroup`                                               Delete the group (with all subgroups).
:meth:`~wx.FileConfig.DisableAutoSave`                                           Prevent this object from saving data to the disk file when it is destroyed.
:meth:`~wx.FileConfig.EnableAutoSave`                                            Enables saving data to the disk file when this object is destroyed.
:meth:`~wx.FileConfig.Flush`                                                     Permanently writes all changes (otherwise, they're only written from object's destructor).
:meth:`~wx.FileConfig.GetGlobalFileName`                                         
:meth:`~wx.FileConfig.GetLocalFileName`                                          
:meth:`~wx.FileConfig.GetNumberOfEntries`                                        Get number of entries in the current group.
:meth:`~wx.FileConfig.GetNumberOfGroups`                                         Get number of entries/subgroups in the current group, with or without its subgroups.
:meth:`~wx.FileConfig.GetPath`                                                   Retrieve the current path (always as absolute path).
:meth:`~wx.FileConfig.HasEntry`                                                  
:meth:`~wx.FileConfig.HasGroup`                                                  
:meth:`~wx.FileConfig.RenameEntry`                                               Renames an entry in the current group.
:meth:`~wx.FileConfig.RenameGroup`                                               Renames a subgroup of the current group.
:meth:`~wx.FileConfig.Save`                                                      Saves all config data to the given stream, returns ``True`` if data was saved successfully or ``False`` on error.
:meth:`~wx.FileConfig.SetPath`                                                   Set current path: if the first character is '/', it is the absolute path, otherwise it is a relative path.
:meth:`~wx.FileConfig.SetUmask`                                                  Allows setting the mode to be used for the config file creation.
================================================================================ ================================================================================


|


|property_summary| Properties Summary
=====================================

================================================================================ ================================================================================
:attr:`~wx.FileConfig.NumberOfEntries`                                           See :meth:`~wx.FileConfig.GetNumberOfEntries`
:attr:`~wx.FileConfig.NumberOfGroups`                                            See :meth:`~wx.FileConfig.GetNumberOfGroups`
:attr:`~wx.FileConfig.Path`                                                      See :meth:`~wx.FileConfig.GetPath` and :meth:`~wx.FileConfig.SetPath`
================================================================================ ================================================================================


|


|api| Class API
===============


.. class:: wx.FileConfig(ConfigBase)

   **Possible constructors**::

       FileConfig(appName=EmptyString, vendorName=EmptyString,
                  localFilename=EmptyString, globalFilename=EmptyString,
                  style=CONFIG_USE_LOCAL_FILE|CONFIG_USE_GLOBAL_FILE)
       
       FileConfig(is)
       
   
   FileConfig implements ConfigBase interface for storing and
   retrieving configuration information using plain text files.



   .. method:: __init__(self, *args, **kw)



      |overload| Overloaded Implementations:

      :html:`<hr class="overloadsep" /><br />`

      
      **__init__** `(self, appName=EmptyString, vendorName=EmptyString, localFilename=EmptyString, globalFilename=EmptyString, style=CONFIG_USE_LOCAL_FILE|CONFIG_USE_GLOBAL_FILE)`
      
      Constructor allowing to choose the file names to use.                  
      
      If `localFilename`  and/or `globalFilename`  are explicitly specified, they are used as the names of the user and system-wide configuration files (the latter is only read by the program while the former is read from and written to). Otherwise the behaviour depends on `style`  parameter. If it includes ``CONFIG_USE_LOCAL_FILE``, then the local file name is constructed from the information in `appName`  and `vendorName`  arguments in a system-dependent way. If ``CONFIG_USE_GLOBAL_FILE``  is not specified at all (and `globalFilename`  is empty) then the system-wide file is not used at all. Otherwise its name and path are also constructed in the way appropriate for the current platform from the application and vendor names.                  
      
      
      :param `appName`: 
      :type `appName`: string
      :param `vendorName`: 
      :type `vendorName`: string
      :param `localFilename`: 
      :type `localFilename`: string
      :param `globalFilename`: 
      :type `globalFilename`: string
      :param `style`: 
      :type `style`: long
      
      
      
      
      
      
      :html:`<hr class="overloadsep" /><br />`

      
      **__init__** `(self, is)`
      
      Read the config data from the specified stream instead of the associated file, as usual.                  
      
                      
      
      
      :param `is`: 
      :type `is`: wx.InputStream
      
      
      
      
      
      
      .. seealso:: :meth:`Save`     
      
      
      
      
      
      
      
      :html:`<hr class="overloadsep" /><br />`






   .. method:: DeleteAll(self)

      Delete the whole underlying object (disk file, registry key, ...).                  

      Primarily for use by uninstallation routine.                  

      :rtype: `bool`








   .. method:: DeleteEntry(self, key, bDeleteGroupIfEmpty=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``.                  


      :param `key`: 
      :type `key`: string
      :param `bDeleteGroupIfEmpty`: 
      :type `bDeleteGroupIfEmpty`: bool




      :rtype: `bool`








   .. method:: DeleteGroup(self, key)

      Delete the group (with all subgroups).                  

      If the current path is under the group being deleted it is changed to its deepest still existing component. E.g. if the current path is  ``"/A/B/C/D"``   and the group   ``C``   is deleted, the path becomes   ``"/A/B"`` .                   


      :param `key`: 
      :type `key`: string




      :rtype: `bool`








   .. method:: DisableAutoSave(self)

      Prevent this object from saving data to the disk file when it is destroyed.                  

      By default, changes to this object are only saved permanently when :meth:`Flush`   is explicitly called or when it is destroyed. If this method is called, :meth:`Flush`   won't be called automatically from the destructor, meaning that any non-explicitly-flushed changes will be lost. 

                 



      .. versionadded:: 4.1/wxWidgets-3.1.3  
     








   .. method:: EnableAutoSave(self)

      Enables saving data to the disk file when this object is destroyed.                  

      This is the default behaviour and this function doesn't need to be called explicitly unless :meth:`DisableAutoSave`   had been previously called. 

                 



      .. versionadded:: 4.1/wxWidgets-3.1.3  
     








   .. method:: Flush(self, bCurrentOnly=False)

      Permanently writes all changes (otherwise, they're only written from object's destructor).                  


      :param `bCurrentOnly`: 
      :type `bCurrentOnly`: bool




      :rtype: `bool`








   .. staticmethod:: GetGlobalFileName(szFile)




      :param `szFile`: 
      :type `szFile`: string




      :rtype: `string`








   .. staticmethod:: GetLocalFileName(szFile, style=0)




      :param `szFile`: 
      :type `szFile`: string
      :param `style`: 
      :type `style`: int




      :rtype: `string`








   .. method:: GetNumberOfEntries(self, bRecursive=False)

      Get number of entries in the current group.                  


      :param `bRecursive`: 
      :type `bRecursive`: bool




      :rtype: `int`








   .. method:: GetNumberOfGroups(self, bRecursive=False)

      Get number of entries/subgroups in the current group, with or without its subgroups.                  


      :param `bRecursive`: 
      :type `bRecursive`: bool




      :rtype: `int`








   .. method:: GetPath(self)

      Retrieve the current path (always as absolute path).                  

      :rtype: `string`








   .. method:: HasEntry(self, strName)



                


      :param `strName`: 
      :type `strName`: string




      :rtype: `bool`







      :returns: 

         ``True`` if the entry by this name exists.   








   .. method:: HasGroup(self, strName)



                


      :param `strName`: 
      :type `strName`: string




      :rtype: `bool`







      :returns: 

         ``True`` if the group by this name exists.   








   .. method:: RenameEntry(self, oldName, newName)

      Renames an entry in the current group.                  

      The entries names (both the old and the new one) shouldn't contain backslashes, i.e. only simple names and not arbitrary paths are accepted by this function. 

                


      :param `oldName`: 
      :type `oldName`: string
      :param `newName`: 
      :type `newName`: string




      :rtype: `bool`







      :returns: 

         ``False`` if `oldName`  doesn't exist or if `newName`  already exists.   








   .. method:: RenameGroup(self, oldName, newName)

      Renames a subgroup of the current group.                  

      The subgroup names (both the old and the new one) shouldn't contain backslashes, i.e. only simple names and not arbitrary paths are accepted by this function. 

                


      :param `oldName`: 
      :type `oldName`: string
      :param `newName`: 
      :type `newName`: string




      :rtype: `bool`







      :returns: 

         ``False`` if `oldName`  doesn't exist or if `newName`  already exists.   








   .. method:: Save(self, os)

      Saves all config data to the given stream, returns ``True`` if data was saved successfully or ``False`` on error.                  

      :rtype: `bool`








   .. method:: SetPath(self, strPath)

      Set current path: if the first character is '/', it is the absolute path, otherwise it is a relative path.                  

      '..' is supported. If `strPath`  doesn't exist, it is created. 

                


      :param `strPath`: 
      :type `strPath`: string






      .. seealso:: :ref:`wx.ConfigPathChanger`    








   .. method:: SetUmask(self, mode)

      Allows setting the mode to be used for the config file creation.                  

      For example, to create a config file which is not readable by other users (useful if it stores some sensitive information, such as passwords), you could use  ``SetUmask(0077)`` . 

      This function doesn't do anything on non-Unix platforms. 

                


      :param `mode`: 
      :type `mode`: int






      .. seealso:: ``CHANGE_UMASK``    








   .. attribute:: NumberOfEntries

      See :meth:`~wx.FileConfig.GetNumberOfEntries`


   .. attribute:: NumberOfGroups

      See :meth:`~wx.FileConfig.GetNumberOfGroups`


   .. attribute:: Path

      See :meth:`~wx.FileConfig.GetPath` and :meth:`~wx.FileConfig.SetPath`