org.xwiki.gwt.wysiwyg.client.plugin.list
Class ListBehaviorAdjuster

java.lang.Object
  extended by org.xwiki.gwt.user.client.KeyboardAdaptor
      extended by org.xwiki.gwt.wysiwyg.client.plugin.list.ListBehaviorAdjuster
All Implemented Interfaces:
com.google.gwt.event.dom.client.KeyDownHandler, com.google.gwt.event.dom.client.KeyPressHandler, com.google.gwt.event.dom.client.KeyUpHandler, com.google.gwt.event.shared.EventHandler, CommandListener

public class ListBehaviorAdjuster
extends KeyboardAdaptor
implements CommandListener

Handles keyboard actions on valid HTML lists, to ensure that the lists stay valid even after keyboard changes such as adding or deleting list items (enter or delete / backspace). Also ensures that all the list items which only contain a sublist inside are editable.


Field Summary
protected static String LIST_ITEM_TAG
          List item element name.
protected static String ORDERED_LIST_TAG
          Ordered list element name.
protected static Command RESET_COMMAND
          The command that notifies when the content of the rich text area has been reset.
protected static String UNORDERED_LIST_TAG
          Unordered list element name.
 
Constructor Summary
ListBehaviorAdjuster(RichTextArea textArea)
          Creates a new instance.
 
Method Summary
protected  void cleanUp(Element element)
          Executes lists clean up on the subtree rooted in the element passed as parameter.
protected  void cleanUpLists(com.google.gwt.dom.client.NodeList<com.google.gwt.dom.client.Element> listElements)
          Helper function to handle a list of list elements and clean them.
protected  void executeDelete(com.google.gwt.dom.client.Node reference, Element nextLi, com.google.gwt.dom.client.Node skippedEmptyPlaceHolder, Range range)
          Effectively executes the delete operation at the end of a list item by moving the next list item in this one, for the passed parameters.
protected  void handleEmptyListItem(Element li)
          Handles a list item which void by adding a placeholder to render this element editable.
 void handleKeyRelease(Event event)
          Handles a key release.
protected  void handleRepeatableKey(Event event)
          Handles a repeatable key press.
 boolean isEmptyListItemPlaceholder(com.google.gwt.dom.client.Node node)
          Determines if a node is an empty list item placeholder.
protected  boolean needsDeleteAdjustment(Element sourceListItem, Element destListItem)
          Helper function to determine whether deleting at the end / backspacing at the beginning of one of the list items when next list item / previous list item is the other needs special handling or will fall back on the browser default.
protected  void onBackspace(Element li, Event event)
          Handles the backspace key inside a list item, such that it meets the following behavior when hit at the beginning of a list item: The list item in which the delete backspace button is hit is always deleted, if there is another list item preceeding it.
 boolean onBeforeCommand(CommandManager sender, Command command, String param)
          Notifies that the given command is about to be executed with the given parameter by the specified command manager.
 void onCommand(CommandManager sender, Command command, String param)
          Notifies that the given command has been executed with the given parameter by the specified command manager.
protected  void onDelete(Element li, Event event)
          Handles the delete key inside a list item, such that it meets the following behavior when hit at the end of a list item: The list item in which the delete button is hit is never deleted, if there is another list item following it.
protected  void wrapList(Element listElement)
          Tries to reposition a list element that appears in another list element: if there is a previous sibling, it tries to add it as a sublist, else it wraps it in a new list item.
 
Methods inherited from class org.xwiki.gwt.user.client.KeyboardAdaptor
onKeyDown, onKeyPress, onKeyUp
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

LIST_ITEM_TAG

protected static final String LIST_ITEM_TAG
List item element name.

See Also:
Constant Field Values

UNORDERED_LIST_TAG

protected static final String UNORDERED_LIST_TAG
Unordered list element name.

See Also:
Constant Field Values

ORDERED_LIST_TAG

protected static final String ORDERED_LIST_TAG
Ordered list element name.

See Also:
Constant Field Values

RESET_COMMAND

protected static final Command RESET_COMMAND
The command that notifies when the content of the rich text area has been reset.

Constructor Detail

ListBehaviorAdjuster

public ListBehaviorAdjuster(RichTextArea textArea)
Creates a new instance.

Parameters:
textArea - the rich text area to do adjustments for
Method Detail

cleanUp

protected void cleanUp(Element element)
Executes lists clean up on the subtree rooted in the element passed as parameter. Lists cleanup consists of: (but these operations are executed in a single pass).
Note that while these operations are not enough from a strict xhtml cleaning point of view, they address all the practical cases that appear so we chose to limit the operations executed to only these for performance reasons.

