Mechanism class

The Mechanism class gives you access to mechanism 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

BlankAll(Model[Model], redraw (optional)[boolean])
BlankFlagged(Model[Model], flag[Flag], redraw (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])
Pick(prompt[string], limit (optional)[Model or Flag], modal (optional)[boolean], button text (optional)[string])
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])
SketchFlagged(Model[Model], flag[Flag], redraw (optional)[boolean])
Total(Model[Model], exists (optional)[boolean])
UnblankAll(Model[Model], redraw (optional)[boolean])
UnblankFlagged(Model[Model], flag[Flag], redraw (optional)[boolean])
UnflagAll(Model[Model], flag[Flag])
UnsketchAll(Model[Model], redraw (optional)[boolean])
UnsketchFlagged(Model[Model], flag[Flag], redraw (optional)[boolean])

Member functions

AddNodeSetToAssembly(index[integer], nsid[integer])
AddPartSetToAssembly(index[integer], psid[integer])
AddPartToAssembly(index[integer], pid[integer])
AssociateComment(Comment[Comment])
Blank()
Blanked()
ClearFlag(flag[Flag])
Copy(range (optional)[boolean])
DetachComment(Comment[Comment])
Error(message[string], details (optional)[string])
Flagged(flag[Flag])
GetAssembly(index[integer])
GetComments()
GetConnection(index[integer])
GetParameter(prop[string])
GetPoint(index[integer])
GetPointData(rpt[integer])
GetPointTitle(rpt[integer])
Next()
Previous()
RemoveConnection(index[integer])
RemoveNodeSetFromAssembly(index[integer], nsid[integer])
RemovePartFromAssembly(index[integer], pid[integer])
RemovePartSetFromAssembly(index[integer], psid[integer])
RemovePoint(index[integer])
SetConnection(index[integer], data[object])
SetFlag(flag[Flag])
SetPoint(index[integer], data[object])
Sketch(redraw (optional)[boolean])
Unblank()
Unsketch(redraw (optional)[boolean])
ViewParameters()
Warning(message[string], details (optional)[string])
Xrefs()

Mechanism constants

Constants for Connection types

Name	Description
Mechanism.COUPLER	Coupler mechanism connection
Mechanism.HINGE	Hinge mechanism connection
Mechanism.LINE	Line mechanism connection
Mechanism.PIN	Pin mechanism connection

Constants for Coupler modes

Name	Description
Mechanism.ROTATION	Rotational coupling on mechanism coupler
Mechanism.TRANSLATION	Translational coupling on mechanism coupler

Mechanism properties

Name	Type	Description
assemblies (read only)	integer	Number of assemblies defined.
connections (read only)	integer	Number of connections defined.
exists (read only)	logical	true if mechanism exists, false if referred to but not defined.
id (read only)	integer	Mechanism number. Also see the label property which is an alternative name for this.
include	integer	The Include file number that the mechanism is in.
label (read only)	integer	Mechanism number. Also see the id property which is an alternative name for this.
model (read only)	integer	The Model number that the mechanism is in.
points (read only)	integer	Number of reference points defined.
title	string	Mechanism title.

Detailed Description

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

Details of functions

AddNodeSetToAssembly(index[integer], nsid[integer])

Description

Add node set to assembly

Arguments

index (integer)

The index of the assembly in which you want to add node set. Note that reference points start at 0, not 1. 0 <= index < assemblies

nsid (integer)

The node set ID that you want to add.

Returns

No return value

Example

To add node set 3 in 3rd assembly in mechanism m:

m.AddNodeSetToAssembly(2,3);

AddPartSetToAssembly(index[integer], psid[integer])

Description

Add part set to assembly

Arguments

index (integer)

The index of the assembly in which you want to add part set. Note that reference points start at 0, not 1. 0 <= index < assemblies

psid (integer)

The part set ID that you want to add.

Returns

No return value

Example

To add part set 3 in 3rd assembly in mechanism m:

m.AddPartSetToAssembly(2,3);

AddPartToAssembly(index[integer], pid[integer])

Description

Add part to assembly

Arguments

index (integer)

The index of the assembly in which you want to add part. Note that reference points start at 0, not 1. 0 <= index < assemblies

pid (integer)

The part ID that you want to add.

Returns

No return value

Example

To add part 3 in 3rd assembly in mechanism m:

m.AddPartToAssembly(2,3);

