Comment class

The Comment class gives you access to comment cards 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:

_example
$example
ABC_example

Class functions

Create(Model[Model], modal (optional)[boolean])
First(Model[Model])
FlagAll(Model[Model], flag[Flag])
ForEach(Model[Model], func[function], extra (optional)[any])
GetAll(Model[Model], property (optional)[string])
GetFlagged(Model[Model], flag[Flag], property (optional)[string])
GetFromID(Model[Model], number[integer])
Last(Model[Model])
Select(flag[Flag], prompt[string], limit (optional)[Model or Flag], modal (optional)[boolean])
Total(Model[Model], exists (optional)[boolean])
UnflagAll(Model[Model], flag[Flag])

Member functions

AddLine(Line content[String or array of strings], Line number (optional)[Integer])
Browse(modal (optional)[boolean])
ClearFlag(flag[Flag])
Copy(range (optional)[boolean])
DeleteLine(Line number[Integer])
Edit(modal (optional)[boolean])
Error(message[string], details (optional)[string])
Flagged(flag[Flag])
GetLine(Line (optional)[integer])
GetParameter(prop[string])
Keyword()
KeywordCards()
ModifyLine(Line number[Integer], New line content[String])
Next()
Previous()
SetFlag(flag[Flag])
ViewParameters()
Warning(message[string], details (optional)[string])
Xrefs()
toString()

Comment constants

Constants for Comment anchor_mode types

Name	Description
Comment.MULTIPLE	The *COMMENT is associated with all cards in the next block of keywords.
Comment.SINGLE	The *COMMENT is associated with just the one immediately following keyword.

Comment properties

Name	Type	Description
anchor_mode	integer	Anchor mode. Can be Comment.SINGLE, Comment.MULTIPLE.
exists (read only)	logical	true if comment exists, false if referred to but not defined.
header	string	The header of the comment, or empty if the comment has no header.
include	integer	The Include file number that the comment is in.
model (read only)	integer	The Model number that the comment is in.
nlines	integer	Number of lines in the comment.
noecho	logical	true if _NOECHO option is set, false if not.

Detailed Description

The Comment class allows you to create, modify, edit and manipulate comment cards. See the documentation below for more details.

Constructor

new Comment(Model[Model], Header (optional)[string], Mode (optional)[constant])

Description

Create a new Comment object.

Arguments

Model (Model)

Model that comment will be created in

Header (optional) (string)

Comment number

Mode (optional) (constant)

Anchor: single or multiple

Returns

Comment object

Return type

Comment

Example

To create a new comment in model m with header "My header", and multiple anchor:

var c = new Comment(m, "My header", Comment.MULTIPLE);

To create a new comment in model m without header, and single anchor:

var c = new Comment(m);

Details of functions

AddLine(Line content[String or array of strings], Line number (optional)[Integer])

Description

Adds a line, or an array of lines, to a comment object.

Arguments

Line content (String or array of strings)

String that will be added to a line

Line number (optional) (Integer)

0: First line, 1: Second line, etc.

If array of lines has been passed in the first argument, the first line of the array will be inserted in the line number specified in second argument, the second line of the array will be inserted in the following line number, etc.

If that line already exists, that line and rest of them below will be shifted down.

If greater than number of existing lines, blank lines will be added.

If lower than 0, not valid argument.

If no argument, the line(s) will be appended at the end.

Returns

no return value

Example

To add a new line in the second row of comment c:

var str = c.AddLine("New line", 1);

Browse(modal (optional)[boolean])

Description

Starts an edit panel in Browse mode.

Arguments

modal (optional) (boolean)

If this window is modal (blocks the user from doing anything else in PRIMER until this window is dismissed). If omitted the window will be modal.

Returns

no return value

Example

To Browse comment c:

c.Browse();

ClearFlag(flag[Flag])

Description

Clears a flag on the comment.

Arguments

flag (Flag)

Flag to clear on the comment

