org.netbeans.api.visual 2.10

org.netbeans.api.visual.widget
Class Widget

java.lang.Object
  extended by org.netbeans.api.visual.widget.Widget
All Implemented Interfaces:
Accessible
Direct Known Subclasses:
ComponentWidget, ConnectionWidget, ConvolveWidget, IconNodeWidget, ImageWidget, LabelWidget, LayerWidget, LevelOfDetailsWidget, ListWidget, Scene, ScrollWidget, SeparatorWidget, SwingScrollWidget, VMDGlyphSetWidget, VMDNodeWidget, VMDPinWidget

public class Widget
extends Object
implements Accessible

A scene is a tree of small building blocks called widgets and represented by this class.

Each widget has a origin location specified relatively to the location its parent widget and placement is specified be its boundary.

The widget is also responsible for rendering the region. The widget is an abstract implementation and does not have render anything except borders and background. There are various built-in widget each for a specific visualization. The widget also holds general properties like foreground, opacity, ... that could be reused by the high-level widgets.

The widget has a layout assigned. The layout takes care about resolving the placement of children widgets. For that it can use various properties like preferredLocation, preferredBounds, ... When the widget is resolved (placed) than the read only location and bounds properties contains resolved location and boundary of a widget.

Each widget has a chain of actions. Actions defined defines a behaviour of the widget. E.g. MoveAction makes the widget moveable. Also there is possible to create/assign other chains that will be activated based on the active tool of a scene.

The widget have its state specified by ObjectState class. When the widget state is change, notifyStateChanged is called to notify about it. The state is automatically updated by high-level scenes and actions. Yherefore you can define your own look and feel directly in the that method. Since version 2.6 Widget class implements Accessible interface.


Nested Class Summary
static interface Widget.Dependency
          The dependency listener which is used for notifying dependent widgets, anchor, ...
 
Constructor Summary
Widget(Scene scene)
          Creates a new widget which will be used in a specified scene.
 
Method Summary
 void addChild(int index, Widget child)
          Adds a child at a specified index
 void addChild(int index, Widget child, Object constraint)
          Adds a child at a specified index
 void addChild(Widget child)
          Adds a child widget as the last one.
 void addChild(Widget child, Object constraint)
          Adds a child widget as the last one.
 void addChildren(List<? extends Widget> children)
          Adds all children in a specified list.
 void addDependency(Widget.Dependency dependency)
          Adds a dependency listener which is notified when the widget placement or boundary is going to be changed or similar thing happens to its parent widget.
 void bringToBack()
          Brings the widget to the back.
 void bringToFront()
          Brings the widget to the front.
protected  Rectangle calculateClientArea()
          Called to calculate the client area required by the widget without the children widgets.
 Point convertLocalToScene(Point localLocation)
          Converts a location in the local coordination system to the scene coordination system.
 Rectangle convertLocalToScene(Rectangle localRectangle)
          Converts a rectangle in the local coordination system to the scene coordination system.
 Point convertSceneToLocal(Point sceneLocation)
          Converts a location in the scene coordination system to the local coordination system.
 Rectangle convertSceneToLocal(Rectangle sceneRectangle)
          Converts a rectangle in the scene coordination system to the local coordination system.
 WidgetAction.Chain createActions(String tool)
          Creates and returns an action chain for a specified tool.
 boolean equals(Object object)
          Returns whether a specified object is the same as the widget.
 AccessibleContext getAccessibleContext()
          Returns an accessible context of the widget.
 WidgetAction.Chain getActions()
          Returns a default action chain.
 WidgetAction.Chain getActions(String tool)
          Returns already created action chain for a specified tool.
 Paint getBackground()
          Returns the widget background paint.
 Border getBorder()
          Returns the border of the widget.
 Rectangle getBounds()
          Returns the resolved bounds of the widget.
 Object getChildConstraint(Widget child)
          Returns constraint assigned to a specified child widget.
 List<Widget> getChildren()
          Returns a list of children widgets.
 Rectangle getClientArea()
          Returns a client area of the widget.
 Cursor getCursor()
          Returns a mouse cursor for the widget.
