Class MacaoPage

Package kernel

Class MacaoPage

The class MacaoPage is not a class itself, but it is used to document the global properties and methods of the package core/kernel.js.

Field Summary
`boolean`	`_isInternetExplorer` This field is true, if the browser uses the Microsoft Internet Explorer rendering engine.
`boolean`	`_isOpera` This field is true, if the browser uses the Opera rendering engine.
`integer`	`_pageHeight` The height of the page in pixels.
`integer`	`_pageWidth` The width of the page in pixels.
`String`	`basePath` This field keeps the path from the current page to the Macao base directory. It is strongly recommended to set this field before loading the JavaScript libraries.

Method Summary
`Element`	`appendTableCell(Element tableRow, optional integer colspan)` Call this method to append a cell to a table row.
`Element`	`appendTableRow(Element table)` Call this method to append a row to a table.
`void`	`broadcastEvent(String eventType, optional Array params, optional boolean toAllFrames)` Call this method to send an event to all objects.
`void`	`clearGameEvent(String eventName)` Use this method to clear a game event.
`void`	`defResource(String resourceName, String language1Text, optional String language2Text)` Use this method to define the texts of a text resource in one or more languages.
`String`	`getBasePath()` Use this method to get the base path.
`integer`	`getClientHeight()` Provides the height of the current window.
`integer`	`getClientWidth()` Provides the width of the current window.
`Window`	`getFrame(String frameName)` Use this method to get a frame or an iframe by name.
`String`	`getFrameName()` Use this method to get the name of the actual frame.
`String`	`getLanguage()` Use this method to get the name of the language, which is used to actually display this page.
`String`	`getOpenerPageName()` Use this method to get the name of the page, which opened this page.
`String`	`getPageName()` This method calculates the name of the page from the page's filename by removing the extension.
`String`	`getParameter(String parameterName)` This method gets the value of a parameter of the URL, which was used to open the page.
`String`	`getResource(String resourceName, optional String defaultLanguageText, optional boolean nullIfUndefined)` Use this method to get the content of a text resource for the actual language.
`variant`	`getStorageValue(String valueName)` Use this method to get a value from the storage manager.
`Window`	`getStorageWindow()` Use this method to get the window, where the storage manager is loaded.
`void`	`hidePopup()` Use this method to close a popup, which is opened by showPopup().
`void`	`inheritPrototype(Function fromClass, Function toClass)` This method inherits all methods and properties from one prototype to another prototype.
`boolean`	`isBetweenGameEvents(String eventBefore, String eventAfter)` Use this method to test, if one game event is already set and another game event is not set.
`boolean`	`isDesignMode()` Call this method to check, if the design mode is active.
`boolean`	`isGameEvent(String eventName)` Use this method to test, if a game event is set.
`boolean`	`isStorageBlocked()` Call this method to check, if this page may write to the Storage Manager.
`void`	`logError(String message, optional integer errorNumber)` Call this method to display and log an error.
`void`	`openPage(String pageURL, optional String frameName, optional boolean forceReload, optional String basePath)` Opens a page in the defined frame.
`void`	`openResourceExportWindow()` This method opens a dialog window to export the text resources.
`void`	`preloadImage(String imageSource)` This method is called internally to preload an image.
`String`	`replaceSubString(String sourceString, String find, String replace)` This method replaces all occurrences of one string in a source string with another string and returns the result.
`void`	`restoreObjects()` This method calls the method MacaoObject.restore() of all objects to let them restore their values from the Storage Manger.
`variant`	`sendEvent(String eventType, optional Array params, optional String recipientName, optional String frameName)` Call this method to send an event by a global method.
`void`	`setBasePath(String path)` You may use this method to set the base path.
`void`	`setDragThreshold(integer threshold)` Use this method to set the threshold value for all drag operations in this window.
`void`	`setGameEvent(String eventName)` Use this method to set a game event.
`void`	`setLanguage(String language)` Use this method to set the actual language of the page.
`void`	`setPageSize(optional integer width, optional integer height)` Call this method to set the page size for drag operations.
`void`	`setResourceDefaultLanguage(String language)` This method sets the language, which is used by the parameter defaultLanguageText of the method getResource().
`void`	`setResourceDefinitionLanguages(Array languagesArray)` This method sets the languages, which are used by the method defResource() to define resource texts.
`void`	`setStorageValue(String valueName, variant value)` Use this method to set a value to the storage manager.
`void`	`showPopup(String text, optional String html, optional String imageSource, optional integer imageWidth, optional integer imageHeight, optional String cssClassName, optional integer duration)` Use this method to display a popup in on page.
`void`	`storeObjects()` This method calls the method MacaoObject.store() of all objects to let them store their values to the storage manger.

