On-layer Object - HuTime API Manual

1. Overview

Figures, images and strings can be treated as on-layer objects. An on-layer object is created from a class derived from the HuTime.OnLayerObjectBase class. Unlike cases where figures, images and strings are displayed using a method of HuTime.Drawing, an on-layer object behaves as one object and therefore can receive events, etc. The on-layer object is useful for small numbers. However, you should preferably use methods of HuTime.Drawing if you want to use a large number of figures, images and strings, in terms of resource consumption.

Function	On-layer Object	Object Drawn by HuTime.Drawing
Redrawing	Is redrawn by the redraw method on an object basis.	Is redrawn by executing the display method of HuTime.Drawing again. Alternatively, execute the redraw method of the layer.
Redraw timing	Redrawing is specified automatically if it is added to a layer. You can also define processBeforeRedraw or processAfterRedraw for the object.	Is manually specified on processBeforeRedraw or processAfterRedraw of the layer.
Stack order on the screen	Specifies it with the zIndex property.	Specifies it with the order of drawing.
Visible/invisible control	Specifies it with the visible property.	Has no control mechanism by default. You should provide some form of control over the action for displaying the object that is described in processBeforeRedraw or processAfterRedraw of the layer.
Event reception	Can receive events directly. They are incorporated into the entire event flow process.	Cannot receive events directly. They are received by layers and then determined.
Resource consumption	Consumes a certain amount of resources as a single object.	Consumes a few resources.

List of on-layer objects (classes derived from the OnLayerObject class). The OnLayerObjectBase is defined as an abstract class, and is not used in practice.

2. Types of On-layer Objects and Constructors

Unlike when objects are drawn by the HuTime.Drawing method, the constructor is not used to specify the layer or canvas on which the object is drawn. This is performed when the object is added to the layer. The constructor for each object has the following common arguments:

style: Type: FigureStyle object (StringStyle object in HuTime.String); Specifies the format of the figure or string.
rotate: Type: Number; The angle of rotation of the figure (in degrees). This can be optionally specified. If omitted, it is set to 0. The figure is rotated around the center of the figure itself. It cannot be specified for some figures, such as circle objects.

Line (Polyline)

HuTime.Line(style, positions)

Specify the positions of nodes for the line as an array of Position objects. Unlike polygons, this method does not close the path. The rotation angle (rotate) cannot be specified.

positions: Type: HuTime.PositionBase array.; A collection of positions of nodes for the line.

Polygon

HuTime.Polygon(style, positions)

Specify the vertex position of the polygon as an array of Position objects. This method connects the last position with the first position in the array, and closes the path. The rotation angle (rotate) cannot be specified.

positions: Type: HuTime.PositionBase array.; A collection of vertex positions of the polygon.

Square

HuTime.Square(style, position, width [, rotate])

Specify the center of the square as the position using a Position object, and the size as the width (the length of a side) in pixels. When the rotation angle (rotate) is set to 45, a rhombus is drawn.

position: Type: HuTime.PositionBase; The center position of the square.
width: Type: Number; The width of the square (in pixels). It corresponds to the length of the side.

Rectangle

HuTime.Rect(style, position1, position2 [, rotate])

Specify the positions of two diagonal vertices of the rectangle as the position and size using Position objects.

position1: Type: HuTime.PositionBase; The position of one vertex of the rectangle, which is one endpoint of a diagonal joining two opposite vertices.
position2: Type: HuTime.PositionBase; The position of another vertex of the rectangle, which is the other endpoint of the diagonal joining two opposite vertices.

Circle

HuTime.Circle(style, position, width)

Specify the center of the circle as the position using a Position object, and the size as the width (the diameter) in pixels. The rotation angle (rotate) cannot be specified.

position: Type: HuTime.PositionBase; The center position of the circle.
width: Type: Number; The width of the figure (in pixels). It corresponds to the diameter of the circle.

Circular Arc

HuTime.Arc(style, position, radius, startAngle, endAngle)

Specify the center of the circle of which the circular arc is part as the position using a Position object, and the radius of the circle (in pixels) and the angles of the start and end positions (in degrees) as the size and shape. The rotation angle (rotate) cannot be specified.

position: Type: HuTime.PositionBase; The center position of the circle of which the circular arc is part.
radius: Type: Number; The radius of the circle of which the circular arc is part (in pixels).
startAngle: Type: Number; The start angle of the circular arc (in degrees).
endAngle: Type: Number; The end angle of the circular arc (in degrees).

Sector

HuTime.Pie(style, position, radius, startAngle, endAngle)

Specify the center of the circle of which the sector is part as the position using a Position object, and the radius of the circle (in pixels) and the angles of the start and end positions (in degrees) as the size and shape. The rotation angle (rotate) cannot be specified.

position: Type: HuTime.PositionBase; The center position of the circle of which the sector is part.
radius: Type: Number; The radius of the circle of which the sector is part (in pixels).
startAngle: Type: Number; The start angle of the sector (in degrees).
endAngle: Type: Number; The end angle of the sector (in degrees).

Triangle

