Drawing Figures - HuTime API Manual

1. Overview

In HuTime, all figures are drawn on the canvas element of a Layer object. This is usually performed roughly in the following steps:

Obtain the context using the getContext method of the canvas element
Draw the path of the figure using the methods (e.g., beginPath, moveTo or lineTo) of the context
Display the figure using the methods (e.g., stroke or fill) of the context

HuTime provides methods to perform all the above steps, 1 through 3, and part of the steps, 1 and 2, with regard to basic figures. These methods belong to the HuTime.Drawing class. Using an action of drawing a circle as an example, steps 1 through 3, in which the figure is displayed, are performed by the HuTime.Drawing.drawCircle method, and steps 1 and 2, in which the path is drawn, are performed by the HuTime.Drawing.pathCircle method.

2. Drawing Figures

The HuTime.Drawing class has methods for displaying a figure on a layer and for drawing a path for each figure. Usually, the method for displaying a figure is used.

Displaying a Figure

HuTime.Drawing.method(style, layer, positioning, size and shape [, rotate [, canvas]])

Here, method is a method name that begins with "draw" and is different for each figure (e.g., drawCircle). The arguments for positioning, size and shape also depend on the figures. For details about these arguments, see the description of each figure. Meanwhile, the other arguments are common to all figures and detailed below:

style: Type: HuTime.FigureStyle; Specifies the format (e.g., the color, the width of the line) of the figure.
layer: Type: HuTime.Layer; The layer on which the figure is drawn.
rotate: Type: Number; The angle of rotation of the figure (in degrees). This argument is optional; 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 lines and circles.
canvas: Type: canvas element; The canvas on which the figure is drawn. This argument is optional; 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.

Drawing a Path

HuTime.Drawing.method(layer, positioning, size and shape [, rotate [, canvas]])

The method for drawing a path only sets a path on canvas, but does not display a figure. It is used when, for example, you want to obtain the region of the figure. Here, method is a method name that begins with "path" and is different for each figure (e.g., pathCircle). Unlike the method for displaying a figure, this method does not take any arguments to specify the format of the figure. The other arguments are the same as the method for displaying a figure.

3. Types of Figures

In HuTime, several types of basic figures support the mechanism for drawing them on layer. For each figure, the following shows the methods for displaying the figure and drawing the path, and details how to specify the position where the figure is drawn and the size and shape of the figure:

Line (Polyline)

HuTime.Drawing.drawLine(style , layer, positions [, canvas])

HuTime.Drawing.pathLine(layer, positions [, canvas])

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.Position array; A collection of positions of nodes for the line.

Polygon

HuTime.Drawing.drawPolygon(style , layer, positions [, canvas])

HuTime.Drawing.pathPolygon(layer, positions [, canvas])

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.Position array; A collection of vertex positions of the polygon.

Square

HuTime.Drawing.drawSquare(style, layer, position, width [, rotate [, canvas]])

HuTime.Drawing.pathSquare(layer, position, width [, rotate [, canvas]])

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.Position; 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.Drawing.drawRect(style, layer, position1, position2 [, rotate [, canvas]])

HuTime.Drawing.pathRect(layer, position1, position2 [, rotate [, canvas]])

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

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

Circle

HuTime.Drawing.drawCircle(style, layer, position, width [, canvas])

HuTime.Drawing.pathCircle(layer, position, width [, canvas])

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.Position; 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.Drawing.drawArc(style, layer, position, radius, startAngle, endAngle [, canvas])

HuTime.Drawing.pathArc(layer, position, radius, startAngle, endAngle [, canvas])

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.Position; 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.Drawing.drawPie(style, layer, position, radius, startAngle, endAngle [, canvas])

HuTime.Drawing.pathPie(layer, position, radius, startAngle, endAngle [, canvas])

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.Position; Type: HuTime.Position
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.Drawing.drawTriangle(style, layer, position, width [, rotate [, canvas]])

HuTime.Drawing.pathTriangle(layer, position, width [, rotate [, canvas]])

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.Position; 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.

Plus Sign

HuTime.Drawing.drawPlusMark(style, layer, position, width [, rotate [, canvas]])

HuTime.Drawing.pathPlusMark(layer, position, width [, rotate [, canvas]])

Specify the center of the symbol as the position using a Position object, and the size as the width (the length of a line segment) in pixels. When the rotation angle (rotate) is set to 45, an X sign is drawn.

position: Type: HuTime.Position; The center position of the symbol.
width: Type: Number; The width of the symbol (in pixels). It corresponds to the length of the line segments that form the symbol.

4. When Figures are Drawn

If a figure is drawn using a method of HuTime.Drawing, it disappears when the layer that it is on is redrawn. Therefore, you need to write your code so that each method of HuTime.Drawing is invoked when the layer is redrawn. In practice, write the code in the HuTime.Layer.processBeforeRedraw method (before the layer is redrawn) or HuTime.Layer.processAfterRedraw method (after the layer is redrawn), both of which have the ability to add operations when the layer is redrawn. When you use the processBeforeRedraw method, the figure is drawn behind records on a timeline layer, plots on a chart layer, on-layer objects, etc. On the contrary, when you use the processAfterRedraw method, the figure is drawn in front of these.

An example of drawing figures (see the sample code below). As the circle is drawn by the processBeforeRedraw method, it is displayed behind the chart. On the other hand, the triangle, drawn by the processAfterRedraw method, is displayed in front of the chart.

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.LineChartLayer(
        new HuTime.CalendarChartRecordset("Weather201507.csv", "Date", "Date", "Temperature"));
    pnl.appendLayer(lyr);

    var posCircle = new HuTime.TVPosition(HuTime.timeToJd(2015, 7, 10), 25);
    var styCircle = new HuTime.FigureStyle("lime");
    lyr.processBeforeRedraw = function (layer) {
        HuTime.Drawing.drawCircle(styCircle, layer, posCircle, 120);
    };
    var posTriangle = new HuTime.TVPosition(HuTime.timeToJd(2015, 7, 25), 30);
    var styTriangle = new HuTime.FigureStyle("aqua");
    lyr.processAfterRedraw = function (layer) {
        HuTime.Drawing.drawTriangle(styTriangle, layer, posTriangle, 120, 30);
    };

    ht.redraw(HuTime.timeToJd(2015, 7, 1), HuTime.timeToJd(2015, 8, 1));
  </script>
</body>
</html>

5. Use of the Path

You can use a path-drawing method that is defined for each figure, for purposes such as determining whether the mouse cursor is located inside a figure. In the sample code below, the color of the figure changes when the mouse cursor goes into the area of it.

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, 0, 0, 100, 0);
  pnl.appendLayer(lyr);

  pos = new HuTime.TVPosition(100, 50);
  styOut = new HuTime.FigureStyle(3, "red", "white");
  styIn = new HuTime.FigureStyle(3, "red", "green");
  lyr.processBeforeRedraw = function processBeforeRedraw(layer) {
    HuTime.Drawing.drawCircle(styOut, layer, pos, 100);
  };

  lyr.mouseEventCapture = HuTime.EventCapture.All;
  lyr.addEventListener("mousemove",
          function(ev) {
            var ctx = HuTime.Drawing.pathCircle(ev.target, pos, 100);
            if (ctx.isPointInPath(ev.offsetX, ev.offsetY))
              HuTime.Drawing.drawCircle(styIn, ev.target, pos, 100);
            else
              HuTime.Drawing.drawCircle(styOut, ev.target, pos, 100);
          }
  );

  ht.redraw(50, 150);
</script>
</body>
</html>

Back to the Contents of this Manual