Package road

Class MacaoRoadGrid

Inherited from MacaoObject

     Adding a Road to a Page
     Using the Road Editor
          Opening the Road Editor
          Adding a Road Element
          Avoid Dead Ends
          Naming a Road Element
          Removing a Road Element
          Exporting and Pasting the Road Definition

Constructor   Methods

Add a road to your page, to create a net, which can be used by cars, other vehicles and characters. The road creates the nodes and connections of a MacaoNet. You may also create a MacaoRoadGrid, which displays the images of the road.

The following paragraphs explain, how to add a road to a page and how to use the Road Editor to add road elements to your road. See the class description of MacaoRoad on how to implement your own road elements.

Adding a Road to a Page

To add a road to a page you need to include the packages core/kernel.js, core/dynamic.js and core/road.js into the page. You also need to include a package, which defines the road types. Macao comes with the package optional/road/roadTypes.js, which defines a number of standard road types. See below on how to define your own road types.

To create the road, you first need to call the method MacaoPage.setRoadMetrics() to define the position of the road grid and the size of the road cells. By defining the size of the road cells you can zoom the display of the road.

Then you need to add road elements to the road. The elements are added using the method MacaoPage.createRoad(). When calling this method, you provide the type of the element, its position in grid units, its orientation and optionally its name. Because it's toilsome to create all the method calls by hand, you can use the Road Editor (see below). Use the Road Editor to add the road elements with the mouse. Because the Road Editor is web based, it can't write its result direct into your source file. So you need to export the result of your design work with the Export function of the Road Editor. Then you need to paste it via the clipboard into the code of your page. Because we want to use the Road Editor, initially we are adding only one road element to our new road. Replace this later by the export of the Road Editor.

After all road elements have been added you have to link them by calling the method MacaoPage.linkRoads(). When you add a road element, it creates its nodes and internal connections. Linking the roads connects adjusting road elements, so a car can 'walk' from one road element to another.

At last you need to create the MacaoRoadGrid. The road grid is a MacaoObject, which makes the road visible by displaying the graphics of the road elements in an HTML table. The position of the road grid is already defined by the call of the method setRoadMethrics(). You may only add one road grid per page. This will display all road elements. The road grid object has the name RoadGrid. You can use that name to send events to the grid.

The following example creates a page with a road, which has a single road element. Use the road editor, to add more road elements.

<head>
<meta http-equiv="expires" content="10000">
<script>
var basePath = "../../"
</script>
<link rel=stylesheet type="text/css" href="../../core/macao.css">
</head>
<body background="../../optional/landscape/background/grasTile.gif">

<!-- add the required packages -->
<script language="JavaScript" src="../../core/storageManager.js" type="text/javascript">
</script>
<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>
<script language="JavaScript" src="../../optional/road/roadTypes.js" type="text/javascript">
</script>
<script language="JavaScript">

// set the road metrics
setRoadMetrics(20, 200, 26)
	
// add a single road element
// replace the following line by the Road Editor export
createRoad("RoadDJunc", 5, 1, 0,  null)

// link road elements together
linkRoads()

// create a road grid to make the road visible
var roadGrid = new MacaoRoadGrid(50, 40)

</script>
</body>

You can find the source code in the file examples/road/simpleRoad.html. Because the example works without a frameset, the package core/storageManager.js is inserted into the page. Remove this package, when you use the code for a page in a frameset.

Now lets add a car, which can use the road.

// build the car
var car = new MacaoObject("Car", "Car", 400, 250)
car.addLookBunch(
	car.BUNCH_TYPE_STAND,
	"optional/cars/red/carRed", 3, ".gif", 20, 20
)

// bind the car to the road
car.bindToNet("Road")

// make the car walk to the mouse click
car.setApproachClick(true)

Note: All road elements of the package optional/road/roadTypes.js are adding its nodes to the net with the netType 'Road'. So the car has to be bound to this net in order to use the road. Further extensions may add nodes to nets with other names like 'Rail' to create more than one net on the same page for different types of vehicles.

Now click on the page to start the car and hit the key 'e' to open the Road Editor.

Using the Road Editor

Opening the Road Editor

Once you have added the road grid to your page you can open the Road Editor by keyboard. Click on the page and hit 'e'. This will open the Road Editor Window, if the design mode is active. By default the design mode is active. Resize the page window and place the Road Editor window beside it.

Note: Because the Road Editor is opened as an extra window, a popup-blocker may prevent the opening of the window. If the Road Editor doesn't open, please disable your popup blocker.

Note: You can open the Road Editor by calling the method MacaoRoadGrid.openEditor().

Note: You can use the method MacaoPage.setDesignModeSM() to deactivate the design mode and make the Road Editor unavailable to the user.

Adding a Road Element

First you should activate the checkbox Show grid to show the borders of the grid cells. The grid is optimized so that it works with a minimum number of cells.

Note: The borders of the grid cells are displayed in white color. Change the background of your page to another color or use an image, to make the cell borders visible.

Note: The display of the grid uses a little space between the grid cells. So the positions of the road elements will differ a little from the display without grid lines. Hide the grid to check the right position.

Select the editor mode Add by the radio button. Select a road type, which you want to add, by clicking on an image in the list of road types. The selected road type will appear in the frame below the controls of the Road Editor. Click on the displayed road element to rotate the element. Click to the grid position, where the upper left cell of the new road element has to appear, to add the new element.

If there are other road elements where you tried to place the new element, you will get the error message: There is not enough space for this element. Delete the other elements or place the new element in another position.

