org.netbeans.api.visual.model

Class ObjectScene

java.lang.Object

org.netbeans.api.visual.widget.Widget

org.netbeans.api.visual.widget.Scene

org.netbeans.api.visual.model.ObjectScene

All Implemented Interfaces:

Accessible, Lookup.Provider

Direct Known Subclasses:

GraphPinScene, GraphScene

public class ObjectScene
extends Scene

This class manages mapping between model-objects and widgets on a scene. Object mapping is added/removed using addObject and removeObject methods. You can query the mapping using the findWidget(Object) and the findObject(Widget) methods.

It also manages object-oriented states and creates a object-specific action that could be assigned to widgets to provide functionality like object-based selection, object-based hovering, ...

Nested Class Summary

Nested classes/interfaces inherited from class org.netbeans.api.visual.widget.Scene

Scene.SceneListener

Nested classes/interfaces inherited from class org.netbeans.api.visual.widget.Widget

Widget.Dependency

Constructor Summary

Constructors

Constructor and Description
ObjectScene()

Method Summary

Modifier and Type	Method and Description
void	addObject(Object object, Widget... widgets) Adds a mapping between an object and a widget.
void	addObjectSceneListener(ObjectSceneListener listener, ObjectSceneEventType... types) Adds object scene listener for specified object scene event types.
void	clearObjectState(Object object) Removes the object's state, removes the object from selection, hover etc.
WidgetAction	createObjectHoverAction() Returns a object-oriented hover action.
WidgetAction	createSelectAction() Creates a object-oriented select action.
Object	findObject(Widget widget) Returns an object which is assigned to a widget.
protected ObjectState	findObjectState(Object o) Finds the state for the given object.
Object	findStoredObject(Object object) Returns an instance of stored object.
Widget	findWidget(Object object) Returns the widget that is mapped to a specified object.
List<Widget>	findWidgets(Object object) Returns a list of all widgets that are mapped to a specified object.
Object	getFocusedObject() Returns a focused object.
Set<?>	getHighlightedObjects() Returns a set of highlighted objects.
Object	getHoveredObject() Returns a hovered object.
Comparable	getIdentityCode(Object object) This method returns an identity code.
Set<?>	getObjects() Returns a set of objects with registered mapping.
ObjectState	getObjectState(Object object) Returns an object-state of a specified object.
Set<?>	getSelectedObjects() Returns a set of selected objects.
boolean	isObject(Object object) Returns whether a specified object is registered.
void	removeObject(Object object) Removes a mapping for an object.
void	removeObjectMapping(Object object) Removes mapping for an object.
void	removeObjectSceneListener(ObjectSceneListener listener, ObjectSceneEventType... types) Removes object scene listener for specified object scene event types.
void	setFocusedObject(Object focusedObject) Sets a focused object.
void	setHighlightedObjects(Set<?> highlightedObjects) Sets a set of highlighted objects.
void	setHoveredObject(Object hoveredObject) Sets a hovered object.
void	setSelectedObjects(Set<?> selectedObjects) Sets a set of selected objects.
void	userSelectionSuggested(Set<?> suggestedSelectedObjects, boolean invertSelection) Set by actions for setting selected objects invoked by an user.

Methods inherited from class org.netbeans.api.visual.widget.Scene

addSceneListener, convertSceneToView, convertSceneToView, convertViewToScene, convertViewToScene, createBirdView, createSatelliteView, createView, createWidgetHoverAction, getActiveTool, getDefaultFont, getFocusedWidget, getGraphics, getInputBindings, getKeyEventProcessingType, getLookFeel, getMaximumBounds, getPriorActions, getResourceTable, getSceneAnimator, getView, getZoomFactor, isRepaintRequiredForRevalidating, isValidated, paint, removeSceneListener, setActiveTool, setFocusedWidget, setKeyEventProcessingType, setLookFeel, setMaximumBounds, setResourceTable, setZoomFactor, validate, validate

