View source for Manual/Plugins/Scripting

{{vbox|0.9.6}}

Scripts are in QtScript aka ECMAScript aka JavaScript. 

The details of the language are specified in the [http://qt-project.org/doc/qt-5.0/qtscript/ecmascript.html Qt ECMAScript reference]. This page focuses on functions and objects specific to Knotter.



==Geometry==

===Point===
A wrapper to [http://qt-project.org/doc/qt-5.0/qtcore/qpointf.html QPointF].

{{object list begin}}

{{object list section|Constructors}}
{{object list header}}
{{object list item|new Point()|Point|{{js|new Point(0,0)}}}}
{{object list item|new Point( Point other )|Point|Copy point {{js|other}}}}
{{object list item|new Point( Number x, Number y )|Point|Create point with given coordinates}}

{{object list section|External functions}}
{{object list header}}
{{object list item|opposite( Point p )|Point|{{js|new Point(-p.x,-p.y)}}}}
{{object list item|distance(Point a, Point b)|Number|Distance from '''a''' and '''b'''}}

{{object list end}}

===Line===
A wrapper to [http://qt-project.org/doc/qt-5.0/qtcore/qlinef.html QLineF] most of the functionality of '''QLineF''' is also present in {{js|line}}.

{{object list begin}}

{{object list section|Constructors}}
{{object list header}}
{{object list item|new Line()|Line|Empty line}}
{{object list item|new Line( Line other )|Line|Copy line {{js|other_line}}}}
{{object list item|new Line( point1, point2 )|Line|Line from point {{js|point1}} to {{js|point2}}}}

{{object list section|Properties}}
{{object list header}}
{{object list item|p1|Point|Starting point of the line}}
{{object list item|p2|Point|End point of the line}}
{{object list item|x1|Number|{{js|p1.x}}}}
{{object list item|x2|Number|{{js|p2.x}}}}
{{object list item|y1|Number|{{js|p1.y}}}}
{{object list item|y2|Number|{{js|p2.y}}}}
{{object list item|angle|Number
|Angle of the line in degrees. An angle of 0° is a horizontal line pointing to the right.}}
{{object list item|length|Number|Length of the line (distance between {{js|p1}} and {{js|p2}}}}
{{object list item|dx|Number|{{js|p1.x-p2.x}}}}
{{object list item|dy|Number|{{js|p1.y-p2.y}}}}

{{object list section|Methods}}
{{object list header}}
{{object list item|intersect ( Line other )|Point|Return the intersection point between the current line and other}}
{{object list item|normalVector()|Line|Returns a line that is perpendicular to this line with the same starting point and length.}}
{{object list item|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.}}
{{object list item|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.}}
{{object list item|translate(Point offset)|void|Translate the line by {{js|offset}}}}
{{object list item|translate(Number x,Number y)|void|{{js|translate(point(x,y))}}}}
{{object list end}}

===Polygon===
{{object list begin}}
{{object list header}}
{{object list item|new Polygon()|Polygon|Create an empty polygon.}}
{{object list item|new Polygon(vertices)|Polygon|Create a polygon with given vertices.}}
{{object list item|vertices|Array[Point]|Vertices of the polygon.}}
{{object list item|contains(point)|Boolean|Whether the point is inside the polygon.}}
{{object list item|contains(x,y)|Boolean|{{js|contains(new Point(x,y))}}.}}
{{object list item|add_vertex(point)|void|Appends a vertex to {{js|vertices}}.}}
{{object list end}}


==Misc==
===global functions===
{{object list begin}}
{{object list header}}
{{object list item|print(...)|void|Writes all arguments to standard output and the {{bl|Manual/Dialogs/Script_Console}}.}}
{{object list item|run_script(filename)|void|executes the given script file in the current context.}}
{{object list end}}

===Color===
{{object list begin}}
{{object list section|Constructors}}
{{object list header}}
{{object list item|new Color()|Color|Creates a transparent black color}}
{{object list item|new Color(string)|Color|Create a color from a color name eg: '''#ff00ff''', '''red'''}}
{{object list item|new Color(r,g,b,a{{=}}255)|Color|Create a color from rgb components [0-255]}}
{{object list item|new Color(color)|Color|Copy color}}
{{object list section|Properties}}
{{object list header}}
{{object list item|alpha|Number|Transparency [0-255]}}
{{object list item|red|Number|RGB red channel [0-255]}}
{{object list item|green|Number|RGB green channel [0-255]}}
{{object list item|blue|Number|RGB blue channel [0-255]}}
{{object list item|hue|Number|HSV hue channel [0-360]}}
{{object list item|saturation|Number|HSV saturation channel [0-255]}}
{{object list item|value|Number|HSV value channel [0-255]}}
{{object list item|cyan|Number|CMYK cyan channel [0-255]}}
{{object list item|magenta|Number|CMYK magenta channel [0-255]}}
{{object list item|yellow|Number|CMYK yellow channel [0-255]}}
{{object list item|black|Number|CMYK black channel [0-255]}}
{{object list section|Number|External functions}}
{{object list header}}
{{object list item|rgb(r,g,b,a{{=}}255)|Color|Same as {{js|new Color(r,g,b,a)}}}}
{{object list item|hsv(h,s,v,a{{=}}255)|Color|Creates a color from its HSV components}}
{{object list item|hsl(h,s,l,a{{=}}255)|Color|Creates a color from its HSL components}}
{{object list item|cmyk(c,m,y,k,a{{=}}255)|Color|Creates a color from its CMYK components}}
{{object list end}}

===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.
{{object list begin}}
{{object list section|Methods}}
{{object list header}}
{{object list item|add_line( Point p1, Point p2 )|void|Draw a straight line from {{js|p1}} to {{js|p2}} }}
{{object list item|add_quad( Point p1, Point control, Point p2|void
|Draw a quadratic curve from {{js|p1}} to {{js|p2}} with control point {{js|control}} }}
{{object list item|add_cubic( Point p1, Point control1, Point control2, Point p2 )|void
|Draw a cubic curve from {{js|p1}} to {{js|p2}} with control points {{js|control1}} and {{js|control2}} }}
{{object list end}}

==Graph==

===Graph===
The graph for a given knot.
{{object list begin}}
{{object list header}}
{{object list item|new graph()|Graph|Creates an empty graph}}
{{object list item|nodes|Array[Node]|Nodes in the graph}}
{{object list item|edges|Array[Edge]|Edges in the graph}}
{{object list item|style|Graph.Style|Graph Style}}
{{object list item|selected_nodes|Array[node]|List of the selected nodes}}
{{object list item|add_node(point)|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_edge(edge)|void|Remove edge from the graph}}
{{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(x,y)|Node|Get the node at the given 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|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}}


===Node===
{{object list begin}}
{{object list header}}
{{object list item|pos|Point|Position of the node.}}
{{object list item|x|Number|{{js|pos.x}}.}}
{{object list item|y|Number|{{js|pos.y}}.}}
{{object list item|selected|Boolean|Whether the node is selected.}}
{{object list item|edges|Array[Edge]|(Read-Only) Edges with this node as vertex.}}
{{object list item|style|Node.Style|Contains the style features that this node overrides from the graph}}
{{object list item|has_edge_too(Node other)|Boolean|Whether there is an edge from {{js|this}} to {{js|other}}.}}
{{object list item|edge_to(Node other)|Edge|Edge connecting {{js|this}} and {{js|other}}.}}
{{object list end}}

===Edge===
{{object list begin}}
{{object list header}}
{{object list item|vertex1|Node|One of the vertices of the edge}}
{{object list item|vertex2|Node|One of the vertices of the edge}}
{{object list item|line|Line|Line from {{js|vertex1.pos}} to {{js|vertex2.pos}}}}
{{object list item|midpoint|Point|Point at the middle of the edge}}
{{object list item|style|Edge.Style|Contains the style features that this edge overrides from the graph}}
{{object list item|is_vertex(node)|Boolean|Whether the node is a vertex of the edge}}
{{object list item|other(node)|Node|If the given node is one of its vertices, return the other vertex}}
{{object list end}}


===Graph.Style===
Default style for nodes and edges and graph appearance
{{object list begin}}
{{object list header}}
{{object list item|crossing|Edge.Style|Default edge style}}
{{object list item|cusp|Node.Style|Default node style}}
{{object list item|colors|Array[Color]|(Read-Only) Colors}}
{{object list end}}

===Node.Style===
For nodes, a single style feature can be removed by setting it to {{js|undefined}}
{{object list begin}}
{{object list header}}
{{object list item|angle|Number|Minimum angle required to trigger a cusp}}
{{object list item|curve|Number|Size of the curve control handles}}
{{object list item|distance|Number|Distance of the tip of the cusp from the node}}
{{object list item|shape|String|Name of the cusp shape. Possible values are the elements of {{js|knotter.cusp_shapes}}}}
{{object list item|clear()|void|Reset all features}}
{{object list end}}

===Edge.Style===
For nodes, a single style feature can be removed by setting it to {{js|undefined}}
{{object list begin}}
{{object list header}}
{{object list item|curve|Number|Size of the curve control handles}}
{{object list item|gap|Number|Size of the gap for a rope passing under a crossing}}
{{object list item|slide|Number|Slide the crossing position [0-1]}}
{{object list item|type|String|The name of the edge type. Possible values are the elements of {{js|knotter.edge_types}} }}
{{object list item|clear()|void|Reset all features}}
{{object list end}}


==Interaction with Knotter==

===system===
Object that allows interactions with the system.
{{object list begin}}
{{object list header}}
{{object list item|read_file(file_name)|ByteArray|Read file contents}}
{{object list item|write_file(file_name,data)|Boolean|Write data to file.{{js|data}} can be either a string or a ByteArray. Returns true if the output was successful.}}
{{object list item|temp_path()|String|Returns the system temporary directory path.}}
{{object list end}}

===knotter===
Object with information on Knotter.
{{object list begin}}
{{object list header}}
{{object list item|version|String|Knotter version}}
{{object list item|has_version(Number major,Number minor)|Boolean|Whether the current version is greater than major.minor.0}}
{{object list item|cusp_shapes|Array[String]|Array of names of the available cusp shapes}}
{{object list item|edge_types|Array[String]|Array of names of the available edge types}}
{{object list end}}

===window===
Perform some basic operations to Knotter main window.
{{object list begin}}
{{object list header}}
{{object list item|current_file|String|(Read only) File name of the knot in the active tab}}
{{object list item|current_tab|Number|Index of the active tab}}
{{object list item|open_tabs|Number|Number of open tabs}}
{{object list item|document|Document|Document corresponding to the current tab.}}
{{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|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}}

===window.dialog===
An object that contains several functions to display simple dialogs to the user.
{{object list begin}}
{{object list header}}
{{object list item|information(message,title{{=}}"")|void|Display an information dialog}}
{{object list item|warning(message,title{{=}}"")|void|Display a warning dialog}}
{{object list item|critical(message,title{{=}}"")|void|Display an error dialog}}
{{object list item|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.}}
{{object list item|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.}}
{{object list item|get_number(message, title{{=}}"", default_value{{=}}0, min{{=}}MIN, max{{=}}MAX)|Number|Asks a dialog for a number. Returns NaN if the user canceled.}}
{{object list item|get_integer(message, title{{=}}"", default_value{{=}}0, min{{=}}MIN, max{{=}}MAX)|Number|Just like '''get_number''' but only integers values are allowed}}
{{object list item|get_text(message,title{{=}}"",default_value{{=}})|String|Ask the user for a line of text.}}
{{object list item|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.}}
{{object list item|load_widget(file_name)|QWidget|Load a widget from a Ui file}}
{{object list item|progress_dialog(message, maximum{{=}}0, cancel_button{{=}}"Cancel" )|QProgressDialog|Creates a [http://qt-project.org/doc/qt-5.0/qtwidgets/qprogressdialog.html progress dialog].}}
{{object list end}}

===gui===
Utility object that creates wrappers to Qt widgets in order to access some of their functionality that is not usually available to scripts.
{{object list begin}}
{{object list header}}
{{object list item|table_widget(QTableWidget)|gui.table_widget|Creates a wrapper to a QTableWidget.}}
{{object list end}}
====gui.table_widget====
{{object list begin}}
{{object list header}}
{{object list item|table|QObject|The wrapped QTableWidget.}}
{{object list item|set_value(row, column, value)|void|Change the value in the given cell.}}
{{object list item|get_value (row,column)|String|Get the value in the given cell.}}
{{object list item|append_row([values])|void|Append a row with the given values.}}
{{object list item|current_row()|Number|The currently selected row or -1.}}
{{object list item|current_column()|Number|The currently selected column or -1.}}
{{object list item|value_changed(row,column,value)|(Signal)|Emitted when the user changes the content of a cell.}}
{{object list end}}

===Document===
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.
{{object list begin}}
{{object list header}}
{{object list item|filename|String|The name of the file for this document.}}
{{object list item|graph|Graph|The graph contained by the document.}}
{{object list item|grid|Grid|The grid used by the document.}}
{{object list item|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.}}
{{object list item|render|Document.Render|Document renderer}}
{{object list item|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.}}
{{object list item|end_macro()|void|End current macro. For each call to {{js|begin_macro}} there should be a call to {{js|end_macro}}.}}
{{object list end}}

===Grid===
The grid displayed by a document object.
{{object list begin}}
{{object list header}}
{{object list item|size|Number|Size of a grid cell.}}
{{object list item|origin|Point|Position of the grid origin}}
{{object list item|enabled|Boolean|Whether the grid is displayed or not.}}
{{object list item|shape|String|One of ''SQUARE'', ''TRIANGLE1'' or ''TRIANGLE2''.}}
{{object list item|enable()|void|Shorthand for {{js|grid.enabled {{=}} true;}}.}}
{{object list item|disable()|void|Shorthand for {{js|grid.enabled {{=}} false;}}.}}
{{object list end}}

==Plugin-specific objects==

===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 header}}
{{object list item|angle|Number|The angle between input and output edge}}
{{object list item|cusp_angle|Number|Style setting, if {{js|angle > cusp_angle}} , draw a cusp}}
{{object list item|handle_length|Number|Style setting, "curve" style parameter in the UI}}
{{object list item|start_handle|Line|Starting point for lines, start_handle.p1 will be connected to the path forming the crossing}}
{{object list item|finish_handle|Line|Ending point for lines, finish_handle.p1 will be connected to the path forming the crossing}}
{{object list item|cusp_point|Point|Pre-computed cusp point location}}
{{object list item|node_point|Point|Position of the node between the two edges}}
{{object list item|input_edge|Line|Line corresponding to the input edge}}
{{object list item|output_edge|Line|Line corresponding to the output edge}}
{{object list item|path|Path|Object used to build the path}}
{{object list item|direction|Number| -1 or +1 depending on the direction of the angle (clockwise or counter)}}
{{object list end}}

====Guidelines====
A cusp is expected to render a path from {{js|start_handle.p1}} to {{js|finish_handle.p1}}.

{{js|start_handle.p2}} and {{js|finish_handle.p2}} may be used as control points.

If {{js|angle > cusp_angle}} the line should pass through {{js|cusp_point}}

====Example====
Follows the code to replicate the built-in rounded cusp.
{{script|
// 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);
    }
} 
}}