org.eclipse.nebula.widgets.richtext

Class RichTextEditor

java.lang.Object

org.eclipse.swt.widgets.Widget

org.eclipse.swt.widgets.Control

org.eclipse.swt.widgets.Scrollable

org.eclipse.swt.widgets.Composite

org.eclipse.nebula.widgets.richtext.RichTextEditor

All Implemented Interfaces:

org.eclipse.swt.graphics.Drawable

public class RichTextEditor
extends org.eclipse.swt.widgets.Composite

Rich Text Editor control that wraps a Browser with enabled Javascript that shows a simple HTML template containing a ckeditor as rich text editor.

The following style bits are supported:

• SWT.RESIZE - specify if the resize function of ckeditor is enabled (mostly used for embedded usage)
• SWT.MIN - specify if the configured minimum dimensions should be applied to the resize function of ckeditor
• SWT.EMBEDDED - specify if the rich text editor is used in embedded mode (e.g. as a cell editor of a JFace viewer)

Additionally the SWT Browser style bits SWT.MOZILLA or SWT.WEBKIT can be set to specify the native browser that should be used for rendering

See Also:

http://ckeditor.com/

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
(package private) class	RichTextEditor.FocusInFunction Callback function that is called via Javascript if the editor gains focus.
(package private) class	RichTextEditor.FocusOutFunction Callback function that is called via Javascript on blur in the editor part.
(package private) class	RichTextEditor.JavaExecutionFinishedFunction Callback function that is called via Javascript after a java callback is triggered via custom toolbar button.
(package private) class	RichTextEditor.JavaExecutionStartedFunction Callback function that is called via Javascript before a java callback is triggered via custom toolbar button.
(package private) class	RichTextEditor.KeyPressedFunction Callback function that is called via Javascript if a keydown event occurs in the editor part.
(package private) class	RichTextEditor.KeyReleasedFunction Callback function that is called via Javascript if a keyup event occurs in the editor part.
(package private) class	RichTextEditor.ModifyFunction Callback function that is called via Javascript if a change event occurs in the editor part.

Field Summary

Fields

Modifier and Type	Field and Description
static java.lang.String	JAR_UNPACK_LOCATION_PROPERTY Key of the system property to specify a fixed directory to unpack the ckeditor resources to.
protected org.eclipse.swt.graphics.Rectangle	resizedBounds

Fields inherited from class org.eclipse.swt.widgets.Control

handle

Constructor Summary

Constructors

Constructor and Description
RichTextEditor(org.eclipse.swt.widgets.Composite parent) Creates a RichTextEditor that wraps a Browser using the style bit SWT.NONE and the default RichTextEditorConfiguration.
RichTextEditor(org.eclipse.swt.widgets.Composite parent, int style) Creates a RichTextEditor that wraps a Browser using the given style bit and the default RichTextEditorConfiguration.
RichTextEditor(org.eclipse.swt.widgets.Composite parent, RichTextEditorConfiguration editorConfig) Creates a RichTextEditor that wraps a Browser using the style bit SWT.NONE and the given RichTextEditorConfiguration.
RichTextEditor(org.eclipse.swt.widgets.Composite parent, RichTextEditorConfiguration editorConfig, int style) Creates a RichTextEditor that wraps a Browser using the given style bit and the given RichTextEditorConfiguration.
RichTextEditor(org.eclipse.swt.widgets.Composite parent, ToolbarConfiguration toolbarConfig) Deprecated. use constructors that take a RichTextEditorConfiguration
RichTextEditor(org.eclipse.swt.widgets.Composite parent, ToolbarConfiguration toolbarConfig, int style) Deprecated. use constructors that take a RichTextEditorConfiguration

Method Summary

