Click or drag to resize

ToolBar Class

X#
Create a toolbar.
Inheritance Hierarchy
Object
  VObject
    Control
      ToolBar

Namespace:  VO
Assembly:  VOGUIClasses (in VOGUIClasses.dll) Version: 2.19
Syntax
 CLASS ToolBar INHERIT Control
Request Example View Source

The ToolBar type exposes the following members.

Constructors
  NameDescription
Public methodToolBar
Create a toolbar.
Top
Properties
  NameDescription
Public propertyBackground
The brush used for painting the background of the control. For example, in a single line edit control, the background is the color behind the text in the edit control.
(Inherited from Control.)
Public propertyBandCount
The number of bands in the toolbar.
Public propertyBandImageList
An Image List object used for the bands.
Public propertyBitmap
The Bitmap object (containing a bitmap ribbon with one or more button images) that will be used to display buttons on the toolbar. If not assigned, the default bitmap is used.
Public propertyBorderStyle
This property is no longer supported. It is included only for compatibility with existing X#1.0 code.
Public propertyBoundingBox
The bounding box, in canvas coordinates, representing the minimal area that encloses the toolbar.
Public propertyButtonCount
A numeric value representing the number of buttons currently on the toolbar.
Public propertyButtonSize
A Dimension object representing the size of buttons on the toolbar. If not assigned, the default is a 16 by 16 button.
Public propertyButtonStyle
A constant that represents how the buttons are displayed:
Public propertyCaption
A string representing the caption of the control (i.e., the static text identifying the control)
(Inherited from Control.)
Public propertyClientArea
A bounding box (group or character box) representing the area of its parent window that remains available given the placement of the toolbar.
Public propertyContextMenu
A menu object representing the local pop-up menu for a control.
(Inherited from Control.)
Public propertyControlID
A number between 1 and 8000 representing the unique ID of a control
(Inherited from Control.)
Public propertyFieldSpec
The field specification connected to the control.
(Inherited from Control.)
Public propertyGapSize
This property is no longer supported. It is included only for compatibility with existing X#1.0 code.
Public propertyHyperLabel
The hyperlabel connected to the control.
(Inherited from Control.)
Public propertyImageCount
A numeric value representing the number of images in the toolbar bitmap. If a custom bitmap has been assigned to the toolbar, this value must be assigned as the number of images in that bitmap.
Public propertyLocation
This property is no longer supported. It is included only for compatibility with existing X#1.0 code.
Public propertyModified
A logical value that is set to TRUE when a standard edit control or editable combo box is in the process of being modified.
(Inherited from Control.)
Public propertyName
A string representing the name of the control.
(Inherited from Control.)
Public propertyNameSym
A symbol representing the name of the control.
(Inherited from Control.)
Public propertyOrigin
A point representing the location of a control on its owner window, in canvas coordinates.
(Inherited from Control.)
Public propertyOwner
The owner window of a control.
(Inherited from Control.)
Public propertyOwnerAlignment
Constant representing how the window will be aligned within its owner window.
(Inherited from Control.)
Public propertyReadOnly
Is the control readonly ?
(Inherited from Control.)
Public propertyCode exampleRows
A numeric value representing the number of rows of buttons on the toolbar. Note that Rows now has an optional parameter, <symTB>, to indicate which toolbar, or sub-toolbar, to query. If not specified, #MAINTOOLBAR is assumed.
Public propertySeparatorSize
This property is no longer supported. It is included only for compatibility with existing X#1.0 code.
Public propertyServer
The server object that currently connected to this control. If no server is connected, the value is NIL.
(Inherited from Control.)
Public propertySize
A dimension representing the size of a control.
(Inherited from Control.)
Public propertyStatus
A hyperlabel indicating the status of the control after a validation attempt or other action.
(Inherited from Control.)
Public propertyCode exampleTextValue
A string representing the value held in the control.
(Inherited from Control.)
Public propertyToolTipText
String value representing the tooltip text used when the user moves the mouse pointer over the control.
(Inherited from Control.)
Public propertyUseHLForToolTip
Logical value determining whether the descriptive text of a control's Hyperlabel should be used as the tooltip text.
(Inherited from Control.)
Public propertyCode exampleValue
The value held in the control, in whatever data type the control holds.
(Inherited from Control.)
Public propertyValueChanged
A logical value representing whether the control's Value has been changed from its prior setting.
(Inherited from Control.)
Top
Methods
  NameDescription
