kindred/create
1
1
Fork 0
Code Issues 37 Pull Requests Actions Packages Projects 9 Releases 2 Wiki Activity

Draft: update description of draftobjects package

Browse Source
This commit is contained in:
vocx-fc
2020-05-01 22:21:30 -05:00
committed by Yorik van Havre
parent ef7e30c653
commit f1398c3207
2 changed files with 87 additions and 17 deletions
Download Patch File Download Diff File Expand all files Collapse all files

47
src/Mod/Draft/draftobjects/README.md
View File

@@ -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)

57
src/Mod/Draft/draftobjects/__init__.py
View File

@@ -1,8 +1,55 @@
"""Functions and classes that define custom scripted objects.
# ***************************************************************************
# * (c) 2020 Carlo Pavan <carlopav@gmail.com> *
# * (c) 2020 Eliud Cabrera Castillo <e.cabrera-castillo@tum.de> *
# * *
# * 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
"""