Graphics class

The Graphics class allows you to draw graphics in PRIMER. More...

The PRIMER JavaScript API provides many class constants, properties and methods. For Arup to be able to extend and enhance the API in the future any constant, property or method names beginning with a lowercase or uppercase letter are reserved.
If you need to add your own properties or methods to one of the existing classes then to avoid any potential future conflict you should ensure that the name begins with either an underscore (_) or a dollar sign ($) or the name is prefixed with your own unique identifier.
For example if company 'ABC' need to add a property called 'example' then to avoid any potential future conflict use one of:

Class functions

Graphics constants

Name Description
Graphics.CIRCLE Circle shape. See Graphics.Shape() for use.
Graphics.DASHDOT_LINE Dashed and dotted lines. See Graphics.LineStyle() for use.
Graphics.DASH_LINE Dashed lines. See Graphics.LineStyle() for use.
Graphics.DIAMOND Diamond shape. See Graphics.Shape() for use.
Graphics.DOT_LINE Dotted lines. See Graphics.LineStyle() for use.
Graphics.FILLED_CIRCLE Filled circle shape. See Graphics.Shape() for use.
Graphics.FILLED_DIAMOND Filled diamond shape. See Graphics.Shape() for use.
Graphics.FILLED_HOURGLASS Filled hourglass shape. See Graphics.Shape() for use.
Graphics.FILLED_SQUARE Filled square shape. See Graphics.Shape() for use.
Graphics.HOURGLASS Hourglass shape. See Graphics.Shape() for use.
Graphics.POINT Point shape. See Graphics.Shape() for use.
Graphics.SOLID_LINE Solid lines. See Graphics.LineStyle() for use.
Graphics.SQUARE Square shape. See Graphics.Shape() for use.

Detailed Description

The Graphics class gives you access to functions to draw lines, shapes etc on the graphics screen in PRIMER. For example the following will draw a solid thick red line on the screen: 

Graphics.Start();
Graphics.LineWidth(3);
Graphics.LineColour(Colour.RED);
Graphics.LineStyle(Graphics.SOLID_LINE);
Graphics.Line(0, 0, 0, 10, 20, 30);
Graphics.Finish();

The drawing commands must be between 

Graphics.Start()

and 

Graphics.Finish()

or else nothing will be seen. This is suitable for sketching but the line will disappear if the graphics are redrawn or any dynamic viewing is done. To draw graphics which will stay on the screen even if dynamic viewing or a redraw is done you have to register a function using Graphics.DrawingFunction() which will be called every time the graphics are redrawn by PRIMER. e.g: 

var w = new Window("Graphics test", 0.8, 1.0, 0.5, 0.6);

var e = new Widget(w, Widget.BUTTON,  1, 21, 1, 7, "Exit");
e.onClick  = Exit;

do_draw();
Graphics.DrawingFunction(do_draw);

w.Show();

////////////////////////////////////////////////////////////////////////////////

function do_draw()
{
    Graphics.Start();
    Graphics.LineWidth(3);
    Graphics.LineColour(Colour.RED);
    Graphics.LineStyle(Graphics.SOLID_LINE);
    Graphics.Line(0, 0, 0, 10, 20, 30);
    Graphics.Finish();
}

See the documentation below for more details.

Details of functions

DepthTest(enable[boolean]) [static]

Description

Allows depth testing (hidden surface removal) to be turned on or off. Temporarily turning depth testing off may be used to ensure that an item (e.g. some text) is always drawn in front and will not be obscured.