Modifier and Type	Method and Description
void	addFocusListener(org.eclipse.swt.events.FocusListener listener)
void	addJavaCallbackListener(JavaCallbackListener listener) Add a JavaCallbackListener that is triggered on executing a Java callback via custom ToolbarButton.
void	addKeyListener(org.eclipse.swt.events.KeyListener listener)
void	addModifyListener(org.eclipse.swt.events.ModifyListener listener) Adds the listener to the collection of listeners who will be notified when the receiver's text is modified, by sending it one of the messages defined in the ModifyListener interface.
void	addToolbarButton(ToolbarButton button) Adds the given ToolbarButton to the toolbar of the editor.
void	addToolbarButton(ToolbarButton button, org.eclipse.swt.browser.BrowserFunction function) Adds the given ToolbarButton to the toolbar of the editor.
void	dispose()
java.lang.Object	evaluateJavascript(java.lang.String script) Evaluates the specified script in the internal Browser and returns the result.
boolean	executeJavascript(java.lang.String script) Executes the specified script in the internal Browser.
boolean	forceFocus()
RichTextEditorConfiguration	getEditorConfiguration() This method returns the RichTextEditorConfiguration that is used to configure this RichTextEditor.
protected int	getMinimumHeight() Returns the minimum height that should be used for initially open the editor in embedded mode.
protected int	getMinimumWidth() Returns the minimum width that should be used for initially open the editor in embedded mode.
java.lang.String	getSelectedHTML() Returns the current selected text containing the markup tags for styling.
java.lang.String	getSelectedText() Returns the current selected text without any markup tags.
java.lang.String	getText()
void	insertHTML(java.lang.String html) Inserts HTML code into the currently selected position in the editor in WYSIWYG mode.
void	insertText(java.lang.String text) Insert text content into the currently selected position in the editor in WYSIWYG mode.
boolean	isEditable() Returns the editable state.
boolean	isFocusControl()
boolean	isHandleFocusChanges()
void	notifyFocusGained(org.eclipse.swt.events.FocusEvent event) Notify the registered FocusListener that the editor gained focus.
void	notifyFocusLost(org.eclipse.swt.events.FocusEvent event) Notify the registered FocusListener that the editor lost focus.
void	notifyKeyPressed(org.eclipse.swt.events.KeyEvent event) Notify the registered KeyListener that a key was pressed.
void	notifyKeyReleased(org.eclipse.swt.events.KeyEvent event) Notify the registered KeyListener that a key was released.
void	notifyModifyListeners(org.eclipse.swt.events.ModifyEvent event) Notifies all of the receiver's listeners when the receiver's text is modified.
void	removeFocusListener(org.eclipse.swt.events.FocusListener listener)
void	removeJavaCallbackListener(JavaCallbackListener listener) Remove a JavaCallbackListener that is triggered on executing a Java callback via custom ToolbarButton.
void	removeKeyListener(org.eclipse.swt.events.KeyListener listener)
void	removeModifyListener(org.eclipse.swt.events.ModifyListener listener) Removes the listener from the collection of listeners who will be notified when the receiver's text is modified.
void	removeToolbarButton(ToolbarButton button) Removes the given ToolbarButton from the toolbar of the editor.
void	setBounds(int x, int y, int width, int height)
void	setBounds(org.eclipse.swt.graphics.Rectangle rect)
void	setEditable(boolean editable) Sets the editable state.
boolean	setFocus()
void	setHandleFocusChanges(boolean handleFocusChanges) Configure whether focus changes should be handled or not.
(package private) void	setInlineContainerBounds(int x, int y, int width, int height) Used in embedded mode to support manual resizing of the editor.
void	setLanguage(java.util.Locale locale) Sets the user interface language localization to use.
void	setLanguage(java.util.Locale locale, boolean update)
void	setLanguage(java.lang.String language) Sets the user interface language localization to use.
void	setLanguage(java.lang.String language, boolean update)
void	setText(java.lang.String text) Set text to the editing area.
void	setVisible(boolean visible)
void	updateEditor() Update the editor.
void	updateToolbar() Update the toolbar.

Methods inherited from class org.eclipse.swt.widgets.Composite

changed, checkSubclass, drawBackground, getBackgroundMode, getChildren, getLayout, getLayoutDeferred, getTabList, isLayoutDeferred, layout, layout, layout, layout, layout, setBackgroundMode, setLayout, setLayoutDeferred, setTabList

Methods inherited from class org.eclipse.swt.widgets.Scrollable