Methods inherited from class org.netbeans.api.visual.widget.Widget

addChild, addChild, addChild, addChild, addChildren, addDependency, bringToBack, bringToFront, calculateClientArea, convertLocalToScene, convertLocalToScene, convertSceneToLocal, convertSceneToLocal, createActions, equals, getAccessibleContext, getActions, getActions, getBackground, getBorder, getBounds, getChildConstraint, getChildren, getClientArea, getCursor, getCursorAt, getDependencies, getFont, getForeground, getLayout, getLocation, getLookup, getMaximumSize, getMinimumSize, getParentWidget, getPreferredBounds, getPreferredLocation, getPreferredSize, getScene, getState, getToolTipText, hashCode, isCheckClipping, isEnabled, isHitAt, isOpaque, isPreferredBoundsSet, isVisible, notifyAdded, notifyBackgroundChanged, notifyFontChanged, notifyForegroundChanged, notifyRemoved, notifyStateChanged, paint, paintBackground, paintBorder, paintChildren, paintWidget, removeChild, removeChildren, removeChildren, removeDependency, removeFromParent, repaint, resolveBounds, revalidate, revalidate, setAccessibleContext, setBackground, setBackgroundFromResource, setBorder, setBorder, setCheckClipping, setChildConstraint, setCursor, setEnabled, setFont, setFontFromResource, setForeground, setForegroundFromResource, setLayout, setMaximumSize, setMinimumSize, setOpaque, setPreferredBounds, setPreferredLocation, setPreferredSize, setState, setToolTipText, setVisible, updateResources

Methods inherited from class java.lang.Object

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

Constructor Detail

ObjectScene

public ObjectScene()

Method Detail

addObject

public final void addObject(Object object,
                            Widget... widgets)

Adds a mapping between an object and a widget. Note that it does not add the widget into the scene automatically - it has to be done manually before this method is called.

Parameters:

object - the model object; the object must not be a Widget

widgets - the scene widgets; if it is empty or it is a single null value then the object is non-visual and does not have any widget assigned; otherwise the widgets cannot contain null values

removeObjectMapping

public final void removeObjectMapping(Object object)

Removes mapping for an object. The caller is responsible for removing widgets from the scene before this call. If the object is already removed or did not exist, the method does nothing. The method will not clear object's state.

As ObjectScene.addObject(java.lang.Object, org.netbeans.api.visual.widget.Widget...) allows to add object-widget mapping as the user works with the scene, this method allows to remove such mapping. Selection, highlight and other flags remain unchanged.

Parameters:

object - object, whose mapping should be removed

Since:

2.49

clearObjectState

public void clearObjectState(Object object)

Removes the object's state, removes the object from selection, hover etc. Does not deregister the object or remove its widgets.

Parameters:

object - to clear

Since:

2.49

removeObject

public final void removeObject(Object object)

Removes a mapping for an object. Note that it does not remove the widget from the scene automatically - it has to be done manually after this method is called.

Parameters:

object - the object for which the mapping is removed

getObjects

public final Set<?> getObjects()

Returns a set of objects with registered mapping.

Returns:

the set of register objects

isObject

public final boolean isObject(Object object)

Returns whether a specified object is registered.

Parameters:

object - the object to be checked

Returns:

true if the object is register; false if the object is not registered

getSelectedObjects

public final Set<?> getSelectedObjects()

Returns a set of selected objects.

Returns:

the set of selected objects

setSelectedObjects

public final void setSelectedObjects(Set<?> selectedObjects)

Sets a set of selected objects.

Parameters:

selectedObjects - the set of selected objects

getHighlightedObjects

public final Set<?> getHighlightedObjects()

Returns a set of highlighted objects.

Returns:

the set of highlighted objects

setHighlightedObjects

public final void setHighlightedObjects(Set<?> highlightedObjects)

Sets a set of highlighted objects.

Parameters:

highlightedObjects - the set of highlighted objects