Field Details

boolean _isInternetExplorer

This field is true, if the browser uses the Microsoft Internet Explorer rendering engine.

boolean _isOpera

This field is true, if the browser uses the Opera rendering engine.

integer _pageHeight

The height of the page in pixels.

This value is used to limit the automatic scrolling during drag and drop operations.

integer _pageWidth

The width of the page in pixels.

This value is used to limit the automatic scrolling during drag and drop operations.

String basePath

This field keeps the path from the current page to the Macao base directory. It is strongly recommended to set this field before loading the JavaScript libraries.

The Macao base directory is defined as the directory, which has the subdirectory named core. For example, if you have your HTML page file in the in the subdirectory "myapp", set this field to "../". If you have your page in the subdirectory "myapp/chapter1", set this field to "../../" and so on. The following example shows the setting of the base path for a page "myapp/page1.html":

<html>
<head>
	<script>
		var basePath = "../"
	</script>
	<link rel=stylesheet type="text/css" href="../core/macao.css">
</head>
<body>
	<script language="JavaScript" src="../core/kernel.js" type="text/javascript"></script>
	<script language="JavaScript" src="../core/dynamic.js" type="text/javascript"></script>
	<script language="JavaScript" src="../core/road.js" type="text/javascript"></script>
	...
</body>
</html>

Method Details

Element appendTableCell(Element tableRow, optional integer colspan)

Call this method to append a cell to a table row.

This utility method implements a way to add a cell to a table row, which works on all supported browsers.

Parameters

tableRow:

colspan:

Returns

Element appendTableRow(Element table)

Call this method to append a row to a table.

This utility method implements a way to add a row to a table, which works on all supported browsers.

Parameters

table:

Returns

void broadcastEvent(String eventType, optional Array params, optional boolean toAllFrames)

Call this method to send an event to all objects.

Parameters

eventType:

params:

toAllFrames:

void clearGameEvent(String eventName)

Use this method to clear a game event.

Parameters

eventName:

void defResource(String resourceName, String language1Text, optional String language2Text)

Use this method to define the texts of a text resource in one or more languages.

You may provide texts for as much languages as you like by providing more parameters. The text has to fit the languages, which are defined using the method setResourceDefinitionLanguages(). You have to call that method first. See the example:

setResourceDefinitionLanguages(["en", "de", "fr"])
defResource(
	"John_Hello",
	"Good morning John!",
	"Guten morgen John!",
	"Bon jour John!"
)

Parameters

resourceName:

language1Text:

language2Text:

String getBasePath()

Use this method to get the base path.

The base path is the relative path between the location of the current page and the Macao base directory. Use this path, if you calculate an image source location. See also setBasePath() and basePath.

What is the BasePath?

All resources in Macao have to be referenced relative to the Macao base directory. This is the directory, which has the sub directory core.
The references to the resources like pages and images have to be handled relative to this directory. Only in the last moment when a page or image is loaded, the base path will be added to get the relative path from the current page to the resource. This is done to easily exchange the resource paths between different packages, pages and frames.
If for example you create a look with an image, the path to the image is stored twice in the look. The source of the image is set relative to the current page. But a second instance of the path relative to the Macao directory is stored. It can be obtained by a getter method.

Returns

integer getClientHeight()

Provides the height of the current window.

Returns

