WebViewer Xtra ver.1.5.1 User's Manual

Copyright (C) 2005 Xtras.jp
All rights reserved.


Overview

The First Cross-platform Web Browser Embed Xtra is Here.

WebViewer Xtra embeds Web Browser functions in your Director movie, using Microsoft's Internet Explorer engine in the Windows platform, and Apple's Safari engine in the Macintosh platform. By cross-platform Lingo scripting, it realizes not only HTML rendering, but also full controlling of the web browser features such as re-direct hyper-link navigation, disable the context menu, and so on. It also provides you some additional functions like executing your JavaScript, capturing the rendered HTML image, etc.

Examples using WebViewer Xtra

System requirements

Authoring environment:

Windows platform

Macintosh platform

Installation

Install on Director - Windows

Download a WebViewerXtra.zip package and unpack it somewhere you like.

Copy the WebViewer.x32 file to the "Xtras" folder used by Director application. The file path of Director's Xtras folder depends on what version of Director you use. If you installed your Director to the default location, these are the final path of the xtra file :

Director 8.5 : C:\Program Files\Macromedia\Director\Director 8.5\Xtras\WebViewer.x32
Director MX : C:\Program Files\Macromedia\Director\Director MX\Xtras\WebViewer.x32
Director MX2004 : C:\Program Files\Macromedia\Director\Director MX 2004\Configuration\Xtras\WebViewer.x32

If you have previously installed an older copy of the xtra make sure to remove or replace it.

Restart Director for the changes to take effect. The WebViewer Xtra should appear in the [Insert] -> [Xtras.jp] -> [WebViewer] of your Director's menu.

Install on Director - Macintosh

Download a WebViewerXtra.sit package and unpack it somewhere you like.

Copy the WebViewer file and the WebViewer.bundle folder(file) in "MacOSX" folder to the "Xtras" folder used by Director application. The file path of Director's Xtras folder depends on what version of Director you use. If you installed your Director to the default location, these are the final path of the xtra file :

Director MX : OSX Volume Name/Applications/Macromedia Director MX/Xtras/WebViewer
Director MX : OSX Volume Name/Applications/Macromedia Director MX/Xtras/WebViewer.bundle

Director MX 2004 : OSX Volume Name/Applications/Macromedia Director MX 2004/Configuration/Xtras/WebViewer
Director MX 2004 : OSX Volume Name/Applications/Macromedia Director MX 2004/Configuration/Xtras/WebViewer.bundle

The MacOSX version of WebViewer Xtra needs both of these files in the same folder. If you have previously installed an older copy of the xtra make sure to remove or replace it.

Restart Director for the changes to take effect. The WebViewer Xtra should appear in the [Insert] -> [Xtras.jp] -> [WebViewer] of your Director's menu.

Usage

Authoring in Director

WebViewer Xtra is an Asset xtra. You can use it in the score and cast window just like other Director's built-in media types. Select [Insert] -> [Xtras.jp] -> [WebViewer] item in your Director's menu to create a WebViewer Xtra cast member in the cast window. Click on it and drag the cast member to the score or stage. A transparent WebViewer Xtra sprite with "WebViewer Xtra ver.1.3" text will appear in the stage window. By using it, you can adjust the position and the size of the web browser area.

Play your Director movie, and execute the following Lingo command in the message window to display an web site.

(sprite 1).Navigate("http://www.macromedia.com")

To execute the same Lingo command in a handler, double click the second frame of the sprite in the score window, and write the following Lingo commands in the opened script window.

on exitFrame me
(sprite 1).Navigate("http://www.macromedia.com")
end

* If you want to call a Lingo method to the WebViewer sprite, you must call it after the sprite appeared on the stage.

WebViewer Xtra works as a "DirectToScreen" sprite, and it opens a web browser window at its placed area. So you can't put any other sprites over the WebViewer sprite.

When you stop the Director movie, the WebViewer sprite captures its rendered HTML, and behaves like a bitmap member sprite. The remained image will be lost if you move the current frame out of the sprite span, but it is useful to adjust the sprite with the actual rendering result.

To know all the functions of WebViewer Xtra in detail, refer to its Lingo reference. The Demo applications and source codes are also useful to understand their actual usage.

