Xbase++ - Method XbpStatusBar():addItem()

Adds a status bar item (panel) to the XbpStatusBar object.

:addItem( [<cCaption>], [<xImage>], [<cDLL>], [<nStyle>], [<cKey>] ) => <oPanel>

<cCaption> is a character string that specifies the caption to be displayed by the status bar panel after it is added. This parameter is optional. If one of the pre-defined panel styles is specified in <nStyle>, parameter <cCaption> is ignored. See below for further information.

The parameter <xImage> specifies the image to be displayed by the statusbar item (panel) to be added. The image may be specified by passing a numeric value with the resource ID of a BITMAP resource. Alternatively, an instance of the XbpBitmap or XbpIcon classes may be used. If an image is defined using parameter <xImage>, it is displayed next to the caption string.

<cDLL>

<cDLL> is an optional character string that can be used to specify the name of a Dynamic Link Library (DLL). This parameter is only used if the resource ID of an image is specified in parameter <xImage>. In this case, the XbpStatusBar object attempts to load the image resource from the DLL file passed in <cDLL> instead of the application's main module (.EXE). If no image is specified or if it is specified using an XbpBitmap or XbpIcon object, parameter <cDLL> is ignored.

Parameter <nStyle> is a numeric value that defines the style of the status bar item to be added. This parameter is optional. If omitted, the default style for status bar panels is used.

<cKey>

Parameter <cKey> is an optional character string that specifies a key string to be assigned to the status bar item (panel) to be added. If a key string is passed in parameter <cKey>, it can later be used to address the status bar panel, eg. for changing its caption string. Key strings must be unique within the array of status bar items. If a duplicate key string is passed in parameter <cKey>, a runtime error occurs.

The method :addItem() returns a reference to the XbpStatusBarPanel() object added to the status bar item array.

The method :addItem() is used to add a new status bar panel to the XbpStatusBar object. Status bar panels are used to divide the display area into separate sections, each displaying different kinds of status information. One status bar panel is automatically defined when method :create() is called to create an XbpStatusBar instance. Additional panels can later be added by the application via method :addItem().

Each status bar panel can optionally display its own status message and image. Also, several pre-defined status bar panel styles exist, which can be selected by specifying one of following constants in parameter <nStyle>:

Constant	Description
XBPSTATUSBAR_PANEL_TEXT *)	Panel displays status text
XBPSTATUSBAR_PANEL_CAPSLOCK	Panel displays status of CAPSLOCK key
XBPSTATUSBAR_PANEL_NUMLOCK	Panel displays status of NUMLOCK key
XBPSTATUSBAR_PANEL_INSERT	Panel displays status of INSERT key
XBPSTATUSBAR_PANEL_SCROLL	Panel displays status of SCROLL LOCK key
XBPSTATUSBAR_PANEL_TIME	Panel displays current time
XBPSTATUSBAR_PANEL_DATE	Panel displays current date
Default panel style

In addition to the status or key state displayed, a panel added to an XbpStatusBar object can also display an application-defined image. The image must be specified using parameter <xImage> when a new panel is added using :addItem(). The image may be defined in the resource linked to the application, a Dynamic Link Library (DLL) or may be loaded from disk using an object of the XbpBitmap() or XbpIcon() classes.

After the XbpStatusBar object is configured, the items defined in the internal array of status bar panels can be retrieved using method :getItem(). For easier access and better readability of the source code, a unique identifier may be assigned to each panel added using method :addItem(). The key must be specified as a character string in parameter <cKey>.

// 
// Example for using :addItem() to add a panel 
// to an XbpStatusBar object 
// 
#include "XBP.CH" 

PROCEDURE Main() 
  LOCAL oSBar 
  LOCAL oPanel 

    // Create the XbpStatusBar object 
    oSBar := XbpStatusBar():new() 
    oSBar:create( ,, {0,0}, {SetAppWindow():currentSize()[1],30} ) 

    // Add a new status bar panel and assign it 
    // a unique identifier 
    oSBar:addItem( ,,,, "TXTPANEL" ) 

    // Use :getItem() to retrieve a reference 
    // to the panel just added. Use this to 
    // change the caption text and the 
    // panel's size. 
    oPanel := oSBar:getItem( "TXTPANEL" ) 
    oPanel:caption  := "Test Status Text" 
    oPanel:autoSize := XBPSTATUSBAR_AUTOSIZE_CONTENTS 

    WAIT 
 RETURN

Method XbpStatusBar():addItem() Foundation