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