piIconId - cCJStatusBarPane

Can be used to select a different statusbar pane image at runtime

Type: Property
Access: Read/Write
Data Type: Integer
Parameters: None

Syntax

Property Integer piIconId

Access Type	Syntax
Read Access:	Get piIconId to IntegerVariable
Write Access:	Set piIconId to IntegerVariable/Value

Description

Normally an image is assigned to a statusbar pane by setting the design-time psImage property. This image is applied to statusbar pane when it is displayed. In such a case, piIconId is zero and is not used.

If piIconId is non-zero when the pane was displayed it would show the image associated with this ID.

If you need to change the image after the pane has been displayed, you must change it by setting the piIconId property. If you set piIconId to zero after the pane has been displayed, the image will be cleared.

Image ID Assignment

Each image in the commandbar system's imagelist is identified by a numeric ID. Normally, this process is automatic and you do not need to worry about it. When you are assigning your image IDs manually you need to know how to assign the IDs and what the ID of the Image added via psImage was.

When an Image is added using psImage, the ID is the same as the status pane's piID. Therefore if you need to reset an image using piID back to the original image, you can do this by setting piIconId to piID.

If you adding images to the imagelist manually, you can assign your own IDs.

The only restriction placed on these IDs is that we suggest they fall in the range of 1 to 4999.

The following example shows how you could add your own images to the imagelist. Normally, this should be done within the cCJCommandBarSystem object's OnCreateCommandBars event using the AddImage message.

// First you must assign IDs for the images

Define idImgSave for 100
Define idImgDelete for 101
Define idImgClear for 102
:

// next you add the images withn OnCreateCommandBars

Procedure OnCreateCommandBars
    Integer iId
    Get AddImage "ActionSave.ico" idImgSave   xtpImageNormal to iId
    Get AddImage "ActionDelete.ico" idImgDelete xtpImageNormal to iId
    Get AddImage "ActionClear.ico" idImgClear xtpImageNormal to iId
    : 
End_Procedure

You could also use AddImage message to auto-assign image Ids as the images are added. If the image ID passed is zero, this function auto assigns the image ID and returns its value. This has the advantage that you don't have to worry about defining the image ID constants but adds the overhead of having to keep track of the dynamically assigned IDs.

Sample 1

This simple example will show how this can be used. In this sample, clicking on the pane will display the normal psImage and double clicking will display no image. We will clear the image by setting piIconId to 0. Resetting the image requires that we know ID of the image added with psImage, which as noted above, is the pane ID, piID.

Object oStatusPane3 is a cCJStatusBarPane
    Set psImage to "ActionSave.ico"

    // click to restore the image defined with psImage
    Procedure OnClick
        Integer iId
        Get piID to iId
        Set piIconId to iId
    End_Procedure

    // double click to clear the image
    Procedure OnDblClick
        Set piIconId to 0
    End_Procedure

End_Object

Sample 2

This is a more complicated sample that shows how you can use piIconId to select any image.

First you must add the images to the cCJCommandBarSystem's image list passing with known developer assigned IDs. This must occur after the commandbar system's COM object is created. We could use the OnCreate event of the statusbar, the statusbar pane or use the OnCreateCommandBars event in the commandbar system object. We will use OnCreateCommandBars in the cCJCommandBarSystem object to do this.

// we must define the image Ids manually
Define idImgSave for 100
Define idImgDelete for 101

:

// this procedure is inside the cCJCommandBarSystem object
Procedure OnCreateCommandBars
    Integer iId
    Get AddImage "ActionSave.ico" idImgSave   xtpImageNormal to iId
    Get AddImage "ActionDelete.ico" idImgDelete xtpImageNormal to iId
End_Procedure

Once the images are added to the list, we simply choose the image we want by setting piIconId. In this object, we created a new property called pbSave. This determines whether the pane should be a save or a delete pane. Clicking on the pane changes its mode.

Object oStatusPane3 is a cCJStatusBarPane

    Property Boolean pbSave True

    Set piIconId to idImgSave
    Set psText to "Save"

    Procedure OnClick
        Boolean bSave

        // toggle the property
        Get pbSave to bSave
        Move (not(bSave)) to bSave
        Set pbSave to bSave

        // adjust the text and the image
        If bSave Begin
           Set psText to "Save"
           Set piIconId to idImgSave
        End
        Else Begin
           Set psText to "Delete"
           Set piIconId to idImgDelete
        End

        // this forces the pane to readjust its size to fit the text
        Set piWidth to 0
    End_Procedure

End_Object