Returns

No return value

Example

To clear flag f for comment c:

c.ClearFlag(f);

Copy(range (optional)[boolean])

Description

Copies the comment. The target include of the copied comment can be set using Options.copy_target_include.

Arguments

range (optional) (boolean)

If you want to keep the copied item in the range specified for the current include. Default value is false. To set current include, use Include.MakeCurrentLayer().

Returns

Comment object

Return type

Comment

Example

To copy comment c into comment z:

var z = c.Copy();

Create(Model[Model], modal (optional)[boolean]) [static]

Description

Starts an interactive editing panel to create a comment

Arguments

Model (Model)

Model that the comment will be created in.

modal (optional) (boolean)

If this window is modal (blocks the user from doing anything else in PRIMER until this window is dismissed). If omitted the window will be modal.

Returns

Comment object (or null if not made).

Return type

Comment

Example

To start creating a comment in model m:

var c = Comment.Create(m);

DeleteLine(Line number[Integer])

Description

Deletes a line of a comment.

Arguments

Line number (Integer)

Line number to delete (starting at 0). The following lines will be shifted up.

Returns

no return value

Example

To delete the line in the second row of comment c:

var str = c.DeleteLine(1);

Edit(modal (optional)[boolean])

Description

Starts an interactive editing panel.

Arguments

modal (optional) (boolean)

If this window is modal (blocks the user from doing anything else in PRIMER until this window is dismissed). If omitted the window will be modal.

Returns

no return value

Example

To Edit comment c:

c.Edit();

Error(message[string], details (optional)[string])

Description

Adds an error for comment. For more details on checking see the Check class.

Arguments

message (string)

The error message to give

details (optional) (string)

An optional detailed error message

Returns

No return value

Example

To add an error message "My custom error" for comment c:

c.Error("My custom error");

First(Model[Model]) [static]

Description

Returns the first comment in the model.

Arguments

Model (Model)

Model to get first comment in

Returns

Comment object (or null if there are no comments in the model).

Return type

Comment

Example

To get the first comment in model m:

var c = Comment.First(m);

FlagAll(Model[Model], flag[Flag]) [static]

Description

Flags all of the comments in the model with a defined flag.

Arguments

Model (Model)

Model that all comments will be flagged in

flag (Flag)

Flag to set on the comments

Returns

No return value

Example

To flag all of the comments with flag f in model m:

Comment.FlagAll(m, f);

Flagged(flag[Flag])

Description

Checks if the comment is flagged or not.

Arguments

flag (Flag)

Flag to test on the comment

Returns

true if flagged, false if not.

Return type

Boolean

Example

To check if comment c has flag f set on it:

if (c.Flagged(f) ) do_something...

ForEach(Model[Model], func[function], extra (optional)[any]) [static]

Description

Calls a function for each comment in the model.
Note that ForEach has been designed to make looping over comments as fast as possible and so has some limitations.
Firstly, a single temporary Comment object is created and on each function call it is updated with the current comment data. This means that you should not try to store the Comment object for later use (e.g. in an array) as it is temporary.
Secondly, you cannot create new comments inside a ForEach loop.

Arguments

Model (Model)

Model that all comments are in

func (function)

Function to call for each comment

extra (optional) (any)

An optional extra object/array/string etc that will appended to arguments when calling the function

Returns

No return value

Example

To call function test for all of the comments in model m:

Comment.ForEach(m, test);
function test(c)
{
// c is Comment object
}

To call function test for all of the comments in model m with optional object:

var data = { x:0, y:0 };
Comment.ForEach(m, test, data);
function test(c, extra)
{
// c is Comment object
// extra is data
}

GetAll(Model[Model], property (optional)[string]) [static]

Description

Returns an array of Comment objects or properties for all of the comments in a model in PRIMER. If the optional property argument is not given then an array of Comment objects is returned. If the property argument is given, that property value for each comment is returned in the array instead of a Comment object

