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