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;
    TreeViewItem* getDeepestOpenParentItem() 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 (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;
 
private:
    friend class TreeViewItem;
 
    class ItemComponent;
    class ContentComponent;
    class TreeViewport;
    class InsertPointHighlight;
    class TargetGroupHighlight;
    class TreeAccessibilityHandler;
    struct InsertPoint;
 
    std::unique_ptr<AccessibilityHandler> createAccessibilityHandler() override;
    void itemsChanged() noexcept;
    void updateVisibleItems();
    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