| 1 | \section{\class{wxFileDialog}}\label{wxfiledialog} |
| 2 | |
| 3 | This class represents the file chooser dialog. |
| 4 | |
| 5 | \wxheading{Derived from} |
| 6 | |
| 7 | \helpref{wxDialog}{wxdialog}\\ |
| 8 | \helpref{wxWindow}{wxwindow}\\ |
| 9 | \helpref{wxEvtHandler}{wxevthandler}\\ |
| 10 | \helpref{wxObject}{wxobject} |
| 11 | |
| 12 | \wxheading{Include files} |
| 13 | |
| 14 | <wx/filedlg.h> |
| 15 | |
| 16 | \wxheading{See also} |
| 17 | |
| 18 | \helpref{wxFileDialog overview}{wxfiledialogoverview}, \helpref{wxFileSelector}{wxfileselector} |
| 19 | |
| 20 | \wxheading{Remarks} |
| 21 | |
| 22 | Pops up a file selector box. In Windows and GTK2.4+, this is the common |
| 23 | file selector dialog. In X, this is a file selector box with somewhat less |
| 24 | functionality. The path and filename are distinct elements of a full file pathname. |
| 25 | If path is ``", the current directory will be used. If filename is ``", |
| 26 | no default filename will be supplied. The wildcard determines what files |
| 27 | are displayed in the file selector, and file extension supplies a type |
| 28 | extension for the required filename. Flags may be a combination of wxOPEN, |
| 29 | wxSAVE, wxOVERWRITE\_PROMPT, wxHIDE\_READONLY, wxFILE\_MUST\_EXIST, |
| 30 | wxMULTIPLE, wxCHANGE\_DIR or 0. |
| 31 | |
| 32 | Both the X and Windows versions implement a wildcard filter. Typing a |
| 33 | filename containing wildcards (*, ?) in the filename text item, and |
| 34 | clicking on Ok, will result in only those files matching the pattern being |
| 35 | displayed. The wildcard may be a specification for multiple |
| 36 | types of file with a description for each, such as: |
| 37 | |
| 38 | \begin{verbatim} |
| 39 | "BMP and GIF files (*.bmp;*.gif)|*.bmp;*.gif|PNG files (*.png)|*.png" |
| 40 | \end{verbatim} |
| 41 | |
| 42 | It must be noted that wildcard support in the native Motif file |
| 43 | dialog is quite limited: only one alternative is supported, |
| 44 | and it is displayed without the descriptive test; ``BMP files (*.bmp)|*.bmp'' |
| 45 | is displayed as ``*.bmp'', and both |
| 46 | ``BMP files (*.bmp)|*.bmp|GIF files (*.gif)|*.gif'' and |
| 47 | ``Image files|*.bmp;*.gif'' are errors. |
| 48 | |
| 49 | \latexignore{\rtfignore{\wxheading{Members}}} |
| 50 | |
| 51 | \membersection{wxFileDialog::wxFileDialog}\label{wxfiledialogctor} |
| 52 | |
| 53 | \func{}{wxFileDialog}{\param{wxWindow* }{parent}, \param{const wxString\& }{message = "Choose a file"},\rtfsp |
| 54 | \param{const wxString\& }{defaultDir = ""}, \param{const wxString\& }{defaultFile = ``"},\rtfsp |
| 55 | \param{const wxString\& }{wildcard = ``*.*"}, \param{long }{style = 0}, \param{const wxPoint\& }{pos = wxDefaultPosition}} |
| 56 | |
| 57 | Constructor. Use \helpref{wxFileDialog::ShowModal}{wxfiledialogshowmodal} to show the dialog. |
| 58 | |
| 59 | \wxheading{Parameters} |
| 60 | |
| 61 | \docparam{parent}{Parent window.} |
| 62 | |
| 63 | \docparam{message}{Message to show on the dialog.} |
| 64 | |
| 65 | \docparam{defaultDir}{The default directory, or the empty string.} |
| 66 | |
| 67 | \docparam{defaultFile}{The default filename, or the empty string.} |
| 68 | |
| 69 | \docparam{wildcard}{A wildcard, such as ``*.*" or ``BMP files (*.bmp)|*.bmp|GIF files (*.gif)|*.gif". |
| 70 | |
| 71 | Note that the native Motif dialog has some limitations with respect to |
| 72 | wildcards; see the Remarks section above.} |
| 73 | |
| 74 | \docparam{style}{A dialog style. A bitlist of: |
| 75 | |
| 76 | \twocolwidtha{5cm} |
| 77 | \begin{twocollist} |
| 78 | \twocolitem{{\bf wxOPEN}}{This is an open dialog.} |
| 79 | \twocolitem{{\bf wxSAVE}}{This is a save dialog.} |
| 80 | \twocolitem{{\bf wxOVERWRITE\_PROMPT}}{For save dialog only: prompt for a confirmation if a file will be overwritten.} |
| 81 | \twocolitem{{\bf wxHIDE\_READONLY}}{Do not display the checkbox to toggle display of read-only files. Deprecated in 2.6; the checkbox is never shown.} |
| 82 | \twocolitem{{\bf wxFILE\_MUST\_EXIST}}{The user may only select files that actually exist.} |
| 83 | \twocolitem{{\bf wxMULTIPLE}}{For open dialog only: allows selecting multiple files.} |
| 84 | \twocolitem{{\bf wxCHANGE\_DIR}}{Change the current working directory to the directory where the file(s) chosen by the user are.} |
| 85 | \end{twocollist}% |
| 86 | } |
| 87 | |
| 88 | \docparam{pos}{Dialog position. Not implemented.} |
| 89 | |
| 90 | {\bf NB:} Previous versions of wxWidgets used {\tt wxCHANGE\_DIR} by default |
| 91 | under MS Windows which allowed the program to simply remember the last |
| 92 | directory where user selected the files to open/save. This (desired) |
| 93 | functionality must be implemented in the program itself now (manually remember |
| 94 | the last path used and pass it to the dialog the next time it is called) or |
| 95 | by using this flag. |
| 96 | |
| 97 | \membersection{wxFileDialog::\destruct{wxFileDialog}}\label{wxfiledialogdtor} |
| 98 | |
| 99 | \func{}{\destruct{wxFileDialog}}{\void} |
| 100 | |
| 101 | Destructor. |
| 102 | |
| 103 | \membersection{wxFileDialog::GetDirectory}\label{wxfiledialoggetdirectory} |
| 104 | |
| 105 | \constfunc{wxString}{GetDirectory}{\void} |
| 106 | |
| 107 | Returns the default directory. |
| 108 | |
| 109 | \membersection{wxFileDialog::GetFilename}\label{wxfiledialoggetfilename} |
| 110 | |
| 111 | \constfunc{wxString}{GetFilename}{\void} |
| 112 | |
| 113 | Returns the default filename. |
| 114 | |
| 115 | \membersection{wxFileDialog::GetFilenames}\label{wxfiledialoggetfilenames} |
| 116 | |
| 117 | \constfunc{void}{GetFilenames}{\param{wxArrayString\& }{filenames}} |
| 118 | |
| 119 | Fills the array {\it filenames} with the names of the files chosen. This |
| 120 | function should only be used with the dialogs which have {\tt wxMULTIPLE} style, |
| 121 | use \helpref{GetFilename}{wxfiledialoggetfilename} for the others. |
| 122 | |
| 123 | Note that under Windows, if the user selects shortcuts, the filenames |
| 124 | include paths, since the application cannot determine the full path |
| 125 | of each referenced file by appending the directory containing the shortcuts |
| 126 | to the filename. |
| 127 | |
| 128 | \membersection{wxFileDialog::GetFilterIndex}\label{wxfiledialoggetfilterindex} |
| 129 | |
| 130 | \constfunc{int}{GetFilterIndex}{\void} |
| 131 | |
| 132 | Returns the index into the list of filters supplied, optionally, in the wildcard parameter. |
| 133 | Before the dialog is shown, this is the index which will be used when the dialog is first displayed. |
| 134 | After the dialog is shown, this is the index selected by the user. |
| 135 | |
| 136 | \membersection{wxFileDialog::GetMessage}\label{wxfiledialoggetmessage} |
| 137 | |
| 138 | \constfunc{wxString}{GetMessage}{\void} |
| 139 | |
| 140 | Returns the message that will be displayed on the dialog. |
| 141 | |
| 142 | \membersection{wxFileDialog::GetPath}\label{wxfiledialoggetpath} |
| 143 | |
| 144 | \constfunc{wxString}{GetPath}{\void} |
| 145 | |
| 146 | Returns the full path (directory and filename) of the selected file. |
| 147 | |
| 148 | \membersection{wxFileDialog::GetPaths}\label{wxfiledialoggetpaths} |
| 149 | |
| 150 | \constfunc{void}{GetPaths}{\param{wxArrayString\& }{paths}} |
| 151 | |
| 152 | Fills the array {\it paths} with the full paths of the files chosen. This |
| 153 | function should only be used with the dialogs which have {\tt wxMULTIPLE} style, |
| 154 | use \helpref{GetPath}{wxfiledialoggetpath} for the others. |
| 155 | |
| 156 | \membersection{wxFileDialog::GetStyle}\label{wxfiledialoggetstyle} |
| 157 | |
| 158 | \constfunc{long}{GetStyle}{\void} |
| 159 | |
| 160 | Returns the dialog style. |
| 161 | |
| 162 | \membersection{wxFileDialog::GetWildcard}\label{wxfiledialoggetwildcard} |
| 163 | |
| 164 | \constfunc{wxString}{GetWildcard}{\void} |
| 165 | |
| 166 | Returns the file dialog wildcard. |
| 167 | |
| 168 | \membersection{wxFileDialog::SetDirectory}\label{wxfiledialogsetdirectory} |
| 169 | |
| 170 | \func{void}{SetDirectory}{\param{const wxString\& }{directory}} |
| 171 | |
| 172 | Sets the default directory. |
| 173 | |
| 174 | \membersection{wxFileDialog::SetFilename}\label{wxfiledialogsetfilename} |
| 175 | |
| 176 | \func{void}{SetFilename}{\param{const wxString\& }{setfilename}} |
| 177 | |
| 178 | Sets the default filename. |
| 179 | |
| 180 | \membersection{wxFileDialog::SetFilterIndex}\label{wxfiledialogsetfilterindex} |
| 181 | |
| 182 | \func{void}{SetFilterIndex}{\param{int }{filterIndex}} |
| 183 | |
| 184 | Sets the default filter index, starting from zero. |
| 185 | |
| 186 | \membersection{wxFileDialog::SetMessage}\label{wxfiledialogsetmessage} |
| 187 | |
| 188 | \func{void}{SetMessage}{\param{const wxString\& }{message}} |
| 189 | |
| 190 | Sets the message that will be displayed on the dialog. |
| 191 | |
| 192 | \membersection{wxFileDialog::SetPath}\label{wxfiledialogsetpath} |
| 193 | |
| 194 | \func{void}{SetPath}{\param{const wxString\& }{path}} |
| 195 | |
| 196 | Sets the path (the combined directory and filename that will be returned when the dialog is dismissed). |
| 197 | |
| 198 | \membersection{wxFileDialog::SetStyle}\label{wxfiledialogsetstyle} |
| 199 | |
| 200 | \func{void}{SetStyle}{\param{long }{style}} |
| 201 | |
| 202 | Sets the dialog style. See \helpref{wxFileDialog::wxFileDialog}{wxfiledialogctor} for details. |
| 203 | |
| 204 | \membersection{wxFileDialog::SetWildcard}\label{wxfiledialogsetwildcard} |
| 205 | |
| 206 | \func{void}{SetWildcard}{\param{const wxString\& }{wildCard}} |
| 207 | |
| 208 | Sets the wildcard, which can contain multiple file types, for example: |
| 209 | |
| 210 | ``BMP files (*.bmp)|*.bmp|GIF files (*.gif)|*.gif" |
| 211 | |
| 212 | Note that the native Motif dialog has some limitations with respect to |
| 213 | wildcards; see the Remarks section above. |
| 214 | |
| 215 | \membersection{wxFileDialog::ShowModal}\label{wxfiledialogshowmodal} |
| 216 | |
| 217 | \func{int}{ShowModal}{\void} |
| 218 | |
| 219 | Shows the dialog, returning wxID\_OK if the user pressed OK, and wxID\_CANCEL |
| 220 | otherwise. |
| 221 | |
| 222 | |