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{Window styles}
  32
  33 \twocolwidtha{5cm}%
  34 \begin{twocollist}\itemsep=0pt
  35 \twocolitem{\windowstyle{wxFLP\_DEFAULT\_STYLE}}{The default style: includes
  36 wxFLP\_OPEN | wxFLP\_FILE\_MUST\_EXIST and, under wxMSW only,
  37 wxFLP\_USE\_TEXTCTRL.}
  38 \twocolitem{\windowstyle{wxFLP\_USE\_TEXTCTRL}}{Creates a text control to the left of the
  39 picker button which is completely managed by the \helpref{wxFilePickerCtrl}{wxfilepickerctrl}
  40 and which can be used by the user to specify a path (see \helpref{SetPath}{wxfilepickerctrlsetpath}).
  41 The 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
  48 NB: the wxFD\_MULTIPLE style of wxFileDialog is not supported!
  49
  50 \end{twocollist}
  51
  52 \wxheading{Event handling}
  53
  54 To process a file picker event, use these event handler macros to direct input to member
  55 functions 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
  60 selected in the control either using the button or using text control (see
  61 wxFLP\_USE\_TEXTCTRL; note that in this case the event is fired only if the
  62 user's input is valid, e.g. an existing file path if wxFLP\_FILE\_MUST\_EXIST
  63 was 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{wxfilepickerctrl}
  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
  87 Initializes the object and calls \helpref{Create}{wxfilepickerctrlcreate} with
  88 all 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::GetFileName}\label{wxfilepickerctrlgetfilename}
 132
 133 \constfunc{wxFileName}{GetFileName}{\void}
 134
 135 Similar to \helpref{GetPath}{wxfilepickerctrlgetpath} but returns the path of
 136 the currently selected file as a \helpref{wxFileName} object.
 137
 138
 139 \membersection{wxFilePickerCtrl::GetPath}\label{wxfilepickerctrlgetpath}
 140
 141 \constfunc{wxString}{GetPath}{\void}
 142
 143 Returns the absolute path of the currently selected file.
 144
 145
 146 \membersection{wxFilePickerCtrl::SetFileName}\label{wxfilepickerctrlsetfilename}
 147
 148 \func{void}{SetFileName}{\param{const wxFileName \&}{filename}}
 149
 150 This method does the same thing as \helpref{SetPath}{wxfilepickerctrlsetpath} but
 151 takes a \helpref{wxFileName}{wxfilename} object instead of a string.
 152
 153
 154 \membersection{wxFilePickerCtrl::SetPath}\label{wxfilepickerctrlsetpath}
 155
 156 \func{void}{SetPath}{\param{const wxString \&}{filename}}
 157
 158 Sets the absolute path of the currently selected file. This must be a valid file if
 159 the {\tt wxFLP\_FILE\_MUST\_EXIST} style was given.
 160
 161
 162
 163 %% wxFileDirPickerEvent documentation
 164
 165 \section{\class{wxFileDirPickerEvent}}\label{wxfiledirpickerevent}
 166
 167 This event class is used for the events generated by
 168 \helpref{wxFilePickerCtrl}{wxfilepickerctrl} and by \helpref{wxDirPickerCtrl}{wxdirpickerctrl}.
 169
 170 \wxheading{Derived from}
 171
 172 \helpref{wxCommandEvent}{wxcommandevent}\\
 173 \helpref{wxEvent}{wxevent}\\
 174 \helpref{wxObject}{wxobject}
 175
 176 \wxheading{Include files}
 177
 178 <wx/filepicker.h>
 179
 180 \wxheading{Event handling}
 181
 182 To process input from a wxFilePickerCtrl or from a wxDirPickerCtrl, use one of these event handler macros to
 183 direct input to member function that take a \helpref{wxFileDirPickerEvent}{wxfiledirpickerevent} argument:
 184
 185 \twocolwidtha{7cm}
 186 \begin{twocollist}
 187 \twocolitem{{\bf EVT\_FILEPICKER\_CHANGED(id, func)}}{Generated whenever the selected file changes.}
 188 \twocolitem{{\bf EVT\_DIRPICKER\_CHANGED(id, func)}}{Generated whenever the selected directory changes.}
 189 \end{twocollist}%
 190
 191
 192 \wxheading{See also}
 193
 194 \helpref{wxfilepickerctrl}{wxfilepickerctrl}
 195
 196 \latexignore{\rtfignore{\wxheading{Members}}}
 197
 198 \membersection{wxFileDirPickerEvent::wxFileDirPickerEvent}\label{wxfiledirpickereventctor}
 199
 200 \func{}{wxFileDirPickerEvent}{\param{wxEventType}{ type}, \param{wxObject *}{ generator}, \param{int}{ id}, \param{const wxString&}{ path}}
 201
 202 The constructor is not normally used by the user code.
 203
 204
 205 \membersection{wxFileDirPickerEvent::GetPath}\label{wxfiledirpickereventgetpath}
 206
 207 \constfunc{wxString}{GetPath}{\void}
 208
 209 Retrieve the absolute path of the file/directory the user has just selected.
 210
 211
 212 \membersection{wxFileDirPickerEvent::SetPath}\label{wxfiledirpickereventsetpath}
 213
 214 \func{void}{SetPath}{\param{const wxString \&}{path}}
 215
 216 Set the absolute path of the file/directory associated with the event.
 217