All Packages  Class Hierarchy  This Package  Previous  Next  Index

Class quicktime.app.display.QTCanvas

java.lang.Object
   |
   +----java.awt.Component
           |
           +----java.awt.Canvas
                   |
                   +----quicktime.app.display.QTCanvas

public class QTCanvas

extends Canvas

The resize and alignment flags determine how the QTCanvas object acts when it has its setSize or setBounds method called. These flags allow the application to control or restrict the viewing size of a QTCanvas - generally desirable as the QuickTime client of a QTCanvas is constructed to be viewed in a particular best size or react in a desired manner when resized. The resize flags comments discuss the typically appropriate usage. If the kAnySize flag is used the QTCanvas will be resized as any other java.awt.Component.

The size of the QTCanvas and its Drawable client are kept synchronized. The actual size of the QTCanvas is determined by the size of its Drawable client when it is set (which becomes its "best" viewing size), the resize and alignement flag settings, and the size of the QTCanvas' java.awt.Container parent. The client, the resize and alignment flags determine how a QTCanvas reacts to a setBounds or setSize call - any resize flag other than the kAnySize flag will result in the QTCanvas' actual size being arbitrated with the best viewing size of its client. Thus in many cases the calls to setSize and setBounds on a QTCanvas object are requests and may not result in the QTCanvas actually being resized to that requested size.

When a QTCanvas' client is set the size of the client's current size is used by the QTCanvas to indicate that this is that client's best viewing size. By default (and an application can change this) this will also become the preferred size of the QTCanvas. This size is cached by the QTCanvas and used when it is responding to resize requests from its parent Container (for instance, the user resizes the window the QTCanvas is in).

If an application changes the size of the client after it has been set - for instance a Movie client is edited and the viewing area of the movie is now different - then the application must inform the QTCanvas that the client's best size is changed, before resizing the QTCanvas itself. This ensures that the QTCanvas will resize and redraw the client correctly, avoiding unwanted scaling of the client:

	// application changes the actual display size of a Movie through 
	// adding a video track to a movie that only had a sound track
	// this means that the movie client has now a best size that 
	// that is different when it was originally set as the client of this QTCanvas
	myQTCanvas.clientChanged (r.getWidth(), r.getHeight());
	myQTCanvas.invalidate();
 	//resize the QTCanvas' parent container so that the changed viewing conditions of the
	//client will be seen.
	//pack() is appropriate, as is getParent().setSize(), or getParent().setBounds()
	//The application could also just validate the parent if the parent should not change size
 

Once the application has notified the canvas that the client's best viewing size has changed the QTCanvas will correctly respond to the any new sizes that are given to it by it parent's layout manager or resizing actions.

In most interactions between a QTCanvas and its client this explicit resizing of the client is not required as all of the Drawable clients are able to scale themselves appropriately to a different display size. It is only required when the client's size itself has changed.

See Also:

Drawable

kAspectResize

Use this flag if the client can be resized to any size which preserves the initial aspect ratio.

kFreeResize

Use this flag if the client can be resized to any size >= the minimum and <= the maximum.

kHorizontalResize

Use this flag to allow the client's horizontal aspect to be any size, but the vertical axis will be the intial size of smaller.

kInitialSize

Use this flag if the client should revert to its initially specified size.

kIntegralResize

Use this flag if the client should maintain the aspect size of its original dimensions but grow bigger by integral increments (2x, 3x, 4x, etc.)

kPerformanceResize

Use this flag if the client can be resized to any size which is a factor of 2 of the initial size.

kVerticalResize

Use this flag to allow the client's vertical aspect to be any size, but the horizontal axis will be the intial size of smaller.

QTCanvas()

Constructor for creating a client-less QTCanvas.

QTCanvas(int, float, float)

Constructor for creating a client-less QTCanvas.

addNotify()

We use this method to notify an existing client that its NativeGraphics environment may have changed and it should recheck its status

addQTClientListener(ComponentListener)

A ComponentListener and ComponentEvent are used to listen to these types of events that occur to the QTCanvas' client - ie.

clientChanged(Dimension)

