Class MacaoTalkItem

Use the class MacaoTalkItem to create talk items and add them to MacaoObjects.

Use the methods MacaoObject.addTalkItem() and MacaoObject.createTalkItem() to add talk items to an object.

What are TalkItems?

Adding talk items to the MacaoObjects is the main technique, which you should use, to define the behavior of the objects. A talk item defines an action. The action is triggered by a trigger event or by a keyword. When the talk item is triggered, it may but not has to display a bubble with text, image or html. This is called saying (see MacaoObject.say()). Every talk item at an object has to have a unique name. After the talk item is executed, its name is broadcasted to all other objects and may there trigger other talk items.

A talk item can used send an event before and an event after the display of the bubble with the message text. See setBeforeEvent() and setAfterEvent(). You can also define not to display a bubble but only execute these one or two events. Do this by defining no message, HTML or image source for the talk item. Using these events, you can call all the methods of the objects.

You can define the view of the bubble by providing a message with the constructor (see MacaoTalkItem()) or setting html or an image (see setImage() and setHTML()). You can define a specific CSS class for one talk item (see setCssClassName()) or for all talk items of an object (see MacaoObject.setTalkCssClassName()). For the object, uses the talk item, you can define a specific look, that will be displayed, while the bubble of the talk item is shown (see setLookName()).

You can change the look of the 'talking' object for a while without displaying a bubble. Call the method setLookName() to set the name of the look, that is to be displayed. Call setDuration() to set the duration for this look. Provide null for the parameter message of the constructor of the talk item. You can use this to display a special emotion of a character.

How to Trigger TalkItems?

Use the parameter triggerEvents of the constructor MacaoTalkItem(), to set the trigger events of a talk item. Use the parameter keywords of the constructor, to define keywords as triggers. If there are more than one talk item at one object, that are triggered by the same event or keyword, one of the talk items is selected at random to execute.

Talk items can be triggered in many ways:

Trigger by Mouse and Object Events

The execution of a talk item can be triggered by an event like a mouse click to the arrival of another object. See below for a list of useful events.

Trigger by another Talk Item

It can be triggered by the execution of another talk item. After the talk item is executed, its name is broadcasted to all other objects or objects that this object is currently meeting (See MacaoObject.isMeetingObject()). These objects are searched for talk items that use the event name as a trigger event. One of them is executed.

Trigger by Controllers

Controllers can trigger talk items. Controllers are objects, which are displayed to let the users interact with other objects. The MacaoSentenceController is used to build sentences of a verb and one or two object names. The sentences are sent as trigger events to the objects, which have registered that controller. (See also MacaoObject.addController()).

Trigger by Response Talk Items

Predefined response talk items may trigger Talk items. You can add a number of response talk items to a talk item (see createResponseTalkItem()). After the talk item is executed, the MacaoTalkController presents the response talk items to the user. The user can choose one of the response talk items to respond. The chosen item will be executed and may trigger other talk items by its name.

Trigger by User Input Keyword or Password

A response talk item can have an input field or a password field. To use an input field, just add one of the placeholders %input% or %password% to the message of a response talk items. The user can type a text in that field and hit enter. The difference between an input field and a password field is, that in a password field are appearing asterisks instead of the text, when the user enters text. After the user enters the password, the text is not displayed as a bubble by the character that is controlled by the user, because that would betray the password.

The Text is send back to the object, which defined the response talk items. The object is searched for talk items with a fitting keyword. One of the fitting talk items is executed. Use the parameter keywords at the constructor MacaoTalkItem(), to define the keywords of a talk item. If there is no talk item with a fitting keyword, the name of the response talk item is used as trigger event to search for talk items. So you can define a default response.

To find a talk item with the fitting keyword for an entered free text, first the text is trimmed. That means, all leading and trailing white space and double white space within the text is removed. The keywords and the entered text are converted to lower case, so the search is not case sensitive. The object is first searched for a keyword, which contains the entire entered phrase. If no such talk item is found, than the phrase is split into words and the keywords are searched for each word. If no talk item is found by this keyword search, the object is searched for a talk item whose trigger event matches the name of the response talk item, which was used to enter the phrase.

Trigger by Method Call

