juce_ListBox.h

Go to the documentation of this file.

 /*
  ==============================================================================
 
   This file is part of the JUCE library.
   Copyright (c) 2022 - Raw Material Software Limited
 
   JUCE is an open source library subject to commercial or open-source
   licensing.
 
   By using JUCE, you agree to the terms of both the JUCE 7 End-User License
   Agreement and JUCE Privacy Policy.
 
   End User License Agreement: www.juce.com/juce-7-licence
   Privacy Policy: www.juce.com/juce-privacy-policy
 
   Or: You may also use this code under the terms of the GPL v3 (see
   www.gnu.org/licenses).
 
   JUCE IS PROVIDED "AS IS" WITHOUT ANY WARRANTY, AND ALL WARRANTIES, WHETHER
   EXPRESSED OR IMPLIED, INCLUDING MERCHANTABILITY AND FITNESS FOR PURPOSE, ARE
   DISCLAIMED.
 
  ==============================================================================
*/
 
namespace juce
{
 
//==============================================================================
class JUCE_API  ListBoxModel
{
public:
    //==============================================================================
    virtual ~ListBoxModel() = default;
 
    //==============================================================================
    virtual int getNumRows() = 0;
 
    virtual void paintListBoxItem (int rowNumber,
                                   Graphics& g,
                                   int width, int height,
                                   bool rowIsSelected) = 0;
 
    virtual Component* refreshComponentForRow (int rowNumber, bool isRowSelected,
                                               Component* existingComponentToUpdate);
 
    virtual String getNameForRow (int rowNumber);
 
    virtual void listBoxItemClicked (int row, const MouseEvent&);
 
    virtual void listBoxItemDoubleClicked (int row, const MouseEvent&);
 
    virtual void backgroundClicked (const MouseEvent&);
 
    virtual void selectedRowsChanged (int lastRowSelected);
 
    virtual void deleteKeyPressed (int lastRowSelected);
 
    virtual void returnKeyPressed (int lastRowSelected);
 
    virtual void listWasScrolled();
 
    virtual var getDragSourceDescription (const SparseSet<int>& rowsToDescribe);
 
    virtual bool mayDragToExternalWindows() const   { return true; }
 
    virtual String getTooltipForRow (int row);
 
