Xbase++ - Class XbpToolBar()

Class function of the XbpToolBar() class

The class XbpToolBar implements an Xbase Part that can be used to provide users with quick access to certain commands of the application. An instance of the XbpToolBar class displays buttons that can be selected with the mouse. A tool bar button is similar to a push button in its behaviour and represents one application tool or command. If a button is activated, the command associated with the button is executed. Tool bar objects generally define buttons for a sub-set of the commands available through the application's menus.

Using the XbpToolBar Xbase Part

An instance of the XbpToolBar class is created by calling its :new() method followed by :create(). After the object is created, an application uses the object's instance variables and methods to add or remove tool bar buttons. Each button can have its own caption and/or image associated with it. Tool bar buttons may also serve as a container for other Xbase Parts, such as an XbpCombobox. A button is added to an XbpToolBar instance by calling the tool bar's :addItem() method.

If a tool bar button is selected by the user, an event is generated. This allows the application to respond by activating the function associated with the button selected.

Usage in MDI applications

In so-called MDI applications, one or more child or document windows can be displayed within the main window of the application. MDI applications are created by making the XbpDialog objects representing the child windows a child of the :drawingArea of the main window. Afterwards, the child windows can moved freely within the drawing area of the main window. The child dialogs overlap each other as well as all other childs defined in the :drawingArea of the main window. This is to be taken into account when using the XbpToolBar class within the main window of an MDI application. In this case, the tool bar often visualizes global application commands and hence should be visible at all times. In order to prevent the tool bar from being hidden by overlapping child dialogs, the tool bar should be created as a child of the main window (XbpDialog), and not as a child of the main window's drawing area. Also, the dimension of the drawing area must be reduced by the height of the tool bar, and the position must be adjusted accordingly.

To function properly, the XbpToolBar class requires a certain system component, the Microsoft Common Controls Version 6.0, to be installed on your computer. Normally, this component is not installed with the operating system, so provisions must be taken to distribute the component with your Xbase++ application. An installation package with the required system files for using the XbpToolBar Xbase Part is available from Alaska Software. The corresponding archive should be located on your Xbase++ disk or CD ROM. For further information, please click the 'Info' button on this page.

Creates an instance of the XbpToolBar class.

Requests system resources for the XbpToolBar object.

Reconfigures the XbpToolBar object after :create() has been executed.

Releases the system resources of the object.

Unless documented otherwise, the instance variables in the following section can only be used after method :create() was called.

Specifies whether the user can customize the XbpToolBar object.

Controls general appearance of an XbpToolBar object.

Specifies whether a border should be drawn around the XbpToolBar object.

Specifies the height of the tool bar buttons defined in an XbpToolBar object.

Specifies the width of the tool bar buttons defined in an XbpToolBar object.

Specifies whether the XbpToolBar object is enabled.

Specifies the height of the images displayed in the buttons defined in a XbpToolBar object.

Specifies the width of the images displayed in the buttons defined in a XbpToolBar object.

Specifies whether tooltips should be displayed by the XbpToolBar object.

Controls the appearance of an XbpToolBar object.

Controls alignment of the caption strings displayed by the buttons defined in a XbpToolBar object.

Specifies the transparent color to be used when drawing toolbar button images.

Specifies whether tool bar buttons may be wrapped when the XbpToolBar object is resized.

Adds a tool bar item (button) to the XbpToolBar object.

Removes all tool bar items (buttons) defined for a XbpToolBar object.

Display a dialog for customizing a XbpToolBar object at run time.

Removes an item (button) from the XbpToolBar object.

Retrieves an item (button) from the XbpToolBar object's item array.

Loads a set of pre-defined standard images for usage with tool bar buttons.

Returns the number of tool bar items (buttons) defined for an XbpToolBar object.

Restores a XbpToolBar object's button arrangement previously saved.

Saves the XbpToolBar object's current button arrangement.

Changes position and size of the Xbase Part.

Changes the size of the Xbase Part.

A tool bar button has been clicked with the mouse.

A tool bar button's menu has been dropped down.

