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