Using Gadget Items
This section covers the following topics:
Creating a Gadget Item
A gadget item can be represented by a label, a picture, or both. The picture can be a bitmap or a graphic object. See Setting a Label and Setting a Picture.
You define the way a gadget item appears when you create it. Here are a few examples:
item1 = new IlvGadgetItem("Item1"); // Creates an item with only a label.
item2 = new IlvGadgetItem("Item2", // Creates an item with a label
bitmap); // and a bitmap.
item3 = new IlvGadgetItem(bitmap); // Creates an item with a bitmap.
item4 = new IlvGadgetItem("Item 4", // Creates an item with a label
graphic); // and an IlvGraphic.
item5 = new IlvGadgetItem(graphic); // Creates an item with an IlvGraphic.
Setting a Label
A gadget item can be represented by a label. To associate a label with a gadget item, use the member function setLabel.
When a gadget item label extends over several lines, you can use setLabelAlignment to specify whether the text should be aligned right, left, or be centered.
Message Labels with Various Alignments
Using the member function setLabelOrientation, you can also specify whether a gadget item label should be drawnhorizontally (the default) or vertically.
Message Labels Displayed Vertically
Setting a Picture
A gadget item can include either an IlvBitmap or an IlvGraphic object. The following sections explain how gadget items handle these objects.
IlvBitmap Used as a Picture
A gadget item manages an array of bitmaps. Each bitmap in the array can be accessed by means of an index or a symbol name. You can retrieve the bitmap displayed by a gadget item from its bitmap array using getCurrentBitmap. This member function determines the displayed bitmap from the state of the gadget item. For example, if the gadget item is selected, the bitmap corresponding to the “selected” state is returned.
Below are the symbol names associated with the various gadget item states a bitmap can represent:
IlvGadgetItem::BitmapSymbol(); Sensitive state
IlvGadgetItem::SelectedBitmapSymbol(); Selected state
IlvGadgetItem::InsensitiveBitmapSymbol(); Nonsensitive state
IlvGadgetItem::HighlightedBitmapSymbol(); Highlighted state
To know how many bitmaps are associated with a gadget item, call the method getBitmapCount.
To set the bitmap that will be displayed by the gadget item when it is selected, call:
item->setBitmap(IlvGadgetItem::SelectedBitmapSymbol(), bitmap);
To retrieve the bitmap that is displayed when the gadget item is set to nonsensitive, call:
IlvBitmap* bitmap = item->getBitmap(IlvGadgetItem::InsensitiveBitmapSymbol());
IlvGraphic Used as a Picture
A gadget item can be represented by an IlvGraphic object. Use the member function setGraphic to associate a gadget item with a graphic object.
Specifying the Layout of a Gadget Item
You can define the position of a gadget item label relative to its picture using the member function setLabelPosition. For example, to place the label under the picture, call:
item->setLabelPosition(IlvBottom);
You can also fix the spacing between the label and the picture with setSpacing. For example, to set the spacing to 10 pixels, call:
A gadget item can be any size. Its dimensions are automatically computed from its label, its picture, the label position, and the spacing between the label and the picture. To retrieve the size of a gadget item, use the following methods:
IlvDim width = item->getWidth();
IlvDim height = item->getHeight();
| Note
The width and height of a gadget item should not exceed 65535 pixels. The member functions getWidth and getHeight return 0 if the item is not managed by a gadget. |
To know the position of a label and a picture inside a gadget item, use the following member functions:
item->labelRect(rect, itembbox);// Puts the label bounding box of the item
// in rect when the item is drawn in itembbox.
item->pictureRect(rect, itembbox); // Puts the picture bounding box of the item
//in rect when the item is drawn in itembbox.
You can show or hide either the label or the picture that makes up a gadget item. To hide a gadget item label, use showLabel with its parameter set to IlFalse. If the gadget item contains no picture, it becomes invisible.
To make the picture visible, use the showPicture method with its parameter set to IlTrue.
Nonsensitive Gadget Items
By default, gadget items are sensitive, which means that they respond to user events. Calling the member function setSensitive with IlFalse as parameter lets you set a gadget item to nonsensitive. In this case, the gadget item appears dimmed on the screen and cannot be selected.
If only a sensitive bitmap is provided, the insensitive bitmap is computed automatically. If a nonsensitive bitmap is provided, this bitmap is used.
