.. wxPython Phoenix documentation

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

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

.. include:: headings.inc



.. _wx.FileDialog:

==========================================================================================================================================
|phoenix_title|  **wx.FileDialog**
==========================================================================================================================================

This class represents the file chooser dialog.          

The path and filename are distinct elements of a full file pathname. If path is :meth:`~wx.FileDialog.EmptyString`, the current directory will be used. If filename is :meth:`~wx.FileDialog.EmptyString`, no default filename will be supplied. The wildcard determines what files are displayed in the file selector, and file extension supplies a type extension for the required filename. 

The typical usage for the open file dialog is: ::

        def OnOpen(self, event):

            if self.contentNotSaved:
                if wx.MessageBox("Current content has not been saved! Proceed?", "Please confirm",
                                 wx.ICON_QUESTION | wx.YES_NO, self) == wx.NO:
                    return

            # otherwise ask the user what new file to open
            with wx.FileDialog(self, "Open XYZ file", wildcard="XYZ files (*.xyz)|*.xyz",
                               style=wx.FD_OPEN | wx.FD_FILE_MUST_EXIST) as fileDialog:

                if fileDialog.ShowModal() == wx.ID_CANCEL:
                    return     # the user changed their mind

                # Proceed loading the file chosen by the user
                pathname = fileDialog.GetPath()
                try:
                    with open(pathname, 'r') as file:
                        self.doLoadDataOrWhatever(file)
                except IOError:
                    wx.LogError("Cannot open file '%s'." % newfile)



The typical usage for the save file dialog is instead somewhat simpler: ::

        def OnSaveAs(self, event):

            with wx.FileDialog(self, "Save XYZ file", wildcard="XYZ files (*.xyz)|*.xyz",
                               style=wx.FD_SAVE | wx.FD_OVERWRITE_PROMPT) as fileDialog:

                if fileDialog.ShowModal() == wx.ID_CANCEL:
                    return     # the user changed their mind

                # save the current contents in the file
                pathname = fileDialog.GetPath()
                try:
                    with open(pathname, 'w') as file:
                        self.doSaveData(file)
                except IOError:
                    wx.LogError("Cannot save current data in file '%s'." % pathname)







.. _FileDialog-styles:

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

This class supports the following styles: 

  

- ``wx.FD_DEFAULT_STYLE``: Equivalent to  ``FD_OPEN`` .   
- ``wx.FD_OPEN``: This is an open dialog; usually this means that the default button's label of the dialog is "Open". Cannot be combined with  ``FD_SAVE`` .   
- ``wx.FD_SAVE``: This is a save dialog; usually this means that the default button's label of the dialog is "Save". Cannot be combined with  ``FD_OPEN`` .   
- ``wx.FD_OVERWRITE_PROMPT``: For save dialog only: prompt for a confirmation if a file will be overwritten.  
- ``wx.FD_FILE_MUST_EXIST``: For open dialog only: the user may only select files that actually exist. Notice that under OS X the file dialog with  ``FD_OPEN``   style always behaves as if this style was specified, because it is impossible to choose a file that doesn't exist from a standard OS X file dialog.   
- ``wx.FD_MULTIPLE``: For open dialog only: allows selecting multiple files.  
- ``wx.FD_CHANGE_DIR``: Change the current working directory (when the dialog is dismissed) to the directory where the file(s) chosen by the user are.  
- ``wx.FD_PREVIEW``: Show the preview of the selected files (currently only supported by wxGTK).  








         



.. note:: 

   All implementations of the :ref:`wx.FileDialog`  provide a wildcard filter. Typing a filename containing wildcards (, ?) in the filename text item, and clicking on Ok, will result in only those files matching the pattern being displayed. The wildcard may be a specification for multiple types of file with a description for each, such as: ::

                   wildcard = "BMP and GIF files (*.bmp;*.gif)|*.bmp;*.gif|PNG files (*.png)|*.png"

   It must be noted that wildcard support in the native Motif file dialog is quite limited: only one file type is supported, and it is displayed without the descriptive test; "``BMP`` files (.bmp)|.bmp" is displayed as "x.bmp", and both "``BMP`` files (.bmp)|.bmp|GIF files (.gif)|.gif" and "Image files|.bmp;.gif" are errors.  







.. seealso:: :ref:`FileDialog Overview <filedialog overview>`, :ref:`wx.FileSelector`    







|

|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>FileDialog</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.FileDialog_inheritance.png" alt="Inheritance diagram of FileDialog" usemap="#dummy" class="inheritance"/></center>
   </div>
   <script type="text/javascript">toggleVisibilityOnLoad(document.getElementById('toggleBlock'))</script>
   <map id="dummy" name="dummy"> <area shape="rect" id="node1" href="wx.Trackable.html" title="wx.Trackable" alt="" coords="5,5,107,35"/> <area shape="rect" id="node6" href="wx.EvtHandler.html" title="wx.EvtHandler" alt="" coords="57,83,168,112"/> <area shape="rect" id="node2" href="wx.Object.html" title="wx.Object" alt="" coords="131,5,212,35"/> <area shape="rect" id="node3" href="wx.NonOwnedWindow.html" title="wx.NonOwnedWindow" alt="" coords="34,237,192,267"/> <area shape="rect" id="node5" href="wx.TopLevelWindow.html" title="wx.TopLevelWindow" alt="" coords="42,315,184,344"/> <area shape="rect" id="node4" href="wx.Window.html" title="wx.Window" alt="" coords="69,160,157,189"/> <area shape="rect" id="node8" href="wx.Dialog.html" title="wx.Dialog" alt="" coords="72,392,153,421"/> <area shape="rect" id="node7" href="wx.FileDialog.html" title="wx.FileDialog" alt="" coords="62,469,164,499"/> </map> 
   </p>

