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