.. 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.DirPickerCtrl:

==========================================================================================================================================
|phoenix_title|  **wx.DirPickerCtrl**
==========================================================================================================================================

This control allows the user to select a directory.          

The generic implementation is a button which brings up a :ref:`wx.DirDialog`  when clicked. Native implementation may differ but this is usually a (small) widget which give access to the dir-chooser dialog. It is only available if  ``USE_DIRPICKERCTRL``   is set to 1 (the default). 

^^ 



.. _DirPickerCtrl-styles:

|styles| Window Styles
================================

This class supports the following styles: 

  

- ``wx.DIRP_DEFAULT_STYLE``: The default style: includes ``wx.DIRP_DIR_MUST_EXIST`` and, under wxMSW only, ``wx.DIRP_USE_TEXTCTRL``.  
- ``wx.DIRP_USE_TEXTCTRL``: Creates a text control to the left of the picker button which is completely managed by the :ref:`wx.DirPickerCtrl`  and which can be used by the user to specify a path (see SetPath). The text control is automatically synchronized with button's value. Use functions defined in :ref:`wx.PickerBase`  to modify the text control.  
- ``wx.DIRP_DIR_MUST_EXIST``: Creates a picker which allows selecting only existing directories in the popup :ref:`wx.DirDialog`. Notice that, as with  ``FLP_FILE_MUST_EXIST`` , it is still possible to enter a non-existent directory even when this file is specified if   ``DIRP_USE_TEXTCTRL``   style is also used. Also note that if   ``DIRP_USE_TEXTCTRL``   is not used, the native wxGTK implementation always uses this style as it doesn't support selecting non-existent directories.   
- ``wx.DIRP_CHANGE_DIR``: Change current working directory on each user directory selection change.  
- ``wx.DIRP_SMALL``: Use smaller version of the control with a small "..." button instead of the normal "Browse" one. This flag is new since wxWidgets 2.9.3. ^^ 

^^






.. _DirPickerCtrl-events:

|events| Events Emitted by this Class
=====================================

Handlers bound for the following event types will receive a :ref:`wx.FileDirPickerEvent` parameter.


