InterfaceComponent class

The InterfaceComponent class gives you access to interface component 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])
FirstFreeLabel(Model[Model], layer (optional)[Include number])
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])
LastFreeLabel(Model[Model], layer (optional)[Include number])
NextFreeLabel(Model[Model], layer (optional)[Include number])
RenumberAll(Model[Model], start[integer])
RenumberFlagged(Model[Model], flag[Flag], start[integer])
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

AssociateComment(Comment[Comment])
Browse(modal (optional)[boolean])
ClearFlag(flag[Flag])
Copy(range (optional)[boolean])
DetachComment(Comment[Comment])
Edit(modal (optional)[boolean])
Error(message[string], details (optional)[string])
Flagged(flag[Flag])
GetComments()
GetParameter(prop[string])
Keyword()
KeywordCards()
Next()
Previous()
SetFlag(flag[Flag])
ViewParameters()
Warning(message[string], details (optional)[string])
Xrefs()
toString()

InterfaceComponent constants

Name	Description
InterfaceComponent.NODE	Node option
InterfaceComponent.SEGMENT	Segment option

InterfaceComponent properties

Name	Type	Description
cid	integer	Coordinate system ID.
exists (read only)	logical	true if interface component exists, false if referred to but not defined.
include	integer	The Include file number that the interface component is in.
model (read only)	integer	The Model number that the interface component is in.
nid	integer	Node ID.
nsid	integer	Element ID or element set ID. The ssid property is an alternative name for this.
option	constant	InterfaceComponent option. Can be InterfaceComponent.NODE, InterfaceComponent.SEGMENT,
ssid	integer	Element ID or element set ID. The nsid property is an alternative name for this.
title	string	InterfaceComponent title

Detailed Description

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

Constructor

new InterfaceComponent(Model[Model], type[constant], snid/ssid[integer], cid[integer], nid[integer], label (optional)[integer], title (optional)[string])

Description

Create a new InterfaceComponent object.

Arguments

Model (Model)

Model that InterfaceComponent will be created in

type (constant)

InterfaceComponent type. Can be InterfaceComponent.NODE, InterfaceComponent.SEGMENT,

snid/ssid (integer)

Set node or set segment ID

cid (integer)

Coordinate system ID

nid (integer)

Node ID

label (optional) (integer)

InterfaceComponent number

title (optional) (string)

Title for this interface

Returns

InterfaceComponent object

Return type

InterfaceComponent

Example

To create a new Interface Component in model m with option: NODE, nsid: 100, cyd: 200, nid: 300, ID: 1, title: "MyInterfaceComponent"

var i_c = new InterfaceComponent(m, InterfaceComponent.NODE, 100, 200, 300, 1, MyInterfaceComponent);

Details of functions

AssociateComment(Comment[Comment])

Description

Associates a comment with a interface component.

Arguments

Comment (Comment)

Comment that will be attached to the interface component

Returns

No return value

Example

To associate comment c to the interface component i_c:

i_c.AssociateComment(c);

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 interface component i_c:

i_c.Browse();

ClearFlag(flag[Flag])

Description

Clears a flag on the interface component.

Arguments

flag (Flag)

Flag to clear on the interface component

Returns

No return value

Example

To clear flag f for interface component i_c:

i_c.ClearFlag(f);

Copy(range (optional)[boolean])

Description

Copies the interface component. The target include of the copied interface component 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

InterfaceComponent object

Return type

InterfaceComponent

Example

To copy interface component i_c into interface component z:

var z = i_c.Copy();

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

Description

Starts an interactive editing panel to create a interface component

Arguments

Model (Model)

Model that the interface component 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

InterfaceComponent object (or null if not made).

Return type

InterfaceComponent

Example

To start creating a interface component in model m:

var i_c = InterfaceComponent.Create(m);

DetachComment(Comment[Comment])

Description

Detaches a comment from a interface component.

Arguments

Comment (Comment)

Comment that will be detached from the interface component

Returns

No return value

Example

To detach comment c from the interface component i_c:

i_c.DetachComment(c);

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 interface component i_c:

i_c.Edit();

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

Description

Adds an error for interface component. 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 interface component i_c:

i_c.Error("My custom error");

First(Model[Model]) [static]

Description

Returns the first interface component in the model.

Arguments

Model (Model)

Model to get first interface component in

Returns

InterfaceComponent object (or null if there are no interface components in the model).

Return type

InterfaceComponent

Example

To get the first interface component in model m:

var i_c = InterfaceComponent.First(m);

