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