interface/filectrl.h

   1 /////////////////////////////////////////////////////////////////////////////
   2 // Name:        filectrl.h
   3 // Purpose:     documentation for wxFileCtrl class
   4 // Author:      wxWidgets team
   5 // RCS-ID:      $Id$
   6 // Licence:     wxWindows license
   7 /////////////////////////////////////////////////////////////////////////////
   8
   9 /**
  10     @class wxFileCtrl
  11     @wxheader{filectrl.h}
  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 @c wxUSE_FILECTRL is set to 1.
  16
  17     @beginStyleTable
  18     @style{wxFC_DEFAULT_STYLE}:
  19            The default style: wxFC_OPEN
  20     @style{wxFC_OPEN}:
  21            Creates an file control suitable for opening files. Cannot be
  22            combined with wxFC_SAVE.
  23     @style{wxFC_SAVE}:
  24            Creates an file control suitable for saving files. Cannot be
  25            combined with wxFC_OPEN.
  26     @style{wxFC_MULTIPLE}:
  27            For open control only, Allows selecting multiple files. Cannot be
  28            combined with wxFC_SAVE
  29     @style{wxFC_NOSHOWHIDDEN}:
  30            Hides the "Show Hidden Files" checkbox (Generic only)
  31     @endStyleTable
  32
  33     @library{wxbase}
  34     @category{FIXME}
  35
  36     @seealso
  37     wxGenericDirCtrl
  38 */
  39 class wxFileCtrl : public wxWindow
  40 {
  41 public:
  42     //@{
  43     /**
  44         @param parent
  45         Parent window, must not be non-@NULL.
  46
  47         @param id
  48         The identifier for the control.
  49
  50         @param defaultDirectory
  51         The initial directory shown in the control. Must be
  52         a valid path to a directory or the empty string.
  53         In case it is the empty string, the current working directory is used.
  54
  55         @param defaultFilename
  56         The default filename, or the empty string.
  57
  58         @param wildcard
  59         A wildcard specifying which files can be selected,
  60         such as "*.*" or "BMP files (*.bmp)|*.bmp|GIF files (*.gif)|*.gif".
  61
  62         @param style
  63         The window style, see wxFC_* flags.
  64
  65         @param pos
  66         Initial position.
  67
  68         @param size
  69         Initial size.
  70
  71         @param name
  72         Control name.
  73
  74         @returns @true if the control was successfully created or @false if
  75                    creation failed.
  76     */
  77     wxFileCtrl();
  78     wxFileCtrl(wxWindow * parent, wxWindowID id,
  79                const wxString& defaultDirectory = wxEmptyString,
  80                const wxString& defaultFilename = wxEmptyString,
  81                const wxPoint& wildCard = wxFileSelectorDefaultWildcardStr,
  82                long style = wxFC_DEFAULT_STYLE,
  83                const wxPoint& pos = wxDefaultPosition,
  84                const wxSize& size = wxDefaultSize,
  85                const wxString& name = "filectrl");
  86     //@}
  87
  88     /**
  89         Create function for two-step construction. See wxFileCtrl() for details.
  90     */
  91     bool Create(wxWindow * parent, wxWindowID id,
  92                 const wxString& defaultDirectory = wxEmptyString,
  93                 const wxString& defaultFilename = wxEmptyString,
  94                 const wxPoint& wildCard = wxFileSelectorDefaultWildcardStr,
  95                 long style = wxFC_DEFAULT_STYLE,
  96                 const wxPoint& pos = wxDefaultPosition,
  97                 const wxSize& size = wxDefaultSize,
  98                 const wxString& name = "filectrl");
  99
 100     /**
 101         Returns the current directory of the file control (i.e. the directory shown by
 102         it).
 103     */
 104     wxString GetDirectory();
 105
 106     /**
 107         Returns the currently selected filename.
 108         For the controls having the @c wxFC_MULTIPLE style, use GetFilenames()
 109         instead
 110     */
 111     wxString GetFilename();
 112
 113     /**
 114         Fills the array @e filenames with the filenames only of selected items. This
 115         function should only be used with the controls having the @c wxFC_MULTIPLE
 116         style,
 117         use GetFilename() for the others.
 118
 119         @remarks filenames is emptied first.
 120     */
 121     void GetFilenames(wxArrayString& filenames);
 122
 123     /**
 124         Returns the zero-based index of the currently selected filter.
 125     */
 126     int GetFilterIndex();
 127
 128     /**
 129         Returns the full path (directory and filename) of the currently selected file.
 130         For the controls having the @c wxFC_MULTIPLE style, use GetPaths()
 131         instead
 132     */
 133     wxString GetPath();
 134
 135     /**
 136         Fills the array @e paths with the full paths of the files chosen. This
 137         function should be used with the controls having the @c wxFC_MULTIPLE style,
 138         use GetPath() otherwise.
 139
 140         @remarks paths is emptied first.
 141     */
 142     void GetPaths(wxArrayString& paths);
 143
 144     /**
 145         Returns the current wildcard.
 146     */
 147     wxString GetWildcard();
 148
 149     /**
 150         Sets(changes) the current directory displayed in the control.
 151
 152         @returns Returns @true on success, @false otherwise.
 153     */
 154     bool SetDirectory(const wxString& directory);
 155
 156     /**
 157         Selects a certain file.
 158
 159         @returns Returns @true on success, @false otherwise
 160     */
 161     bool SetFilename(const wxString& filename);
 162
 163     /**
 164         Sets the current filter index, starting from zero.
 165     */
 166     void SetFilterIndex(int filterIndex);
 167
 168     /**
 169         Sets the wildcard, which can contain multiple file types, for example:
 170
 171         "BMP files (*.bmp)|*.bmp|GIF files (*.gif)|*.gif"
 172     */
 173     void SetWildcard(const wxString& wildCard);
 174
 175     /**
 176         Sets whether hidden files and folders are shown or not.
 177     */
 178     void ShowHidden(const bool show);
 179 };
 180
 181
 182 /**
 183     @class wxFileCtrlEvent
 184     @wxheader{filectrl.h}
 185
 186     A file control event holds information about events associated with
 187     wxFileCtrl objects.
 188
 189     @library{wxbase}
 190     @category{FIXME}
 191 */
 192 class wxFileCtrlEvent : public wxCommandEvent
 193 {
 194 public:
 195     /**
 196         Constructor.
 197     */
 198     wxFileCtrlEvent(wxEventType type, wxObject evtObject, int id);
 199
 200     /**
 201         Returns the current directory.
 202         In case of a @b EVT_FILECTRL_FOLDERCHANGED, this method returns the new
 203         directory.
 204     */
 205     wxString GetDirectory();
 206
 207     /**
 208         Returns the file selected(assuming it is only one file).
 209     */
 210     wxString GetFile();
 211
 212     /**
 213         Returns the files selected.
 214         In case of a @b EVT_FILECTRL_SELECTIONCHANGED, this method returns the
 215         files selected after the event.
 216     */
 217     wxArrayString GetFiles();
 218
 219     /**
 220         Sets the files changed by this event.
 221     */
 222     wxFileCtrlEvent::SetFiles(const wxArrayString files);
 223 };