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

Draft: update description of draftviewproviders package

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

59
src/Mod/Draft/draftviewproviders/README.md
View File

@@ -1,25 +1,50 @@
2020 February
2020 May
These files define the view provider classes of the "scripted objects"
defined by the workbench. These scripted objects are originally
defined in the big `Draft.py` file.
These files define the viewprovider classes for "scripted objects"
defined within the workbench. The corresponding proxy object classes
should be defined in the modules in `draftobjects/`.
Each scripted object has a creation command like `make_arc`,
a proxy class like `Arc`, and a view provider like `ViewProviderArc`.
The view providers define the code that indicates how they are displayed
in the tree view and in the 3D view, and visual properties
such as line thickness, line color, face color, and transparency.
These properties are only available when the graphical interface exists,
otherwise they are ignored.
Each scripted object in `draftobjects/` should import its corresponding
view provider from this directory as long the graphical interface
Each scripted object has a creation function like `make_rectangle`,
a proxy class like `Rectangle`, and a viewprovider class
like `ViewProviderRectangle`.
The view providers define how they are displayed in the tree view
and in the 3D view, that is, visual properties such as line thickness,
line color, face color, and transparency.
These properties are only available when the graphical interface is loaded;
in a console only session, these properties cannot be read nor set.
These properties aren't very "real" because they don't affect the actual
geometrical shape of the object.
Each make function in `draftmake/` should import its corresponding
viewprovider from this package in order to set the visual properties
of the new scripted object, as long the graphical interface
is available.
These modules should be split from the big `Draft.py` module.
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
At the moment the files in this directory aren't really used,
but are used as placeholders for when the migration of classes happens.
new_obj = App.ActiveDocument.addObject("Part::Part2DObjectPython", "New")
if App.GuiUp:
Draft.ViewProviderRectangle(new_obj.ViewObject)
# Subclass
class NewViewProvider(Draft.ViewProviderRectangle):
...
```
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/draftviewproviders/__init__.py
View File

@@ -1,7 +1,56 @@
"""Classes that define the viewproviders of 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 viewproviders for scripted objects.
These classes define viewproviders for the custom objects
defined in `draftobjects`.
The viewproviders can be used only when the graphical interface
is available; in console mode the viewproviders are not available.
defined in the `draftobjects` package.
They extend the basic viewprovider that is installed by default
with the creation of a base object defined in C++.
These classes are not normally used by themselves, but are used at creation
time by the make functions defined in the `draftmake` package.
These viewproviders are installed only when the graphical interface
is available; in console-only mode the viewproviders are not available
so the make functions ignore them.
Similar to the object classes, once a viewprovider class is assigned
to an object, and it is saved in a document, the object's viewprovider
will be rebuilt with the same class every time the document
is opened. In order to do this, the viewprovider module must exist
with the same name as when the object was saved.
For example, when creating a `Rectangle`, the object uses
the `draftviewproviders.view_rectangle.ViewProviderRectangle` 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.ViewProviderRectangle = new_module.ViewProviderRectangle
"""