This method is used by an appliction to notify a QTCanvas that the best size of its' current client has changed.

clientChanged(int, int)

This method is used by an appliction to notify a QTCanvas that the best size of its' current client has changed.

finalize()

getAlignmentX()

Returns the current setting of the x position alignment being used.

getAlignmentY()

Returns the current setting of the y position alignment being used.

getBestSize()

Returns the best size of the client, the size of the client when it was set to this QTCanvas, or the size if the appliction notified the QTCanvas that the clien't best size was changed.

getClient()

Returns the Drawable object currently associated with this QTCanvas.

getMaximumSize()

Returns the maximum acceptable size of this QTCanvas object.

getMinimumSize()

Returns the minimum acceptable size of this QTCanvas object.

getNativeGraphics()

Returns the NativeGrapics object that represents the Graphics Port that corresponds to the display space taken up by the QTCanvas.

getNGLocation()

Returns the coordinates of a component relative to the NativeGrapics window it is currently placed within.

getPort()

This method will return a QTJava object, QDGraphics, which is a reference to the native graphics drawing environment being used by this QTCanvas object.

getPreferredSize()

Returns the preferred size of the QTCanvas object.

getResizeFlag()

Returns the current setting of the resize flag being used.

paint(Graphics)

Override the standard paint method.

removeClient()

Removes the client from the canvas.

removeNotify()

Overridden to notify the client associated with this QTCanvas that it no longer has a grafport to draw to and should stop all graphics operations.

removeQTClientListener(ComponentListener)

Remove a previously registered ComponentListener that is listening to events that occur with the QTCanvas' QTDrawable client.

reshape(int, int, int, int)

Deprecated.

setAlignment(float, float)

Set the alignment position values.

setAlignmentX(float)

setAlignmentY(float)

setBounds(int, int, int, int)

Resizes and/or moves the QTCanvas object as well as the associated Drawable object to the parameters specified.

setClient(Drawable, boolean)

Associates a new client, a Drawable object, with this QTCanvas.

setClient(Drawable, QDRect)

Associates a new client, a Drawable object, with this QTCanvas.

setMaximumSize(Dimension)

Set the minimum size of the QTCanvas.

setMaximumSize(int, int)

Set the maximum size of the canvas.

setMinimumSize(Dimension)

Set the minimum size of the QTCanvas.

setMinimumSize(int, int)

Set the minimum size of the canvas.

setPreferredSize(Dimension)

Sets the preferred size of the QTCanvas object.

setPreferredSize(int, int)

Sets the preferred size of the QTCanvas object.

setResizeFlag(int)

Reset the resize flag and re-layout the component.

setSize(Dimension)

Resizes the QTCanvas object to the specified parameters.

setSize(int, int)

Resizes the QTCanvas object, as well as the associated Drawable object.

setVisible(boolean)

Sets the visible state of the Canvas.

toString()

Print information about this object.

translatePoint(int, int)

An incoming point (typically from some kind of MouseEvent) is in coordinates that have their origin set at the local coordinate system of the canvas.

update(Graphics)

We override the update method to call our paint method as the background colour repaint is not valid for a QTCanvas object.

 public static final int kIntegralResize

Use this flag if the client should maintain the aspect size of its original dimensions but grow bigger by integral increments (2x, 3x, 4x, etc.)

 public static final int kInitialSize

Use this flag if the client should revert to its initially specified size. The client can be made smaller (using an aspect setting) but can be no larger than its initial size. The QTCanvas takes this initial size as the best viewing size for its client.

 public static final int kFreeResize

Use this flag if the client can be resized to any size >= the minimum and <= the maximum.

 public static final int kAspectResize

Use this flag if the client can be resized to any size which preserves the initial aspect ratio.

 public static final int kPerformanceResize

Use this flag if the client can be resized to any size which is a factor of 2 of the initial size.

 public static final int kHorizontalResize

Use this flag to allow the client's horizontal aspect to be any size, but the vertical axis will be the intial size of smaller. This is a good setting for QT VR content.

 public static final int kVerticalResize

Use this flag to allow the client's vertical aspect to be any size, but the horizontal axis will be the intial size of smaller.

 public QTCanvas()