computeTrim, getClientArea, getHorizontalBar, getScrollbarsMode, getVerticalBar

Methods inherited from class org.eclipse.swt.widgets.Control

addControlListener, addDragDetectListener, addGestureListener, addHelpListener, addMenuDetectListener, addMouseListener, addMouseMoveListener, addMouseTrackListener, addMouseWheelListener, addPaintListener, addTouchListener, addTraverseListener, computeSize, computeSize, dragDetect, dragDetect, getAccessible, getBackground, getBackgroundImage, getBorderWidth, getBounds, getCursor, getDragDetect, getEnabled, getFont, getForeground, getLayoutData, getLocation, getMenu, getMonitor, getOrientation, getParent, getRegion, getShell, getSize, getTextDirection, getToolTipText, getTouchEnabled, getVisible, internal_dispose_GC, internal_new_GC, isEnabled, isReparentable, isVisible, moveAbove, moveBelow, pack, pack, print, redraw, redraw, removeControlListener, removeDragDetectListener, removeGestureListener, removeHelpListener, removeMenuDetectListener, removeMouseListener, removeMouseMoveListener, removeMouseTrackListener, removeMouseWheelListener, removePaintListener, removeTouchListener, removeTraverseListener, requestLayout, setBackground, setBackgroundImage, setCapture, setCursor, setDragDetect, setEnabled, setFont, setForeground, setLayoutData, setLocation, setLocation, setMenu, setOrientation, setParent, setRedraw, setRegion, setSize, setSize, setTextDirection, setToolTipText, setTouchEnabled, toControl, toControl, toDisplay, toDisplay, traverse, traverse, traverse, update

Methods inherited from class org.eclipse.swt.widgets.Widget

addDisposeListener, addListener, checkWidget, getData, getData, getDisplay, getListeners, getStyle, isAutoDirection, isDisposed, isListening, notifyListeners, removeDisposeListener, removeListener, removeListener, reskin, setData, setData, toString

Methods inherited from class java.lang.Object

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

Methods inherited from interface org.eclipse.swt.graphics.Drawable

isAutoScalable

Field Detail

resizedBounds

protected org.eclipse.swt.graphics.Rectangle resizedBounds

JAR_UNPACK_LOCATION_PROPERTY

public static final java.lang.String JAR_UNPACK_LOCATION_PROPERTY

Key of the system property to specify a fixed directory to unpack the ckeditor resources to. If a system property for that key is registered and the rich text control is deployed within a JAR, the resources will be unpacked into the specified directory. If no value is registered for that key and the rich text control is deployed in a JAR, the resources will be unpacked into a temporary directory, that gets deleted when the runtime is shutdown. If the rich text control is not deployed within a JAR but as part of an Eclipse application, the bundle will be unpacked automatically. In this case this system property won't get interpreted.

See Also:

Constant Field Values

Constructor Detail

RichTextEditor

public RichTextEditor(org.eclipse.swt.widgets.Composite parent)

Creates a RichTextEditor that wraps a Browser using the style bit SWT.NONE and the default RichTextEditorConfiguration.

Parameters:

parent - the parent composite where this rich text editor should be added to

RichTextEditor

@Deprecated
public RichTextEditor(org.eclipse.swt.widgets.Composite parent,
                                   ToolbarConfiguration toolbarConfig)

Deprecated. use constructors that take a RichTextEditorConfiguration

Creates a RichTextEditor that wraps a Browser using the style bit SWT.NONE and creates a RichTextEditorConfiguration out of the given ToolbarConfiguration.

Parameters:

parent - the parent composite where this rich text editor should be added to

toolbarConfig - the ToolbarConfiguration to use or null for using the default ToolbarConfiguration

RichTextEditor

public RichTextEditor(org.eclipse.swt.widgets.Composite parent,
                      RichTextEditorConfiguration editorConfig)

Creates a RichTextEditor that wraps a Browser using the style bit SWT.NONE and the given RichTextEditorConfiguration.

Parameters:

parent - the parent composite where this rich text editor should be added to

editorConfig - the RichTextEditorConfiguration to use or null for using the default RichTextEditorConfiguration

