Difference between revisions of "Manual/Plugins/Scripting/0.9.4"

From Knotter
Jump to navigation Jump to search
 
(5 intermediate revisions by the same user not shown)
Line 84: Line 84:
 
{{object list item|add_node(x,y)|Node|Creates a new node}}
 
{{object list item|add_node(x,y)|Node|Creates a new node}}
 
{{object list item|remove_node(node)|void|Remove node from the graph}}
 
{{object list item|remove_node(node)|void|Remove node from the graph}}
 +
{{object list item|remove_edge(edge)|void|Remove edge from the graph}}
 
{{object list item|connect(node1,node2)|Edge|Creates a new edge}}
 
{{object list item|connect(node1,node2)|Edge|Creates a new edge}}
 
{{object list item|node_at(point)|Node|Get the node at the given location}}
 
{{object list item|node_at(point)|Node|Get the node at the given location}}
Line 89: Line 90:
 
{{object list item|node_at(point,radius)|Array[Node]|Get the nodes within given distance from location}}
 
{{object list item|node_at(point,radius)|Array[Node]|Get the nodes within given distance from location}}
 
{{object list item|node_at(x,y,radius)|Array[Node]|Get the nodes within given distance from location}}
 
{{object list item|node_at(x,y,radius)|Array[Node]|Get the nodes within given distance from location}}
 +
{{object list item|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.}}
 +
{{object list item|append(Graph other)|void|The contents of the other graph are copied to this graph.}}
 +
{{object list item|clear()|void|Remove all edges and nodes}}
 
{{object list end}}
 
{{object list end}}
  
Line 136: Line 140:
 
{{object list item|open( String file )|Boolean|Open file, returns true if successful}}
 
{{object list item|open( String file )|Boolean|Open file, returns true if successful}}
 
{{object list item|open()|Boolean|Create an new tab}}
 
{{object list item|open()|Boolean|Create an new tab}}
 +
{{object list item|screenshot(String file, String widget_name{{=}}"")|void|Take a screenshot of the given widget (or the main window if '''widget_name''' is empty).}}
 
{{object list end}}
 
{{object list end}}
  
Line 198: Line 203:
 
==Plugin-specific objects==
 
==Plugin-specific objects==
  
===Cusp===
+
===All Plugins===
 +
All plugins can access the object {{js|plugin}} that contains the information from the [[Manual/Plugins#Plugin_Data|plugin data]].
 +
 
 +
===Cusp Plugins===
 
{{object list begin}}
 
{{object list begin}}
 
{{object list header}}
 
{{object list header}}

Latest revision as of 16:28, 12 June 2013

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 );
        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);
    }
}