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 "" the current directory will be used. If filename is "" 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)

phoenix_title Wildcard Filters

All implementations of the 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"

On Mac macOS in the open file dialog the filter choice box is not shown by default. Instead all given wildcards are applied at the same time: So in the above example all bmp, gif and png files are displayed. To enforce the display of the filter choice set the corresponding wx.SystemOptions before calling the file open dialog:

wx.SystemOptions.SetOption(wx.OSX_FILEDIALOG_ALWAYS_SHOW_TYPES, 1)

But in contrast to Windows and Unix, where the file type choice filters only the selected files, on Mac macOS even in this case the dialog shows all files matching all file types. The files which does not match the currently selected file type are greyed out and are not selectable.

phoenix_title Dialog Customization

Uniquely among the other standard dialogs, wx.FileDialog can be customized by adding extra controls to it. Moreover, there are two ways to do it: the first one is to define a callback function and use SetExtraControlCreator to tell the dialog to call it, while the second one requires defining a class inheriting from wx.FileDialogCustomizeHook and implementing its virtual functions, notably wx.FileDialogCustomizeHook.AddCustomControls where the extra controls have to be created, and finally calling SetCustomizeHook with this custom hook object. The first approach is somewhat simpler and more flexible, as it allows to create any kind of custom controls, but is not supported by the “new style” (where “new” means used since Windows Vista, i.e. circa 2007) file dialogs under MSW. Because of this, calling SetExtraControlCreator in wxMSW forces the use of old style (Windows XP) dialogs, that may look out of place. The second approach is implemented by the MSW dialogs natively and doesn’t suffer from this limitation, so its use is recommended, especially if the few simple control types supported by it (see wx.FileDialogCustomize for more information about the supported controls) are sufficient for your needs. Both of the approaches to the dialog customization are demonstrated in the Dialogs Sample, please check it for more details.

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. This style is always enabled on wxOSX and cannot be disabled.

  • wx.FD_NO_FOLLOW: Directs the dialog to return the path and file name of the selected shortcut file, not its target as it does by default. Currently this flag is only implemented in wxMSW and wxOSX (where it prevents aliases from being resolved). The non-dereferenced link path is always returned, even without this flag, under Unix and so using it there doesn’t do anything. This flag was added in wxWidgets 3.1.0.

  • wx.FD_FILE_MUST_EXIST: For open dialog only: the user may only select files that actually exist. Notice that under macOS 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 macOS 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).

  • wx.FD_SHOW_HIDDEN: Show hidden files. This flag was added in wxWidgets 3.1.3 ^^

Note

New style file dialogs can only be used in wxMSW when the apartment, COM threading model is used. This is the case by default, but if the application initializes COM on its own using multi-threaded model, old style dialogs are used, at least when they must have a parent, as the new style dialog doesn’t support this threading model.

class_hierarchy Class Hierarchy

Inheritance diagram for class FileDialog:

appearance Control Appearance


wxMSW

wxMSW

wxMAC

wxMAC

wxGTK

wxGTK


method_summary Methods Summary

__init__

Constructor.

AddShortcut

Add a directory to the list of shortcuts shown in the dialog.

GetClassDefaultAttributes

GetCurrentlySelectedFilename

Returns the path of the file currently selected in dialog.

GetCurrentlySelectedFilterIndex

Returns the file type filter index currently selected in dialog.

GetDirectory

Returns the default directory.

GetExtraControl

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

GetFilename

Returns the default filename.

GetFilenames

Returns a list of filenames chosen in the dialog. This function

GetFilterIndex

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

GetMessage

Returns the message that will be displayed on the dialog.

GetPath

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

GetPaths

Returns a list of the full paths of the files chosen. This function

GetWildcard

Returns the file dialog wildcard.

SetCustomizeHook

Set the hook to be used for customizing the dialog contents.

SetDirectory

Sets the default directory.

SetFilename

Sets the default filename.

SetFilterIndex

Sets the default filter index, starting from zero.

SetMessage

Sets the message that will be displayed on the dialog.

SetPath

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

SetWildcard

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

ShowModal

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


property_summary Properties Summary

CurrentlySelectedFilename

See GetCurrentlySelectedFilename

CurrentlySelectedFilterIndex

See GetCurrentlySelectedFilterIndex

Directory

See GetDirectory and SetDirectory

ExtraControl

See GetExtraControl

Filename

See GetFilename and SetFilename

Filenames

See GetFilenames

FilterIndex

See GetFilterIndex and SetFilterIndex

Message

See GetMessage and SetMessage

Path

See GetPath and SetPath

Paths

See GetPaths

Wildcard

See GetWildcard and SetWildcard


api Class API

class wx.FileDialog(Dialog)

Possible constructors:

FileDialog(parent, message=FileSelectorPromptStr,
           defaultDir="", defaultFile="",
           wildcard=FileSelectorDefaultWildcardStr, style=FD_DEFAULT_STYLE,
           pos=DefaultPosition, size=DefaultSize, name=FileDialogNameStr)

This class represents the file chooser dialog.


Methods

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

Constructor.

Use ShowModal to show the dialog.