RichTextEditor

public RichTextEditor(org.eclipse.swt.widgets.Composite parent,
                      int style)

Creates a RichTextEditor that wraps a Browser using the given style bit and the default RichTextEditorConfiguration.

Parameters:

parent - the parent composite where this rich text editor should be added to

style - the style of widget to construct, see Browser for further style bit information

RichTextEditor

@Deprecated
public RichTextEditor(org.eclipse.swt.widgets.Composite parent,
                                   ToolbarConfiguration toolbarConfig,
                                   int style)

Deprecated. use constructors that take a RichTextEditorConfiguration

Creates a RichTextEditor that wraps a Browser using the given style bit and creates a RichTextEditorConfiguration out of the given ToolbarConfiguration.

Parameters:

parent - the parent composite where this rich text editor should be added to

toolbarConfig - the ToolbarConfiguration to use or null for using the default ToolbarConfiguration

style - the style of widget to construct, see Browser for further style bit information

See Also:

Browser

RichTextEditor

public RichTextEditor(org.eclipse.swt.widgets.Composite parent,
                      RichTextEditorConfiguration editorConfig,
                      int style)

Creates a RichTextEditor that wraps a Browser using the given style bit and the given RichTextEditorConfiguration.

Parameters:

parent - the parent composite where this rich text editor should be added to

editorConfig - the RichTextEditorConfiguration to use or null for using the default RichTextEditorConfiguration

style - the style of widget to construct, see Browser for further style bit information

See Also:

Browser

Method Detail

dispose

public void dispose()

Overrides:

dispose in class org.eclipse.swt.widgets.Widget

setVisible

public void setVisible(boolean visible)

Overrides:

setVisible in class org.eclipse.swt.widgets.Control

getText

public java.lang.String getText()

Returns:

The text that is currently set in the editing area. Contains HTML tags for formatting.

setText

public void setText(java.lang.String text)

Set text to the editing area. Can contain HTML tags for styling.

Parameters:

text - The text to set to the editing area.

insertText

public void insertText(java.lang.String text)

Insert text content into the currently selected position in the editor in WYSIWYG mode. The styles of the selected element will be applied to the inserted text. Spaces around the text will be left untouched.

Parameters:

text - Text to be inserted into the editor.

insertHTML

public void insertHTML(java.lang.String html)

Inserts HTML code into the currently selected position in the editor in WYSIWYG mode.

Parameters:

html - HTML code to be inserted into the editor.

getSelectedText

public java.lang.String getSelectedText()

Returns the current selected text without any markup tags.

Returns:

The current selected text without any markup tags.

getSelectedHTML

public java.lang.String getSelectedHTML()

Returns the current selected text containing the markup tags for styling.

Note: It will not contain the parent tag.

Returns:

The current selected text containing any markup styling tags.

isEditable

public boolean isEditable()

Returns the editable state.

Returns:

whether or not the receiver is editable

updateToolbar

public void updateToolbar()

Update the toolbar. Typically used if buttons where added or removed at runtime.

updateEditor

public void updateEditor()

Update the editor. Basically it will destroy and recreate the CKEditor. Needed to be used if a basic configuration is changed, e.g. the language.

Since:

1.1

setEditable

public void setEditable(boolean editable)

Sets the editable state.

Parameters:

editable - the new editable state

getEditorConfiguration

public RichTextEditorConfiguration getEditorConfiguration()

This method returns the RichTextEditorConfiguration that is used to configure this RichTextEditor. It can be used to change some configurations at runtime.

Note: After configuration values have been changed it is necessary to call updateEditor() so the configurations are applied.

Returns:

The RichTextEditorConfiguration used to configure this RichTextEditor.

Since:

1.1

setLanguage

public void setLanguage(java.util.Locale locale)

Sets the user interface language localization to use. Only the language part of the Locale will be used. This method triggers an immediate update of the editor instance.

Parameters:

locale - The user interface language localization to use.

Since:

1.1

setLanguage

public void setLanguage(java.util.Locale locale,
                        boolean update)

Parameters:

locale - The user interface language localization to use.

