docs/latex/wx/dirpicker.tex

   1 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
   2 %% Name:        dirpicker.tex
   3 %% Purpose:     wxDirPickerCtrl 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{wxDirPickerCtrl}}\label{wxdirpickerctrl}
  12
  13 This control allows the user to select a directory. The generic implementation is
  14 a button which brings up a \helpref{wxDirDialog}{wxdirdialog} when clicked. Native implementation
  15 may differ but this is usually a (small) widget which give access to the dir-chooser
  16 dialog.
  17 It is only available if \texttt{wxUSE\_DIRPICKERCTRL} 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{wxDIRP\_DEFAULT\_STYLE}}{The default style: includes
  40 wxDIRP\_DIR\_MUST\_EXIST and, under wxMSW only, wxDIRP\_USE\_TEXTCTRL.}
  41 \twocolitem{\windowstyle{wxDIRP\_USE\_TEXTCTRL}}{Creates a text control to the left of the
  42 picker button which is completely managed by the \helpref{wxDirPickerCtrl}{wxdirpickerctrl}
  43 and which can be used by the user to specify a path (see \helpref{SetPath}{wxdirpickerctrlsetpath}).
  44 The text control is automatically synchronized with button's value. Use functions defined in \helpref{wxPickerBase}{wxpickerbase} to modify the text control.}
  45
  46 \twocolitem{\windowstyle{wxDIRP\_DIR\_MUST\_EXIST}}{Creates a picker which allows to select only existing directories. wxGTK control always adds this flag internally as it does not support its absence.}
  47 \twocolitem{\windowstyle{wxDIRP\_CHANGE\_DIR}}{Change current working directory on each user directory selection change.}
  48
  49 \end{twocollist}
  50
  51 \wxheading{Event handling}
  52
  53 To process a directory picker event, use these event handler macros to direct input to member
  54 functions that take a \helpref{wxFileDirPickerEvent}{wxfiledirpickerevent} argument.
  55
  56 \twocolwidtha{7cm}%
  57 \begin{twocollist}\itemsep=0pt
  58 \twocolitem{{\bf EVT\_DIRPICKER\_CHANGED(id, func)}}{The user changed the
  59 directory selected in the control either using the button or using text control
  60 (see wxDIRP\_USE\_TEXTCTRL; note that in this case the event is fired only if
  61 the user's input is valid, e.g. an existing directory path).}
  62 \end{twocollist}
  63
  64 \wxheading{See also}
  65
  66 \helpref{wxDirDialog}{wxdirdialog},\\
  67 \helpref{wxFileDirPickerEvent}{wxfiledirpickerevent}
  68
  69
  70 \latexignore{\rtfignore{\wxheading{Members}}}
  71
  72 \membersection{wxDirPickerCtrl::wxDirPickerCtrl}\label{wxdirpickerctrl}
  73
  74 \func{}{wxDirPickerCtrl}{\param{wxWindow *}{parent},\rtfsp
  75 \param{wxWindowID}{ id},\rtfsp
  76 \param{const wxString\& }{path = wxEmptyString},\rtfsp
  77 \param{const wxString\& }{message = ``Select a folder"},\rtfsp
  78 \param{const wxPoint\& }{pos = wxDefaultPosition},\rtfsp
  79 \param{const wxSize\& }{size = wxDefaultSize},\rtfsp
  80 \param{long}{ style = wxDIRP\_DEFAULT\_STYLE},\rtfsp
  81 \param{const wxValidator\& }{validator = wxDefaultValidator},
  82 \param{const wxString\& }{name = ``dirpickerctrl"}}
  83
  84 Initializes the object and calls \helpref{Create}{wxdirpickerctrlcreate} with
  85 all the parameters.
  86
  87
  88 \membersection{wxDirPickerCtrl::Create}\label{wxdirpickerctrlcreate}
  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 folder"},\rtfsp
  94 \param{const wxPoint\& }{pos = wxDefaultPosition},\rtfsp
  95 \param{const wxSize\& }{size = wxDefaultSize},\rtfsp
  96 \param{long}{ style = wxDIRP\_DEFAULT\_STYLE},\rtfsp
  97 \param{const wxValidator\& }{validator = wxDefaultValidator},
  98 \param{const wxString\& }{name = ``dirpickerctrl"}}
  99
 100 \wxheading{Parameters}
 101
 102 \docparam{parent}{Parent window, must not be non-\texttt{NULL}.}
 103
 104 \docparam{id}{The identifier for the control.}
 105
 106 \docparam{path}{The initial directory shown in the control. Must be a valid path to a directory or the empty string.}
 107
 108 \docparam{message}{The message shown to the user in the \helpref{wxDirDialog}{wxdirdialog} shown by the control.}
 109
 110 \docparam{pos}{Initial position.}
 111
 112 \docparam{size}{Initial size.}
 113
 114 \docparam{style}{The window style, see {\tt wxDIRP\_*} flags.}
 115
 116 \docparam{validator}{Validator which can be used for additional date checks.}
 117
 118 \docparam{name}{Control name.}
 119
 120 \wxheading{Return value}
 121
 122 \true if the control was successfully created or \false if creation failed.
 123
 124
 125 \membersection{wxFilePickerCtrl::GetDirName}\label{wxfilepickerctrlgetdirname}
 126
 127 \constfunc{wxFileName}{GetDirName}{\void}
 128
 129 Returns the absolute path of the currently selected directory as a \helpref{wxFileName}{wxfilename} object.
 130 This function is equivalent to \helpref{GetPath}{wxdirpickerctrlgetpath}
 131
 132
 133 \membersection{wxDirPickerCtrl::GetPath}\label{wxdirpickerctrlgetpath}
 134
 135 \constfunc{wxString}{GetPath}{\void}
 136
 137 Returns the absolute path of the currently selected directory.
 138
 139
 140 \membersection{wxFilePickerCtrl::SetDirName}\label{wxfilepickerctrlsetdirname}
 141
 142 \func{void}{SetDirName}{\param{const wxFileName \&}{dirname}}
 143
 144 Just like \helpref{SetPath}{wxdirpickerctrlsetpath} but this function takes a
 145 \helpref{wxFileName}{wxfilename} object.
 146
 147
 148 \membersection{wxDirPickerCtrl::SetPath}\label{wxdirpickerctrlsetpath}
 149
 150 \func{void}{SetPath}{\param{const wxString \&}{dirname}}
 151
 152 Sets the absolute path of  (the default converter uses current locale's
 153 charset)the currently selected directory. This must be a valid directory if
 154 {\tt wxDIRP\_DIR\_MUST\_EXIST} style was given.
 155
 156