diff --git a/src/Mod/Draft/draftobjects/README.md b/src/Mod/Draft/draftobjects/README.md index ebe8650694..67d065516d 100644 --- a/src/Mod/Draft/draftobjects/README.md +++ b/src/Mod/Draft/draftobjects/README.md @@ -1,20 +1,43 @@ -2020 February +2020 May -These files define modules to create specific "scripted objects" -from the terminal, that is, without requiring the graphical interface. -They define both a creation command such as `make_arc`, and the corresponding -proxy class, such as `Arc`. The corresponding view provider class +These files define the proxy classes for "scripted objects" +defined within the workbench. The corresponding viewprovider classes should be defined in the modules in `draftviewproviders/`. -These modules should be split from the big `Draft.py` module. +Each scripted object has a creation function like `make_rectangle`, +a proxy class like `Rectangle`, and a viewprovider class +like `ViewProviderRectangle`. +The proxy classes define the code that manipulates the internal properties +of the objects, determining how the internal shape is calculated. +These properties are "real" information because they affect the actual +geometrical shape of the object. +Each make function in `draftmake/` should import its corresponding +proxy class from this package in order to build the new scripted object. -At the moment the files in this directory aren't really used, -but are used as placeholders for when the migration of classes and functions -happens. +These classes were previously defined in the `Draft.py` module, +which was very large. Now `Draft.py` is an auxiliary module +which just loads the individual classes in order to provide backwards +compatibility for older files. +Other workbenches can import these classes for their own use, +including creating derived classes. +```py +import Draft -The creation functions should be used internally by the "GuiCommands" -defined in `DraftTools.py` or in the newer modules under `draftguitools/` -and `drafttaskpanels/`. +new_obj = App.ActiveDocument.addObject("Part::Part2DObjectPython", "New") +Draft.Rectangle(new_obj) + + +# Subclass +class NewObject(Draft.Rectangle): + ... +``` + +As the scripted objects are rebuilt every time a document is loaded, +this means that, in general, these modules cannot be renamed +without risking breaking previously saved files. They can be renamed +only if the old class can be migrated to point to a new class, +for example, by creating a reference to the new class named the same +as the older class. 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/draftobjects/__init__.py b/src/Mod/Draft/draftobjects/__init__.py index 418915c82b..d273235673 100644 --- a/src/Mod/Draft/draftobjects/__init__.py +++ b/src/Mod/Draft/draftobjects/__init__.py @@ -1,8 +1,55 @@ -"""Functions and classes that define custom scripted 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 classes that define custom scripted objects. -These classes define a custom object which is based on one of the core -objects defined in C++. The custom object inherits some basic properties, -and new properties are added. +These proxy classes are used to extend one of the core classes +defined in C++, for example, `Part::FeaturePython` +or `Part::Part2DObjectPython`, thus creating a custom object type +tied to a Python class. +A new object that uses one of these classes inherits some basic properties +from the parent C++ class, and new properties and behavior +are added by the Python class. -Most Draft objects are based on Part::Part2DObject. +These classes are not normally used by themselves, but are used at creation +time by the make functions defined in the `draftmake` package. + +Once an object is assigned one of these proxy classes, and it is saved +in a document, the object will be rebuilt with the same class every time +the document is opened. In order to do this, the object module must exist +with the same name as when the object was saved. + +For example, when creating a `Rectangle`, the object uses +the `draftobjects.rectangle.Rectangle` class. This class must exist +when the document is opened again. + +This means that, in general, these modules cannot be renamed or moved +without risking breaking previously saved files. They can be renamed +only if the old class can be migrated to point to a new class, +for example, by creating a reference to the new class named the same +as the older class. + +:: + + old_module.Rectangle = new_module.Rectangle """