Setup for Projector application - Windows

When you use WebViewer Xtra in your Projector application in the Windows platform, create a "Xtras" folder in the same folder of your Projector, and copy the WebViewer.x32 file in it. You can also embed the xtra by selecting [Modify] -> [Movie] -> [Xtras] item in your Director's menu, and check [WebViewer.x32] item to include it in your Projector.

You need to purchase WebViewer Xtra and enter its serial code to make it work in your Projector application.

Setup for Projector application - Macintosh

When you use WebViewer Xtra in your Projector application in the Macintosh platform, create a "Xtras" folder in the same folder of your Projector, and copy the WebViewer file and the WebViewer.bundle folder(file) in it.

The MacOSX version of WebViewer Xtra needs both of these files in the same folder.

You need to purchase WebViewer Xtra and enter its serial code to make it work in your Projector application. For this reason, the Projector application can not includes WebViewer Xtra in it.

Setup for Shockwave

For security reasons, we don't provide "Shockwavable" version of WebViewer Xtra.

Lingo Reference

Cast member properties

available (integer type, read-only)

This property indicates if WebViewer Xtra is available in the current environment (true or 1) or not (false of 0).

e.g. put (member "WebViewer").available

browserVersion (string type, read-only)

This property indicates a version string of the web browser in the current environment. In the Windows platform it represents the Internet Explorer's version, and in the Macintosh platform it represents the WebKit's version as the Safari's rendering engine.

e.g. put (member "WebViewer").available
  -- "6.0.2800.1106" <- Windows
  -- "1.2" <- Macintosh

version (string type, read-only)

This property indicates a version string of the WebViewer Xtra.

e.g. put (member "WebViewer").version
  -- "1.32"

hideOnStart (string type)

This property sets initial visibility of WebViewer Xtra sprite. If you set true or 1 to this property, the WebViewer sprite is hidden when it appears on the stage. If you set false or 0 to this property, the WebViewer sprite is shown hidden when it appears on the stage.

e.g. (member "WebViewer").hideOnStart = 0

Cast member methods

Register(memberRef type member, string type serial)

This method register the WebViewer xtra. When you're authoring in Director, you can use all the functions of WebViewer Xtra. But in Projector application, you must register the xtra before you begin to navigate pages.

e.g. (member 1).Register("123456789")

Sprite properties

busy (integer type, read-only)

This property indicates if the web browser is currently loading an web page (true or 1) or not (false of 0).

e.g. put (sprite 1).busy

baseURL (string type)

This property indicates a baseURL for setting the "html" sprite property. The local path must be an existing file path because of the specification of the WebKit.This property has no effects in the Windows platform.

e.g. (sprite 1).baseURL = "http://www.xtras/jp/"
e.g. (sprite 1).baseURL = the moviePath & the movieName

cancelNavigation (integer type)

This property enables and disables the page navigations. If you set true or 1 to this property, you can't navigate to anywhere at all. If you set false or 0 to this property, you can navigate the web pages via clicking hyper-links as usual.

e.g. (sprite 1).cancelNavigation = 1

cancelNewWindow (integer type)

This property enables and disables to open a new browser window (or page navigation). If you set true or 1 to this property, WebViewer does nothing. If you set false or 0 to this property, you can open the new page in its window.

e.g. (sprite 1).cancelNewWindow = 1

contextMenu (integer type)

This property enables and disables the web browser's context menu shown by right-click (or control and click) on the web browser area. If you set true or 1 to this property, the context menu will be shown same as the usual web browser. If you set false or 0 to this property, the context menu will never be shown.

e.g. (sprite 1).contextMenu = 1

html (string type)

With this property you can set a raw HTML code to load in the web browser. You can also get the raw HTML code of the current page by this property.

e.g. (sprite 1).html = "<html><body>Hello world !!</body></html>

image (image type, read-only)

This property captures the current rendered HTML image and returns it as an a bitmap object. When you capture the image by this property, don't put any other window over the WebViewer sprite.

e.g. (member "img").image = (sprite 1).image

locationName (string type, read-only)

This property indicates the title of the current page. To get a notification about changing this property, use titleChange sprite event handler.

