source/modules/juce_gui_basics/widgets/juce_ToolbarItemComponent.h

   1 /*
   2   ==============================================================================
   3
   4    This file is part of the JUCE library.
   5    Copyright (c) 2022 - Raw Material Software Limited
   6
   7    JUCE is an open source library subject to commercial or open-source
   8    licensing.
   9
  10    By using JUCE, you agree to the terms of both the JUCE 7 End-User License
  11    Agreement and JUCE Privacy Policy.
  12
  13    End User License Agreement: www.juce.com/juce-7-licence
  14    Privacy Policy: www.juce.com/juce-privacy-policy
  15
  16    Or: You may also use this code under the terms of the GPL v3 (see
  17    www.gnu.org/licenses).
  18
  19    JUCE IS PROVIDED "AS IS" WITHOUT ANY WARRANTY, AND ALL WARRANTIES, WHETHER
  20    EXPRESSED OR IMPLIED, INCLUDING MERCHANTABILITY AND FITNESS FOR PURPOSE, ARE
  21    DISCLAIMED.
  22
  23   ==============================================================================
  24 */
  25
  26 namespace juce
  27 {
  28
  29 //==============================================================================
  30 /**
  31     A component that can be used as one of the items in a Toolbar.
  32
  33     Each of the items on a toolbar must be a component derived from ToolbarItemComponent,
  34     and these objects are always created by a ToolbarItemFactory - see the ToolbarItemFactory
  35     class for further info about creating them.
  36
  37     The ToolbarItemComponent class is actually a button, but can be used to hold non-button
  38     components too. To do this, set the value of isBeingUsedAsAButton to false when
  39     calling the constructor, and override contentAreaChanged(), in which you can position
  40     any sub-components you need to add.
  41
  42     To add basic buttons without writing a special subclass, have a look at the
  43     ToolbarButton class.
  44
  45     @see ToolbarButton, Toolbar, ToolbarItemFactory
  46
  47     @tags{GUI}
  48 */
  49 class JUCE_API  ToolbarItemComponent  : public Button
  50 {
  51 public:
  52     //==============================================================================
  53     /** Constructor.
  54
  55         @param itemId       the ID of the type of toolbar item which this represents
  56         @param labelText    the text to display if the toolbar's style is set to
  57                             Toolbar::iconsWithText or Toolbar::textOnly
  58         @param isBeingUsedAsAButton     set this to false if you don't want the button
  59                             to draw itself with button over/down states when the mouse
  60                             moves over it or clicks
  61     */
  62     ToolbarItemComponent (int itemId,
  63                           const String& labelText,
  64                           bool isBeingUsedAsAButton);
  65
  66     /** Destructor. */
  67     ~ToolbarItemComponent() override;
  68
  69     //==============================================================================
  70     /** Returns the item type ID that this component represents.
  71         This value is in the constructor.
  72     */
  73     int getItemId() const noexcept                                  { return itemId; }
  74
  75     /** Returns the toolbar that contains this component, or nullptr if it's not currently
  76         inside one.
  77     */
  78     Toolbar* getToolbar() const;
  79
  80     /** Returns true if this component is currently inside a toolbar which is vertical.
  81         @see Toolbar::isVertical
  82     */
  83     bool isToolbarVertical() const;
  84
  85     /** Returns the current style setting of this item.
  86
  87         Styles are listed in the Toolbar::ToolbarItemStyle enum.
  88         @see setStyle, Toolbar::getStyle
  89     */
  90     Toolbar::ToolbarItemStyle getStyle() const noexcept             { return toolbarStyle; }
  91
  92     /** Changes the current style setting of this item.
  93
  94         Styles are listed in the Toolbar::ToolbarItemStyle enum, and are automatically updated
  95         by the toolbar that holds this item.
  96
  97         @see setStyle, Toolbar::setStyle
  98     */
  99     virtual void setStyle (const Toolbar::ToolbarItemStyle& newStyle);
 100
 101     /** Returns the area of the component that should be used to display the button image or
 102         other contents of the item.
 103
 104         This content area may change when the item's style changes, and may leave a space around the
 105         edge of the component where the text label can be shown.
 106
 107         @see contentAreaChanged
 108     */
 109     Rectangle<int> getContentArea() const noexcept                  { return contentArea; }
 110
 111     //==============================================================================
 112     /** This method must return the size criteria for this item, based on a given toolbar
 113         size and orientation.
 114
 115         The preferredSize, minSize and maxSize values must all be set by your implementation
 116         method. If the toolbar is horizontal, these will be the width of the item; for a vertical
 117         toolbar, they refer to the item's height.
 118
 119         The preferredSize is the size that the component would like to be, and this must be
 120         between the min and max sizes. For a fixed-size item, simply set all three variables to
 121         the same value.
 122
 123         The toolbarThickness parameter tells you the depth of the toolbar - the same as calling
 124         Toolbar::getThickness().
 125
 126         The isToolbarVertical parameter tells you whether the bar is oriented horizontally or
 127         vertically.
 128     */
 129     virtual bool getToolbarItemSizes (int toolbarThickness,
 130                                       bool isToolbarVertical,
 131                                       int& preferredSize,
 132                                       int& minSize,
 133                                       int& maxSize) = 0;
 134
 135     /** Your subclass should use this method to draw its content area.
 136
 137         The graphics object that is passed-in will have been clipped and had its origin
 138         moved to fit the content area as specified get getContentArea(). The width and height
 139         parameters are the width and height of the content area.
 140
 141         If the component you're writing isn't a button, you can just do nothing in this method.
 142     */
 143     virtual void paintButtonArea (Graphics& g,
 144                                   int width, int height,
 145                                   bool isMouseOver, bool isMouseDown) = 0;
 146
 147     /** Callback to indicate that the content area of this item has changed.
 148
 149         This might be because the component was resized, or because the style changed and
 150         the space needed for the text label is different.
 151
 152         See getContentArea() for a description of what the area is.
 153     */
 154     virtual void contentAreaChanged (const Rectangle<int>& newBounds) = 0;
 155
 156
 157     //==============================================================================
 158     /** Editing modes.
 159         These are used by setEditingMode(), but will be rarely needed in user code.
 160     */
 161     enum ToolbarEditingMode
 162     {
 163         normalMode = 0,     /**< Means that the component is active, inside a toolbar. */
 164         editableOnToolbar,  /**< Means that the component is on a toolbar, but the toolbar is in
 165                                  customisation mode, and the items can be dragged around. */
 166         editableOnPalette   /**< Means that the component is on an new-item palette, so it can be
 167                                  dragged onto a toolbar to add it to that bar.*/
 168     };
 169
 170     /** Changes the editing mode of this component.
 171
 172         This is used by the ToolbarItemPalette and related classes for making the items draggable,
 173         and is unlikely to be of much use in end-user-code.
 174     */
 175     void setEditingMode (const ToolbarEditingMode newMode);
 176
 177     /** Returns the current editing mode of this component.
 178
 179         This is used by the ToolbarItemPalette and related classes for making the items draggable,
 180         and is unlikely to be of much use in end-user-code.
 181     */
 182     ToolbarEditingMode getEditingMode() const noexcept                  { return mode; }
 183
 184
 185     //==============================================================================
 186     /** @internal */
 187     void paintButton (Graphics&, bool isMouseOver, bool isMouseDown) override;
 188     /** @internal */
 189     void resized() override;
 190
 191 private:
 192     friend class Toolbar;
 193     class ItemDragAndDropOverlayComponent;
 194     friend class ItemDragAndDropOverlayComponent;
 195
 196     std::unique_ptr<AccessibilityHandler> createAccessibilityHandler() override;
 197
 198     const int itemId;
 199     ToolbarEditingMode mode;
 200     Toolbar::ToolbarItemStyle toolbarStyle;
 201     std::unique_ptr<Component> overlayComp;
 202     int dragOffsetX, dragOffsetY;
 203     bool isActive, isBeingDragged, isBeingUsedAsAButton;
 204     Rectangle<int> contentArea;
 205
 206     JUCE_DECLARE_NON_COPYABLE_WITH_LEAK_DETECTOR (ToolbarItemComponent)
 207 };
 208
 209 } // namespace juce