2006-05-31 19:57:54 -04:00
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%% Name: filepicker.tex
%% Purpose: wxFilePickerCtrl and wxFileDirPickerEvent documentation
%% Author: Francesco Montorsi
%% Created: 2006-05-12
%% RCS-ID: $Id$
%% Copyright: (c) 2006 Francesco Montorsi
%% License: wxWindows license
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\section { \class { wxFilePickerCtrl} } \label { wxfilepickerctrl}
This control allows the user to select a file. The generic implementation is
a button which brings up a \helpref { wxFileDialog} { wxfiledialog} when clicked. Native implementation
may differ but this is usually a (small) widget which give access to the file-chooser
dialog.
It is only available if \texttt { wxUSE\_ FILEPICKERCTRL} is set to $ 1 $ (the default).
\wxheading { Derived from}
\helpref { wxPickerBase} { wxpickerbase} \\
\helpref { wxControl} { wxcontrol} \\
\helpref { wxWindow} { wxwindow} \\
\helpref { wxEvtHandler} { wxevthandler} \\
\helpref { wxObject} { wxobject}
\wxheading { Include files}
<wx/filepicker.h>
\wxheading { Window styles}
\twocolwidtha { 5cm} %
\begin { twocollist} \itemsep =0pt
2006-06-25 21:04:44 -04:00
\twocolitem { \windowstyle { wxFLP\_ DEFAULT\_ STYLE} } { The default style: includes
wxFLP\_ OPEN | wxFLP\_ FILE\_ MUST\_ EXIST and, under wxMSW only,
wxFLP\_ USE\_ TEXTCTRL.}
2006-05-31 19:57:54 -04:00
\twocolitem { \windowstyle { wxFLP\_ USE\_ TEXTCTRL} } { Creates a text control to the left of the
picker button which is completely managed by the \helpref { wxFilePickerCtrl} { wxfilepickerctrl}
and which can be used by the user to specify a path (see \helpref { SetPath} { wxfilepickerctrlsetpath} ).
The text control is automatically synchronized with button's value. Use functions defined in \helpref { wxPickerBase} { wxpickerbase} to modify the text control.}
\twocolitem { \windowstyle { wxFLP\_ OPEN} } { Creates a picker which allows the user to select a file to open.}
\twocolitem { \windowstyle { wxFLP\_ SAVE} } { Creates a picker which allows the user to select a file to save.}
\twocolitem { \windowstyle { wxFLP\_ OVERWRITE\_ PROMPT} } { Can be combined with wxFLP\_ SAVE only: ask confirmation to the user before selecting a file.}
\twocolitem { \windowstyle { wxFLP\_ FILE\_ MUST\_ EXIST} } { Can be combined with wxFLP\_ OPEN only: the selected file must be an existing file.}
\twocolitem { \windowstyle { wxFLP\_ CHANGE\_ DIR} } { Change current working directory on each user file selection change.}
NB: the wxFD\_ MULTIPLE style of wxFileDialog is not supported!
\end { twocollist}
\wxheading { Event handling}
\twocolwidtha { 7cm} %
\begin { twocollist} \itemsep =0pt
\twocolitem { { \bf EVT\_ FILEPICKER\_ CHANGED(id, func)} } { The user changed the file
selected in the control either using the button or using text control (see
2006-06-08 15:10:00 -04:00
wxFLP\_ USE\_ TEXTCTRL; note that in this case the event is fired only if the
user's input is valid, e.g. an existing file path if wxFLP\_ FILE\_ MUST\_ EXIST
2006-05-31 19:57:54 -04:00
was given).}
\end { twocollist}
\wxheading { See also}
\helpref { wxFileDialog} { wxfiledialog} ,\\
\helpref { wxFileDirPickerEvent} { wxfiledirpickerevent}
\latexignore { \rtfignore { \wxheading { Members} } }
\membersection { wxFilePickerCtrl::wxFilePickerCtrl} \label { wxfilepickerctrl}
2006-06-08 15:10:00 -04:00
\func { } { wxFilePickerCtrl} { \param { wxWindow *} { parent} ,\rtfsp
2006-05-31 19:57:54 -04:00
\param { wxWindowID} { id} ,\rtfsp
\param { const wxString\& } { path = wxEmptyString} ,\rtfsp
\param { const wxString\& } { message = ``Select a file"} ,\rtfsp
\param { const wxString\& } { wildcard = ``*.*"} ,\rtfsp
\param { const wxPoint\& } { pos = wxDefaultPosition} ,\rtfsp
\param { const wxSize\& } { size = wxDefaultSize} ,\rtfsp
2006-06-08 15:10:00 -04:00
\param { long} { style = wxFLP\_ DEFAULT\_ STYLE} ,\rtfsp
2006-05-31 19:57:54 -04:00
\param { const wxValidator\& } { validator = wxDefaultValidator} ,
\param { const wxString\& } { name = ``filepickerctrl"} }
Initializes the object and calls \helpref { Create} { wxfilepickerctrlcreate} with
all the parameters.
\membersection { wxFilePickerCtrl::Create} \label { wxfilepickerctrlcreate}
\func { bool} { Create} { \param { wxWindow *} { parent} ,\rtfsp
\param { wxWindowID} { id} ,\rtfsp
\param { const wxString\& } { path = wxEmptyString} ,\rtfsp
\param { const wxString\& } { message = ``Select a file"} ,\rtfsp
\param { const wxString\& } { wildcard = ``*.*"} ,\rtfsp
\param { const wxPoint\& } { pos = wxDefaultPosition} ,\rtfsp
\param { const wxSize\& } { size = wxDefaultSize} ,\rtfsp
2006-06-08 15:10:00 -04:00
\param { long} { style = wxFLP\_ DEFAULT\_ STYLE} ,\rtfsp
2006-05-31 19:57:54 -04:00
\param { const wxValidator\& } { validator = wxDefaultValidator} ,
\param { const wxString\& } { name = ``filepickerctrl"} }
\wxheading { Parameters}
\docparam { parent} { Parent window, must not be non-\texttt { NULL} .}
\docparam { id} { The identifier for the control.}
\docparam { path} { The initial file shown in the control. Must be a valid path to a file or the empty string.}
\docparam { message} { The message shown to the user in the \helpref { wxFileDialog} { wxfiledialog} shown by the control.}
2006-06-08 15:10:00 -04:00
\docparam { wildcard} { A wildcard which defines user-selectable files (use the same syntax as for \helpref { wxFileDialog} { wxfiledialog} 's wildcards).}
2006-05-31 19:57:54 -04:00
\docparam { pos} { Initial position.}
\docparam { size} { Initial size.}
2006-06-08 15:10:00 -04:00
\docparam { style} { The window style, see { \tt wxFLP\_ * } flags.}
2006-05-31 19:57:54 -04:00
\docparam { validator} { Validator which can be used for additional date checks.}
\docparam { name} { Control name.}
\wxheading { Return value}
\true if the control was successfully created or \false if creation failed.
\membersection { wxFilePickerCtrl::GetPath} \label { wxfilepickerctrlgetpath}
\constfunc { wxString} { GetPath} { \void }
2006-10-08 11:49:36 -04:00
Returns the absolute path of the currently selected file.
2006-05-31 19:57:54 -04:00
\membersection { wxFilePickerCtrl::SetPath} \label { wxfilepickerctrlsetpath}
\func { void} { SetPath} { \param { const wxString \& } { filename} }
2006-10-08 11:49:36 -04:00
Sets the absolute path of the currently selected file. This must be a valid file if
the { \tt wxFLP\_ FILE\_ MUST\_ EXIST} style was given.
2006-05-31 19:57:54 -04:00
%% wxFileDirPickerEvent documentation
\section { \class { wxFileDirPickerEvent} } \label { wxfiledirpickerevent}
This event class is used for the events generated by
\helpref { wxFilePickerCtrl} { wxfilepickerctrl} and by \helpref { wxDirPickerCtrl} { wxdirpickerctrl} .
\wxheading { Derived from}
\helpref { wxCommandEvent} { wxcommandevent} \\
\helpref { wxEvent} { wxevent} \\
\helpref { wxObject} { wxobject}
\wxheading { Include files}
<wx/filepicker.h>
\wxheading { Event handling}
To process input from a wxFilePickerCtrl or from a wxDirPickerCtrl, use one of these event handler macros to
direct input to member function that take a \helpref { wxFileDirPickerEvent} { wxfiledirpickerevent} argument:
\twocolwidtha { 7cm}
\begin { twocollist}
\twocolitem { { \bf EVT\_ FILEPICKER\_ CHANGED(id, func)} } { Generated whenever the selected file changes.}
\twocolitem { { \bf EVT\_ DIRPICKER\_ CHANGED(id, func)} } { Generated whenever the selected directory changes.}
\end { twocollist} %
\wxheading { See also}
\helpref { wxfilepickerctrl} { wxfilepickerctrl}
\latexignore { \rtfignore { \wxheading { Members} } }
\membersection { wxFileDirPickerEvent::wxFileDirPickerEvent} \label { wxfiledirpickereventctor}
\func { } { wxFileDirPickerEvent} { \param { wxEventType} { type} , \param { wxObject *} { generator} , \param { int} { id} , \param { const wxString& } { path} }
The constructor is not normally used by the user code.
\membersection { wxFileDirPickerEvent::GetPath} \label { wxfiledirpickereventgetpath}
\constfunc { wxString} { GetPath} { \void }
2006-10-08 11:49:36 -04:00
Retrieve the absolute path of the file/directory the user has just selected.
2006-05-31 19:57:54 -04:00
\membersection { wxFileDirPickerEvent::SetPath} \label { wxfiledirpickereventsetpath}
\func { void} { SetPath} { \param { const wxString \& } { path} }
2006-10-08 11:49:36 -04:00
Set the absolute path of the file/directory associated with the event.