juce_TreeView.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 TreeView;
 
//==============================================================================
class JUCE_API  TreeViewItem
{
public:
    //==============================================================================
    TreeViewItem();
 
    virtual ~TreeViewItem();
 
    //==============================================================================
    int getNumSubItems() const noexcept;
 
    TreeViewItem* getSubItem (int index) const noexcept;
 
    void clearSubItems();
 
    void addSubItem (TreeViewItem* newItem, int insertPosition = -1);
 
    template <class ElementComparator>
    void addSubItemSorted (ElementComparator& comparator, TreeViewItem* newItem)
    {
        addSubItem (newItem, findInsertIndexInSortedArray (comparator, subItems.begin(), newItem, 0, subItems.size()));
    }
 
    void removeSubItem (int index, bool deleteItem = true);
 
    template <class ElementComparator>
    void sortSubItems (ElementComparator& comparator)
    {
        subItems.sort (comparator);
    }
 
    //==============================================================================
    TreeView* getOwnerView() const noexcept             { return ownerView; }
 
    TreeViewItem* getParentItem() const noexcept        { return parentItem; }
 
    //==============================================================================
    bool isOpen() const noexcept;
 
    void setOpen (bool shouldBeOpen);
 
    enum class Openness
    {
        opennessDefault,
        opennessClosed,
        opennessOpen
    };
 
    Openness getOpenness() const noexcept;
 
    void setOpenness (Openness newOpenness);
 
    bool isSelected() const noexcept;
 
    void setSelected (bool shouldBeSelected,
                      bool deselectOtherItemsFirst,
                      NotificationType shouldNotify = sendNotification);
 
    Rectangle<int> getItemPosition (bool relativeToTreeViewTopLeft) const noexcept;
 
    void treeHasChanged() const noexcept;
 
    void repaintItem() const;
 
    int getRowNumberInTree() const noexcept;
 
    bool areAllParentsOpen() const noexcept;
 
    void setLinesDrawnForSubItems (bool shouldDrawLines) noexcept;
 
    //==============================================================================
    virtual bool mightContainSubItems() = 0;
 
    virtual String getUniqueName() const;
 
    virtual void itemOpennessChanged (bool isNowOpen);
 
    virtual int getItemWidth() const                          { return -1; }
 
    virtual int getItemHeight() const                         { return 20; }
 
    virtual bool canBeSelected() const                        { return true; }
 
    virtual std::unique_ptr<Component> createItemComponent()  { return nullptr; }
 
    //==============================================================================
    virtual void paintItem (Graphics& g, int width, int height);
 
    virtual void paintOpenCloseButton (Graphics&, const Rectangle<float>& area,
                                       Colour backgroundColour, bool isMouseOver);
 
    virtual void paintHorizontalConnectingLine (Graphics&, const Line<float>& line);
 
    virtual void paintVerticalConnectingLine (Graphics&, const Line<float>& line);
 
    virtual bool customComponentUsesTreeViewMouseHandler() const     { return false; }
 
    virtual void itemClicked (const MouseEvent&);
 
    virtual void itemDoubleClicked (const MouseEvent&);
 
    virtual void itemSelectionChanged (bool isNowSelected);
 
    virtual void ownerViewChanged (TreeView* newOwner);
 
    virtual String getTooltip();
 
    virtual String getAccessibilityName();
 
    //==============================================================================
    virtual var getDragSourceDescription();
 
    virtual bool isInterestedInFileDrag (const StringArray& files);
 
    virtual void filesDropped (const StringArray& files, int insertIndex);
 
    virtual bool isInterestedInDragSource (const DragAndDropTarget::SourceDetails& dragSourceDetails);
 
    virtual void itemDropped (const DragAndDropTarget::SourceDetails& dragSourceDetails, int insertIndex);
 
    //==============================================================================
    void setDrawsInLeftMargin (bool canDrawInLeftMargin) noexcept;
 
