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

java.lang.Object
  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 java.lang.Object
implements com.google.gwt.event.dom.client.KeyDownHandler, com.google.gwt.event.dom.client.KeyUpHandler, com.google.gwt.event.dom.client.KeyPressHandler, 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: ListBehaviorAdjuster.java 26786 2010-02-07 16:46:17Z mflorea $

Field Summary

protected static java.lang.String	LIST_ITEM_TAG List item element name.
protected static java.lang.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 java.lang.String	UNORDERED_LIST_TAG Unordered list element name.

Constructor Summary

ListBehaviorAdjuster()

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	dispatchKey(com.google.gwt.user.client.ui.Widget sender, int keyCode, Event originalEvent) Dispatches the passed key pressed on the specified sender, with the specified modifiers.
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.
RichTextArea	getTextArea()
protected void	handleEmptyListItem(Element li) Handles a list item which void by adding a placeholder to render this element editable.
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, java.lang.String param)
void	onCommand(CommandManager sender, Command command, java.lang.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.
void	onKeyDown(com.google.gwt.event.dom.client.KeyDownEvent event)
void	onKeyPress(com.google.gwt.event.dom.client.KeyPressEvent event)
void	onKeyUp(com.google.gwt.event.dom.client.KeyUpEvent event)
void	setTextArea(RichTextArea textArea)
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 java.lang.Object

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

Field Detail

LIST_ITEM_TAG

protected static final java.lang.String LIST_ITEM_TAG

List item element name.

See Also:

Constant Field Values

UNORDERED_LIST_TAG

protected static final java.lang.String UNORDERED_LIST_TAG

Unordered list element name.

See Also:

Constant Field Values

ORDERED_LIST_TAG

protected static final java.lang.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()

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.

onKeyPress

public void onKeyPress(com.google.gwt.event.dom.client.KeyPressEvent event)

Specified by:

onKeyPress in interface com.google.gwt.event.dom.client.KeyPressHandler

See Also:

KeyPressHandler.onKeyPress(KeyPressEvent)

dispatchKey

protected void dispatchKey(com.google.gwt.user.client.ui.Widget sender,
                           int keyCode,
                           Event originalEvent)

Dispatches the passed key pressed on the specified sender, with the specified modifiers. This function does generalized dispatching, regardless of the actual key event that signals the press of the key. The different implementations for browsers will use their own key detecting mechanisms, but will use this function to dispatch it.

Parameters:

sender - the sender widget of the key press event

keyCode - the code of the key to dispatch

originalEvent - the original native key event that was fired

onKeyUp

public void onKeyUp(com.google.gwt.event.dom.client.KeyUpEvent event)

Specified by:

onKeyUp in interface com.google.gwt.event.dom.client.KeyUpHandler

See Also:

KeyUpHandler.onKeyUp(KeyUpEvent)

onKeyDown

public void onKeyDown(com.google.gwt.event.dom.client.KeyDownEvent event)

Specified by:

onKeyDown in interface com.google.gwt.event.dom.client.KeyDownHandler

See Also:

KeyDownHandler.onKeyDown(KeyDownEvent)

getTextArea

public RichTextArea getTextArea()

Returns:

the textArea that this handler is operating on

setTextArea

public void setTextArea(RichTextArea textArea)

Parameters:

textArea - the textArea to operate on

onBeforeCommand

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

Specified by:

onBeforeCommand in interface CommandListener

See Also:

CommandListener.onBeforeCommand(CommandManager, Command, String)

onCommand

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

Specified by:

onCommand in interface CommandListener

See Also:

CommandListener.onCommand(CommandManager, Command, String)