Open Source 2D CAD
The new QCAD Part Library Browser can not only contain static part library items but also dynamic items that are created based on parameters, mathematical formulas, user input, SQL data bases, XML files or other data sources. A dynamic item is rendered when the item is being inserted.
Script items may display a custom user interface component for the user to enter script parameters. For example, an item that shows the top view of a dining table might allow the user to input the length and width of the table.
The part library included with QCAD contains such a sample script item called "DiningTable.js" located under "library/misc".
In this tutorial we will create a new dynamic item for the library browser. The item should generate a cut-out template for a cube as shown here:
The dynamic item has two parameters which can be specified by the user when the script item is being inserted into the drawing:
First, we create a new script file that will do the work behind our new dynamic part library item:
This adds a class named
CubeCuttingOut to the script file. Note that the class must have the same name as the script file (case sensitive).
Besides the constructor, three functions are required to make this a valid, functional script item:
init()is called whenever the preview icon (see below) is generated or when the script item is being inserted into a drawing.
formWidgetis the widget that displays the script item's parameters (if applicable).
generate()is called when the user is about to insert the script item.
documentInterfaceis a valid document interface (RDocumentInterface) that is used to create the library item. This is not the document the user is editing. The part library script has no direct access to the drawing of the user.
fileis the name of the current script file (String).
generatePreview()is called to create an icon for the library browser preview. Note that at the moment the preview icon is generated, no user input is available. Usually an icon with default parameters is generated.
documentInterfaceis a valid document interface (RDocumentInterface).
iconSizeis the user configurable size of the icon (integer).
The script item is now valid. Locate your new library folder in the 'File System' tab of the QCAD Library Browser. Right-click on the folder and click 'Regenerate Icons'. Your item should show up with an empty icon that is decorated with a small cog wheel to indicate that this is a dynamic library item backed by a script file.
In most cases, the functions
generatePreview() do almost the same. The main difference between
generatePreview() is that generate() works with user input to define the script parameters, while generatePreview() has no user input and should generate the item with default parameters to create a recognizable icon.
It is usually recommendable to write a helper function that creates the RAddObjectsOperation object that is returned by both functions based on the script parameters.
For this example, we name that function
For now, the size of the cube is fixed to 10 drawing units (variable
CubeCuttingOut.size). We will later use
CubeCuttingOut.size as an input parameter for our helper function.
Based on the cube size, the helper function generates the CAD entities that represent a square. These entities are added to the operation that will be applied to the document that represents the item.
generate(), we simply call our helper function:
The script is now functional but does not display an icon and only creates one single square with a fixed size.
Save the modified script file and then drag-n-drop the script item from the library browser into the drawing area.
When moving the mouse cursor inside the drawing area, a square with a size of 10 drawing units is shown. Left-click to place the square somewhere in your drawing. Note that you may also specify a scale factor and rotation angle or flip the item in the options tool bar. These are standard operations available for all items that are being inserted, including dynamic items.
We now modify the script to create the full cut-out template for the cube:
For the user to enter script parameters, we need to define a user interface component (widget). We use Qt Designer to design the user interface for this widget. Qt Designer is available for free as part of the Qt SDK or Qt Creator: http://qt.nokia.com/downloads
The UI file must have the same name as the script file but with the extension
You may also want to add some labels to indicate to the user what is being defined where. In the end, the widget may for example look like this:
Save the UI file as "CubeCuttingOut.ui". If you don't have Qt Designer, you can find the file source at the bottom of this page.
The library browser will now display that user interface component whenever this script item is being inserted.
All the script item implementation has to do is to get the script parameters from the user interface component:
Save the script file again, and insert the script item from the library browser into your drawing. The cut-out template is still drawn with a size of 10. As soon as you enter a different value in the user interface component, the cut-out template is drawn with that size.
The script item parameter Draw plates can be handled in the same way:
Finally, we provide a script preview that is shown as icon in the library browser. For that, we simply set some appropriate default values as script item parameters and call our helper function.
The library browser icons are updated on every start of QCAD. You can also right-click on a directory in the 'File System' tab and choose Regenerate Icons to rebuild the icons in that directory.