ToolBar Class (Typed)

Object
  VObject
    Control
      ToolBar

Request Example View Source

A toolbar provides the user with an alternative way of selecting menu commands. Although a toolbar looks more like a collection of controls than like a menu, it is constructed and manipulated as a menu rather than as a control. It is true that the events generated by a menu, a toolbar, and a push button are not fundamentally different: each menu command, toolbar button, or push button has a symbolic name; each type of event calls a named method; each has a description that appears in the status bar ("short help") and a help context that appears when you select context help (Shift+F1). But, since the toolbar is one object, capable of generating many events, and, since it is attached to the window as a whole (instead of as several push buttons), it resembles a menu more than a regular control. Also, the standard way of defining and using a toolbar is as an adjunct of its associated menu; this is the structure generated by the Menu Editor. Toolbar buttons can be presented with icons, icons plus text captions, or text only. The border around the buttons offers several different looks, and the gaps between buttons can be adjusted. If a toolbar is too small to display all its buttons, perhaps because its owner window is too small, it automatically presents scrolling buttons. The placement of the toolbar depends, to a certain extent, on its contents. For example, text-only buttons are long and thin, and are, therefore, better stacked along a vertical edge than along the top or bottom edge. Icon-only buttons, with no gaps, look very natural along the top edge. Icon and text buttons, with a small gap, are effective along the bottom edge. The ToolBar class also provides CoolBar/Band support, i.e., toolbars with separator bands: (This example is from one of the Internet Explorer's flat-style, toolbar bands.) A window is assigned a toolbar the same way it is assigned a menu, through an assignment to AppWindow:ToolBar(). Each toolbar button is associated with a menu command and generates the corresponding menu event; therefore, the menu and toolbar assigned to a window must be coordinated. The most convenient way to manage the toolbar is to associate it with a menu when both are created. Then, when the menu is assigned to the window, its toolbar is automatically assigned as well. This automatic approach, which fits the class definition created by the Menu Editor, ensures that toolbar button clicks are associated with the intended menu command event. (This is also the approach used with the accelerator table. Thus, a "menu" is actually a combination of menu, accelerator table, and toolbar, all coordinated and all used together.) It is possible to place a toolbar on any window, even windows that cannot own menus (such as dialog windows and nested subwindows). In these cases, assigning a menu does not produce a visible menu, but the toolbar is still active. It is also possible to have a toolbar button associated with a menu command that is not included on any menu, as long as the menu command is registered with Menu:RegisterItem(). A toolbar takes up room on the window's client area. Some window types automatically adapt to this spatial conflict, but others require explicit management of space. The most common use of a toolbar in business applications is to attach it to a shell window or a data window. Both of these window types automatically adapt to the toolbar, so no further action is required. The data window is most likely used as a child window under the shell, or as a nested subwindow; in either case, the data window adapts to the toolbar. Placing a toolbar on a subwindow is particularly useful: it visually associates operations with the data they apply to. Many data windows may use toolbar buttons like Insert Record, Delete Record, Skip Next, Skip Previous, Go Top, Go Bottom, Seek, Undo, Cut, Copy, and Paste. With general top windows, child windows, and dialog windows, the management of space is the responsibility of the developer. With a toolbar on the window, this is somewhat tricky, especially if the user is allowed to drag the toolbar around: the room available depends both on resizing of the window and placement of the toolbar. The toolbar has the ToolBar:ClientArea access, which can be called during expose events to determine the shape of the remaining area. The action of control events sent by a toolbar attached to a window would seem to be pretty obvious: clicking on the Print button sends a #Print message to the window. But what happens if the toolbar is not attached to a child window, but to the shell window? Or if it is attached to the child window but the method that acts on the message belongs to the shell window? And what of a toolbar attached to a data window used as a nested subform? Toolbars are identical to menus in their action. Regardless of which window owns the toolbar or menu, the command event is sent first to the window that has focus; if it does not deal with it, it is sent to its owner, and to its owner, until it is handled. If no window responds to the message, the shell window displays a message in its status bar. More precisely, the chain of responses looks like this, given the symbolic name of the toolbar or menu command: Does the window that has focus have a method with a proper name? If so, it is called. Check if its owner has a matching method, as well as the owner's owner, and so on. If no window has a matching method, the message is sent to the MenuCommand() method of the window with focus. The default implementation has the following logic: if it is owned by a window (as is a child window or subform), pass the method up to its owner; if it is owned by the application (as is the top or shell window), check if there is a window class with that name, and if so instantiate it; if not, display the message. The MenuCommand() method can, of course, be replaced with different logic (for example, the traditional CASE statement often used in low-level Windows programming). Thus, there are two chains of escalation: first, the system looks for matching method names up the ownership chain; then it escalates through the MenuCommand() methods up the ownership chain. If nobody reacts to the method, as a last resort, the window instantiation is tried; otherwise, it fails. This means that a toolbar can be placed on the shell window, on a child window, or even on a nested subwindow: it is active in any case, and the message is sent to all the windows and propagated up the ownership chain. Remember that only one menu is visible at any time, and a child window with a menu replaces the menu of its shell; but toolbars are different, they can be visible on any type of window. The window instantiation trick means that if we design a window in the Window Editor, all we have to do to open it is to give its name to a menu or toolbar item that is owned by some visible window. Note that there is a potential for confusing the end user with commands that could refer to different windows. (This problem is not confined to toolbars; it applies to menus as well.) Consider an order window, with information about an order and a nested subwindow (in browse view) that contains the order's line items. If a menu contains a Delete command, what does this refer to? Does it delete an order, an order and all its line items, or only a line item? Technically, the issue is clear: the command is sent to the lowest level window that has focus, so if the user is located on the line item subwindow, that window gets the command first. If it does not respond to it, the order window and later the shell window gets the command. However, from the user's viewpoint, this behavior is not obvious. The problem lies in the caption of the menu command or toolbar button: "Delete" is not very clear. Since the user may not be aware that the line item table is a subwindow (it looks just like a table on a window) getting different effects of Delete (depending on where the cursor is) can be confusing. It is, therefore, recommended that menu commands and toolbar buttons be labeled explicitly and clearly, for example as "Delete Order" and "Delete Item." Even if higher-level logic disables commands depending on cursor location and data (for example, Delete Order may be dimmed as long as there are still unshipped line items), captions should still be clear.

For examples of suitable code, use the Menu Editor to generate a simple menu with a toolbar, and then use the Window Editor to assign this menu to a window.