quicktime.app.display
Class GroupDrawable

java.lang.Object
  |
  +--quicktime.app.spaces.SimpleSpace
        |
        +--quicktime.app.display.GroupDrawable
All Implemented Interfaces:
Collection, Drawable, DynamicCollection, Listener, QTDisplaySpace, QTDrawable, Space, Ticklish, Transformable
Direct Known Subclasses:
DirectGroup

public abstract class GroupDrawable
extends SimpleSpace
implements QTDisplaySpace

This forms the base class for grouping QTDrawable objects within a single display space that is controlled by this group.

QTDrawable are drawn in their layer order (Short.minimum value is frontmost, Short.maximum value is furthest back). You can change a position or size of a member by interacting directly with the QTDrawable member itself but you must notify the group of any changes in the display characteristics of the QTDrawable by calling memberChanged().

QTDrawable members can also be positioned within a GroupDrawable using alignment values. An alignment of 0 will place the member at the top and/or left position. An alignment value of 1 will place the member so that it's bottom and/or right is aligned with the bottom of the GroupDrawable's display space.

To reset the layer of an object you use the QTDrawable's Layerable object. QTDrawable objects do not contain any sense of layering, so the GroupDrawable uses the GroupMember objects to contain the information about a member's layer characteristics.

See Also:
DirectGroup

Field Summary
protected  Region clip
          The current clip region of the group
protected  java.util.Vector vec
          THis vector is used to store the members in.
 
Fields inherited from class quicktime.app.spaces.SimpleSpace
containedSpaces, controllersVec, ticklers, timer
 
Fields inherited from interface quicktime.app.time.Ticklish
kScale
 
Constructor Summary
protected GroupDrawable(java.awt.Dimension initialSize, QDColor bc, int scale, int period, Protocol p)
          Deprecated. since QTJava 4.0
protected GroupDrawable(QDDimension initialSize, QDColor bc, int scale, int period, Protocol p)
          Provided for subclasses to create a group drawable.
 
Method Summary
 Region getBackgroundClip()
          This method returns the clip that contains any space within the GroupDrawable that is not drawn upon by one of the members.
 QDColor getBackgroundColor()
          Returns the current background colour or null if no background colour.
 int getBackLayer()
          Returns the back most layer of any object in the group.
 Region getClip()
          This method allows you to get the current clipped Region of the Transformable.
 QDRect getDisplayBounds()
          This method is called automatically via the QTCanvas object associated with this client to set the boundary of the movie.
 int getFrontLayer()
          Returns the current front most layer of any object in the group.
 GroupMember getGroupMember(java.lang.Object member)
          Returns a GroupMember that contains the specified QTDrawable object or null if the requested item is not a member of this group.
 QDGraphics getGWorld()
          QTCanvas calls this method to get the destination QDGraphics of its client.
 java.awt.Dimension getInitialSize()
          Deprecated. since QTJava 4.0
 Layerable getLayerable(java.lang.Object member)
          Returns the Layerable object for a member (or null if the Object is not a member) that allows the application to get and set the layer of a member.
 Matrix getMatrix()
          This will return the client's current display transformations.
 QDDimension getOriginalSize()
          This method returns the original size before the transformations specified in the returned matrix are applied.
 Transformable getTransformable(java.lang.Object member)
          Returns the Transformable object that represents the member in the DisplaySpace.
 java.lang.Object hitTest(int x, int y)
          Returns the front most object located at the specified x and y pixel location or null if there is no object at the location
 boolean isEmpty()
          Returns true if the space does not have any members.
abstract  GroupMember memberChanged(QTDrawable d)
          This tells the group that the position or display size of the drawer has changed and it should do whatever actions are appropriate to reestablish the display integrity of the group.
 java.util.Enumeration members()
          Returns an iterator of QTDrawable members that are the items that are currently contained within the DirectGroup.
 void redraw(Region invalidRgn)
          QTCanvas calls this method when the client should redraw itself.
