interface/wx/dirctrl.h

   1 /////////////////////////////////////////////////////////////////////////////
   2 // Name:        dirctrl.h
   3 // Purpose:     interface of wxGenericDirCtrl
   4 // Author:      wxWidgets team
   5 // RCS-ID:      $Id$
   6 // Licence:     wxWindows licence
   7 /////////////////////////////////////////////////////////////////////////////
   8
   9 enum
  10 {
  11     // Only allow directory viewing/selection, no files
  12     wxDIRCTRL_DIR_ONLY       = 0x0010,
  13     // When setting the default path, select the first file in the directory
  14     wxDIRCTRL_SELECT_FIRST   = 0x0020,
  15     // Use 3D borders on internal controls
  16     wxDIRCTRL_3D_INTERNAL    = 0x0080,
  17     // Editable labels
  18     wxDIRCTRL_EDIT_LABELS    = 0x0100,
  19     // Allow multiple selection
  20     wxDIRCTRL_MULTIPLE       = 0x0200
  21 };
  22
  23
  24 /**
  25     @class wxGenericDirCtrl
  26
  27     This control can  be used to place a directory listing (with optional
  28     files) on an arbitrary window.
  29
  30     The control contains a wxTreeCtrl window representing the directory
  31     hierarchy, and optionally, a wxChoice window containing a list of filters.
  32
  33     @beginStyleTable
  34     @style{wxDIRCTRL_DIR_ONLY}
  35            Only show directories, and not files.
  36     @style{wxDIRCTRL_3D_INTERNAL}
  37            Use 3D borders for internal controls.
  38     @style{wxDIRCTRL_SELECT_FIRST}
  39            When setting the default path, select the first file in the
  40            directory.
  41     @style{wxDIRCTRL_EDIT_LABELS}
  42            Allow the folder and file labels to be editable.
  43     @style{wxDIRCTRL_MULTIPLE}
  44            Allows multiple files and folders to be selected.
  45     @endStyleTable
  46
  47     @library{wxcore}
  48     @category{ctrl}
  49     @appearance{genericdirctrl}
  50     @event{EVT_DIRCTRL_CHANGED(id, func)}
  51           Selected directory has changed.
  52           Processes a @c wxEVT_COMMAND_DIRCTRL_CHANGED event type.
  53           Notice that this event is generated even for the changes done by the
  54           program itself and not only those done by the user.
  55           @since 2.9.5
  56 */
  57 class wxGenericDirCtrl : public wxControl
  58 {
  59 public:
  60     /**
  61         Default constructor.
  62     */
  63     wxGenericDirCtrl();
  64
  65     /**
  66         Main constructor.
  67
  68         @param parent
  69             Parent window.
  70         @param id
  71             Window identifier.
  72         @param dir
  73             Initial folder.
  74         @param pos
  75             Position.
  76         @param size
  77             Size.
  78         @param style
  79             Window style. Please see wxGenericDirCtrl for a list of possible
  80             styles.
  81         @param filter
  82             A filter string, using the same syntax as that for wxFileDialog.
  83             This may be empty if filters are not being used. Example:
  84             @c "All files (*.*)|*.*|JPEG files (*.jpg)|*.jpg"
  85         @param defaultFilter
  86             The zero-indexed default filter setting.
  87         @param name
  88             The window name.
  89     */
  90     wxGenericDirCtrl(wxWindow* parent, const wxWindowID id = wxID_ANY,
  91                      const wxString& dir = wxDirDialogDefaultFolderStr,
  92                      const wxPoint& pos = wxDefaultPosition,
  93                      const wxSize& size = wxDefaultSize,
  94                      long style = wxDIRCTRL_3D_INTERNAL,
  95                      const wxString& filter = wxEmptyString,
  96                      int defaultFilter = 0,
  97                      const wxString& name = wxTreeCtrlNameStr);
  98
  99     /**
 100         Destructor.
 101     */
 102     virtual ~wxGenericDirCtrl();
 103
 104     /**
 105         Collapse the given @a path.
 106     */
 107     virtual bool CollapsePath(const wxString& path);
 108
 109     /**
 110         Collapses the entire tree.
 111     */
 112     virtual void CollapseTree();
 113
 114     /**
 115         Create function for two-step construction. See wxGenericDirCtrl() for
 116         details.
 117     */
 118     bool Create(wxWindow* parent, const wxWindowID id = wxID_ANY,
 119                 const wxString& dir = wxDirDialogDefaultFolderStr,
 120                 const wxPoint& pos = wxDefaultPosition,
 121                 const wxSize& size = wxDefaultSize,
 122                 long style = wxDIRCTRL_3D_INTERNAL,
 123                 const wxString& filter = wxEmptyString, int defaultFilter = 0,
 124                 const wxString& name = wxTreeCtrlNameStr);
 125
 126     /**
 127         Tries to expand as much of the given @a path as possible, so that the
 128         filename or directory is visible in the tree control.
 129     */
 130     virtual bool ExpandPath(const wxString& path);
 131
 132     /**
 133         Gets the default path.
 134     */
 135     virtual wxString GetDefaultPath() const;
 136
 137     /**
 138         Gets selected filename path only (else empty string).
 139
 140         This function doesn't count a directory as a selection.
 141     */
 142     virtual wxString GetFilePath() const;
 143
 144     /**
 145         Fills the array @a paths with the currently selected filepaths.
 146
 147         This function doesn't count a directory as a selection.
 148     */
 149     virtual void GetFilePaths(wxArrayString& paths) const;
 150
 151     /**
 152         Returns the filter string.
 153     */
 154     virtual wxString GetFilter() const;
 155
 156     /**
 157         Returns the current filter index (zero-based).
 158     */
 159     virtual int GetFilterIndex() const;
 160
 161     /**
 162         Returns a pointer to the filter list control (if present).
 163     */
 164     virtual wxDirFilterListCtrl* GetFilterListCtrl() const;
 165
 166     /**
 167         Gets the currently-selected directory or filename.
 168     */
 169     virtual wxString GetPath() const;
 170
 171     /**
 172         Gets the path corresponding to the given tree control item.
 173
 174         @since 2.9.5
 175     */
 176     wxString GetPath(wxTreeItemId itemId) const;
 177
 178     /**
 179         Fills the array @a paths with the selected directories and filenames.
 180     */
 181     virtual void GetPaths(wxArrayString& paths) const;
 182
 183     /**
 184         Returns the root id for the tree control.
 185     */
 186     virtual wxTreeItemId GetRootId();
 187
 188     /**
 189         Returns a pointer to the tree control.
 190     */
 191     virtual wxTreeCtrl* GetTreeCtrl() const;
 192
 193     /**
 194         Initializes variables.
 195     */
 196     virtual void Init();
 197
 198     /**
 199         Collapse and expand the tree, thus re-creating it from scratch. May be
 200         used to update the displayed directory content.
 201     */
 202     virtual void ReCreateTree();
 203
 204     /**
 205         Sets the default path.
 206     */
 207     virtual void SetDefaultPath(const wxString& path);
 208
 209     /**
 210         Sets the filter string.
 211     */
 212     virtual void SetFilter(const wxString& filter);
 213
 214     /**
 215         Sets the current filter index (zero-based).
 216     */
 217     virtual void SetFilterIndex(int n);
 218
 219     /**
 220         Sets the current path.
 221     */
 222     virtual void SetPath(const wxString& path);
 223
 224     /**
 225         @param show
 226             If @true, hidden folders and files will be displayed by the
 227             control. If @false, they will not be displayed.
 228     */
 229     virtual void ShowHidden(bool show);
 230
 231     /**
 232         Selects the given item.
 233
 234         In multiple selection controls, can be also used to deselect a
 235         currently selected item if the value of @a select is false.
 236         Existing selections are not changed. Only visible items can be
 237         (de)selected, otherwise use ExpandPath().
 238     */
 239     virtual void SelectPath(const wxString& path, bool select = true);
 240
 241     /**
 242         Selects only the specified paths, clearing any previous selection.
 243
 244         Only supported when wxDIRCTRL_MULTIPLE is set.
 245     */
 246     virtual void SelectPaths(const wxArrayString& paths);
 247
 248     /**
 249         Removes the selection from all currently selected items.
 250     */
 251     virtual void UnselectAll();
 252 };
 253
 254
 255
 256 class wxDirFilterListCtrl: public wxChoice
 257 {
 258 public:
 259     wxDirFilterListCtrl();
 260     wxDirFilterListCtrl(wxGenericDirCtrl* parent, const wxWindowID id = wxID_ANY,
 261                         const wxPoint& pos = wxDefaultPosition,
 262                         const wxSize& size = wxDefaultSize,
 263                         long style = 0);
 264     bool Create(wxGenericDirCtrl* parent, const wxWindowID id = wxID_ANY,
 265                 const wxPoint& pos = wxDefaultPosition,
 266                 const wxSize& size = wxDefaultSize,
 267                 long style = 0);
 268
 269     virtual ~wxDirFilterListCtrl() {}
 270
 271     void Init();
 272
 273     //// Operations
 274     void FillFilterList(const wxString& filter, int defaultFilter);
 275 };