interface/wx/dirctrl.h

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