    void setDrawsInRightMargin (bool canDrawInRightMargin) noexcept;
 
    //==============================================================================
    std::unique_ptr<XmlElement> getOpennessState() const;
 
    void restoreOpennessState (const XmlElement& xml);
 
    //==============================================================================
    int getIndexInParent() const noexcept;
 
    bool isLastOfSiblings() const noexcept;
 
    String getItemIdentifierString() const;
 
    //==============================================================================
    class JUCE_API  OpennessRestorer
    {
    public:
        OpennessRestorer (TreeViewItem&);
        ~OpennessRestorer();
 
    private:
        TreeViewItem& treeViewItem;
        std::unique_ptr<XmlElement> oldOpenness;
 
        JUCE_DECLARE_NON_COPYABLE_WITH_LEAK_DETECTOR (OpennessRestorer)
    };
 
private:
    //==============================================================================
    friend class TreeView;
 
    void updatePositions (int);
    int getIndentX() const noexcept;
    void setOwnerView (TreeView*) noexcept;
    TreeViewItem* getTopLevelItem() noexcept;
    const TreeViewItem* getDeepestOpenParentItem() const noexcept;
    int getNumRows() const noexcept;
    TreeViewItem* getItemOnRow (int) noexcept;
    void deselectAllRecursively (TreeViewItem*);
    int countSelectedItemsRecursively (int) const noexcept;
    TreeViewItem* getSelectedItemWithIndex (int) noexcept;
    TreeViewItem* findItemFromIdentifierString (const String&);
    void restoreToDefaultOpenness();
    bool isFullyOpen() const noexcept;
    std::unique_ptr<XmlElement> getOpennessState (bool) const;
    bool removeSubItemFromList (int, bool);
    void removeAllSubItemsFromList();
    bool areLinesDrawn() const;
    void draw (Graphics&, int, bool);
 
    //==============================================================================
    TreeView* ownerView = nullptr;
    TreeViewItem* parentItem = nullptr;
    OwnedArray<TreeViewItem> subItems;
 
    Openness openness = Openness::opennessDefault;
    int y = 0, itemHeight = 0, totalHeight = 0, itemWidth = 0, totalWidth = 0, uid = 0;
    bool selected = false, redrawNeeded = true, drawLinesInside = false, drawLinesSet = false,
         drawsInLeftMargin = false, drawsInRightMargin = false;
 
    //==============================================================================
    JUCE_DECLARE_NON_COPYABLE_WITH_LEAK_DETECTOR (TreeViewItem)
};
 