|


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

================================================================================ ================================================================================
:meth:`~wx.FileDialog.__init__`                                                  Constructor.
:meth:`~wx.FileDialog.GetCurrentlySelectedFilename`                              Returns the path of the file currently selected in dialog.
:meth:`~wx.FileDialog.GetDirectory`                                              Returns the default directory.
:meth:`~wx.FileDialog.GetExtraControl`                                           If functions :meth:`~FileDialog.SetExtraControlCreator`   and :meth:`~FileDialog.ShowModal`   were called, returns the extra window.
:meth:`~wx.FileDialog.GetFilename`                                               Returns the default filename.
:meth:`~wx.FileDialog.GetFilenames`                                              Returns a list of filenames chosen in the dialog.  This function
:meth:`~wx.FileDialog.GetFilterIndex`                                            Returns the index into the list of filters supplied, optionally, in the wildcard parameter.
:meth:`~wx.FileDialog.GetMessage`                                                Returns the message that will be displayed on the dialog.
:meth:`~wx.FileDialog.GetPath`                                                   Returns the full path (directory and filename) of the selected file.
:meth:`~wx.FileDialog.GetPaths`                                                  Returns a list of the full paths of the files chosen. This function
:meth:`~wx.FileDialog.GetWildcard`                                               Returns the file dialog wildcard.
:meth:`~wx.FileDialog.SetDirectory`                                              Sets the default directory.
:meth:`~wx.FileDialog.SetFilename`                                               Sets the default filename.
:meth:`~wx.FileDialog.SetFilterIndex`                                            Sets the default filter index, starting from zero.
:meth:`~wx.FileDialog.SetMessage`                                                Sets the message that will be displayed on the dialog.
:meth:`~wx.FileDialog.SetPath`                                                   Sets the path (the combined directory and filename that will be returned when the dialog is dismissed).
:meth:`~wx.FileDialog.SetWildcard`                                               Sets the wildcard, which can contain multiple file types, for example: "``BMP`` files (.bmp)|.bmp|GIF files (.gif)|.gif".
:meth:`~wx.FileDialog.ShowModal`                                                 Shows the dialog, returning  ``ID_OK``   if the user pressed ``wx.OK``, and   ``ID_CANCEL``   otherwise.
================================================================================ ================================================================================


|


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

================================================================================ ================================================================================
:attr:`~wx.FileDialog.CurrentlySelectedFilename`                                 See :meth:`~wx.FileDialog.GetCurrentlySelectedFilename`
:attr:`~wx.FileDialog.Directory`                                                 See :meth:`~wx.FileDialog.GetDirectory` and :meth:`~wx.FileDialog.SetDirectory`
:attr:`~wx.FileDialog.ExtraControl`                                              See :meth:`~wx.FileDialog.GetExtraControl`
:attr:`~wx.FileDialog.Filename`                                                  See :meth:`~wx.FileDialog.GetFilename` and :meth:`~wx.FileDialog.SetFilename`
:attr:`~wx.FileDialog.Filenames`                                                 See :meth:`~wx.FileDialog.GetFilenames`
:attr:`~wx.FileDialog.FilterIndex`                                               See :meth:`~wx.FileDialog.GetFilterIndex` and :meth:`~wx.FileDialog.SetFilterIndex`
:attr:`~wx.FileDialog.Message`                                                   See :meth:`~wx.FileDialog.GetMessage` and :meth:`~wx.FileDialog.SetMessage`
:attr:`~wx.FileDialog.Path`                                                      See :meth:`~wx.FileDialog.GetPath` and :meth:`~wx.FileDialog.SetPath`
:attr:`~wx.FileDialog.Paths`                                                     See :meth:`~wx.FileDialog.GetPaths`
:attr:`~wx.FileDialog.Wildcard`                                                  See :meth:`~wx.FileDialog.GetWildcard` and :meth:`~wx.FileDialog.SetWildcard`
================================================================================ ================================================================================


|


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


