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

==========================================================================================================================================
|phoenix_title|  **wx.FileCtrl**
==========================================================================================================================================

This control allows the user to select a file.          

Two implementations of this class exist, one for Gtk and another generic one for all the other ports. 

This class is only available if  ``USE_FILECTRL``   is set to 1. 





.. _FileCtrl-styles:

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

This class supports the following styles: 

  

- ``wx.FC_DEFAULT_STYLE``: The default style: ``wx.FC_OPEN``  
- ``wx.FC_OPEN``: Creates an file control suitable for opening files. Cannot be combined with ``wx.FC_SAVE``.  
- ``wx.FC_SAVE``: Creates an file control suitable for saving files. Cannot be combined with ``wx.FC_OPEN``.  
- ``wx.FC_MULTIPLE``: For open control only, Allows selecting multiple files. Cannot be combined with ``wx.FC_SAVE``  
- ``wx.FC_NOSHOWHIDDEN``: Hides the "Show Hidden Files" checkbox (Generic only)  








.. _FileCtrl-events:

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

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


- EVT_FILECTRL_FILEACTIVATED: The user activated a file(by double-clicking or pressing Enter)  
- EVT_FILECTRL_SELECTIONCHANGED: The user changed the current selection(by selecting or deselecting a file)  
- EVT_FILECTRL_FOLDERCHANGED: The current folder of the file control has been changed  
- EVT_FILECTRL_FILTERCHANGED: The current file filter of the file control has been changed. 

  .. versionadded:: 2.9.1.
     










Implementations:GTK port; a generic implementation is used elsewhere. 

         



.. seealso:: :ref:`wx.GenericDirCtrl`    







|

|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>FileCtrl</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.FileCtrl_inheritance.png" alt="Inheritance diagram of FileCtrl" 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.FileCtrl.html" title="wx.FileCtrl" alt="" coords="63,315,154,344"/> <area shape="rect" id="node2" href="wx.Control.html" title="wx.Control" alt="" coords="63,237,155,267"/> <area shape="rect" id="node3" href="wx.Window.html" title="wx.Window" alt="" coords="60,160,157,189"/> <area shape="rect" id="node4" href="wx.EvtHandler.html" title="wx.EvtHandler" alt="" coords="50,83,167,112"/> <area shape="rect" id="node5" href="wx.Object.html" title="wx.Object" alt="" coords="5,5,92,35"/> <area shape="rect" id="node6" href="wx.Trackable.html" title="wx.Trackable" alt="" coords="117,5,223,35"/> </map> 
   </p>
   </div>

|


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

|

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

   **wxMSW**


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

   **wxMAC**


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

   **wxGTK**


|


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

================================================================================ ================================================================================
:meth:`~wx.FileCtrl.__init__`                                                    
:meth:`~wx.FileCtrl.Create`                                                      Create function for two-step construction.
:meth:`~wx.FileCtrl.GetClassDefaultAttributes`                                   
:meth:`~wx.FileCtrl.GetDirectory`                                                Returns the current directory of the file control (i.e. the directory shown by it).
:meth:`~wx.FileCtrl.GetFilename`                                                 Returns the currently selected filename.
:meth:`~wx.FileCtrl.GetFilenames`                                                Returns a list of filenames selected in the control.  This function
:meth:`~wx.FileCtrl.GetFilterIndex`                                              Returns the zero-based index of the currently selected filter.
:meth:`~wx.FileCtrl.GetPath`                                                     Returns the full path (directory and filename) of the currently selected file.
:meth:`~wx.FileCtrl.GetPaths`                                                    Returns a list of the full paths (directory and filename) of the files
:meth:`~wx.FileCtrl.GetWildcard`                                                 Returns the current wildcard.
:meth:`~wx.FileCtrl.SetDirectory`                                                Sets(changes) the current directory displayed in the control.
:meth:`~wx.FileCtrl.SetFilename`                                                 Selects a certain file.
:meth:`~wx.FileCtrl.SetFilterIndex`                                              Sets the current filter index, starting from zero.
:meth:`~wx.FileCtrl.SetPath`                                                     Changes to a certain directory and selects a certain file.
:meth:`~wx.FileCtrl.SetWildcard`                                                 Sets the wildcard, which can contain multiple file types, for example: "``BMP`` files (.bmp)|.bmp|GIF files (.gif)|.gif".
:meth:`~wx.FileCtrl.ShowHidden`                                                  Sets whether hidden files and folders are shown or not.
================================================================================ ================================================================================