FirstFreeLabel(Model[Model], layer (optional)[Include number]) [static]

Description

Returns the first free interface component label in the model. Also see InterfaceComponent.LastFreeLabel(), InterfaceComponent.NextFreeLabel() and Model.FirstFreeItemLabel().

Arguments

Model (Model)

Model to get first free interface component label in

layer (optional) (Include number)

Include file (0 for the main file) to search for labels in (Equivalent to First free in layer in editing panels). If omitted the whole model will be used (Equivalent to First free in editing panels).

Returns

InterfaceComponent label.

Return type

Number

Example

To get the first free interface component label in model m:

var label = InterfaceComponent.FirstFreeLabel(m);

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

Description

Flags all of the interface components in the model with a defined flag.

Arguments

Model (Model)

Model that all interface components will be flagged in

flag (Flag)

Flag to set on the interface components

Returns

No return value

Example

To flag all of the interface components with flag f in model m:

InterfaceComponent.FlagAll(m, f);

Flagged(flag[Flag])

Description

Checks if the interface component is flagged or not.

Arguments

flag (Flag)

Flag to test on the interface component

Returns

true if flagged, false if not.

Return type

Boolean

Example

To check if interface component i_c has flag f set on it:

if (i_c.Flagged(f) ) do_something...

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

Description

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

Arguments

Model (Model)

Model that all interface components are in

func (function)

Function to call for each interface component

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 interface components in model m:

InterfaceComponent.ForEach(m, test);
function test(i_c)
{
// i_c is InterfaceComponent object
}

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

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

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

Description

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

Arguments

Model (Model)

Model to get interface components from

property (optional) (string)

Name for property to get for all interface components in the model

Returns

Array of InterfaceComponent objects or properties

Return type

Array

Example

To make an array of InterfaceComponent objects for all of the interface components in model m:

var a = InterfaceComponent.GetAll(m);

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

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

GetComments()

Description

Extracts the comments associated to a interface component.

Arguments

No arguments

Returns

Array of Comment objects (or null if there are no comments associated to the node).

Return type

Array

Example

To get the array of comments associated to the interface component i_c:

var comm_array = i_c.GetComments();

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

Description

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

Arguments

Model (Model)

Model to get interface components from

flag (Flag)

Flag set on the interface components that you want to retrieve

property (optional) (string)

Name for property to get for all flagged interface components in the model

Returns

Array of InterfaceComponent objects or properties

Return type

Array

Example

To make an array of InterfaceComponent objects for all of the interface components in model m flagged with f:

var i_c = InterfaceComponent.GetFlagged(m, f);

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

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

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

Description

Returns the InterfaceComponent object for a interface component ID.

Arguments

Model (Model)

Model to find the interface component in

number (integer)

number of the interface component you want the InterfaceComponent object for

Returns

InterfaceComponent object (or null if interface component does not exist).

Return type

InterfaceComponent

Example

To get the InterfaceComponent object for interface component 100 in model m

var i_c = InterfaceComponent.GetFromID(m, 100);

GetParameter(prop[string])

Description

Checks if a InterfaceComponent 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 InterfaceComponent.ViewParameters() method and 'method chaining' (see the examples below).

Arguments

prop (string)

interface component property to get parameter for

Returns

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

Return type

Parameter

Example

To check if InterfaceComponent property i_c.example is a parameter:

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

To check if InterfaceComponent property i_c.example is a parameter by using the GetParameter method:

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

Keyword()

Description

Returns the keyword for this InterfaceComponent (*INTERFACE_COMPONENT). Note that a carriage return is not added. See also InterfaceComponent.KeywordCards()

Arguments

No arguments

Returns

string containing the keyword.

Return type

String

Example

To get the keyword for InterfaceComponent ed:

var key = ed.Keyword();

KeywordCards()

Description

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

Arguments

No arguments

Returns

string containing the cards.

Return type

String

Example

To get the cards for InterfaceComponent ed:

var cards = ed.KeywordCards();

Last(Model[Model]) [static]

Description

Returns the last interface component in the model.

Arguments

Model (Model)

Model to get last interface component in

Returns

InterfaceComponent object (or null if there are no interface components in the model).

Return type

InterfaceComponent

Example

To get the last interface component in model m:

var i_c = InterfaceComponent.Last(m);

LastFreeLabel(Model[Model], layer (optional)[Include number]) [static]

Description

Returns the last free interface component label in the model. Also see InterfaceComponent.FirstFreeLabel(), InterfaceComponent.NextFreeLabel() and see Model.LastFreeItemLabel()

