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 toggle tool to the tool bar (simple version).
 107
 108         @since 2.9.4
 109
 110         @see AddTool()
 111     */
 112     virtual wxRibbonToolBarToolBase* AddToggleTool(
 113         int tool_id,
 114         const wxBitmap& bitmap,
 115         const wxString& help_string);
 116
 117     /**
 118         Add a tool to the tool bar.
 119
 120         @param tool_id
 121             ID of the new tool (used for event callbacks).
 122         @param bitmap
 123             Bitmap to use as the foreground for the new tool. Does not have
 124             to be the same size as other tool bitmaps, but should be similar
 125             as otherwise it will look visually odd.
 126         @param bitmap_disabled
 127             Bitmap to use when the tool is disabled. If left as wxNullBitmap,
 128             then a bitmap will be automatically generated from @a bitmap.
 129         @param help_string
 130             The UI help string to associate with the new tool.
 131         @param kind
 132             The kind of tool to add.
 133         @param client_data
 134             Client data to associate with the new tool.
 135
 136         @return An opaque pointer which can be used only with other tool bar
 137             methods.
 138
 139         @see AddDropdownTool(), AddHybridTool(), AddSeparator(), InsertTool()
 140     */
 141     virtual wxRibbonToolBarToolBase* AddTool(
 142                 int tool_id,
 143                 const wxBitmap& bitmap,
 144                 const wxBitmap& bitmap_disabled = wxNullBitmap,
 145                 const wxString& help_string = wxEmptyString,
 146                 wxRibbonButtonKind kind = wxRIBBON_BUTTON_NORMAL,
 147                 wxObject* client_data = NULL);
 148
 149     /**
 150         Add a separator to the tool bar.
 151
 152         Separators are used to separate tools into groups. As such, a separator
 153         is not explicitly drawn, but is visually seen as the gap between tool
 154         groups.
 155     */
 156     virtual wxRibbonToolBarToolBase* AddSeparator();
 157
 158     /**
 159         Insert a tool to the tool bar (simple version) as the specified
 160         position.
 161
 162         @since 2.9.4
 163
 164         @see InsertTool()
 165      */
 166     virtual wxRibbonToolBarToolBase* InsertTool(
 167                 size_t pos,
 168                 int tool_id,
 169                 const wxBitmap& bitmap,
 170                 const wxString& help_string,
 171                 wxRibbonButtonKind kind = wxRIBBON_BUTTON_NORMAL);
 172
 173
 174     /**
 175         Insert a dropdown tool to the tool bar (simple version) as the specified
 176         position.
 177
 178         @since 2.9.4
 179
 180         @see AddDropdownTool(), InsertTool()
 181      */
 182     virtual wxRibbonToolBarToolBase* InsertDropdownTool(
 183                 size_t pos,
 184                 int tool_id,
 185                 const wxBitmap& bitmap,
 186                 const wxString& help_string = wxEmptyString);
 187
 188     /**
 189         Insert a hybrid tool to the tool bar (simple version) as the specified
 190         position.
 191
 192         @since 2.9.4
 193
 194         @see AddHybridTool(), InsertTool()
 195      */
 196     virtual wxRibbonToolBarToolBase* InsertHybridTool(
 197                 size_t pos,
 198                 int tool_id,
 199                 const wxBitmap& bitmap,
 200                 const wxString& help_string = wxEmptyString);
 201
 202     /**
 203         Insert a toggle tool to the tool bar (simple version) as the specified
 204         position.
 205
 206         @since 2.9.4
 207
 208        @see AddToggleTool(), InsertTool()
 209      */
 210     virtual wxRibbonToolBarToolBase* InsertToggleTool(
 211                 size_t pos,
 212                 int tool_id,
 213                 const wxBitmap& bitmap,
 214                 const wxString& help_string = wxEmptyString);
 215
 216     /**
 217         Insert a tool to the tool bar at the specified position.
 218
 219         @param pos
 220             Position of the new tool (number of tools and separators from the
 221             beginning of the toolbar).
 222         @param tool_id
 223             ID of the new tool (used for event callbacks).
 224         @param bitmap
 225             Bitmap to use as the foreground for the new tool. Does not have
 226             to be the same size as other tool bitmaps, but should be similar
 227             as otherwise it will look visually odd.
 228         @param bitmap_disabled
 229             Bitmap to use when the tool is disabled. If left as wxNullBitmap,
 230             then a bitmap will be automatically generated from @a bitmap.
 231         @param help_string
 232             The UI help string to associate with the new tool.
 233         @param kind
 234             The kind of tool to add.
 235         @param client_data
 236             Client data to associate with the new tool.
 237
 238         @return An opaque pointer which can be used only with other tool bar
 239             methods.
 240
 241         @since 2.9.4
 242
 243         @see InsertDropdownTool(), InsertHybridTool(), InsertSeparator()
 244     */
 245     virtual wxRibbonToolBarToolBase* InsertTool(
 246                 size_t pos,
 247                 int tool_id,
 248                 const wxBitmap& bitmap,
 249                 const wxBitmap& bitmap_disabled = wxNullBitmap,
 250                 const wxString& help_string = wxEmptyString,
 251                 wxRibbonButtonKind kind = wxRIBBON_BUTTON_NORMAL,
 252                 wxObject* client_data = NULL);
 253
 254     /**
 255         Insert a separator to the tool bar at the specified position.
 256
 257         @since 2.9.4
 258
 259         @see AddSeparator(), InsertTool()
 260     */
 261     virtual wxRibbonToolBarToolBase* InsertSeparator(size_t pos);
 262
 263     /**
 264         Deletes all the tools in the toolbar.
 265
 266         @since 2.9.4
 267     */
 268     virtual void ClearTools();
 269
 270     /**
 271         Removes the specified tool from the toolbar and deletes it.
 272
 273         @param tool_id
 274             ID of the tool to delete.
 275
 276         @returns @true if the tool was deleted, @false otherwise.
 277
 278         @since 2.9.4
 279
 280         @see DeleteToolByPos()
 281     */
 282     virtual bool DeleteTool(int tool_id);
 283
 284     /**
 285         This function behaves like DeleteTool() but it deletes the tool at the
 286         specified position and not the one with the given id.
 287         Useful to delete separators.
 288
 289         @since 2.9.4
 290     */
 291     virtual bool DeleteToolByPos(size_t pos);
 292
 293     /**
 294         Returns a pointer to the tool opaque structure by @a id or @NULL if no
 295         corresponding tool is found.
 296
 297         @since 2.9.4
 298     */
 299     virtual wxRibbonToolBarToolBase* FindById(int tool_id)const;
 300
 301     /**
 302         Return the opaque pointer corresponding to the given tool.
 303
 304         @return an opaque pointer, NULL if is a separator or not found.
 305
 306         @since 2.9.4
 307     */
 308     wxRibbonToolBarToolBase* GetToolByPos(size_t pos)const
 309
 310     /**
 311         Returns the number of tools in the toolbar.
 312
 313         @since 2.9.4
 314     */
 315     virtual size_t GetToolCount() const;
 316
 317     /**
 318         Return the id assciated to the tool opaque structure.
 319
 320         The structure pointer must not be @NULL.
 321
 322         @since 2.9.4
 323     */
 324     virtual int GetToolId(const wxRibbonToolBarToolBase* tool)const;
 325
 326     /**
 327         Get any client data associated with the tool.
 328
 329         @param toolId
 330             ID of the tool in question, as passed to AddTool().
 331
 332         @return Client data, or @NULL if there is none.
 333
 334         @since 2.9.4
 335     */
 336     virtual wxObject* GetToolClientData(int tool_id)const;
 337
 338     /**
 339         Called to determine whether a tool is enabled (responds to user input).
 340
 341         @param toolId
 342             ID of the tool in question, as passed to AddTool().
 343
 344         @return @true if the tool is enabled, @false otherwise.
 345
 346         @since 2.9.4
 347
 348         @see EnableTool()
 349     */
 350     virtual bool GetToolEnabled(int tool_id)const;
 351
 352     /**
 353         Returns the help string for the given tool.
 354
 355         @param toolId
 356             ID of the tool in question, as passed to AddTool().
 357
 358         @since 2.9.4
 359     */
 360     virtual wxString GetToolHelpString(int tool_id)const;
 361
 362     /**
 363         Return the kind of the given tool.
 364
 365         @param toolId
 366             ID of the tool in question, as passed to AddTool().
 367
 368         @since 2.9.4
 369     */
 370     virtual wxRibbonButtonKind GetToolKind(int tool_id)const;
 371
 372     /**
 373         Returns the tool position in the toolbar, or @c wxNOT_FOUND if the tool
 374         is not found.
 375
 376         @param toolId
 377             ID of the tool in question, as passed to AddTool().
 378
 379         @since 2.9.4
 380     */
 381     virtual int GetToolPos(int tool_id)const;
 382
 383     /**
 384         Gets the on/off state of a toggle tool.
 385
 386         @param toolId
 387             ID of the tool in question, as passed to AddTool().
 388
 389         @return @true if the tool is toggled on, @false otherwise.
 390
 391         @see ToggleTool()
 392
 393         @since 2.9.4
 394     */
 395     virtual bool GetToolState(int tool_id)const;
 396
 397     /**
 398         Calculate tool layouts and positions.
 399
 400         Must be called after tools are added to the tool bar, as otherwise
 401         the newly added tools will not be displayed.
 402     */
 403     virtual bool Realize();
 404
 405     /**
 406         Set the number of rows to distribute tool groups over.
 407
 408         Tool groups can be distributed over a variable number of rows. The way
 409         in which groups are assigned to rows is not specified, and the order
 410         of groups may change, but they will be distributed in such a way as to
 411         minimise the overall size of the tool bar.
 412
 413         @param nMin
 414             The minimum number of rows to use.
 415         @param nMax
 416             The maximum number of rows to use (defaults to nMin).
 417     */
 418     virtual void SetRows(int nMin, int nMax = -1);
 419
 420     /**
 421         Sets the client data associated with the tool.
 422
 423         @param id
 424             ID of the tool in question, as passed to AddTool().
 425
 426         @since 2.9.4
 427     */
 428     virtual void SetToolClientData(int tool_id, wxObject* clientData);
 429
 430     /**
 431         Sets the bitmap to be used by the tool with the given ID when the tool
 432         is in a disabled state.
 433
 434         @param tool_id
 435             ID of the tool in question, as passed to AddTool().
 436
 437         @since 2.9.4
 438     */
 439     virtual void SetToolDisabledBitmap(int tool_id, const wxBitmap &bitmap);
 440
 441     /**
 442         Sets the help string shown in tooltip for the given tool.
 443
 444         @param tool_Id
 445             ID of the tool in question, as passed to AddTool().
 446         @param helpString
 447             A string for the help.
 448
 449         @see GetToolHelpString()
 450
 451         @since 2.9.4
 452     */
 453     virtual void SetToolHelpString(int tool_id, const wxString& helpString);
 454
 455     /**
 456         Sets the bitmap to be used by the tool with the given ID.
 457
 458         @param tool_id
 459             ID of the tool in question, as passed to AddTool().
 460
 461         @since 2.9.4
 462     */
 463     virtual void SetToolNormalBitmap(int tool_id, const wxBitmap &bitmap);
 464
 465     /**
 466         Enable or disable a single tool on the bar.
 467
 468         @param tool_id
 469             ID of the tool to enable or disable.
 470         @param enable
 471             @true to enable the tool, @false to disable it.
 472
 473         @since 2.9.4
 474     */
 475     virtual void EnableTool(int tool_id, bool enable = true);
 476
 477     /**
 478         Set a toggle tool to the checked or unchecked state.
 479
 480         @param tool_id
 481             ID of the toggle tool to manipulate.
 482         @param checked
 483             @true to set the tool to the toggled/pressed/checked state,
 484             @false to set it to the untoggled/unpressed/unchecked state.
 485
 486         @since 2.9.4
 487     */
 488     virtual void ToggleTool(int tool_id, bool checked);
 489 };