Parameters:
element - the root element of the subtree in which to execute cleanup.

cleanUpLists

protected void cleanUpLists(com.google.gwt.dom.client.NodeList<com.google.gwt.dom.client.Element> listElements)
Helper function to handle a list of list elements and clean them.

Parameters:
listElements - the list elements to clean up, according to the description at cleanUp(Element)

wrapList

protected void wrapList(Element listElement)
Tries to reposition a list element that appears in another list element: if there is a previous sibling, it tries to add it as a sublist, else it wraps it in a new list item.

Parameters:
listElement - the list node to wrap

handleEmptyListItem

protected void handleEmptyListItem(Element li)
Handles a list item which void by adding a placeholder to render this element editable. Overwrite this function to add browser specific behaviour.

Parameters:
li - the empty list item to handle

onDelete

protected void onDelete(Element li,
                        Event event)
Handles the delete key inside a list item, such that it meets the following behavior when hit at the end of a list item:

Parameters:
li - the list item in which the delete key is hit
event - the native event that was fired

onBackspace

protected void onBackspace(Element li,
                           Event event)
Handles the backspace key inside a list item, such that it meets the following behavior when hit at the beginning of a list item:

Parameters:
li - the list item in which the backspace key is hit
event - the native event that was fired

needsDeleteAdjustment

protected boolean needsDeleteAdjustment(Element sourceListItem,
                                        Element destListItem)
Helper function to determine whether deleting at the end / backspacing at the beginning of one of the list items when next list item / previous list item is the other needs special handling or will fall back on the browser default. The idea is to interfere only with backspace / delete inside the same list, between different levels list items. If the two list items are in different lists (and none of them is included in the other), the delete between them will be done with the browser default algorithm. Also, if the source list item is an ancestor of the destination list item, the default browser behavior will be executed.

Parameters:
sourceListItem - the list item from which content should be moved
destListItem - the list item to which content should be moved
Returns:
true if the delete / backspace between the two needs special handling, false otherwise

executeDelete

protected void executeDelete(com.google.gwt.dom.client.Node reference,
                             Element nextLi,
                             com.google.gwt.dom.client.Node skippedEmptyPlaceHolder,
                             Range range)
Effectively executes the delete operation at the end of a list item by moving the next list item in this one, for the passed parameters.

Parameters:
reference - the reference element, to move the content of the nextLi after it
nextLi - the next list item after the current list item end, to move in the current list item
range - the selection range for which this operation is executed, used to determine where the nextLi needs to be inserted and how selection needs to be restored
skippedEmptyPlaceHolder - the first empty list item placeholder that was skipped by the next leaf lookup algorithm in this delete operation, and which needs to be removed with the execution of the delete

isEmptyListItemPlaceholder

public boolean isEmptyListItemPlaceholder(com.google.gwt.dom.client.Node node)
Determines if a node is an empty list item placeholder. Overwrite this function to provide specific behavior depending on the type of placeholder each browser uses.

Parameters:
node - the node for which to check if it is the empty list item placeholder or not
Returns:
true if the passed node is an empty list placeholder, or false otherwise.

handleRepeatableKey

protected void handleRepeatableKey(Event event)
Description copied from class: KeyboardAdaptor
Handles a repeatable key press.

Overrides:
handleRepeatableKey in class KeyboardAdaptor
Parameters:
event - the native event that was fired

handleKeyRelease

public void handleKeyRelease(Event event)
Description copied from class: KeyboardAdaptor
Handles a key release.

Overrides:
handleKeyRelease in class KeyboardAdaptor
Parameters:
event - the native event that was fired

onBeforeCommand

public boolean onBeforeCommand(CommandManager sender,
                               Command command,
                               String param)
Notifies that the given command is about to be executed with the given parameter by the specified command manager.

Specified by:
onBeforeCommand in interface CommandListener
Parameters:
sender - The command manager that is about to execute the specified command.
command - The command that will be executed.
param - The parameter that will be passed to the command.
Returns:
true to prevent the execution of the command, false to allow it.
See Also:
CommandListener.onBeforeCommand(CommandManager, Command, String)

onCommand

public void onCommand(CommandManager sender,
                      Command command,
                      String param)
Notifies that the given command has been executed with the given parameter by the specified command manager.

Specified by:
onCommand in interface CommandListener
Parameters:
sender - The command manager that executed the command.
command - The command executed.
param - The parameter used when the command was executed.
See Also:
CommandListener.onCommand(CommandManager, Command, String)