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