ESFlashView

Inherits fromESScriptingPluginView:ESNetscapePluginView:NSView:NSObject
FrameworkFlashInApp.framework
Declared in ESScriptingPluginView.h
Companion guideFlash’In’App Programming Guide 
Required system version Mac OS X 10.4 and higher

 

Class description of ESFlashView


ESFlashView class is defined to interact with Flash Player plugin. ESFlashView is based on ESScriptingPluginView and adds all required functions for correct work with Flash movies.

 

Class constants of ESFlashView


The following constants of type FlashMovieQuality are used to playback quality constants:

FlashMovieQuality_Low

Low quality of Flash Movie

FlashMovieQuality_Medium

Medium quality of Flash Movie

FlashMovieQuality_HighHigh quality of Flash Movie

 

The following constants of type FlashScaleType are used to indicate scale type:

SCALE_SHOWALL

makes the entire movie visible in the specified area without distortion, while maintaining the original aspect ratio of the movie. Borders may appear on two sides of the movie.

SCALE_NOBORDER

scales the movie to fill the specified area, without distortion but possibly with some cropping, while maintaining the original aspect ratio of the movie.

SCALE_NOSCALE
shows the movie in original size
SCALE_EXACTFIT
makes the entire movie visible in the specified area without trying to preserve the original aspect ratio. Distortion may occur.

 

The following constants of type FlashSAlignType are used to indicate align type:

SALIGN_DEFAULT

align the movie to the centre

SALIGN_LEFT

align the movie along the left edge of the browser window and crop the remaining three sides as needed

SALIGN_TOP
align the movie along the top edge of the browser window and crop the remaining three sides as needed
SALIGN_RIGHT
align the movie along the right edge of the browser window and crop the remaining three sides as needed
SALIGN_BOTTOM
align the movie along the bottom edge of the browser window and crop the remaining three sides as needed
SALIGN_TOP_LEFT
align the movie to the top left corner of the browser window and crop the bottom and remaining right or left side as needed
SALIGN_TOP_RIGHT
align the movie to the top right corner of the browser window and crop the bottom and remaining right or left side as needed
SALIGN_BOTTOM_LEFT
align the movie to the bottom left corner of the browser window and crop the top and remaining right or left side as needed
SALIGN_BOTTOM_RIGHT
align the movie to the bottom right corner of the browser window and crop the top and remaining right or left side as needed

 

Tasks


Setting registration name and key

Movie representation customization

Background Drawing

Setting Path to Plugin

Working with Security

Behavior while Dragging

Taking a Snapshot

Scripting Support

Working with ZoomRect

 

Class Methods


setName:andKey:
Sets registration name and key.
+ (void) setName:(NSString *)aName andKey:(NSString *)aKey;
Parameters
aName – registration name
aKey – registration key

Discussion
setName:andKey: method has to be called before loading any movie to register Flash’In’App, otherwise a demo reminder will be shown to user
NOTE: this method is deprecated since Flash’In’App 2.5, please use [[ESFIAPreferences sharedPreferences] setName:andKey:] instead.

registrationName
Gets registration name.
+ (NSString *) registrationName;
Return Value
registration name

NOTE: this method is deprecated since Flash’In’App 2.5, please use [[ESFIAPreferences sharedPreferences] setName:andKey:] instead.

registrationKey
Gets registration key.
+ (NSString *) registrationKey;

Return Value
registration key

NOTE: this method is deprecated since Flash’In’App 2.5, please use [[ESFIAPreferences sharedPreferences] setName:andKey:] instead.
 

setPluginPath:

Sets the path value to the plugin.

+ (void) setPluginPath:(NSString*)thePluginPath;

Parameters

thePluginPath – path to the plugin

Discussion

Cannot be nil and should point to existing path. Default plugin path will be loaded from Contents/Plugins/Flash Player.plugin

NOTE: this method is deprecated since Flash’In’App 2.5, please use [[ESFIAPreferences sharedPreferences] setFlashPluginPath:] instead.

 

pluginPath

Returns current path to the plugin.

+ (NSString *) pluginPath;

Return Value

The path to the plugin.

NOTE: this method is deprecated since Flash’In’App 2.5, please use [[ESFIAPreferences sharedPreferences] setFlashPluginPath:] instead.

 

Instance Methods


setFlashBackgroundColor:
This method lets you set Flash background color for playback
– (void) setFlashBackgroundColor:(NSColor *)aColor;