e.g. put (sprite 1).locationName

locationURL (string type, read-only)

This property indicates the URL address of the current page. It is generally used to detect if an internet connection is available.

e.g. put (sprite 1).locationURL

offline (integer type)

This property enables and disables the web browser's offline mode. If you set true or 1 to this property, the web browser works in offline mode, and it loads pages from cached data. If you set false or 0 to this property, disables the offline mode. This property has no effects in the Macintosh platform.

e.g. (sprite 1).offline = 1

readyState (integer type, read-only)

This property indicates the web browser's current ready state. Possible ready states one of the following values. The value of this property and its timing may be different depends on the platforms. In the Windows platform, when you give the contents by "html" sptite property, the value of "readyState" is invalid.

readyState state
0 The web browser is not initialized with data.
1 The web browser is loading its data.
2 The web browser has finished loading its data.
3 User can interact with the web browser even though it is not fully loaded.
4 The web browser is completely initialized.
e.g. put (sprite 1).readyState

scrollBars (integer type)

This property shows and hides the web browser's scroll bar. If you set true or 1 to this property, the web browser shows its scroll bars when they're needed. If you set false or 0 to this property, the web browser hide their scroll bars. In the Internet Explorer 5.0 and Safari, you can't hide the scroll bars by this property.

e.g. (sprite 1).scrollBars = 1

scrollWidth (integer type, read-only)

This property indicates width of the shown page. It is useful to implement your own scroll bars.

e.g. put (sprite 1).scrollWidth

scrollHeight (integer type, read-only)

This property indicates height of the shown page. It is useful to implement your own scroll bars.

e.g. put (sprite 1).scrollHeight

scrollLeft (integer type)

This property indicates distance of the shown area from left edge of the page. You can also set this property to scroll the page. It is useful to implement your own scroll bars.

e.g. (sprite 1).scrollLeft = 10

scrollTop (integer type)

This property indicates distance of the shown area from top edge of the page. You can also set this property to scroll the page. It is useful to implement your own scroll bars.

e.g. (sprite 1).scrollTop = 10

silent (integer type)

This property enables and disables the web browser's silent mode. If you set true or 1 to this property, the web browser works in silent mode, and it prohibits to open a new window when a page that contains invalid JavaScript code is loaded. If you set false or 0 to this property, disables the silent mode. This property has no effects in the Macintosh platform.

e.g. (sprite 1).silent = 1

statusText (string type, read-only)

This property indicates the web browser's current status text. The status text will be changed when you move mouse over a hype-link, put a text to the status text by JavaScript, and so on. To get a notification about changing this property, use statusTextChange sprite event handler.

e.g. put (sprite 1).statusText

Sprite methods

Navigate(spriteRef type sprite, string type URL, string type targetName)

This method initiates a navigation to the specified URL. You can also specify the target frame name where the new page will be loaded (optional).

e.g. (sprite 1).Navigate("http://www.macromedia.com")
e.g. (sprite 1).Navigate("http://www.macromedia.com","main")
e.g. (sprite 1).Navigate(the moviePath & "test.html")

GoForward(spriteRef type sprite)

This method navigates to the next URL in the browser history, if available.

e.g. (sprite 1).GoForward()

GoBack(spriteRef type sprite)

This method navigates to the previous URL in the browser history, if available.

e.g. (sprite 1).GoBack()

GoHome(spriteRef type sprite)

This method navigates to the Home URL set in the system preferences. This method has no effects in the Macintosh platform.

e.g. (sprite 1).GoHome()

GoSearch(spriteRef type sprite)

This method navigates to the Search URL set in the system preferences. In the Macintosh platform this method navigates to Google page.

e.g. (sprite 1).GoSearch()

Stop(spriteRef type sprite)

This method stops the current page loading.

e.g. (sprite 1).Stop()

Refresh(spriteRef type sprite)

This method reloads the current page from the cache data. In the Macintosh platform this method is same as Refresh2 method.

e.g. (sprite 1).Refresh()

Refresh2(spriteRef type sprite)

This method reloads the current page.

e.g. (sprite 1).Refresh2()

PageSetup(spriteRef type sprite)

