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