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, org.openide.util.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, ...

  • Constructor Details

    • ObjectScene

      public ObjectScene()

  • Method Details

    • 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 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