protected  Cursor getCursorAt(Point localLocation)
          Returns a mouse cursor for a specified local location in the widget.
 Collection<Widget.Dependency> getDependencies()
          Returns a collection of registered dependencies.
 Font getFont()
          Returns the font assigned to the widget.
 Color getForeground()
          Returns the widget foreground color.
protected  Graphics2D getGraphics()
          Returns a Graphics2D instance with is assigned to the scene.
 Layout getLayout()
          Returns the layout of the widget.
 Point getLocation()
          Returns the resolved location of the widget.
 Lookup getLookup()
          Returns a lookup of the widget.
 Dimension getMaximumSize()
          Returns a maximum size of the widget.
 Dimension getMinimumSize()
          Returns a minimum size of the widget.
 Widget getParentWidget()
          Returns a parent widget.
 Rectangle getPreferredBounds()
          Returns a preferred bounds relatively to the location of the widget.
 Point getPreferredLocation()
          Returns a preferred location of the widget.
 Dimension getPreferredSize()
          Returns a preferred size of the widget.
 Scene getScene()
          Returns a scene where the widget is assigned
 ObjectState getState()
          Returns a state of the widget.
 String getToolTipText()
          Returns a tool-tip text of the widget.
 int hashCode()
          Returns the object hash code.
 boolean isCheckClipping()
          Returns whether clipping is used in the widget.
 boolean isEnabled()
          Returns whether the widget is enabled.
 boolean isHitAt(Point localLocation)
          Called to whether a particular location in local coordination system is controlled (otionally also painted) by the widget.
 boolean isOpaque()
          Returns whether the widget is opaque.
 boolean isPreferredBoundsSet()
          Returns whether a preferred bounds are set.
protected  boolean isRepaintRequiredForRevalidating()
          Returns whether whole area of the widget has to be repainted after the validation of the widget.
 boolean isValidated()
          Returns true if the widget is validated (is not scheduled to revalidation).
 boolean isVisible()
          Returns whether the widget is visible.
protected  void notifyAdded()
          This method is called to notify that the view is shown.
protected  void notifyRemoved()
          This method is called to notify that the view is hidden.
protected  void notifyStateChanged(ObjectState previousState, ObjectState state)
          Called to notify about the change of the widget state.
 void paint()
          Paints the widget with its children widget into the Graphics2D instance acquired from Scene.getGraphics method.
protected  void paintBackground()
          Called to paint the widget background itself only using the Graphics2D instance acquired from Scene.getGraphics method.
protected  void paintBorder()
          Called to paint the widget border itself only using the Graphics2D instance acquired from Scene.getGraphics method.
protected  void paintChildren()
          Called to paint the children widgets only using the Graphics2D instance acquired from Scene.getGraphics method.
protected  void paintWidget()
          Called to paint the widget itself only using the Graphics2D instance acquired from Scene.getGraphics method.
 void removeChild(Widget child)
          Removes a child widget.
 void removeChildren()
          Removes all children widgets.
 void removeChildren(List<Widget> widgets)
          Removes all children widget that are in a specified list.
 void removeDependency(Widget.Dependency dependency)
          Removes a dependency listener.
 void removeFromParent()
          Removes the widget from its parent.
 void repaint()
          Schedules the widget for repainting.
 void resolveBounds(Point location, Rectangle bounds)
          Sets resolved location and bounds of the widget This method is usually called from implementations of Layout interface.
 void revalidate()
          Schedules the widget for revalidation.
 void revalidate(boolean repaintOnly)
          Schedules the widget to repaint or revalidation.
 void setAccessibleContext(AccessibleContext accessibleContext)
          Sets a accessible context of the widget.
 void setBackground(Paint background)
          Sets the widget background paint.
 void setBorder(Border border)
          Sets the border of the widget.
 void setBorder(Border swingBorder)
          Sets the Swing layout as the border of the widget.
 void setCheckClipping(boolean checkClipping)
          Sets a clipping for the widget.
 void setChildConstraint(Widget child, Object constraint)
          Assigns a constraint to a child widget.
 void setCursor(Cursor cursor)
          Sets a cursor for the widget.
 void setEnabled(boolean enabled)
          Sets whether the widget is enabled.
 void setFont(Font font)
          Sets the widget font.
 void setForeground(Color foreground)
          Sets the widget foreground color.
 void setLayout(Layout layout)
          Sets the layout of the widget.
 void setMaximumSize(Dimension maximumSize)
          Sets a maximum size of the widget
 void setMinimumSize(Dimension minimumSize)
          Sets a minumum size of the widget
 void setOpaque(boolean opaque)
          Sets the widget opacity.
 void setPreferredBounds(Rectangle preferredBounds)
          Sets a preferred bounds that are specified relatively to the location of the widget.
 void setPreferredLocation(Point preferredLocation)
          Sets a preferred location of the widget.
 void setPreferredSize(Dimension preferredSize)
          Sets a preferred size of the widget
 void setState(ObjectState state)
          Sets a state of the widget.
 void setToolTipText(String toolTipText)
          Sets a tool-tip of the widget.
 void setVisible(boolean visible)
          Sets whether the widget is visible.
 
