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