|


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

================================================================================ ================================================================================
:attr:`~wx.FileCtrl.Directory`                                                   See :meth:`~wx.FileCtrl.GetDirectory` and :meth:`~wx.FileCtrl.SetDirectory`
:attr:`~wx.FileCtrl.Filename`                                                    See :meth:`~wx.FileCtrl.GetFilename` and :meth:`~wx.FileCtrl.SetFilename`
:attr:`~wx.FileCtrl.Filenames`                                                   See :meth:`~wx.FileCtrl.GetFilenames`
:attr:`~wx.FileCtrl.FilterIndex`                                                 See :meth:`~wx.FileCtrl.GetFilterIndex` and :meth:`~wx.FileCtrl.SetFilterIndex`
:attr:`~wx.FileCtrl.Path`                                                        See :meth:`~wx.FileCtrl.GetPath` and :meth:`~wx.FileCtrl.SetPath`
:attr:`~wx.FileCtrl.Paths`                                                       See :meth:`~wx.FileCtrl.GetPaths`
:attr:`~wx.FileCtrl.Wildcard`                                                    See :meth:`~wx.FileCtrl.GetWildcard` and :meth:`~wx.FileCtrl.SetWildcard`
================================================================================ ================================================================================


|


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


.. class:: wx.FileCtrl(Control)

   **Possible constructors**::

       FileCtrl()
       
       FileCtrl(parent, id=ID_ANY, defaultDirectory=EmptyString,
                defaultFilename=EmptyString, wildCard=FileSelectorDefaultWildcardStr,
                style=FC_DEFAULT_STYLE, pos=DefaultPosition, size=DefaultSize,
                name=FileCtrlNameStr)
       
   
   This control allows the user to select a file.



   .. 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, defaultDirectory=EmptyString, defaultFilename=EmptyString, wildCard=FileSelectorDefaultWildcardStr, style=FC_DEFAULT_STYLE, pos=DefaultPosition, size=DefaultSize, name=FileCtrlNameStr)`
      
      Constructs the window.                  
      
      
      
      
      :param `parent`: Parent window, must not be non-NULL.   
      :type `parent`: wx.Window
      :param `id`: The identifier for the control.   
      :type `id`: wx.WindowID
      :param `defaultDirectory`: The initial directory shown in the control. Must be a valid path to a directory or the empty string. In case it is the empty string, the current working directory is used.   
      :type `defaultDirectory`: string
      :param `defaultFilename`: The default filename, or the empty string.   
      :type `defaultFilename`: string
      :param `wildCard`: A wildcard specifying which files can be selected, such as "x.x" or "``BMP`` files (.bmp)|.bmp|GIF files (.gif)|.gif".   
      :type `wildCard`: string
      :param `style`: The window style, see ``FC_`` flags.   
      :type `style`: long
      :param `pos`: Initial position.   
      :type `pos`: wx.Point
      :param `size`: Initial size.   
      :type `size`: wx.Size
      :param `name`: Control name.  
      :type `name`: string
      
      
      
      
      
      
      
      
      
      
      
      
      
      
      
      
      
      
      
      
                        
      
      
      
      :returns: 
      
         ``True`` if the control was successfully created or ``False`` if creation failed.   
      
      
      
      
      
      
      
      :html:`<hr class="overloadsep" /><br />`






   .. method:: Create(self, parent, id=ID_ANY, defaultDirectory=EmptyString, defaultFilename=EmptyString, wildCard=FileSelectorDefaultWildcardStr, style=FC_DEFAULT_STYLE, pos=DefaultPosition, size=DefaultSize, name=FileCtrlNameStr)

      Create function for two-step construction.                  

      See :ref:`wx.FileCtrl`  for details.                  


      :param `parent`: 
      :type `parent`: wx.Window
      :param `id`: 
      :type `id`: wx.WindowID
      :param `defaultDirectory`: 
      :type `defaultDirectory`: string
      :param `defaultFilename`: 
      :type `defaultFilename`: string
      :param `wildCard`: 
      :type `wildCard`: string
      :param `style`: 
      :type `style`: long
      :param `pos`: 
      :type `pos`: wx.Point
      :param `size`: 
      :type `size`: wx.Size
      :param `name`: 
      :type `name`: string




      :rtype: `bool`








   .. staticmethod:: GetClassDefaultAttributes(variant=WINDOW_VARIANT_NORMAL)




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




      :rtype: :ref:`wx.VisualAttributes`








   .. method:: GetDirectory(self)

      Returns the current directory of the file control (i.e. the directory shown by it).                  

      :rtype: `string`








   .. method:: GetFilename(self)

      Returns the currently selected filename.                  

      For the controls having the  ``FC_MULTIPLE``   style, use  :meth:`GetFilenames`   instead.                  

      :rtype: `string`








   .. method:: GetFilenames(self)

                      Returns a list of filenames selected in the control.  This function
                      should only be used with controls which have the wx.``wx.FC_MULTIPLE`` style,
                      use GetFilename for the others. 

      :rtype: `list of strings`








   .. method:: GetFilterIndex(self)

      Returns the zero-based index of the currently selected filter.                  

      :rtype: `int`








   .. method:: GetPath(self)

      Returns the full path (directory and filename) of the currently selected file.                  

      For the controls having the  ``FC_MULTIPLE``   style, use  :meth:`GetPaths`   instead.                  

      :rtype: `string`








   .. method:: GetPaths(self)

                      Returns a list of the full paths (directory and filename) of the files
                      chosen. This function should only be used with controlss which have
                      the wx.``wx.FC_MULTIPLE`` style, use GetPath for the others.
                 

      :rtype: `list of strings`








   .. method:: GetWildcard(self)

      Returns the current wildcard.                  

      :rtype: `string`








   .. method:: SetDirectory(self, directory)

      Sets(changes) the current directory displayed in the control.                  

                


      :param `directory`: 
      :type `directory`: string




      :rtype: `bool`







      :returns: 

         Returns ``True`` on success, ``False`` otherwise.   








   .. method:: SetFilename(self, filename)

      Selects a certain file.                  

                


      :param `filename`: 
      :type `filename`: string




      :rtype: `bool`







      :returns: 

         Returns ``True`` on success, ``False`` otherwise   








   .. method:: SetFilterIndex(self, filterIndex)

      Sets the current filter index, starting from zero.                  


      :param `filterIndex`: 
      :type `filterIndex`: int







   .. method:: SetPath(self, path)

      Changes to a certain directory and selects a certain file.                  

      If `path`  includes the directory part, it must exist, otherwise ``False`` is returned and nothing else is done. 

                


      :param `path`: 
      :type `path`: string




      :rtype: `bool`







      :returns: 

         Returns ``True`` on success, ``False`` otherwise   








   .. method:: SetWildcard(self, wildCard)

      Sets the wildcard, which can contain multiple file types, for example: "``BMP`` files (.bmp)|.bmp|GIF files (.gif)|.gif".                  


      :param `wildCard`: 
      :type `wildCard`: string







   .. method:: ShowHidden(self, show)

      Sets whether hidden files and folders are shown or not.                  


      :param `show`: 
      :type `show`: bool







   .. attribute:: Directory

      See :meth:`~wx.FileCtrl.GetDirectory` and :meth:`~wx.FileCtrl.SetDirectory`


   .. attribute:: Filename

      See :meth:`~wx.FileCtrl.GetFilename` and :meth:`~wx.FileCtrl.SetFilename`


   .. attribute:: Filenames

      See :meth:`~wx.FileCtrl.GetFilenames`


   .. attribute:: FilterIndex

      See :meth:`~wx.FileCtrl.GetFilterIndex` and :meth:`~wx.FileCtrl.SetFilterIndex`


   .. attribute:: Path

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


   .. attribute:: Paths

      See :meth:`~wx.FileCtrl.GetPaths`


   .. attribute:: Wildcard

      See :meth:`~wx.FileCtrl.GetWildcard` and :meth:`~wx.FileCtrl.SetWildcard`

