docs/latex/wx/filectrl.tex

   1 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
   2 %% Name:        filectrl.tex
   3 %% Purpose:     wxFilerCtrl documentation
   4 %% Author:      Diaa M. Sami
   5 %% Created:     2007-07-25
   6 %% RCS-ID:      $Id: $
   7 %% Copyright:   (c) 2007 Diaa M. Sami
   8 %% License:     wxWindows license
   9 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
  10
  11 \section{\class{wxFileCtrl}}\label{wxfilectrl}
  12
  13 This control allows the user to select a file. two implemetations exist, one
  14 for Gtk and another generic one for anything other than Gtk.
  15 It is only available if \texttt{wxUSE\_FILECTRL} is set to $1$.
  16
  17 \wxheading{Derived from}
  18
  19 \helpref{wxWindow}{wxwindow}\\
  20 \helpref{wxEvtHandler}{wxevthandler}\\
  21 \helpref{wxObject}{wxobject}
  22
  23 \wxheading{Include files}
  24
  25 <wx/filectrl.h>
  26
  27 \wxheading{Window styles}
  28
  29 \twocolwidtha{5cm}%
  30 \begin{twocollist}\itemsep=0pt
  31 \twocolitem{\windowstyle{wxFC\_DEFAULT\_STYLE}}{The default style: wxFC\_OPEN}
  32 \twocolitem{\windowstyle{wxFC\_OPEN}}{Creates an file control suitable for opening files.
  33 Cannot be combined with wxFC\_SAVE.}
  34 \twocolitem{\windowstyle{wxFC\_SAVE}}{Creates an file control suitable for saving files. Cannot be combined with wxFC\_OPEN.}
  35 \twocolitem{\windowstyle{wxFC\_MULTIPLE}}{For open control only, Allows selecting multiple files. Cannot be combined with wxFC\_SAVE}
  36 \twocolitem{\windowstyle{wxFC\_NOSHOWHIDDEN}}{Hides the ``Show Hidden Files" checkbox (Generic only)}
  37 \end{twocollist}
  38
  39 \wxheading{Event handling}
  40
  41 To process a file control event, use these event handler macros to direct
  42 input to member functions that take a \helpref{wxFileCtrlEvent}{wxfilectrlevent}
  43 argument.
  44
  45 \twocolwidtha{7cm}%
  46 \begin{twocollist}\itemsep=0pt
  47 \twocolitem{{\bf EVT\_FILECTRL\_FILEACTIVATED(id, func)}}{The user activated a file(by double-clicking or pressing Enter)}
  48 \twocolitem{{\bf EVT\_FILECTRL\_SELECTIONCHANGED(id, func)}}{The user changed the current selection(by selecting or deselecting a file)}
  49 \twocolitem{{\bf EVT\_FILECTRL\_FOLDERCHANGED(id, func)}}{The current folder of the file control has been changed}
  50 \end{twocollist}
  51
  52 \wxheading{See also}
  53
  54 \helpref{wxGenericDirCtrl}{wxgenericdirctrl}
  55
  56 \latexignore{\rtfignore{\wxheading{Members}}}
  57
  58 \membersection{wxFileCtrl::wxFileCtrl}\label{wxfilectrlctor}
  59
  60 \func{}{wxFileCtrl}{\void}
  61
  62 Default constructor.
  63
  64 \func{}{wxFileCtrl}{\param{wxWindow *}{parent},\rtfsp
  65 \param{wxWindowID}{ id},\rtfsp
  66 \param{const wxString\& }{defaultDirectory = wxEmptyString},\rtfsp
  67 \param{const wxString\& }{defaultFilename = wxEmptyString},\rtfsp
  68 \param{const wxPoint\& }{wildCard = wxFileSelectorDefaultWildcardStr},\rtfsp
  69 \param{long}{ style = wxFC\_DEFAULT\_STYLE},\rtfsp
  70 \param{const wxPoint\& }{pos = wxDefaultPosition},
  71 \param{const wxSize\& }{size = wxDefaultSize},
  72 \param{const wxString\& }{name = ``filectrl"}}
  73
  74 \wxheading{Parameters}
  75
  76 \docparam{parent}{Parent window, must not be non-\texttt{NULL}.}
  77
  78 \docparam{id}{The identifier for the control.}
  79
  80 \docparam{defaultDirectory}{The initial directory shown in the control. Must be
  81 a valid path to a directory or the empty string.
  82 In case it is the empty string, the current working directory is used.}
  83
  84 \docparam{defaultFilename}{The default filename, or the empty string.}
  85
  86 \docparam{wildcard}{A wildcard specifying which files can be selected,
  87 such as ``*.*" or ``BMP files (*.bmp)|*.bmp|GIF files (*.gif)|*.gif".}
  88
  89 \docparam{style}{The window style, see {\tt wxFC\_*} flags.}
  90
  91 \docparam{pos}{Initial position.}
  92
  93 \docparam{size}{Initial size.}
  94
  95 \docparam{name}{Control name.}
  96
  97 \wxheading{Return value}
  98
  99 \true if the control was successfully created or \false if creation failed.
 100
 101 \membersection{wxFileCtrl::Create}\label{wxfilectrlcreate}
 102
 103 \func{bool}{Create}{\param{wxWindow *}{parent},\rtfsp
 104 \param{wxWindowID}{ id},\rtfsp
 105 \param{const wxString\& }{defaultDirectory = wxEmptyString},\rtfsp
 106 \param{const wxString\& }{defaultFilename = wxEmptyString},\rtfsp
 107 \param{const wxPoint\& }{wildCard = wxFileSelectorDefaultWildcardStr},\rtfsp
 108 \param{long}{ style = wxFC\_DEFAULT\_STYLE},\rtfsp
 109 \param{const wxPoint\& }{pos = wxDefaultPosition},
 110 \param{const wxSize\& }{size = wxDefaultSize},
 111 \param{const wxString\& }{name = ``filectrl"}}
 112
 113 Create function for two-step construction. See \helpref{wxFileCtrl::wxFileCtrl}{wxfilectrlctor} for details.
 114
 115 \membersection{wxFileDialog::GetFilename}\label{wxfilectrlgetfilename}
 116
 117 \constfunc{wxString}{GetFilename}{\void}
 118
 119 Returns the currently selected filename.
 120 For the controls having the {\tt wxFC\_MULTIPLE} style, use \helpref{GetFilenames}{wxfilectrlgetfilenames}
 121 instead
 122
 123 \membersection{wxFileCtrl::GetDirectory}\label{wxfilectrlgetdirectory}
 124
 125 \constfunc{wxString}{GetDirectory}{\void}
 126
 127 Returns the current directory of the file control (i.e. the directory shown by
 128 it).
 129
 130 \membersection{wxFileCtrl::GetWildcard}\label{wxfilectrlgetwildcard}
 131
 132 \constfunc{wxString}{GetWildcard}{\void}
 133
 134 Returns the current wildcard.
 135
 136 \membersection{wxFileCtrl::GetPath}\label{wxfilectrlgetpath}
 137
 138 \constfunc{wxString}{GetPath}{\void}
 139
 140 Returns the full path (directory and filename) of the currently selected file.
 141 For the controls having the {\tt wxFC\_MULTIPLE} style, use \helpref{GetPaths}{wxfilectrlgetpaths}
 142 instead
 143
 144 \membersection{wxFileCtrl::GetPaths}\label{wxfilectrlgetpaths}
 145
 146 \constfunc{void}{GetPaths}{\param{wxArrayString\& }{paths}}
 147
 148 Fills the array {\it paths} with the full paths of the files chosen. This
 149 function should be used with the controls having the {\tt wxFC\_MULTIPLE} style,
 150 use \helpref{GetPath}{wxfilectrlgetpath} otherwise.
 151
 152 \wxheading{Remarks}
 153
 154 {\it paths} is emptied first.
 155
 156 \membersection{wxFileCtrl::GetFilenames}\label{wxfilectrlgetfilenames}
 157
 158 \constfunc{void}{GetFilenames}{\param{wxArrayString\& }{filenames}}
 159
 160 Fills the array {\it filenames} with the filenames only of selected items. This
 161 function should only be used with the controls having the {\tt wxFC\_MULTIPLE} style,
 162 use \helpref{GetFilename}{wxfilectrlgetfilename} for the others.
 163
 164 \wxheading{Remarks}
 165
 166 {\it filenames} is emptied first.
 167
 168 \membersection{wxFileCtrl::GetFilterIndex}\label{wxfilectrlgetfilterindex}
 169
 170 \constfunc{int}{GetFilterIndex}{\void}
 171
 172 Returns the zero-based index of the currently selected filter.
 173
 174 \membersection{wxFileCtrl::ShowHidden}\label{wxfilectrlshowhidden}
 175
 176 \func{void}{ShowHidden}{\param{const bool }{show}}
 177
 178 Sets whether hidden files and folders are shown or not.
 179
 180 \membersection{wxFileCtrl::SetWildcard}\label{wxfilectrlsetwildcard}
 181
 182 \func{void}{SetWildcard}{\param{const wxString\& }{wildCard}}
 183
 184 Sets the wildcard, which can contain multiple file types, for example:
 185
 186 ``BMP files (*.bmp)|*.bmp|GIF files (*.gif)|*.gif"
 187
 188 \membersection{wxFileCtrl::SetFilterIndex}\label{wxfilectrlsetfilterindex}
 189
 190 \func{void}{SetFilterIndex}{\param{int }{filterIndex}}
 191
 192 Sets the current filter index, starting from zero.
 193
 194 \membersection{wxFileCtrl::SetDirectory}\label{wxfilectrlsetdirectory}
 195
 196 \func{bool}{SetDirectory}{\param{const wxString\& }{directory}}
 197
 198 Sets(changes) the current directory displayed in the control.
 199
 200 \wxheading{Return value}
 201
 202 Returns \true on success, \false otherwise.
 203
 204 \membersection{wxFileCtrl::SetFilename}\label{wxfilectrlsetfilename}
 205
 206 \func{bool}{SetFilename}{\param{const wxString\& }{filename}}
 207
 208 Selects a certain file.
 209
 210 \wxheading{Return value}
 211
 212 Returns \true on success, \false otherwise
 213
 214 \membersection{wxFileCtrl::SetPath}\label{wxfilectrlsetpath}
 215
 216 \func{bool}{SetPath}{\param{const wxString\& }{path}}
 217
 218 Selects a certain file using its path (the combined directory and filename).
 219 Equivalent to \helpref{SetPath}{wxfilectrlsetpath} then \helpref{SetFilename}{wxfilectrlsetfilename}.
 220
 221 \wxheading{Return value}
 222
 223 Returns \true on success, \false otherwise.