Talk items may be triggered by the call of the method MacaoObject.hearEvent() or MacaoObject.hearFreeText(). To hearEvent() you can provide the name of a trigger event. To hearFreeText() you can provide the text that is searched for keywords. The method searches the object for talk items with the fitting trigger event or keyword and executes one of them.

Every Event may be used as Trigger

Talk items may be triggered by every event, which an object receives. Each event is used to search for talk items with a fitting trigger event. See MacaoObject.sendEvent()). First there are searched talk items with the trigger event of the type EventName_SenderName, where EventName is the name of the received event and SenderName is the name of the object, that sent the event. When there is no fitting talk item found, the object is searched for a trigger event of EventName.

Restricting the Validity

You can restrict the talk items that are scanned for a trigger event by using game events (see setGameEvents()). You can define that a talk item is only active after one game event and/or before another game event. You can also define, that the talk item sets or clears a game event, after it is executed. See isGameEvent().

Another way to restrict the validity of a talk item is to set the parameter onceAtTalk at the constructor MacaoTalkItem(). If this parameter is set to true, the talk item is only executed once. To bring the talk item back into play, once it is executed, you have to call the method MacaoTalkItem.setClearTalk(). Both methods are resetting all talk items with the property onceAtTalk.

Useful Trigger Events

Here you can find a list of events, which can be used as trigger events to trigger your talk items:

Node Events

When a name is set to a MacaoNode, then the object gets events, when it is entering or leaving the node. Use the method MacaoNode.setName() to set a name to the node. If the node is part of a road element, you can use the method MacaoPage.getRoadByName() to get the road element. Use the method MacaoRoad.getNodeByIndex() to get the node of the road.
enteringNode_NodeName: This event is raised, when the object enters the node. Replace NodeName with the name of the node.
leavingNode_NodeName: This event is raised, when the object leaves the node. Replace NodeName with the name of the node.
leavingNode_NodeName_to_NextNodeName: This event is raised, when the object leaves one node in the direction of another node. Both nodes have to be named. Replace NodeName with the name of the node, which is left. Replace NextNodeName with the name of the next node the object is walking to.

Meeting Events

Two objects are meeting each other, when one of them enters a node, which is assigned to the other. It leaves the other, when it leaves the assigned node. Use the method MacaoObject.setAssignedNode() to assign a static object to a node.
meet: This event is raised, when the object meets any other object.
leave: This event is raised, when the object leaves any other object.
meet_ObjectName: This event is raised, when the object meets the object with the ObjectName. This event is most useful to begin a talk.
leave_ObjectName: This event is raised, when the object meets the object with the ObjectName.

Mouse Events

These events are raised by the mouse:
onMouseOver: This event is raised, when the user moves the mouse pointer over the object.
onMouseOut: This event is raised, when the user moves the mouse pointer off from over the object.
onMouseDown: This event is raised, when the user clicks the left mouse button down on the object.
onMouseUp: This event is raised, when the user lets the left mouse button up on the object.
onClick: This event is raised, when the user clicks the left mouse button on the object.
onDblClick: This event is raised, when the user double clicks the left mouse button on the object.

Keyboard Events

Be careful when using keyboard events, because the browsers occupy most of the keyboard events. Key-combinations with the Alt-key are setting the focus to the menu bar. Key-combinations with the Control-key are occupied by menu shortcuts. And even when you find a Control-combination, which is not occupied, the user may suspect a bad intention. Also most of the function keys are occupied by browser specific functions. These functions may change over time. The navigation keys like the cursor keys, page up and so on are used to scroll the page.

So there are the alphabetic keys left. In Mozilla they are used to jump to the next link element. Because most of your Macao pages will have no links, you may use them anyway. The only case, where you can use nearly all keyboard events, is in stand-alone applications. But these are running only on Windows and not in the browser. They have to be installed locally.

How ever, Macao generates trigger events for nearly all keys and key-combinations. For key-codes lower than 47 the trigger event has the format key_KeyCode_Shift_Alt_Ctrl. For key codes greater equal 47 the trigger event has the format key_Character_Alt_Ctrl. Here are the components of the format:
KeyCode: This is replaced by the numeric key code. So this is a number between 0 and 46.
Character: This is replaced by the character of the Latin 1 character-set, which is corresponding to the key-code. For others than the standard ASCII characters, this mostly will differ from the label on the keyboard key. If the shift key is pressed, this character is converted to upper case. Else it is converted to lower case.
_Shift: This element is only added, if the shift key is pressed. It is only part of the first format, because the other format has this information in the case of the character.
_Alt: This element is only added, if the alt key is pressed.
_Ctrl: This element is only added, if the control key is pressed.