abstract  void redrawMember(QTDrawable d, Region invalidRgn)
          An optimized redraw that will redraw only those objects that it needs to based on the fact that the supplied drawer has changed but those behind or in front of it have not.
 void removeMember(java.lang.Object member)
          Remove a QTDrawable object from the Group of drawn items.
protected  void setAlignedMemberLocation(QTDrawable drawer, float xAlign, float yAlign)
          A helper method that is used to set the location of the member based on the x and y alignment.
 void setBackgroundColor(QDColor col)
          Sets the background color.
abstract  void setClip(Region theClip)
          This method allows you to set a Transformable's clipping region.
 void setDisplayBounds(QDRect bounds)
          This method is called automatically via the QTCanvas object associated with this client to set its boundary.
 void setGWorld(QDGraphics cgp)
          QTCanvas calls this method to give the client the QDGraphics object it should use to do its drawing.
 void setLocation(int x, int y)
          A convenience method to set the position of a QTDrawable object.
 void setMatrix(Matrix matrix)
          This method sets the current matrix of the Transformable object to the new matrix.
 boolean setMemberAlignment(QTDrawable d, float xAlign, float yAlign)
          This will reset an item's alignment and redraw the group.
 boolean setMemberLayer(QTDrawable member, int layer)
          This sets the layer of the incoming drawable to the new layer.
 int size()
          Returns the number of members in the collection, ie.
 
Methods inherited from class quicktime.app.spaces.SimpleSpace
addController, addedTo, addMember, controllers, finalize, getProtocol, getSource, getTimer, hasMember, isAppropriate, memberAdded, memberRemoved, removeAllControllers, removeAllMembers, removeController, removedFrom, tickle, tickleList, timeChanged
 
Methods inherited from class java.lang.Object
clone, equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 
Methods inherited from interface quicktime.app.display.QTDisplaySpace
addMember
 
Methods inherited from interface quicktime.app.spaces.Listener
addedTo, removedFrom
 
Methods inherited from interface quicktime.app.spaces.Space
addController, controllers, getSource, getTimer, removeController, tickleList
 
Methods inherited from interface quicktime.app.spaces.DynamicCollection
getProtocol
 
Methods inherited from interface quicktime.app.spaces.Collection
addMember, hasMember, isAppropriate
 
Methods inherited from interface quicktime.app.time.Ticklish
tickle, timeChanged
 

Field Detail

clip

protected Region clip
The current clip region of the group

vec

protected java.util.Vector vec
THis vector is used to store the members in. It is kept sorted by layer with the frontmost member in the first slot of the vector.
Constructor Detail

GroupDrawable

protected GroupDrawable(java.awt.Dimension initialSize,
                        QDColor bc,
                        int scale,
                        int period,
                        Protocol p)
                 throws QTException
Deprecated. since QTJava 4.0

Provided for subclasses to create a group drawable.
Parameters:
initialSize - initial size of the Drawable object
bc - the background color
scale - the scale of the Space's Timer
period - the period of the Space's Timer.
p - the Protocol that is enforced on candidate member objects of this group

GroupDrawable

protected GroupDrawable(QDDimension initialSize,
                        QDColor bc,
                        int scale,
                        int period,
                        Protocol p)
                 throws QTException
Provided for subclasses to create a group drawable.
Parameters:
initialSize - initial size of the Drawable object
bc - the background color
scale - the scale of the Space's Timer
period - the period of the Space's Timer.
p - the Protocol that is enforced on candidate member objects of this group
Method Detail

getGWorld

public QDGraphics getGWorld()
                     throws StdQTException
QTCanvas calls this method to get the destination QDGraphics of its client.
Specified by:
getGWorld in interface QTDrawable
Returns:
a QDGraphics object or null

setGWorld

public void setGWorld(QDGraphics cgp)
               throws QTException
QTCanvas calls this method to give the client the QDGraphics object it should use to do its drawing. If the incoming QDGraphics is the QDGraphics.scratch then the drawable will not be visible and can disable itself. If a client is unable to set the graphics world it should throw an exception.
Specified by:
setGWorld in interface QTDrawable
Parameters:
cgp - a QDGraphics object

setLocation

