Class UIItem

public class UIItem extends UIStatic
{
  // Fields
  static public final int ABOVE;
  static public final int FIRSTLINE;
  static public final int ONLEFT;

  // Constructors
  public UIItem();
  public UIItem(Image image, String text);
  public UIItem(Image image, String text, int style);
  public UIItem(Image image, String text, int style, int imagePos);

  // Methods
  public int getGap();
  public Image getImage();
  public int getImagePos();
  public Dimension getPreferredSize();
  public int getRoleCode();
  public boolean imageUpdate(Image image, int flags, int x, int y,
        int width, int height);
  public void paint(FxGraphics g, Rectangle rect);
  public void setFocused(boolean on);
  public void setGap(int gap);
  public void setHot(boolean on);
  public void setImage(Image image);
  public void setImagePos(int imagePos);
  public void setName(String text);
  public void setSelected(boolean on);
}

This class implements a static item control that displays both a graphical image and text. Typically, a UIItem object is used to display information on another control, such as a button. When you create a UIItem object, you specify the image and text, as well as an optional alignment, style, and image position. The image position identifies where the image will be positioned relative to the text. By default, UIItem uses a gap of 2 pixels between the image and text.

The following example shows how to use UIItem to create another object.

// Construct a push button that uses UIItem to
// display the image stored in the variable myImage,
// and the text "Push Button." Left-align the content
// and let the image lie above the text.
UIPushButton p = 
   new UIPushButton(new UIItem(myImage, "Push Button", 
                               UIStatic.LEFT, UIItem.ABOVE));
add(p);  // Add p to the container.

In addition to using UIItem, you can use UIText and UIGraphic to create other static objects.

UIItem overrides the paint method to draw the associated text string according to the control's current states. For example, if the control is hot-tracked, the text changes colors when the mouse enters the control; the color is restored when the mouse exits. If the control is currently selected, the text is white on a dark background. Whenever the state of the control changes, paint is called to redraw the control.

Note UIItem and UIText handle the display of text in a similar manner. For more information about hot-tracked controls, see the UIText overview.

The hot-track color is the same color as the button text color. As a result, hot-tracking does not appear to be functional.

UIComponent
  |
  +--UIStateComponent
    |
    +--UICanvas
      |
      +--UIStatic
        |
        +--UIItem

Constructors

UIItem

public UIItem();

Creates a static item control with no image or text.

UIItem

public UIItem(Image image, String text);

Creates a static item control with the specified image and text.

Parameter	Description
image	The image to be displayed within the control.
text	The text to be displayed within the control.

Remarks:

By default, the image and text are aligned both horizontally and vertically. The image is positioned to the left of the text, with a gap of 2 pixels between the image and text.

UIItem

public UIItem(Image image, String text, int style);

Creates a static item control with the specified image, text, and style.

Parameter	Description
image	The image to be displayed within the control.
text	The text to be displayed within the control.
style	The alignment and style of the control. You can pass any bitwise combination of an alignment flag and a style flag. For a list of possible flags, see the UIStatic.setFlags method.

Remarks:

By default, the image is positioned to the left of the text, with a gap of 2 pixels between the image and text. If a vertical alignment is not specified, VCENTER is used (by default). Similarly, if a horizontal alignment is not specified, HCENTER is used.

Exceptions:

IllegalArgumentException if more than one vertical alignment, more than one horizontal alignment, or an undefined style was specified.

UIItem

public UIItem(Image image, String text, int style, int imagePos);

Creates a static item control using the specified image and text, with the specified alignment, style, and image position.

Parameter	Description
image	The image to be displayed within the control.
text	The text to be displayed within the control.
style	The alignment and style of the control. You can pass any bitwise combination of an alignment flag and a style flag. For a list of possible flags, see the UIStatic.setFlags method.
imagePos	The position of the image relative to the text. Possible values include ONLEFT, ABOVE, or FIRSTLINE.

Remarks:

By default, a gap of 2 pixels is used between the image and text. If a vertical alignment is not specified, VCENTER is used (by default). Similarly, if a horizontal alignment is not specified, HCENTER is used.

Exceptions:

IllegalArgumentException if more than one vertical alignment, more than one horizontal alignment, or an undefined style or image position was specified.

Methods

getGap

public int getGap();

Retrieves the size of the gap (in pixels) between the control's image and text.

Return Value:

Returns the number of pixels in the gap.

Remarks:

