interface/wx/ribbon/toolbar.h

   1 ///////////////////////////////////////////////////////////////////////////////
   2 // Name:        ribbon/toolbar.h
   3 // Purpose:     interface of wxRibbonToolBar
   4 // Author:      Peter Cawley
   5 // Licence:     wxWindows licence
   6 ///////////////////////////////////////////////////////////////////////////////
   7
   8 /**
   9     @class wxRibbonToolBar
  10
  11     A ribbon tool bar is similar to a traditional toolbar which has no labels.
  12     It contains one or more tool groups, each of which contains one or more
  13     tools. Each tool is represented by a (generally small, i.e. 16x15) bitmap.
  14
  15     @beginEventEmissionTable{wxRibbonToolBarEvent}
  16     @event{EVT_RIBBONTOOLBAR_CLICKED(id, func)}
  17         Triggered when the normal (non-dropdown) region of a tool on the tool
  18         bar is clicked.
  19     @event{EVT_RIBBONTOOLBAR_DROPDOWN_CLICKED(id, func)}
  20         Triggered when the dropdown region of a tool on the tool bar is
  21         clicked. wxRibbonToolBarEvent::PopupMenu() should be called by the
  22         event handler if it wants to display a popup menu (which is what most
  23         dropdown tools should be doing).
  24     @endEventTable
  25
  26     @library{wxribbon}
  27     @category{ribbon}
  28 */
  29 class wxRibbonToolBar : public wxRibbonControl
  30 {
  31 public:
  32     /**
  33         Default constructor.
  34         With this constructor, Create() should be called in order to create
  35         the tool bar.
  36     */
  37     wxRibbonToolBar();
  38
  39     /**
  40         Construct a ribbon tool bar with the given parameters.
  41
  42         @param parent
  43             Parent window for the tool bar (typically a wxRibbonPanel).
  44         @param id
  45             An identifier for the toolbar. @c wxID_ANY is taken to mean a default.
  46         @param pos
  47             Initial position of the tool bar.
  48         @param size
  49             Initial size of the tool bar.
  50         @param style
  51             Tool bar style, currently unused.
  52     */
  53     wxRibbonToolBar(wxWindow* parent,
  54                   wxWindowID id = wxID_ANY,
  55                   const wxPoint& pos = wxDefaultPosition,
  56                   const wxSize& size = wxDefaultSize,
  57                   long style = 0);
  58
  59     /**
  60         Destructor.
  61     */
  62     virtual ~wxRibbonToolBar();
  63
  64     /**
  65         Create a tool bar in two-step tool bar construction.
  66         Should only be called when the default constructor is used, and
  67         arguments have the same meaning as in the full constructor.
  68     */
  69     bool Create(wxWindow* parent,
  70                 wxWindowID id = wxID_ANY,
  71                 const wxPoint& pos = wxDefaultPosition,
  72                 const wxSize& size = wxDefaultSize,
  73                 long style = 0);
  74
  75     /**
  76         Add a tool to the tool bar (simple version).
  77     */
  78     virtual wxRibbonToolBarToolBase* AddTool(
  79                 int tool_id,
  80                 const wxBitmap& bitmap,
  81                 const wxString& help_string,
  82                 wxRibbonButtonKind kind = wxRIBBON_BUTTON_NORMAL);
  83
  84     /**
  85         Add a dropdown tool to the tool bar (simple version).
  86
  87         @see AddTool()
  88     */
  89     virtual wxRibbonToolBarToolBase* AddDropdownTool(
  90                 int tool_id,
  91                 const wxBitmap& bitmap,
  92                 const wxString& help_string = wxEmptyString);
  93
  94     /**
  95         Add a hybrid tool to the tool bar (simple version).
  96
  97         @see AddTool()
  98     */
  99     virtual wxRibbonToolBarToolBase* AddHybridTool(
 100                 int tool_id,
 101                 const wxBitmap& bitmap,
 102                 const wxString& help_string = wxEmptyString);
 103
 104     /**
 105         Add a toggle tool to the tool bar (simple version).
 106
 107         @since 2.9.4
 108
 109         @see AddTool()
 110     */
 111     virtual wxRibbonToolBarToolBase* AddToggleTool(
 112         int tool_id,
 113         const wxBitmap& bitmap,
 114         const wxString& help_string);
 115
 116     /**
 117         Add a tool to the tool bar.
 118
 119         @param tool_id
 120             ID of the new tool (used for event callbacks).
 121         @param bitmap
 122             Bitmap to use as the foreground for the new tool. Does not have
 123             to be the same size as other tool bitmaps, but should be similar
 124             as otherwise it will look visually odd.
 125         @param bitmap_disabled
 126             Bitmap to use when the tool is disabled. If left as wxNullBitmap,
 127             then a bitmap will be automatically generated from @a bitmap.
 128         @param help_string
 129             The UI help string to associate with the new tool.
 130         @param kind
 131             The kind of tool to add.
 132         @param client_data
 133             Client data to associate with the new tool.
 134
 135         @return An opaque pointer which can be used only with other tool bar
 136             methods.
 137
 138         @see AddDropdownTool(), AddHybridTool(), AddSeparator(), InsertTool()
 139     */
 140     virtual wxRibbonToolBarToolBase* AddTool(
 141                 int tool_id,
 142                 const wxBitmap& bitmap,
 143                 const wxBitmap& bitmap_disabled = wxNullBitmap,
 144                 const wxString& help_string = wxEmptyString,
 145                 wxRibbonButtonKind kind = wxRIBBON_BUTTON_NORMAL,
 146                 wxObject* client_data = NULL);
 147
 148     /**
 149         Add a separator to the tool bar.
 150
 151         Separators are used to separate tools into groups. As such, a separator
 152         is not explicitly drawn, but is visually seen as the gap between tool
 153         groups.
 154     */
 155     virtual wxRibbonToolBarToolBase* AddSeparator();
 156
 157     /**
 158         Insert a tool to the tool bar (simple version) as the specified
 159         position.
 160
 161         @since 2.9.4
 162
 163         @see InsertTool()
 164      */
 165     virtual wxRibbonToolBarToolBase* InsertTool(
 166                 size_t pos,
 167                 int tool_id,
 168                 const wxBitmap& bitmap,
 169                 const wxString& help_string,
 170                 wxRibbonButtonKind kind = wxRIBBON_BUTTON_NORMAL);
 171
 172
 173     /**
 174         Insert a dropdown tool to the tool bar (simple version) as the specified
 175         position.
 176
 177         @since 2.9.4
 178
 179         @see AddDropdownTool(), InsertTool()
 180      */
 181     virtual wxRibbonToolBarToolBase* InsertDropdownTool(
 182                 size_t pos,
 183                 int tool_id,
 184                 const wxBitmap& bitmap,
 185                 const wxString& help_string = wxEmptyString);
 186
 187     /**
 188         Insert a hybrid tool to the tool bar (simple version) as the specified
 189         position.
 190
 191         @since 2.9.4
 192
 193         @see AddHybridTool(), InsertTool()
 194      */
 195     virtual wxRibbonToolBarToolBase* InsertHybridTool(
 196                 size_t pos,
 197                 int tool_id,
 198                 const wxBitmap& bitmap,
 199                 const wxString& help_string = wxEmptyString);
 200
 201     /**
 202         Insert a toggle tool to the tool bar (simple version) as the specified
 203         position.
 204
 205         @since 2.9.4
 206
 207        @see AddToggleTool(), InsertTool()
 208      */
 209     virtual wxRibbonToolBarToolBase* InsertToggleTool(
 210                 size_t pos,
 211                 int tool_id,
 212                 const wxBitmap& bitmap,
 213                 const wxString& help_string = wxEmptyString);
 214
 215     /**
 216         Insert a tool to the tool bar at the specified position.
 217
 218         @param pos
 219             Position of the new tool (number of tools and separators from the
 220             beginning of the toolbar).
 221         @param tool_id
 222             ID of the new tool (used for event callbacks).
 223         @param bitmap
 224             Bitmap to use as the foreground for the new tool. Does not have
 225             to be the same size as other tool bitmaps, but should be similar
 226             as otherwise it will look visually odd.
 227         @param bitmap_disabled
 228             Bitmap to use when the tool is disabled. If left as wxNullBitmap,
 229             then a bitmap will be automatically generated from @a bitmap.
 230         @param help_string
 231             The UI help string to associate with the new tool.
 232         @param kind
 233             The kind of tool to add.
 234         @param client_data
 235             Client data to associate with the new tool.
 236
 237         @return An opaque pointer which can be used only with other tool bar
 238             methods.
 239
 240         @since 2.9.4
 241
 242         @see InsertDropdownTool(), InsertHybridTool(), InsertSeparator()
 243     */
 244     virtual wxRibbonToolBarToolBase* InsertTool(
 245                 size_t pos,
 246                 int tool_id,
 247                 const wxBitmap& bitmap,
 248                 const wxBitmap& bitmap_disabled = wxNullBitmap,
 249                 const wxString& help_string = wxEmptyString,
 250                 wxRibbonButtonKind kind = wxRIBBON_BUTTON_NORMAL,
 251                 wxObject* client_data = NULL);
 252
 253     /**
 254         Insert a separator to the tool bar at the specified position.
 255
 256         @since 2.9.4
 257
 258         @see AddSeparator(), InsertTool()
 259     */
 260     virtual wxRibbonToolBarToolBase* InsertSeparator(size_t pos);
 261
 262     /**
 263         Deletes all the tools in the toolbar.
 264
 265         @since 2.9.4
 266     */
 267     virtual void ClearTools();
 268
 269     /**
 270         Removes the specified tool from the toolbar and deletes it.
 271
 272         @param tool_id
 273             ID of the tool to delete.
 274
 275         @returns @true if the tool was deleted, @false otherwise.
 276
 277         @since 2.9.4
 278
 279         @see DeleteToolByPos()
 280     */
 281     virtual bool DeleteTool(int tool_id);
 282
 283     /**
 284         This function behaves like DeleteTool() but it deletes the tool at the
 285         specified position and not the one with the given id.
 286         Useful to delete separators.
 287
 288         @since 2.9.4
 289     */
 290     virtual bool DeleteToolByPos(size_t pos);
 291
 292     /**
 293         Returns a pointer to the tool opaque structure by @a id or @NULL if no
 294         corresponding tool is found.
 295
 296         @since 2.9.4
 297     */
 298     virtual wxRibbonToolBarToolBase* FindById(int tool_id)const;
 299
 300     /**
 301         Return the opaque pointer corresponding to the given tool.
 302
 303         @return an opaque pointer, NULL if is a separator or not found.
 304
 305         @since 2.9.4
 306     */
 307     wxRibbonToolBarToolBase* GetToolByPos(size_t pos)const
 308
 309     /**
 310         Returns the number of tools in the toolbar.
 311
 312         @since 2.9.4
 313     */
 314     virtual size_t GetToolCount() const;
 315
 316     /**
 317         Return the id assciated to the tool opaque structure.
 318
 319         The structure pointer must not be @NULL.
 320
 321         @since 2.9.4
 322     */
 323     virtual int GetToolId(const wxRibbonToolBarToolBase* tool)const;
 324
 325     /**
 326         Get any client data associated with the tool.
 327
 328         @param tool_id
 329             ID of the tool in question, as passed to AddTool().
 330
 331         @return Client data, or @NULL if there is none.
 332
 333         @since 2.9.4
 334     */
 335     virtual wxObject* GetToolClientData(int tool_id)const;
 336
 337     /**
 338         Called to determine whether a tool is enabled (responds to user input).
 339
 340         @param tool_id
 341             ID of the tool in question, as passed to AddTool().
 342
 343         @return @true if the tool is enabled, @false otherwise.
 344
 345         @since 2.9.4
 346
 347         @see EnableTool()
 348     */
 349     virtual bool GetToolEnabled(int tool_id)const;
 350
 351     /**
 352         Returns the help string for the given tool.
 353
 354         @param tool_id
 355             ID of the tool in question, as passed to AddTool().
 356
 357         @since 2.9.4
 358     */
 359     virtual wxString GetToolHelpString(int tool_id)const;
 360
 361     /**
 362         Return the kind of the given tool.
 363
 364         @param tool_id
 365             ID of the tool in question, as passed to AddTool().
 366
 367         @since 2.9.4
 368     */
 369     virtual wxRibbonButtonKind GetToolKind(int tool_id)const;
 370
 371     /**
 372         Returns the tool position in the toolbar, or @c wxNOT_FOUND if the tool
 373         is not found.
 374
 375         @param tool_id
 376             ID of the tool in question, as passed to AddTool().
 377
 378         @since 2.9.4
 379     */
 380     virtual int GetToolPos(int tool_id)const;
 381
 382     /**
 383         Gets the on/off state of a toggle tool.
 384
 385         @param tool_id
 386             ID of the tool in question, as passed to AddTool().
 387
 388         @return @true if the tool is toggled on, @false otherwise.
 389
 390         @see ToggleTool()
 391
 392         @since 2.9.4
 393     */
 394     virtual bool GetToolState(int tool_id)const;
 395
 396     /**
 397         Calculate tool layouts and positions.
 398
 399         Must be called after tools are added to the tool bar, as otherwise
 400         the newly added tools will not be displayed.
 401     */
 402     virtual bool Realize();
 403
 404     /**
 405         Set the number of rows to distribute tool groups over.
 406
 407         Tool groups can be distributed over a variable number of rows. The way
 408         in which groups are assigned to rows is not specified, and the order
 409         of groups may change, but they will be distributed in such a way as to
 410         minimise the overall size of the tool bar.
 411
 412         @param nMin
 413             The minimum number of rows to use.
 414         @param nMax
 415             The maximum number of rows to use (defaults to nMin).
 416     */
 417     virtual void SetRows(int nMin, int nMax = -1);
 418
 419     /**
 420         Sets the client data associated with the tool.
 421
 422         @param tool_id
 423             ID of the tool in question, as passed to AddTool().
 424         @param clientData
 425             The client data to use.
 426
 427         @since 2.9.4
 428     */
 429     virtual void SetToolClientData(int tool_id, wxObject* clientData);
 430
 431     /**
 432         Sets the bitmap to be used by the tool with the given ID when the tool
 433         is in a disabled state.
 434
 435         @param tool_id
 436             ID of the tool in question, as passed to AddTool().
 437         @param bitmap
 438             Bitmap to use for disabled tools.
 439
 440         @since 2.9.4
 441     */
 442     virtual void SetToolDisabledBitmap(int tool_id, const wxBitmap &bitmap);
 443
 444     /**
 445         Sets the help string shown in tooltip for the given tool.
 446
 447         @param tool_id
 448             ID of the tool in question, as passed to AddTool().
 449         @param helpString
 450             A string for the help.
 451
 452         @see GetToolHelpString()
 453
 454         @since 2.9.4
 455     */
 456     virtual void SetToolHelpString(int tool_id, const wxString& helpString);
 457
 458     /**
 459         Sets the bitmap to be used by the tool with the given ID.
 460
 461         @param tool_id
 462             ID of the tool in question, as passed to AddTool().
 463         @param bitmap
 464             Bitmap to use for normals tools.
 465
 466         @since 2.9.4
 467     */
 468     virtual void SetToolNormalBitmap(int tool_id, const wxBitmap &bitmap);
 469
 470     /**
 471         Enable or disable a single tool on the bar.
 472
 473         @param tool_id
 474             ID of the tool to enable or disable.
 475         @param enable
 476             @true to enable the tool, @false to disable it.
 477
 478         @since 2.9.4
 479     */
 480     virtual void EnableTool(int tool_id, bool enable = true);
 481
 482     /**
 483         Set a toggle tool to the checked or unchecked state.
 484
 485         @param tool_id
 486             ID of the toggle tool to manipulate.
 487         @param checked
 488             @true to set the tool to the toggled/pressed/checked state,
 489             @false to set it to the untoggled/unpressed/unchecked state.
 490
 491         @since 2.9.4
 492     */
 493     virtual void ToggleTool(int tool_id, bool checked);
 494 };