juce/source/src/gui/components/controls/juce_Toolbar.h

   1 /*
   2   ==============================================================================
   3
   4    This file is part of the JUCE library - "Jules' Utility Class Extensions"
   5    Copyright 2004-11 by Raw Material Software Ltd.
   6
   7   ------------------------------------------------------------------------------
   8
   9    JUCE can be redistributed and/or modified under the terms of the GNU General
  10    Public License (Version 2), as published by the Free Software Foundation.
  11    A copy of the license is included in the JUCE distribution, or can be found
  12    online at www.gnu.org/licenses.
  13
  14    JUCE is distributed in the hope that it will be useful, but WITHOUT ANY
  15    WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR
  16    A PARTICULAR PURPOSE.  See the GNU General Public License for more details.
  17
  18   ------------------------------------------------------------------------------
  19
  20    To release a closed-source product which uses JUCE, commercial licenses are
  21    available: visit www.rawmaterialsoftware.com/juce for more information.
  22
  23   ==============================================================================
  24 */
  25
  26 #ifndef __JUCE_TOOLBAR_JUCEHEADER__
  27 #define __JUCE_TOOLBAR_JUCEHEADER__
  28
  29 #include "../mouse/juce_DragAndDropContainer.h"
  30 #include "../layout/juce_ComponentAnimator.h"
  31 #include "../buttons/juce_Button.h"
  32 class ToolbarItemComponent;
  33 class ToolbarItemFactory;
  34
  35
  36 //==============================================================================
  37 /**
  38     A toolbar component.
  39
  40     A toolbar contains a horizontal or vertical strip of ToolbarItemComponents,
  41     and looks after their order and layout.
  42
  43     Items (icon buttons or other custom components) are added to a toolbar using a
  44     ToolbarItemFactory - each type of item is given a unique ID number, and a
  45     toolbar might contain more than one instance of a particular item type.
  46
  47     Toolbars can be interactively customised, allowing the user to drag the items
  48     around, and to drag items onto or off the toolbar, using the ToolbarItemPalette
  49     component as a source of new items.
  50
  51     @see ToolbarItemFactory, ToolbarItemComponent, ToolbarItemPalette
  52 */
  53 class JUCE_API  Toolbar   : public Component,
  54                             public DragAndDropContainer,
  55                             public DragAndDropTarget,
  56                             private ButtonListener  // (can't use Button::Listener due to idiotic VC2005 bug)
  57 {
  58 public:
  59     //==============================================================================
  60     /** Creates an empty toolbar component.
  61
  62         To add some icons or other components to your toolbar, you'll need to
  63         create a ToolbarItemFactory class that can create a suitable set of
  64         ToolbarItemComponents.
  65
  66         @see ToolbarItemFactory, ToolbarItemComponents
  67     */
  68     Toolbar();
  69
  70     /** Destructor.
  71
  72         Any items on the bar will be deleted when the toolbar is deleted.
  73     */
  74     ~Toolbar();
  75
  76     //==============================================================================
  77     /** Changes the bar's orientation.
  78         @see isVertical
  79     */
  80     void setVertical (bool shouldBeVertical);
  81
  82     /** Returns true if the bar is set to be vertical, or false if it's horizontal.
  83
  84         You can change the bar's orientation with setVertical().
  85     */
  86     bool isVertical() const noexcept                 { return vertical; }
  87
  88     /** Returns the depth of the bar.
  89
  90         If the bar is horizontal, this will return its height; if it's vertical, it
  91         will return its width.
  92
  93         @see getLength
  94     */
  95     int getThickness() const noexcept;
  96
  97     /** Returns the length of the bar.
  98
  99         If the bar is horizontal, this will return its width; if it's vertical, it
 100         will return its height.
 101
 102         @see getThickness
 103     */
 104     int getLength() const noexcept;
 105
 106     //==============================================================================
 107     /** Deletes all items from the bar.
 108     */
 109     void clear();
 110
 111     /** Adds an item to the toolbar.
 112
 113         The factory's ToolbarItemFactory::createItem() will be called by this method
 114         to create the component that will actually be added to the bar.
 115
 116         The new item will be inserted at the specified index (if the index is -1, it
 117         will be added to the right-hand or bottom end of the bar).
 118
 119         Once added, the component will be automatically deleted by this object when it
 120         is no longer needed.
 121
 122         @see ToolbarItemFactory
 123     */
 124     void addItem (ToolbarItemFactory& factory,
 125                   int itemId,
 126                   int insertIndex = -1);
 127
 128     /** Deletes one of the items from the bar.
 129     */
 130     void removeToolbarItem (int itemIndex);
 131
 132     /** Returns the number of items currently on the toolbar.
 133
 134         @see getItemId, getItemComponent
 135     */
 136     int getNumItems() const noexcept;
 137
 138     /** Returns the ID of the item with the given index.
 139
 140         If the index is less than zero or greater than the number of items,
 141         this will return 0.
 142
 143         @see getNumItems
 144     */
 145     int getItemId (int itemIndex) const noexcept;
 146
 147     /** Returns the component being used for the item with the given index.
 148
 149         If the index is less than zero or greater than the number of items,
 150         this will return 0.
 151
 152         @see getNumItems
 153     */
 154     ToolbarItemComponent* getItemComponent (int itemIndex) const noexcept;
 155
 156     /** Clears this toolbar and adds to it the default set of items that the specified
 157         factory creates.
 158
 159         @see ToolbarItemFactory::getDefaultItemSet
 160     */
 161     void addDefaultItems (ToolbarItemFactory& factoryToUse);
 162
 163     //==============================================================================
 164     /** Options for the way items should be displayed.
 165         @see setStyle, getStyle
 166     */
 167     enum ToolbarItemStyle
 168     {
 169         iconsOnly,       /**< Means that the toolbar should just contain icons. */
 170         iconsWithText,   /**< Means that the toolbar should have text labels under each icon. */
 171         textOnly         /**< Means that the toolbar only display text labels for each item. */
 172     };
 173
 174     /** Returns the toolbar's current style.
 175         @see ToolbarItemStyle, setStyle
 176     */
 177     ToolbarItemStyle getStyle() const noexcept               { return toolbarStyle; }
 178
 179     /** Changes the toolbar's current style.
 180         @see ToolbarItemStyle, getStyle, ToolbarItemComponent::setStyle
 181     */
 182     void setStyle (const ToolbarItemStyle& newStyle);
 183
 184     //==============================================================================
 185     /** Flags used by the showCustomisationDialog() method. */
 186     enum CustomisationFlags
 187     {
 188         allowIconsOnlyChoice            = 1,    /**< If this flag is specified, the customisation dialog can
 189                                                      show the "icons only" option on its choice of toolbar styles. */
 190         allowIconsWithTextChoice        = 2,    /**< If this flag is specified, the customisation dialog can
 191                                                      show the "icons with text" option on its choice of toolbar styles. */
 192         allowTextOnlyChoice             = 4,    /**< If this flag is specified, the customisation dialog can
 193                                                      show the "text only" option on its choice of toolbar styles. */
 194         showResetToDefaultsButton       = 8,    /**< If this flag is specified, the customisation dialog can
 195                                                      show a button to reset the toolbar to its default set of items. */
 196
 197         allCustomisationOptionsEnabled = (allowIconsOnlyChoice | allowIconsWithTextChoice | allowTextOnlyChoice | showResetToDefaultsButton)
 198     };
 199
 200     /** Pops up a modal dialog box that allows this toolbar to be customised by the user.
 201
 202         The dialog contains a ToolbarItemPalette and various controls for editing other
 203         aspects of the toolbar. This method will block and run the dialog box modally,
 204         returning when the user closes it.
 205
 206         The factory is used to determine the set of items that will be shown on the
 207         palette.
 208
 209         The optionFlags parameter is a bitwise-or of values from the CustomisationFlags
 210         enum.
 211
 212         @see ToolbarItemPalette
 213     */
 214     void showCustomisationDialog (ToolbarItemFactory& factory,
 215                                   int optionFlags = allCustomisationOptionsEnabled);
 216
 217     /** Turns on or off the toolbar's editing mode, in which its items can be
 218         rearranged by the user.
 219
 220         (In most cases it's easier just to use showCustomisationDialog() instead of
 221         trying to enable editing directly).
 222
 223         @see ToolbarItemPalette
 224     */
 225     void setEditingActive (bool editingEnabled);
 226
 227     //==============================================================================
 228     /** A set of colour IDs to use to change the colour of various aspects of the toolbar.
 229
 230         These constants can be used either via the Component::setColour(), or LookAndFeel::setColour()
 231         methods.
 232
 233         @see Component::setColour, Component::findColour, LookAndFeel::setColour, LookAndFeel::findColour
 234     */
 235     enum ColourIds
 236     {
 237         backgroundColourId          = 0x1003200,  /**< A colour to use to fill the toolbar's background. For
 238                                                        more control over this, override LookAndFeel::paintToolbarBackground(). */
 239         separatorColourId           = 0x1003210,  /**< A colour to use to draw the separator lines. */
 240
 241         buttonMouseOverBackgroundColourId = 0x1003220,  /**< A colour used to paint the background of buttons when the mouse is
 242                                                              over them. */
 243         buttonMouseDownBackgroundColourId = 0x1003230,  /**< A colour used to paint the background of buttons when the mouse is
 244                                                              held down on them. */
 245
 246         labelTextColourId           = 0x1003240,        /**< A colour to use for drawing the text under buttons
 247                                                              when the style is set to iconsWithText or textOnly. */
 248
 249         editingModeOutlineColourId  = 0x1003250   /**< A colour to use for an outline around buttons when
 250                                                        the customisation dialog is active and the mouse moves over them. */
 251     };
 252
 253     //==============================================================================
 254     /** Returns a string that represents the toolbar's current set of items.
 255
 256         This lets you later restore the same item layout using restoreFromString().
 257
 258         @see restoreFromString
 259     */
 260     String toString() const;
 261
 262     /** Restores a set of items that was previously stored in a string by the toString()
 263         method.
 264
 265         The factory object is used to create any item components that are needed.
 266
 267         @see toString
 268     */
 269     bool restoreFromString (ToolbarItemFactory& factoryToUse,
 270                             const String& savedVersion);
 271
 272     //==============================================================================
 273     /** @internal */
 274     void paint (Graphics& g);
 275     /** @internal */
 276     void resized();
 277     /** @internal */
 278     void buttonClicked (Button*);
 279     /** @internal */
 280     void mouseDown (const MouseEvent&);
 281     /** @internal */
 282     bool isInterestedInDragSource (const SourceDetails&);
 283     /** @internal */
 284     void itemDragMove (const SourceDetails&);
 285     /** @internal */
 286     void itemDragExit (const SourceDetails&);
 287     /** @internal */
 288     void itemDropped (const SourceDetails&);
 289     /** @internal */
 290     void updateAllItemPositions (bool animate);
 291     /** @internal */
 292     static ToolbarItemComponent* createItem (ToolbarItemFactory&, int itemId);
 293
 294 private:
 295     //==============================================================================
 296     ScopedPointer<Button> missingItemsButton;
 297     bool vertical, isEditingActive;
 298     ToolbarItemStyle toolbarStyle;
 299     class MissingItemsComponent;
 300     friend class MissingItemsComponent;
 301     OwnedArray <ToolbarItemComponent> items;
 302
 303     friend class ItemDragAndDropOverlayComponent;
 304     static const char* const toolbarDragDescriptor;
 305
 306     void addItemInternal (ToolbarItemFactory& factory, int itemId, int insertIndex);
 307
 308     ToolbarItemComponent* getNextActiveComponent (int index, int delta) const;
 309
 310     JUCE_DECLARE_NON_COPYABLE_WITH_LEAK_DETECTOR (Toolbar);
 311 };
 312
 313
 314 #endif   // __JUCE_TOOLBAR_JUCEHEADER__