interface/filectrl.h

   1 /////////////////////////////////////////////////////////////////////////////
   2 // Name:        filectrl.h
   3 // Purpose:     documentation for wxFileCtrl class
   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     @seealso
  37     wxGenericDirCtrl
  38 */
  39 class wxFileCtrl : public wxWindow
  40 {
  41 public:
  42     //@{
  43     /**
  44         @param parent
  45             Parent window, must not be non-@NULL.
  46         @param id
  47             The identifier for the control.
  48         @param defaultDirectory
  49             The initial directory shown in the control. Must be
  50             a valid path to a directory or the empty string.
  51             In case it is the empty string, the current working directory is used.
  52         @param defaultFilename
  53             The default filename, or the empty string.
  54         @param wildcard
  55             A wildcard specifying which files can be selected,
  56             such as "*.*" or "BMP files (*.bmp)|*.bmp|GIF files (*.gif)|*.gif".
  57         @param style
  58             The window style, see wxFC_* flags.
  59         @param pos
  60             Initial position.
  61         @param size
  62             Initial size.
  63         @param name
  64             Control name.
  65
  66         @returns @true if the control was successfully created or @false if
  67                  creation failed.
  68     */
  69     wxFileCtrl();
  70     wxFileCtrl(wxWindow* parent, wxWindowID id,
  71                const wxString& defaultDirectory = wxEmptyString,
  72                const wxString& defaultFilename = wxEmptyString,
  73                const wxPoint& wildCard = wxFileSelectorDefaultWildcardStr,
  74                long style = wxFC_DEFAULT_STYLE,
  75                const wxPoint& pos = wxDefaultPosition,
  76                const wxSize& size = wxDefaultSize,
  77                const wxString& name = "filectrl");
  78     //@}
  79
  80     /**
  81         Create function for two-step construction. See wxFileCtrl() for details.
  82     */
  83     bool Create(wxWindow* parent, wxWindowID id,
  84                 const wxString& defaultDirectory = wxEmptyString,
  85                 const wxString& defaultFilename = wxEmptyString,
  86                 const wxPoint& wildCard = wxFileSelectorDefaultWildcardStr,
  87                 long style = wxFC_DEFAULT_STYLE,
  88                 const wxPoint& pos = wxDefaultPosition,
  89                 const wxSize& size = wxDefaultSize,
  90                 const wxString& name = "filectrl");
  91
  92     /**
  93         Returns the current directory of the file control (i.e. the directory shown by
  94         it).
  95     */
  96     wxString GetDirectory() const;
  97
  98     /**
  99         Returns the currently selected filename.
 100         For the controls having the @c wxFC_MULTIPLE style, use GetFilenames()
 101         instead
 102     */
 103     wxString GetFilename() const;
 104
 105     /**
 106         Fills the array @a filenames with the filenames only of selected items. This
 107         function should only be used with the controls having the @c wxFC_MULTIPLE
 108         style,
 109         use GetFilename() for the others.
 110
 111         @remarks filenames is emptied first.
 112     */
 113     void GetFilenames(wxArrayString& filenames) const;
 114
 115     /**
 116         Returns the zero-based index of the currently selected filter.
 117     */
 118     int GetFilterIndex() const;
 119
 120     /**
 121         Returns the full path (directory and filename) of the currently selected file.
 122         For the controls having the @c wxFC_MULTIPLE style, use GetPaths()
 123         instead
 124     */
 125     wxString GetPath() const;
 126
 127     /**
 128         Fills the array @a paths with the full paths of the files chosen. This
 129         function should be used with the controls having the @c wxFC_MULTIPLE style,
 130         use GetPath() otherwise.
 131
 132         @remarks paths is emptied first.
 133     */
 134     void GetPaths(wxArrayString& paths) const;
 135
 136     /**
 137         Returns the current wildcard.
 138     */
 139     wxString GetWildcard() const;
 140
 141     /**
 142         Sets(changes) the current directory displayed in the control.
 143
 144         @returns Returns @true on success, @false otherwise.
 145     */
 146     bool SetDirectory(const wxString& directory);
 147
 148     /**
 149         Selects a certain file.
 150
 151         @returns Returns @true on success, @false otherwise
 152     */
 153     bool SetFilename(const wxString& filename);
 154
 155     /**
 156         Sets the current filter index, starting from zero.
 157     */
 158     void SetFilterIndex(int filterIndex);
 159
 160     /**
 161         Sets the wildcard, which can contain multiple file types, for example:
 162         "BMP files (*.bmp)|*.bmp|GIF files (*.gif)|*.gif"
 163     */
 164     void SetWildcard(const wxString& wildCard);
 165
 166     /**
 167         Sets whether hidden files and folders are shown or not.
 168     */
 169     void ShowHidden(const bool show);
 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 };