# Manual/Plugins/Scripting/0.9.4

Scripts are in QtScript aka ECMAScript aka JavaScript.

The details of the language are specified in the Qt ECMAScript reference. This page focuses on functions and objects specific to Knotter.

## Geometry

### Point

A wrapper to QPointF.

Constructors
Name Type Description
`new Point()` `Point` `new Point(0,0)`
`new Point( Point other )` `Point` Copy point `other`
`new Point( Number x, Number y )` `Point` Create point with given coordinates
External functions
Name Type Description
`opposite( Point p )` `Point` `new Point(-p.x,-p.y)`
`distance(Point a, Point b)` `Number` Distance from a and b

### Line

A wrapper to QLineF most of the functionality of QLineF is also present in `line`.

Constructors
Name Type Description
`new Line()` `Line` Empty line
`new Line( Line other )` `Line` Copy line `other_line`
`new Line( point1, point2 )` `Line` Line from point `point1` to `point2`
Properties
Name Type Description
`p1` `Point` Starting point of the line
`p2` `Point` End point of the line
`x1` `Number` `p1.x`
`x2` `Number` `p2.x`
`y1` `Number` `p1.y`
`y2` `Number` `p2.y`
`angle` `Number` Angle of the line in degrees. An angle of 0° is a horizontal line pointing to the right.
`length` `Number` Length of the line (distance between `p1` and `p2`
`dx` `Number` `p1.x-p2.x`
`dy` `Number` `p1.y-p2.y`
Methods
Name Type Description
`intersect ( Line other )` `Point` Return the intersection point between the current line and other
`normalVector()` `Line` Returns a line that is perpendicular to this line with the same starting point and length.
`unitVector()` `Line` Returns the unit vector for this line, i.e a line starting at the same point as this line with a length of 1.0.
`pointAt(Number t)` `Point` Returns the point at the parameterized position specified by t. The function returns the line's start point if t = 0, and its end point if t = 1.
`translate(Point offset)` `void` Translate the line by `offset`
`translate(Number x,Number y)` `void` `translate(point(x,y))`

### Polygon

Name Type Description
`new Polygon()` `Polygon` Create an empty polygon.
`new Polygon(vertices)` `Polygon` Create a polygon with given vertices.
`vertices` `Array[Point]` Vertices of the polygon.
`contains(point)` `Boolean` Whether the point is inside the polygon.
`contains(x,y)` `Boolean` `contains(new Point(x,y))`.
`add_vertex(point)` `void` Appends a vertex to `vertices`.

## Graph

### Graph

The graph for a given knot.

Name Type Description
`new graph()` `Graph` Creates an empty graph
`nodes` `Array[Node]` Nodes in the graph
`edges` `Array[Edge]` Edges in the graph
`selected_nodes` `Array[node]` List of the selected nodes
`add_node(point)` `Node` Creates a new node
`add_node(x,y)` `Node` Creates a new node
`remove_node(node)` `void` Remove node from the graph
`remove_edge(edge)` `void` Remove edge from the graph
`connect(node1,node2)` `Edge` Creates a new edge
`node_at(point)` `Node` Get the node at the given location
`node_at(x,y)` `Node` Get the node at the given location
`node_at(point,radius)` `Array[Node]` Get the nodes within given distance from location
`node_at(x,y,radius)` `Array[Node]` Get the nodes within given distance from location
`append( file_name, keep_style=false, offset=Point() )` `Boolean` Add nodes and edges from a file. keep_style controls whether the nodes should have their custom style set to override the graph style in order to follow the style from the file.
`append(Graph other)` `void` The contents of the other graph are copied to this graph.
`clear()` `void` Remove all edges and nodes

### Node

Name Type Description
`pos` `Point` Position of the node.
`x` `Number` `pos.x`.
`y` `Number` `pos.y`.
`selected` `Boolean` Whether the node is selected.
`edges` `Array[Edge]` (Read-Only) Edges with this node as vertex.
`has_edge_too(Node other)` `Boolean` Whether there is an edge from `this` to `other`.
`edge_to(Node other)` `Edge` Edge connecting `this` and `other`.

### Edge

Name Type Description
`vertex1` `Node` One of the vertices of the edge
`vertex2` `Node` One of the vertices of the edge
`line` `Line` Line from `vertex1.pos` to `vertex2.pos`
`midpoint` `Point` Point at the middle of the edge
`is_vertex(node)` `Boolean` Whether the node is a vertex of the edge
`other(node)` `Node` If the given node is one of its vertices, return the other vertex

## Interaction with Knotter

### knotter

Object with information on Knotter.

Name Type Description
`version` `String` Knotter version
`has_version(Number major,Number minor)` `Boolean` Whether the current version is greater than major.minor.0

### window

Perform some basic operations to Knotter main window.

Name Type Description
`current_file` `String` (Read only) File name of the knot in the active tab
`current_tab` `Number` Index of the active tab
`open_tabs` `Number` Number of open tabs
`document` `Document` Document corresponding to the current tab.
`open( String file )` `Boolean` Open file, returns true if successful
`open()` `Boolean` Create an new tab
`screenshot(String file, String widget_name="")` `void` Take a screenshot of the given widget (or the main window if widget_name is empty).

### window.dialog

An object that contains several functions to display simple dialogs to the user

Name Type Description
`information(message,title="")` `void` Display an information dialog
`warning(message,title="")` `void` Display a warning dialog
`critical(message,title="")` `void` Display an error dialog
`question(message, title="", button_0="OK", button_1="", button_2="")` `Number` Display a dialog asking a question. For every non-empty button text a button is shown. Returns the index of the button that the user pressed.
`get_open_file(title="",filters="")` `String` Show a dialog to open a file. Filters is in the form "Text (.txt);;Image (.svg .png)", Returns the selected file name or an empty string if the user canceled the dialog.
`get_number(message, title="", default_value=0, min=MIN, max=MAX)` `Number` Asks a dialog for a number. Returns NaN if the user canceled.
`get_integer(message, title="", default_value=0, min=MIN, max=MAX)` `Number` Just like get_number but only integers values are allowed
`get_text(message,title="",default_value=)` `String` Ask the user for a line of text.
`information(get_item,title="",items=[])` `String` Ask the user to select an item from the list. Returns the string representing the value or an empty string if the user canceled the dialog.
`load_widget(file_name)` `QWidget` Load a widget from a Ui file
`progress_dialog(message, maximum=0, cancel_button="Cancel" )` `QProgressDialog` Creates a progress dialog.

### Document

(Global object) The document from which the script was called. While window.document may change, the global document object will be the same during the entire script.

Name Type Description
`filename` `String` The name of the file for this document.
`graph` `Graph` The graph contained by the document.
`grid` `Grid` The grid used by the document.
`insert(graph,message="ScriptInsert")` `Boolean` Insert graph in the document. The inserted graph will have to be placed by the user in the desired location. Returns whether insertion has been successful.
`begin_macro(message)` `void` Wrap following edits to the document in a macro, the message will be the text displayed in the action history. Macros can be nested.
`end_macro()` `void` End current macro. For each call to `begin_macro` there should be a call to `end_macro`.

### Grid

The grid displayed by a document object.

Name Type Description
`size` `Number` Size of a grid cell.
`origin` `Point` Position of the grid origin
`enabled` `Boolean` Whether the grid is displayed or not.
`shape` `String` One of SQUARE, TRIANGLE1 or TRIANGLE2.
`enable()` `void` Shorthand for `grid.enabled = true;`.
`disable()` `void` Shorthand for `grid.enabled = false;`.

### Path

Object used in cusp plugins to draw the knot line, wrapper to the Knotter internal Path_Builder class. Cannot be constructed by the user.

Methods
Name Type Description
`add_line( Point p1, Point p2 )` `void` Draw a straight line from `p1` to `p2`
`add_quad( Point p1, Point control, Point p2` `void` Draw a quadratic curve from `p1` to `p2` with control point `control`
`add_cubic( Point p1, Point control1, Point control2, Point p2 )` `void` Draw a cubic curve from `p1` to `p2` with control points `control1` and `control2`

## Plugin-specific objects

### All Plugins

All plugins can access the object `plugin` that contains the information from the plugin data.

### Cusp Plugins

Name Type Description
`angle` `Number` The angle between input and output edge
`cusp_angle` `Number` Style setting, if `angle > cusp_angle` , draw a cusp
`handle_length` `Number` Style setting, "curve" style parameter in the UI
`start_handle` `Line` Starting point for lines, start_handle.p1 will be connected to the path forming the crossing
`finish_handle` `Line` Ending point for lines, finish_handle.p1 will be connected to the path forming the crossing
`cusp_point` `Point` Pre-computed cusp point location
`node_point` `Point` Position of the node between the two edges
`input_edge` `Line` Line corresponding to the input edge
`output_edge` `Line` Line corresponding to the output edge
`path` `Path` Object used to build the path
`direction` `Number` -1 or +1 depending on the direction of the angle (clockwise or counter)

#### Guidelines

A cusp is expected to render a path from `start_handle.p1` to `finish_handle.p1`.

`start_handle.p2` and `finish_handle.p2` may be used as control points.

If `angle > cusp_angle` the line should pass through `cusp_point`

#### Example

Follows the code to replicate the built-in rounded cusp.

```// When angle is large enough, draw the cusp
if ( angle > cusp_angle )
{
// Create a "handle" that on cusp_point with size handle_length to determine the control points
var handle = new Line(start_handle.p1,finish_handle.p1);
handle.translate(cusp_point);
handle.translate(opposite(start_handle.p1));
handle.length = handle_length;
var h2 = handle.p2;
handle.length = -handle_length;
var h1 = handle.p2;
// Use the control points to render the cusp
path.add_cubic ( start_handle.p1, start_handle.p2, h1, cusp_point );
path.add_cubic ( finish_handle.p1, finish_handle.p2, h2, cusp_point );
}
else
{
// Don't draw a cusp, just a curve from start_handle to finish_handle

if ( distance(start_handle.p1,finish_handle.p1) < start_handle.length + finish_handle.length )
{
// The two edges are very close together, avoid artifacts with a simpler curve
var midpoint = Point( (start_handle.p2.x+finish_handle.p2.x)/2,
(start_handle.p2.y+finish_handle.p2.y)/2 );