Arguments

  • enable (boolean)

    Whether depth testing (hidden surface removal) is performed (true) or not (false)

    Returns

    No return value

    Example

    To turn off depth testing: 

    Graphics.DepthTest(false);

    To turn depth testing back on: 

    Graphics.DepthTest(true);

    DrawingFunction(name[function]) [static]

    Description

    Set the function to draw graphics from javaScript. This function will be called each time the graphics are redrawn after PRIMER has finished drawing everything else. This allows you to add extra items to the graphics.
    To remove the graphics drawing function use Graphics.DrawingFunction(null).
    It is the responsibility of the script developer to ensure that any objects or variables that are used in the drawing function do not refer to items in PRIMER that no longer exist. Not doing so may cause PRIMER to crash. For example, if you use some Node objects in the drawing function that refer to nodes in model 1 and you delete the model, when the graphics are redrawn PRIMER may crash as the nodes referred to by the Node objects no longer exist. You should either remove the drawing function by calling Graphics.DrawingFunction(null) or set the Node variables to null (and test that they exist before using them) in your drawing function before deleting the model.
    If a drawing function is used in your script, you should reset it before the script terminates to avoid a "race condition" between the script terminating and the graphics function being called. Not doing so may cause PRIMER to crash.

    Arguments

  • name (function)

    The name of the function (or null to remove a function)

    Returns

    No return value

    Example

    To set function MyRedrawFunction as the Graphics drawing function 

    Graphics.DrawingFunction(MyRedrawFunction);

    FillColour(colour[Colour]) [static]

    Description

    Sets the colour for drawing polygons. See the Colour class for more details on colours.

    Arguments

  • colour (Colour)

    The colour you want to fill polygons with

    Returns

    No return value

    Example

    To Set the current fill colour to red: 

    Graphics.FillColour(Colour.RED);

    or 

    Graphics.FillColour( Colour.RGB(255, 0, 0) );

    Finish() [static]

    Description

    Finish any graphics. See also Graphics.Start(). This must be used to finish drawing.

    Arguments

    No arguments

    Returns

    No return value

    Example

    To finish any graphics operations: 

    Graphics.Finish();

    Line(x1[real], y1[real], z1[real], x2[real], y2[real], z2[real]) [static]

    Description

    Draws a line from (x1, y1, z1) to (x2, y2, z2). See also Graphics.LineTo() and Graphics.MoveTo()

    Arguments

  • x1 (real)

    X coordinate of point 1

  • y1 (real)

    Y coordinate of point 1

  • z1 (real)

    Z coordinate of point 1

  • x2 (real)

    X coordinate of point 2

  • y2 (real)

    Y coordinate of point 2

  • z2 (real)

    Z coordinate of point 2

    Returns

    No return value

    Example

    To draw a line from (0.0, 0.0, 0.0) to (10.0, 20.0, 30.0) 

    Graphics.Line(0.0, 0.0, 0.0, 10.0, 20.0, 30.0);

    LineColour(colour[Colour]) [static]

    Description

    Sets the colour for drawing lines. See the Colour class for more details on colours.

    Arguments

  • colour (Colour)

    The colour you want to draw lines with

    Returns

    No return value

    Example

    To Set the current drawing colour to red: 

    Graphics.LineColour(Colour.RED);

    or 

    Graphics.LineColour( Colour.RGB(255, 0, 0) );

    LineStyle(style[constant]) [static]

    Description

    Sets the style for drawing lines.

    Arguments

  • style (constant)

    The style to draw lines with. Can be: Graphics.SOLID_LINE, Graphics.DASH_LINE, Graphics.DASHDOT_LINE or Graphics.DOT_LINE

    Returns

    No return value

    Example

    To Set the current line style to 3: 

    Graphics.LineStyle(3);

    LineTo(x[real], y[real], z[real]) [static]

    Description

    Draws a line from the current point to (x, y, z). After drawing the line the current point will be (x, y, z). See also Graphics.Line() and Graphics.MoveTo()

    Arguments

  • x (real)

    X coordinate

  • y (real)

    Y coordinate

  • z (real)

    Z coordinate

    Returns

    No return value

    Example

    To draw a line from the current point to (10.0, 20.0, 30.0): 

    Graphics.LineTo(10.0, 20.0, 30.0);

    LineWidth(width[Integer]) [static]

    Description

    Sets the width for drawing lines.

    Arguments

  • width (Integer)

    The width to draw lines with

    Returns

    No return value

    Example

    To Set the current line width to 3: 

    Graphics.LineWidth(3);

    MoveTo(x[real], y[real], z[real]) [static]

    Description

    Sets the current point to (x, y, z). See also Graphics.Line() and Graphics.LineTo()

    Arguments

  • x (real)

    X coordinate

  • y (real)

    Y coordinate

  • z (real)

    Z coordinate

    Returns

    No return value

    Example

    To set the current point to (10.0, 20.0, 30.0): 

    Graphics.MoveTo(10.0, 20.0, 30.0);

    PolygonFinish() [static]

    Description

    Ends drawing a polygon. See also Graphics.PolygonStart()

    Arguments

    No arguments

    Returns

    No return value

    Example

    To draw a red square: 

    Graphics.FillColour(Colour.RED);
