net.rim.blackberry.api.homescreen
Interface Shortcut


public interface Shortcut

Interface that encapsulates a Home screen shortcut. A shortcut is an icon on the Home screen that when clicked opens the associated application with a specific context. For example, a shortcut to a contact might open the contact in the Contacts application. Other possible examples of shortcuts might include:

For more information on creating a shortcut, see the package overview.

See Also:
HomeScreen, ShortcutProvider, ShortcutEventListener
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

Method Summary
Category: Signed  void setCommandItems(CommandItem[] items)
          Sets the CommandItem of the shortcut.
Category: Signed  void setDescription(String description)
          Specifies the description of the shortcut.
Category: Signed  void setIcon(EncodedImage icon)
          Specifies the icon (normal state) to associate with this shortcut.
Category: Signed  void setIsEditable(boolean isEditable)
          Specifies the editable flag for this shortcut.
Category: Signed  void setIsFavourite(boolean isFavourite)
          Specifies whether this shortcut is a favorite.
Category: Signed  void setNewState(boolean newState)
          Specifies the state flag to indicate that there is something new for the shortcut.
Category: Signed  void setRollOverIcon(EncodedImage focusIcon)
          Specifies the focus state icon to associate with this shortcut.
Category: Signed  void setSearchable(boolean searchable)
          Specifies whether this shortcut can be a part of search results of Homescreen.
Category: Signed  void setUnreadCount(int unreadCount)
          Specifies the number of unread items associated with this shortcut.
 



Method Detail

setIcon

void setIcon(EncodedImage icon)
Specifies the icon (normal state) to associate with this shortcut. 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

void setRollOverIcon(EncodedImage focusIcon)
Specifies the focus state icon to associate with this shortcut. 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 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

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

setNewState

void setNewState(boolean newState)
Specifies the state flag to indicate that there is something new for the shortcut. When there is something new, an indicator (for example, a red asterisk) is added to the icon to indicate that there are "new" items available. The application that registers this shortcut should set and clear the state flag when there are new items and after they are read.

Parameters:
newState - If true there is something new for this shortcut; false otherwise.
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

setUnreadCount

void setUnreadCount(int unreadCount)
Specifies the number of unread items associated with this shortcut. The theme might add a visual indicator on the icon or descriptive text that includes this number. The application that registers this shortcut should update this count when there are new items and after they are read.

Parameters:
unreadCount - The number of unread items associated with this shortcut.
Throws:
IllegalArgumentException - if the unread count is negative.
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

setIsEditable

void setIsEditable(boolean isEditable)
Specifies the editable flag for this shortcut. By default shortcuts are not editable.

If true, when the shortcut is in focus, an Edit menu item is added to the menu. For example, if the shortcut is to a contact, you could use the menu item to launch the Contacts application and open the contact for editing. Your application must specify what happens when the menu item is selected. After a change, the application is notified through ShortcutEventListener.editShortcut(java.lang.String).

Parameters:
isEditable - If true then this shortcut is editable.
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

setIsFavourite

void setIsFavourite(boolean isFavourite)
Specifies whether this shortcut is a favorite. If true then it appears in the favorites view of the Home screen.

Parameters:
isFavourite - If true then the shortcut appears in favorites view of the Home screen.
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

setSearchable

void setSearchable(boolean searchable)
Specifies whether this shortcut can be a part of search results of Homescreen. If true then it can be a part of search results. Applications can specify their shortcut to be not searchable if they do not want Homescreen to provide their shortcuts as a part of search result. By default all the shortcuts are searchable. So applications have to explicitly set value to false if they do not want shortcut to be part of Homescreen search result.

Parameters:
searchable - If true then shortcut can be a part of search results of Homescreen
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

setCommandItems

void setCommandItems(CommandItem[] items)
Sets the CommandItem of the shortcut. The CommamdItem is added into displaying the popup menu for this shortcut.

Parameters:
CommandItem - Array of CommandItems for the shortcut.
Throws:
IllegalArgumentException - if the array is null.
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





Copyright 1999-2011 Research In Motion Limited. 295 Phillip Street, Waterloo, Ontario, Canada, N2L 3W8. All Rights Reserved.
Java is a trademark of Oracle America Inc. in the US and other countries.
Legal