Parameters:
  • parent (wx.Window) – Parent window.

  • message (string) – Message to show on the dialog.

  • defaultDir (string) – The default directory, or the empty string.

  • defaultFile (string) – The default filename, or the empty string.

  • wildcard (string) – 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.

  • style (long) – A dialog style. See FD_* styles for more info.

  • pos (wx.Point) – Dialog position. Not implemented.

  • size (wx.Size) – Dialog size. Not implemented.

  • name (string) – Dialog name. Not implemented.



AddShortcut(self, directory, flags=0)

Add a directory to the list of shortcuts shown in the dialog.

File dialogs on many platforms display a fixed list of directories which can be easily selected by the user. This function allows to add an application-defined directory to this list, which can be convenient for the programs that use specific directories for their files instead of the default user document directory (see wx.StandardPaths).

Currently this function is only implemented in wxMSW and wxGTK and does nothing under the other platforms. Moreover, in wxMSW this function is incompatible with the use of SetExtraControlCreator , if you need to use this function and customize the dialog contents, please use the newer SetCustomizeHook instead.

The dialogs sample shows the use of this function by adding two custom shortcuts corresponding to the subdirectories of WXWIN environment variable if it is defined.

Parameters:
  • directory (string) – The full path to the directory, which should exist.

  • flags (int) – Can be set to FD_SHORTCUT_BOTTOM (which is also the default behaviour) to add the shortcut after the existing ones, or FD_SHORTCUT_TOP to add it before them. Support for the latter flag is only available in wxMSW, in wxGTK the shortcuts are always added to the bottom of the list.

Return type:

bool

Returns:

True on success or False if shortcut couldn’t be added, e.g. because this functionality is not available on the current platform.

New in version 4.2/wxWidgets-3.2.1.

Note

In wxMSW, the shortcuts appear in a separate section called “Application Links” by default. To change the title of this section, the application can specify a value of the FileDescription field of the version information structure in its resource file –



static GetClassDefaultAttributes(variant=WINDOW_VARIANT_NORMAL)
Parameters:

variant (WindowVariant) –

Return type:

wx.VisualAttributes



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.

Return type:

string

Returns:

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

New in version 2.9.5.

See also

SetExtraControlCreator



GetCurrentlySelectedFilterIndex(self)

Returns the file type filter index currently selected in dialog.

Notice that this file type filter is not necessarily going to be the one finally 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 type filter.

Currently this function is fully implemented under macOS and MSW and always returns NOT_FOUND elsewhere.

Return type:

int

Returns:

The 0-based index of the currently selected file type filter or wx.NOT_FOUND if nothing is selected.

New in version 4.1/wxWidgets-3.1.3: - MSW

New in version 4.1/wxWidgets-3.1.5: - macOS

See also

SetExtraControlCreator

See also

GetFilterIndex

See also

SetFilterIndex



GetDirectory(self)

Returns the default directory.

Return type:

string



GetExtraControl(self)

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

Otherwise returns None.

Return type:

wx.Window

New in version 2.9.0.



GetFilename(self)

Returns the default filename.

Return type:

string

Note

This function can’t be used with dialogs which have the FD_MULTIPLE style, use GetFilenames instead.



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.

Return type:

list of strings



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.

Return type:

int



GetMessage(self)

Returns the message that will be displayed on the dialog.

Return type:

string



GetPath(self)

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

Return type:

string

Note

This function can’t be used with dialogs which have the FD_MULTIPLE style, use GetPaths instead.



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.

Return type:

list of strings



GetWildcard(self)

Returns the file dialog wildcard.

Return type:

string



SetCustomizeHook(self, customizeHook)

Set the hook to be used for customizing the dialog contents.

This function can be called before calling ShowModal to specify that the dialog contents should be customized using the provided hook. See wx.FileDialogCustomizeHook documentation and Dialogs Sample for the examples of using it.

Parameters:

customizeHook (wx.FileDialogCustomizeHook) – The hook object that will be used by the dialog. This object must remain valid at least until ShowModal returns.

Return type:

bool

Returns:

True if the hook was successfully set or False if customizing the file dialog is not supported by the current platform.

New in version 4.1/wxWidgets-3.1.7.

Note

In order to define a custom hook object, /filedlgcustomize.h must be included in addition to the usual /filedlg.h header.



SetDirectory(self, directory)

Sets the default directory.

Parameters:

directory (string) –



SetFilename(self, setfilename)

Sets the default filename.

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

Parameters:

setfilename (string) –



SetFilterIndex(self, filterIndex)

Sets the default filter index, starting from zero.

Parameters:

filterIndex (int) –



SetMessage(self, message)

Sets the message that will be displayed on the dialog.

Parameters:

message (string) –



SetPath(self, path)

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

Parameters:

path (string) –



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.

Parameters:

wildCard (string) –



ShowModal(self)

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

Return type:

int


Properties

CurrentlySelectedFilename

See GetCurrentlySelectedFilename



CurrentlySelectedFilterIndex

See GetCurrentlySelectedFilterIndex



Directory

See GetDirectory and SetDirectory



ExtraControl

See GetExtraControl



Filename

See GetFilename and SetFilename



Filenames

See GetFilenames



FilterIndex

See GetFilterIndex and SetFilterIndex



Message

See GetMessage and SetMessage



Path

See GetPath and SetPath



Paths

See GetPaths



Wildcard

See GetWildcard and SetWildcard