com.nokia.mid.ui
Class PopupList

java.lang.Object
  com.nokia.mid.ui.PopupListItem
      com.nokia.mid.ui.PopupList

public class PopupList

extends PopupListItem

This class implements a popup list which can be populated by various types of list elements. The list items to be added to the list must be of type PopupListItem. PopupList instances can be nested if the list is contextual menu. So if nested a list into another one an item in a PopupList can open up into a new "sublist". A client only need to implement the PopupListListener interface in order to receive list events. There are two types of lists:

• contextual menu and
• list dialog

Contextual menu is the default one and can be nested and it doesn't have a header

List dialog shows a header and cannot be nested.

To be able to nest an contextual menu into another one PopupList inherits from PopupListItem. However the icon and marking related functions doesn't result in appearance changes only text changes are visible

Normally the list would be used like so:

PopupList list1 = new PopupList();
PopupListItem item1 = new PopupListItem("Item1");
PopupListItem item2 = new PopupListItem("Item1", image1);
list1.appendItem(item1);
list1.appendItem(item2);
list1.setVisible(true);


This example creates a PopupList with 2 different items and with a sublist.

PopupList list1 = new PopupList();
PopupList list2 = new PopupList();
list2.setItemText("Sublist");
PopupListItem item1 = new PopupListItem("Text");
PopupListItem item2 = new PopupListItem("Text", image1);
PopupListItem item3 = new PopupListItem("Text2");
PopupListItem item4 = new PopupListItem("Text3", image1);
list1.appendItem(item1);
list1.appendItem(item2);
list1.appendItem(list2);
list2.appendItem(item3);
list2.appendItem(item4);
list1.setVisible(true);


Field Summary

static int	CONTEXTUAL_MENU PopupList type is contextual menu
static int	LIST_DIALOG PopupList type is list dialog
static int	TAIL_LEFT PopupList Tail Style indicating that the tail should point to the left action button.
static int	TAIL_NONE PopupList Tail Style indicating that the list should have no tail.
static int	TAIL_PARENT PopupList Tail Style indicating that the tail should point to the parent list item.
static int	TAIL_RIGHT PopupList Tail Style indicating that the tail should point to the right action button.

Constructor Summary

PopupList()
This constructor instantiates a PopupList instance.

PopupList(java.lang.String itemText)
This constructor instantiates a PopupList instance with itemText set.

PopupList(java.lang.String itemText, int listType)
This constructor instantiates a PopupList instance with the itemText set as provided and depending on the listType value it is a contextual menu or a list dialog

Method Summary

void	appendItem(PopupListItem item) This method will append an item to the list.
PopupListItem	getItem(int index) Returns the item specified by the index from the popuplist.
void	insertItem(PopupListItem item, int index) This method will insert an item to the list at the give index.
void	removeItem(PopupListItem item) This will remove the item from the popuplist.
void	removeItemAt(int index) This will remove the item specified by the index from the popuplist.
void	setItemText(java.lang.String text) Deprecated. will be removed soon, use the setText instead of
void	setListener(PopupListListener listener) This method sets the PopupListListener for this list.
void	setListYPos(int yPos) Sets the y coordinate where the contextual menu should be shown.
void	setTailStyle(int style) This sets the tail style for the contextual menu.
void	setText(java.lang.String text) This method sets the PopupList item text.
void	setVisible(boolean visible) This sets the list visible or hidden.
int	size() This will return the size of the popuplist.

Methods inherited from class com.nokia.mid.ui.PopupListItem

getIcon, getText, hasMarking, isMarked, setHasMarking, setIcon, setMarked

Methods inherited from class java.lang.Object

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

Field Detail

CONTEXTUAL_MENU

public static final int CONTEXTUAL_MENU

PopupList type is contextual menu

See Also:

Constant Field Values

LIST_DIALOG

public static final int LIST_DIALOG

PopupList type is list dialog

See Also:

Constant Field Values

TAIL_LEFT

public static final int TAIL_LEFT

PopupList Tail Style indicating that the tail should point to the left action button.

See Also:

Constant Field Values

TAIL_RIGHT

public static final int TAIL_RIGHT

PopupList Tail Style indicating that the tail should point to the right action button.

See Also:

Constant Field Values

TAIL_NONE

public static final int TAIL_NONE

PopupList Tail Style indicating that the list should have no tail.

See Also:

Constant Field Values

TAIL_PARENT

public static final int TAIL_PARENT

PopupList Tail Style indicating that the tail should point to the parent list item.

See Also:

Constant Field Values

Constructor Detail

PopupList

public PopupList()

This constructor instantiates a PopupList instance. By default it is a contextual menu

PopupList

public PopupList(java.lang.String itemText)

This constructor instantiates a PopupList instance with itemText set. By default it is a contextual menu

Parameters:

itemText - the itemText to be set

PopupList