Parameters
aColor – Color to set as the receiver’s background color.

Discussion
Should you change the background color settings in runtime, you should reload the movie
 

flashBackgroundColor:
This method lets you get Flash background color for playback
– (NSColor *) flashBackgroundColor;

Return Value
The receiver’s background color.
 

setFlashVars:
This method lets you set root level variables to pass to Flash Player
– (void) setFlashVars:(NSString *)aVars;

Parameters
aVars – names and values of variables. The format of the string is a set of name=value combinations separated by ‘&’.

Discussion
Should you set root level variables in runtime, you should reload the movie

 

flashVars:
This method lets you get root level variables which are transmitted to the player.
– (NSString *) flashVars;
Return Value
root level variables values

 

setScaleType:
This method lets you specify scaling option used to display the Flash movie.
– (void) setScaleType:(FlashScaleType)aScale;

Parameters
aScale – scaling type can be SCALE_SHOWALL, SCALE_NOBORDER, SCALE_NOSCALE, SCALE_EXACTFIT

Discussion
Should you be changing scaling settings in runtime, you will need to reload the movie

 

scaleType
This method lets you get scaling option used to display the Flash movie.
– (FlashScaleType) scaleType;
Return Value
scaling type

setSAlignType:
This method lets you set vertical and horizontal movie alignment within the player region.
– (void) setSAlignType:(FlashSAlignType)anAlign;
Parameters
anAlign – alignment type can be SALIGN_DEFAULT, SALIGN_LEFT, SALIGN_TOP, SALIGN_RIGHT, SALIGN_BOTTOM, SALIGN_TOP_LEFT, SALIGN_TOP_RIGHT, SALIGN_BOTTOM_LEFT, SALIGN_BOTTOM_RIGHT
Discussion
Should you be changing movie alignment settings in runtime, you will need to reload the movie

 

sAlignType
This method lets you get movie alignment.
– (FlashSAlignType) sAlignType;

Return Value
alignment type

 

setAttributeKeys:andValues:
This method lets you set all the rest of parameters provided by Adobe (menu, quality, etc, see Adobe help pages).
– (void)setAttributeKeys:(NSArray *)keys andValues:(NSArray *)values;

Parameters
keys – keys array
values – values array

Discussion
Should you be changing movie parameters in runtime, you will need to reload the movie 

 

attributeKeys
This method lets you get keys array.
– (NSArray *) attributeKeys;
Return Value
keys array
 

attributeValues
This method lets you get values array.
– (NSArray *) attributeValues;
Return Value
values array
 

setTransparent

Specifies whether the receiver is transparent.

– (void)setTransparent:(BOOL)transparent;

Parameter

transparent – YES makes the receiver transparent. NO makes the receiver opaque.

Discussion

Must be called before loading movie. Default value is NO. If you change the transparency settings in runtime, you should reload the movie

Please, note that transparent applications are supported only by Intel-based Mac.
 

setEnabledSecurity:

Specifies FlashLocalSecurity status to “ON/OFF”.

 – (void)setEnabledSecurity:(BOOL)value;

Parameters

value – YES when FlashLocalSecurity is on, otherwise NO

Discussion

This method must be called before loading movie. Default and recommended value is NO.

 

isEnabledSecurity

Returns FlashLocalSecurity state.

 – (BOOL)isEnabledSecurity;

Return Value

The FlashLocalSecurity state.

 

setAllowNativeDrag:

This method enables or disables handling dragging options by plugin.

– (void) setAllowNativeDrag:(BOOL)value;

Parameters

value – YES enable drag option, NO disable this option

Discussion

If YES zooming is disabled, Flash components like sliders and scrolls will work; otherwise, NO.

 

allowNativeDrag

Returns current state of dragging.

– (BOOL) allowNativeDrag;

Return Value

The current state of dragging.

 

setCanDrag:

Sets dragging by Flash’In’App.

– (void) setCanDrag:(BOOL)value;

Parameters

value – YES to specify that a content can be dragged, NO to specify that a content can’t be dragged
Discussion

Globally allow/deny dragging by Flash’In’App. Here we deny dragging by Adobe Flash Player and let dragging be handled by your own app. This will work only if you set current and original rectangle correctly.

 

canDrag

Returns current state of drag settings.

 – (BOOL) canDrag;

Return Value

The current state of drag settings.

 

