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