Arguments

Model (Model)

Model to get comments from

property (optional) (string)

Name for property to get for all comments in the model

Returns

Array of Comment objects or properties

Return type

Array

Example

To make an array of Comment objects for all of the comments in model m:

var a = Comment.GetAll(m);

To return an array containing the value of property 'foo' (for example 'x' for a node) for each comment in model m:

var a = Comment.GetAll(m, 'foo');

GetFlagged(Model[Model], flag[Flag], property (optional)[string]) [static]

Description

Returns an array of Comment objects for all of the flagged comments in a model in PRIMER If the optional property argument is not given then an array of Comment objects is returned. If the property argument is given, then that property value for each comment is returned in the array instead of a Comment object

Arguments

Model (Model)

Model to get comments from

flag (Flag)

Flag set on the comments that you want to retrieve

property (optional) (string)

Name for property to get for all flagged comments in the model

Returns

Array of Comment objects or properties

Return type

Array

Example

To make an array of Comment objects for all of the comments in model m flagged with f:

var c = Comment.GetFlagged(m, f);

To return an array containing the value of property 'foo' (for example 'x' for a node) for all of the comments in model m flagged with f:

var a = Comment.GetFlagged(m, f, 'foo');

GetFromID(Model[Model], number[integer]) [static]

Description

Returns the Comment object for a comment ID.

Arguments

Model (Model)

Model to find the comment in

number (integer)

number of the comment you want the Comment object for

Returns

Comment object (or null if comment does not exist).

Return type

Comment

Example

To get the Comment object for comment 100 in model m

var c = Comment.GetFromID(m, 100);

GetLine(Line (optional)[integer])

Description

Extracts the lines (the strings) from a comment object.

Arguments

Line (optional) (integer)

Line number to be extracted. Default value: 0 (first line)

Returns

String (or null if no lines in the comment and not argument passed)

Return type

String

Example

To extract the first line of comment c:

var str = c.GetLine();

GetParameter(prop[string])

Description

Checks if a Comment property is a parameter or not. Note that object properties that are parameters are normally returned as the integer or float parameter values as that is virtually always what the user would want. For this function to work the JavaScript interpreter must use the parameter name instead of the value. This can be done by setting the Options.property_parameter_names option to true before calling the function and then resetting it to false afterwards.. This behaviour can also temporarily be switched by using the Comment.ViewParameters() method and 'method chaining' (see the examples below).

Arguments

prop (string)

comment property to get parameter for

Returns

Parameter object if property is a parameter, null if not.

Return type

Parameter

Example

To check if Comment property c.example is a parameter:

Options.property_parameter_names = true;
if (c.GetParameter(c.example) ) do_something...
Options.property_parameter_names = false;

To check if Comment property c.example is a parameter by using the GetParameter method:

if (c.ViewParameters().GetParameter(c.example) ) do_something...

Keyword()

Description

Returns the keyword for this comment (*COMMENT) and the header of the comment if there is one. Note that a carriage return is not added. See also Comment.KeywordCards()

Arguments

No arguments

Returns

string containing the keyword.

Return type

String

Example

To get the keyword for comment c:

var key = c.Keyword();

KeywordCards()

Description

Returns the keyword cards for the comment. Note that a carriage return is not added. See also Comment.Keyword()

Arguments

No arguments

Returns

string containing the cards.

Return type

String

Example

To get the cards for comment c:

var cards = c.KeywordCards();

Last(Model[Model]) [static]

Description

Returns the last comment in the model.

Arguments

Model (Model)

Model to get last comment in

Returns

Comment object (or null if there are no comments in the model).

Return type

Comment

Example

To get the last comment in model m:

var c = Comment.Last(m);

ModifyLine(Line number[Integer], New line content[String])

Description

Modifies the content of a line in a comment.

Arguments

Line number (Integer)

Line number to modify (starting at 0)

New line content (String)

