ro.sync.ecss.extensions.api.editor
Interface InplaceEditor

All Superinterfaces:

Extension

All Known Implementing Classes:

AbstractInplaceEditor, AbstractInplaceEditorWrapper, InplaceEditorAdapter, InplaceEditorRendererAdapter, SimpleURLChooserEditor, URLChooserEditorSWT

@API(type=EXTENDABLE,
     src=PUBLIC)
public interface InplaceEditor
extends Extension

An author in-place editor. Subclasses contain implementation based on real SWT or Swing components like combo boxes, text fields, check boxes, buttons etc.

An editor is associated with an oxy_editor CSS function and is invoked on user interaction. It only handles edit requests while the InplaceRenderer will handle the painting of the value to edit.

An editor implementation is used through the oxy_editor function like this:

 code {
   content: 
     "Attr1: " oxy_editor(type, combo, edit, '@attr1')
     "Attr2: " oxy_editor(type, text, edit, '@attr2')
  }
 

In the previous example a predefined combo editor is requested for editing the value of attribute attr1 and a predefined text editor for editing attribute attr2. For a custom implementation properties InplaceEditorCSSConstants.PROPERTY_SWING_EDITOR_CLASS_NAME and InplaceEditorCSSConstants.PROPERTY_SWT_EDITOR_CLASS_NAME must be used:

 myElement {
   content: oxy_editor(
       rendererClassName, "com.custom.editors.CustomRenderer",
       swingEditorClassName, "com.custom.editors.SwingCustomEditor",
       swtEditorClassName, "com.custom.editors.SwtCustomEditor",
       edit, "@my_attr"
       customProperty1, "customValue1",
       customProperty2, "customValue2"
   )
 }
 

In the previous example, the editor classes com.custom.editors.SwingCustomEditor and com.custom.editors.SwtCustomEditor must be added in the Classpath of the document type associated with the edited document.

It is recommended to extend the adapter class InplaceEditorRendererAdapter or InplaceEditorAdapter in order to be protected from future API additions.

A SWT implementation should also implement org.eclipse.jface.text.ITextOperationTarget so that it will be delegated with events of UNDO, REDO, CUT, PASTE, SELECT ALL.

Since:

14.1

*********************************
EXPERIMENTAL - Subject to change
********************************

Please note that this API is not marked as final and it can change in one of the next versions of the application. If you have suggestions, comments about it, please let us know.

See Also:

SimpleURLChooserEditor, URLChooserEditorSWT

Method Summary

void	addEditingListener(InplaceEditingListener editingListener) Adds a listener to receive edit notifications: - InplaceEditingListener.editingCanceled() to remove the editor and cancel the edit operation.
void	cancelEditing() Cancels the editing process.
java.lang.Object	getEditorComponent(AuthorInplaceContext context, Rectangle allocation, Point mouseInvocationLocation) Prepare and return the editor component.
Rectangle	getScrollRectangle() Returns a rectangle that should be made visible after the editor is shown.
java.lang.Object	getValue() Gets the value that the user entered.
void	removeEditingListener(InplaceEditingListener editingListener) Removes a listener that receives editing events.
void	requestFocus() Requests focus inside the editing component.
void	stopEditing() Stops the editing and commits the current value.

Methods inherited from interface ro.sync.ecss.extensions.api.Extension

getDescription

Method Detail

getEditorComponent

java.lang.Object getEditorComponent(AuthorInplaceContext context,
                                    Rectangle allocation,
                                    Point mouseInvocationLocation)

Prepare and return the editor component.

Parameters:

context - The context where the editor will be used.

allocation - The bounds where the editor will be shown. This is normally the bounds of the box in which the value being edited is rendered. If the editor requires to be presented in different bounds it should alter this parameter. The X,Y coordinates are relative to the parent in which the editor will be added.

mouseInvocationLocation - if the editor was requested using the mouse this parameter represents the X,Y location where the event took place. It is relative to the parent in which the editor will be added. null if the editor wasn't requested through mouse interaction.

OBS: This is the very first call received by an editor. This ensures that the editor is properly initialized for the subsequent calls (like a requestFocus() call).
OBS: An editor implementation will have to add listeners onto itself like:

• a KeyListener for handling key events like: ENTER to stop editing (by calling InplaceEditingListener.editingStopped(EditingEvent)) and ESCAPE to cancel it (by calling InplaceEditingListener.editingCanceled()).
• a FocusListener to stop editing when the focus is given to a component that is not part of the editor (by calling InplaceEditingListener.editingStopped(EditingEvent)).
• a DocumentListener to fire InplaceEditingListener.editingOccured() events (If the editor has a document).

Returns:

The component that performs the editing. For the Standalone distribution this should be a java.awt.JComponent implementation. For the Eclipse plugin distribution, an org.eclipse.swt.widgets.Control is expected.

getScrollRectangle

Rectangle getScrollRectangle()

Returns a rectangle that should be made visible after the editor is shown. The coordinate should be relative to the editor itself. The default behavior is to make the entire editor visible but if the editor is bigger than the viewport the visible part might not be the right one. For example is the editor is a text field the caret might not be visible. This is when this method is useful. The caret rectangle should be returned so that the part of the editor with the caret is presented.

Returns:

A rectangle to be made visible or null to make the entire editor visible.

addEditingListener

void addEditingListener(InplaceEditingListener editingListener)

Adds a listener to receive edit notifications: - InplaceEditingListener.editingCanceled() to remove the editor and cancel the edit operation. - InplaceEditingListener.editingOccured() to signal modification in the editor. This event marks the editor as dirty and it's value will be committed when a InplaceEditingListener.editingStopped(EditingEvent) is received. - InplaceEditingListener.editingStopped(EditingEvent) to end editing and commit it's value if needed. The value is usually committed ONLY if a InplaceEditingListener.editingOccured() was fired. See InplaceEditingListener.editingStopped(EditingEvent) for more information.

Parameters:

editingListener - Editing listener.

requestFocus

void requestFocus()

Requests focus inside the editing component.

getValue

java.lang.Object getValue()

Gets the value that the user entered.

Returns:

The value that the user entered.

stopEditing

void stopEditing()

Stops the editing and commits the current value. The editor should release any held resources and notify InplaceEditingListener.editingStopped(EditingEvent). OBS: The current value will be committed only if at least one InplaceEditingListener.editingOccured() event was issued before this moment.

cancelEditing

void cancelEditing()

Cancels the editing process. The editor should release any held resources and notify InplaceEditingListener.editingCanceled().

removeEditingListener

void removeEditingListener(InplaceEditingListener editingListener)

Removes a listener that receives editing events.

Parameters:

editingListener - Editing listener.