net.rim.blackberry.api.homescreen
Class ShortcutIconField

java.lang.Object
  net.rim.device.api.ui.Field
      net.rim.blackberry.api.homescreen.ShortcutIconField

public abstract class ShortcutIconField
extends Field

Provides the ability to add a shortcut to a UI screen. For example, you can use this field to provide users a preview of how the shortcut will appear on the Home screen.

To create an instance of ShortcutIconField, use create(). This creates a Field which looks like the shortcut as it would appear on the Home screen with the specified parameters.

Use setIcon() to change the normal state icon. Use setRollOverIcon() to change the roll over icon (same as focus icon). Use setDescription() to change the description.

Category:

Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.

Since:

BlackBerry API 6.0.0

Field Summary

Fields inherited from class net.rim.device.api.ui.Field

ACTION_INVOKE, AXIS_HORIZONTAL, AXIS_SEQUENTIAL, AXIS_VERTICAL, EDITABLE, EDITABLE_MASK, FIELD_BOTTOM, FIELD_HALIGN_MASK, FIELD_HCENTER, FIELD_LEADING, FIELD_LEFT, FIELD_RIGHT, FIELD_TOP, FIELD_TRAILING, FIELD_VALIGN_MASK, FIELD_VCENTER, FOCUSABLE, FOCUSABLE_MASK, HIGHLIGHT_FOCUS, HIGHLIGHT_SELECT, NON_FOCUSABLE, NON_SPELLCHECKABLE, READONLY, SPELLCHECKABLE, SPELLCHECKABLE_MASK, STATUS_MOVE_FOCUS_HORIZONTALLY, STATUS_MOVE_FOCUS_VERTICALLY, USE_ALL_HEIGHT, USE_ALL_WIDTH, VISUAL_STATE_ACTIVE, VISUAL_STATE_DISABLED, VISUAL_STATE_DISABLED_FOCUS, VISUAL_STATE_FOCUS, VISUAL_STATE_NORMAL

Method Summary
	static ShortcutIconField	create(EncodedImage icon, EncodedImage focusIcon, String description) Creates an instance of ShortcutIconField with the given parameters.
	abstract void	setDescription(String description) Specifies the description of the shortcut.
	abstract void	setIcon(EncodedImage icon) Specifies the icon (normal state) to associate with this ShortcutIconField.
	abstract void	setRollOverIcon(EncodedImage focusIcon) Sets the focus state icon associated with this ShortcutIconField.

Methods inherited from class net.rim.device.api.ui.Field

drawFocus, drawHighlightRegion, fieldChangeNotify, focusAdd, focusRemove, getAccessibleContext, getBackground, getBackground, getBorder, getBorder, getBorder, getChangeListener, getCommandItemProvider, getContentHeight, getContentLeft, getContentRect, getContentRect, getContentTop, getContentWidth, getContextMenu, getCookie, getExtent, getExtent, getFieldStyle, getFocusListener, getFocusRect, getFont, getHeight, getIndex, getLeafFieldWithFocus, getLeft, getManager, getMargin, getMarginBottom, getMarginLeft, getMarginRight, getMarginTop, getOriginal, getPadding, getPaddingBottom, getPaddingLeft, getPaddingRight, getPaddingTop, getPreferredHeight, getPreferredWidth, getScreen, getStyle, getTop, getVisualState, getWidth, invalidate, invalidate, invalidateAll, invokeAction, isDataValid, isDirty, isEditable, isEnabled, isFocus, isFocusable, isMuddy, isPasteable, isScrollCopyable, isSelectable, isSelecting, isSelectionCopyable, isSelectionCutable, isSelectionDeleteable, isSpellCheckable, isStyle, isVisible, keyChar, keyControl, keyDown, keyRepeat, keyStatus, keyUp, layout, makeContextMenu, moveFocus, moveFocus, navigationClick, navigationMovement, navigationUnclick, onDisplay, onExposed, onFocus, onMenuDismissed, onMenuDismissed, onObscured, onUndisplay, onUnfocus, onVisibilityChange, paint, paste, select, selectionCopy, selectionCut, selectionDelete, setBackground, setBackground, setBorder, setBorder, setBorder, setBorder, setChangeListener, setCommandItemProvider, setCookie, setDirty, setEditable, setEnabled, setExtent, setFocus, setFocusListener, setFont, setMargin, setMargin, setMuddy, setNonSpellCheckable, setPadding, setPadding, setPosition, setVisualState, touchEvent, trackwheelClick, trackwheelUnclick, updateLayout

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Detail

create

public static ShortcutIconField create(EncodedImage icon,
                                       EncodedImage focusIcon,
                                       String description)

Creates an instance of ShortcutIconField with the given parameters.

Parameters:

icon - The icon (normal state) to associate with this shortcut.

focusIcon - The focus state icon to associate with this shortcut.

description - The description of the shortcut. The description displays when the shortcut is in focus.

Returns:

Instance of ShortcutIconField.

Category:

Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.

Since:

BlackBerry API 6.0.0

setIcon

public abstract void setIcon(EncodedImage icon)

Specifies the icon (normal state) to associate with this ShortcutIconField. If the icon is smaller or larger than the size preferred by the active theme, it might be resized to match other icons on the Home screen. If the icon is null, then the default application icon is used.

Parameters:

icon - EncodedImage to be used for normal state.

See Also:

HomeScreen.getPreferredIconHeight(), HomeScreen.getPreferredIconWidth()

Category:

Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.

Since:

BlackBerry API 6.0.0

setRollOverIcon

public abstract void setRollOverIcon(EncodedImage focusIcon)

Sets the focus state icon associated with this ShortcutIconField. If the icon is smaller or larger than the preferred icon size it may be resized to match other icons on the Home screen. If focusIcon is null, then the normal state icon is used. If the normal state icon is null, then the default application icon is used.

Parameters:

focusIcon - EncodedImage to be used for focus state.

See Also:

HomeScreen.getPreferredIconHeight(), HomeScreen.getPreferredIconWidth()

Category:

Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.

Since:

BlackBerry API 6.0.0

setDescription

public abstract void setDescription(String description)

Specifies the description of the shortcut. The description displays when the shortcut is in focus.

Parameters:

description - Display name of the shortcut.

Throws:

IllegalArgumentException - if the description is null, an empty String, or white space.

Category:

Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.

Since:

BlackBerry API 6.0.0