interface/wx/filectrl.h

   1 /////////////////////////////////////////////////////////////////////////////
   2 // Name:        filectrl.h
   3 // Purpose:     interface of wxFileCtrl
   4 // Author:      wxWidgets team
   5 // RCS-ID:      $Id$
   6 // Licence:     wxWindows licence
   7 /////////////////////////////////////////////////////////////////////////////
   8
   9 enum
  10 {
  11     wxFC_OPEN              = 0x0001,
  12     wxFC_SAVE              = 0x0002,
  13     wxFC_MULTIPLE          = 0x0004,
  14     wxFC_NOSHOWHIDDEN      = 0x0008
  15 };
  16
  17 #define wxFC_DEFAULT_STYLE wxFC_OPEN
  18
  19 /**
  20     @class wxFileCtrl
  21
  22     This control allows the user to select a file.
  23
  24     Two implementations of this class exist, one for Gtk and another generic
  25     one for all the other ports.
  26
  27     This class is only available if @c wxUSE_FILECTRL is set to 1.
  28
  29     @beginStyleTable
  30     @style{wxFC_DEFAULT_STYLE}
  31            The default style: wxFC_OPEN
  32     @style{wxFC_OPEN}
  33            Creates an file control suitable for opening files. Cannot be
  34            combined with wxFC_SAVE.
  35     @style{wxFC_SAVE}
  36            Creates an file control suitable for saving files. Cannot be
  37            combined with wxFC_OPEN.
  38     @style{wxFC_MULTIPLE}
  39            For open control only, Allows selecting multiple files. Cannot be
  40            combined with wxFC_SAVE
  41     @style{wxFC_NOSHOWHIDDEN}
  42            Hides the "Show Hidden Files" checkbox (Generic only)
  43     @endStyleTable
  44
  45     @beginEventEmissionTable{wxFileCtrlEvent}
  46     @event{EVT_FILECTRL_FILEACTIVATED(id, func)}
  47         The user activated a file(by double-clicking or pressing Enter)
  48     @event{EVT_FILECTRL_SELECTIONCHANGED(id, func)}
  49         The user changed the current selection(by selecting or deselecting a file)
  50     @event{EVT_FILECTRL_FOLDERCHANGED(id, func)}
  51         The current folder of the file control has been changed
  52     @event{EVT_FILECTRL_FILTERCHANGED(id, func)}
  53         The current file filter of the file control has been changed.
  54         @since 2.9.1.
  55
  56     @endEventTable
  57
  58     @library{wxcore}
  59     @category{ctrl}
  60     @appearance{filectrl.png}
  61
  62     @nativeimpl{wxgtk}
  63
  64     @see wxGenericDirCtrl
  65 */
  66 class wxFileCtrl : public wxControl
  67 {
  68 public:
  69     wxFileCtrl();
  70
  71     /**
  72         Constructs the window.
  73
  74         @param parent
  75             Parent window, must not be non-@NULL.
  76         @param id
  77             The identifier for the control.
  78         @param defaultDirectory
  79             The initial directory shown in the control.
  80             Must be a valid path to a directory or the empty string.
  81             In case it is the empty string, the current working directory is used.
  82         @param defaultFilename
  83             The default filename, or the empty string.
  84         @param wildCard
  85             A wildcard specifying which files can be selected,
  86             such as "*.*" or "BMP files (*.bmp)|*.bmp|GIF files (*.gif)|*.gif".
  87         @param style
  88             The window style, see wxFC_* flags.
  89         @param pos
  90             Initial position.
  91         @param size
  92             Initial size.
  93         @param name
  94             Control name.
  95
  96         @return @true if the control was successfully created or @false if
  97                  creation failed.
  98     */
  99
 100     wxFileCtrl(wxWindow* parent, wxWindowID id,
 101                const wxString& defaultDirectory = wxEmptyString,
 102                const wxString& defaultFilename = wxEmptyString,
 103                const wxString& wildCard = wxFileSelectorDefaultWildcardStr,
 104                long style = wxFC_DEFAULT_STYLE,
 105                const wxPoint& pos = wxDefaultPosition,
 106                const wxSize& size = wxDefaultSize,
 107                const wxString& name = wxFileCtrlNameStr);
 108
 109     /**
 110         Create function for two-step construction. See wxFileCtrl() for details.
 111     */
 112     bool Create(wxWindow* parent, wxWindowID id,
 113                 const wxString& defaultDirectory = wxEmptyString,
 114                 const wxString& defaultFilename = wxEmptyString,
 115                 const wxString& wildCard = wxFileSelectorDefaultWildcardStr,
 116                 long style = wxFC_DEFAULT_STYLE, const wxPoint& pos = wxDefaultPosition,
 117                 const wxSize& size = wxDefaultSize,
 118                 const wxString& name = wxFileCtrlNameStr);
 119
 120     /**
 121         Returns the current directory of the file control (i.e. the directory shown by it).
 122     */
 123     virtual wxString GetDirectory() const;
 124
 125     /**
 126         Returns the currently selected filename.
 127
 128         For the controls having the @c wxFC_MULTIPLE style, use GetFilenames() instead.
 129     */
 130     virtual wxString GetFilename() const;
 131
 132     /**
 133         Fills the array @a filenames with the filenames only of selected items.
 134
 135         This function should only be used with the controls having the @c wxFC_MULTIPLE
 136         style, use GetFilename() for the others.
 137
 138         @remarks filenames is emptied first.
 139     */
 140     virtual void GetFilenames(wxArrayString& filenames) const;
 141
 142     /**
 143         Returns the zero-based index of the currently selected filter.
 144     */
 145     virtual int GetFilterIndex() const;
 146
 147     /**
 148         Returns the full path (directory and filename) of the currently selected file.
 149         For the controls having the @c wxFC_MULTIPLE style, use GetPaths() instead.
 150     */
 151     virtual wxString GetPath() const;
 152
 153     /**
 154         Fills the array @a paths with the full paths of the files chosen.
 155
 156         This function should be used with the controls having the @c wxFC_MULTIPLE style,
 157         use GetPath() otherwise.
 158
 159         @remarks paths is emptied first.
 160     */
 161     virtual void GetPaths(wxArrayString& paths) const;
 162
 163     /**
 164         Returns the current wildcard.
 165     */
 166     virtual wxString GetWildcard() const;
 167
 168     /**
 169         Sets(changes) the current directory displayed in the control.
 170
 171         @return Returns @true on success, @false otherwise.
 172     */
 173     virtual bool SetDirectory(const wxString& directory);
 174
 175     /**
 176         Selects a certain file.
 177
 178         @return Returns @true on success, @false otherwise
 179     */
 180     virtual bool SetFilename(const wxString& filename);
 181
 182     /**
 183         Changes to a certain directory and selects a certain file.
 184
 185         In case the filename specified isn't found/couldn't be shown with
 186         currently selected filter, false is returned.
 187
 188         @return Returns @true on success, @false otherwise
 189     */
 190     virtual bool SetPath(const wxString& path);
 191
 192     /**
 193         Sets the current filter index, starting from zero.
 194     */
 195     virtual void SetFilterIndex(int filterIndex);
 196
 197     /**
 198         Sets the wildcard, which can contain multiple file types, for example:
 199         "BMP files (*.bmp)|*.bmp|GIF files (*.gif)|*.gif"
 200     */
 201     virtual void SetWildcard(const wxString& wildCard);
 202
 203     /**
 204         Sets whether hidden files and folders are shown or not.
 205     */
 206     virtual void ShowHidden(bool show);
 207 };
 208
 209
 210 wxEventType wxEVT_FILECTRL_SELECTIONCHANGED;
 211 wxEventType wxEVT_FILECTRL_FILEACTIVATED;
 212 wxEventType wxEVT_FILECTRL_FOLDERCHANGED;
 213 wxEventType wxEVT_FILECTRL_FILTERCHANGED;
 214
 215
 216 /**
 217     @class wxFileCtrlEvent
 218
 219     A file control event holds information about events associated with
 220     wxFileCtrl objects.
 221
 222     @beginEventTable{wxFileCtrlEvent}
 223     @event{EVT_FILECTRL_FILEACTIVATED(id, func)}
 224         The user activated a file(by double-clicking or pressing Enter)
 225     @event{EVT_FILECTRL_SELECTIONCHANGED(id, func)}
 226         The user changed the current selection(by selecting or deselecting a file)
 227     @event{EVT_FILECTRL_FOLDERCHANGED(id, func)}
 228         The current folder of the file control has been changed
 229     @event{EVT_FILECTRL_FILTERCHANGED(id, func)}
 230         The current file filter of the file control has been changed
 231     @endEventTable
 232
 233     @library{wxbase}
 234     @category{events}
 235 */
 236 class wxFileCtrlEvent : public wxCommandEvent
 237 {
 238 public:
 239     /**
 240         Constructor.
 241     */
 242     wxFileCtrlEvent(wxEventType type, wxObject *evtObject, int id);
 243
 244     /**
 245         Returns the current directory.
 246
 247         In case of a @b EVT_FILECTRL_FOLDERCHANGED, this method returns the new
 248         directory.
 249     */
 250     wxString GetDirectory() const;
 251
 252     /**
 253         Returns the file selected (assuming it is only one file).
 254     */
 255     wxString GetFile() const;
 256
 257     /**
 258         Returns the files selected.
 259
 260         In case of a @b EVT_FILECTRL_SELECTIONCHANGED, this method returns the
 261         files selected after the event.
 262     */
 263     wxArrayString GetFiles() const;
 264
 265     /**
 266         Returns the current file filter index.
 267
 268         For a @b EVT_FILECTRL_FILTERCHANGED event, this method returns the new
 269         file filter index.
 270
 271         @since 2.9.1
 272     */
 273     int GetFilterIndex() const;
 274
 275     /**
 276         Sets the files changed by this event.
 277     */
 278     void SetFiles(const wxArrayString& files);
 279
 280
 281     /**
 282         Sets the directory of this event.
 283     */
 284     void SetDirectory( const wxString &directory );
 285
 286     /**
 287         Sets the filter index changed by this event.
 288
 289         @since 2.9.1
 290     */
 291     void SetFilterIndex(int index);
 292 };
 293