This method shows the Print Setup dialog. This method has no effects in the Macintosh platform.

e.g. (sprite 1).PageSetup()

PrintPreview(spriteRef type sprite)

This method shows the Print Preview dialog of the current page. This method has no effects in the Macintosh platform.

e.g. (sprite 1).PrintPreview()

Print(spriteRef type sprite, integer type setup)

This method prints out the current page. If you specify 0, the method prints out in normal way. If you specify 1 at "setup", the method shows the prompt dialog before printing at "setup". If you specify 2 at "setup", the method does not show the prompt dialog before printing. This method has no effects in the Macintosh platform.

e.g. (sprite 1).Print(0)

Save(spriteRef type sprite, string type fileName)

This method Saves the current page contents (html) to the specified file. This method has no effects in the Macintosh platform. This method doesn't support Microsoft's Archive nor Complete html format, nor pages in a frameset.

e.g. (sprite 1).Save("test.html")

Save(spriteRef type sprite)

This method shows the SaveAs dialog for the current page contents (html). This method has no effects in the Macintosh platform. This method doesn't support Microsoft's Archive nor Complete html format, nor pages in a frameset.

e.g. (sprite 1).SaveAs()

Scroll(spriteRef type sprite, integer type x, integer type y)

This method scrolls the page in the web browser to specified position. The position values are in pixel unit, absolute coordinates from top-left side of the page.

e.g. (sprite 1).Scroll(10,20)

ScrollBy(spriteRef type sprite, integer type x, integer type y)

This method scrolls the page in the web browser to specified position. The position values are in pixel unit, relative coordinates from top-left side of the page.

e.g. (sprite 1).ScrollBy(10,20)

MakeTextLarger(spriteRef type sprite)

This method enlarges the text font size one unit in the web browser, if available.

e.g. (sprite 1).MakeTextLarger()

MakeTextSmaller(spriteRef type sprite)

This method en smalls the text font size one unit in the web browser, if available.

e.g. (sprite 1).MakeTextSmaller()

SearchFor(spriteRef type sprite, string type keyword, integer type forward, integer type caseSensitive)

This method searches for the specified keyword in the current page. If the keyword is found, the method scrolls the page there and highlights the keyword. If you specifies true or 1 at "forward", the search is done in the forward direction. If you specifies false or 0 at "forward", the search is done in the backward direction. If you specifies true or 1 at "caseSensitive", the search is case sensitive. If you specifies false or 0 at "caseSensitive", the search is not case sensitive. This method has no effects in the Windows platform.

e.g. (sprite 1).SearchFor("Director",true,false)

EvalScript(spriteRef type sprite, string type script)

This method executes the specified JavaScript command. In the Macintosh platform, this method returns the return value of the JavaScript command.

e.g. put (sprite 1).EvalScript("return confirm('continue?');")

SetFocus(spriteRef type sprite)

This method sets focus on the WebViewer sprite.

e.g. (sprite 1).SetFocus()

UnsetFocus(spriteRef type sprite)

This method unsets focus on the WebViewer sprite. This method has no effects in the Windows platform.

e.g. (sprite 1).UnsetFocus()

Show(spriteRef type sprite)

This method shows the WebViewer sprite on the stage.

e.g. (sprite 1).Show()

Hide(spriteRef type sprite)

This method hides the WebViewer sprite on the stage.

e.g. (sprite 1).Hide()

Sprite event handler

BeforeNavigate2(spriteRef type sprite, string type URL, string type target)

This event handler is called before the web browser begins to load a new page. "URL" provides the URL of the new page. "target" provides the target frame name where the new page will be loaded.

e.g. 
on BeforeNavigate2 me, newURL, newTtarget
	put "BeforeNaigate2" && newURL && newTarget
end

NavigateForwardStateChange(spriteRef type sprite, integer type enable)

This event handler is called when the current capability of forward navigation in the browser history is changed. It's useful to enable and disable the "forward" button of your original web browser. "enable" provides the capability of forward navigation.

e.g. 
on NavigateForwardStateChange me, nextEnable
	if nextEnable = true then
		(sprite 10).locV = 16  -- 'Next' button sprite 
	else
		(sprite 10).locV = -1000
	end if