Note: The Road Editor only changes the road elements, which are displayed by the Road Editor. But it doesn't re-link the net. So the vehicles can't use the new roads until you export them and paste them to the source code of your page. You must export the changes and paste them to your page, in order not to loose them.

Note: You should not use the first row and the first column in the Road Grid to place road elements at. The HTML-table may be confused by the colspan or rowspan of these cells, when calculating the cell sizes.

Avoid Dead Ends

Connections in a MacaoNet are directed. That means, if a node A is connected to B but B is not connected to A, a vehicle can "walk" from A to B but not back. The road elements in the package optional/road/roadTypes.js are designed for right-hand traffic. On a two- or four-lane road element, the lanes are not connected to each other. But at the junctions there are short cuts, so the vehicles can turn around. There is a conclusion element for two lane roads, which you can use to conclude a road. The one lane road elements are so designed, that they use the same nodes for both directions. So a vehicle can turn around at each node. When you are not sure, if your road map has no dead ends, bind an object to the road and call it's method MacaoObject.wanderAround() to let it check out your road map. Let it walk around a while to see, if it hangs.

Naming a Road Element

To edit the name of a road element select the mode Edit by the radio button. Click on the road element, which name you want to change. An input dialog will be opened. If there has not been a name specified for this element, the standard name is displayed. The standard name is assigned to the road element automatically. Enter your specific name and hit OK.

It is useful to name road elements, which nodes properties you want to change. So you can reach the road element and its nodes in your program without changing the code, which is generated by the Road Editor. For example you may want to assign an element to a node, change the zoom factor of the node or name the node. You can get a named road element by the method MacaoPage.getRoadByName(). Use the method MacaoRoad.getNodeByIndex() to access a node of the road element.

Removing a Road Element

To remove a road element select the mode Remove by the radio button. Click on the road element in your page to remove it.

Exporting and Pasting the Road Definition

To get the changes of the Road Grid permanently to your page you need to export them from the Road Editor and paste them to the source code of your page. Click Export to display a textbox with the generated source code of the road definition. Select all the text in the text box. Copy the text to the clipboard. Open the source code of your page in an editor. Replace the road definition of your page with the definition in the clipboard. Save the source code and reload the page in the browser. You need to reopen the Road Editor to use it with the reloaded page.

Constructor Summary
MacaoRoadGrid(integer gridWidth, integer gridHeight)
     Use this constructor to create a road grid, which displays the road on your page.

Method Summary
MacaoRoad addRoad(String RoadType, integer gridX, integer gridY, integer ordination, optional String name)
     Call this method to add a road element to the page.
void closeEditor()
     Call this method to close the Road Editor window.
Array getAvailableRoadTypes()
     Call this method to get an array with all defined road types.
integer getCellSize()
     Call this method to get the size of the grid cells.
Window getEditorWindow()
     Call this method to get the window object of the opened Road Editor.
MacaoRoad getRoadAt(integer gridX, integer gridY)
     Call this method to get the road element at a specified position.
boolean isFreeBlock(integer gridLeft, integer gridTop, integer width, integer height)
     Call this method to check, if a block of cells in the road grid if free from road elements.
void onKeyPress(Event event, integer keyCode, boolean shiftKey, boolean altKey, boolean ctrlKey)
     This method is implemented to get the hit of the key 'e' to open the Road Editor.
void openEditor()
     Call this method to open the Road Editor.
void refreshHTML()
     Call this method to refresh the display of the road grid.
void removeRoad(MacaoRoad road)
     Call this method to remove a road element from the page.
void showGrid(boolean showGrid)
     Call this method to show or hide the cell borders of the grid cells.

Inherited Methods
activateDrag, activateDrop, addController, broadcastEvent, createLayer, createLook, displayMeasures, getActualLook, getCollisionCheck, getCssClassName, getFrameName, getHeight, getLayer, getLeft, getLook, getName, getTitle, getTop, getType, getVisibility, getWidth, getZIndex, getZoom, hasLook, initObject, isController, isDragActive, isDragged, isDropActive, isDropAllowed, moveTo, moveToCenter, notifyControllers, onClick, onClickOther, onClickOtherItem, onClickWindow, onCollisionOut, onCollisionOver, onDblClick, onDblClickOther, onDblClickWindow, onDragEnd, onDragOut, onDragOver, onDragStart, onDrop, onKeyDown, onKeyPress, onKeyUp, onLoad, onMouseDown, onMouseDownWindow, onMouseMove, onMouseOut, onMouseOver, onMouseUp, onMouseUpWindow, onUnload, openPage, postEvent, refreshZoom, removeController, removeObject, say, scrollVisible, sendEvent, setActualLook, setBaseSize, setCollisionCheck, setCssClassName, setForwardMouseEvents, setHTML, setImage, setScrollVisibleOptions, setTitle, setToolTip, setType, setVisibility, setZIndex, setZoom, toBack, toFront

Constructor Details
MacaoRoadGrid(integer gridWidth, integer gridHeight)

Method Details
MacaoRoad addRoad(String RoadType, integer gridX, integer gridY, integer ordination, optional String name)

void closeEditor()

Array getAvailableRoadTypes()

integer getCellSize()

Window getEditorWindow()

MacaoRoad getRoadAt(integer gridX, integer gridY)

boolean isFreeBlock(integer gridLeft, integer gridTop, integer width, integer height)

void onKeyPress(Event event, integer keyCode, boolean shiftKey, boolean altKey, boolean ctrlKey)

void openEditor()

void refreshHTML()

void removeRoad(MacaoRoad road)

void showGrid(boolean showGrid)