piIconId - cCJAction

A unique Id used to identify an image in the imagelist. Can be used to dynamically assign images to an action

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

piIconId is a unique ID that is used to identify an image in the imagelist. You will normally not set this value yourself. When the value is 0, the icon ID will be the assigned the same ID as the action ID (piID). The piID value is also normally not set - it is auto assigned.

The default value is 0 - which means that the action's piID value is used.

You will normally use psImage, psImageDisabled, psImageHot, psImageChecked and psImagePressed to assign images to an action. These properties are all design-time properties. After the commandbar system has been created, changing these properties will not change the item's image.

You can use piIconId when you need to dynamically change images. You must first add the image to your imagelist using the cCJCommandBarSystem's AddImage or AddImageType methods. If you have done this, you would bind the action to this image by setting piIconId.

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 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 action'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 zero or 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 add the images. 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 toolbar item will change the caption and image. This is not particularly useful, but it shows how images may be changed dynamically.

Object oFlip is a cCJMenuItem

    Set psCaption to "Add"
    Set psImage to "ActionSave.ico"
    Set peControlStyle to xtpButtonIconAndCaption

    // when pressed change the text and change the icon.
    Procedure OnExecute Variant vCommandBarControl
        String sCap
        Get psCaption to sCap

        If (sCap="Add") Begin
            Set psCaption to "Del"
            Set piIconId to idImgDelete 
        End
        Else Begin
            Set psCaption to "Add"
            // setting this to 0 makes it use the psImage.
            Set piIconId to 0

            // another way to do the same thing, is to assign the Id to the piId
            //Get piId to iId
            //Set piIconId to iId

            // alternately, we could assign it to some other image
            //Set piIconId to idImgClear 

        End
    End_Procedure
End_Object

Sample 2

This example shows how you could use piIconId in place of psImage. One big disadvantage of this is that the images will not be visually modeled in the studio. The Studio assumes that piIconID is a runtime property.

This sample assumes that you have defined these images using AddImage as shown above.

Object oSave is a cCJMenuItem
    :
    Set piIconId to idImgSave   
    :
End_Object

Object oDelete is a cCJMenuItem
    :
    Set piIconId to idImgDelete
    :
End_Object

Object oClear is a cCJMenuItem
    :
    Set piIconId to idImgClear
    :
End_Object

Image Mask Color

The image mask color determines how the various image states (normal, disabled, hot, etc.) are rendered. This data is provided in icon files. With bitmap files this color is determined by using the image's top left corner.