Manual/Plugins/Scripting/0.9.5

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
type	String	The name of the edge type. Possible values are regular, inverted, wall, hole

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 );
        path.add_quad(start_handle.p1,midpoint,finish_handle.p1);
    }
    else
    {
        // There's enough room to draw a cubic curve
        path.add_cubic(start_handle.p1,start_handle.p2,finish_handle.p2,finish_handle.p1);
    }
}