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