snapshotOriginalSize

Takes movie snapshot in original size.

– (NSImage *) snapshotOriginalSize;

Return Value

The movie snapshot in original size.

 

isPlaying

Returns YES if the movie is currently playing.

– (BOOL) isPlaying;

Return Value

YES if the movie is currently playing, otherwise NO.

 

play

 Starts playing the movie.

 – (void) play;
 

stopPlay

 Stops playing the movie.

 – (void) stopPlay;

 

totalFrames

Returns the total number of frames in the movie.

– (int) totalFrames;

Return Value

The total number of frames in the movie.

 

currentFrame

Returns the current frame.

 – (int) currentFrame;

Return Value

The current frame in the movie.

 

gotoFrame:

Activates the frame number specified by frame in the current movie.

 – (void) gotoFrame:(int32)frame;

Parameters

frame – number of frame

Discussion

If the data for the requested frame is not yet available, the player goes to the last frame available and stops, causing unexpected results during playback.

The argument frame is zero-based; that is, frame is 0 in the first frame of the movie, 1 for the second frame, and so on. This differs from the Goto action within Flash, which begins at 1. The argument type is integer.

 

rewind

Goes to the first frame.

 – (void) rewind;

 

back  

Goes to the previous frame.

 – (void) back;

 

forward

Goes to the next frame.

– (void) forward;

 

pan:::  

Pans a zoomed-in movie to the coordinates specified by x and y.

– (void) pan:(int32)x :(int32)y :(int32)panMode;
Parameters

panMode – use mode to specify whether the values for x and y are pixels or a percent of the window. When mode is 0, the coordinates are pixels; when mode is 1, the coordinates are percent of the window. Pan does not pan beyond the boundaries of the zoomed-in movie. The argument type for all arguments is integer.

 

zoom:

Zooms the view by a relative scale factor specified in percent.

– (void) zoom:(int32)value;

Parameters

value – current zoom percentage. Zoom(50) doubles the size of the objects in the view. Zoom(200) reduces the size of objects in the view by one half. Zoom(0) resets the view to 100%

Discussion

You cannot specify size reduction of objects in the view when the current view is already 100%. The argument type is integer.

 

setZoomRect::::

Zooms in on a rectangular area of the movie.

– (void) setZoomRect:(int32)left :(int32)top :(int32)right :(int32)bottom;

Parameters

The following parameters: left, top, right, bottom – are points of movie rectangular area, which will be displayed when zooming.

Discussion

The units of the coordinates are in twips (1440 units per inch). To calculate a rectangle in Flash, set the ruler units to Points and multiply the coordinates by 20 to get twips. (There are 72 points per inch.) The argument type for all arguments is integer.

 

setFlashQuality:

Sets quality of the movie.

– (void) setFlashQuality:(FlashMovieQuality)value;

Parameters

value – the quality of movie playback. Can be FlashMovieQuality_Low, FlashMovieQuality_Medium, FlashMovieQuality_High

 

flashQuality

Returns movie quality settings.

– (FlashMovieQuality) flashQuality;

Return Value

The quality of the movie.

 

callFunction:

Calls function with ExternalAPI help.

– (id) callFunction:(NSString *)value;

Parameters

value – name and arguments of calling function, that has view <invoke name=”asFunc”><arguments><string> Hello from Cocoa </string></arguments></invoke>

Return Value

The result of function execution.

 

setVariable:toValue:  

Sets variable value.

– (void) setVariable:(NSString *)name toValue:(id)value;

Parameters

name – variable name, which you want to change

value – new variable value

 

getVariable:

Gets current variable value.

– (id) getVariable:(NSString *)name;

Parameters

name – variable name, which you want to get

Return Value

The variable value.

 

currentRect

Gets current zoom rectangle.

– (NPSignedRect) currentRect;

Return Value

Current zoom rectangle.

Discussion

All coordinates in TWIPS

 

setCurrentRect:  

Sets current zoom rectangle and display it.

– (void) setCurrentRect:(NPSignedRect)rect;

Parameters

rect – new zoom rectangle

Discussion

All coordinates in TWIPS

 

originalRect

Gets original zoom rectangle.

– (NPSignedRect) originalRect;

Return Value

Original zoom rectangle

Discussion

All coordinates in TWIPS. Rectangle is read from SWF file while loading.

 

setOriginalRect:  

Sets original zoom rectangle and displays it.

