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