AssociateComment(Comment[Comment])

Description

Associates a comment with a mechanism.

Arguments

Comment (Comment)

Comment that will be attached to the mechanism

Returns

No return value

Example

To associate comment c to the mechanism m:

m.AssociateComment(c);

Blank()

Description

Blanks the mechanism

Arguments

No arguments

Returns

No return value

Example

To blank mechanism m:

m.Blank();

BlankAll(Model[Model], redraw (optional)[boolean]) [static]

Description

Blanks all of the mechanisms in the model.

Arguments

Model (Model)

Model that all mechanisms will be blanked in

redraw (optional) (boolean)

If model should be redrawn or not. If omitted redraw is false. If you want to do several (un)blanks and only redraw after the last one then use false for all redraws apart from the last one. Alternatively you can redraw using View.Redraw().

Returns

No return value

Example

To blank all of the mechanisms in model m:

Mechanism.BlankAll(m);

BlankFlagged(Model[Model], flag[Flag], redraw (optional)[boolean]) [static]

Description

Blanks all of the flagged mechanisms in the model.

Arguments

Model (Model)

Model that all the flagged mechanisms will be blanked in

flag (Flag)

Flag set on the mechanisms that you want to blank

redraw (optional) (boolean)

Returns

No return value

Example

To blank all of the mechanisms in model m flagged with f:

Mechanism.BlankFlagged(m, f);

Blanked()

Description

Checks if the mechanism is blanked or not.

Arguments

No arguments

Returns

true if blanked, false if not.

Return type

Boolean

Example

To check if mechanism m is blanked:

if (m.Blanked() ) do_something...

ClearFlag(flag[Flag])

Description

Clears a flag on the mechanism.

Arguments

flag (Flag)

Flag to clear on the mechanism

Returns

No return value

Example

To clear flag f for mechanism m:

m.ClearFlag(f);

Copy(range (optional)[boolean])

Description

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

Mechanism object

Return type

Mechanism

Example

To copy mechanism m into mechanism z:

var z = m.Copy();

DetachComment(Comment[Comment])

Description

Detaches a comment from a mechanism.

Arguments

Comment (Comment)

Comment that will be detached from the mechanism

Returns

No return value

Example

To detach comment c from the mechanism m:

m.DetachComment(c);

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

Description

Adds an error for mechanism. 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 mechanism m:

m.Error("My custom error");

First(Model[Model]) [static]

Description

Returns the first mechanism in the model.

Arguments

Model (Model)

Model to get first mechanism in

Returns

Mechanism object (or null if there are no mechanisms in the model).

Return type

Mechanism

Example

To get the first mechanism in model m:

var m = Mechanism.First(m);

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

Description

Returns the first free mechanism label in the model. Also see Mechanism.LastFreeLabel(), Mechanism.NextFreeLabel() and Model.FirstFreeItemLabel().

Arguments

Model (Model)

Model to get first free mechanism 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

Mechanism label.

Return type

Number

Example

To get the first free mechanism label in model m:

var label = Mechanism.FirstFreeLabel(m);

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

Description

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

Arguments

Model (Model)

Model that all mechanisms will be flagged in

flag (Flag)

Flag to set on the mechanisms

Returns

No return value

Example

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

Mechanism.FlagAll(m, f);

Flagged(flag[Flag])

Description

Checks if the mechanism is flagged or not.

Arguments

flag (Flag)

Flag to test on the mechanism

Returns

true if flagged, false if not.

Return type

Boolean

Example

To check if mechanism m has flag f set on it:

if (m.Flagged(f) ) do_something...

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

Description

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

Arguments

Model (Model)

Model that all mechanisms are in

func (function)

Function to call for each mechanism

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

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

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

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

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

Description

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

Arguments

Model (Model)

Model to get mechanisms from

property (optional) (string)

Name for property to get for all mechanisms in the model

Returns

Array of Mechanism objects or properties

Return type

Array

Example

To make an array of Mechanism objects for all of the mechanisms in model m:

var a = Mechanism.GetAll(m);

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

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

GetAssembly(index[integer])

Description

Returns the information for an assembly

Arguments

index (integer)

The index of the assembly you want the coordinates for. Note that reference points start at 0, not 1. 0 <= index < assemblies

Returns

Object with the following properties:

Name	Type	Description
label	integer	Assembly label
parent	integer	Parent assembly label
title	string	Assembly title