//==============================================================================
class JUCE_API  TreeView  : public Component,
                            public SettableTooltipClient,
                            public FileDragAndDropTarget,
                            public DragAndDropTarget
{
public:
    //==============================================================================
    TreeView (const String& componentName = {});
 
    ~TreeView() override;
 
    //==============================================================================
    void setRootItem (TreeViewItem* newRootItem);
 
    TreeViewItem* getRootItem() const noexcept        { return rootItem; }
 
    void deleteRootItem();
 
    void setRootItemVisible (bool shouldBeVisible);
 
    bool isRootItemVisible() const noexcept           { return rootItemVisible; }
 
    void setDefaultOpenness (bool isOpenByDefault);
 
    bool areItemsOpenByDefault() const noexcept       { return defaultOpenness; }
 
    void setMultiSelectEnabled (bool canMultiSelect);
 
    bool isMultiSelectEnabled() const noexcept        { return multiSelectEnabled; }
 
    void setOpenCloseButtonsVisible (bool shouldBeVisible);
 
    bool areOpenCloseButtonsVisible() const noexcept  { return openCloseButtonsVisible; }
 
    //==============================================================================
    void clearSelectedItems();
 
    int getNumSelectedItems (int maximumDepthToSearchTo = -1) const noexcept;
 
    TreeViewItem* getSelectedItem (int index) const noexcept;
 
    void moveSelectedRow (int deltaRows);
 
    //==============================================================================
    int getNumRowsInTree() const;
 
    TreeViewItem* getItemOnRow (int index) const;
 
    TreeViewItem* getItemAt (int yPosition) const noexcept;
 
    void scrollToKeepItemVisible (const TreeViewItem* item);
 
    Viewport* getViewport() const noexcept;
 
    int getIndentSize() noexcept;
 
    void setIndentSize (int newIndentSize);
 
    TreeViewItem* findItemFromIdentifierString (const String& identifierString) const;
 
    Component* getItemComponent (const TreeViewItem* item) const;
 
    //==============================================================================
    std::unique_ptr<XmlElement> getOpennessState (bool alsoIncludeScrollPosition) const;
 
    void restoreOpennessState (const XmlElement& newState, bool restoreStoredSelection);
 
    //==============================================================================
    enum ColourIds
    {
        backgroundColourId             = 0x1000500, 
        linesColourId                  = 0x1000501, 
        dragAndDropIndicatorColourId   = 0x1000502, 
        selectedItemBackgroundColourId = 0x1000503, 
        oddItemsColourId               = 0x1000504, 
        evenItemsColourId              = 0x1000505  
    };
 
    //==============================================================================
    struct JUCE_API  LookAndFeelMethods
    {
        virtual ~LookAndFeelMethods() = default;
 
        virtual void drawTreeviewPlusMinusBox (Graphics&, const Rectangle<float>& area,
                                               Colour backgroundColour, bool isItemOpen, bool isMouseOver) = 0;
 
        virtual bool areLinesDrawnForTreeView (TreeView&) = 0;
        virtual int getTreeViewIndentSize (TreeView&) = 0;
    };
 
    //==============================================================================
    void paint (Graphics&) override;
    void resized() override;
    bool keyPressed (const KeyPress&) override;
    void colourChanged() override;
    void enablementChanged() override;
    bool isInterestedInFileDrag (const StringArray&) override;
    void fileDragEnter (const StringArray&, int, int) override;
    void fileDragMove (const StringArray&, int, int) override;
    void fileDragExit (const StringArray&) override;
    void filesDropped (const StringArray&, int, int) override;
    bool isInterestedInDragSource (const SourceDetails&) override;
    void itemDragEnter (const SourceDetails&) override;
    void itemDragMove (const SourceDetails&) override;
    void itemDragExit (const SourceDetails&) override;
    void itemDropped (const SourceDetails&) override;
    std::unique_ptr<AccessibilityHandler> createAccessibilityHandler() override;
 
private:
    friend class TreeViewItem;
 
    class ItemComponent;
    class ContentComponent;
    class TreeViewport;
    class InsertPointHighlight;
    class TargetGroupHighlight;
    class TreeAccessibilityHandler;
    struct InsertPoint;
 
    void itemsChanged() noexcept;
    void updateVisibleItems (std::optional<Point<int>> viewportPosition = {});
    void updateButtonUnderMouse (const MouseEvent&);
    void showDragHighlight (const InsertPoint&) noexcept;
    void hideDragHighlight() noexcept;
    void handleDrag (const StringArray&, const SourceDetails&);
    void handleDrop (const StringArray&, const SourceDetails&);
    bool toggleOpenSelectedItem();
    void moveOutOfSelectedItem();
    void moveIntoSelectedItem();
    void moveByPages (int);
 
    std::unique_ptr<TreeViewport> viewport;
    TreeViewItem* rootItem = nullptr;
    std::unique_ptr<InsertPointHighlight> dragInsertPointHighlight;
    std::unique_ptr<TargetGroupHighlight> dragTargetGroupHighlight;
    int indentSize = -1;
    bool defaultOpenness = false, rootItemVisible = true, multiSelectEnabled = false, openCloseButtonsVisible = true;
 
    JUCE_DECLARE_NON_COPYABLE_WITH_LEAK_DETECTOR (TreeView)
};
 
} // namespace juce