Public methodActivate
Provide a method that is invoked when the control has focus and a window is activated.

(Inherited from Control.)
Public methodCode exampleAddBand
Use this method to add a band to the ToolBar.
Public methodAddSubToolBarBand
Add a new band to the toolbar as a sub-toolbar.
Public methodAddTipText
Add a string to be displayed as tip text for a button.
Public methodCode exampleAppendItem
Add a new toolbar button item to the end of the toolbar from the list of buttons available.
Public methodAsString
Return the contents of the control (or its identifying label).
(Inherited from Control.)
Public methodChangeTipText
Change the current tip text for a button.
Public methodClickItem
Make a button look like it is has been clicked, indicating that it has been selected.
Public methodConfigure
This method is no longer supported. It is included only for compatibility with existing X#1.0 code.
Public methodDeactivate
Provide a method that is invoked when the control has focus and a window is deactivated.

(Inherited from Control.)
Public methodDEFAULT
Call the default windows procedure for a control and set the EventReturnValue.
(Inherited from Control.)
Public methodDeleteItem
Remove a button from the toolbar.
Public methodDestroy
Provide a method to de-instantiate a ToolBar object.
(Overrides Destroy.)
Public methodDimItem
Dim a button.
Public methodDisable
Disable a control (until a subsequent call to Control:Enable()).
(Inherited from Control.)
Public methodDisableItem
Disable a button.
Public methodDisableTheme
Disable the WinXP theme for a control.
(Inherited from Control.)
Public methodDispatch
Provide the prototype dispatcher for events within the system when the control has focus; routing various events to their appropriate event handlers.

(Inherited from Control.)
Public methodEnable
Enable a control that was previously disabled.
(Inherited from Control.)
Public methodCode exampleEnableBands
Enable toolbar band support.
Public methodEnableDrag
Allow the user to move the toolbar around with the mouse.
Public methodEnableItem
Enable a button that has been disabled.
Public methodExpose
Provide a method that is invoked when the control has focus and whenever part of the window needs repainting.

(Inherited from Control.)
Public methodFocusChange
Provide a method that is invoked when the control has focus and the input focus changes from the current control to another (or vice versa).

(Inherited from Control.)
Public methodGetButtonDescription
Retrieve the description of a toolbar button.
Public methodGetExStyle
Retrieve the Ex styles for the control.
(Inherited from Control.)
Public methodGetImageList
Gets the ImageList that is specified by the parameters passed.
Public methodGetStyle
Retrieve the styles for the control.
(Inherited from Control.)
Public methodGetTipText
Return the current tip text for a button.
Public methodHandle
Return the handle for a control.
(Inherited from Control.)
Public methodHasBorder
Check if a border has been set for the control
(Inherited from Control.)
Public methodHasStyle
Check if a style value has been set for the control
(Inherited from Control.)
Public methodHide
Hide a toolbar so it is not visible.
(Overrides Hide.)
Public methodHideItem
Hide a button.
Public methodHorizontalScroll
Provide a method that is invoked when the control has focus and a horizontal scroll bar is scrolled.

(Inherited from Control.)
Public methodInsertItem
Insert a new toolbar button item before a specified toolbar button item, from the list of buttons available.
Public methodCode exampleIsClicked
Return a logical value indicating whether the specified button is currently clicked or selected.
Public methodCode exampleIsDimmed
Determine whether a button is dimmed.
Public methodIsEnabled
Report if this control is currently enabled.
(Inherited from Control.)
Public methodCode exampleIsEnabled(Usual, Usual, Usual)
Return a logical value indicating whether the specified button is currently enabled.
Public methodIsExStyle
Check if a exstyle value has been set for the control
(Inherited from Control.)
Public methodIsHidden
Determine whether a button is hidden.
Public methodIsPressed
Determine whether a button is pressed.
Public methodIsReadOnly
Report if this control is currently readonly.
(Inherited from Control.)
Public methodIsStyle
Check if a style value has been set for the control
(Inherited from Control.)
Public methodIsVisible
Report if this control is visible (completely or partially) or hidden.
(Inherited from Control.)
Public methodKeyDown
Provide a method that is invoked when the control has focus and a key on the keyboard is pressed.

