juce/source/src/gui/components/controls/juce_TableListBox.h

   1 /*
   2   ==============================================================================
   3
   4    This file is part of the JUCE library - "Jules' Utility Class Extensions"
   5    Copyright 2004-11 by Raw Material Software Ltd.
   6
   7   ------------------------------------------------------------------------------
   8
   9    JUCE can be redistributed and/or modified under the terms of the GNU General
  10    Public License (Version 2), as published by the Free Software Foundation.
  11    A copy of the license is included in the JUCE distribution, or can be found
  12    online at www.gnu.org/licenses.
  13
  14    JUCE is distributed in the hope that it will be useful, but WITHOUT ANY
  15    WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR
  16    A PARTICULAR PURPOSE.  See the GNU General Public License for more details.
  17
  18   ------------------------------------------------------------------------------
  19
  20    To release a closed-source product which uses JUCE, commercial licenses are
  21    available: visit www.rawmaterialsoftware.com/juce for more information.
  22
  23   ==============================================================================
  24 */
  25
  26 #ifndef __JUCE_TABLELISTBOX_JUCEHEADER__
  27 #define __JUCE_TABLELISTBOX_JUCEHEADER__
  28
  29 #include "juce_TableHeaderComponent.h"
  30 #include "juce_ListBox.h"
  31
  32
  33 //==============================================================================
  34 /**
  35     One of these is used by a TableListBox as the data model for the table's contents.
  36
  37     The virtual methods that you override in this class take care of drawing the
  38     table cells, and reacting to events.
  39
  40     @see TableListBox
  41 */
  42 class JUCE_API  TableListBoxModel
  43 {
  44 public:
  45     //==============================================================================
  46     TableListBoxModel()  {}
  47
  48     /** Destructor. */
  49     virtual ~TableListBoxModel()  {}
  50
  51     //==============================================================================
  52     /** This must return the number of rows currently in the table.
  53
  54         If the number of rows changes, you must call TableListBox::updateContent() to
  55         cause it to refresh the list.
  56     */
  57     virtual int getNumRows() = 0;
  58
  59     /** This must draw the background behind one of the rows in the table.
  60
  61         The graphics context has its origin at the row's top-left, and your method
  62         should fill the area specified by the width and height parameters.
  63     */
  64     virtual void paintRowBackground (Graphics& g,
  65                                      int rowNumber,
  66                                      int width, int height,
  67                                      bool rowIsSelected) = 0;
  68
  69     /** This must draw one of the cells.
  70
  71         The graphics context's origin will already be set to the top-left of the cell,
  72         whose size is specified by (width, height).
  73     */
  74     virtual void paintCell (Graphics& g,
  75                             int rowNumber,
  76                             int columnId,
  77                             int width, int height,
  78                             bool rowIsSelected) = 0;
  79
  80     //==============================================================================
  81     /** This is used to create or update a custom component to go in a cell.
  82
  83         Any cell may contain a custom component, or can just be drawn with the paintCell() method
  84         and handle mouse clicks with cellClicked().
  85
  86         This method will be called whenever a custom component might need to be updated - e.g.
  87         when the table is changed, or TableListBox::updateContent() is called.
  88
  89         If you don't need a custom component for the specified cell, then return 0.
  90
  91         If you do want a custom component, and the existingComponentToUpdate is null, then
  92         this method must create a new component suitable for the cell, and return it.
  93
  94         If the existingComponentToUpdate is non-null, it will be a pointer to a component previously created
  95         by this method. In this case, the method must either update it to make sure it's correctly representing
  96         the given cell (which may be different from the one that the component was created for), or it can
  97         delete this component and return a new one.
  98     */
  99     virtual Component* refreshComponentForCell (int rowNumber, int columnId, bool isRowSelected,
 100                                                 Component* existingComponentToUpdate);
 101
 102     //==============================================================================
 103     /** This callback is made when the user clicks on one of the cells in the table.
 104
 105         The mouse event's coordinates will be relative to the entire table row.
 106         @see cellDoubleClicked, backgroundClicked
 107     */
 108     virtual void cellClicked (int rowNumber, int columnId, const MouseEvent& e);
 109
 110     /** This callback is made when the user clicks on one of the cells in the table.
 111
 112         The mouse event's coordinates will be relative to the entire table row.
 113         @see cellClicked, backgroundClicked
 114     */
 115     virtual void cellDoubleClicked (int rowNumber, int columnId, const MouseEvent& e);
 116
 117     /** This can be overridden to react to the user double-clicking on a part of the list where
 118         there are no rows.
 119
 120         @see cellClicked
 121     */
 122     virtual void backgroundClicked();
 123
 124     //==============================================================================
 125     /** This callback is made when the table's sort order is changed.
 126
 127         This could be because the user has clicked a column header, or because the
 128         TableHeaderComponent::setSortColumnId() method was called.
 129
 130         If you implement this, your method should re-sort the table using the given
 131         column as the key.
 132     */
 133     virtual void sortOrderChanged (int newSortColumnId, bool isForwards);
 134
 135     //==============================================================================
 136     /** Returns the best width for one of the columns.
 137
 138         If you implement this method, you should measure the width of all the items
 139         in this column, and return the best size.
 140
 141         Returning 0 means that the column shouldn't be changed.
 142
 143         This is used by TableListBox::autoSizeColumn() and TableListBox::autoSizeAllColumns().
 144     */
 145     virtual int getColumnAutoSizeWidth (int columnId);
 146
 147     /** Returns a tooltip for a particular cell in the table.
 148     */
 149     virtual const String getCellTooltip (int rowNumber, int columnId);
 150
 151     //==============================================================================
 152     /** Override this to be informed when rows are selected or deselected.
 153
 154         @see ListBox::selectedRowsChanged()
 155     */
 156     virtual void selectedRowsChanged (int lastRowSelected);
 157
 158     /** Override this to be informed when the delete key is pressed.
 159
 160         @see ListBox::deleteKeyPressed()
 161     */
 162     virtual void deleteKeyPressed (int lastRowSelected);
 163
 164     /** Override this to be informed when the return key is pressed.
 165
 166         @see ListBox::returnKeyPressed()
 167     */
 168     virtual void returnKeyPressed (int lastRowSelected);
 169
 170     /** Override this to be informed when the list is scrolled.
 171
 172         This might be caused by the user moving the scrollbar, or by programmatic changes
 173         to the list position.
 174     */
 175     virtual void listWasScrolled();
 176
 177     /** To allow rows from your table to be dragged-and-dropped, implement this method.
 178
 179         If this returns a non-null variant then when the user drags a row, the table will try to
 180         find a DragAndDropContainer in its parent hierarchy, and will use it to trigger a
 181         drag-and-drop operation, using this string as the source description, and the listbox
 182         itself as the source component.
 183
 184         @see getDragSourceCustomData, DragAndDropContainer::startDragging
 185     */
 186     virtual const var getDragSourceDescription (const SparseSet<int>& currentlySelectedRows);
 187 };
 188
 189
 190 //==============================================================================
 191 /**
 192     A table of cells, using a TableHeaderComponent as its header.
 193
 194     This component makes it easy to create a table by providing a TableListBoxModel as
 195     the data source.
 196
 197
 198     @see TableListBoxModel, TableHeaderComponent
 199 */
 200 class JUCE_API  TableListBox   : public ListBox,
 201                                  private ListBoxModel,
 202                                  private TableHeaderComponent::Listener
 203 {
 204 public:
 205     //==============================================================================
 206     /** Creates a TableListBox.
 207
 208         The model pointer passed-in can be null, in which case you can set it later
 209         with setModel().
 210     */
 211     TableListBox (const String& componentName = String::empty,
 212                   TableListBoxModel* model = 0);
 213
 214     /** Destructor. */
 215     ~TableListBox();
 216
 217     //==============================================================================
 218     /** Changes the TableListBoxModel that is being used for this table.
 219     */
 220     void setModel (TableListBoxModel* newModel);
 221
 222     /** Returns the model currently in use. */
 223     TableListBoxModel* getModel() const                             { return model; }
 224
 225     //==============================================================================
 226     /** Returns the header component being used in this table. */
 227     TableHeaderComponent& getHeader() const                         { return *header; }
 228
 229     /** Sets the header component to use for the table.
 230         The table will take ownership of the component that you pass in, and will delete it
 231         when it's no longer needed.
 232     */
 233     void setHeader (TableHeaderComponent* newHeader);
 234
 235     /** Changes the height of the table header component.
 236         @see getHeaderHeight
 237     */
 238     void setHeaderHeight (int newHeight);
 239
 240     /** Returns the height of the table header.
 241         @see setHeaderHeight
 242     */
 243     int getHeaderHeight() const;
 244
 245     //==============================================================================
 246     /** Resizes a column to fit its contents.
 247
 248         This uses TableListBoxModel::getColumnAutoSizeWidth() to find the best width,
 249         and applies that to the column.
 250
 251         @see autoSizeAllColumns, TableHeaderComponent::setColumnWidth
 252     */
 253     void autoSizeColumn (int columnId);
 254
 255     /** Calls autoSizeColumn() for all columns in the table. */
 256     void autoSizeAllColumns();
 257
 258     /** Enables or disables the auto size options on the popup menu.
 259
 260         By default, these are enabled.
 261     */
 262     void setAutoSizeMenuOptionShown (bool shouldBeShown);
 263
 264     /** True if the auto-size options should be shown on the menu.
 265         @see setAutoSizeMenuOptionsShown
 266     */
 267     bool isAutoSizeMenuOptionShown() const;
 268
 269     /** Returns the position of one of the cells in the table.
 270
 271         If relativeToComponentTopLeft is true, the co-ordinates are relative to
 272         the table component's top-left. The row number isn't checked to see if it's
 273         in-range, but the column ID must exist or this will return an empty rectangle.
 274
 275         If relativeToComponentTopLeft is false, the co-ords are relative to the
 276         top-left of the table's top-left cell.
 277     */
 278     const Rectangle<int> getCellPosition (int columnId, int rowNumber,
 279                                           bool relativeToComponentTopLeft) const;
 280
 281     /** Returns the component that currently represents a given cell.
 282         If the component for this cell is off-screen or if the position is out-of-range,
 283         this may return 0.
 284         @see getCellPosition
 285     */
 286     Component* getCellComponent (int columnId, int rowNumber) const;
 287
 288     /** Scrolls horizontally if necessary to make sure that a particular column is visible.
 289
 290         @see ListBox::scrollToEnsureRowIsOnscreen
 291     */
 292     void scrollToEnsureColumnIsOnscreen (int columnId);
 293
 294     //==============================================================================
 295     /** @internal */
 296     int getNumRows();
 297     /** @internal */
 298     void paintListBoxItem (int, Graphics&, int, int, bool);
 299     /** @internal */
 300     Component* refreshComponentForRow (int rowNumber, bool isRowSelected, Component* existingComponentToUpdate);
 301     /** @internal */
 302     void selectedRowsChanged (int lastRowSelected);
 303     /** @internal */
 304     void deleteKeyPressed (int currentSelectedRow);
 305     /** @internal */
 306     void returnKeyPressed (int currentSelectedRow);
 307     /** @internal */
 308     void backgroundClicked();
 309     /** @internal */
 310     void listWasScrolled();
 311     /** @internal */
 312     void tableColumnsChanged (TableHeaderComponent*);
 313     /** @internal */
 314     void tableColumnsResized (TableHeaderComponent*);
 315     /** @internal */
 316     void tableSortOrderChanged (TableHeaderComponent*);
 317     /** @internal */
 318     void tableColumnDraggingChanged (TableHeaderComponent*, int);
 319     /** @internal */
 320     void resized();
 321
 322
 323 private:
 324     //==============================================================================
 325     TableHeaderComponent* header;
 326     TableListBoxModel* model;
 327     int columnIdNowBeingDragged;
 328     bool autoSizeOptionsShown;
 329
 330     void updateColumnComponents() const;
 331
 332     JUCE_DECLARE_NON_COPYABLE_WITH_LEAK_DETECTOR (TableListBox);
 333 };
 334
 335
 336 #endif   // __JUCE_TABLELISTBOX_JUCEHEADER__