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 \twocolwidtha{7cm}%
  50 \begin{twocollist}\itemsep=0pt
  51 \twocolitem{{\bf EVT\_DIRPICKER\_CHANGED(id, func)}}{The user changed the
  52 directory selected in the control either using the button or using text control
  53 (see wxDIRP\_USE\_TEXTCTRL; note that in this case the event is fired only if
  54 the user's input is valid, e.g. an existing directory path).}
  55 \end{twocollist}
  56
  57 \wxheading{See also}
  58
  59 \helpref{wxDirDialog}{wxdirdialog},\\
  60 \helpref{wxFileDirPickerEvent}{wxfiledirpickerevent}
  61
  62
  63 \latexignore{\rtfignore{\wxheading{Members}}}
  64
  65 \membersection{wxDirPickerCtrl::wxDirPickerCtrl}\label{wxdirpickerctrl}
  66
  67 \func{}{wxDirPickerCtrl}{\param{wxWindow *}{parent},\rtfsp
  68 \param{wxWindowID}{ id},\rtfsp
  69 \param{const wxString\& }{path = wxEmptyString},\rtfsp
  70 \param{const wxString\& }{message = ``Select a folder"},\rtfsp
  71 \param{const wxPoint\& }{pos = wxDefaultPosition},\rtfsp
  72 \param{const wxSize\& }{size = wxDefaultSize},\rtfsp
  73 \param{long}{ style = wxDIRP\_DEFAULT\_STYLE},\rtfsp
  74 \param{const wxValidator\& }{validator = wxDefaultValidator},
  75 \param{const wxString\& }{name = ``dirpickerctrl"}}
  76
  77 Initializes the object and calls \helpref{Create}{wxdirpickerctrlcreate} with
  78 all the parameters.
  79
  80
  81 \membersection{wxDirPickerCtrl::Create}\label{wxdirpickerctrlcreate}
  82
  83 \func{bool}{Create}{\param{wxWindow *}{parent},\rtfsp
  84 \param{wxWindowID}{ id},\rtfsp
  85 \param{const wxString\& }{path = wxEmptyString},\rtfsp
  86 \param{const wxString\& }{message = ``Select a folder"},\rtfsp
  87 \param{const wxPoint\& }{pos = wxDefaultPosition},\rtfsp
  88 \param{const wxSize\& }{size = wxDefaultSize},\rtfsp
  89 \param{long}{ style = wxDIRP\_DEFAULT\_STYLE},\rtfsp
  90 \param{const wxValidator\& }{validator = wxDefaultValidator},
  91 \param{const wxString\& }{name = ``dirpickerctrl"}}
  92
  93 \wxheading{Parameters}
  94
  95 \docparam{parent}{Parent window, must not be non-\texttt{NULL}.}
  96
  97 \docparam{id}{The identifier for the control.}
  98
  99 \docparam{path}{The initial directory shown in the control. Must be a valid path to a directory or the empty string.}
 100
 101 \docparam{message}{The message shown to the user in the \helpref{wxDirDialog}{wxdirdialog} shown by the control.}
 102
 103 \docparam{pos}{Initial position.}
 104
 105 \docparam{size}{Initial size.}
 106
 107 \docparam{style}{The window style, see {\tt wxDIRP\_*} flags.}
 108
 109 \docparam{validator}{Validator which can be used for additional date checks.}
 110
 111 \docparam{name}{Control name.}
 112
 113 \wxheading{Return value}
 114
 115 \true if the control was successfully created or \false if creation failed.
 116
 117
 118 \membersection{wxDirPickerCtrl::GetPath}\label{wxdirpickerctrlgetpath}
 119
 120 \constfunc{wxString}{GetPath}{\void}
 121
 122 Returns the absolute path of the currently selected directory.
 123
 124
 125 \membersection{wxDirPickerCtrl::SetPath}\label{wxdirpickerctrlsetpath}
 126
 127 \func{void}{SetPath}{\param{const wxString \&}{dirname}}
 128
 129 Sets the absolute path of the currently selected directory. This must be a valid directory if
 130 {\tt wxDIRP\_DIR\_MUST\_EXIST} style was given.
 131
 132