Here are some examples (key combination: trigger event).
a: key_a
shift-b: key_B
control-c: key_c_Ctrl
up-arrow: key_38
shift: key_16
ctrl: key_17
enter: key_13

The keyboard trigger events are sent to all objects in all frames. This is independent from the frame, which has the focus, when the key is pressed. But one of the frames needs to have the focus. When you load a frameset to the browser, initially none of the frames will have the focus. You should set the focus to the frame of the content page in the onload-event of each content page . The frame will also get the focus, when the user clicks to it.

Load and Unload Event

These events are raised, when the page is loaded and unloaded.
onLoad: This event is raised, after the page has loaded.
onUnload: This event is raised, before the page starts to unload.

Sentence Controller Events

You can include the MacaoSentenceController in one frame, to let the user talk to your object. You have to call MacaoObject.addController(), to register the sentence controller to your object. The object then will receive trigger events, that use the following formats, where Command is one of the commands, that are defined by the sentence controller and Object1 is the fist object and Object2 is the second object, that is clicked by the user:
Command: This event is raised, when the user clicks one verb of the sentence controller.
Command_Object1: This event is raised, when the user clicks one verb on the sentence controller and then one object.
Command_Object1_Object2: This event is raised, when the user clicks one verb on the sentence controller and then object 1 and object 2.
Command_Default: This event is raised, when the user has clicked a command on the sentence controller and then one or two objects and there were no fitting event of the other three types. So you can define a default TalkItem, which is exectued, when the user doesn't find the fitting objects. If the event is executed after the user has clicked the first or the second object depends on, if there is a conjunction defined for the command at the sentence controller or is not. If there is no conjunction defined, then the sentence controller decides after the first object, if the user failed to build the valid sentence, and sends the default event. See also MacaoSentenceController.addSentenceCommand().

By default, the page optional/controllers/controllers.html creates a sentence controller with the following commands and conjunctions:
Look without conjunction.
Talk without conjuction.
Use with.
Consume with.
Open with.
Close with.
Take without conjuction.
Give to.
So if you want to add a talk item, that acts when the user builds the Sentence "Open door with key", you add the trigger event Open_Door_Key to the object, where Door and Key are the names of the objects, the user has to click on.

Drag and Drop Events

These events are raised, when drag is activated for an object. See also MacaoObject.activateDrag().
dragStart: This event is raised, when the user starts dragging the object.
draggedMeOver_ObjectName: This event is raised, when the user drags this object over an object, for that drop is activated. ObjectName is the name of the other object.
draggedMeOut_ObjectName: This event is raised, when the user drags this object out of an object, for that drop is activated. ObjectName is the name of the other object.
droppedMeTo_ObjectName: This event is raised, when the user drops this object to an object, for that drop is activated. ObjectName is the name of the object this object is dropped to.
dragEnd: This event is raised, when the user stops dragging the object.

These events are raised, when drop is activated for an object. See also MacaoObject.activateDrop().
draggedOverMe_ObjectName: This event is raised when the user draggs an object over this object. ObjectName is the name of the dragged object.
draggedOutMe_ObjectName: This event is raised when the user drags an object out of this object. ObjectName is the name of the dragged object.
droppedToMe_ObjectName: This event is raised when the user drops an object to this object. ObjectName is the name of the dropped object.

Examples

Example: Automatic Dialog

The following example defines an automatic dialog between the two objects Jim and Sandy. The dialog starts, when the user clicks on Jim. The dialog is as follows:

Jim: Hello, how are you?
Sandy: Thanks. Do you come to the party tonight?
Jim: Where is a party? I haven't heard about it.
Sandy: It's at Julie at home.

// create and position Jim and Sandy
var jim = new MacaoObject("Jim", "Jim", 300, 300)
var sandy = new MacaoObject("Sandy", "Sandy", 450, 300)

// define the images
jim.setImage("jim.gif")
sandy.setImage("sandy.gif")