If the image is positioned above the text, the gap is the vertical space between the image and text. Otherwise, the gap is the horizontal space between the image and text.

See Also: setGap

getImage

public Image getImage();

Retrieves the control's image.

Return Value:

Returns the Image object displayed within the control.

See Also: setImage

getImagePos

public int getImagePos();

Retrieves the position of the control's image relative to the text.

Return Value:

Returns the current image position. Possible values include ONLEFT, ABOVE, or FIRSTLINE.

See Also: setImagePos

getPreferredSize

public Dimension getPreferredSize();

Retrieves the preferred size (in pixels) of the static item control.

Return Value:

Returns a Dimension object containing the preferred size.

Remarks:

If the image lies above the text, the height of the returned Dimension object is the sum of the image's height, the text's height, and the current gap. The Dimension object's width is the larger of the image's width and the text's width.

Conversely, if the image does not lie above the text, the Dimension object's width is the sum of the image's width, the text's width, and the current gap. The height is the larger of the image's and text's height (whichever is greater).

getRoleCode

public int getRoleCode();

Retrieves the ROLE_SYSTEM code that best describes the role of the control.

Return Value:

Returns the ROLE_SYSTEM_GRAPHIC code.

imageUpdate

public boolean imageUpdate(Image image, int flags, int x, int y, int width,
        int height);

Called to incrementally draw the control's image as the image bits become available.

Return Value:

Returns true if more information is needed to draw the full image; otherwise, returns false.

Parameter	Description
image	The control's image.
flags	The flags that specify the status of the image being loaded. You can pass any bitwise combination of the fields defined in the ImageObserver interface.
x	The x coordinate of the image.
y	The y coordinate of the image.
width	The width of the image.
height	The height of the image.

paint

public void paint(FxGraphics g, Rectangle rect);

Draws the control's image and text. This method is called by paint(FxGraphics g), inherited through UIStatic.

Return Value:

No return value.

Parameter	Description
g	The graphics context.
rect	The rectangle to draw the control's image and text in.

Remarks:

This method checks the current image position and gap, and draws the image and text accordingly.

Overrides:

paint(FxGraphics,Rectangle) in UIStatic.

setFocused

public void setFocused(boolean on);

Sets or clears the focus state of the static item control.

Return Value:

No return value.

Parameter	Description
on	If true, the focus state is set; otherwise, it is cleared.

Remarks:

This method redraws the control to update the text according to the new state. For more information, see the UIItem overview.

setGap

public void setGap(int gap);

Sets the size of the gap (in pixels) between the control's image and text.

Return Value:

No return value.

Parameter	Description
gap	The number of pixels for the gap.

Remarks:

If the image is positioned above the text, the gap is the vertical space between the image and text. Otherwise, the gap is the horizontal space between the image and text.

See Also: getGap

setHot

public void setHot(boolean on);

Sets or clears the hot-tracked state of the static item control.

Return Value:

No return value.

Parameter	Description
on	If true, the hot-tracked state is set; otherwise, it is cleared.

Remarks:

This method redraws the control to update the text according to the new state. The control must have the HOTTRACK style for the hot-tracked state to be set or cleared. For more information about hot-tracking, see the UIItem overview.

Overrides:

setHot(boolean) in UIStatic.

setImage

public void setImage(Image image);

Sets the control's image.

Return Value:

No return value.

Parameter	Description
image	The image to be displayed within the control.

See Also: getImage

setImagePos

public void setImagePos(int imagePos);

Sets the position of the control's image relative to the text.

Return Value:

No return value.

Parameter	Description
imagePos	The position of the image. Possible values include ONLEFT, ABOVE, or FIRSTLINE.

Exceptions:

IllegalArgumentException if an undefined position was specified.

See Also: getImagePos

setName

public void setName(String text);

Sets the control's text.

Return Value:

No return value.

Parameter	Description
text	The text to be displayed within the control.

Remarks:

The getName method (inherited through UICanvas) enables you to retrieve the control's current text.

setSelected

public void setSelected(boolean on);

Sets or clears the selected state of the static item control.

Return Value:

No return value.

Parameter	Description
on	If true, the selected state is set; otherwise, it is cleared.

Remarks:

This method redraws the control to update the text according to the new state. For more information about states, see the UIItem overview.

Fields

ABOVE

Specifies that the image will be positioned above the text.

FIRSTLINE

Specifies that the image will be positioned, centered vertically, on the first line of text.

ONLEFT

Specifies that the image will be positioned to the left of the text.