Methods inherited from class java.lang.Object
clone, finalize, getClass, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

Widget

public Widget(Scene scene)
Creates a new widget which will be used in a specified scene.

Parameters:
scene - the scene where the widget is going to be used
Method Detail

getScene

public final Scene getScene()
Returns a scene where the widget is assigned

Returns:
the scene

getGraphics

protected Graphics2D getGraphics()
Returns a Graphics2D instance with is assigned to the scene. Usually used in the calculatedClientArea and paintWidget method.

Returns:
the Graphics2D instance; null if the scene view is not created or visible yet

getParentWidget

public final Widget getParentWidget()
Returns a parent widget.

Returns:
the parent widget

getChildren

public final List<Widget> getChildren()
Returns a list of children widgets.

Returns:
the list of children widgets

addChild

public final void addChild(Widget child)
Adds a child widget as the last one.

Parameters:
child - the child widget to be added

addChild

public final void addChild(Widget child,
                           Object constraint)
Adds a child widget as the last one.

Parameters:
child - the child widget to be added
constraint - the constraint assigned to the child widget

addChild

public final void addChild(int index,
                           Widget child)
Adds a child at a specified index

Parameters:
index - the index (the child is added before the one that is not the index place)
child - the child widget

addChild

public final void addChild(int index,
                           Widget child,
                           Object constraint)
Adds a child at a specified index

Parameters:
index - the index (the child is added before the one that is not the index place)
child - the child widget
constraint - the constraint assigned to the child widget

removeChild

public final void removeChild(Widget child)
Removes a child widget.

Parameters:
child - the child widget

removeFromParent

public final void removeFromParent()
Removes the widget from its parent.


removeChildren

public final void removeChildren()
Removes all children widgets.


addChildren

public final void addChildren(List<? extends Widget> children)
Adds all children in a specified list.

Parameters:
children - the list of children widgets

removeChildren

public final void removeChildren(List<Widget> widgets)
Removes all children widget that are in a specified list.

Parameters:
widgets - the list of children widgets to be removed

notifyAdded

protected void notifyAdded()
This method is called to notify that the view is shown. Note: You must not modify a tree of widgets from within this method. It means: do not call addChild, removeChild and similar methods.


notifyRemoved

protected void notifyRemoved()
This method is called to notify that the view is hidden. Note: You must not modify a tree of widgets from within this method. It means: do not call addChild, removeChild and similar methods.


bringToFront

public final void bringToFront()
Brings the widget to the front. Means: the widget becomes the last child in the list of children of the parent widget.


bringToBack

public final void bringToBack()
Brings the widget to the back. Means: the widget becomes the first child in the list of children of the parent widget.


getChildConstraint

public final Object getChildConstraint(Widget child)
Returns constraint assigned to a specified child widget.

Parameters:
child - the child widget
Returns:
the constraint