end

NavigateBackStateChange(spriteRef type sprite, integer type enable)

This event handler is called when the current capability of back navigation in the browser history is changed. It's useful to enable and disable the "back" button of your original web browser. "enable" provides the capability of back navigation.

e.g. 
on NavigateBackStateChange me, backEnable
	if backEnable = true then
		(sprite 11).locV = 16  -- 'Back' button sprite 
	else
		(sprite 11).locV = -1000
	end if
end

TextLargerStateChange(spriteRef type sprite, integer type enable)

This event handler is called when the current capability of enlarging the text font size is changed. It's useful to enable and disable the "larger font" button of your original web browser. "enable" provides the capability of enlarging the text font size.

e.g. 
on TextLargerStateChange me, largerEnable
	if largerEnable = true then
		(sprite 12).locV = 16  -- 'Larger font' button sprite 
	else
		(sprite 12).locV = -1000
	end if
end

TextSmallerStateChange(spriteRef type sprite, integer type enable)

This event handler is called when the current capability of en-smalling the text font size is changed. It's useful to enable and disable the "smaller font" button of your original web browser. "enable" provides the capability of en-smalling the text font size.

e.g. 
on TextSmallerStateChange me, smallerEnable
if smallerEnable = true then
(sprite 13).locV = 16 -- 'Smaller font' button sprite
else
(sprite 13).locV = -1000
end if
end

DocumentComplete(spriteRef type sprite)

This event handler is called when the page loading is completed. The "readyState" property becomes 4.

e.g. 
on DocumentComplete me
	put "DocumentComplete"
end

DownloadBegin(spriteRef type sprite)

This event handler is called when the downloading is begun. The "busy" property becomes 1.

e.g. 
on DownloadBegin me
	put "DownloadBegin"
end

DownloadComplete(spriteRef type sprite)

This event handler is called when the downloading is completed. The "busy" property becomes 0.

e.g. 
on DownloadComplete me
	put "DownloadComplete"
end

FileDownload(spriteRef type sprite)

This event handler is called when the file downloading is begun.

e.g. 
on FileDownload me
	put "FileDownload"
end

NavigateComplete2(spriteRef type sprite)

This event handler is called when the new page is displayed.

e.g. 
on NavigationComplete2 me
	put "NavigationComplete2"
end

NavigateError(spriteRef type sprite, string type URL, string type target, integer type statusCode)

This event handler is called when an error occurs in the page loading. "URL" provides the URL of the new page. "target" provides the target frame name where the new page will be loaded. "statusCode" provides the error information. About status code in detail, refer to this web site.

e.g. 
on NavigateError me, newURL, newTarget, statusCode
	put "NavigateError" && string(statusCode) && "at" && newURL && "(" & newTarget & ")"
end

NewWindow2(spriteRef type sprite, string type URL, string type target)

This event handler is called before a new web browser window will be opened. "URL" provides the URL of the new page. "target" provides the target frame name where the new page will be loaded.

e.g. 
on NewWindow2 me, newURL, newTtarget
	put "NewWindow2" && newURL && newTtarget
end

ProgressChange(spriteRef type sprite, integer type progress, integer type progressMax)

This event handler is called constantly during the page loading. "progressMax" provides the total number of the loading files. "progress" provides the number of files already downloaded.

e.g. 
on ProgressChange me, progress, progressMax
	put "Loading..." && string(progress) && "/" && string(progressMax)
end

StatusTextChange(spriteRef type sprite, string type statusText)

This event handler is called when the status text of the web browser is changed. "statusText" provides the new status text.

e.g. 
on StatusTextChange me, statusText
	(member "StatusText").text = statusText
end

TitleChange(spriteRef type sprite, string type title)

This event handler is called when the page title of the web browser is changed. "title" provides the title of new page.

e.g. 
on TitleChange titleText me
	(member "TitleText").text = titleText
end

Known problems

Windows platform

Macintosh platform

Version history

Version 1.5.1

Version 1.5

Version 1.4

Version 1.3

Version 1.2

Version 1.1

Version 1.0

First public release.

 


Last updated: 2004-08-21