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

Class ListBehaviorAdjuster

java.lang.Object

org.xwiki.gwt.user.client.KeyboardAdaptor

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.

Version:

$Id: 962fe55c7acd7e9a207c5ad222beec31431fc2ed $

Field Summary

Fields

Modifier and Type	Field and Description
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

Constructors

Constructor and Description
ListBehaviorAdjuster(RichTextArea textArea) Creates a new instance.

Method Summary

Methods

Modifier and Type	Method and Description
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)
protected void	handleRepeatableKey(Event event)
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)
void	onCommand(CommandManager sender, Command command, String param)
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:

• finding all the ul or ol tags which are in another ul or ol and adding a li wrapper around each
• finding all the ul or ol tags which are at the beginning (first child) of a list item and making the parent list items editable

(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:

• The list item in which the delete button is hit is never deleted, if there is another list item following it. On internet explorer, this may happen when the list item's entire content is deleted.
• The next list item is found (if any) and moved in the current list item in which the delete button has been hit

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:

• The list item in which the delete backspace button is hit is always deleted, if there is another list item preceeding it. Backspace never acts as unindent, for this, the unindent command should be used.
• The previous list item is found (if any) and the current list item is moved at the end of it

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)

Overrides:

handleRepeatableKey in class KeyboardAdaptor

handleKeyRelease

public void handleKeyRelease(Event event)

Overrides:

handleKeyRelease in class KeyboardAdaptor

onBeforeCommand

public boolean onBeforeCommand(CommandManager sender,
                      Command command,
                      String param)

Specified by:

onBeforeCommand in interface CommandListener

See Also:

CommandListener.onBeforeCommand(CommandManager, Command, String)

onCommand

public void onCommand(CommandManager sender,
             Command command,
             String param)

Specified by:

onCommand in interface CommandListener

See Also:

CommandListener.onCommand(CommandManager, Command, String)