// add talk items
jim.createTalkItem(
	"Jim_Hello", "onClick",
	"Hello, how are you?"
)
sandy.createTalkItem(
	"Sandy_Hello_Party", "Jim_Hello",
	"Thanks. Do you come to the party tonight?"
)
jim.createTalkItem(
	"Jim_Where_Party", "Sandy_Hello_Party", 
	"Where is a party? I haven't heard about it."
)
sandy.createTalkItem(
	"Sandy_Party_Karen", "Jim_Where_Party",
	"It's at Julie at home."
)

Example: Use of the Sentence Controller

The next example defines a dialog between the automatic character Caren and the character John, which is controlled by the user. To give the user the ability to send the Talk command to John, you have to include a MacaoSentenceController in your page. To display the response talk items, you have to include a MacaoTalkController in your page. You can add both controllers by including the page optional/controllers/controllers.html in one frame of a frameset. The page names the controller "SentenceController". To let John be controlled by that controller, the controller has to be registered to John. The dialog has to start, when the user tells John to talk to Caren. John then gets the option to ask Caren for a party or for a pencil. Every of this questions can only be asked once per talk.

When Caren is asked for a pencil, the pencil is added to the inventory. In order to do that, the MacaoInventory has to be added to the page. You can do that by include the page optional/controllers/inventory.html in the frame named "Inventory" of the frameset.

To clear the information of "oncePerTalk", Sandy clears the talk in her hello item. The dialog has to be the following, where the user can vary the order of the questions:

John: Hello Caren.
Caren: Hi John!
John: Did you hear something about a party tonight?
Caren: Yes, Julie is throwing a party.
John: May I have your pencil please?
Caren: Yes, here you are.
(Caren gives her pencil to John)

// define a variable for a talk item
var talkItem

// create John and Caren
var john = new MacaoObject("John", "John", 300, 300)
var caren = new MacaoObject("Caren", "Caren", 450, 300)

// register the sentence controller
john.addController("SentenceController")

// add the characters images
john.setImage("john.gif")
caren.setImage("caren.gif")

// let John answer to the Talk command of the sentence controller
john.createTalkItem("John_Hello_Caren", "Talk_Caren", "Hello Caren.")

// define an array with the response talk items
var responseTalkItems = [
	new MacaoTalkItem(
		"John_IsParty", null,
		"Did you hear something about a party tonight?",
		null, true
	),
	new MacaoTalkItem(
		"John_PencilPlease", null,
		"May I have your pencil please?",
		null, true
	)
]

// let Caren say hello
talkItem = caren.crateTalkItem(
	"Caren_Hello_John", "John_Hello_Caren",
	"Hi John!"
)

// clear all onceAtTalk items
talkItem.setClearTalk(true)

// add the responses to the hello prase
talkItem.createResponseTalkItem(responseTalkItems)


// add the answer to the party question
talkItem = caren.crateTalkItem(
	"Caren_Party_Julie", "John_IsParty",
	"Yes, Julie is throwing a party."
)

// add the responses to julie response
talkItem.createResponseTalkItem(responseTalkItems)


// add the answer to the pencil question
talkItem = caren.crateTalkItem(
	"Caren_Gives_Pencil", "John_PencilPlease",
	"Yes, here you are."
)

// define the event that puts the pencil to the inventory
talkItem.setAfterEvent(
	"addInventoryItem",
	["Pencil", "Pencil", "pencil.gif"],
	"Inventory", "inventory"
)

// add the responses to pencil response
talkItem.createResponseTalkItem(responseTalkItems)

The response talk items need no trigger event, because their parent talk item triggers their display to the user. When Caren answers one of the questions, the response talk items are displayed again. Because they have the type onceAtTalk, the executed response talk item will not be displayed again

The only talk item, which is added to John, that is the item "Talk_Caren", the start item. The sentence controller triggers that item. All other items of the dialog between Caren and the user (John) are added to Caren. That has the advantage, that you can define all talk items for a dialog in one place.

After the Caren says, "Yes, here you are," an event is sent to the object "Inventory" in the frame "inventory". The name of the frame is provided, to make sure, the object gets the event, even if the inventory page is not fully loaded. If the frame name is provided, the event will be buffered until the page is loaded. The event adds an inventory item with the name and the title "Pencil", that is displayed by the image pencil.gif. See also MacaoInventory.

Example: Use of an Input Field