Arguments

Model (Model)

Model to get last free interface component label in

layer (optional) (Include number)

Include file (0 for the main file) to search for labels in (Equivalent to Highest free in layer in editing panels). If omitted the whole model will be used.

Returns

InterfaceComponent label.

Return type

Number

Example

To get the last free interface component label in model m:

var label = InterfaceComponent.LastFreeLabel(m);

Next()

Description

Returns the next interface component in the model.

Arguments

No arguments

Returns

InterfaceComponent object (or null if there are no more interface components in the model).

Return type

InterfaceComponent

Example

To get the interface component in model m after interface component i_c:

var i_c = i_c.Next();

NextFreeLabel(Model[Model], layer (optional)[Include number]) [static]

Description

Returns the next free (highest+1) interface component label in the model. Also see InterfaceComponent.FirstFreeLabel(), InterfaceComponent.LastFreeLabel() and Model.NextFreeItemLabel()

Arguments

Model (Model)

Model to get next free interface component label in

layer (optional) (Include number)

Include file (0 for the main file) to search for labels in (Equivalent to Highest+1 in layer in editing panels). If omitted the whole model will be used (Equivalent to Highest+1 in editing panels).

Returns

InterfaceComponent label.

Return type

Number

Example

To get the next free interface component label in model m:

var label = InterfaceComponent.NextFreeLabel(m);

Previous()

Description

Returns the previous interface component in the model.

Arguments

No arguments

Returns

InterfaceComponent object (or null if there are no more interface components in the model).

Return type

InterfaceComponent

Example

To get the interface component in model m before interface component i_c:

var i_c = i_c.Previous();

RenumberAll(Model[Model], start[integer]) [static]

Description

Renumbers all of the interface components in the model.

Arguments

Model (Model)

Model that all interface components will be renumbered in

start (integer)

Start point for renumbering

Returns

No return value

Example

To renumber all of the interface components in model m, from 1000000:

InterfaceComponent.RenumberAll(m, 1000000);

RenumberFlagged(Model[Model], flag[Flag], start[integer]) [static]

Description

Renumbers all of the flagged interface components in the model.

Arguments

Model (Model)

Model that all the flagged interface components will be renumbered in

flag (Flag)

Flag set on the interface components that you want to renumber

start (integer)

Start point for renumbering

Returns

No return value

Example

To renumber all of the interface components in model m flagged with f, from 1000000:

InterfaceComponent.RenumberFlagged(m, f, 1000000);

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

Description

Allows the user to select interface components using standard PRIMER object menus.

Arguments

flag (Flag)

Flag to use when selecting interface components

prompt (string)

Text to display as a prompt to the user

limit (optional) (Model or Flag)

If the argument is a Model then only interface components from that model can be selected. If the argument is a Flag then only interface components that are flagged with limit can be selected (limit should be different to flag). If omitted, or null, any interface components 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 interface components selected or null if menu cancelled

Return type

Number

Example

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

InterfaceComponent.Select(f, 'Select interface components', m);

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

InterfaceComponent.Select(f, 'Select interface components', l);

SetFlag(flag[Flag])

Description

Sets a flag on the interface component.

Arguments

flag (Flag)

Flag to set on the interface component

Returns

No return value

Example

To set flag f for interface component i_c:

i_c.SetFlag(f);

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

Description

Returns the total number of interface components in the model.

Arguments

Model (Model)

Model to get total for

exists (optional) (boolean)

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

Returns

number of interface components

Return type

Number

Example

To get the total number of interface components in model m:

var total = InterfaceComponent.Total(m);

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

Description

Unsets a defined flag on all of the interface components in the model.

Arguments

Model (Model)

Model that the defined flag for all interface components will be unset in

flag (Flag)

Flag to unset on the interface components

Returns

No return value

Example

To unset the flag f on all the interface components in model m:

InterfaceComponent.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

InterfaceComponent object.

Return type

InterfaceComponent

Example

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

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

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

Description

Adds a warning for interface component. 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 interface component i_c:

i_c.Warning("My custom warning");

Xrefs()

Description

Returns the cross references for this interface component.

Arguments

No arguments

Returns

Xrefs object.

Return type

Xrefs

Example

To get the cross references for interface component i_c:

var xrefs = i_c.Xrefs();

toString()

Description

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

Arguments

No arguments

Returns

string

Return type

String

Example

To get data for InterfaceComponent ed in keyword format

var s = ed.toString();