]> git.saurik.com Git - wxWidgets.git/blob - docs/latex/wx/filedlg.tex
Tweaks for demos on MacOSX
[wxWidgets.git] / 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 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