Toolbar overview

Toolbar overview

A toolbar is an array of bitmap buttons, implemented by drawing bitmaps onto a canvas, instead of using the native button implementation. Since the toolbar inherits from canvas, you can use all canvas functions on a toolbar object.

Each tool can be specified as a normal button, on/off toggle, and disabled or enabled. Tool layout is automatic or manual. Left click and right click events may be intercepted, using OnLeftClick and OnRightClick callbacks. The OnMouseEnter callback is used to update the status line (for example) with help text as the mouse moves over the tools. See window-add-callback for details on these callbacks.

Normal subwindow geometry considerations are applicable (i.e., in a frame with more than one subwindow, you must resize the subwindows when you receive an OnSize event from the frame). The exception is for Multiple Document Interface (MDI) frames under Windows, where you must call frame-set-tool-bar to associate the toolbar with the MDI client window, and after initializing the toolbar height, further resizing is unnecessary.

Toolbars are often displayed as a horizontal strip under the menubar, or in a floating frame. If you wish to draw a border for the toolbar, you must intercept the toolbar's OnPaint handler. In this overriden callback, you must first call the toolbar's toolbar-on-paint function to draw all the tools, and then draw the border onto the toolbar canvas.

Note that under Windows, you must supply bitmaps that are 16 pixels wide and 15 pixels high: they will be placed on a tool button that is 24 by 22 pixels. If you wish to supply bitmaps of a different size, you must call toolbar-set-default-size to set the overall tool button size (as opposed to the bitmap size), or use the toolbar in non-button-creation mode by supplying an extra argument to toolbar-create to disable this functionality.

Note also that in some circumstances, especially for the WIN32 version of wxCLIPS, there are problems with the buttonbar (the symptoms are bitmaps scrambled randomly). If this happens, revert to the normal toolbar by passing 0 in the create-buttons argument to toolbar-create, or download a Windows 95 version of wxCLIPS.

Under X, tool buttons are the same size as the supplied button and there is no need to call toolbar-set-default-size.

Tip: in circumstances where you might think of using drag and drop, which is not currently implemented in wxWindows or wxCLIPS, you can use a toolbar to select 'modes' of operation which change the cursor in a subwindow. Intercept left-click in the subwindow to place an object or perform some operation.

Canvas callbacks apply, plus:

OnLeftClick: The function is called with the toolbar identifier, tool index, and an integer which is 1 if the tool is being toggled on, or zero otherwise. If this is a toggle tool, return 1 to allow the toggle to take place, or 0 otherwise.
OnRightClick: The function is called with the toolbar identifier, tool index, and x and y floating point parameters indicating the position of the click. No value need be returned.
OnMouseEnter: The function is called with the tool index, whenever the mouse goes into a tool, or out of all tools. In the latter case, the tool index is -1. No value need be returned.

Differences in toolbar types

Different toolbar code kicks in according to the platform, and the arguments given to tool-bar-create.

If create-buttons is 0, then the bog-standard wxToolBar class from wxWindows is used: no 3D effect. This works across all supported wxCLIPS platforms. Layout can either be automated, or tools must be placed at absolute coordinates.
If create-buttons is 1 and the platform is Windows 3.1 or generic WIN32 (not Windows 95), then the buttons will be 3D effect using the wxButtonBar class. On WIN32 toggle tools will not work. On UNIX, the standard wxToolBar code will be used instead of wxButtonBar. Again, layout is automatic or absolute.
If create-buttons is 1 and the Windows 95 version of wxCLIPS is being used (not just the WIN32 version running on Windows 95), then the toolbar common control is used, supporting tooltips. However, layout is different: you must specify wxVERTICAL for layout orientation, plus the number of rows (usually 1), and you need to use toolbar-add-separator to get spaces between tools. You cannot place tools at absolute coordinates or use the toolbar-layout function. You must also call toolbar-create-tools after adding tools. Device context painting is restricted and no events may be intercepted for the toolbar except OnLeftClick and OnMouseEnter.

Note: under Windows 95, a wxButtonBar cannot be moved to any position other than the top-left of the frame.