integer getClientWidth()

Provides the width of the current window.

Returns

Window getFrame(String frameName)

Use this method to get a frame or an iframe by name.

It's recommended to use events to communicate between frames rather than to access a frame directly. See also sendEvent().

The examples work with the frames named "page", "controllers" and "inventory". See also getFrameName().

Parameters

frameName:

Returns

String getFrameName()

Use this method to get the name of the actual frame.

The name of a frame is usually defined in the frameset definition. The examples work with the frames named "page", "controllers" and "inventory".

Returns

String getLanguage()

Use this method to get the name of the language, which is used to actually display this page.

The name of the language can be set by using the parameter language in the URL of the frameset. Or it can be set by the page or by calling the method setLanguage() or setLanguageSM(). The following example opens a page setting the German language (de). The default language is "en" (English).

myapp/page1.html?language=de

To set the language in the frameset it should be the top most frameset and it must contain the package storageManager. In the page containing the storage manager, you can set the actual language for all frames using the method setLanguageSM() or the URL parameter language.

It is recommended to use two character lower case language codes. The language controls the text resources, which are provided calling the method getResource().

Returns

String getOpenerPageName()

Use this method to get the name of the page, which opened this page.

This may be useful to place an object e.g. at the matching door. See also getPageName().

Returns

openPage()

String getPageName()

This method calculates the name of the page from the page's filename by removing the extension.

If the page has the filename "page1.html", then the method returns "page1".

Returns

String getParameter(String parameterName)

This method gets the value of a parameter of the URL, which was used to open the page.

Parameters

parameterName:

Returns

String getResource(String resourceName, optional String defaultLanguageText, optional boolean nullIfUndefined)

Use this method to get the content of a text resource for the actual language.

The actual language can be set using the method setLanguage() or the URL parameter language. See getLanguage().

Each text resource has a name and may have the content for several languages. The name of the resource has to be unique in a page.

You can define and request a text resource with one call to this method. This is useful when you start to develop an application in one language. Later you can define this resource in other languages or override this definition for your primary language in a central place.
The following example defines and uses the resource "John_Hello".

setLanguage("en")
...
setResourceDefaultLanguage("en")

var myObject = new MacaoObject("John", "John", 200, 200)

// defining and using the resource in one call
myObject.say(getResource("John_Hello", "Hello John!"))

The first two lines are setting the actual language and the resource default language to English. You can omit these lines, because all languages are by default set to English.
The actual language defines the language, which the user wants to see in the page. It is better set by using the URL parameter "language". The resource default language defines the language, which you use for the text in the parameter defaultLanguageText of the method getResource(). As far as these languages are the same, the method will return the defaultLanguageText "Hello John!".
If you want to extend your application providing an additional language, you may use a central location to define the resource in other languages.

// set the actual language (better use the url parameter)
setLanguage("en")
...
// central place for defining resources
setResourceDefinitionLanguages(["en", "de", "fr"])
defResource("John_Hello", "Good morning John!", "Guten morgen John!", "Bon jour John!")
...
// using the resource
setResourceDefaultLanguage("en")
var myObject = new MacaoObject("John", "John", 200, 200)
myObject.say(getResource("John_Hello", "Hello John!"))

Now the resource "John_Hello" is defined in the languages en, de and fr. Because the method defResource() has precedence over the parameter defaultLanguageText, the value for the resource in the language en is now "Good morning John!". This will be returned by getResource(). You don't need to redefine the English texts in the central place. If you omit the array element "en" for the setResourceDefinitionLanguages() call, you may only define the additional languages here.
You may test the three languages by modifying the call of setLanguage().

Parameters

resourceName:

defaultLanguageText:

setResourceDefaultLanguage()

nullIfUndefined:

Returns

variant getStorageValue(String valueName)

Use this method to get a value from the storage manager.

Parameters

valueName:

Returns

Window getStorageWindow()

Use this method to get the window, where the storage manager is loaded.

The storage manager is used to store values while the pages are switched. See also setStorageValue().

Returns

void hidePopup()

