ewe.ui
Class SoftKeyBar

java.lang.Object
  ewe.ui.SoftKeyBar

All Implemented Interfaces:

EventListener

public class SoftKeyBar

extends Object

implements EventListener

A SoftKeyBar is used on Smartphone or other such systems where general purpose hardware keys are used to control inputs to the software in a way that changes depending on the situation.

SoftKeyBars provide two types of controls - buttons which simply fire an action when the associated softkey is pressed, or menus which display a general Menu when pressed.

The SoftKeyBar is not a UI Control since it may actually be implemented using the system's native UI system - but it is fully responsible for configuring the appearance on screen and handling the softkey presses. The only thing an application has to do is to trap the events sent out by the SoftKeyBar or override the event handling of the SoftKeyBar.

Because only one SoftKeyBar can be displayed at a time, you display it by calling Window.setSoftKeyBar() on the containing Window.

Field Summary

int	barModifiersToClear
int	barModifiersToSet
static Color	defaultBackgroundColor The default background color for the soft keys.
static Font	defaultFont This is the default font.
static SoftKeyBar	empty
static boolean	hideRemovesSoftKeyBar This is false by default and if you set it true, then a hide() will cause the SoftKeyBar to disappear entirely, instead of just becoming empty - which is the default.
String	name You can use this as an identifier for bar.

Constructor Summary

SoftKeyBar()

SoftKeyBar(EventListener listener)

Method Summary

void	addListener(EventListener el)
void	addTo(SingleContainer sc)
void	clearKeys()
Menu	createMenuFor(Object obj) Create a Menu for a specific set of Objects, placed in a Vector, or a Container or an Object array.
MenuItem	createMenuItem(mButton button) Return a MenuItem that will be used as a proxy for a specific buton.
MenuItem	createMenuItem(String label, String action, IImage icon)
MenuItem	createMenuItem(String label, String action, String iconName, Object maskOrColor)
MenuItem	createMenuItemFor(Object obj) Create a MenuItem for a particular Object.
boolean	display() Display the SoftKeyBar in the global SoftKeyBar location.
static Menu	fixMenu(Menu m) Fix a Menu for use with the SoftKeyBar.
static SoftKeyBar	getDisplayed()
FontMetrics	getFontMetrics()
boolean	handleKey(KeyEvent ev)
static void	hide() Hide any visible SoftKeyBar.
protected Control	make()
static int	numberOfKeys() Returns the number of keys supported by the system.
void	onEvent(Event ev)
static boolean	onKeyEvent(KeyEvent ev)
static void	pop() Display the keybar that was displayed before the last push() call.
static void	push(SoftKeyBar skb) Display a new keybar, but save the old keybar.
void	removeListener(EventListener el)
static boolean	reveal() Reveal a hidden SoftKeyBar.
protected void	sendToListeners(Event ev)
void	setFont(Font f) Set the Font to be used by the bar if possible.
SoftKeyBar	setKey(int which, IImage image, Menu menu)
SoftKeyBar	setKey(int which, mButton button) Set one of the SoftKeyBar keys to be a proxy for an existing mButton.
SoftKeyBar	setKey(int which, Object obj, String label) Set one of the SoftKeys to be a button or a Menu, depending on the type of the obj parameter.
SoftKeyBar	setKey(int which, String text, IImage icon, Menu menu)
SoftKeyBar	setKey(int which, String text, Menu menu)
SoftKeyBar	setKey(int which, String text, String iconName, Object maskOrColor, Menu menu)
SoftKeyBar	setMenu(int which, String name, IImage icon, String items) Set a particular softkey to be a Menu, specifying the menu as a String.
SoftKeyBar	setMenu(int which, String name, String iconName, Object maskOrColor, String items) Set a particular softkey to be a Menu, specifying the menu as a String.
static void	setupIn(Panel c) Setup the global location for the SoftKeyBar.
static void	setupScreen() This is called by the GUI system when running on a Smartphone.
static boolean	supportsImages() Returns true if the softkey displays on screen supports the display of images, false if not.
static boolean	usingSoftKeys() This returns true if SoftKeys are under this platform.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, toString