public void setLocation(int x,
                        int y)
                 throws QTException
A convenience method to set the position of a QTDrawable object.
Specified by:
setLocation in interface QTDrawable
Parameters:
x - the new x location
y - the new y location

setDisplayBounds

public void setDisplayBounds(QDRect bounds)
                      throws QTException
This method is called automatically via the QTCanvas object associated with this client to set its boundary.
Specified by:
setDisplayBounds in interface Drawable
Parameters:
bounds - a QDRect object describing the boundary

getDisplayBounds

public QDRect getDisplayBounds()
                        throws StdQTException
This method is called automatically via the QTCanvas object associated with this client to set the boundary of the movie.
Specified by:
getDisplayBounds in interface Drawable
Parameters:
bounds - a QDRect object describing the boundary

getBackgroundColor

public QDColor getBackgroundColor()
Returns the current background colour or null if no background colour.

setBackgroundColor

public void setBackgroundColor(QDColor col)
                        throws QTException
Sets the background color. This will force a redraw of the Compositor.

removeMember

public void removeMember(java.lang.Object member)
                  throws QTException
Remove a QTDrawable object from the Group of drawn items.
Specified by:
removeMember in interface Collection
Overrides:
removeMember in class SimpleSpace
Parameters:
QTDrawable - drawer the item to remove

members

public java.util.Enumeration members()
Returns an iterator of QTDrawable members that are the items that are currently contained within the DirectGroup.
Specified by:
members in interface Collection
Returns:
an Enumeration

isEmpty

public boolean isEmpty()
Returns true if the space does not have any members.
Specified by:
isEmpty in interface Collection
Returns:
a boolean

getGroupMember

public GroupMember getGroupMember(java.lang.Object member)
Returns a GroupMember that contains the specified QTDrawable object or null if the requested item is not a member of this group.
Parameters:
drawer - the QTDrawable object to search for.
Returns:
a GroupMember that contains the layer and alignment information for the member in this group

size

public int size()
Returns the number of members in the collection, ie. the collection's size.
Specified by:
size in interface Collection
Returns:
the size of the collection.

memberChanged

public abstract GroupMember memberChanged(QTDrawable d)
                                   throws QTException
This tells the group that the position or display size of the drawer has changed and it should do whatever actions are appropriate to reestablish the display integrity of the group. If the drawer is not a member of the group then null should be returned, if it is a member then a GroupMember object is returned that contains the layout characteristics of the drawer.
Parameters:
d - the drawer that has changed
Returns:
the GroupMember object that is associated with that drawer.

redrawMember

public abstract void redrawMember(QTDrawable d,
                                  Region invalidRgn)
                           throws QTException
An optimized redraw that will redraw only those objects that it needs to based on the fact that the supplied drawer has changed but those behind or in front of it have not.
Parameters:
d - the member of which some display characteristic has changed.
invalidRgn - the Region that has changed as a result of the changes in the specified member. Generally this Region should encompass the area of the Group's display space that was occupied before the member was changed as this call will result in the member itself being redrawn.

setMemberAlignment

public boolean setMemberAlignment(QTDrawable d,
                                  float xAlign,
                                  float yAlign)
                           throws QTException
This will reset an item's alignment and redraw the group. Internally the group uses alignment values to recall where an item is in relation to the other members and the group's display space. Upon resize of the group's display space items are layed out in accordance of their alignment settings.
Parameters:
d - the drawer to reposition the alignment
xAlign - the new x alignment value for the member
yAlign - the new y alignemen value for the member
Returns:
true if the drawer is a member of the group

setMemberLayer

public boolean setMemberLayer(QTDrawable member,
                              int layer)
                       throws QTException
This sets the layer of the incoming drawable to the new layer. It returns true if the drawable is a member of the group and was reset, false otherwise.
Parameters:
d - the group member to reset
layer - the new layer
Returns:
true if d is a member of the group

getBackLayer

public int getBackLayer()
Returns the back most layer of any object in the group.
Specified by:
getBackLayer in interface QTDisplaySpace
Returns:
the current back most layer