Constructor for creating a client-less QTCanvas. Default settings are:

Resize Flag is kFreeResize

xAlignment and yAlignment are both set to 0 (top left)

Minimum size is (1, 1)

Maximum size is (Integer.MAX_VALUE, Integer.MAX_VALUE)

 public QTCanvas(int resizeFlag,
                 float xAlignment,
                 float yAlignment)

Constructor for creating a client-less QTCanvas.

Parameters:

resizeFlag - the resize control setting

xAlignment - a value between 0 and 1 that sets the position of the drawable client within the space that AWT will give to the canvas when layed out. 0 means left, 1 means right, 0.5 means centre.

yAlignment - a value between 0 and 1 that sets the position of the drawable client within the space that AWT will give to the canvas when layed out. 0 means top, 1 means bottom, 0.5 means centre.

 public final QDGraphics getPort() throws QTUnknownOSException, NativeGraphicsException

This method will return a QTJava object, QDGraphics, which is a reference to the native graphics drawing environment being used by this QTCanvas object. If the canvas is invisible it will return an offscreen QDGraphics that will never be seen.

Returns:

a QDGraphics object

Throws: QTUnknownOSException

if the current operating system is unknown to QuickTime

Throws: NativeGraphicsException

if there was a problem initialising the NativeGraphics environment

 public final Point getNGLocation() throws QTUnknownOSException, NativeGraphicsException

Returns the coordinates of a component relative to the NativeGrapics window it is currently placed within.

Returns:

a Point object representing the location of the QTCanvas in the native graphics environment

 public final NativeGraphics getNativeGraphics()

Returns the NativeGrapics object that represents the Graphics Port that corresponds to the display space taken up by the QTCanvas. It may return null if there is currently no native graphics environment

Returns:

a NativeGraphics object.

 public final QDPoint translatePoint(int x,
                                     int y) throws QTUnknownOSException, NativeGraphicsException

An incoming point (typically from some kind of MouseEvent) is in coordinates that have their origin set at the local coordinate system of the canvas. This method converts those coordinates into the native graphics location that is the coordinate system of the canvas' client.

Parameters:

x - the x location

y - the y location

Returns:

a QDPoint that translates the x and y into the NativeGraphics coordinate system.

 public final synchronized void removeClient()

Removes the client from the canvas.

 public synchronized void setClient(Drawable client,
                                    boolean layoutFlag) throws QTException

Associates a new client, a Drawable object, with this QTCanvas. The flag determines if awt will perform a layout and how the client will be integrated with the canvas. If the flag is false then the new client will take on the current size and position of the canvas. If the flag is true, then awt will layout the canvas again, using the initial size of the client and the resize flags to resize the canvas and its client.

The size of the client when this method is called is used to ascertain the best size for viewing this client's media.

This method can throw a number of exceptions:
QTUnknownOSException the application is trying to run on a platform that is not supported by QuickTime
NativeGraphicsException the native graphics environment is not initialised
QTException or subclass - there was a problem within QuickTime itself in dealing with this client

Parameters:

client - a Drawable object - if null the method will remove the client

layoutFlag - if true java.awt will re-layout the canvas, if false the client will fit into the existing state (display size, etc) of the canvas, disregarding any resize that might have occured to honour the layout flag setting with respect to the different size of the new client.

 public synchronized void setClient(Drawable client,
                                    QDRect initialBounds) throws QTException

Associates a new client, a Drawable object, with this QTCanvas. It will use existing alignment and resize restrictions.

This method can throw a number of exceptions:
QTUnknownOSException the application is trying to run on a platform that is not supported by QuickTime
NativeGraphicsException the native graphics environment is not initialised
QTException or subclass - there was a problem within QuickTime itself in dealing with this client

Parameters:

client - a Drawable object - if null the method will remove the client

initialBounds - the best size of the client

 public final Drawable getClient()

Returns the Drawable object currently associated with this QTCanvas.

Returns:

a Drawable object

 public void setAlignment(float xAlignment,
                          float yAlignment)