Return type

object

Example

To get the information for the 3rd assembly for mechanism m:

var info = m.GetAssembly(2);

GetComments()

Description

Extracts the comments associated to a mechanism.

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 mechanism m:

var comm_array = m.GetComments();

GetConnection(index[integer])

Description

Returns the information for a connection

Arguments

index (integer)

The index of the connection you want the information for. Note that connections start at 0, not 1. 0 <= index < connections

Returns

Object with the following properties:

Name	Type	Description
angle	real	Current angle in degrees (for Mechanism.LINE and Mechanism.HINGE)
assembly1	integer	Assembly 1 label
assembly2	integer	Assembly 2 label
assembly3	integer	Assembly 3 label
coefficient1	real	Coefficient for linear coupler equation for connection 1 (for Mechanism.COUPLER)
coefficient2	real	Coefficient for linear coupler equation for connection 2 (for Mechanism.COUPLER)
coefficient3	real	Coefficient for linear coupler equation for connection 3 (for Mechanism.COUPLER)
connection1	integer	Connection 1 label (for Mechanism.COUPLER)
connection2	integer	Connection 2 label (for Mechanism.COUPLER)
connection3	integer	Connection 3 label (for Mechanism.COUPLER)
distance	real	Current distance (for Mechanism.LINE)
factor1	real	Factor 1 on Assembly 3 (Mechanism.LINE only)
factor2	real	Factor 2 on Assembly 3 (Mechanism.LINE only)
label	integer	Connection label
locked	integer	1 if locked (for Mechanism.LINE, Mechanism.PIN and Mechanism.HINGE)
mode1	integer	Coupling mode for connection 1. 0 = translational coupling, 1 = rotational coupling (for Mechanism.COUPLER)
mode2	integer	Coupling mode for connection 2. 0 = translational coupling, 1 = rotational coupling (for Mechanism.COUPLER)
mode3	integer	Coupling mode for connection 3. 0 = translational coupling, 1 = rotational coupling (for Mechanism.COUPLER)
node1	integer	Node 1 label (for Mechanism.LINE, Mechanism.PIN and Mechanism.HINGE)
node2	integer	Node 2 label (for Mechanism.LINE, Mechanism.PIN and Mechanism.HINGE)
nrotation	real	-ve rotation limit in degrees (for Mechanism.LINE and Mechanism.HINGE)
nslide	real	-ve slide translation (for Mechanism.LINE)
protation	real	+ve rotation limit in degrees (for Mechanism.LINE and Mechanism.HINGE)
pslide	real	+ve slide translation (for Mechanism.LINE)
title	string	Connection label
type	integer	Mechanism type (Mechanism.COUPLER, Mechanism.HINGE, Mechanism.LINE, Mechanism.PIN)
x1	real	X1 coordinates (for Mechanism.LINE, Mechanism.PIN and Mechanism.HINGE)
x2	real	X2 coordinates (for Mechanism.LINE, Mechanism.PIN and Mechanism.HINGE)
y1	real	Y1 coordinates (for Mechanism.LINE, Mechanism.PIN and Mechanism.HINGE)
y2	real	Y2 coordinates (for Mechanism.LINE, Mechanism.PIN and Mechanism.HINGE)
z1	real	Z1 coordinates (for Mechanism.LINE, Mechanism.PIN and Mechanism.HINGE)
z2	real	Z2 coordinates (for Mechanism.LINE, Mechanism.PIN and Mechanism.HINGE)

Return type

object

Example

To get the information for the 3rd connection for mechanism m:

var info = m.GetConnection(2);

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

Description

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

Arguments

Model (Model)

Model to get mechanisms from

flag (Flag)

Flag set on the mechanisms that you want to retrieve

property (optional) (string)

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

Returns

Array of Mechanism objects or properties

Return type

Array

Example

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

var m = Mechanism.GetFlagged(m, f);

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

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

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

Description

Returns the Mechanism object for a mechanism ID.

Arguments

Model (Model)

Model to find the mechanism in

number (integer)

number of the mechanism you want the Mechanism object for

Returns

Mechanism object (or null if mechanism does not exist).

Return type

Mechanism

Example

To get the Mechanism object for mechanism 100 in model m

var m = Mechanism.GetFromID(m, 100);

GetParameter(prop[string])

Description

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

Arguments

prop (string)

mechanism property to get parameter for

