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         @param parent
  43             Parent window for the tool bar (typically a wxRibbonPanel).
  44         @param pos
  45             Initial position of the tool bar.
  46         @param size
  47             Initial size of the tool bar.
  48         @param style
  49             Tool bar style, currently unused.
  50     */
  51     wxRibbonToolBar(wxWindow* parent,
  52                   wxWindowID id = wxID_ANY,
  53                   const wxPoint& pos = wxDefaultPosition,
  54                   const wxSize& size = wxDefaultSize,
  55                   long style = 0);
  56
  57     /**
  58         Destructor.
  59     */
  60     virtual ~wxRibbonToolBar();
  61
  62     /**
  63         Create a tool bar in two-step tool bar construction.
  64         Should only be called when the default constructor is used, and
  65         arguments have the same meaning as in the full constructor.
  66     */
  67     bool Create(wxWindow* parent,
  68                 wxWindowID id = wxID_ANY,
  69                 const wxPoint& pos = wxDefaultPosition,
  70                 const wxSize& size = wxDefaultSize,
  71                 long style = 0);
  72
  73     /**
  74         Add a tool to the tool bar (simple version).
  75     */
  76     virtual wxRibbonToolBarToolBase* AddTool(
  77                 int tool_id,
  78                 const wxBitmap& bitmap,
  79                 const wxString& help_string,
  80                 wxRibbonButtonKind kind = wxRIBBON_BUTTON_NORMAL);
  81
  82     /**
  83         Add a dropdown tool to the tool bar (simple version).
  84
  85         @see AddTool()
  86     */
  87     virtual wxRibbonToolBarToolBase* AddDropdownTool(
  88                 int tool_id,
  89                 const wxBitmap& bitmap,
  90                 const wxString& help_string = wxEmptyString);
  91
  92     /**
  93         Add a hybrid tool to the tool bar (simple version).
  94
  95         @see AddTool()
  96     */
  97     virtual wxRibbonToolBarToolBase* AddHybridTool(
  98                 int tool_id,
  99                 const wxBitmap& bitmap,
 100                 const wxString& help_string = wxEmptyString);
 101
 102     /**
 103         Add a tool to the tool bar.
 104
 105         @param tool_id
 106             ID of the new tool (used for event callbacks).
 107         @param bitmap
 108             Bitmap to use as the foreground for the new tool. Does not have
 109             to be the same size as other tool bitmaps, but should be similar
 110             as otherwise it will look visually odd.
 111         @param bitmap_disabled
 112             Bitmap to use when the tool is disabled. If left as wxNullBitmap,
 113             then a bitmap will be automatically generated from @a bitmap.
 114         @param help_string
 115             The UI help string to associate with the new tool.
 116         @param kind
 117             The kind of tool to add.
 118         @param client_data
 119             Client data to associate with the new tool.
 120
 121         @return An opaque pointer which can be used only with other tool bar
 122             methods.
 123
 124         @see AddDropdownTool()
 125         @see AddHybridTool()
 126         @saa AddSeparator()
 127     */
 128     virtual wxRibbonToolBarToolBase* AddTool(
 129                 int tool_id,
 130                 const wxBitmap& bitmap,
 131                 const wxBitmap& bitmap_disabled = wxNullBitmap,
 132                 const wxString& help_string = wxEmptyString,
 133                 wxRibbonButtonKind kind = wxRIBBON_BUTTON_NORMAL,
 134                 wxObject* client_data = NULL);
 135
 136     /**
 137         Add a separator to the tool bar.
 138
 139         Separators are used to separate tools into groups. As such, a separator
 140         is not explicity drawn, but is visually seen as the gap between tool
 141         groups.
 142     */
 143     virtual wxRibbonToolBarToolBase* AddSeparator();
 144
 145     /**
 146         Set the number of rows to distribute tool groups over.
 147
 148         Tool groups can be distributed over a variable number of rows. The way
 149         in which groups are assigned to rows is not specificed, and the order
 150         of groups may change, but they will be distributed in such a way as to
 151         minimise the overall size of the tool bar.
 152
 153         @param nMin
 154             The minimum number of rows to use.
 155         @param nMax
 156             The maximum number of rows to use (defaults to nMin).
 157     */
 158     virtual void SetRows(int nMin, int nMax = -1);
 159 };