getHoveredObject

public final Object getHoveredObject()

Returns a hovered object. There could be only one hovered object at maximum at the same time.

Returns:

the hovered object; null if no object is hovered

setHoveredObject

public final void setHoveredObject(Object hoveredObject)

Sets a hovered object.

Parameters:

hoveredObject - the hovered object; if null, then the scene does not have hovered object

getFocusedObject

public final Object getFocusedObject()

Returns a focused object. There could be only one focused object at maximum at the same time.

Returns:

the focused object; null if no object is focused

setFocusedObject

public final void setFocusedObject(Object focusedObject)

Sets a focused object.

Parameters:

focusedObject - the focused object; if null, then the scene does not have focused object

createSelectAction

public final WidgetAction createSelectAction()

Creates a object-oriented select action.

Returns:

the object-oriented select action

createObjectHoverAction

public final WidgetAction createObjectHoverAction()

Returns a object-oriented hover action.

Returns:

the object-oriented hover action

findWidget

public final Widget findWidget(Object object)

Returns the widget that is mapped to a specified object.

Parameters:

object - the object; must not be a Widget

Returns:

the widget from the registered mapping; null if the object is non-visual or no mapping is registered

findWidgets

public final List<Widget> findWidgets(Object object)

Returns a list of all widgets that are mapped to a specified object.

Parameters:

object - the object; must not be a Widget

Returns:

the list of all widgets from the registered mapping; empty list if the object is non-visual; null if no mapping is registered

findObject

public final Object findObject(Widget widget)

Returns an object which is assigned to a widget. If the widget is not mapped to any object then the method recursively searches for an object of the parent widget.

Parameters:

widget - the widget

Returns:

the mapped object; null if no object is assigned to a widget or any of its parent widgets

findStoredObject

public final Object findStoredObject(Object object)

Returns an instance of stored object. It searches for an instance of an object stored internally in the class using "equals" method on an object.

Parameters:

object - the object that is equals (observed by calling the "equals" method on the instances stored in the class); the object must not be a Widget

Returns:

the stored instance of the object

getObjectState

public final ObjectState getObjectState(Object object)

Returns an object-state of a specified object.

Parameters:

object - the object

Returns:

the object-state of the specified object; null if the object is not registered

userSelectionSuggested

public void userSelectionSuggested(Set<?> suggestedSelectedObjects,
                                   boolean invertSelection)

Set by actions for setting selected objects invoked by an user.

Parameters:

suggestedSelectedObjects - the selected objects suggested by an user

invertSelection - the invert selection is specified by an user

getIdentityCode

public Comparable getIdentityCode(Object object)

This method returns an identity code. It should be unique for each object in the scene. The identity code is a Comparable and could be used for sorting. The method implementation should be fast.

Parameters:

object - the object

Returns:

the identity code of the object; null, if the object is null

addObjectSceneListener

public final void addObjectSceneListener(ObjectSceneListener listener,
                                         ObjectSceneEventType... types)

Adds object scene listener for specified object scene event types.

Parameters:

listener - the object scene listener

types - the object scene event types

removeObjectSceneListener

public final void removeObjectSceneListener(ObjectSceneListener listener,
                                            ObjectSceneEventType... types)

Removes object scene listener for specified object scene event types.

Parameters:

listener - the object scene listener

types - the object scene event types

findObjectState

protected ObjectState findObjectState(Object o)
                               throws IllegalArgumentException

Finds the state for the given object. The object must be a valid part of the model, although it may not be registered yet and no widgets are created for it. The method may return null for instances that are not proper models for the scene. The default method returns ObjectState.createNormal() for all inputs.

Note that even objects, which have currently no widgets can have ObjectState associated. For example objects, for which the widgets were not created yet, or whose widgets were removed.

Parameters:

o - the object

Returns:

the ObjectState or null for objects that cannot be part of the model.

Throws:

IllegalArgumentException

Since:

2.49