This example puts an input field to the only response talk item. The user may type a keyword to the response talk item, which is displayed in the sentence controller, to guess what is Joan's favorite dish.
To let the user interact with the characters, you have to include the MacaoSentenceController and MacaoTalkController in your page, like in the example above. The dialog has to start, when the user states "Talk to Joan" using the sentence controller.
First we draft the dialog:

Marc: Hi Joan. Do you go to lunch with me?
Joan: Yes, they have my favorite dish today. Guess what it is!
Marc: Apple pie.
Joan: No, I don't like apples.
Marc: Fish and chips.
Joan: No, I don't like 'Fish and chips' so much.
Marc: Spaghetti.
Joan: Yes, that's it. They have meatballs with spaghetti.

// create a variable for a talk item
var talkItem

// create the characters
var marc = new MacaoObject("Marc", "Marc", 200, 300)
var joan = new MacaoObject("Joan", "Joan", 350, 300)

// set the character's images
marc.setImage("marc.gif")
joan.setImage("joan.gif")

// let Marc say hello
marc.createTalkItem(
	"Marc_Hello_Joan", "Talk_Joan",
	"Hi Joan. Do you go to lunch with me?"
)

// let Joan riddle Marc
talkItem = joan.crateTalkItem(
	"Joan_Riddle_Dish", "Marc_Hello_Joan",
	"Yes, they have my favorite dish today. Guess what it is!"
)

// create the guess response talk item enclosed in an array
responseTalkItems = [
	new MacaoTalkItem(
		"Marc_Guess_Dish", null,
		"I think you like %input% most."
	)
]
talkItem.createResponseTalkItem(responseTalkItems)


// Joans answer to apple pie
talkItem = joan.createTalkItem(
	"Joan_Apple_Pie", null,
	"No, I don't like apples.",
	["apple", "pie"]
)

// Marc failed, display the response talk item again
talkItem.createResponseTalkItem(responseTalkItems)


// Joans answer to an unknown dish like Fish and chips
talkItem = joan.createTalkItem(
	"Joan_Unknown_Dish", "Marc_Guess_Dish",
	"No, I don't like '%input%' so much."
)

// Marc failed, display the response talk item again
talkItem.createResponseTalkItem(responseTalkItems)


// Joans answer to spaghetti
joan.createTalkItem(
	"Joan_Apple_Pie", null,
	"Yes, that's it. They have meatballs with spaghetti.",
	["meatballs", "spaghetti"]
)

The answers to "apple pie" and "meatballs spaghetti" are recognized by one of two keywords, so the keywords have to be enclosed in an array. Every unknown answer like "Fish and chips" is responded by a talk item, which uses the name of the response talk item "Marc_Guess_Dish" as a trigger. So it's the default answer. It displays the input value itself by using the placeholder %input%. All answers to a wrong guess are displaying the standard response talk item again.

If you would use the parameter %password% instead of %input%, the user will get a password field to enter the text. The message with the password is not be displayed by Marc, because this would compromise the password. But Joan would hear the password.

This is the constructor for creating a new talk item or response talk item.

For a detailed description, on how to use talk items, see the class description of MacaoTalkItem.

Parameters

itemName: Provide a unique name for the talk item. The name of the talk item is automatically used to handle the text resource of the message (See also MacaoPage.getResource() and MacaoPage.defResource()). This name can also be used as trigger event for other talk items (see next parameter). It is recommended to start the name of the talk item with the name of the MacaoObject, which is using the talk item.
triggerEvents: Provide the name of one or more events, which will cause the execution of this event. You can provide one event as single String. You can provide a number of trigger events as an Array of Strings. See the description of the class MacaoTalkItem for useful trigger events. If you use this talk item as response talk item of you want it to be triggered by keywords (see parameter keywords) you can set this parameter to null.
message: Provide the message, that is to be displayed in the bubble or as a response talk item in the MacaoTalkController.
If you use this talk item as response talk item, you may include one of the placeholders %input% or %password%. When displayed in the talk controller, an input- or password field will replace this placeholder. When the message of the response talk item will be displayed in the bubble, the placeholder %input% will be replaced by the entered text. A message with the placeholder %password% will not be displayed in the bubble, because this would compromise the password.
The message may also contain the placeholder %sender%. This placeholder will be replaced by the title of the object, whose event caused the execution of this talk item. So this object can for example say "Hello title !" to another object. This placeholder currently does not work with inventory items.
The message, which you provide here, is automatically added to the resources and received from the resources. The item name is used as the item name is used as resource name. See also MacaoPage.getResource().
Set this parameter to null, if you don't want a message to be displayed or you want the bubble to be displayed using html or an image. See setHTML() and setImage().
keywords: Provide keywords, if you want the talk item to be executed by the entering of a keyword. See the description of the class MacaoTalkItem for a detailed description how to use keywords. You can provide a single keyword as String. You can provide a list of keywords a String, separated by commas, or as Array of Strings. Set this parameter to null, if you don't want this talk item to be triggered by keywords.
onceAtTalk: Set this parameter to true, if you want this talk item to be executed only once at a talk. Once it is executed, its name is added to a list of executed talk items, so that is not available for execution again, until the list is cleared. You can mark another talk item with setClearTalk(), so that it will clear this list. Set this parameter to false, if you don't want to restrict the availability of this talk item.