Field Detail

name

public String name

You can use this as an identifier for bar.

defaultBackgroundColor

public static Color defaultBackgroundColor

The default background color for the soft keys. Defaults to MediumBlue

hideRemovesSoftKeyBar

public static boolean hideRemovesSoftKeyBar

This is false by default and if you set it true, then a hide() will cause the SoftKeyBar to disappear entirely, instead of just becoming empty - which is the default.

barModifiersToSet

public int barModifiersToSet

barModifiersToClear

public int barModifiersToClear

empty

public static final SoftKeyBar empty

defaultFont

public static Font defaultFont

This is the default font.

Constructor Detail

SoftKeyBar

public SoftKeyBar()

SoftKeyBar

public SoftKeyBar(EventListener listener)

Method Detail

addListener

public void addListener(EventListener el)

removeListener

public void removeListener(EventListener el)

sendToListeners

protected void sendToListeners(Event ev)

clearKeys

public void clearKeys()

setFont

public void setFont(Font f)

Set the Font to be used by the bar if possible.

Parameters:

f - the Font to use if this is allowed by the system. If setting of the Font is not allowed, then this method will have no effect.

supportsImages

public static boolean supportsImages()

Returns true if the softkey displays on screen supports the display of images, false if not.

numberOfKeys

public static int numberOfKeys()

Returns the number of keys supported by the system.

onEvent

public void onEvent(Event ev)

Specified by:

onEvent in interface EventListener

getFontMetrics

public FontMetrics getFontMetrics()

createMenuItem

public MenuItem createMenuItem(String label,
                               String action,
                               String iconName,
                               Object maskOrColor)

createMenuItem

public MenuItem createMenuItem(String label,
                               String action,
                               IImage icon)

createMenuItem

public MenuItem createMenuItem(mButton button)

Return a MenuItem that will be used as a proxy for a specific buton. When the menu item is selected via the soft key bar, the specified button will fire of an action event (ControlEvent.PRESSED)

setKey

public SoftKeyBar setKey(int which,
                         mButton button)

Set one of the SoftKeyBar keys to be a proxy for an existing mButton. Pressing that soft key will cause the specified button to fire of an action event (ControlEvent.PRESSED)

Parameters:

which - the key to set, either 1 (left) or 2 (right.

button - the button that will be activated by the Soft Key.

Returns:

this SoftKeyBar

createMenuItemFor

public MenuItem createMenuItemFor(Object obj)
                           throws IllegalArgumentException

Create a MenuItem for a particular Object.

Parameters:

obj - - this can be a String or an mButton, each of which creates a normal MenuItem, or it can be a Menu or Vector or Object[] or a Container, in which case a MenuItem that has a sub-menu will be created.

Returns:

the MenuItem created.

Throws:

IllegalArgumentException

createMenuFor

public Menu createMenuFor(Object obj)
                   throws IllegalArgumentException

Create a Menu for a specific set of Objects, placed in a Vector, or a Container or an Object array. Each item in the Vector can be an mButton or a String or a MenuItem or another Vector or Menu.

Throws:

IllegalArgumentException

setKey

public SoftKeyBar setKey(int which,
                         Object obj,
                         String label)
                  throws IllegalArgumentException

Set one of the SoftKeys to be a button or a Menu, depending on the type of the obj parameter.

Parameters:

which - the key to set, either 1 (left) or 2 (right.

obj - this can be either a String or mButton (either of which creates a single button for the Soft Key) or a Vector or Object[] or Container or Menu - in which case a Menu will be created for the Soft Key.

label - if the obj parameter gets converted to a Menu, then this parameter will be the label for the menu.

Returns:

this SoftKeyBar

Throws:

IllegalArgumentException

setKey

public SoftKeyBar setKey(int which,
                         IImage image,
                         Menu menu)
                  throws IllegalArgumentException

Parameters:

which - The key to set, starting from 1.

image - The image to use for the key.

menu - An optional menu to display when the key is pressed. If this is null the key will just be treated as a button.

Throws:

IllegalArgumentException - if the system does not support displaying images on the soft keys.

setKey

public SoftKeyBar setKey(int which,
                         String text,
                         IImage icon,
                         Menu menu)
                  throws IllegalArgumentException

Parameters:

which - The key to set, starting from 1.

text - The text for the key. If this is in the form "Text_1|Text_2" then "Text_1" is used as the text for the key and "Text_2" is used as the action for the key.

icon - An image to display as an icon next to the text if possible. If this is not possible then the icon is ignored.

menu - An optional menu to display when the key is pressed. If this is null the key will just be treated as a button.

Throws:

IllegalArgumentException - if the system does not support displaying images on the soft keys.

setKey

public SoftKeyBar setKey(int which,
                         String text,
                         Menu menu)

Parameters:

which - The key to set, starting from 1.

text - The text for the key. If this is in the form "Text_1|Text_2" then "Text_1" is used as the text for the key and "Text_2" is used as the action for the key.

menu - An optional menu to display when the key is pressed. If this is null the key will just be treated as a button with the Text and action for the button being the same.

Throws:

IllegalArgumentException - if the system does not support displaying images on the soft keys.

setKey

public SoftKeyBar setKey(int which,
                         String text,
                         String iconName,
                         Object maskOrColor,
                         Menu menu)

Parameters:

which - The key to set, starting from 1.

text - The text for the key. If this is in the form "Text_1|Text_2" then "Text_1" is used as the text for the key and "Text_2" is used as the action for the key.

iconName - The name of the saved image.

maskOrColor - A name of a mask image or a color mask for the icon, or null.

menu - An optional menu to display when the key is pressed. If this is null the key will just be treated as a button.

Throws:

IllegalArgumentException - if the system does not support displaying images on the soft keys.

setMenu

public SoftKeyBar setMenu(int which,
                          String name,
                          IImage icon,
                          String items)

Set a particular softkey to be a Menu, specifying the menu as a String.

Parameters:

which - The key to set, starting from 1.

name - The name of the menu.

icon - An optional icon for the menu.

items - The items for the menu. This should be specified either as a comma separted list of item names (e.g. "Item 1,Item 2,Item 3") or as a '|' separated list of item name and action pairs (e.g. "Item 1|ACTION_1|Item 2|ACTION_2|Item 3|ACTION_3").

setMenu

public SoftKeyBar setMenu(int which,
                          String name,
                          String iconName,
                          Object maskOrColor,
                          String items)

Set a particular softkey to be a Menu, specifying the menu as a String.

Parameters:

which - The key to set, starting from 1.

name - The name of the menu.

iconName - The name of the saved image.

maskOrColor - A name of a mask image or a color mask for the icon, or null.

items - The items for the menu. This should be specified either as a comma separted list of item names (e.g. "Item 1,Item 2,Item 3") or as a '|' separated list of item name and action pairs (e.g. "Item 1|ACTION_1|Item 2|ACTION_2|Item 3|ACTION_3").

make

protected Control make()

handleKey

public boolean handleKey(KeyEvent ev)

onKeyEvent

public static boolean onKeyEvent(KeyEvent ev)

addTo

public void addTo(SingleContainer sc)

usingSoftKeys

public static boolean usingSoftKeys()

This returns true if SoftKeys are under this platform.

setupIn

public static void setupIn(Panel c)

Setup the global location for the SoftKeyBar.

display

public boolean display()

Display the SoftKeyBar in the global SoftKeyBar location.

getDisplayed

public static SoftKeyBar getDisplayed()

setupScreen

public static void setupScreen()

This is called by the GUI system when running on a Smartphone. It turns off multiple windows and sets up a special area for the SoftKeyBar.

hide

public static void hide()

Hide any visible SoftKeyBar.

reveal

public static boolean reveal()

Reveal a hidden SoftKeyBar.

push

public static void push(SoftKeyBar skb)

Display a new keybar, but save the old keybar.

pop

public static void pop()

Display the keybar that was displayed before the last push() call.

fixMenu

public static Menu fixMenu(Menu m)

Fix a Menu for use with the SoftKeyBar. This will ensure that MenuItem objects are used instead of Strings within the Menu and that numbers are prefixed to the labels.