– (void) setOriginalRect: (int32)left :(int32)top :(int32)right :(int32) bottom;

Parameters

left, top, right, bottom – are points of movie rectangular area, which will be displayed when zooming

Discussion
The units of the coordinates are in twips (1440 units per inch). To calculate a rectangle in Flash, set the ruler units to Points and multiply the coordinates by 20 to get twips. (There are 72 points per inch.) The argument type for all arguments is integer. Rectangle is read from SWF file while loading. Maximum (left – 14400, top – 14400, right + 14400, bottom + 14400) and current rectangle is set in addition to original rectangle while calling setOriginalRect method.

 

maxRect

Gets maximum zoom rectangle.

– (NPSignedRect) maxRect;

Return Value

Maximum zoom rectangle

Discussion

All coordinates in TWIPS. Zoom rectangle value can be increased to maxRect value maximum.

 

setOriginalSize:  

Displays SWF in original size.

– (void) setOriginalSize: (BOOL)flag;

Parameters

flag – for internal usage, should be always YES

 

setFitSize  

Enables SWF auto size (SWF will be fitted to visible area)

– (void) setFitSize;

 

zoomIn

Increases current zoom rect by one step.

– (void) zoomIn;

Discussion

One step equals 700 TWIPS.

 

zoomOut

Decreases current zoom rect at one step.

– (void) zoomOut;

Discussion

One step equals 700 TWIPS.

 

setZoomPercent:  

Sets zoom value (in percent).

– (void) setZoomPercent: (int)value;

Parameters

value – zoom value in percent

Discussion

100 is original size

 

zoomPercent

Gets current zoom value in percent.

– (int) zoomPercent;

Return Value

Current zoom value

 

displayRect:  

Displays rectangle.

– (void) displayRect: (NPSignedRect)rect;

 Parameters

rect – rectangle value

 

displayZoomRect:  

Displays zoom rectangle.

– (void) displayZoomRect: (NPRect)rect;

Parameters

rect – zoom rectangle value
 

updateCurrentRect

Updates current zoom rectangle.

– (void) udpdateCurrentRect;

 

Delegate Methods


flashView:wasDraggedFrom:to:

This message will be sent to delegate when dragging is active.

– (void) flashView:(ESFlashView *)flashView wasDraggedFrom:(NSPoint *)fromPoint to:(NSPoint *)toPoint;

Parameters

flashView – flash view that sent the message

fromPoint – start point for drag

toPoint – final point for drag

Discussions  

This is the method, which you should use to perform dragging of the whole movie window when user drags it. You can see the sample of how this method works in our GUI sample.

 

flashView:callFunction:

This is the method, which informs the delegate that SWF file performed ExternalInterface.call.

– (id) flashView:(ESFlashView *)flashView callFunction:(NSString *)xmlString;

Parameters

xmlString – function name and arguments are represented as <invoke name=”asFunc”><arguments><string>Hello from Cocoa</string></arguments></invoke>
Return Value: Since Flash’In’App 2.5, you should return object (e.g. NSString), not xml string as it was before
NOTE: if you implement flashView:callFunction: and flashView:callFunction:withArguments: methods, only second one will be called.

 

flashView:callFunction:withArguments:

This method informs the delegate that swf file performed ExternalInterface.call.

– (id) flashView:(ESFlashView *)flashView callFunction:(NSString *)aName withArguments:(NSArray *)anArguments;

Parameters
aName – function name that was called
anArguments – arguments of function call

Return value

Since Flash’In’App 2.5, you should return object (e.g. NSString), not xml string as it was before.

NOTE: if you implement flashView:callFunction: and flashView:callFunction:withArguments: methods, only second one will be called.

 

flashView:invokeFSCommand:withArguments:

This message will be sent to delegate when movie calls an FSCommand.

– (id) flashView:(ESFlashView *)flashView invokeFSCommand:(NSString *)commandName withArguments:(NSArray *)arguments;

Parameters

flashView – flash view that sent the message

commandName – command name

arguments – an array of arguments that can be used

Return Value

The object which will be sent to the plugin as return value of FSCommand().

 

flashView:didDisplayRect:

This message will be sent to delegate when ESFlashView changes visible rect of movie.

– (void) flashView:(ESFlashView *)flashView didDisplayRect:(NPSignedRect)aDisplayedRect;

Parameters

flashView – flash view that sent the message

aDisplayedRect – new visible rectangle