Returns

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

Return type

Parameter

Example

To check if Mechanism property m.example is a parameter:

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

To check if Mechanism property m.example is a parameter by using the GetParameter method:

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

GetPoint(index[integer])

Description

Returns the information for a reference point

Arguments

index (integer)

The index of the reference point you want the information for. Note that reference points start at 0, not 1. 0 <= index < points

Returns

Object with the following properties:

Name	Type	Description
assembly	integer	Assembly label
csys	integer	Coordinate system
hpt	boolean	If point has been automatically created by PRIMER at the H-point
label	integer	Point label
node	integer	Node label (0 if coordinate)
rx	boolean	Point restrained rotationally in X
ry	boolean	Point restrained rotationally in Y
rz	boolean	Point restrained rotationally in Z
title	string	Point title
tx	boolean	Point restrained translationally in X
ty	boolean	Point restrained translationally in Y
tz	boolean	Point restrained translationally in Z
x	real	Node/point x coordinate
y	real	Node/point y coordinate
z	real	Node/point z coordinate

Return type

object

Example

To get the information for the 3rd reference point for mechanism m:

var info = m.GetPoint(2);

GetPointData(rpt[integer])

Description

Returns the coordinates of a reference point

Arguments

rpt (integer)

The reference point you want the coordinates for. Note that reference points start at 0, not 1.

Returns

Array containing the reference point coordinates

Return type

Array

Example

To get the coordinates of the 3rd reference point for mechanism mec:

var c = mec.GetPointData(2)

GetPointTitle(rpt[integer])

Description

Returns the title of a reference point

Arguments

rpt (integer)

The reference point you want the title for. Note that reference points start at 0, not 1.

Returns

The reference point title

Return type

String

Example

To get the title of the 3rd reference point for mechanism mec:

var c = mec.GetPointTitle(2)

Last(Model[Model]) [static]

Description

Returns the last mechanism in the model.

Arguments

Model (Model)

Model to get last mechanism in

Returns

Mechanism object (or null if there are no mechanisms in the model).

Return type

Mechanism

Example

To get the last mechanism in model m:

var m = Mechanism.Last(m);

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

Description

Returns the last free mechanism label in the model. Also see Mechanism.FirstFreeLabel(), Mechanism.NextFreeLabel() and see Model.LastFreeItemLabel()

Arguments

Model (Model)

Model to get last free mechanism 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

Mechanism label.

Return type

Number

Example

To get the last free mechanism label in model m:

var label = Mechanism.LastFreeLabel(m);

Next()

Description

Returns the next mechanism in the model.

Arguments

No arguments

Returns

Mechanism object (or null if there are no more mechanisms in the model).

Return type

Mechanism

Example

To get the mechanism in model m after mechanism m:

var m = m.Next();

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

Description

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

Arguments

Model (Model)

Model to get next free mechanism 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

Mechanism label.

Return type

Number

Example

To get the next free mechanism label in model m:

var label = Mechanism.NextFreeLabel(m);

Pick(prompt[string], limit (optional)[Model or Flag], modal (optional)[boolean], button text (optional)[string]) [static]

Description

Allows the user to pick a mechanism.

Arguments

prompt (string)

Text to display as a prompt to the user

limit (optional) (Model or Flag)

If the argument is a Model then only mechanisms from that model can be picked. If the argument is a Flag then only mechanisms that are flagged with limit can be selected. If omitted, or null, any mechanisms from any model can be selected. from any model.

modal (optional) (boolean)

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

button text (optional) (string)

By default the window with the prompt will have a button labelled 'Cancel' which if pressed will cancel the pick and return null. If you want to change the text on the button use this argument. If omitted 'Cancel' will be used.

Returns

Mechanism object (or null if not picked)

Return type

Mechanism

Example

To pick a mechanism from model m giving the prompt 'Pick mechanism from screen':

var m = Mechanism.Pick('Pick mechanism from screen', m);

Previous()

Description

Returns the previous mechanism in the model.

Arguments

No arguments

Returns

Mechanism object (or null if there are no more mechanisms in the model).

Return type

Mechanism

Example

To get the mechanism in model m before mechanism m:

var m = m.Previous();

RemoveConnection(index[integer])

Description

Removes a connection from a mechanism

Arguments

index (integer)

The index of the connection you want to remove. Note that connections start at 0, not 1. 0 <= index < connections