- EVT_DIRPICKER_CHANGED: The user changed the directory selected in the control either using the button or using text control (see ``wx.DIRP_USE_TEXTCTRL``; note that in this case the event is fired only if the user's input is valid, e.g. an existing directory path). ^^ 






         



.. seealso:: :ref:`wx.DirDialog`, :ref:`wx.FileDirPickerEvent`    







|

|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>DirPickerCtrl</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.DirPickerCtrl_inheritance.png" alt="Inheritance diagram of DirPickerCtrl" 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.DirPickerCtrl.html" title="This control allows the user to select a directory." alt="" coords="45,392,165,421"/> <area shape="rect" id="node2" href="wx.PickerBase.html" title="Base abstract class for all pickers which support an auxiliary text control." alt="" coords="49,315,161,344"/> <area shape="rect" id="node3" href="wx.Control.html" title="This is the base class for a control or 'widget'." alt="" coords="61,237,149,267"/> <area shape="rect" id="node4" href="wx.Window.html" title="wx.Window  is the base class for all windows and represents any visible object on screen." alt="" coords="61,160,150,189"/> <area shape="rect" id="node5" href="wx.EvtHandler.html" title="A class that can handle events from the windowing system." alt="" coords="49,83,161,112"/> <area shape="rect" id="node6" href="wx.Object.html" title="This is the root class of many of the wxWidgets classes." alt="" coords="5,5,88,35"/> <area shape="rect" id="node7" href="wx.Trackable.html" title="Add-on base class for a trackable object." alt="" coords="113,5,215,35"/> </map> 
   </p>
   </div>

|


|appearance| Control Appearance
===============================

|

.. figure:: _static/images/widgets/fullsize/wxmsw/wx.dirpickerctrl.png
   :alt: wxMSW
   :figclass: floatleft

   **wxMSW**


.. figure:: _static/images/widgets/fullsize/wxmac/wx.dirpickerctrl.png
   :alt: wxMAC
   :figclass: floatright

   **wxMAC**


.. figure:: _static/images/widgets/fullsize/wxgtk/wx.dirpickerctrl.png
   :alt: wxGTK
   :figclass: floatcenter

   **wxGTK**


|


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

================================================================================ ================================================================================
:meth:`~wx.DirPickerCtrl.__init__`                                               
:meth:`~wx.DirPickerCtrl.Create`                                                 Creates the widgets with the given parameters.
:meth:`~wx.DirPickerCtrl.GetClassDefaultAttributes`                              
:meth:`~wx.DirPickerCtrl.GetPath`                                                Returns the absolute path of the currently selected directory.
:meth:`~wx.DirPickerCtrl.SetInitialDirectory`                                    Set the directory to show when starting to browse for directories.
:meth:`~wx.DirPickerCtrl.SetPath`                                                Sets the absolute path of the currently selected directory.
================================================================================ ================================================================================


|


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

================================================================================ ================================================================================
:attr:`~wx.DirPickerCtrl.Path`                                                   See :meth:`~wx.DirPickerCtrl.GetPath` and :meth:`~wx.DirPickerCtrl.SetPath`
================================================================================ ================================================================================


|


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


.. class:: wx.DirPickerCtrl(PickerBase)

   **Possible constructors**::

       DirPickerCtrl()
       
       DirPickerCtrl(parent, id=ID_ANY, path="",
                     message=DirSelectorPromptStr, pos=DefaultPosition, size=DefaultSize,
                     style=DIRP_DEFAULT_STYLE, validator=DefaultValidator,
                     name=DirPickerCtrlNameStr)
       
   
   This control allows the user to select a directory.



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



      |overload| Overloaded Implementations:

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

      
      **__init__** `(self)`
      
      
      
      
      
      :html:`<hr class="overloadsep" /><br />`

      
      **__init__** `(self, parent, id=ID_ANY, path="", message=DirSelectorPromptStr, pos=DefaultPosition, size=DefaultSize, style=DIRP_DEFAULT_STYLE, validator=DefaultValidator, name=DirPickerCtrlNameStr)`
      
      Initializes the object and calls :meth:`Create`   with all the parameters.                  
      
      
      :param `parent`: 
      :type `parent`: wx.Window
      :param `id`: 
      :type `id`: wx.WindowID
      :param `path`: 
      :type `path`: string
      :param `message`: 
      :type `message`: string
      :param `pos`: 
      :type `pos`: wx.Point
      :param `size`: 
      :type `size`: wx.Size
      :param `style`: 
      :type `style`: long
      :param `validator`: 
      :type `validator`: wx.Validator
      :param `name`: 
      :type `name`: string
      
      
      
      
      
      
      :html:`<hr class="overloadsep" /><br />`






   .. method:: Create(self, parent, id=ID_ANY, path="", message=DirSelectorPromptStr, pos=DefaultPosition, size=DefaultSize, style=DIRP_DEFAULT_STYLE, validator=DefaultValidator, name=DirPickerCtrlNameStr)

      Creates the widgets with the given parameters.                  




      :param `parent`: Parent window, must not be not ``None``.   
      :type `parent`: wx.Window
      :param `id`: The identifier for the control.   
      :type `id`: wx.WindowID
      :param `path`: The initial directory shown in the control. Must be a valid path to a directory or the empty string.   
      :type `path`: string
      :param `message`: The message shown to the user in the :ref:`wx.DirDialog`  shown by the control.   
      :type `message`: string
      :param `pos`: Initial position.   
      :type `pos`: wx.Point
      :param `size`: Initial size.   
      :type `size`: wx.Size
      :param `style`: The window style, see ``DIRP_`` flags.   
      :type `style`: long
      :param `validator`: Validator which can be used for additional data checks.   
      :type `validator`: wx.Validator
      :param `name`: Control name.  
      :type `name`: string






















      :rtype: `bool`



                  



      :returns: 

         ``True`` if the control was successfully created or ``False`` if creation failed.   








   .. staticmethod:: GetClassDefaultAttributes(variant=WINDOW_VARIANT_NORMAL)




      :param `variant`: 
      :type `variant`: wx.WindowVariant




      :rtype: :ref:`wx.VisualAttributes`








   .. method:: GetPath(self)

      Returns the absolute path of the currently selected directory.                  

      :rtype: `string`








   .. method:: SetInitialDirectory(self, dir)

      Set the directory to show when starting to browse for directories.                  

      This function is mostly useful for the directory picker controls which have no selection initially to configure the directory that should be shown if the user starts browsing for directories as otherwise the initially selected directory is used, which is usually the desired behaviour and so the directory specified by this function is ignored in this case. 

                


      :param `dir`: 
      :type `dir`: string






      .. versionadded:: 2.9.4 
     








   .. method:: SetPath(self, dirname)

      Sets the absolute path of the currently selected directory.                  

      If the control uses  ``DIRP_DIR_MUST_EXIST``   and does not use   ``DIRP_USE_TEXTCTRL``   style, the  `dirname`  must be a name of an existing directory and will be simply ignored by the native wxGTK implementation if this is not the case.                  


      :param `dirname`: 
      :type `dirname`: string







   .. attribute:: Path

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