    virtual MouseCursor getMouseCursorForRow (int row);
 
private:
   #if ! JUCE_DISABLE_ASSERTIONS
    friend class ListBox;
    struct Empty {};
    std::shared_ptr<Empty> sharedState = std::make_shared<Empty>();
   #endif
};
 
//==============================================================================
class JUCE_API  ListBox  : public Component,
                           public SettableTooltipClient
{
public:
    //==============================================================================
    ListBox (const String& componentName = String(),
             ListBoxModel* model = nullptr);
 
    ~ListBox() override;
 
    //==============================================================================
    void setModel (ListBoxModel* newModel);
 
    ListBoxModel* getListBoxModel() const noexcept
    {
       #if ! JUCE_DISABLE_ASSERTIONS
        checkModelPtrIsValid();
       #endif
 
        return model;
    }
 
    //==============================================================================
    void updateContent();
 
    //==============================================================================
    void setMultipleSelectionEnabled (bool shouldBeEnabled) noexcept;
 
    void setClickingTogglesRowSelection (bool flipRowSelection) noexcept;
 
    void setRowSelectedOnMouseDown (bool isSelectedOnMouseDown) noexcept;
 
    bool getRowSelectedOnMouseDown() const                  { return selectOnMouseDown; }
 
    void setMouseMoveSelectsRows (bool shouldSelect);
 
    //==============================================================================
    void selectRow (int rowNumber,
                    bool dontScrollToShowThisRow = false,
                    bool deselectOthersFirst = true);
 
    void selectRangeOfRows (int firstRow,
                            int lastRow,
                            bool dontScrollToShowThisRange = false);
 
    void deselectRow (int rowNumber);
 
    void deselectAllRows();
 
    void flipRowSelection (int rowNumber);
 
    SparseSet<int> getSelectedRows() const;
 
    void setSelectedRows (const SparseSet<int>& setOfRowsToBeSelected,
                          NotificationType sendNotificationEventToModel = sendNotification);
 
    bool isRowSelected (int rowNumber) const;
 
    int getNumSelectedRows() const;
 
    int getSelectedRow (int index = 0) const;
 
    int getLastRowSelected() const;
 
    void selectRowsBasedOnModifierKeys (int rowThatWasClickedOn,
                                        ModifierKeys modifiers,
                                        bool isMouseUpEvent);
 
    //==============================================================================
    void setVerticalPosition (double newProportion);
 
    double getVerticalPosition() const;
 
    void scrollToEnsureRowIsOnscreen (int row);
 
    ScrollBar& getVerticalScrollBar() const noexcept;
 
    ScrollBar& getHorizontalScrollBar() const noexcept;
 
    int getRowContainingPosition (int x, int y) const noexcept;
 
    int getInsertionIndexForPosition (int x, int y) const noexcept;
 
    Rectangle<int> getRowPosition (int rowNumber,
                                   bool relativeToComponentTopLeft) const noexcept;
 
    Component* getComponentForRowNumber (int rowNumber) const noexcept;
 
    int getRowNumberOfComponent (const Component* rowComponent) const noexcept;
 
    int getVisibleRowWidth() const noexcept;
 
    //==============================================================================
    void setRowHeight (int newHeight);
 
    int getRowHeight() const noexcept                   { return rowHeight; }
 
    int getNumRowsOnScreen() const noexcept;
 
    //==============================================================================
    enum ColourIds
    {
        backgroundColourId      = 0x1002800, 
        outlineColourId         = 0x1002810, 
        textColourId            = 0x1002820  
    };
 
    void setOutlineThickness (int outlineThickness);
 
    int getOutlineThickness() const noexcept            { return outlineThickness; }
 
    void setHeaderComponent (std::unique_ptr<Component> newHeaderComponent);
 
    Component* getHeaderComponent() const noexcept      { return headerComponent.get(); }
 
    void setMinimumContentWidth (int newMinimumWidth);
 
    int getVisibleContentWidth() const noexcept;
 
    void repaintRow (int rowNumber) noexcept;
 
    virtual ScaledImage createSnapshotOfRows (const SparseSet<int>& rows, int& x, int& y);
 
    Viewport* getViewport() const noexcept;
 
    //==============================================================================
    bool keyPressed (const KeyPress&) override;
    bool keyStateChanged (bool isKeyDown) override;
    void paint (Graphics&) override;
    void paintOverChildren (Graphics&) override;
    void resized() override;
    void visibilityChanged() override;
    void mouseWheelMove (const MouseEvent&, const MouseWheelDetails&) override;
    void mouseUp (const MouseEvent&) override;
    void colourChanged() override;
    void parentHierarchyChanged() override;
    void startDragAndDrop (const MouseEvent&, const SparseSet<int>& rowsToDrag,
                           const var& dragDescription, bool allowDraggingToOtherWindows);
    std::unique_ptr<AccessibilityHandler> createAccessibilityHandler() override;
 
    //==============================================================================
   #ifndef DOXYGEN
    [[deprecated ("This method's bool parameter has changed: see the new method signature.")]]
    void setSelectedRows (const SparseSet<int>&, bool);
   #endif
 
    [[deprecated ("The name of this function is ambiguous if derived classes supply their own models, use getListBoxModel instead")]]
    ListBoxModel* getModel() const noexcept  { return getListBoxModel(); }
 
private:
    //==============================================================================
    JUCE_PUBLIC_IN_DLL_BUILD (class ListViewport)
    JUCE_PUBLIC_IN_DLL_BUILD (class RowComponent)
    friend class ListViewport;
    friend class TableListBox;
    ListBoxModel* model = nullptr;
    std::unique_ptr<ListViewport> viewport;
    std::unique_ptr<Component> headerComponent;
    std::unique_ptr<MouseListener> mouseMoveSelector;
    SparseSet<int> selected;
    int totalItems = 0, rowHeight = 22, minimumRowWidth = 0;
    int outlineThickness = 0;
    int lastRowSelected = -1;
    bool multipleSelection = false, alwaysFlipSelection = false, hasDoneInitialUpdate = false, selectOnMouseDown = true;
 
   #if ! JUCE_DISABLE_ASSERTIONS
    std::weak_ptr<ListBoxModel::Empty> weakModelPtr;
   #endif
 
    void assignModelPtr (ListBoxModel*);
    void checkModelPtrIsValid() const;
    bool hasAccessibleHeaderComponent() const;
    void selectRowInternal (int rowNumber, bool dontScrollToShowThisRow,
                            bool deselectOthersFirst, bool isMouseClick);
 
    JUCE_DECLARE_NON_COPYABLE_WITH_LEAK_DETECTOR (ListBox)
};
 
} // namespace juce