HuTime.Triangle(style, position, width [, rotate])

Specify the center of the triangle (the center of gravity) as the position using a Position object, and the width (the length of the base) as the size in pixels.

position: Type: HuTime.PositionBase; The position of the center (the center of gravity) of the triangle.
width: Type: Number; The width of the triangle (in pixels). It corresponds to the length of the base.

3. Key Properties and Methods of On-layer Objects

Properties

id: Type: String; Default value: null; The ID for uniquely identifying the object.
name: Type: String; Default value: null; The name of the object.
visible: Type: Boolean; Default value: true; Whether the object is visible or invisible. If true, it is visible.
zIndex: Type: Number; Default value: 0; The stack order of the object. An object with a greater value appears at an upper position.

Methods

redraw()

Redraws the object.

Return value: None

addEventListener(type, handler [, useCapture])

Adds event handling.

Return value: None
type: Type: String; The string that represents the type of the event.
handler: Type: Function (function(ev)); The function to handle the event. The ev argument is an event object (type: HuTime.Event).
useCapture: Type: Boolean; Specify which phase of the event is used. If true, the capture phase is used; if false, the bubbling phase is used. If omitted, it is set to false (the bubbling phase).

dispatchEvent(ev)

Triggers the event from the on-layer object.

Return value: None
ev: Type: HuTime.Event object; The event object for the event to be triggered. ev.target is set to the source on-layer object.

4. Adding an Object to a Layer

You can add an object to a layer by using the appendObject method of the layer. Also, you can remove an object from a layer by using the removeObject method of the layer. One layer can have only one object on it. Thus, when you execute appendObject on the object that has been placed on a different layer, it is removed from the layer to which it already belongs.

layer.appendObject(obj [, canvas])

layer.removeObject(obj)

layer: Type: HuTime.Layer; The layer to which the object is added or from which it is removed.
obj: Type: HuTime.OnLayerObjectBase; The object to be added or removed.
canvas: Type: canvas element; The canvas on which the figure is drawn. This can be optionally specified. If omitted, it is set to layer.canvas. It is used when you want to draw a figure on a Layer object with multiple canvas elements, such as timeline layer or chart layer.

An example of displaying on-layer objects (see the sample code below).

Sample code (click here for a running example):

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <script type="text/javascript" src="http://web.hutime.org/js/HuTime.min.js"></script>
  <title>Sample Code</title>
</head>
<body>
<div id="timeline"></div>
<script type="text/javascript">
    var ht = new HuTime();
    var pnls = new HuTime.PanelCollection(200, 400);
    ht.appendPanelCollection(pnls, document.getElementById("timeline"));
    var pnl = new HuTime.TilePanel(200);
    pnls.appendPanel(pnl);
    var lyr = new HuTime.Layer(200);
    pnl.appendLayer(lyr);

    var objCircle = new HuTime.Circle(
        new HuTime.FigureStyle("blue"),
        new HuTime.TVPosition(100, 50),
        50
    );
    lyr.appendObject(objCircle);

    var objImage = new HuTime.Image(
        new HuTime.FigureStyle(),
        new HuTime.TVPosition(50, 30),
        "http://web.hutime.org/manual/img/ImageSample.jpg",
        100
    );
    lyr.appendObject(objImage);

    var objString = new HuTime.String(
        new HuTime.StringStyle(20, "red"),
        new HuTime.TVPosition(120, 80),
        "Hello World!"
    );
    lyr.appendObject(objString);

    ht.redraw(0, 200);
</script>
</body>
</html>

5. Event Handling of On-layer Objects

You can define an action that receives an event directly and deals with it for an on-layer object. How the event is handled is added by the addEventListener method. In the sample code below, the color of the circle changes when you click the gray rectangle that is displayed as an on-layer object.

Sample code (click here for a running example):

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <script type="text/javascript" src="http://web.hutime.org/js/HuTime.min.js"></script>
  <title>Sample Code</title>
</head>
<body>
<div id="timeline"></div>
<script type="text/javascript">
    var ht = new HuTime();
    var pnls = new HuTime.PanelCollection(200, 400);
    ht.appendPanelCollection(pnls, document.getElementById("timeline"));
    var pnl = new HuTime.TilePanel(200);
    pnls.appendPanel(pnl);
    var lyr = new HuTime.Layer(200);
    pnl.appendLayer(lyr);

    var objCircle = new HuTime.Circle(
        new HuTime.FigureStyle("blue"),
        new HuTime.TVPosition(50, 50),
        100
    );
    lyr.appendObject(objCircle);

    var objButton = new HuTime.Rect(
        new HuTime.FigureStyle("lightgray"),
        new HuTime.TVPosition(100, 40), new HuTime.TVPosition(140, 60)
    );
    lyr.appendObject(objButton);
    objButton.addEventListener("click", function(ev) {
        if (objCircle.style.fillColor == "blue")
            objCircle.style.fillColor = "red";
        else
            objCircle.style.fillColor = "blue";
        objCircle.redraw();
    });

    ht.redraw(0, 200);
</script>
</body>
</html>

Back to the Contents of this Manual