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