source/modules/juce_gui_basics/widgets/juce_ListBox.h

   1 /*
   2   ==============================================================================
   3
   4    This file is part of the JUCE library.
   5    Copyright (c) 2022 - Raw Material Software Limited
   6
   7    JUCE is an open source library subject to commercial or open-source
   8    licensing.
   9
  10    By using JUCE, you agree to the terms of both the JUCE 7 End-User License
  11    Agreement and JUCE Privacy Policy.
  12
  13    End User License Agreement: www.juce.com/juce-7-licence
  14    Privacy Policy: www.juce.com/juce-privacy-policy
  15
  16    Or: You may also use this code under the terms of the GPL v3 (see
  17    www.gnu.org/licenses).
  18
  19    JUCE IS PROVIDED "AS IS" WITHOUT ANY WARRANTY, AND ALL WARRANTIES, WHETHER
  20    EXPRESSED OR IMPLIED, INCLUDING MERCHANTABILITY AND FITNESS FOR PURPOSE, ARE
  21    DISCLAIMED.
  22
  23   ==============================================================================
  24 */
  25
  26 namespace juce
  27 {
  28
  29 //==============================================================================
  30 /**
  31     A subclass of this is used to drive a ListBox.
  32
  33     @see ListBox
  34
  35     @tags{GUI}
  36 */
  37 class JUCE_API  ListBoxModel
  38 {
  39 public:
  40     //==============================================================================
  41     /** Destructor. */
  42     virtual ~ListBoxModel() = default;
  43
  44     //==============================================================================
  45     /** This has to return the number of items in the list.
  46         @see ListBox::getNumRows()
  47     */
  48     virtual int getNumRows() = 0;
  49
  50     /** This method must be implemented to draw a row of the list.
  51         Note that the rowNumber value may be greater than the number of rows in your
  52         list, so be careful that you don't assume it's less than getNumRows().
  53     */
  54     virtual void paintListBoxItem (int rowNumber,
  55                                    Graphics& g,
  56                                    int width, int height,
  57                                    bool rowIsSelected) = 0;
  58
  59     /** This is used to create or update a custom component to go in a row of the list.
  60
  61         Any row may contain a custom component, or can just be drawn with the paintListBoxItem() method
  62         and handle mouse clicks with listBoxItemClicked().
  63
  64         This method will be called whenever a custom component might need to be updated - e.g.
  65         when the list is changed, or ListBox::updateContent() is called.
  66
  67         If you don't need a custom component for the specified row, then return nullptr.
  68         (Bear in mind that even if you're not creating a new component, you may still need to
  69         delete existingComponentToUpdate if it's non-null).
  70
  71         If you do want a custom component, and the existingComponentToUpdate is null, then
  72         this method must create a suitable new component and return it.
  73
  74         If the existingComponentToUpdate is non-null, it will be a pointer to a component previously created
  75         by this method. In this case, the method must either update it to make sure it's correctly representing
  76         the given row (which may be different from the one that the component was created for), or it can
  77         delete this component and return a new one.
  78
  79         The component that your method returns will be deleted by the ListBox when it is no longer needed.
  80
  81         Bear in mind that if you put a custom component inside the row but still want the
  82         listbox to automatically handle clicking, selection, etc, then you'll need to make sure
  83         your custom component doesn't intercept all the mouse events that land on it, e.g by
  84         using Component::setInterceptsMouseClicks().
  85     */
  86     virtual Component* refreshComponentForRow (int rowNumber, bool isRowSelected,
  87                                                Component* existingComponentToUpdate);
  88
  89     /** This can be overridden to return a name for the specified row.
  90
  91         By default this will just return a string containing the row number.
  92     */
  93     virtual String getNameForRow (int rowNumber);
  94
  95     /** This can be overridden to react to the user clicking on a row.
  96         @see listBoxItemDoubleClicked
  97     */
  98     virtual void listBoxItemClicked (int row, const MouseEvent&);
  99
 100     /** This can be overridden to react to the user double-clicking on a row.
 101         @see listBoxItemClicked
 102     */
 103     virtual void listBoxItemDoubleClicked (int row, const MouseEvent&);
 104
 105     /** This can be overridden to react to the user clicking on a part of the list where
 106         there are no rows.
 107         @see listBoxItemClicked
 108     */
 109     virtual void backgroundClicked (const MouseEvent&);
 110
 111     /** Override this to be informed when rows are selected or deselected.
 112
 113         This will be called whenever a row is selected or deselected. If a range of
 114         rows is selected all at once, this will just be called once for that event.
 115
 116         @param lastRowSelected      the last row that the user selected. If no
 117                                     rows are currently selected, this may be -1.
 118     */
 119     virtual void selectedRowsChanged (int lastRowSelected);
 120
 121     /** Override this to be informed when the delete key is pressed.
 122
 123         If no rows are selected when they press the key, this won't be called.
 124
 125         @param lastRowSelected   the last row that had been selected when they pressed the
 126                                  key - if there are multiple selections, this might not be
 127                                  very useful
 128     */
 129     virtual void deleteKeyPressed (int lastRowSelected);
 130
 131     /** Override this to be informed when the return key is pressed.
 132
 133         If no rows are selected when they press the key, this won't be called.
 134
 135         @param lastRowSelected   the last row that had been selected when they pressed the
 136                                  key - if there are multiple selections, this might not be
 137                                   very useful
 138     */
 139     virtual void returnKeyPressed (int lastRowSelected);
 140
 141     /** Override this to be informed when the list is scrolled.
 142
 143         This might be caused by the user moving the scrollbar, or by programmatic changes
 144         to the list position.
 145     */
 146     virtual void listWasScrolled();
 147
 148     /** To allow rows from your list to be dragged-and-dropped, implement this method.
 149
 150         If this returns a non-null variant then when the user drags a row, the listbox will
 151         try to find a DragAndDropContainer in its parent hierarchy, and will use it to trigger
 152         a drag-and-drop operation, using this string as the source description, with the listbox
 153         itself as the source component.
 154
 155         @see DragAndDropContainer::startDragging
 156     */
 157     virtual var getDragSourceDescription (const SparseSet<int>& rowsToDescribe);
 158
 159     /** You can override this to provide tool tips for specific rows.
 160         @see TooltipClient
 161     */
 162     virtual String getTooltipForRow (int row);
 163
 164     /** You can override this to return a custom mouse cursor for each row. */
 165     virtual MouseCursor getMouseCursorForRow (int row);
 166
 167 private:
 168    #if ! JUCE_DISABLE_ASSERTIONS
 169     friend class ListBox;
 170     struct Empty {};
 171     std::shared_ptr<Empty> sharedState = std::make_shared<Empty>();
 172    #endif
 173 };
 174
 175 //==============================================================================
 176 /**
 177     A list of items that can be scrolled vertically.
 178
 179     To create a list, you'll need to create a subclass of ListBoxModel. This can
 180     either paint each row of the list and respond to events via callbacks, or for
 181     more specialised tasks, it can supply a custom component to fill each row.
 182
 183     @see ComboBox, TableListBox
 184
 185     @tags{GUI}
 186 */
 187 class JUCE_API  ListBox  : public Component,
 188                            public SettableTooltipClient
 189 {
 190 public:
 191     //==============================================================================
 192     /** Creates a ListBox.
 193
 194         The model pointer passed-in can be null, in which case you can set it later
 195         with setModel().
 196
 197         The ListBoxModel instance must stay alive for as long as the ListBox
 198         holds a pointer to it. Be careful to destroy the ListBox before the
 199         ListBoxModel, or to call ListBox::setModel (nullptr) before destroying
 200         the ListBoxModel.
 201     */
 202     ListBox (const String& componentName = String(),
 203              ListBoxModel* model = nullptr);
 204
 205     /** Destructor. */
 206     ~ListBox() override;
 207
 208     //==============================================================================
 209     /** Changes the current data model to display.
 210
 211         The ListBoxModel instance must stay alive for as long as the ListBox
 212         holds a pointer to it. Be careful to destroy the ListBox before the
 213         ListBoxModel, or to call ListBox::setModel (nullptr) before destroying
 214         the ListBoxModel.
 215     */
 216     void setModel (ListBoxModel* newModel);
 217
 218     /** Returns the current list model. */
 219     ListBoxModel* getModel() const noexcept
 220     {
 221        #if ! JUCE_DISABLE_ASSERTIONS
 222         checkModelPtrIsValid();
 223        #endif
 224
 225         return model;
 226     }
 227
 228     //==============================================================================
 229     /** Causes the list to refresh its content.
 230
 231         Call this when the number of rows in the list changes, or if you want it
 232         to call refreshComponentForRow() on all the row components.
 233
 234         This must only be called from the main message thread.
 235     */
 236     void updateContent();
 237
 238     //==============================================================================
 239     /** Turns on multiple-selection of rows.
 240
 241         By default this is disabled.
 242
 243         When your row component gets clicked you'll need to call the
 244         selectRowsBasedOnModifierKeys() method to tell the list that it's been
 245         clicked and to get it to do the appropriate selection based on whether
 246         the ctrl/shift keys are held down.
 247     */
 248     void setMultipleSelectionEnabled (bool shouldBeEnabled) noexcept;
 249
 250     /** If enabled, this makes the listbox flip the selection status of
 251         each row that the user clicks, without affecting other selected rows.
 252
 253         (This only has an effect if multiple selection is also enabled).
 254         If not enabled, you can still get the same row-flipping behaviour by holding
 255         down CMD or CTRL when clicking.
 256     */
 257     void setClickingTogglesRowSelection (bool flipRowSelection) noexcept;
 258
 259     /** Sets whether a row should be selected when the mouse is pressed or released.
 260         By default this is true, but you may want to turn it off.
 261     */
 262     void setRowSelectedOnMouseDown (bool isSelectedOnMouseDown) noexcept;
 263
 264     /** Makes the list react to mouse moves by selecting the row that the mouse if over.
 265
 266         This function is here primarily for the ComboBox class to use, but might be
 267         useful for some other purpose too.
 268     */
 269     void setMouseMoveSelectsRows (bool shouldSelect);
 270
 271     //==============================================================================
 272     /** Selects a row.
 273
 274         If the row is already selected, this won't do anything.
 275
 276         @param rowNumber                the row to select
 277         @param dontScrollToShowThisRow  if true, the list's position won't change; if false and
 278                                         the selected row is off-screen, it'll scroll to make
 279                                         sure that row is on-screen
 280         @param deselectOthersFirst      if true and there are multiple selections, these will
 281                                         first be deselected before this item is selected
 282         @see isRowSelected, selectRowsBasedOnModifierKeys, flipRowSelection, deselectRow,
 283              deselectAllRows, selectRangeOfRows
 284     */
 285     void selectRow (int rowNumber,
 286                     bool dontScrollToShowThisRow = false,
 287                     bool deselectOthersFirst = true);
 288
 289     /** Selects a set of rows.
 290
 291         This will add these rows to the current selection, so you might need to
 292         clear the current selection first with deselectAllRows()
 293
 294         @param firstRow                       the first row to select (inclusive)
 295         @param lastRow                        the last row to select (inclusive)
 296         @param dontScrollToShowThisRange      if true, the list's position won't change; if false and
 297                                               the selected range is off-screen, it'll scroll to make
 298                                               sure that the range of rows is on-screen
 299     */
 300     void selectRangeOfRows (int firstRow,
 301                             int lastRow,
 302                             bool dontScrollToShowThisRange = false);
 303
 304     /** Deselects a row.
 305         If it's not currently selected, this will do nothing.
 306         @see selectRow, deselectAllRows
 307     */
 308     void deselectRow (int rowNumber);
 309
 310     /** Deselects any currently selected rows.
 311         @see deselectRow
 312     */
 313     void deselectAllRows();
 314
 315     /** Selects or deselects a row.
 316         If the row's currently selected, this deselects it, and vice-versa.
 317     */
 318     void flipRowSelection (int rowNumber);
 319
 320     /** Returns a sparse set indicating the rows that are currently selected.
 321         @see setSelectedRows
 322     */
 323     SparseSet<int> getSelectedRows() const;
 324
 325     /** Sets the rows that should be selected, based on an explicit set of ranges.
 326
 327         If sendNotificationEventToModel is true, the ListBoxModel::selectedRowsChanged()
 328         method will be called. If it's false, no notification will be sent to the model.
 329
 330         @see getSelectedRows
 331     */
 332     void setSelectedRows (const SparseSet<int>& setOfRowsToBeSelected,
 333                           NotificationType sendNotificationEventToModel = sendNotification);
 334
 335     /** Checks whether a row is selected.
 336     */
 337     bool isRowSelected (int rowNumber) const;
 338
 339     /** Returns the number of rows that are currently selected.
 340         @see getSelectedRow, isRowSelected, getLastRowSelected
 341     */
 342     int getNumSelectedRows() const;
 343
 344     /** Returns the row number of a selected row.
 345
 346         This will return the row number of the Nth selected row. The row numbers returned will
 347         be sorted in order from low to high.
 348
 349         @param index    the index of the selected row to return, (from 0 to getNumSelectedRows() - 1)
 350         @returns        the row number, or -1 if the index was out of range or if there aren't any rows
 351                         selected
 352         @see getNumSelectedRows, isRowSelected, getLastRowSelected
 353     */
 354     int getSelectedRow (int index = 0) const;
 355
 356     /** Returns the last row that the user selected.
 357
 358         This isn't the same as the highest row number that is currently selected - if the user
 359         had multiply-selected rows 10, 5 and then 6 in that order, this would return 6.
 360
 361         If nothing is selected, it will return -1.
 362     */
 363     int getLastRowSelected() const;
 364
 365     /** Multiply-selects rows based on the modifier keys.
 366
 367         If no modifier keys are down, this will select the given row and
 368         deselect any others.
 369
 370         If the ctrl (or command on the Mac) key is down, it'll flip the
 371         state of the selected row.
 372
 373         If the shift key is down, it'll select up to the given row from the
 374         last row selected.
 375
 376         @see selectRow
 377     */
 378     void selectRowsBasedOnModifierKeys (int rowThatWasClickedOn,
 379                                         ModifierKeys modifiers,
 380                                         bool isMouseUpEvent);
 381
 382     //==============================================================================
 383     /** Scrolls the list to a particular position.
 384
 385         The proportion is between 0 and 1.0, so 0 scrolls to the top of the list,
 386         1.0 scrolls to the bottom.
 387
 388         If the total number of rows all fit onto the screen at once, then this
 389         method won't do anything.
 390
 391         @see getVerticalPosition
 392     */
 393     void setVerticalPosition (double newProportion);
 394
 395     /** Returns the current vertical position as a proportion of the total.
 396
 397         This can be used in conjunction with setVerticalPosition() to save and restore
 398         the list's position. It returns a value in the range 0 to 1.
 399
 400         @see setVerticalPosition
 401     */
 402     double getVerticalPosition() const;
 403
 404     /** Scrolls if necessary to make sure that a particular row is visible. */
 405     void scrollToEnsureRowIsOnscreen (int row);
 406
 407     /** Returns a reference to the vertical scrollbar. */
 408     ScrollBar& getVerticalScrollBar() const noexcept;
 409
 410     /** Returns a reference to the horizontal scrollbar. */
 411     ScrollBar& getHorizontalScrollBar() const noexcept;
 412
 413     /** Finds the row index that contains a given x,y position.
 414         The position is relative to the ListBox's top-left.
 415         If no row exists at this position, the method will return -1.
 416         @see getComponentForRowNumber
 417     */
 418     int getRowContainingPosition (int x, int y) const noexcept;
 419
 420     /** Finds a row index that would be the most suitable place to insert a new
 421         item for a given position.
 422
 423         This is useful when the user is e.g. dragging and dropping onto the listbox,
 424         because it lets you easily choose the best position to insert the item that
 425         they drop, based on where they drop it.
 426
 427         If the position is out of range, this will return -1. If the position is
 428         beyond the end of the list, it will return getNumRows() to indicate the end
 429         of the list.
 430
 431         @see getComponentForRowNumber
 432     */
 433     int getInsertionIndexForPosition (int x, int y) const noexcept;
 434
 435     /** Returns the position of one of the rows, relative to the top-left of
 436         the listbox.
 437
 438         This may be off-screen, and the range of the row number that is passed-in is
 439         not checked to see if it's a valid row.
 440     */
 441     Rectangle<int> getRowPosition (int rowNumber,
 442                                    bool relativeToComponentTopLeft) const noexcept;
 443
 444     /** Finds the row component for a given row in the list.
 445
 446         The component returned will have been created using ListBoxModel::refreshComponentForRow().
 447
 448         If the component for this row is off-screen or if the row is out-of-range,
 449         this will return nullptr.
 450
 451         @see getRowContainingPosition
 452     */
 453     Component* getComponentForRowNumber (int rowNumber) const noexcept;
 454
 455     /** Returns the row number that the given component represents.
 456         If the component isn't one of the list's rows, this will return -1.
 457     */
 458     int getRowNumberOfComponent (Component* rowComponent) const noexcept;
 459
 460     /** Returns the width of a row (which may be less than the width of this component
 461         if there's a scrollbar).
 462     */
 463     int getVisibleRowWidth() const noexcept;
 464
 465     //==============================================================================
 466     /** Sets the height of each row in the list.
 467         The default height is 22 pixels.
 468         @see getRowHeight
 469     */
 470     void setRowHeight (int newHeight);
 471
 472     /** Returns the height of a row in the list.
 473         @see setRowHeight
 474     */
 475     int getRowHeight() const noexcept                   { return rowHeight; }
 476
 477     /** Returns the number of rows actually visible.
 478
 479         This is the number of whole rows which will fit on-screen, so the value might
 480         be more than the actual number of rows in the list.
 481     */
 482     int getNumRowsOnScreen() const noexcept;
 483
 484     //==============================================================================
 485     /** A set of colour IDs to use to change the colour of various aspects of the label.
 486
 487         These constants can be used either via the Component::setColour(), or LookAndFeel::setColour()
 488         methods.
 489
 490         @see Component::setColour, Component::findColour, LookAndFeel::setColour, LookAndFeel::findColour
 491     */
 492     enum ColourIds
 493     {
 494         backgroundColourId      = 0x1002800, /**< The background colour to fill the list with.
 495                                                   Make this transparent if you don't want the background to be filled. */
 496         outlineColourId         = 0x1002810, /**< An optional colour to use to draw a border around the list.
 497                                                   Make this transparent to not have an outline. */
 498         textColourId            = 0x1002820  /**< The preferred colour to use for drawing text in the listbox. */
 499     };
 500
 501     /** Sets the thickness of a border that will be drawn around the box.
 502
 503         To set the colour of the outline, use @code setColour (ListBox::outlineColourId, colourXYZ); @endcode
 504         @see outlineColourId
 505     */
 506     void setOutlineThickness (int outlineThickness);
 507
 508     /** Returns the thickness of outline that will be drawn around the listbox.
 509         @see setOutlineColour
 510     */
 511     int getOutlineThickness() const noexcept            { return outlineThickness; }
 512
 513     /** Sets a component that the list should use as a header.
 514
 515         This will position the given component at the top of the list, maintaining the
 516         height of the component passed-in, but rescaling it horizontally to match the
 517         width of the items in the listbox.
 518
 519         The component will be deleted when setHeaderComponent() is called with a
 520         different component, or when the listbox is deleted.
 521     */
 522     void setHeaderComponent (std::unique_ptr<Component> newHeaderComponent);
 523
 524     /** Returns whatever header component was set with setHeaderComponent(). */
 525     Component* getHeaderComponent() const noexcept      { return headerComponent.get(); }
 526
 527     /** Changes the width of the rows in the list.
 528
 529         This can be used to make the list's row components wider than the list itself - the
 530         width of the rows will be either the width of the list or this value, whichever is
 531         greater, and if the rows become wider than the list, a horizontal scrollbar will
 532         appear.
 533
 534         The default value for this is 0, which means that the rows will always
 535         be the same width as the list.
 536     */
 537     void setMinimumContentWidth (int newMinimumWidth);
 538
 539     /** Returns the space currently available for the row items, taking into account
 540         borders, scrollbars, etc.
 541     */
 542     int getVisibleContentWidth() const noexcept;
 543
 544     /** Repaints one of the rows.
 545
 546         This does not invoke updateContent(), it just invokes a straightforward repaint
 547         for the area covered by this row.
 548     */
 549     void repaintRow (int rowNumber) noexcept;
 550
 551     /** This fairly obscure method creates an image that shows the row components specified
 552         in rows (for example, these could be the currently selected row components).
 553
 554         It's a handy method for doing drag-and-drop, as it can be passed to the
 555         DragAndDropContainer for use as the drag image.
 556
 557         Note that it will make the row components temporarily invisible, so if you're
 558         using custom components this could affect them if they're sensitive to that
 559         sort of thing.
 560
 561         @see Component::createComponentSnapshot
 562     */
 563     virtual ScaledImage createSnapshotOfRows (const SparseSet<int>& rows, int& x, int& y);
 564
 565     /** Returns the viewport that this ListBox uses.
 566
 567         You may need to use this to change parameters such as whether scrollbars
 568         are shown, etc.
 569     */
 570     Viewport* getViewport() const noexcept;
 571
 572     //==============================================================================
 573     /** @internal */
 574     bool keyPressed (const KeyPress&) override;
 575     /** @internal */
 576     bool keyStateChanged (bool isKeyDown) override;
 577     /** @internal */
 578     void paint (Graphics&) override;
 579     /** @internal */
 580     void paintOverChildren (Graphics&) override;
 581     /** @internal */
 582     void resized() override;
 583     /** @internal */
 584     void visibilityChanged() override;
 585     /** @internal */
 586     void mouseWheelMove (const MouseEvent&, const MouseWheelDetails&) override;
 587     /** @internal */
 588     void mouseUp (const MouseEvent&) override;
 589     /** @internal */
 590     void colourChanged() override;
 591     /** @internal */
 592     void parentHierarchyChanged() override;
 593     /** @internal */
 594     void startDragAndDrop (const MouseEvent&, const SparseSet<int>& rowsToDrag,
 595                            const var& dragDescription, bool allowDraggingToOtherWindows);
 596
 597     //==============================================================================
 598    #ifndef DOXYGEN
 599     [[deprecated ("This method's bool parameter has changed: see the new method signature.")]]
 600     void setSelectedRows (const SparseSet<int>&, bool);
 601    #endif
 602
 603 private:
 604     //==============================================================================
 605     JUCE_PUBLIC_IN_DLL_BUILD (class ListViewport)
 606     JUCE_PUBLIC_IN_DLL_BUILD (class RowComponent)
 607     friend class ListViewport;
 608     friend class TableListBox;
 609     ListBoxModel* model = nullptr;
 610     std::unique_ptr<ListViewport> viewport;
 611     std::unique_ptr<Component> headerComponent;
 612     std::unique_ptr<MouseListener> mouseMoveSelector;
 613     SparseSet<int> selected;
 614     int totalItems = 0, rowHeight = 22, minimumRowWidth = 0;
 615     int outlineThickness = 0;
 616     int lastRowSelected = -1;
 617     bool multipleSelection = false, alwaysFlipSelection = false, hasDoneInitialUpdate = false, selectOnMouseDown = true;
 618
 619    #if ! JUCE_DISABLE_ASSERTIONS
 620     std::weak_ptr<ListBoxModel::Empty> weakModelPtr;
 621    #endif
 622
 623     void assignModelPtr (ListBoxModel*);
 624     void checkModelPtrIsValid() const;
 625     std::unique_ptr<AccessibilityHandler> createAccessibilityHandler() override;
 626     bool hasAccessibleHeaderComponent() const;
 627     void selectRowInternal (int rowNumber, bool dontScrollToShowThisRow,
 628                             bool deselectOthersFirst, bool isMouseClick);
 629
 630     JUCE_DECLARE_NON_COPYABLE_WITH_LEAK_DETECTOR (ListBox)
 631 };
 632
 633 } // namespace juce