docs/latex/wx/filedlg.tex

   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 read-only files.}
  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