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



Copyright 1999- Research In Motion Limited. 295 Phillip Street, Waterloo, Ontario, Canada, N2L 3W8. All Rights Reserved.
Copyright 1993-2003 Sun Microsystems, Inc. 901 San Antonio Road, Palo Alto, California, 94303, U.S.A.
Copyright 2002-2003 Nokia Corporation All Rights Reserved.
Java is a trademark or registered trademark of Sun Microsystems, Inc. in the US and other countries.