setChildConstraint

public final void setChildConstraint(Widget child,
                                     Object constraint)
Assigns a constraint to a child widget.

Parameters:
child - the child widget
constraint - the constraint

isVisible

public final boolean isVisible()
Returns whether the widget is visible.

Returns:
true if the widget is visible

setVisible

public final void setVisible(boolean visible)
Sets whether the widget is visible.

Parameters:
visible - if true, then the widget is visible

isEnabled

public final boolean isEnabled()
Returns whether the widget is enabled. If the widget is disabled then any event is processed by assigned actions.

Returns:
true if the widget is enabled.

setEnabled

public final void setEnabled(boolean enabled)
Sets whether the widget is enabled. If the widget is disabled then any event is processed by assigned actions.

Parameters:
enabled - if true, then the widget is enabled

getActions

public final WidgetAction.Chain getActions()
Returns a default action chain.

Returns:
the default action chain.

getActions

public final WidgetAction.Chain getActions(String tool)
Returns already created action chain for a specified tool.

Parameters:
tool - the tool
Returns:
the action chain; null, if no chain for the tool exists

createActions

public final WidgetAction.Chain createActions(String tool)
Creates and returns an action chain for a specified tool.

Parameters:
tool - the tool
Returns:
the action chain

getLookup

public Lookup getLookup()
Returns a lookup of the widget.

Returns:
the lookup

addDependency

public final void addDependency(Widget.Dependency dependency)
Adds a dependency listener which is notified when the widget placement or boundary is going to be changed or similar thing happens to its parent widget.

Parameters:
dependency - the dependency listener

removeDependency

public final void removeDependency(Widget.Dependency dependency)
Removes a dependency listener.

Parameters:
dependency - the dependency listener

getDependencies

public final Collection<Widget.Dependency> getDependencies()
Returns a collection of registered dependencies.

Returns:
the unmodifiable collection of dependencies
Since:
2.6

isOpaque

public final boolean isOpaque()
Returns whether the widget is opaque.

Returns:
true, if the widget is opaque

setOpaque

public final void setOpaque(boolean opaque)
Sets the widget opacity.

Parameters:
opaque - if true, then the widget is opaque

getBackground

public final Paint getBackground()
Returns the widget background paint.

Returns:
the background paint

setBackground

public final void setBackground(Paint background)
Sets the widget background paint.

Parameters:
background - the background paint

getForeground

public final Color getForeground()
Returns the widget foreground color.

Returns:
the foreground color

setForeground

public final void setForeground(Color foreground)
Sets the widget foreground color.

Parameters:
foreground - the foreground color

getFont

public final Font getFont()
Returns the font assigned to the widget. If not set yet, then it returns the font of its parent widget.

Returns:
the font

setFont

public final void setFont(Font font)
Sets the widget font.

Parameters:
font - the font; if null, then widget unassignes its font.

getBorder

public final Border getBorder()
Returns the border of the widget.

Returns:
the border

setBorder

public final void setBorder(Border border)
Sets the border of the widget.

Parameters:
border - the border

setBorder

public final void setBorder(Border swingBorder)
Sets the Swing layout as the border of the widget.

Parameters:
swingBorder - the Swing border

getLayout

public final Layout getLayout()
Returns the layout of the widget.

Returns:
the layout

setLayout

public final void setLayout(Layout layout)
Sets the layout of the widget.

Parameters:
layout - the layout

getMinimumSize

public final Dimension getMinimumSize()
Returns a minimum size of the widget.

Returns:
the minimum size; if null, then no minumum size are set.

setMinimumSize

public final void setMinimumSize(Dimension minimumSize)
Sets a minumum size of the widget

Parameters:
minimumSize - the minimum size; if null, then minimum size are unset.

getMaximumSize

public final Dimension getMaximumSize()
Returns a maximum size of the widget.

Returns:
the maximum size; if null, then no maximum size are set.

setMaximumSize

public final void setMaximumSize(Dimension maximumSize)
Sets a maximum size of the widget

Parameters:
maximumSize - the maximum size; if null, then maximum size are unset.

