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 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* getModel() 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;

    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 (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);
 
    //==============================================================================
   #ifndef DOXYGEN
    [[deprecated ("This method's bool parameter has changed: see the new method signature.")]]
    void setSelectedRows (const SparseSet<int>&, bool);
   #endif
 
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;
    std::unique_ptr<AccessibilityHandler> createAccessibilityHandler() override;
    bool hasAccessibleHeaderComponent() const;
    void selectRowInternal (int rowNumber, bool dontScrollToShowThisRow,
                            bool deselectOthersFirst, bool isMouseClick);
 
    JUCE_DECLARE_NON_COPYABLE_WITH_LEAK_DETECTOR (ListBox)
};
 
} // namespace juce