Class MacaoSentenceController

The MacaoSentenceController can be added to a page to let the user build sentences from commands and object titles. The sentence is send to all objects, which have registered this controller. At the object the sentence may cause the execution of a MacaoTalkItem.

How does the Sentence Controller work?

You can include a sentence controller in your application to let the user build sentences. The built sentence is sent to all objects as trigger event. The trigger event may cause the execution of a MacaoTalkItem at the object.

You need to add a number of commands to the sentence controller. The commands are displayed as menu items. The user can build a sentence by clicking a command and then click on one or two objects. The resulting sentence is displayed and sent to the object. The trigger event has the form Command_ObjectName1_ObjectName2, where Command is the name of the commands menu item, ObjectName1 and ObjectName2 are the names of the objects, which the user has clicked.

The sentence controller only listens to clicks on objects, which have the property approachable set (see MacaoObject.setApproachable()) and to objects in the inventory (see MacaoInventory).

If a conjunction is defined for a command, two objects can be added to the sentence. If there is no conjunction defined, the sentence can only have one object.

The user has first to click on the command and then on the objects. If the user clicks first on an object, the default command is used to build the sentence. You can define the default command by calling setSentenceDefaultCommand(). By default the first command, which was added to the controller, is set as the default command.

An object, whichis to be controlled by the Sentence Controller, needs to register the controller. You can register the sentence controller calling MacaoObject.addController(). When the object has a Talk Item, which is triggered by a sentence built of the command name and the first object name, it informs the Sentence Controller to end the sentence. Else if the sentence has a conjunction and the controlled object has a Talk Item, which might be triggered by the extended sentence, the sentence stays open and the user has to click on another object to continue the sentence. Or the user can click on a command to begin a new sentence. The controlled object can react to the sentence with the command with two objects. Or it can react to the command by a default talk item, which is triggered by an event of the form Command_Default, where Command is the name of the command menu item.

When the controlled object has responded to the command or the maximum length of the sentence is reached, the sentence is closed. When the sentence is closed, it is still displayed for a little moment and then cleared. The duration of the display of the sentence can be controlled by the method setSentenceCharacteristics().

Adding a Sentence Controller to Your Frameset

The page optional/controllers/controllers.html contains a Sentence Controller and other controllers. You can add this page to a frame in you application. Or you can use the class MacaoSentenceController to create your own Sentence Controller.

The class MacaoSentenceController is inherited from the class MacaoMenu. It uses MacaoMenuItem objects to administer and display the commands of the sentence. You need to call the method addSentenceCommand() rather than MacaoMenu.addMenuItem() to add a command, which can be used in a sentence. With the name and the title of the Menu Item, you define the name and the title of the command. With the other parameters of the method, you need to define the conjunction and if the object has to walk to the first object, before it executes the Talk Item. You don't need to define an event when adding a Menu Item, because the controller defines the event of the Menu Item.

The following example adds a sentence controller to a page.

// create controller
var controller = new MacaoSentenceController("SentenceController", 60, 10)

// set the number of columns, hide the images and show the text
controller.setMenuCharacteristics(4, false, true)

// add command items

// look
controller.addSentenceCommand(
	new MacaoMenuItem("Look", "Look"),
	"Look at", null, true
)

// talk
controller.addSentenceCommand(
	new MacaoMenuItem("TalkTo", "Talk"),
	"Talk to", "about", true
)

// use
controller.addSentenceCommand(
	new MacaoMenuItem("Use", "Use"),
	"Use", "with", true
)
	
// consume
controller.addSentenceCommand(
	new MacaoMenuItem("Consume", "Consume"),
	"Consume", null, true
)
	
// open
controller.addSentenceCommand(
	new MacaoMenuItem("Open", "Open"),
	"Open", "using", true
)

// close
controller.addSentenceCommand(
	new MacaoMenuItem("Close", "Close"),
	"Close", "using", true
)
	
// take
controller.addSentenceCommand(
	new MacaoMenuItem("Take", "Take"),
	"Take", null, true
)

// give
controller.addSentenceCommand(
	new MacaoMenuItem("Give", "Give"),
	"Give", "to", true
)

You can look at the page optional/controllers/controllers.html, where a similar code is used to add the Sentence Controller to the controllers' page. The visible texts of the Sentence Controller are got from the text resources. So the controller can be defined in several languages. See also MacaoPage.getResource().

Here are some example sentences, which can be built using the commands in the example sentence controller above:

Look at Chair.
Talk to Barkeeper.
Talk to Barkeeper about Drink.
Use Towel.
Use Knife with Orange.
Consume Bread.
Open Book.
Open Door with Key.
Close Box.
Close Door with Key.
Take Wrench.
Give Money to Cashier.

The first letters of the objects will usually be capitals, because the titles of the objects are used to build the sentence.

The CSS class name of the displayed sentence is MyControllerSentence, where MyController is the name of the controller object.

Use this constructor to create a Sentence Controller on your page.

Parameters

name: Provide a unique name for the sentence controller object. The examples are using the name "SentenceController".
left: Provide the x-coordinate of the left edge of the Sentence Controller in pixels relative to the page.
top: Provide the y-coordinate of the top edge of the Sentence Controller in pixels relative to the page.

Call this method to add a command to the sentence controller.

Parameters

menuItem: Provide a new menu item, which represents the command. The name of the menu item is used as the name of the command. The title of the menu item is used to display the command as menu item.
verb: Provide the text, which is used to build the start of the sentence. For example, the menu item may display the title "Look" while the sentence has to begin with the term "Look at".
conjunction: Provide a conjunction, which will be used in the sentence between the first and second object. For example, in a sentence "Open door with key" "with" is the conjunction. Provide null, if a sentence with this command may only contain one object.
approach: Set this parameter to true, if the controlled object has first to approach the first object of the sentence before it triggers the Talk Item. Set this parameter to false, if the controlled object doesn't have to approach the object first. When the controlled object has the property approach click, the object approaches the object after the talk item is executed. See also MacaoObject.setApprochClick().

Call this method to get the menu item, which is used as the default command.

Returns

Returns the menu item, which is used as the default command. Returns null, if there is no default command defined.

Call this method to set the duration, for which a sentence is displayed, after it has been completed.

Parameters

sentenceDelay: Provide the duration for which a sentence is displayed, after it has been completed, in milliseconds. The default value is 3000.

Call this method to define the command, which is used for a sentence, when the user clicks on an object without clicking on on a command before.

Parameters

menuItemName: Provide the name of the Menu Item, which has to be used as the default command. By default the command, which was added first, is used as the default command.