(Inherited from Control.)
Public methodKeyUp
Provide a method that is invoked when the control has focus and a key on the keyboard is released.

(Inherited from Control.)
Public methodLinkDF
Connect a control to a data field in a data server.
(Inherited from Control.)
Public methodMenuInit
Provide a method that is invoked when a pop-up menu owned by the control is about to pop up.
(Inherited from Control.)
Public methodMenuSelect
Provide a method that is invoked when an item on a menu owned by the control is highlighted.
(Inherited from Control.)
Public methodMouseButtonDoubleClick
Provide a method that is invoked when the control has focus, the mouse pointer is positioned over the window, and a mouse button is double-clicked.

(Inherited from Control.)
Public methodMouseButtonDown
Provide a method that is invoked when the control has focus, the mouse pointer is positioned over the window, and a mouse button is clicked.

(Inherited from Control.)
Public methodMouseButtonUp
Provide a method that is invoked when the control has focus, the mouse pointer is positioned over the window, and a mouse button is released.
(Inherited from Control.)
Public methodMouseDrag
Provide a method that is invoked when the control has focus and a mouse with one or more buttons clicked is moved in the window.
(Inherited from Control.)
Public methodMouseMove
Provide a method that is invoked when the control has focus and the mouse is moved in the control.
(Inherited from Control.)
Public methodMove
Provide a method that is invoked when the control has focus and the control is moved (either by the user or by the application).
(Inherited from Control.)
Public methodOverRide
This is a compatibility method that is no longer used or needed.
(Inherited from Control.)
Public methodPerformValidations
Perform all the validations defined to this control's field specification (for example, required, maximum and minimum digits, maximum and minimum value, validation rule) and return the result of the test.
(Inherited from Control.)
Public methodPressItem
Press a button.
Public methodRegisterTimer
Register a timer method to be invoked for the control.
(Inherited from Control.)
Public methodRemoveTipText
Remove the current tip text for a button.
Public methodRePaint
Send an ExposeEvent to repaint the control
(Inherited from Control.)
Public methodResize
Provide a method that is invoked when the control has focus and the control changes size.
(Inherited from Control.)
Public methodRestoreUpdate
Resume all drawing updates for a control (after Control:SuspendUpdate() is called).
(Inherited from Control.)
Public methodSetExStyle
Set the exstyle for the control.
(Inherited from Control.)
Public methodSetFocus
Pass input focus to a control, thereby directing all mouse and keyboard input to the control.
(Inherited from Control.)
Public methodSetImageList
Sets the ImageList to be used by the ToolBar.
Public methodSetParent
Change the parent handle for the control.
(Inherited from Control.)
Public methodSetStyle
Set the style for the control.
(Inherited from Control.)
Public methodShow
Display a toolbar so it is visible.
(Overrides Show.)
Public methodShowItem
Show a button.
Public methodSuspendUpdate
Temporarily suspend all drawing updates for a control; drawing resumes with a call to Control:RestoreUpdate().
(Inherited from Control.)
Public methodTimer
Provide a method to be invoked at specific intervals defined when the timer is registered though the RegisterTimer() method.
(Inherited from Control.)
Public methodUnClickItem
Make a button look like it is "clicked-out" (returned to its normal state) after it has been "clicked-in" to indicate that it has been selected.
Public methodUnDimItem
Undim a button.
Public methodUnPressItem
Unpress a button.
Public methodUpdate
This method is no longer supported. It is included only for compatibility with existing X#1.0 code.
Public methodValidateControl
This method validates if the control has been created and when not then it triggers the control creation
(Inherited from Control.)
Public methodVerticalScroll
Provide a method that is invoked when the control has focus and a vertical scroll bar is scrolled.
(Inherited from Control.)
Top
Fields
  NameDescription
Public fieldDivider
Public fieldEventReturnValue (Inherited from Control.)
Public fieldoCargo
Cargo slot.
(Inherited from VObject.)
Top
Remarks
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.
X#
1METHOD Init(oWOwner) CLASS MyWindow
2...
3SELF:Menu := MyMenu{}
4...
5METHOD Init() CLASS MyMenu
6...
7SELF:ToolBar := ToolBar{}
(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.
Tip Tip
This is not necessarily the window that owns the toolbar or menu.
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.
Examples
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.
See Also

Reference