interface/wx/ribbon/toolbar.h

   1 ///////////////////////////////////////////////////////////////////////////////
   2 // Name:        ribbon/toolbar.h
   3 // Purpose:     interface of wxRibbonToolBar
   4 // Author:      Peter Cawley
   5 // RCS-ID:      $Id$
   6 // Licence:     wxWindows licence
   7 ///////////////////////////////////////////////////////////////////////////////
   8
   9 /**
  10     @class wxRibbonToolBar
  11
  12     A ribbon tool bar is similar to a traditional toolbar which has no labels.
  13     It contains one or more tool groups, each of which contains one or more
  14     tools. Each tool is represented by a (generally small, i.e. 16x15) bitmap.
  15
  16     @beginEventEmissionTable{wxRibbonToolBarEvent}
  17     @event{EVT_RIBBONTOOLBAR_CLICKED(id, func)}
  18         Triggered when the normal (non-dropdown) region of a tool on the tool
  19         bar is clicked.
  20     @event{EVT_RIBBONTOOLBAR_DROPDOWN_CLICKED(id, func)}
  21         Triggered when the dropdown region of a tool on the tool bar is
  22         clicked. wxRibbonToolBarEvent::PopupMenu() should be called by the
  23         event handler if it wants to display a popup menu (which is what most
  24         dropdown tools should be doing).
  25     @endEventTable
  26
  27     @library{wxribbon}
  28     @category{ribbon}
  29 */
  30 class wxRibbonToolBar : public wxRibbonControl
  31 {
  32 public:
  33     /**
  34         Default constructor.
  35         With this constructor, Create() should be called in order to create
  36         the tool bar.
  37     */
  38     wxRibbonToolBar();
  39
  40     /**
  41         Construct a ribbon tool bar with the given parameters.
  42
  43         @param parent
  44             Parent window for the tool bar (typically a wxRibbonPanel).
  45         @param id
  46             An identifier for the toolbar. @c wxID_ANY is taken to mean a default.
  47         @param pos
  48             Initial position of the tool bar.
  49         @param size
  50             Initial size of the tool bar.
  51         @param style
  52             Tool bar style, currently unused.
  53     */
  54     wxRibbonToolBar(wxWindow* parent,
  55                   wxWindowID id = wxID_ANY,
  56                   const wxPoint& pos = wxDefaultPosition,
  57                   const wxSize& size = wxDefaultSize,
  58                   long style = 0);
  59
  60     /**
  61         Destructor.
  62     */
  63     virtual ~wxRibbonToolBar();
  64
  65     /**
  66         Create a tool bar in two-step tool bar construction.
  67         Should only be called when the default constructor is used, and
  68         arguments have the same meaning as in the full constructor.
  69     */
  70     bool Create(wxWindow* parent,
  71                 wxWindowID id = wxID_ANY,
  72                 const wxPoint& pos = wxDefaultPosition,
  73                 const wxSize& size = wxDefaultSize,
  74                 long style = 0);
  75
  76     /**
  77         Add a tool to the tool bar (simple version).
  78     */
  79     virtual wxRibbonToolBarToolBase* AddTool(
  80                 int tool_id,
  81                 const wxBitmap& bitmap,
  82                 const wxString& help_string,
  83                 wxRibbonButtonKind kind = wxRIBBON_BUTTON_NORMAL);
  84
  85     /**
  86         Add a dropdown tool to the tool bar (simple version).
  87
  88         @see AddTool()
  89     */
  90     virtual wxRibbonToolBarToolBase* AddDropdownTool(
  91                 int tool_id,
  92                 const wxBitmap& bitmap,
  93                 const wxString& help_string = wxEmptyString);
  94
  95     /**
  96         Add a hybrid tool to the tool bar (simple version).
  97
  98         @see AddTool()
  99     */
 100     virtual wxRibbonToolBarToolBase* AddHybridTool(
 101                 int tool_id,
 102                 const wxBitmap& bitmap,
 103                 const wxString& help_string = wxEmptyString);
 104
 105     /**
 106         Add a tool to the tool bar.
 107
 108         @param tool_id
 109             ID of the new tool (used for event callbacks).
 110         @param bitmap
 111             Bitmap to use as the foreground for the new tool. Does not have
 112             to be the same size as other tool bitmaps, but should be similar
 113             as otherwise it will look visually odd.
 114         @param bitmap_disabled
 115             Bitmap to use when the tool is disabled. If left as wxNullBitmap,
 116             then a bitmap will be automatically generated from @a bitmap.
 117         @param help_string
 118             The UI help string to associate with the new tool.
 119         @param kind
 120             The kind of tool to add.
 121         @param client_data
 122             Client data to associate with the new tool.
 123
 124         @return An opaque pointer which can be used only with other tool bar
 125             methods.
 126
 127         @see AddDropdownTool(), AddHybridTool(), AddSeparator()
 128     */
 129     virtual wxRibbonToolBarToolBase* AddTool(
 130                 int tool_id,
 131                 const wxBitmap& bitmap,
 132                 const wxBitmap& bitmap_disabled = wxNullBitmap,
 133                 const wxString& help_string = wxEmptyString,
 134                 wxRibbonButtonKind kind = wxRIBBON_BUTTON_NORMAL,
 135                 wxObject* client_data = NULL);
 136
 137     /**
 138         Add a separator to the tool bar.
 139
 140         Separators are used to separate tools into groups. As such, a separator
 141         is not explicity drawn, but is visually seen as the gap between tool
 142         groups.
 143     */
 144     virtual wxRibbonToolBarToolBase* AddSeparator();
 145
 146     /**
 147         Set the number of rows to distribute tool groups over.
 148
 149         Tool groups can be distributed over a variable number of rows. The way
 150         in which groups are assigned to rows is not specificed, and the order
 151         of groups may change, but they will be distributed in such a way as to
 152         minimise the overall size of the tool bar.
 153
 154         @param nMin
 155             The minimum number of rows to use.
 156         @param nMax
 157             The maximum number of rows to use (defaults to nMin).
 158     */
 159     virtual void SetRows(int nMin, int nMax = -1);
 160 };