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