update - true if the editor should be updated immediately, false if the update should not be executed. In that case updateEditor() needs to be executed explicitly.

Since:

1.1

setLanguage

public void setLanguage(java.lang.String language)

Sets the user interface language localization to use. This method triggers an immediate update of the editor instance.

Parameters:

language - The user interface language localization to use.

Since:

1.1

setLanguage

public void setLanguage(java.lang.String language,
                        boolean update)

Parameters:

language - The user interface language localization to use.

update - true if the editor should be updated immediately, false if the update should not be executed. In that case updateEditor() needs to be executed explicitly.

Since:

1.1

addToolbarButton

public void addToolbarButton(ToolbarButton button)

Adds the given ToolbarButton to the toolbar of the editor.

Parameters:

button - The button to add.

See Also:

RichTextEditorConfiguration.addToolbarButton(ToolbarButton)

addToolbarButton

public void addToolbarButton(ToolbarButton button,
                             org.eclipse.swt.browser.BrowserFunction function)

Adds the given ToolbarButton to the toolbar of the editor. Uses the given BrowserFunction as callback for the button.

Parameters:

button - The button to add.

function - The function to use as callback.

See Also:

RichTextEditorConfiguration.addToolbarButton(ToolbarButton, BrowserFunction)

removeToolbarButton

public void removeToolbarButton(ToolbarButton button)

Removes the given ToolbarButton from the toolbar of the editor.

Parameters:

button - The button to remove.

See Also:

RichTextEditorConfiguration.removeToolbarButton(ToolbarButton)

setFocus

public boolean setFocus()

Overrides:

setFocus in class org.eclipse.swt.widgets.Composite

forceFocus

public boolean forceFocus()

Overrides:

forceFocus in class org.eclipse.swt.widgets.Control

isFocusControl

public boolean isFocusControl()

Overrides:

isFocusControl in class org.eclipse.swt.widgets.Control

addFocusListener

public void addFocusListener(org.eclipse.swt.events.FocusListener listener)

Overrides:

addFocusListener in class org.eclipse.swt.widgets.Control

removeFocusListener

public void removeFocusListener(org.eclipse.swt.events.FocusListener listener)

Overrides:

removeFocusListener in class org.eclipse.swt.widgets.Control

notifyFocusGained

public void notifyFocusGained(org.eclipse.swt.events.FocusEvent event)

Notify the registered FocusListener that the editor gained focus.

Parameters:

event - The event to fire.

notifyFocusLost

public void notifyFocusLost(org.eclipse.swt.events.FocusEvent event)

Notify the registered FocusListener that the editor lost focus.

Parameters:

event - The event to fire.

setBounds

public void setBounds(org.eclipse.swt.graphics.Rectangle rect)

Overrides:

setBounds in class org.eclipse.swt.widgets.Control

setBounds

public void setBounds(int x,
                      int y,
                      int width,
                      int height)

Overrides:

setBounds in class org.eclipse.swt.widgets.Control

setInlineContainerBounds

void setInlineContainerBounds(int x,
                              int y,
                              int width,
                              int height)

Used in embedded mode to support manual resizing of the editor. Executed via callback on ckeditor resize.

Parameters:

x - the new x coordinate for the receiver

y - the new y coordinate for the receiver

width - the new width for the receiver

height - the new height for the receiver

getMinimumHeight

protected int getMinimumHeight()

Returns the minimum height that should be used for initially open the editor in embedded mode. It is also used to specify the resize minimum height if the editor was created using the style bit SWT.MIN. Using the default RichTextEditorConfiguration this is 150 for the toolbar and 50 for showing one row in the editor area.

Returns:

The minimum height to use for initially open the editor in embedded mode and for editor resize minimum in case the editor was created with SWT.MIN

getMinimumWidth

protected int getMinimumWidth()

Returns the minimum width that should be used for initially open the editor in embedded mode. It is also used to specify the resize minimum width if the editor was created using the style bit SWT.MIN. Using the default RichTextEditorConfiguration this is 370 for showing the default options in three lines of the toolbar.

Returns:

The minimum width to use for initially open the editor in embedded mode and for editor resize minimum in case the editor was created with SWT.MIN