Returns

no return value

Example

To remove the 3rd connection for mechanism m:

m.RemoveConnection(2);

RemoveNodeSetFromAssembly(index[integer], nsid[integer])

Description

Remove node set from assembly

Arguments

index (integer)

The index of the assembly from which you want to remove the node set. Note that reference points start at 0, not 1. 0 <= index < assemblies

nsid (integer)

The node set ID that you want to remove.

Returns

No return value

Example

To remove node set 3 from 3rd assembly in mechanism m:

m.RemoveNodeSetFromAssembly(2,3);

RemovePartFromAssembly(index[integer], pid[integer])

Description

Remove part from assembly

Arguments

index (integer)

The index of the assembly from which you want to remove the part. Note that reference points start at 0, not 1. 0 <= index < assemblies

pid (integer)

The part ID that you want to remove.

Returns

No return value

Example

To remove part 3 from 3rd assembly in mechanism m:

m.RemovePartFromAssembly(2,3);

RemovePartSetFromAssembly(index[integer], psid[integer])

Description

Remove part set from assembly

Arguments

index (integer)

The index of the assembly from which you want to remove the part set. Note that reference points start at 0, not 1. 0 <= index < assemblies

psid (integer)

The part set ID that you want to remove.

Returns

No return value

Example

To remove part set 3 from 3rd assembly in mechanism m:

m.RemovePartSetFromAssembly(2,3);

RemovePoint(index[integer])

Description

Removes a reference point from a mechanism

Arguments

index (integer)

The index of the reference point you want to remove. Note that reference points start at 0, not 1. 0 <= index < points

Returns

no return value

Example

To remove the 3rd reference point for mechanism m:

m.RemovePoint(2);

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

Description

Renumbers all of the mechanisms in the model.

Arguments

Model (Model)

Model that all mechanisms will be renumbered in

start (integer)

Start point for renumbering

Returns

No return value

Example

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

Mechanism.RenumberAll(m, 1000000);

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

Description

Renumbers all of the flagged mechanisms in the model.

Arguments

Model (Model)

Model that all the flagged mechanisms will be renumbered in

flag (Flag)

Flag set on the mechanisms that you want to renumber

start (integer)

Start point for renumbering

Returns

No return value

Example

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

Mechanism.RenumberFlagged(m, f, 1000000);

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

Description

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

Arguments

flag (Flag)

Flag to use when selecting mechanisms

prompt (string)

Text to display as a prompt to the user

limit (optional) (Model or Flag)

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

Return type

Number

Example

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

Mechanism.Select(f, 'Select mechanisms', m);

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

Mechanism.Select(f, 'Select mechanisms', l);

SetConnection(index[integer], data[object])

Description

Sets the data for a connection in a mechanism

Arguments

index (integer)

The index of the connection you want to set. Note that connections start at 0, not 1. To add a new connection use index connections

data (object)

Object containing the connection data. The properties can be:

Object has the following properties:

Name	Type	Description
angle (optional)	real	Current angle in degrees (for Mechanism.LINE and Mechanism.HINGE)
assembly1 (optional)	integer	Assembly 1 label (required for Mechanism.LINE, Mechanism.PIN and Mechanism.HINGE)
assembly2 (optional)	integer	Assembly 2 label (required for Mechanism.LINE, Mechanism.PIN and Mechanism.HINGE)
assembly3	integer	Assembly 3 label (required for Mechanism.LINE)
coefficient1 (optional)	real	Coefficient for linear coupler equation for connection 1 (for Mechanism.COUPLER)
coefficient2 (optional)	real	Coefficient for linear coupler equation for connection 2 (for Mechanism.COUPLER)
coefficient3 (optional)	real	Coefficient for linear coupler equation for connection 3 (for Mechanism.COUPLER)
connection1 (optional)	integer	Connection 1 label (for Mechanism.COUPLER)
connection2 (optional)	integer	Connection 2 label (for Mechanism.COUPLER)
connection3 (optional)	integer	Connection 3 label (for Mechanism.COUPLER)
distance (optional)	real	Current distance (for Mechanism.LINE)
factor1 (optional)	real	Factor 1 on Assembly 3 (Mechanism.LINE only)
factor2 (optional)	real	Factor 2 on Assembly 3 (Mechanism.LINE only)
locked (optional)	integer	1 if locked (for Mechanism.LINE, Mechanism.PIN and Mechanism.HINGE)
mode1 (optional)	integer	Coupling mode for connection 1. 0 = translational coupling, 1 = rotational coupling (for Mechanism.COUPLER)
mode2 (optional)	integer	Coupling mode for connection 2. 0 = translational coupling, 1 = rotational coupling (for Mechanism.COUPLER)
mode3 (optional)	integer	Coupling mode for connection 3. 0 = translational coupling, 1 = rotational coupling (for Mechanism.COUPLER)
node1 (optional)	integer	Node 1 label (for Mechanism.LINE, Mechanism.PIN and Mechanism.HINGE, not required if using x1, y1 and z1)
node2 (optional)	integer	Node 2 label (for Mechanism.LINE, Mechanism.PIN and Mechanism.HINGE, not required if using x2, y2 and z2)
nrotation (optional)	real	-ve rotation limit in degrees (for Mechanism.LINE and Mechanism.HINGE)
nslide (optional)	real	-ve slide translation (for Mechanism.LINE)
protation (optional)	real	+ve rotation limit in degrees (for Mechanism.LINE and Mechanism.HINGE)
pslide (optional)	real	+ve slide translation (for Mechanism.LINE)
title (optional)	string	Title
type	integer	Connection type. Can be one of: Mechanism.PIN, Mechanism.LINE, Mechanism.HINGE or Mechanism.COUPLER]
x1 (optional)	real	x1 coordinate (for Mechanism.LINE, Mechanism.PIN and Mechanism.HINGE, not required if using node1)
x2 (optional)	real	x2 coordinate (for Mechanism.LINE, Mechanism.PIN and Mechanism.HINGE, not required if using node2)
y1 (optional)	real	y1 coordinate (for Mechanism.LINE, Mechanism.PIN and Mechanism.HINGE, not required if using node1)
y2 (optional)	real	y2 coordinate (for Mechanism.LINE, Mechanism.PIN and Mechanism.HINGE, not required if using node2)
z1 (optional)	real	z1 coordinate (for Mechanism.LINE, Mechanism.PIN and Mechanism.HINGE, not required if using node1)
z2 (optional)	real	z2 coordinate (for Mechanism.LINE, Mechanism.PIN and Mechanism.HINGE, not required if using node2)

Returns

no return value

Example

To add a new pin connection to mechanism m between assemblies 5 and 6 at node 1000 with title "Example connection":

var data = { type:Mechanism.PIN, assembly1:5, assembly2:6, node1:1000, title:"Example connection" };
m.SetConnection(m.connections, data);

SetFlag(flag[Flag])

Description

Sets a flag on the mechanism.

Arguments

flag (Flag)

Flag to set on the mechanism

Returns

No return value

Example

To set flag f for mechanism m:

m.SetFlag(f);

SetPoint(index[integer], data[object])

Description

Sets the data for a reference point in a mechanism

Arguments

index (integer)

The index of the reference point you want to set. Note that reference points start at 0, not 1. To add a new point use index points

data (object)

Object containing the reference point data. The properties can be:

Object has the following properties:

Name	Type	Description
assembly	integer	Assembly label
csys (optional)	integer	Coordinate system label
node (optional)	integer	Node label (not required if using x, y and z)
rx (optional)	boolean	Point restrained rotationally in X
ry (optional)	boolean	Point restrained rotationally in Y
rz (optional)	boolean	Point restrained rotationally in Z
title (optional)	string	Point title
tx (optional)	boolean	Point restrained translationally in X
ty (optional)	boolean	Point restrained translationally in Y
tz (optional)	boolean	Point restrained translationally in Z
x (optional)	real	x coordinate (not required if using node)
y (optional)	real	y coordinate (not required if using node)
z (optional)	real	z coordinate (not required if using node)

Returns

no return value

Example

To add a new reference point to mechanism m assembly 5 at node 1000 with title "Example point" restrained in x:

var data = { assembly:5, node:1000, title:"Example point", tx:true };
m.SetPoint(m.points, data);

To add a new reference point to mechanism m assembly 5 at (10, 20, 30) with title "Example point":

var data = { assembly:5, x:10, y:20, z:30, title:"Example point" };
m.SetPoint(m.points, data);

Sketch(redraw (optional)[boolean])

Description

Sketches the mechanism. The mechanism will be sketched until you either call Mechanism.Unsketch(), Mechanism.UnsketchAll(), Model.UnsketchAll(), or delete the model

