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 \twocolwidtha{7cm}%
  55 \begin{twocollist}\itemsep=0pt
  56 \twocolitem{{\bf EVT\_FILEPICKER\_CHANGED(id, func)}}{The user changed the file
  57 selected in the control either using the button or using text control (see
  58 wxFLP\_USE\_TEXTCTRL; note that in this case the event is fired only if the
  59 user's input is valid, e.g. an existing file path if wxFLP\_FILE\_MUST\_EXIST
  60 was given).}
  61 \end{twocollist}
  62
  63 \wxheading{See also}
  64
  65 \helpref{wxFileDialog}{wxfiledialog},\\
  66 \helpref{wxFileDirPickerEvent}{wxfiledirpickerevent}
  67
  68
  69 \latexignore{\rtfignore{\wxheading{Members}}}
  70
  71 \membersection{wxFilePickerCtrl::wxFilePickerCtrl}\label{wxfilepickerctrl}
  72
  73 \func{}{wxFilePickerCtrl}{\param{wxWindow *}{parent},\rtfsp
  74 \param{wxWindowID}{ id},\rtfsp
  75 \param{const wxString\& }{path = wxEmptyString},\rtfsp
  76 \param{const wxString\& }{message = ``Select a file"},\rtfsp
  77 \param{const wxString\& }{wildcard = ``*.*"},\rtfsp
  78 \param{const wxPoint\& }{pos = wxDefaultPosition},\rtfsp
  79 \param{const wxSize\& }{size = wxDefaultSize},\rtfsp
  80 \param{long}{ style = wxFLP\_DEFAULT\_STYLE},\rtfsp
  81 \param{const wxValidator\& }{validator = wxDefaultValidator},
  82 \param{const wxString\& }{name = ``filepickerctrl"}}
  83
  84 Initializes the object and calls \helpref{Create}{wxfilepickerctrlcreate} with
  85 all the parameters.
  86
  87
  88 \membersection{wxFilePickerCtrl::Create}\label{wxfilepickerctrlcreate}
  89
  90 \func{bool}{Create}{\param{wxWindow *}{parent},\rtfsp
  91 \param{wxWindowID}{ id},\rtfsp
  92 \param{const wxString\& }{path = wxEmptyString},\rtfsp
  93 \param{const wxString\& }{message = ``Select a file"},\rtfsp
  94 \param{const wxString\& }{wildcard = ``*.*"},\rtfsp
  95 \param{const wxPoint\& }{pos = wxDefaultPosition},\rtfsp
  96 \param{const wxSize\& }{size = wxDefaultSize},\rtfsp
  97 \param{long}{ style = wxFLP\_DEFAULT\_STYLE},\rtfsp
  98 \param{const wxValidator\& }{validator = wxDefaultValidator},
  99 \param{const wxString\& }{name = ``filepickerctrl"}}
 100
 101 \wxheading{Parameters}
 102
 103 \docparam{parent}{Parent window, must not be non-\texttt{NULL}.}
 104
 105 \docparam{id}{The identifier for the control.}
 106
 107 \docparam{path}{The initial file shown in the control. Must be a valid path to a file or the empty string.}
 108
 109 \docparam{message}{The message shown to the user in the \helpref{wxFileDialog}{wxfiledialog} shown by the control.}
 110
 111 \docparam{wildcard}{A wildcard which defines user-selectable files (use the same syntax as for \helpref{wxFileDialog}{wxfiledialog}'s wildcards).}
 112
 113 \docparam{pos}{Initial position.}
 114
 115 \docparam{size}{Initial size.}
 116
 117 \docparam{style}{The window style, see {\tt wxFLP\_*} flags.}
 118
 119 \docparam{validator}{Validator which can be used for additional date checks.}
 120
 121 \docparam{name}{Control name.}
 122
 123 \wxheading{Return value}
 124
 125 \true if the control was successfully created or \false if creation failed.
 126
 127
 128 \membersection{wxFilePickerCtrl::GetPath}\label{wxfilepickerctrlgetpath}
 129
 130 \constfunc{wxString}{GetPath}{\void}
 131
 132 Returns the currently selected file.
 133
 134
 135 \membersection{wxFilePickerCtrl::SetPath}\label{wxfilepickerctrlsetpath}
 136
 137 \func{void}{SetPath}{\param{const wxString \&}{filename}}
 138
 139 Sets the currently selected file. This must be a valid file if
 140 {\tt wxFLP\_FILE\_MUST\_EXIST} style was given.
 141
 142
 143
 144 %% wxFileDirPickerEvent documentation
 145
 146 \section{\class{wxFileDirPickerEvent}}\label{wxfiledirpickerevent}
 147
 148 This event class is used for the events generated by
 149 \helpref{wxFilePickerCtrl}{wxfilepickerctrl} and by \helpref{wxDirPickerCtrl}{wxdirpickerctrl}.
 150
 151 \wxheading{Derived from}
 152
 153 \helpref{wxCommandEvent}{wxcommandevent}\\
 154 \helpref{wxEvent}{wxevent}\\
 155 \helpref{wxObject}{wxobject}
 156
 157 \wxheading{Include files}
 158
 159 <wx/filepicker.h>
 160
 161 \wxheading{Event handling}
 162
 163 To process input from a wxFilePickerCtrl or from a wxDirPickerCtrl, use one of these event handler macros to
 164 direct input to member function that take a \helpref{wxFileDirPickerEvent}{wxfiledirpickerevent} argument:
 165
 166 \twocolwidtha{7cm}
 167 \begin{twocollist}
 168 \twocolitem{{\bf EVT\_FILEPICKER\_CHANGED(id, func)}}{Generated whenever the selected file changes.}
 169 \twocolitem{{\bf EVT\_DIRPICKER\_CHANGED(id, func)}}{Generated whenever the selected directory changes.}
 170 \end{twocollist}%
 171
 172
 173 \wxheading{See also}
 174
 175 \helpref{wxfilepickerctrl}{wxfilepickerctrl}
 176
 177 \latexignore{\rtfignore{\wxheading{Members}}}
 178
 179 \membersection{wxFileDirPickerEvent::wxFileDirPickerEvent}\label{wxfiledirpickereventctor}
 180
 181 \func{}{wxFileDirPickerEvent}{\param{wxEventType}{ type}, \param{wxObject *}{ generator}, \param{int}{ id}, \param{const wxString&}{ path}}
 182
 183 The constructor is not normally used by the user code.
 184
 185
 186 \membersection{wxFileDirPickerEvent::GetPath}\label{wxfiledirpickereventgetpath}
 187
 188 \constfunc{wxString}{GetPath}{\void}
 189
 190 Retrieve the file/directory the user has just selected.
 191
 192
 193 \membersection{wxFileDirPickerEvent::SetPath}\label{wxfiledirpickereventsetpath}
 194
 195 \func{void}{SetPath}{\param{const wxString \&}{path}}
 196
 197 Set the file/directory associated with the event.