net.rim.blackberry.api.bbm.platform.ui.chat.component
Class ChatField

java.lang.Object
  |
  +--net.rim.device.api.ui.Field
        |
        +--net.rim.device.api.ui.ScrollView
              |
              +--net.rim.device.api.ui.Manager
                    |
                    +--net.rim.device.api.ui.container.VerticalFieldManager
                          |
                          +--net.rim.blackberry.api.bbm.platform.ui.chat.component.ChatField

All Implemented Interfaces:

AdjustmentListener, FieldVisibleRectChangeListener, IComponent, InputMethodListener, ToggleFieldProvider

public class ChatField

extends VerticalFieldManager

implements ToggleFieldProvider

This field combines the message list manager, reply field, and a toggler to create an embedded chat experience. This field supports a collapsed and non-collapsed states. If the manager is non-collapsed, it means the reply field is showing in the foreground and the message list manager is partially hidden by the reply field. If the manager is collapsed, it means the reply field is not showing and the message list field is in the foreground. This allows the user to have a chat experience while saving screen space. The toggle field which is positioned below the reply field can be used to toggle the state and visibility of fields.

Since:

BBM SDK 1.0

Field Summary

protected boolean	_isCollapsed Indicates whether the the reply field is hiding or showing.
protected ToggleFieldProvider	_messageList Message list manager
protected ReplyField	_replyField Reply field
protected ToggleFieldProvider	_replyFieldManager Reply field manager
protected SmileyButton	_smileyButton Smiley button
protected ToggleFieldProvider	_toggler Toggle field

Constructor Summary

ChatField()
Creates an instance of the chat field.

ChatField(long displayStyle, int borderStyle)
Creates an instance of the chat field.

Method Summary

protected void	addChatFields() Adds each field created in the constructor to the manager.
void	addMessage(MessageFieldProvider message) Adds a message to the message list manager.
protected Manager	createAllFieldsManager() Returns a new instance of the manager which will contain all of the fields.
protected Manager	createMessageListAndReplyFieldManager() Creates a new instance of the manager that will contain the message list and the reply field.
protected ToggleFieldProvider	createMessageListManager(long displayStyle, int borderStyle) Returns a new instance of the manager for messages.
protected ReplyField	createReplyField() Returns a new instance of the reply field.
protected ToggleFieldProvider	createReplyFieldManager(ReplyField replyField, SmileyButton smileyButton) Returns a manager for the reply field and the smiley button.
protected Field	createReplyFieldTopBorder() Returns a new instance of a field that will appear above the reply field acting as a separator from the fields above.
protected SmileyButton	createSmileyButton() Returns a new instance of the smiley button.
protected Field	createToggleAndReplyFieldSeparator() Returns a new instance of the field that will separate the reply field from the toggle field.
protected ToggleFieldProvider	createToggleChatDisplayField() Returns a new instance of the chat toggler.
ToggleFieldProvider	getMessageListField() Returns the message list field.
ReplyField	getReplyField() Returns the reply field.
ToggleFieldProvider	getReplyFieldManager() Returns the reply field manager.
Field	getToggleField() Returns this manager.
ToggleFieldProvider	getToggler() Returns the toggler.
protected boolean	invokeAction(int action) If the leaf field that has focus is the toggler and the action is ACTION_INVOKE, toggles the state by calling toggle() and returns true; otherwise, uses the super implementation.
boolean	isCollapsed() If the manager is not collapsed, it means the reply field is showing in the foreground and the message list manager is partially hidden by the reply field.
protected boolean	keyChar(char key, int status, int time) If the user selects enter, calls invokeAction with ACTION_INVOKE as a parameter.
protected int	nextFocus(int direction, int axis) Skip focus on the messages field when the state is not collapsed (i.e. message list is hidden).
void	removeAllMessages() Removes all messages that have been added in MessageListManager.
void	toggle() Toggle the state of the field.

Field Detail

_isCollapsed

protected boolean _isCollapsed

Indicates whether the the reply field is hiding or showing.

Since:

BBM SDK 1.0

_messageList

protected ToggleFieldProvider _messageList

Message list manager

Since:

BBM SDK 1.0

_replyField

protected ReplyField _replyField

Reply field

Since:

BBM SDK 1.0

_replyFieldManager

protected ToggleFieldProvider _replyFieldManager

Reply field manager

Since:

BBM SDK 1.0

_smileyButton

protected SmileyButton _smileyButton

Smiley button

Since:

BBM SDK 1.0

_toggler

protected ToggleFieldProvider _toggler

Toggle field

Since:

BBM SDK 1.0

Constructor Detail

ChatField

public ChatField()

