juce_TreeView.h

Go to the documentation of this file.

/*
  ==============================================================================
 
   This file is part of the JUCE library.
   Copyright (c) 2015 - ROLI Ltd.
 
   Permission is granted to use this software under the terms of either:
   a) the GPL v2 (or any later version)
   b) the Affero GPL v3
 
   Details of these licenses can be found at: www.gnu.org/licenses
 
   JUCE is distributed in the hope that it will be useful, but WITHOUT ANY
   WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR
   A PARTICULAR PURPOSE.  See the GNU General Public License for more details.
 
   ------------------------------------------------------------------------------
 
   To release a closed-source product which uses JUCE, commercial licenses are
   available: visit www.juce.com for more information.
 
  ==============================================================================
*/
 
#ifndef JUCE_TREEVIEW_H_INCLUDED
#define JUCE_TREEVIEW_H_INCLUDED
 
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);
 
    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 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 void itemClicked (const MouseEvent& e);
 
    virtual void itemDoubleClicked (const MouseEvent& e);
 
    virtual void itemSelectionChanged (bool isNowSelected);
 
    virtual String getTooltip();
 
    //==============================================================================
    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;
 
    //==============================================================================
    XmlElement* getOpennessState() const;
 
    void restoreOpennessState (const XmlElement& xml);
 
    //==============================================================================
    int getIndexInParent() const noexcept;
 
    bool isLastOfSiblings() const noexcept;
 
    String getItemIdentifierString() const;
 
    //==============================================================================
    class OpennessRestorer
    {
    public:
        OpennessRestorer (TreeViewItem& treeViewItem);
        ~OpennessRestorer();
 
    private:
        TreeViewItem& treeViewItem;
        ScopedPointer <XmlElement> oldOpenness;
 
        JUCE_DECLARE_NON_COPYABLE_WITH_LEAK_DETECTOR (OpennessRestorer)
    };
 
private:
    //==============================================================================
    TreeView* ownerView;
    TreeViewItem* parentItem;
    OwnedArray<TreeViewItem> subItems;
    int y, itemHeight, totalHeight, itemWidth, totalWidth;
    int uid;
    bool selected           : 1;
    bool redrawNeeded       : 1;
    bool drawLinesInside    : 1;
    bool drawLinesSet       : 1;
    bool drawsInLeftMargin  : 1;
    bool drawsInRightMargin : 1;
    unsigned int openness   : 2;
 
    friend class TreeView;
 
    void updatePositions (int newY);
    int getIndentX() const noexcept;
    void setOwnerView (TreeView*) noexcept;
    void paintRecursively (Graphics&, int width);
    TreeViewItem* getTopLevelItem() noexcept;
    TreeViewItem* findItemRecursively (int y) noexcept;
    TreeViewItem* getDeepestOpenParentItem() noexcept;
    int getNumRows() const noexcept;
    TreeViewItem* getItemOnRow (int index) noexcept;
    void deselectAllRecursively (TreeViewItem* itemToIgnore);
    int countSelectedItemsRecursively (int depth) const noexcept;
    TreeViewItem* getSelectedItemWithIndex (int index) noexcept;
    TreeViewItem* getNextVisibleItem (bool recurse) const noexcept;
    TreeViewItem* findItemFromIdentifierString (const String&);
    void restoreToDefaultOpenness();
    bool isFullyOpen() const noexcept;
    XmlElement* getOpennessState (bool canReturnNull) const;
    bool removeSubItemFromList (int index, bool deleteItem);
    void removeAllSubItemsFromList();
    bool areLinesDrawn() const;
 
   #if JUCE_CATCH_DEPRECATED_CODE_MISUSE
    // The parameters for these methods have changed - please update your code!
    virtual void isInterestedInDragSource (const String&, Component*) {}
    virtual int itemDropped (const String&, Component*, int) { return 0; }
   #endif
 
    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 = String::empty);
 
    ~TreeView();
 
    //==============================================================================
    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;
 
    //==============================================================================
    XmlElement* getOpennessState (bool alsoIncludeScrollPosition) const;
 
    void restoreOpennessState (const XmlElement& newState,
                               bool restoreStoredSelection);
 
    //==============================================================================
    enum ColourIds
    {
        backgroundColourId             = 0x1000500, 
        linesColourId                  = 0x1000501, 
        dragAndDropIndicatorColourId   = 0x1000502, 
        selectedItemBackgroundColourId = 0x1000503  
    };
 
    //==============================================================================
    struct JUCE_API  LookAndFeelMethods
    {
        virtual ~LookAndFeelMethods() {}
 
        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& files) override;
    void fileDragEnter (const StringArray& files, int x, int y) override;
    void fileDragMove (const StringArray& files, int x, int y) override;
    void fileDragExit (const StringArray& files) override;
    void filesDropped (const StringArray& files, int x, int y) 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:
    class ContentComponent;
    class TreeViewport;
    class InsertPointHighlight;
    class TargetGroupHighlight;
    friend class TreeViewItem;
    friend class ContentComponent;
    friend struct ContainerDeletePolicy<TreeViewport>;
    friend struct ContainerDeletePolicy<InsertPointHighlight>;
    friend struct ContainerDeletePolicy<TargetGroupHighlight>;
 
    ScopedPointer<TreeViewport> viewport;
    CriticalSection nodeAlterationLock;
    TreeViewItem* rootItem;
    ScopedPointer<InsertPointHighlight> dragInsertPointHighlight;
    ScopedPointer<TargetGroupHighlight> dragTargetGroupHighlight;
    int indentSize;
    bool defaultOpenness, needsRecalculating, rootItemVisible;
    bool multiSelectEnabled, openCloseButtonsVisible;
 
    void itemsChanged() noexcept;
    void recalculateIfNeeded();
    void updateButtonUnderMouse (const MouseEvent&);
    struct InsertPoint;
    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 numPages);
 
   #if JUCE_CATCH_DEPRECATED_CODE_MISUSE
    // this method has been deprecated - see the new version..
    virtual int paintOpenCloseButton (Graphics&, int, int, bool) { return 0; }
   #endif
 
    JUCE_DECLARE_NON_COPYABLE_WITH_LEAK_DETECTOR (TreeView)
};
 
#endif   // JUCE_TREEVIEW_H_INCLUDED