Call this method to create and add a response talk item to the talk item.

See the description of the class MacaoTalkItem for a description on how to use response talk items.

Parameters

itemName: Provide a unique name for the talk item. The name of the talk item is automatically used to handle the text resource of the message (See also MacaoPage.getResource() and MacaoPage.defResource()). This name can also be used as trigger event for other talk items (see next parameter). The name can also be used to set as game event (see MacaoTalkItem.setGameEvents()). It is recommended to start the name of the talk item with the name of the MacaoObject, which is using the talk item.
message: Provide the message, that is to be displayed in the bubble or as a response talk item in the MacaoTalkController.
You may include one of the placeholders %input% or %password%. When displayed in the talk controller, an input- or password field will replace this placeholder. When the message of the response talk item will be displayed in the bubble, the placeholder %input% will be replaced by the entered text. A message with the placeholder %password% will not be displayed in the bubble, because this would compromise the password.
The message may also contain the placeholder %sender%. This placeholder will be replaced by the title of the object, whose event caused the execution of this talk item. So this object can for example say "Hello title !" to another object. This placeholder currently does not work with inventory items.
The message, which you provide here, is automatically added to the resources and received from the resources. The item name is used as the item name is used as resource name. See also MacaoPage.getResource().
Set this parameter to null, if you don't want a message to be displayed or you want the bubble to be displayed using html or an image. See MacaoTalkItem.setHTML() and MacaoTalkItem.setImage().
onceAtTalk: Set this parameter to true, if you want this talk item to be executed only once at a talk. Once it is executed, its name is added to a list of executed talk items, so that is not available for execution again, until the list is cleared. You can mark another talk item with MacaoTalkItem.setClearTalk(), so that it will clear this list. Set this parameter to false, if you don't want to restrict the availability of this talk item.
activatingItemName: Provide the name of a talk item, which has to be executed during a talk to activate this talk item. Only active talk items are available for execution or for use as response talk item. Set this parameter to null, if the activity of this talk item has not to be restricted by another talk item.
deactivatingItemName: Provide the name of a talk item, which will activate this talk item during the current talk, when it is executed. Only active talk items are available for execution or for use as response talk item. Set this parameter to null, if the activity of this talk item has not to be restricted by another talk item.


Returns

The method returns the just created talk item. You can use the return value to modify properties of the talk item.

Call this method to get the information if the message is to be hidden during execution of the talk item.

Returns

The method returns true, if the message is to be hidden. Else it returns false.

Use this method to get the HTML, which is to be displayed in the bubble by this talk item.

Returns

Return the HTML or null, if there is to be displayed a plain text message or an image in the bubble.

Call this method to test, if the object has to keep the look, which is set by the talk item.

Returns

The method returns true, if the object has to keep the look. It returns false, if the object has to revert to its previous look.

Call this method to get the message text, which is used to display in the bubble or in the MacaoTalkController.

Returns

This method returns the method or null, if the bubble should display HTML or an image or there is not bubble to display.

Call this method to get the name of the talk item.

Returns

Returns the name of the talk item.

Call this method to get the out-of-responses trigger.

See also setOutOfResponsesTrigger().

Returns

The method returns the defined trigger. It returns null, if there is no trigger set.

You may implement this method for more complex control of when the talk item is available for execution.

When this method is implemented, it will be queried, if the talk item is available for execution. So you can implement more complex conditions than with the parameters beforeGameEvent and afterGameEvent of the method setGameEvents().
The following example defines the talk item active, after the game event "KeyTaken" is set but before the game event "DoorUnlocked" is set.

