]> git.saurik.com Git - wxWidgets.git/blob - docs/latex/wx/filepicker.tex
many wxIPC Unicode and UTF-8 fixes (use void* instead of wxChar* in the API and UTF...
[wxWidgets.git] / docs / latex / wx / filepicker.tex
1 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
2 %% Name: filepicker.tex
3 %% Purpose: wxFilePickerCtrl and wxFileDirPickerEvent documentation
4 %% Author: Francesco Montorsi
5 %% Created: 2006-05-12
6 %% RCS-ID: $Id$
7 %% Copyright: (c) 2006 Francesco Montorsi
8 %% License: wxWindows license
9 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
10
11 \section{\class{wxFilePickerCtrl}}\label{wxfilepickerctrl}
12
13 This control allows the user to select a file. The generic implementation is
14 a button which brings up a \helpref{wxFileDialog}{wxfiledialog} when clicked. Native implementation
15 may differ but this is usually a (small) widget which give access to the file-chooser
16 dialog.
17 It is only available if \texttt{wxUSE\_FILEPICKERCTRL} is set to $1$ (the default).
18
19 \wxheading{Derived from}
20
21 \helpref{wxPickerBase}{wxpickerbase}\\
22 \helpref{wxControl}{wxcontrol}\\
23 \helpref{wxWindow}{wxwindow}\\
24 \helpref{wxEvtHandler}{wxevthandler}\\
25 \helpref{wxObject}{wxobject}
26
27 \wxheading{Include files}
28
29 <wx/filepicker.h>
30
31 \wxheading{Library}
32
33 \helpref{wxCore}{librarieslist}
34
35 \wxheading{Window styles}
36
37 \twocolwidtha{5cm}%
38 \begin{twocollist}\itemsep=0pt
39 \twocolitem{\windowstyle{wxFLP\_DEFAULT\_STYLE}}{The default style: includes
40 wxFLP\_OPEN | wxFLP\_FILE\_MUST\_EXIST and, under wxMSW only,
41 wxFLP\_USE\_TEXTCTRL.}
42 \twocolitem{\windowstyle{wxFLP\_USE\_TEXTCTRL}}{Creates a text control to the left of the
43 picker button which is completely managed by the \helpref{wxFilePickerCtrl}{wxfilepickerctrl}
44 and which can be used by the user to specify a path (see \helpref{SetPath}{wxfilepickerctrlsetpath}).
45 The text control is automatically synchronized with button's value. Use functions defined in \helpref{wxPickerBase}{wxpickerbase} to modify the text control.}
46 \twocolitem{\windowstyle{wxFLP\_OPEN}}{Creates a picker which allows the user to select a file to open.}
47 \twocolitem{\windowstyle{wxFLP\_SAVE}}{Creates a picker which allows the user to select a file to save.}
48 \twocolitem{\windowstyle{wxFLP\_OVERWRITE\_PROMPT}}{Can be combined with wxFLP\_SAVE only: ask confirmation to the user before selecting a file.}
49 \twocolitem{\windowstyle{wxFLP\_FILE\_MUST\_EXIST}}{Can be combined with wxFLP\_OPEN only: the selected file must be an existing file.}
50 \twocolitem{\windowstyle{wxFLP\_CHANGE\_DIR}}{Change current working directory on each user file selection change.}
51
52 NB: the wxFD\_MULTIPLE style of wxFileDialog is not supported!
53
54 \end{twocollist}
55
56 \wxheading{Event handling}
57
58 To process a file picker event, use these event handler macros to direct input to member
59 functions that take a \helpref{wxFileDirPickerEvent}{wxfiledirpickerevent} argument.
60
61 \twocolwidtha{7cm}%
62 \begin{twocollist}\itemsep=0pt
63 \twocolitem{{\bf EVT\_FILEPICKER\_CHANGED(id, func)}}{The user changed the file
64 selected in the control either using the button or using text control (see
65 wxFLP\_USE\_TEXTCTRL; note that in this case the event is fired only if the
66 user's input is valid, e.g. an existing file path if wxFLP\_FILE\_MUST\_EXIST
67 was given).}
68 \end{twocollist}
69
70 \wxheading{See also}
71
72 \helpref{wxFileDialog}{wxfiledialog},\\
73 \helpref{wxFileDirPickerEvent}{wxfiledirpickerevent}
74
75
76 \latexignore{\rtfignore{\wxheading{Members}}}
77
78 \membersection{wxFilePickerCtrl::wxFilePickerCtrl}\label{wxfilepickerctrlctor}
79
80 \func{}{wxFilePickerCtrl}{\param{wxWindow *}{parent},\rtfsp
81 \param{wxWindowID}{ id},\rtfsp
82 \param{const wxString\& }{path = wxEmptyString},\rtfsp
83 \param{const wxString\& }{message = ``Select a file"},\rtfsp
84 \param{const wxString\& }{wildcard = ``*.*"},\rtfsp
85 \param{const wxPoint\& }{pos = wxDefaultPosition},\rtfsp
86 \param{const wxSize\& }{size = wxDefaultSize},\rtfsp
87 \param{long}{ style = wxFLP\_DEFAULT\_STYLE},\rtfsp
88 \param{const wxValidator\& }{validator = wxDefaultValidator},
89 \param{const wxString\& }{name = ``filepickerctrl"}}
90
91 Initializes the object and calls \helpref{Create}{wxfilepickerctrlcreate} with
92 all the parameters.
93
94
95 \membersection{wxFilePickerCtrl::Create}\label{wxfilepickerctrlcreate}
96
97 \func{bool}{Create}{\param{wxWindow *}{parent},\rtfsp
98 \param{wxWindowID}{ id},\rtfsp
99 \param{const wxString\& }{path = wxEmptyString},\rtfsp
100 \param{const wxString\& }{message = ``Select a file"},\rtfsp
101 \param{const wxString\& }{wildcard = ``*.*"},\rtfsp
102 \param{const wxPoint\& }{pos = wxDefaultPosition},\rtfsp
103 \param{const wxSize\& }{size = wxDefaultSize},\rtfsp
104 \param{long}{ style = wxFLP\_DEFAULT\_STYLE},\rtfsp
105 \param{const wxValidator\& }{validator = wxDefaultValidator},
106 \param{const wxString\& }{name = ``filepickerctrl"}}
107
108 \wxheading{Parameters}
109
110 \docparam{parent}{Parent window, must not be non-\texttt{NULL}.}
111
112 \docparam{id}{The identifier for the control.}
113
114 \docparam{path}{The initial file shown in the control. Must be a valid path to a file or the empty string.}
115
116 \docparam{message}{The message shown to the user in the \helpref{wxFileDialog}{wxfiledialog} shown by the control.}
117
118 \docparam{wildcard}{A wildcard which defines user-selectable files (use the same syntax as for \helpref{wxFileDialog}{wxfiledialog}'s wildcards).}
119
120 \docparam{pos}{Initial position.}
121
122 \docparam{size}{Initial size.}
123
124 \docparam{style}{The window style, see {\tt wxFLP\_*} flags.}
125
126 \docparam{validator}{Validator which can be used for additional date checks.}
127
128 \docparam{name}{Control name.}
129
130 \wxheading{Return value}
131
132 \true if the control was successfully created or \false if creation failed.
133
134
135 \membersection{wxFilePickerCtrl::GetFileName}\label{wxfilepickerctrlgetfilename}
136
137 \constfunc{wxFileName}{GetFileName}{\void}
138
139 Similar to \helpref{GetPath}{wxfilepickerctrlgetpath} but returns the path of
140 the currently selected file as a \helpref{wxFileName}{wxfilename} object.
141
142
143 \membersection{wxFilePickerCtrl::GetPath}\label{wxfilepickerctrlgetpath}
144
145 \constfunc{wxString}{GetPath}{\void}
146
147 Returns the absolute path of the currently selected file.
148
149
150 \membersection{wxFilePickerCtrl::SetFileName}\label{wxfilepickerctrlsetfilename}
151
152 \func{void}{SetFileName}{\param{const wxFileName \&}{filename}}
153
154 This method does the same thing as \helpref{SetPath}{wxfilepickerctrlsetpath} but
155 takes a \helpref{wxFileName}{wxfilename} object instead of a string.
156
157
158 \membersection{wxFilePickerCtrl::SetPath}\label{wxfilepickerctrlsetpath}
159
160 \func{void}{SetPath}{\param{const wxString \&}{filename}}
161
162 Sets the absolute path of the currently selected file. This must be a valid file if
163 the {\tt wxFLP\_FILE\_MUST\_EXIST} style was given.
164
165
166
167 %% wxFileDirPickerEvent documentation
168
169 \section{\class{wxFileDirPickerEvent}}\label{wxfiledirpickerevent}
170
171 This event class is used for the events generated by
172 \helpref{wxFilePickerCtrl}{wxfilepickerctrl} and by \helpref{wxDirPickerCtrl}{wxdirpickerctrl}.
173
174 \wxheading{Derived from}
175
176 \helpref{wxCommandEvent}{wxcommandevent}\\
177 \helpref{wxEvent}{wxevent}\\
178 \helpref{wxObject}{wxobject}
179
180 \wxheading{Include files}
181
182 <wx/filepicker.h>
183
184 \wxheading{Library}
185
186 \helpref{wxCore}{librarieslist}
187
188 \wxheading{Event handling}
189
190 To process input from a wxFilePickerCtrl or from a wxDirPickerCtrl, use one of these event handler macros to
191 direct input to member function that take a \helpref{wxFileDirPickerEvent}{wxfiledirpickerevent} argument:
192
193 \twocolwidtha{7cm}
194 \begin{twocollist}
195 \twocolitem{{\bf EVT\_FILEPICKER\_CHANGED(id, func)}}{Generated whenever the selected file changes.}
196 \twocolitem{{\bf EVT\_DIRPICKER\_CHANGED(id, func)}}{Generated whenever the selected directory changes.}
197 \end{twocollist}%
198
199
200 \wxheading{See also}
201
202 \helpref{wxfilepickerctrl}{wxfilepickerctrl}
203
204 \latexignore{\rtfignore{\wxheading{Members}}}
205
206 \membersection{wxFileDirPickerEvent::wxFileDirPickerEvent}\label{wxfiledirpickereventctor}
207
208 \func{}{wxFileDirPickerEvent}{\param{wxEventType}{ type}, \param{wxObject *}{ generator}, \param{int}{ id}, \param{const wxString&}{ path}}
209
210 The constructor is not normally used by the user code.
211
212
213 \membersection{wxFileDirPickerEvent::GetPath}\label{wxfiledirpickereventgetpath}
214
215 \constfunc{wxString}{GetPath}{\void}
216
217 Retrieve the absolute path of the file/directory the user has just selected.
218
219
220 \membersection{wxFileDirPickerEvent::SetPath}\label{wxfiledirpickereventsetpath}
221
222 \func{void}{SetPath}{\param{const wxString \&}{path}}
223
224 Set the absolute path of the file/directory associated with the event.
225