One of the items defined in the menu defined by a tool bar button has been selected.

The XbpToolBar object has been customized.

Example for using the XbpToolBar Xbase Part


 // 
 // Example for using the XbpToolBar Xbase Part. 
 // The example creates a tool bar object with 
 // two tool buttons. Furthermore, it uses a 
 // callback code block to respond to mouse 
 // clicks on the toolbar's buttons. 
 // 
 #include "XBP.CH" 
 #include "GRA.CH" 
 #include "AppEvent.CH" 

 PROCEDURE Main() 
  LOCAL oDlg 
  LOCAL oTBar 
  LOCAL nEvent, mp1, mp2, oXbp 
  LOCAL oButton 
  LOCAL oDA 

   // 
   // Create application's main dialog 
   // 
   oDlg := XbpDialog():new( Appdesktop() ) 
   oDlg:title 	  := "Toolbar Example" 
   oDlg:taskList := .T. 
   oDlg:close    := {|| PostAppEvent(xbeP_Quit,,, oDlg) } 
   oDA           := oDlg:drawingArea 
   oDlg:create( ,, {50,50}, {640,480},, .F. ) 

   oDA:resize    := {|| ResizeToolbar(oTBar)} 

   // 
   // Create an XbpToolBar object and 
   // add it at the top of the dialog 
   // 
   oTBar         := XbpToolBar():new( oDA ) 
   oTBar:create( ,, {0,oDA:currentSize()[2]-60}, ; 
                    {oDA:currentSize()[1],60} ) 
   // 
   // Add two tool bar buttons, each with a 
   // caption and an image. Constrict the 
   // button image sizes to 32 pixels and 
   // ensure transparency is turned off. 
   // 
   oTBar:imageWidth  := 32 
   oTBar:imageHeight := 32 
   oTBar:addItem("Button #1", 100) 
   oTBar:addItem("Button #2", 101) 
   oTBar:transparentColor := GRA_CLR_INVALID 

   oTBar:buttonClick := {|oButton| MsgBox("Button [" + ; 
                                     oButton:caption + ; 
                                     "] clicked!")} 
   // 
   // Display the main dialog and process 
   // application events until the dialog 
   // is closed 
   // 
   oDlg:show() 

   SetAppWindow( oDlg ) 
   SetAppFocus( oDlg ) 

   nEvent := xbeP_Quit 
   DO WHILE nEvent != xbeP_Close 
     nEvent := AppEvent( @mp1, @mp2, @oXbp ) 
     oXbp:handleEvent( nEvent, mp1, mp2 ) 
   ENDDO 

   oDlg:destroy() 
 RETURN 

 // Resize XbpToolBar object to always span the 
 // whole width of the dialog's drawing area. 
 // Also, the object is always kept at the top 
 // of the dialog's display area 
 PROCEDURE ResizeToolbar( oTBar ) 
   LOCAL oParent 
   LOCAL aPos   
   LOCAL aSize  

     IF GetParentForm(oTBar):getFrameState() == ; 
        XBPDLG_FRAMESTAT_MINIMIZED 
        RETURN 
     ENDIF 

     oParent := oTBar:setParent() 
     aPos    := oTBar:currentPos() 
     aSize   := oTBar:currentSize() 

     oTBar:setPosAndSize( {aPos[1],oParent:currentSize()[2]-aSize[2]},; 
                          {oParent:currentSize()[1],aSize[2]} ) 
 RETURN 

 // Overloaded AppSys() procedure to prevent 
 // creation of the default XbpCrt window 
 PROCEDURE AppSys() 
 RETURN 


 // Use this ARC file to define the image resource. 
 // Compile with ARC and link the .RES-file to the 
 // .EXE 
 #ifdef __ARC__ 
  BITMAP 
    100 = FILE "Tile5.bmp" 
    101 = FILE "Tile7.bmp" 
 #endif

If you see anything in the documentation that is not correct, does not match your experience with the particular feature or requires further clarification, please use this form to report a documentation issue.

Class XbpToolBar() Foundation