executeJavascript

public boolean executeJavascript(java.lang.String script)

Executes the specified script in the internal Browser. Can be used to execute Javascript directly in the browser from a listener if necessary.

Parameters:

script - the script with javascript commands

Returns:

true if the operation was successful and false otherwise

See Also:

Browser.execute(String)

evaluateJavascript

public java.lang.Object evaluateJavascript(java.lang.String script)

Evaluates the specified script in the internal Browser and returns the result. Can be used to evaluate Javascript directly in the browser from a listener if necessary.

Parameters:

script - the script with javascript commands

Returns:

the return value, if any, of executing the script

See Also:

Browser.evaluate(String)

isHandleFocusChanges

public boolean isHandleFocusChanges()

Returns:

true if focus changes are handled, false if not

setHandleFocusChanges

public void setHandleFocusChanges(boolean handleFocusChanges)

Configure whether focus changes should be handled or not. A typical use case for disabling the focus handling is for example to open a dialog from a Java callback via custom toolbar button.

Parameters:

handleFocusChanges - true if focus changes should be handled, false if not

addKeyListener

public void addKeyListener(org.eclipse.swt.events.KeyListener listener)

Overrides:

addKeyListener in class org.eclipse.swt.widgets.Control

removeKeyListener

public void removeKeyListener(org.eclipse.swt.events.KeyListener listener)

Overrides:

removeKeyListener in class org.eclipse.swt.widgets.Control

notifyKeyPressed

public void notifyKeyPressed(org.eclipse.swt.events.KeyEvent event)

Notify the registered KeyListener that a key was pressed.

Parameters:

event - The event to fire.

notifyKeyReleased

public void notifyKeyReleased(org.eclipse.swt.events.KeyEvent event)

Notify the registered KeyListener that a key was released.

Parameters:

event - The event to fire.

addModifyListener

public void addModifyListener(org.eclipse.swt.events.ModifyListener listener)

Adds the listener to the collection of listeners who will be notified when the receiver's text is modified, by sending it one of the messages defined in the ModifyListener interface.

Parameters:

listener - the listener which should be notified

Throws:

java.lang.IllegalArgumentException -

• ERROR_NULL_ARGUMENT - if the listener is null

org.eclipse.swt.SWTException -

• ERROR_WIDGET_DISPOSED - if the receiver has been disposed
• ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver

See Also:

ModifyListener, removeModifyListener(org.eclipse.swt.events.ModifyListener)

removeModifyListener

public void removeModifyListener(org.eclipse.swt.events.ModifyListener listener)

Removes the listener from the collection of listeners who will be notified when the receiver's text is modified.

Parameters:

listener - the listener which should no longer be notified

Throws:

java.lang.IllegalArgumentException -

• ERROR_NULL_ARGUMENT - if the listener is null

org.eclipse.swt.SWTException -

• ERROR_WIDGET_DISPOSED - if the receiver has been disposed
• ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver

See Also:

ModifyListener, addModifyListener(org.eclipse.swt.events.ModifyListener)

notifyModifyListeners

public void notifyModifyListeners(org.eclipse.swt.events.ModifyEvent event)

Notifies all of the receiver's listeners when the receiver's text is modified.

Parameters:

eventType - the type of event which has occurred

event - the event data

Throws:

org.eclipse.swt.SWTException -

• ERROR_WIDGET_DISPOSED - if the receiver has been disposed
• ERROR_THREAD_INVALID_ACCESS - if not called from the thread that created the receiver

See Also:

addModifyListener(ModifyListener), removeModifyListener(ModifyListener)

addJavaCallbackListener

public void addJavaCallbackListener(JavaCallbackListener listener)

Add a JavaCallbackListener that is triggered on executing a Java callback via custom ToolbarButton.

Parameters:

listener - The JavaCallbackListener to add.

removeJavaCallbackListener

public void removeJavaCallbackListener(JavaCallbackListener listener)

Remove a JavaCallbackListener that is triggered on executing a Java callback via custom ToolbarButton.

Parameters:

listener - The JavaCallbackListener to remove.