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