Use this method to close a popup, which is opened by showPopup().

void inheritPrototype(Function fromClass, Function toClass)

This method inherits all methods and properties from one prototype to another prototype.

You can use this method to do multiple inheritances in JavaScript. Because JavaScript is a prototype-based language, the normal way to inherit one class from the other is to set an instance of the super class as prototype for the derived class. You can use this method to copy all methods and properties of another prototype to the derived class. So you can inherit one class from more than one super class.

The only place where this is used in Macao at the moment is optional/road/roadTypes.js. The traffic light object (MacaoRoad_RoadDJuncTL4) is inherited from MacaoObject by instantiate a Macao object and using it as a prototype. The traffic light object is then extended by all the methods and properties of a MacaoRoad object.

// inherit from MacaoObject and MacaoRoad
MacaoRoad_RoadDJuncTL4.prototype = new MacaoObject
inheritPrototype(MacaoRoad, MacaoRoad_RoadDJuncTL4)

Parameters

fromClass:

toClass:

boolean isBetweenGameEvents(String eventBefore, String eventAfter)

Use this method to test, if one game event is already set and another game event is not set.

Parameters

eventBefore:

eventAfter:

Returns

boolean isDesignMode()

Call this method to check, if the design mode is active.

Returns

boolean isGameEvent(String eventName)

Use this method to test, if a game event is set.

Parameters

eventName:

Returns

boolean isStorageBlocked()

Call this method to check, if this page may write to the Storage Manager.

Use this method before you access methods in the Storage Manager directly. Methods in the kernel of this page are checking this blocking implicitly. If you write to the Storage Manager while it is blocked, this might interfere with the loading of a game score.

Returns

void logError(String message, optional integer errorNumber)

Call this method to display and log an error.

Currently all calls to this method are displayed as alert boxes. There is no functionality to switch this off other than modifying this method. At the moment Macao calls this method when noticing design time errors. So there should be no need to switch this off. Currently there is no log functionality.

Parameters

message:

errorNumber:

void openPage(String pageURL, optional String frameName, optional boolean forceReload, optional String basePath)

Opens a page in the defined frame.

It's recommended to open a page to use this method rather than assigning window.location directly. This method informs the opened page about which page was its opener. See also store(), restore(), setAutoRestore() and getOpenerPageName().

Parameters

pageURL:

basePath

frameName:

forceReload:

basePath:

basePath

void openResourceExportWindow()

This method opens a dialog window to export the text resources.

Use this dialog to create the source code for additional languages and the translations of additional resources. You can copy that source code to your page and fill in the translations. See also getResource() and defResource().

void preloadImage(String imageSource)

This method is called internally to preload an image.

The browser caches a preloaded image. When an image with this URL is later used for display, the image is displayed immediately. When the image is not preloaded, the browser requests the image from the server, which may take a while.

Parameters

imageSource:

getBasePath()

String replaceSubString(String sourceString, String find, String replace)

This method replaces all occurrences of one string in a source string with another string and returns the result.

Parameters

sourceString:

find:

replace:

Returns

void restoreObjects()

This method calls the method MacaoObject.restore() of all objects to let them restore their values from the Storage Manger.

Each object may implement the method restore() in another way. This method is called after the page is loaded. You may call this method after loading persisted data to the Storage Manager. See also storeObjects().

variant sendEvent(String eventType, optional Array params, optional String recipientName, optional String frameName)

Call this method to send an event by a global method.

Parameters

eventType:

params:

recipientName:

frameName:

Returns

void setBasePath(String path)

You may use this method to set the base path.

But it's recommended to set the base path before loading the first JavaScript package into the page. So you should better create the variable basePath directly. See basePath. See also getBasePath().

Parameters

path:

void setDragThreshold(integer threshold)

Use this method to set the threshold value for all drag operations in this window.

On drag operations the user has to drag an object a minimum distance to start the drag operation. This is to prevent the start of a drag operation when the user only wants to click an object. This minimum distance is called threshold. By default the threshold is set to 7 pixels. See also activateDrag().

