Skip to content

Standard PythonPart

There are two possible ways how to create the Python source code for a PythonPart. A standard PythonPart is one of them. In a PythonPart like this, the entire workflow is managed via the input in the property palette. That means only the parameters provided in the property palette can be used for creating an object and no user input, such as object selection or coordinate input is possible. This may limit the possibilities, but it also makes the script structure much easier, as you only need to implement two functions. Tasks like handle creation, opening the palette or creating a preview object are managed by the PythonParts Framework.

To get a full control over the workflow, you must create an Interactor PythonPart

Required functions

The Python source code in the .py file must contain at least these two functions:

  • check_allplan_version - this function must always be implemented to check, whether the current Allplan version is supported by the script. Even if your script supports all versions, it always always return True, but it must be implemented.
  • create_element - the function for the actual creation of the model objects.

check_allplan_version(build_ele, version)

Called when the PythonPart is started to check, if the current Allplan version is supported.

Parameters:

Name Type Description Default
build_ele BuildingElement

building element with the parameter properties

 required
version float

current Allplan version

 required

Returns:

Type Description
bool

True if current Allplan version is supported and PythonPart script can be run, False otherwise
Source code in src\PythonPartsScriptTemplates\StandardPythonPart.py 
16
17
18
19
20
21
22
23
24
25
26
27
28
29
def check_allplan_version(build_ele: BuildingElement,
                          version:   float) -> bool:
    """Called when the PythonPart is started to check, if the current
    Allplan version is supported.

    Args:
        build_ele: building element with the parameter properties
        version:   current Allplan version

    Returns:
        True if current Allplan version is supported and PythonPart script can be run, False otherwise
    """

    return True

create_element(build_ele, doc)

Function for the element creation

Parameters:

Name Type Description Default
build_ele BuildingElement

the building element.

 required
doc DocumentAdapter

input document

 required

Returns:

Type Description
CreateElementResult

created element result
Source code in src\PythonPartsScriptTemplates\StandardPythonPart.py 
174
175
176
177
178
179
180
181
182
183
184
185
186
def create_element(build_ele:   BuildingElement,
                   doc:         AllplanElementAdapter.DocumentAdapter) -> CreateElementResult:
    """Function for the element creation

    Args:
        build_ele: the building element.
        doc:       input document

    Returns:
        created element result
    """

    return CreateElementResult()

Info

In some old examples you might see that the create_element function returns a two-element tuple, consisting of model_elements_list and handle_list. Although it works, we recommend returning the data class CreateElementResult. It is a container holding the created objects, but offers extra options like:

  • multi placement - enabling the user to place multiple instances of the PythonPart in one step,
  • global placement point - place the PythonPart in specified point instead of letting the user to place it.

Optional functions

When the geometry of the PythonPart is dynamic, implementation of the function create_docking_points might be necessary. Learn more in the chapter docking points

create_docking_points(build_ele, doc)

Parameters:

Name Type Description Default
build_ele BuildingElement

building element with the parameter properties

 required
doc DocumentAdapter

document of the Allplan drawing files

 required

Returns:

Type Description
List[Tuple[str, Point3D]]

list of tuples (key, docking_point) for the 2D view
List[Tuple[str, Point3D]]

list of tuples (key, docking_point) for the 3D view
List[Tuple[str, Point3D]]

list of tuples (key, docking_point) for the 2D and 3D view
Source code in src\PythonPartsScriptTemplates\StandardPythonPart.py 
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
def create_docking_points(build_ele: BuildingElement,
                          doc      : AllplanElementAdapter.DocumentAdapter) -> Tuple[List[Tuple[str, AllplanGeometry.Point3D]],
                                                                                     List[Tuple[str, AllplanGeometry.Point3D]],
                                                                                     List[Tuple[str, AllplanGeometry.Point3D]]]:
    """ Creation of the docking points

    Args:
        build_ele: building element with the parameter properties
        doc:       document of the Allplan drawing files

    Returns:
        list of tuples (key, docking_point) for the 2D view
        list of tuples (key, docking_point) for the 3D view
        list of tuples (key, docking_point) for the 2D and 3D view
    """

    return ...

If the layout of the property palette must be created dynamically, it can be implemented with the functions:

  • initialize_control_properties
  • modify_control_properties

The modification of the control properties can be done using ctrl_prop_util, which is a ControlPropertiesUtil object. Learn more about dynamic layout of a property palette in this chapter

initialize_control_properties(build_ele, ctrl_prop_util, doc)

Called after the properties and their values are read, but before the property palette is displayed.

Parameters:

Name Type Description Default
build_ele BuildingElement

building element

 required
ctrl_prop_util ControlPropertiesUtil

control properties utility

 required
doc DocumentAdapter

document

 required
