FreeCAD

1
# ***************************************************************************
2
# *   (c) 2020 Carlo Pavan <carlopav@gmail.com>                             *
3
# *   (c) 2020 Eliud Cabrera Castillo <e.cabrera-castillo@tum.de>           *
4
# *                                                                         *
5
# *   This file is part of the FreeCAD CAx development system.              *
6
# *                                                                         *
7
# *   This program is free software; you can redistribute it and/or modify  *
8
# *   it under the terms of the GNU Lesser General Public License (LGPL)    *
9
# *   as published by the Free Software Foundation; either version 2 of     *
10
# *   the License, or (at your option) any later version.                   *
11
# *   for detail see the LICENCE text file.                                 *
12
# *                                                                         *
13
# *   FreeCAD is distributed in the hope that it will be useful,            *
14
# *   but WITHOUT ANY WARRANTY; without even the implied warranty of        *
15
# *   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the         *
16
# *   GNU Library General Public License for more details.                  *
17
# *                                                                         *
18
# *   You should have received a copy of the GNU Library General Public     *
19
# *   License along with FreeCAD; if not, write to the Free Software        *
20
# *   Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  *
21
# *   USA                                                                   *
22
# *                                                                         *
23
# ***************************************************************************
24
"""Modules that contain functions to create custom scripted objects.
25

26
These functions represent the basic application programming interface (API)
27
of the Draft Workbench to create custom objects.
28

29
These functions first create a simple, extensible object defined in C++,
30
for example, `Part::FeaturePython` or `Part::Part2DObjectPython`,
31
and then assign a custom proxy class to define its data properties,
32
and a custom viewprovider class to define its visual properties.
33

34
The proxy class is imported from `draftobjects` and the corresponding
35
viewprovider from `draftviewproviders`.
36

37
::
38

39
    import FreeCAD as App
40
    import draftobjects.my_obj as my_obj
41
    import draftviewproviders.view_my_obj as view_my_obj
42

43
    def make_function(input_data):
44
        doc = App.ActiveDocument
45
        new_obj = doc.addObject("Part::Part2DObjectPython",
46
                                "New_obj")
47
        my_obj.Obj(new_obj)
48

49
        if App.GuiUp:
50
            view_my_obj.ViewProviderObj(new_obj.ViewObject)
51

52
        return new_obj
53

54
Assigning the viewprovider class is only possible if the graphical interface
55
is available. In a terminal-only session the viewproviders are not accessible
56
because the `ViewObject` attribute does not exist.
57

58
If an object is created and saved in a console-only session,
59
the object will not have the custom viewprovider when the file is opened
60
in the GUI version of the program; it will only have a basic viewprovider
61
associated to the base C++ object.
62

63
If needed, the custom viewprovider can be assigned after opening
64
the GUI version of the program; then the object will have access
65
to additional visual properties.
66

67
::
68

69
    import Draft
70
    Draft.ViewProviderDraft(new_obj.ViewObject)
71

72
Most Draft objects are based on two base `Part` objects
73
that are able to handle a `Part::TopoShape`.
74

75
- `Part::Part2DObjectPython` if they should handle only 2D shapes, and
76
- `Part::FeaturePython` if they should handle any type of shape (2D or 3D).
77

78
Generic objects that don't need to handle shapes but which
79
can have other properties like `App::PropertyPlacement`,
80
or which can interact with the 3D view through Coin,
81
can be based on the simple `App::FeaturePython` object.
82
"""
83
## \defgroup draftmake draftmake
84
# \ingroup DRAFT
85
# \brief Modules with functions to create the custom scripted objects.
86