Arguments

redraw (optional) (boolean)

If model should be redrawn or not after the mechanism is sketched. If omitted redraw is true. If you want to sketch several mechanisms and only redraw after the last one then use false for redraw and call View.Redraw().

Returns

No return value

Example

To sketch mechanism m:

m.Sketch();

SketchFlagged(Model[Model], flag[Flag], redraw (optional)[boolean]) [static]

Description

Sketches all of the flagged mechanisms in the model. The mechanisms will be sketched until you either call Mechanism.Unsketch(), Mechanism.UnsketchFlagged(), Model.UnsketchAll(), or delete the model

Arguments

Model (Model)

Model that all the flagged mechanisms will be sketched in

flag (Flag)

Flag set on the mechanisms that you want to sketch

redraw (optional) (boolean)

If model should be redrawn or not after the mechanisms are sketched. If omitted redraw is true. If you want to sketch flagged mechanisms several times and only redraw after the last one then use false for redraw and call View.Redraw().

Returns

No return value

Example

To sketch all mechanisms flagged with flag in model m:

Mechanism.SketchFlagged(m, flag);

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

Description

Returns the total number of mechanisms in the model.

Arguments

Model (Model)

Model to get total for

exists (optional) (boolean)

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

Returns

number of mechanisms

Return type

Number

Example

To get the total number of mechanisms in model m:

var total = Mechanism.Total(m);

Unblank()

Description

Unblanks the mechanism

Arguments

No arguments

Returns

No return value

Example

To unblank mechanism m:

m.Unblank();

UnblankAll(Model[Model], redraw (optional)[boolean]) [static]

Description

Unblanks all of the mechanisms in the model.

Arguments

Model (Model)

Model that all mechanisms will be unblanked in

redraw (optional) (boolean)

Returns

No return value

Example

To unblank all of the mechanisms in model m:

Mechanism.UnblankAll(m);

UnblankFlagged(Model[Model], flag[Flag], redraw (optional)[boolean]) [static]

Description

Unblanks all of the flagged mechanisms in the model.

Arguments

Model (Model)

Model that the flagged mechanisms will be unblanked in

flag (Flag)

Flag set on the mechanisms that you want to unblank

redraw (optional) (boolean)

Returns

No return value

Example

To unblank all of the mechanisms in model m flagged with f:

Mechanism.UnblankFlagged(m, f);

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

Description

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

Arguments

Model (Model)

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

flag (Flag)

Flag to unset on the mechanisms

Returns

No return value

Example

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

Mechanism.UnflagAll(m, f);

Unsketch(redraw (optional)[boolean])

Description

Unsketches the mechanism.

Arguments

redraw (optional) (boolean)

If model should be redrawn or not after the mechanism is unsketched. If omitted redraw is true. If you want to unsketch several mechanisms and only redraw after the last one then use false for redraw and call View.Redraw().

Returns

No return value

Example

To unsketch mechanism m:

m.Unsketch();

UnsketchAll(Model[Model], redraw (optional)[boolean]) [static]

Description

Unsketches all mechanisms.

Arguments

Model (Model)

Model that all mechanisms will be unblanked in

redraw (optional) (boolean)

If model should be redrawn or not after the mechanisms are unsketched. If omitted redraw is true. If you want to unsketch several things and only redraw after the last one then use false for redraw and call View.Redraw().

Returns

No return value

Example

To unsketch all mechanisms in model m:

Mechanism.UnsketchAll(m);

UnsketchFlagged(Model[Model], flag[Flag], redraw (optional)[boolean]) [static]

Description

Unsketches all flagged mechanisms in the model.

Arguments

Model (Model)

Model that all mechanisms will be unsketched in

flag (Flag)

Flag set on the mechanisms that you want to unsketch

redraw (optional) (boolean)

Returns

No return value

Example

To unsketch all mechanisms flagged with flag in model m:

Mechanism.UnsketchAll(m, flag);

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

Mechanism object.

Return type

Mechanism

Example

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

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

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

Description

Adds a warning for mechanism. 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 mechanism m:

m.Warning("My custom warning");

Xrefs()

Description

Returns the cross references for this mechanism.

Arguments

No arguments

Returns

Xrefs object.

Return type

Xrefs

Example

To get the cross references for mechanism m:

var xrefs = m.Xrefs();