.. class:: wx.FileDialog(Dialog)

   **Possible constructors**::

       FileDialog(parent, message=FileSelectorPromptStr,
                  defaultDir=EmptyString, defaultFile=EmptyString,
                  wildcard=FileSelectorDefaultWildcardStr, style=FD_DEFAULT_STYLE,
                  pos=DefaultPosition, size=DefaultSize, name=FileDialogNameStr)
       
   
   This class represents the file chooser dialog.



   .. method:: __init__(self, parent, message=FileSelectorPromptStr, defaultDir=EmptyString, defaultFile=EmptyString, wildcard=FileSelectorDefaultWildcardStr, style=FD_DEFAULT_STYLE, pos=DefaultPosition, size=DefaultSize, name=FileDialogNameStr)

      Constructor.                  

      Use :meth:`ShowModal`   to show the dialog. 




      :param `parent`: Parent window.   
      :type `parent`: wx.Window
      :param `message`: Message to show on the dialog.   
      :type `message`: string
      :param `defaultDir`: The default directory, or the empty string.   
      :type `defaultDir`: string
      :param `defaultFile`: The default filename, or the empty string.   
      :type `defaultFile`: string
      :param `wildcard`: A wildcard, such as "x.x" or "``BMP`` files (.bmp)|.bmp|GIF files (.gif)|.gif". Note that the native Motif dialog has some limitations with respect to wildcards; see the Remarks section above.   
      :type `wildcard`: string
      :param `style`: A dialog style. See  ``FD_*``   styles for more info.    
      :type `style`: long
      :param `pos`: Dialog position. Not implemented.   
      :type `pos`: wx.Point
      :param `size`: Dialog size. Not implemented.   
      :type `size`: wx.Size
      :param `name`: Dialog name. Not implemented.   
      :type `name`: string




















                  





   .. method:: GetCurrentlySelectedFilename(self)

      Returns the path of the file currently selected in dialog.                  

      Notice that this file is not necessarily going to be accepted by the user, so calling this function mostly makes sense from an update UI event handler of a custom file dialog extra control to update its state depending on the currently selected file. 

      Currently this function is fully implemented under GTK and MSW and always returns an empty string elsewhere. 

                

      :rtype: `string`







      :returns: 

         The path of the currently selected file or an empty string if nothing is selected.  







      .. versionadded:: 2.9.5 
    







      .. seealso:: :meth:`SetExtraControlCreator`     








   .. method:: GetDirectory(self)

      Returns the default directory.                  

      :rtype: `string`








   .. method:: GetExtraControl(self)

      If functions :meth:`SetExtraControlCreator`   and :meth:`ShowModal`   were called, returns the extra window.                  

      Otherwise returns ``None``. 

                

      :rtype: :ref:`wx.Window`







      .. versionadded:: 2.9.0 
     








   .. method:: GetFilename(self)

      Returns the default filename.                  

      :rtype: `string`








   .. method:: GetFilenames(self)

                      Returns a list of filenames chosen in the dialog.  This function
                      should only be used with the dialogs which have wx.``MULTIPLE`` style,
                      use GetFilename for the others. 

      :rtype: `list of strings`








   .. method:: GetFilterIndex(self)

      Returns the index into the list of filters supplied, optionally, in the wildcard parameter.                  

      Before the dialog is shown, this is the index which will be used when the dialog is first displayed. 

      After the dialog is shown, this is the index selected by the user.                  

      :rtype: `int`








   .. method:: GetMessage(self)

      Returns the message that will be displayed on the dialog.                  

      :rtype: `string`








   .. method:: GetPath(self)

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

      :rtype: `string`








   .. method:: GetPaths(self)

                      Returns a list of the full paths of the files chosen. This function
                      should only be used with the dialogs which have wx.``MULTIPLE`` style, use
                      GetPath for the others.
                 

      :rtype: `list of strings`








   .. method:: GetWildcard(self)

      Returns the file dialog wildcard.                  

      :rtype: `string`








   .. method:: SetDirectory(self, directory)

      Sets the default directory.                  


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







   .. method:: SetFilename(self, setfilename)

      Sets the default filename.                  

      In wxGTK this will have little effect unless a default directory has previously been set.                  


      :param `setfilename`: 
      :type `setfilename`: string







   .. method:: SetFilterIndex(self, filterIndex)

      Sets the default filter index, starting from zero.                  


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







   .. method:: SetMessage(self, message)

      Sets the message that will be displayed on the dialog.                  


      :param `message`: 
      :type `message`: string







   .. method:: SetPath(self, path)

      Sets the path (the combined directory and filename that will be returned when the dialog is dismissed).                  


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







   .. method:: SetWildcard(self, wildCard)

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

      Note that the native Motif dialog has some limitations with respect to wildcards; see the Remarks section above.                  


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







   .. method:: ShowModal(self)

      Shows the dialog, returning  ``ID_OK``   if the user pressed ``wx.OK``, and   ``ID_CANCEL``   otherwise.                   

      :rtype: `int`








   .. attribute:: CurrentlySelectedFilename

      See :meth:`~wx.FileDialog.GetCurrentlySelectedFilename`


   .. attribute:: Directory

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


   .. attribute:: ExtraControl

      See :meth:`~wx.FileDialog.GetExtraControl`


   .. attribute:: Filename

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


   .. attribute:: Filenames

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


   .. attribute:: FilterIndex

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


   .. attribute:: Message

      See :meth:`~wx.FileDialog.GetMessage` and :meth:`~wx.FileDialog.SetMessage`


   .. attribute:: Path

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


   .. attribute:: Paths

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


   .. attribute:: Wildcard

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