Source code in src\PythonPartsScriptTemplates\StandardPythonPart.py 
106
107
108
109
110
111
112
113
114
115
116
def initialize_control_properties(build_ele:        BuildingElement,
                                  ctrl_prop_util:   ControlPropertiesUtil,
                                  doc:              AllplanElementAdapter.DocumentAdapter) -> None:
    """Called after the properties and their values are read, but before
    the property palette is displayed.

    Args:
        build_ele:      building element
        ctrl_prop_util: control properties utility
        doc:            document
    """

modify_control_properties(build_ele, ctrl_prop_util, value_name, event_id, doc)

Called after each change within the property palette

Parameters:

Name Type Description Default
build_ele BuildingElement

building element

 required
ctrl_prop_util ControlPropertiesUtil

control properties utility

 required
value_name str

name(s) of the modified value (multiple names are separated by ,)

 required
event_id int

event ID

 required
doc DocumentAdapter

document

 required

Returns:

Type Description
bool

True if an update of the property palette is necessary, False otherwise
Source code in src\PythonPartsScriptTemplates\StandardPythonPart.py 
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
def modify_control_properties(build_ele:        BuildingElement,
                              ctrl_prop_util:   ControlPropertiesUtil,
                              value_name:       str,
                              event_id:         int,
                              doc:              AllplanElementAdapter.DocumentAdapter) -> bool:
    """Called after each change within the property palette

    Args:
        build_ele:      building element
        ctrl_prop_util: control properties utility
        value_name:     name(s) of the modified value (multiple names are separated by ,)
        event_id:       event ID
        doc:            document

    Returns:
        True if an update of the property palette is necessary, False otherwise
    """

    return True

Use case

Changing the background color of the property input control to indicate an invalid input based on conditions, which cannot be implemented directly in the .pyp file

When handles are used in the PythonPart, the function move_handle must be implemented to process the event of modifying the PythonPart with a handle. See the chapter Handles in Standard PythonPart to learn more.

move_handle(build_ele, handle_prop, input_pnt, doc)

Parameters:

Name Type Description Default
build_ele BuildingElement

building element with the parameter properties

 required
handle_prop HandleProperties

handle properties

 required
input_pnt Point3D

input point

 required
doc DocumentAdapter

input document

 required

Returns:

Type Description
CreateElementResult

Object with the result data of the element creation
Source code in src\PythonPartsScriptTemplates\StandardPythonPart.py 
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
def move_handle(build_ele:      BuildingElement,
                handle_prop:    HandleProperties,
                input_pnt:      AllplanGeometry.Point3D,
                doc:            AllplanElementAdapter.DocumentAdapter) -> CreateElementResult:
    """Called after modification of the element geometry using handles

    Args:
        build_ele:      building element with the parameter properties
        handle_prop:    handle properties
        input_pnt:      input point
        doc:            input document

    Returns:
        Object with the result data of the element creation

    """
    HandlePropertiesService.update_property_value(build_ele, handle_prop, input_pnt)

    return create_element(build_ele, doc)

To control the behavior of your PythonPart depending on the currently displayed page of the property palette, implement the function set_active_palette_page_index into your script.

set_active_palette_page_index(active_page_index)

Parameters:

Name Type Description Default
active_page_index int

index of the active page, starting from 0

 required
Source code in src\PythonPartsScriptTemplates\StandardPythonPart.py 
140
141
142
143
144
145
def set_active_palette_page_index(active_page_index: int) -> None:
    """ Called when changing page in the property palette

    Args:
        active_page_index: index of the active page, starting from 0
    """

Use case

  • Display only the relevant handles depending on which property palette page is active. Especially useful when the geometry requires a high number of handles, making the PythonPart illegible when displaing them all at once.
  • generate different preview geometry based on the active page

To create elements, which should be displayed in the Allplan library as a preview, implement the function create_preview into your script. See the chapter Library preview to learn more about creating preview in the Allplan library.

create_preview(build_ele, doc)

Parameters:

Name Type Description Default
build_ele BuildingElement

the building element.

 required
doc DocumentAdapter

input document

 required

Returns:

Type Description
CreateElementResult

Preview elements. Only elements included in the property "elements" will be shown in the library preview
Source code in src\PythonPartsScriptTemplates\StandardPythonPart.py 
159
160
161
162
163
164
165
166
167
168
169
170
171
def create_preview(build_ele: BuildingElement,
                   doc: AllplanElementAdapter.DocumentAdapter) -> CreateElementResult:
    """Function for the creation of the library preview elements.

    Args:
        build_ele: the building element.
        doc:       input document

    Returns:
        Preview elements. Only elements included in the property "elements" will be shown in the library preview
    """

    return CreateElementResult(elements=[...])

Info

If the function create_preview is missing in the script, the framework will try to get the elements from the create_elements function.