Parameters

threshold:

void setGameEvent(String eventName)

Use this method to set a game event.

This method uses the storage manager to save a game event. The storage manager package should be loaded in the top most frame. So the game events stay alive while the pages in the other frames are changed.
See also clearGameEvent(), isGameEvent() and isBetweenGameEvents().

What are Game Events?

You should use game events to keep the information, if a specific event has happened during the game. For example there has to be a lever been pulled somewhere in your game in order to open a door somewhere else. When the user pulls the lever you set a game event named "LeverPulled". When the user tries to open the door, you test if this game event is set.

Parameters

eventName:

void setLanguage(String language)

Use this method to set the actual language of the page.

The language may also be set using the parameter "language" while open the page or the frameset. See getLanguage(). The language controls the text resources, which are provided calling the method getResource().

Parameters

language:

void setPageSize(optional integer width, optional integer height)

Call this method to set the page size for drag operations.

During a drag operation, the page is automatically scrolled to keep the draged object visible. If the page size is not defined, the user can drag the object with no limit.

Parameters

width:

height:

void setResourceDefaultLanguage(String language)

This method sets the language, which is used by the parameter defaultLanguageText of the method getResource().

Parameters

language:

void setResourceDefinitionLanguages(Array languagesArray)

This method sets the languages, which are used by the method defResource() to define resource texts.

Parameters

languagesArray:

void setStorageValue(String valueName, variant value)

Use this method to set a value to the storage manager.

The storage manager is built to keep values between pages, which are opened one after another. Normally the package storage manager should be loaded in the top most frame. While the pages in frames of the frameset are changed, this frame stays open and can hold the values.

The storage manager can only store values of simple types. Those are number types, Boolean, String and null. This is because the objects, which are created by a page are belonging to that page. When a page is closed, all its objects are deleted. So the storage manager has to convert an object of another page to an object of its own page. At the moment this is only supported for simple data types.

Parameters

valueName:

value:

void showPopup(String text, optional String html, optional String imageSource, optional integer imageWidth, optional integer imageHeight, optional String cssClassName, optional integer duration)

Use this method to display a popup in on page.

The popup is built by the MacaoBubble object. It is centred in the visible client area of the page. This method is useful to create a splash screen while loading a page. See also hidePopup().
If the bubble object has to display other texts for other objects, this will be finished first before the popup will be displayed.

The following example shows a splash screen popup while loading the Macao packages. The package core/kernel.js has to be loaded before, because it contains the popup functionality. The calls of showPopup() and hidePopup() have to be in different script blocks. If they were in the same script block, no popup would be displayed, because the display is not refreshed during a scripts calculation.
The splash screen is only shown, if the page is not opened by another page (! getOpenerPageName()) but by the frameset. So it should only show up at the start of the game.

<html>
<head>
<script>
var basePath = "../"
</script>
<link rel=stylesheet type="text/css" href="../core/macao.css">
<style>
.transparent {
}
</style>
</head>
<body>
<script language="JavaScript" src="../core/kernel.js" type="text/javascript"></script>
<script>
	if(! getOpenerPageName()) {
		showPopup(
			null, null,
			"optional/images/MacaoLogo.gif", 439, 234,
			"transparent", null
		)
	}
</script>
<script language="JavaScript" src="../core/dynamic.js" type="text/javascript"></script>
<script language="JavaScript" src="../core/road.js" type="text/javascript"></script>
<script language="JavaScript" src="../optional/road/roadTypes.js" type="text/javascript"></script>
<script language="JavaScript">
	//...
	// hide splash screen
	hidePopup()
</script>
</body>
</html>

Parameters

text:

html:

imageSource:

getBasePath()

imageWidth:

imageHeight:

cssClassName:

duration:

hidePopup()

void storeObjects()

This method calls the method MacaoObject.store() of all objects to let them store their values to the storage manger.

Each object may implement the method store() in another way. This method is called before the page is closed. You may call this method before persisting the values of the Storage Manager. See also setStorageValue().