interface/wx/filectrl.h

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