String that replaces the existing one in a line

Returns

no return value

Example

To modify the line in the second row of comment c:

var str = c.ModifyLine(1, "Modified line");

Next()

Description

Returns the next comment in the model.

Arguments

No arguments

Returns

Comment object (or null if there are no more comments in the model).

Return type

Comment

Example

To get the comment in model m after comment c:

var c = c.Next();

Previous()

Description

Returns the previous comment in the model.

Arguments

No arguments

Returns

Comment object (or null if there are no more comments in the model).

Return type

Comment

Example

To get the comment in model m before comment c:

var c = c.Previous();

Select(flag[Flag], prompt[string], limit (optional)[Model or Flag], modal (optional)[boolean]) [static]

Description

Allows the user to select comments using standard PRIMER object menus.

Arguments

flag (Flag)

Flag to use when selecting comments

prompt (string)

Text to display as a prompt to the user

limit (optional) (Model or Flag)

If the argument is a Model then only comments from that model can be selected. If the argument is a Flag then only comments that are flagged with limit can be selected (limit should be different to flag). If omitted, or null, any comments can be selected. from any model.

modal (optional) (boolean)

If selection is modal (blocks the user from doing anything else in PRIMER until this window is dismissed). If omitted the selection will be modal.

Returns

Number of comments selected or null if menu cancelled

Return type

Number

Example

To select comments from model m, flagging those selected with flag f, giving the prompt 'Select comments':

Comment.Select(f, 'Select comments', m);

To select comments, flagging those selected with flag f but limiting selection to comments flagged with flag l, giving the prompt 'Select comments':

Comment.Select(f, 'Select comments', l);

SetFlag(flag[Flag])

Description

Sets a flag on the comment.

Arguments

flag (Flag)

Flag to set on the comment

Returns

No return value

Example

To set flag f for comment c:

c.SetFlag(f);

Total(Model[Model], exists (optional)[boolean]) [static]

Description

Returns the total number of comments in the model.

Arguments

Model (Model)

Model to get total for

exists (optional) (boolean)

true if only existing comments should be counted. If false or omitted referenced but undefined comments will also be included in the total.

Returns

number of comments

Return type

Number

Example

To get the total number of comments in model m:

var total = Comment.Total(m);

UnflagAll(Model[Model], flag[Flag]) [static]

Description

Unsets a defined flag on all of the comments in the model.

Arguments

Model (Model)

Model that the defined flag for all comments will be unset in

flag (Flag)

Flag to unset on the comments

Returns

No return value

Example

To unset the flag f on all the comments in model m:

Comment.UnflagAll(m, f);

ViewParameters()

Description

Object properties that are parameters are normally returned as the integer or float parameter values as that is virtually always what the user would want. This function temporarily changes the behaviour so that if a property is a parameter the parameter name is returned instead. This can be used with 'method chaining' (see the example below) to make sure a property argument is correct.

Arguments

No arguments

Returns

Comment object.

Return type

Comment

Example

To check if Comment property c.example is a parameter by using the Comment.GetParameter() method:

if (c.ViewParameters().GetParameter(c.example) ) do_something...

Warning(message[string], details (optional)[string])

Description

Adds a warning for comment. For more details on checking see the Check class.

Arguments

message (string)

The warning message to give

details (optional) (string)

An optional detailed warning message

Returns

No return value

Example

To add a warning message "My custom warning" for comment c:

c.Warning("My custom warning");

Xrefs()

Description

Returns the cross references for this comment.

Arguments

No arguments

Returns

Xrefs object.

Return type

Xrefs

Example

To get the cross references for comment c:

var xrefs = c.Xrefs();

toString()

Description

Creates a string containing the comment data in keyword format. Note that this contains the keyword header and the keyword cards. See also Comment.Keyword() and Comment.KeywordCards().

Arguments

No arguments

Returns

string

Return type

String

Example

To get data for comment c in keyword format

var s = c.toString();