getPreferredSize

public final Dimension getPreferredSize()
Returns a preferred size of the widget.

Returns:
the preferred size; if null, then no preferred size are set.

setPreferredSize

public final void setPreferredSize(Dimension preferredSize)
Sets a preferred size of the widget

Parameters:
preferredSize - the preferred size; if null, then preferred size are unset.

getPreferredLocation

public final Point getPreferredLocation()
Returns a preferred location of the widget.

Returns:
the preferred location; if null, then no preferred location is set

setPreferredLocation

public final void setPreferredLocation(Point preferredLocation)
Sets a preferred location of the widget.

Parameters:
preferredLocation - the preferred location; if null, then the preferred location is unset

isPreferredBoundsSet

public final boolean isPreferredBoundsSet()
Returns whether a preferred bounds are set.

Returns:
true, if preferred bounds are set

getPreferredBounds

public final Rectangle getPreferredBounds()
Returns a preferred bounds relatively to the location of the widget. If no preferred bounds are set, then it returns a preferred bounds that are calculated from the calculateClientArea method of this widget and location and bounds of the children widgets. This calculated bounds are processed by the minimum and maximum bounds too.

This method can be called after child widgets are layed out which is assured in method calls of the Layout interface implementation. If preferred bounds are set (check it using isPreferredBoundsSet method), you can call this method at any time.

Returns:
the preferred bounds

calculateClientArea

protected Rectangle calculateClientArea()
Called to calculate the client area required by the widget without the children widgets.

Returns:
the calculated client area

setPreferredBounds

public final void setPreferredBounds(Rectangle preferredBounds)
Sets a preferred bounds that are specified relatively to the location of the widget.

Parameters:
preferredBounds - the preferred bounds; if null, then the preferred bounds are unset

isCheckClipping

public final boolean isCheckClipping()
Returns whether clipping is used in the widget.

Returns:
true, if the check clipping is used

setCheckClipping

public final void setCheckClipping(boolean checkClipping)
Sets a clipping for the widget.

Parameters:
checkClipping - if true, then the clipping is used

getCursorAt

protected Cursor getCursorAt(Point localLocation)
Returns a mouse cursor for a specified local location in the widget.

Parameters:
localLocation - the local location
Returns:
the mouse cursor; default implementation return value of cursor property.
Since:
2.3

getCursor

public final Cursor getCursor()
Returns a mouse cursor for the widget.

Returns:
the mouse cursor

setCursor

public final void setCursor(Cursor cursor)
Sets a cursor for the widget.

Parameters:
cursor - the mouse cursor; if null, the cursor is unset

getToolTipText

public final String getToolTipText()
Returns a tool-tip text of the widget.

Returns:
the tool-tip text

setToolTipText

public final void setToolTipText(String toolTipText)
Sets a tool-tip of the widget.

Parameters:
toolTipText - the tool tip text

getAccessibleContext

public final AccessibleContext getAccessibleContext()
Returns an accessible context of the widget.

Specified by:
getAccessibleContext in interface Accessible
Returns:
the accessible context

setAccessibleContext

public final void setAccessibleContext(AccessibleContext accessibleContext)
Sets a accessible context of the widget.

Parameters:
accessibleContext - the accessible context

getState

public final ObjectState getState()
Returns a state of the widget.

Returns:
the widget state

setState

public final void setState(ObjectState state)
Sets a state of the widget.

Parameters:
state - the widget state

notifyStateChanged

protected void notifyStateChanged(ObjectState previousState,
                                  ObjectState state)
Called to notify about the change of the widget state.

Parameters:
previousState - the previous state
state - the new state

convertLocalToScene

public final Point convertLocalToScene(Point localLocation)
Converts a location in the local coordination system to the scene coordination system.

Parameters:
localLocation - the local location
Returns:
the scene location

convertLocalToScene

public final Rectangle convertLocalToScene(Rectangle localRectangle)
Converts a rectangle in the local coordination system to the scene coordination system.

Parameters:
localRectangle - the local rectangle
Returns:
the scene rectangle