Graphics.MoveTo(0.0, 0.0, 0.0);
Graphics.PolygonStart();
Graphics.MoveTo(10.0, 0.0, 0.0);
Graphics.MoveTo(10.0, 10.0, 0.0);
Graphics.MoveTo(0.0, 10.0, 0.0);
Graphics.PolygonFinish();

    PolygonStart() [static]

    Description

    Starts drawing a convexpolygon. A maximum of 250 vertices are allowed. Drawing concave polygons is not supported by this function. To draw concave polygons split them into separate convex polygons.
    See also Graphics.PolygonFinish().
    The only graphics command allowed between Graphics.PolygonStart() and Graphics.PolygonFinish() is Graphics.MoveTo(). Any other graphics drawing commands (e.g. Graphics.Text()) will be ignored.

    Arguments

    No arguments

    Returns

    No return value

    Example

    To draw a red square: 

    Graphics.FillColour(Colour.RED);
Graphics.MoveTo(0.0, 0.0, 0.0);
Graphics.PolygonStart();
Graphics.MoveTo(10.0, 0.0, 0.0);
Graphics.MoveTo(10.0, 10.0, 0.0);
Graphics.MoveTo(0.0, 10.0, 0.0);
Graphics.PolygonFinish();

    Shape(shape[constant], size[integer]) [static]

    Description

    Draws a simple shape.

    Arguments

  • shape (constant)

    The style to draw lines with. Can be: Graphics.POINT, Graphics.SQUARE, Graphics.CIRCLE, Graphics.DIAMOND, Graphics.HOURGLASS, Graphics.FILLED_SQUARE, Graphics.FILLED_CIRCLE, Graphics.FILLED_DIAMOND or Graphics.FILLED_HOURGLASS

  • size (integer)

    Size the shape should be drawn at.

    Returns

    No return value

    Example

    To draw a filled square at (10, 20, 30) at size 10: 

    Graphics.MoveTo(10, 20, 30);
Graphics.Shape(Graphics.FILLED_SQUARE, 10);

    Start() [static]

    Description

    Start any graphics. See also Graphics.Finish(). This must be used before any drawing is done.

    Arguments

    No arguments

    Returns

    No return value

    Example

    To start drawing graphics: 

    Graphics.Start();

    Text(text[String]) [static]

    Description

    Draws text at current position. See Graphics.MoveTo() to set the current position.

    Arguments

  • text (String)

    The text to write

    Returns

    No return value

    Example

    To write "Example" at (10, 20, 30): 

    Graphics.MoveTo(10, 20, 30);
Graphics.Text("Example");

    TextColour(colour[Colour]) [static]

    Description

    Sets the colour for drawing text. See the Colour class for more details on colours.

    Arguments

  • colour (Colour)

    The colour you want to draw text with

    Returns

    No return value

    Example

    To Set the current text drawing colour to red: 

    Graphics.TextColour(Colour.RED);

    or 

    Graphics.TextColour( Colour.RGB(255, 0, 0) );

    TextSize(size[Integer]) [static]

    Description

    Sets the size for drawing text.

    Arguments

  • size (Integer)

    The size to draw text with

    Returns

    No return value

    Example

    To Set the current text size to 30: 

    Graphics.TextSize(30);