public PopupList(java.lang.String itemText,
                 int listType)
          throws PopupListException

This constructor instantiates a PopupList instance with the itemText set as provided and depending on the listType value it is a contextual menu or a list dialog

Parameters:

itemText - the itemText set for the list

listType - the type of popuplist can be CONTEXTUAL_MENU or LIST_DIALOG

Throws:

PopupListException - if the type is not one of the allowed constants

Method Detail

setListener

public void setListener(PopupListListener listener)

This method sets the PopupListListener for this list. If the listener is null it removes the previous listener

Parameters:

listener - the listener to be set or null to remove the listener

appendItem

public void appendItem(PopupListItem item)
                throws java.lang.NullPointerException,
                       PopupListException

This method will append an item to the list. The item is always added at the end of the list. If the item is already added elsewhere, then a PopupListException will be thrown. An PopupListException will also be thrown if there are already 3 nesting layers. If the list is visible whilst an item is appended then the list will be updated immediately.

Parameters:

item - The PopupListItem to append to the list.

Throws:

java.lang.NullPointerException - if item is null

PopupListException - if the item is a PopupList instance which is already attached elsewhere or
if more than 3 nesting layers is attempted or
the popuplist is a list dialog and the item is another popuplist or
if the item is a list dialog

insertItem

public void insertItem(PopupListItem item,
                       int index)
                throws java.lang.NullPointerException,
                       PopupListException,
                       java.lang.IndexOutOfBoundsException

This method will insert an item to the list at the give index. If the item is already added elsewhere, then a PopupListException will be thrown. An PopupListException will also be thrown if there are already 3 nesting layers. If the list is visible whilst an item is appended then the list will be updated immediately.

Parameters:

item - The PopupListItem to append to the list.

index - where to insert the item

Throws:

java.lang.NullPointerException - if item is null

PopupListException - if the item is a PopupList instance which is already attached elsewhere or
if more than 3 nesting layers is attempted or
the popuplist is a list dialog and the item is another popuplist or
if the item is a list dialog

java.lang.IndexOutOfBoundsException - if index is invalid

removeItem

public void removeItem(PopupListItem item)

This will remove the item from the popuplist. If the list is visible whilst an item is removed then the list will be updated immediately.

Parameters:

item - The PopupListItem to be removed. If the item is not found, nothing happens.

removeItemAt

public void removeItemAt(int index)
                  throws java.lang.IndexOutOfBoundsException

This will remove the item specified by the index from the popuplist. If the list is visible whilst an item is removed then the list will be updated immediately.

Parameters:

index - to be removed

Throws:

java.lang.IndexOutOfBoundsException - if the index is not within limits

size

public int size()

This will return the size of the popuplist.

Returns:

size of the popuplist

getItem

public PopupListItem getItem(int index)
                      throws java.lang.IndexOutOfBoundsException

Returns the item specified by the index from the popuplist.

Parameters:

index - to be returned

Throws:

java.lang.IndexOutOfBoundsException - if the index is not within limits

setItemText

public void setItemText(java.lang.String text)

Deprecated. will be removed soon, use the setText instead of

This method sets the PopupList item text. This text is shown as the item text when the PopupList instance is used as an item in a contextual menu or it is shown as the title when the list is a list dialog

Parameters:

text - The item text to set for the PopupList.

setText

public void setText(java.lang.String text)

This method sets the PopupList item text. This text is shown as the item text when the PopupList instance is used as an item in a contextual menu or it is shown as the title when the list is a list dialog

Overrides:

setText in class PopupListItem

Parameters:

text - The item text to set for the PopupList.

Throws:

java.lang.NullPointerException - if itemText is null

setVisible

public void setVisible(boolean visible)
                throws PopupListException,
                       java.lang.IllegalStateException

This sets the list visible or hidden. If a nested list is selected by the user it is automatically set as visible true When the user dismisses a list it is automatically set as visible false When set to visible the popuplist will be bound to the current displayable. When the displayable is replaced by a new one as current. It will dismiss the popuplist too. Currently popuplist is supported on Canvas and Form. On other displayables it might throw an IllegalStateException

Parameters:

visible - true: list is shown, false: list is hidden.

Throws:

java.lang.IllegalStateException - if list is set to visible on an unsupported displayable or if the list is set to visible, but it is empty

PopupListException

setTailStyle

public void setTailStyle(int style)
                  throws PopupListException

This sets the tail style for the contextual menu. The values can be: PopupList.TailStyle. The default TailStyle is TailParent

Parameters:

style - The tail style to set.

Throws:

java.lang.IllegalArgumentException - if tail style is not valid.

PopupListException

setListYPos

public void setListYPos(int yPos)
                 throws PopupListException

Sets the y coordinate where the contextual menu should be shown. Does nothing for list dialog

Parameters:

yPos - the coordinate where the contextual menu should be shown

Throws:

PopupListException - if the yPos is negative