diff --git a/src/Mod/Draft/CMakeLists.txt b/src/Mod/Draft/CMakeLists.txt index 5b7ddd597544..e53eab9e95cc 100644 --- a/src/Mod/Draft/CMakeLists.txt +++ b/src/Mod/Draft/CMakeLists.txt @@ -95,6 +95,7 @@ SET(Draft_make_functions draftmake/make_sketch.py draftmake/make_wire.py draftmake/make_wpproxy.py + draftmake/README.md ) SET(Draft_objects diff --git a/src/Mod/Draft/draftmake/README.md b/src/Mod/Draft/draftmake/README.md new file mode 100644 index 000000000000..de3e65e18b23 --- /dev/null +++ b/src/Mod/Draft/draftmake/README.md @@ -0,0 +1,38 @@ +2020 May + +These modules contain the basic functions to create custom "scripted objects" +defined within the workbench. + +Each scripted object has a "make function" like `make_rectangle`, +a proxy class like `Rectangle`, and a viewprovider class +like `ViewProviderRectangle`. +Each make function should import the two corresponding classes +in order to create a new object with the correct data +and visual properties for that object. +These classes should be defined in the modules in `draftobjects/` +and `draftviewproviders/`. + +The make functions can be used in both graphical and non-graphical +modes (terminal only); in the latter case the viewprovider is not used. +The functions are also used internally by the graphical "GuiCommands" +(buttons, menu actions) defined in the modules in `draftguitools/` +and `drafttaskpanels/`. + +These make functions were previously defined in the `Draft.py` module, +which was very large. Now `Draft.py` just loads the individual modules +in order to provide these functions under the `Draft` namespace. + +```py +import Draft + +new_obj1 = Draft.make_rectangle(...) +new_obj2 = Draft.make_circle(...) +new_obj3 = Draft.make_line(...) +``` + +The functions in the `Draft` namespace are considered to be the public +application programming interface (API) of the workbench, and should be +usable in scripts, macros, and other workbenches. + +For more information see the thread: +[[Discussion] Splitting Draft tools into their own modules](https://forum.freecadweb.org/viewtopic.php?f=23&t=38593&start=10#p341298) diff --git a/src/Mod/Draft/draftmake/__init__.py b/src/Mod/Draft/draftmake/__init__.py index 00f44a9d207a..feb853371994 100644 --- a/src/Mod/Draft/draftmake/__init__.py +++ b/src/Mod/Draft/draftmake/__init__.py @@ -1,3 +1,82 @@ -"""Functions that to create custom scripted Draft objects. +# *************************************************************************** +# * (c) 2020 Carlo Pavan * +# * (c) 2020 Eliud Cabrera Castillo * +# * * +# * This file is part of the FreeCAD CAx development system. * +# * * +# * This program is free software; you can redistribute it and/or modify * +# * it under the terms of the GNU Lesser General Public License (LGPL) * +# * as published by the Free Software Foundation; either version 2 of * +# * the License, or (at your option) any later version. * +# * for detail see the LICENCE text file. * +# * * +# * FreeCAD is distributed in the hope that it will be useful, * +# * but WITHOUT ANY WARRANTY; without even the implied warranty of * +# * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the * +# * GNU Library General Public License for more details. * +# * * +# * You should have received a copy of the GNU Library General Public * +# * License along with FreeCAD; if not, write to the Free Software * +# * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 * +# * USA * +# * * +# *************************************************************************** +"""Modules that contain functions to create custom scripted objects. +These functions represent the basic application programming interface (API) +of the Draft Workbench to create custom objects. + +These functions first create a simple, extensible object defined in C++, +for example, `Part::FeaturePython` or `Part::Part2DObjectPython`, +and then assign a custom proxy class to define its data properties, +and a custom viewprovider class to define its visual properties. + +The proxy class is imported from `draftobjects` and the corresponding +viewprovider from `draftviewproviders`. + +:: + + import FreeCAD as App + import draftobjects.my_obj as my_obj + import draftviewproviders.view_my_obj as view_my_obj + + def make_function(input_data): + doc = App.ActiveDocument + new_obj = doc.addObject("Part::Part2DObjectPython", + "New_obj") + my_obj.Obj(new_obj) + + if App.GuiUp: + view_my_obj.ViewProviderObj(new_obj.ViewObject) + + return new_obj + +Assigning the viewprovider class is only possible if the graphical interface +is available. In a terminal-only session the viewproviders are not accessible +because the `ViewObject` attribute does not exist. + +If an object is created and saved in a console-only session, +the object will not have the custom viewprovider when the file is opened +in the GUI version of the program; it will only have a basic viewprovider +associated to the base C++ object. + +If needed, the custom viewprovider can be assigned after opening +the GUI version of the program; then the object will have access +to additional visual properties. + +:: + + import Draft + Draft.ViewProviderDraft(new_obj.ViewObject) + +Most Draft objects are based on two base `Part` objects +that are able to handle a `Part::TopoShape`. + +- `Part::Part2DObjectPython` if they should handle only 2D shapes, and +- `Part::FeaturePython` if they should handle any type of shape (2D or 3D). + +Generic objects that don't need to handle shapes but which +can have other properties like `App::PropertyPlacement`, +or which can interact with the 3D view through Coin, +can be based on the simple `App::FeaturePython` object. """