// create object
var hero = new MacaoObject("Hero", "Arnold", 100, 100)

// add talk item
var talkItem = hero.createTalkItem("Hero_Hello", "onMouseDown", "Hi fans!")

// define talk item validity
talkItem.isActiveCustom = function() {
	return isGameEvent("KeyTaken") && !isGameEvent("DoorUnlocked")
}

The following example does the same with the method setGameEvents(). You may combine both techniques. Then the talk item will be active when both are true.

//... like above ...

// define talk item validity
talkItem.setGameEvents("KeyTaken", "DoorUnlocked", null, null)

You may assign the implementation of the method to more than one talk item. See the example:

// create object
var hero = new MacaoObject("Hero", "Arnold", 100, 100)

var myMethod = function() {

	return isGameEvent("KeyTaken") && !isGameEvent("DoorUnlocked")

}

// add talk item
var talkItem = hero.createTalkItem("Hero_Hello", "onClick", "Hi fans!")

talkItem.isActiveCustom = myMethod

// add another talk item

talkItem = hero.createTalkItem("Hero_Bye", "onClick", "Good bye.")


talkItem.isActiveCustom = myMethod

Returns

Return true, if the talk item currently has to be available for execution. Otherwise return false.

Call this method to set talk items, which activates or deactivates the current talk item, when it is executed.

Use the method setClearTalk() to mark a talk item as the beginning of a new talk.

Parameters

activatingItemName: Provide the name of a talk item, which has to be executed during a talk to activate this talk item. Only active talk items are available for execution or for use as response talk item. Set this parameter to null, if the activity of this talk item has not to be restricted by another talk item.
deactivatingItemName: Provide the name of a talk item, which will activate this talk item during the current talk, when it is executed. Only active talk items are available for execution or for use as response talk item. Set this parameter to null, if the activity of this talk item has not to be restricted by another talk item.

Call this method to define an event, which has to send or posted after the bubble of the talk item is displayed.

See also MacaoObject.sendEvent() and MacaoObject.postEvent().

Parameters

eventType: Provide the name of the event.
params: Provide an array with parameters for the event. Provide null, if the event needs no parameters.
targetObjectName: Provide the name of the object, to which the event has be send to. Provide null or 0, if the event has to be sent to the object, that the talk item belongs to.
delay: Provide the delay of the event in milliseconds, if the event has to be delayed. Set this parameter to null, if you want the event to be sent immediately.
frameName: Provide the name of the frame, to which the event has to be sent to. Provide null, if all frames have to be searched for the target object.

Call this method to define an event, which has to send or posted before the bubble of the talk item is displayed.

See also MacaoObject.sendEvent() and MacaoObject.postEvent().

Parameters

eventType: Provide the name of the event.
params: Provide an array with parameters for the event. Provide null, if the event needs no parameters.
targetObjectName: Provide the name of the object, to which the event has be send to. Provide null or 0, if the event has to be sent to the object, that the talk item belongs to.
delay: Provide the delay of the event in milliseconds, if the event has to be delayed. Set this parameter to null, if you want the event to be sending immediately.
frameName: Provide the name of the frame, to which the event has to be sent to. Provide null, if all frames have to be searched for the target object.

Call this method, if you want the name of this talk item to be sent as trigger event to all objects or just the objects, which are meeting the talking objects.

By default this property is set to true, so all objects are informed about what the talking object says. See also MacaoObject.getMeetingObjectNames().

Parameters

broadcast: Set this parameter to true, if you want all other objects to hear this talk item when executed. Set this parameter to false, if you want only the currently meeting objects to hear the execution of this talk item. Only the hearing objects may have their talk items triggered by this trigger event. The default value is true.

Call this method to define, that this talk item, when executed, has to clear the list of talked items.

In this list, there are added the talk items, that have the property set onceAtTalk and that have been executed since the last clearing of the list. While added to the list, these items are not used for talk operations. See also the class description MacaoTalkItem and the constructor MacaoTalkItem().

Parameters

active: Set this parameter to true, if the talk item has to clear the list when executed. Set this parameter to false, if you don't want the talk item to clear the list.

Call this method to set a specific cascading style sheet class, which has to be used to display the bubble.