Set the alignment position values. The alignment values must be between 0.0 and 1.0. Values out of this range will be reset to either 0.0 or 1.0, whichever is closest to the given argument.

Alignment Positioning works like this:

x=0.0 y=0.0

is equivalent to a top-left position

x=1.0 y=1.0

is equivalent to a bottom-right position

x=0.5 y=0.5

is equivalent to a centered position

x=0.25 y=0.75

is equivalent to 1/4 in from the the left and 3/4 down from the top

Position alignments can be varied to any degree, limited by the pixel resolution of the display surface.

Parameters:

xAlignment - a float between 0.0 and 1.0 representing the x position alignment

yAlignment - a float between 0.0 and 1.0 representing the y position alignment

 public final void setAlignmentX(float x)

See Also:

setAlignment

 public final void setAlignmentY(float y)

See Also:

setAlignment

 public float getAlignmentX()

Returns the current setting of the x position alignment being used.

Returns:

s the x position alignment

Overrides:

getAlignmentX in class Component

 public float getAlignmentY()

Returns the current setting of the y position alignment being used.

Returns:

s the y position alignment

Overrides:

getAlignmentY in class Component

 public void setResizeFlag(int rFlag)

Reset the resize flag and re-layout the component.

Parameters:

rFlag - the new value for the resizeFlag

 public int getResizeFlag()

Returns the current setting of the resize flag being used.

Returns:

the resize flag value

 public void setMinimumSize(Dimension minSize)

Set the minimum size of the QTCanvas. If the QTCanvas is currently smaller than the minimum size passed in, it will be adjusted to meet the new minimum size requirements, in accordance with the setting of the resizeFlag.

Parameters:

minSize - a Dimension object

 public void setMinimumSize(int width,
                            int height)

Set the minimum size of the canvas.

Parameters:

width - the minimum width

height - the minimum height

 public Dimension getMinimumSize()

Returns the minimum acceptable size of this QTCanvas object.

Returns:

a Dimension object which defines the minimum size

Overrides:

getMinimumSize in class Component

 public Dimension getBestSize()

Returns the best size of the client, the size of the client when it was set to this QTCanvas, or the size if the appliction notified the QTCanvas that the clien't best size was changed. This may not be the size of the display space of the QTCanvas depending on java layout instructions and current display space available to the canvas.

Returns:

a Dimension object which details the client's known initial size

See Also:

clientChanged

 public void clientChanged(Dimension bestSize)

This method is used by an appliction to notify a QTCanvas that the best size of its' current client has changed. This is typically the initial or actual size of the client before any matrix transforamations have been applied to the client.

An application only needs to call this if the display characteristics of the client have been changed. For instance, the client is a movie and some of the visual tracks of this movie have been disabled, or a new video track was added. Thus the movie itself has changed its best size and the application must use this method to notify the QTCanvas that the client's best size has changed.

This will not effect the display area of the QTCanvas, the application should invalidate the QTCanvas and re-layout the parent container to have this change take effect. getBestSize() returns this newly notified size.

In the normal operation of a QTCanvas and its client there is no need for an application to use this method.

Parameters:

bestSize - the client's new best width and height

 public void clientChanged(int bestWidth,
                           int bestHeight)

This method is used by an appliction to notify a QTCanvas that the best size of its' current client has changed. This is typically the initial or actual size of the client before any matrix transforamations have been applied to the client.

An application only needs to call this if the display characteristics of the client have been changed. For instance, the client is a movie and some of the visual tracks of this movie have been disabled, or a new video track was added. Thus the movie itself has changed its best size and the application must use this method to notify the QTCanvas that the client's best size has changed.

This will not effect the display area of the QTCanvas, the application should invalidate the QTCanvas and re-layout the parent container to have this change take effect. getBestSize() returns this newly notified size.

In the normal operation of a QTCanvas and its client there is no need for an application to use this method.

Parameters:

bestWidth - the client's new best width

bestHeight - the client's new actual height

 public Dimension getPreferredSize()

Returns the preferred size of the QTCanvas object. If you haven't explicitly set the preferred size of the canvas this will be the initial size of the canvas' client.

Returns:

a Dimension object which defines the preferred size

Overrides:

getPreferredSize in class Component

 public void setPreferredSize(Dimension prefSize)

Sets the preferred size of the QTCanvas object.

Returns:

a Dimension object which defines the preferred size

 public void setPreferredSize(int width,
                              int height)

Sets the preferred size of the QTCanvas object. Passing in values of less than zero for width and height will reset the behaviour of the QTCanvas to retrieve the preferred size as the initial size of the current or new client of the QTCanvas.

Parameters:

width - the minimum width

height - the minimum height

 public void setMaximumSize(Dimension maxSize)

Set the minimum size of the QTCanvas. If the QTCanvas is currently larger than the maximum size passed in, it will be adjusted to meet the new maximum size requirements, in accordance with the setting of the resizeFlag.

Parameters:

maxSize - a Dimension object

 public void setMaximumSize(int width,
                            int height)

Set the maximum size of the canvas.

Parameters:

width - the minimum width

height - the minimum height

 public Dimension getMaximumSize()

Returns the maximum acceptable size of this QTCanvas object.

Returns:

a Dimension object which defines the maximum size

Overrides:

getMaximumSize in class Component

 public void setSize(Dimension dim)

Resizes the QTCanvas object to the specified parameters.

Parameters:

dim - a Dimension object with the new width and height

Overrides:

setSize in class Component

 public void setSize(int width,
                     int height)

Resizes the QTCanvas object, as well as the associated Drawable object.

Parameters:

width - the width, in pixels, to make this component

height - the height, in pixels, to make this component

Overrides:

setSize in class Component

 public final void reshape(int x,
                           int y,
                           int width,
                           int height)

Overrides:

reshape in class Component

 public final synchronized void setBounds(int x,
                                          int y,
                                          int width,
                                          int height)

Resizes and/or moves the QTCanvas object as well as the associated Drawable object to the parameters specified.

Parameters:

x - the x coordinate, in pixels, relative to the parent of this component

y - the y coordinate, in pixels, relative to the parent of this component

width - the width, in pixels, to make this component

height - the height, in pixels, to make this component

Overrides:

setBounds in class Component

 public void paint(Graphics g)

Override the standard paint method.

Overrides:

paint in class Canvas

 public void update(Graphics g)

We override the update method to call our paint method as the background colour repaint is not valid for a QTCanvas object. However, subclasses can override the update method to do whatever is appropriate for their particular situation.

Overrides:

update in class Component

 public synchronized void setVisible(boolean b)

Sets the visible state of the Canvas.

Parameters:

b - if true canvas is visible, if false then its not

Overrides:

setVisible in class Component

 public void addQTClientListener(ComponentListener e)

A ComponentListener and ComponentEvent are used to listen to these types of events that occur to the QTCanvas' client - ie. when the QTCanvas' client is resized, moved, shown or hidden. These events generally occur in conjunction with the Component events they mirror - with some exceptions:

• ComponentShown and ComponentHidden are generated when the QTCanvas is shown or hidden and when the QTDrawable client is set or removed.
• ComonentMoved and ComponentResized are generated when the QTCanvas is moved or resized but the event is actually generated when the QTCanvas is repainted as this is when the QTDrawable client is itself resized or moved.

  Parameters:

  e - the ComponentListener

 public void removeQTClientListener(ComponentListener e)

Remove a previously registered ComponentListener that is listening to events that occur with the QTCanvas' QTDrawable client.

Parameters:

e - the ComponentListener

See Also:

addQTClientListener

 public synchronized void addNotify()

We use this method to notify an existing client that its NativeGraphics environment may have changed and it should recheck its status

Overrides:

addNotify in class Canvas

 public synchronized void removeNotify()

Overridden to notify the client associated with this QTCanvas that it no longer has a grafport to draw to and should stop all graphics operations.

Overrides:

removeNotify in class Component

 public String toString()

Print information about this object.

Returns:

a string representing this QTCanvas object

Overrides:

toString in class Component

 protected void finalize() throws Throwable

Overrides:

finalize in class Object

All Packages  Class Hierarchy  This Package  Previous  Next  Index