juce/source/src/gui/components/controls/juce_ToolbarItemFactory.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_TOOLBARITEMFACTORY_JUCEHEADER__
  27 #define __JUCE_TOOLBARITEMFACTORY_JUCEHEADER__
  28
  29 #include "juce_ToolbarItemComponent.h"
  30
  31
  32 //==============================================================================
  33 /**
  34     A factory object which can create ToolbarItemComponent objects.
  35
  36     A subclass of ToolbarItemFactory publishes a set of types of toolbar item
  37     that it can create.
  38
  39     Each type of item is identified by a unique ID, and multiple instances of an
  40     item type can exist at once (even on the same toolbar, e.g. spacers or separator
  41     bars).
  42
  43     @see Toolbar, ToolbarItemComponent, ToolbarButton
  44 */
  45 class JUCE_API  ToolbarItemFactory
  46 {
  47 public:
  48     //==============================================================================
  49     ToolbarItemFactory();
  50
  51     /** Destructor. */
  52     virtual ~ToolbarItemFactory();
  53
  54     //==============================================================================
  55     /** A set of reserved item ID values, used for the built-in item types.
  56     */
  57     enum SpecialItemIds
  58     {
  59         separatorBarId      = -1,   /**< The item ID for a vertical (or horizontal) separator bar that
  60                                          can be placed between sets of items to break them into groups. */
  61         spacerId            = -2,   /**< The item ID for a fixed-width space that can be placed between
  62                                          items.*/
  63         flexibleSpacerId    = -3    /**< The item ID for a gap that pushes outwards against the things on
  64                                          either side of it, filling any available space. */
  65     };
  66
  67     //==============================================================================
  68     /** Must return a list of the IDs for all the item types that this factory can create.
  69
  70         The ids should be added to the array that is passed-in.
  71
  72         An item ID can be any integer you choose, except for 0, which is considered a null ID,
  73         and the predefined IDs in the SpecialItemIds enum.
  74
  75         You should also add the built-in types (separatorBarId, spacerId and flexibleSpacerId)
  76         to this list if you want your toolbar to be able to contain those items.
  77
  78         The list returned here is used by the ToolbarItemPalette class to obtain its list
  79         of available items, and their order on the palette will reflect the order in which
  80         they appear on this list.
  81
  82         @see ToolbarItemPalette
  83     */
  84     virtual void getAllToolbarItemIds (Array <int>& ids) = 0;
  85
  86     /** Must return the set of items that should be added to a toolbar as its default set.
  87
  88         This method is used by Toolbar::addDefaultItems() to determine which items to
  89         create.
  90
  91         The items that your method adds to the array that is passed-in will be added to the
  92         toolbar in the same order. Items can appear in the list more than once.
  93     */
  94     virtual void getDefaultItemSet (Array <int>& ids) = 0;
  95
  96     /** Must create an instance of one of the items that the factory lists in its
  97         getAllToolbarItemIds() method.
  98
  99         The itemId parameter can be any of the values listed by your getAllToolbarItemIds()
 100         method, except for the built-in item types from the SpecialItemIds enum, which
 101         are created internally by the toolbar code.
 102
 103         Try not to keep a pointer to the object that is returned, as it will be deleted
 104         automatically by the toolbar, and remember that multiple instances of the same
 105         item type are likely to exist at the same time.
 106     */
 107     virtual ToolbarItemComponent* createItem (int itemId) = 0;
 108 };
 109
 110
 111 #endif   // __JUCE_TOOLBARITEMFACTORY_JUCEHEADER__