See also MacaoObject.setTalkCssClassName() to set class name, that is used for all talk items of the object.

Parameters

cssClassName: Provide the name of a style sheet class, which you want to be used for display. Provide null, if you want the standard style to be used.

Call this method to set the duration, for which the bubble of the object is to be displayed.

By default, the duration is calculated by the length of the message. See also MacaoObject.say().

Parameters

duration: Provide the duration of the display in milliseconds. Provide 0, if you want the duration be calculated from the length of the message.

Call this method to restrict the validity of this talk item by game events and/or set the name of the talk item as game event when executed.

The first and the second parameter are restricting the validity of the talk item, when set. The third and the fourth parameter are changing game events, when set. See also MacaoPage.setGameEvent().

Parameters

beforeGameEvent: Provide a name of a game event, if this talk item has only to be used after the game event is set. Provide null to not restrict the validity of the talk item.
afterGameEvent: Provide a name of a game event, if this talk item has only to be used before the game event is set. Provide null to not restrict the validity of the talk item.
setGameEvent: Provide the name of a game event, which is to be set, after the talk item has been executed. Provide null, if there is no game event to set.
clearGameEvent: Provide the name of a game event, which is to be cleared, after the talk item has been executed. Provide null, if there is no game event to be cleared.

Call this method to hide the message when the talk item is executed.

This is useful for response talk items. If you hide the message and the user selects the response talk item, the execution of the item shows no message.

Parameters

active: Set this parameter to true to hide the message on execution of the talk item. Set this parameter to false to show the message.

Call this method to define, that this talk item has to display HTML in the bubble, rather than a message, that could be provided with the talk items constructor.

See also MacaoTalkItem().

Parameters

html: Provide the HTML, which has to be displayed in the bubble. Provide null, to clear the html.

Call this method to set an image, which is displayed as the bubble content.

To have this image displayed, you may not have defined a message in the constructor of the talk item. See MacaoTalkItem().

Parameters

imageSource: Provide the image source URL relative to the base path.
imageWidth: Provide the base width of the image in pixels.
imageHeight: Provide the base height of the image in pixels.

Call this method to define a look, which is to be displayed for the object, while the bubble of the talk item is displayed.

See also MacaoObject.createLook().

Parameters

lookName: Provide the name of a specific look, which is to be displayed. The look has to be added to the object itself. Provide null, if you don't want a specific look to be displayed.
keepLook: Set this parameter to true, if the object has to keep the look, after the talk item was executed. Use the method MacaoObject.setPreferredLook() to clear this look later. Set this parameter to false, if the object has to revert to its previous look.

Call this method to define a trigger event, which will be sent, when all response talk items are gone inactive.

Response talk items can become inactive by multiple causes. They can have the property onceAtTalk, they can be deactivated by other talk items or by game events. When all response talk items are gone inactive when the talk item is executed, then this trigger event is sent to the talking object. You can use this trigger to continue the talk, when it is running out of responses. See also createResponseTalkItem() and setGameEvents().

Parameters

outOfResponsesTrigger: Provide a trigger, which will be sent, when the talk item is executed and has to response talk items. Set this parameter to true, if you need no trigger for this case.

Call this method to set a direction, to which the object has to turn before executing the talk item.

The direction is absolute, if you provide no object name. If you provide an object name, the direction is calculated as an angle to north. The angle is added to the direction between the talking object and the target object. Provide 0 to both direction components, to use no relative angle between the talking object and the target object.

Parameters

directionX: Provide the x-component of the direction or the angle. Provide 0, if the talking object has to direct to the target object.
directionY: Provide the y-component of the direction or the angle. Provide 0, if the talking object has to direct to the target object.
objectName: Provide the name of the target object, if the talking object has to direct to the target object or relative to the target object. Provide null to define an absolute direction. A relative direction is calculated by the anchor positions of the objects.

Call this method to set a position, to which the object has to walk to before executing the talk item.

The position is relative to the page, if you provide no object name. If you provide an object name, the position is relative to the object. A position is calculated by the anchor positions of the objects.

Parameters

anchorXPos: Provide the x-component of the position relative to the page or relative to the target object.
anchorYPos: Provide the y-component of the position relative to the page or relative to the target object.
objectName: Provide the name of the target object, to define the position relative to it. Provide null, to define the position relative to the page.