Creates an instance of the chat field. Default style is used (messages from the same sender are grouped, sender's display name is shown, messages have a bubble border).

Since:

BBM SDK 1.0

ChatField

public ChatField(long displayStyle,
                 int borderStyle)

Creates an instance of the chat field. Uses the styles specified. Calls create() methods when creating each field.

Parameters:

displayStyle - style bit passed to the BasicMessageListManager when a message list is created; USE_ALL_HEIGHT is supported.

borderStyle - style passed to the BasicMessageListManager when a message list is created

Since:

BBM SDK 1.0

Method Detail

addChatFields

protected void addChatFields()

Adds each field created in the constructor to the manager.

Since:

BBM SDK 1.0

addMessage

public void addMessage(MessageFieldProvider message)

Adds a message to the message list manager. Scrolls the manager using MessageListManager.SCROLL_HOTKEY_BOTTOM flag if the focus is not on a field that is a MessageFieldProvider.

Parameters:

message - message to be added

Throws:

NullPointerException - if the chat field is null

IllegalArgumentException - if getMessageListField() has been overridden to return a class of type that is not MessageListManager

Since:

BBM SDK 1.0

createAllFieldsManager

protected Manager createAllFieldsManager()

Returns a new instance of the manager which will contain all of the fields. By default, returns the VerticalFieldManager. Override if you want your own manager.

Returns:

manager which will contain all of the fields

Since:

BBM SDK 1.0

createMessageListAndReplyFieldManager

protected Manager createMessageListAndReplyFieldManager()

Creates a new instance of the manager that will contain the message list and the reply field. Uses OverlappingFieldManager by default. Override if you want to customize this manager.

Returns:

new instance of the manager that will contain the message list and the reply field

Since:

BBM SDK 1.0

createMessageListManager

protected ToggleFieldProvider createMessageListManager(long displayStyle,
                                                       int borderStyle)

Returns a new instance of the manager for messages. By default, the manager is restricted to 88 pixels. Override to return your own manager.

Parameters:

displayStyle - style bit passed to the BasicMessageListManager when a message list is created; USE_ALL_HEIGHT is supported.

borderStyle - style passed to the BasicMessageListManager when a message list is created

Returns:

manager for messages

Since:

BBM SDK 1.0

createReplyField

protected ReplyField createReplyField()

Returns a new instance of the reply field. Override if you want to customize the field where the user enters the text.

Returns:

reply field

Since:

BBM SDK 1.0

createReplyFieldManager

protected ToggleFieldProvider createReplyFieldManager(ReplyField replyField,
                                                      SmileyButton smileyButton)

Returns a manager for the reply field and the smiley button. By default, returns a BasicReplyFieldManager. Override to customize the look and feel of this field.

Parameters:

replyField - reply field

smileyButton - smiley button

Returns:

manager for the reply field and the smiley button

Since:

BBM SDK 1.0

createReplyFieldTopBorder

protected Field createReplyFieldTopBorder()

Returns a new instance of a field that will appear above the reply field acting as a separator from the fields above. By default, it's a dark grey ThinSeparatorField.

Returns:

separator for the reply field and the fields above

Since:

BBM SDK 1.0

createSmileyButton

protected SmileyButton createSmileyButton()

Returns a new instance of the smiley button. Override if you want to customize this field.

Returns:

smiley button

Since:

BBM SDK 1.0

createToggleAndReplyFieldSeparator

protected Field createToggleAndReplyFieldSeparator()

Returns a new instance of the field that will separate the reply field from the toggle field. By default, it returns a ThinSeparatorField with a light gray background.

Returns:

field that will separator the reply field from the toggle field

Since:

BBM SDK 1.0

createToggleChatDisplayField

protected ToggleFieldProvider createToggleChatDisplayField()

Returns a new instance of the chat toggler. Override if you want to customize the toggler.

Returns:

new instance of the field that will be used to collapse the reply field

Since:

BBM SDK 1.0

getMessageListField

public ToggleFieldProvider getMessageListField()

Returns the message list field.

Returns:

message list

Since:

BBM SDK 1.0

getReplyField

public ReplyField getReplyField()

Returns the reply field.

Returns:

reply field

Since:

BBM SDK 1.0

getReplyFieldManager

public ToggleFieldProvider getReplyFieldManager()

Returns the reply field manager.

Returns:

reply field manager

Since:

BBM SDK 1.0

getToggleField

public Field getToggleField()

Returns this manager.

Since:

BBM SDK 1.0

See Also:

ToggleFieldProvider.getToggleField()

getToggler

public ToggleFieldProvider getToggler()

Returns the toggler.

Returns:

toggler

Since:

BBM SDK 1.0

invokeAction

protected boolean invokeAction(int action)

If the leaf field that has focus is the toggler and the action is ACTION_INVOKE, toggles the state by calling toggle() and returns true; otherwise, uses the super implementation.

Since:

BBM SDK 1.0

isCollapsed

public boolean isCollapsed()

If the manager is not collapsed, it means the reply field is showing in the foreground and the message list manager is partially hidden by the reply field. If the manager is collapsed, it means the reply field is not showing and the message list field is in the foreground.

Returns:

true if the manager is collapsed; false otherwise

Since:

BBM SDK 1.0

keyChar

protected boolean keyChar(char key,
                          int status,
                          int time)

If the user selects enter, calls invokeAction with ACTION_INVOKE as a parameter. Otherwise, uses the super implementation.

Since:

BBM SDK 1.0

nextFocus

protected int nextFocus(int direction,
                        int axis)

Skip focus on the messages field when the state is not collapsed (i.e. message list is hidden).

Since:

BBM SDK 1.0

See Also:

VerticalFieldManager#nextFocus(int direction, int axis)

removeAllMessages

public void removeAllMessages()

Removes all messages that have been added in MessageListManager.

Throws:

IllegalArgumentException - if getMessageListField() has been overridden to return a class of type that is not MessageListManager

Since:

BBM SDK 1.0

toggle

public void toggle()

Toggle the state of the field. Calls toggle() on the message list, reply field and toggler. Sets the focus on the reply field if the state is not collapsed.

Since:

BBM SDK 1.0