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