convertSceneToLocal

public final Point convertSceneToLocal(Point sceneLocation)
Converts a location in the scene coordination system to the local coordination system.

Parameters:
sceneLocation - the scene location
Returns:
the local location

convertSceneToLocal

public final Rectangle convertSceneToLocal(Rectangle sceneRectangle)
Converts a rectangle in the scene coordination system to the local coordination system.

Parameters:
sceneRectangle - the scene rectangle
Returns:
the local rectangle

getLocation

public final Point getLocation()
Returns the resolved location of the widget. The location is specified relatively to the location of the parent widget.

The location is resolved/set by calling resolveBounds method which should be called from Layout interface implementation only. Therefore the corrent value is available only after the scene is validated (SceneListener.sceneValidated method). Before validation a previous/obsolete or [0,0] value could be returned. See Layout section in documentation.

Returns:
the location in the local coordination system of the parent widget

getBounds

public final Rectangle getBounds()
Returns the resolved bounds of the widget. The bounds are specified relatively to the location of the widget.

The location is resolved/set by calling resolveBounds method which should be called from Layout interface implementation only. Therefore the corrent value is available only after the scene is validated (SceneListener.sceneValidated method). Before validation a previous/obsolete or null value could be returned. See Layout section in documentation.

Returns:
the bounds in local coordination system

resolveBounds

public final void resolveBounds(Point location,
                                Rectangle bounds)
Sets resolved location and bounds of the widget This method is usually called from implementations of Layout interface.

Parameters:
location - the resolved location; if null then [0,0] point is used instead
bounds - the resolved bounds; if null then the preferred bounds are used instead

getClientArea

public final Rectangle getClientArea()
Returns a client area of the widget.

Returns:
the client area

isHitAt

public boolean isHitAt(Point localLocation)
Called to whether a particular location in local coordination system is controlled (otionally also painted) by the widget.

Parameters:
localLocation - the local location
Returns:
true, if the location belong to the widget

repaint

public final void repaint()
Schedules the widget for repainting.


isValidated

public boolean isValidated()
Returns true if the widget is validated (is not scheduled to revalidation).

Returns:
true, if is validated

revalidate

public final void revalidate(boolean repaintOnly)
Schedules the widget to repaint or revalidation.

Parameters:
repaintOnly - if true, then the widget is scheduled for repainting only; if false, then widget is scheduled for revalidation (the Scene.validate method has to be called after all changes to invoke validation)

revalidate

public final void revalidate()
Schedules the widget for revalidation. The Scene.validate method has to be called after all changes to invoke validation. In some cases it is invoked automatically.


isRepaintRequiredForRevalidating

protected boolean isRepaintRequiredForRevalidating()
Returns whether whole area of the widget has to be repainted after the validation of the widget. Used be LayerWidget for performance optiomalization.

Returns:
true, if requires; false, if does not require

paint

public final void paint()
Paints the widget with its children widget into the Graphics2D instance acquired from Scene.getGraphics method.


paintBackground

protected void paintBackground()
Called to paint the widget background itself only using the Graphics2D instance acquired from Scene.getGraphics method.


paintBorder

protected void paintBorder()
Called to paint the widget border itself only using the Graphics2D instance acquired from Scene.getGraphics method.

Since:
2.1

paintWidget

protected void paintWidget()
Called to paint the widget itself only using the Graphics2D instance acquired from Scene.getGraphics method.


paintChildren

protected void paintChildren()
Called to paint the children widgets only using the Graphics2D instance acquired from Scene.getGraphics method.


hashCode

public final int hashCode()
Returns the object hash code.

Overrides:
hashCode in class Object
Returns:
the object hash code

equals

public final boolean equals(Object object)
Returns whether a specified object is the same as the widget.

Overrides:
equals in class Object
Parameters:
object - the object
Returns:
true if the object reference is the same as the widget

org.netbeans.api.visual 2.10

Built on May 30 2008.  |  Portions Copyright 1997-2007 Sun Microsystems, Inc. All rights reserved.