getFrontLayer

public int getFrontLayer()
Returns the current front most layer of any object in the group.
Specified by:
getFrontLayer in interface QTDisplaySpace
Returns:
the current front most layer

getInitialSize

public java.awt.Dimension getInitialSize()
                                  throws QTException
Deprecated. since QTJava 4.0

This method returns the original size before the transformations specified in the returned matrix are applied.
See Also:
()

getOriginalSize

public QDDimension getOriginalSize()
                            throws QTException
This method returns the original size before the transformations specified in the returned matrix are applied.
Specified by:
getOriginalSize in interface Transformable
Returns:
the original size of the GroupDrawable

redraw

public void redraw(Region invalidRgn)
            throws QTException
QTCanvas calls this method when the client should redraw itself. If the canvas is able to discern that only a part of the client's drawing area needs to be redrawn - then this area shall be passed in using the invalidRgn. Otherwise this will be null in which case the client should redraw itself entirely.
Specified by:
redraw in interface Drawable
Parameters:
canv - the QTCanvas that is doing the drawing
invalidRgn - the invalidRgn that the client should redraw

getLayerable

public Layerable getLayerable(java.lang.Object member)
Returns the Layerable object for a member (or null if the Object is not a member) that allows the application to get and set the layer of a member. This may or may not be the member itself, depending both on the type of the object of the member and the manner in which the QTDisplaySpace handles the Layer property of its members.
Specified by:
getLayerable in interface QTDisplaySpace
Parameters:
member - the member
Returns:
a Layerable object to interact with the display layer of a member.

getTransformable

public Transformable getTransformable(java.lang.Object member)
Returns the Transformable object that represents the member in the DisplaySpace. The Transformable object allows the application to get and set the TwoD display characteristics of a member (position, size, rotation, skewing, perspective). If the Object is not a member of the Space this returns null. This may or may not return the member itself, based on the type of the member and how the Space deals with the two dimensional placement and display of its members.
Specified by:
getTransformable in interface QTDisplaySpace
Parameters:
member - the member of Space for which the Transformable object should be returned.
Returns:
a Transformable object that allows the application to manipulate the two d display characteristics of the member or null if the object is not a member.

hitTest

public java.lang.Object hitTest(int x,
                                int y)
                         throws QTException
Returns the front most object located at the specified x and y pixel location or null if there is no object at the location
Specified by:
hitTest in interface QTDisplaySpace
Parameters:
x - the x pixel to test
y - the y pixel to test
Returns:
front most object or null

getMatrix

public Matrix getMatrix()
                 throws StdQTException
This will return the client's current display transformations. A GroupDrawable object does not by default support any transformation but location.
Specified by:
getMatrix in interface Transformable
Returns:
the display transformations of the client

setMatrix

public void setMatrix(Matrix matrix)
               throws QTException
This method sets the current matrix of the Transformable object to the new matrix. A GroupDrawable object does not by default support any transformation but location.
Specified by:
setMatrix in interface Transformable
Parameters:
matrix - the new location

getClip

public Region getClip()
               throws QTException
This method allows you to get the current clipped Region of the Transformable.
Specified by:
getClip in interface QTDrawable
Returns:
the clipping region

getBackgroundClip

public Region getBackgroundClip()
This method returns the clip that contains any space within the GroupDrawable that is not drawn upon by one of the members. This region is contains the pixels that will be filled in with the background colour.
Returns:
the background region.

setClip

public abstract void setClip(Region theClip)
                      throws QTException
This method allows you to set a Transformable's clipping region.
Specified by:
setClip in interface QTDrawable
Parameters:
theClip - a Region that defines the new clipping region.

setAlignedMemberLocation

protected void setAlignedMemberLocation(QTDrawable drawer,
                                        float xAlign,
                                        float yAlign)
                                 throws QTException
A helper method that is used to set the location of the member based on the x and y alignment. The alignment values must be between 0 and 1.
Parameters:
drawer - The drawer to locate based on the current size of the GroupDrawable and the alignment values
xAlign - the x alignment
yAlign - the y alignment