Skip to content

Standard PythonPart

In a standard PythonPart the entire workflow consists of two steps:

  • input of the parameters in the property palette
  • placing the element in the model

This means that only the parameters provided in the property palette influence the final element. The workflow is already implemented in the PythonParts framework, meaning that you don't need to implement it entirely, just a function for the element creation. This also means, that additional input steps, such as object selection or coordinate input, cannot be introduced. This limits the possibilities, but requires only two functions to be implemented (see required functions below). Tasks like handle creation, showing the palette or creating a preview are managed entirely by the framework.

Beside the creation of the element, you can handle other events, by implementing optional functions, e.g. when the user modifies a certain property in the property palette.

Required functions

  • check_allplan_version

    This function is called at the very beginning to check, whether the PythonPart can be started in the current ALLPLAN version. You can prevent the user for starting the PythonPart in an older ALLPLAN version. You must implement it, even if your script supports all versions.

  • create_element

    Here you implement the creation of the elements. The input, framework gives you as arguments, is a.o. the BuildingElement, containing all the parameter values from the property palette. You can refer to them as shown here. The output should be the elements, you want to create, put into a data class CreateElementResult

check_allplan_version 

check_allplan_version(build_ele: BuildingElement, version: float) -> bool

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

Parameters:

  • build_ele (BuildingElement) –

    building element with the parameter properties

  • version (float) –

    current Allplan version

Returns:

  • 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
Example

To allow the user to open your script with ALLPLAN 2025 only, you can implement it like this:

def check_allplan_version(_build_ele, version: float) -> bool:
    return float(version) >= 2025.0

create_element 

create_element(
    build_ele: BuildingElement, doc: DocumentAdapter
) -> CreateElementResult

Function for the element creation

Parameters:

Returns:

Source code in src\PythonPartsScriptTemplates\StandardPythonPart.py 
191
192
193
194
195
196
197
198
199
200
201
202
203
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()
Example

To create a 3D element, being a simple cube, you can implement it like this:

import NemAll_Python_Geometry as AllplanGeometry
from CreateElementResult import CreateElementResult
from TypeCollections.ModelEleList import ModelEleList

def create_element(_build_ele, _doc):

    cube = AllplanGeometry.Polyhedron3D.CreateCuboid(length = 1000.0,
                                                     width  = 1000.0, 
                                                     height = 1000.0)
    elements = ModelEleList()
    elements.append_geometry_3d(cube)

    return CreateElementResult(elements)

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

Implementing additional functions allows you to handle other events. For example, if you want to introduce some steps before the palette is being shown (like reading data from an external CSV file), or when a button is pressed in the palette.

Here is an overview of the functions that framework may call from your script, together with the description when these functions are called. Implementing them is either entirely optional, or required by an optional feature.

  • initialize_control_properties

    Implement it to introduce some actions before the property palette is shown. For example to read some data from an external file, in order to show it in the property palette.

  • modify_control_properties

    Implement it, if you want to react to the event of the user modifying the values in the property palette. This allows you to make it more responsive and dynamic. Learn more about making the palette dynamic in this chapter

  • on_control_event

    Implement it, if you want to introduce an action triggered by pressing a button on the property palette.

  • create_docking_points

    The implementation of this function is necessary only in case, when the PythonPart should have the docking points feature

  • move_handle

    Implementing this function makes sense only, when your PythonPart uses handles. It allows you to react to the event of a handle being modified by the user.

  • set_active_palette_page_index

    To control the behavior of your PythonPart depending on the currently displayed page of the property palette, implement the function into your script. You may want to show different objects in the preview or only selected handles, depending on what palette page is currently active.

  • create_preview

    By default, the preview in the library is generated by calling the create_element function with default parameter values and displaying the resulting elements. You can override this, by implementing this function and create different elements for the library preview.

  • migrate_parameter

    When you released a new version of your PythonPart and you have changed e.g. the parameter names, implementing this function might be necessary to migrate the old parameters to the new structure and ensure the seamless work when with already placed PythonParts in the modification mode.

create_docking_points 

create_docking_points(
    build_ele: BuildingElement, doc: DocumentAdapter
) -> Tuple[
    List[Tuple[str, Point3D]],
    List[Tuple[str, Point3D]],
    List[Tuple[str, Point3D]],
]

Creation of the docking points

Parameters:

Returns:

  • 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 
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
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 ...

initialize_control_properties 

initialize_control_properties(
    build_ele: BuildingElement,
    ctrl_prop_util: ControlPropertiesUtil,
    doc: DocumentAdapter,
) -> None

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

Parameters:

Source code in src\PythonPartsScriptTemplates\StandardPythonPart.py 
119
120
121
122
123
124
125
126
127
128
129
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 

modify_control_properties(
    build_ele: BuildingElement,
    ctrl_prop_util: ControlPropertiesUtil,
    value_name: str,
    event_id: int,
    doc: DocumentAdapter,
) -> bool

Called after each change within the property palette

Parameters:

  • build_ele (BuildingElement) –

    building element

  • ctrl_prop_util (ControlPropertiesUtil) –

    control properties utility

  • value_name (str) –

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

  • event_id (int) –

    event ID

  • doc (DocumentAdapter) –

    document

Returns:

  • bool –

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

Source code in src\PythonPartsScriptTemplates\StandardPythonPart.py 
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
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

on_control_event 

on_control_event(
    build_ele: BuildingElement, event_id: int, doc: DocumentAdapter
) -> bool

Called, when an event is triggered with a control (e.g. a button) in a property palette

Parameters:

  • build_ele (BuildingElement) –

    building element with the parameter properties

  • event_id (int) –

    event id of the triggered control

  • doc (DocumentAdapter) –

    document of the Allplan drawing files

Returns:

  • bool –

    True if palette refresh is necessary, False otherwise

Source code in src\PythonPartsScriptTemplates\StandardPythonPart.py 
161
162
163
164
165
166
167
168
169
170
171
172
173
def on_control_event(build_ele: BuildingElement,
                     event_id: int,
                     doc: AllplanElementAdapter.DocumentAdapter) -> bool:
    """ Called, when an event is triggered with a control (e.g. a button) in a property palette

    Args:
        build_ele: building element with the parameter properties
        event_id:  event id of the triggered control
        doc:       document of the Allplan drawing files

    Returns:
        True if palette refresh is necessary, False otherwise
    """

move_handle 

move_handle(
    build_ele: BuildingElement,
    handle_prop: HandleProperties,
    input_pnt: Point3D,
    doc: DocumentAdapter,
) -> CreateElementResult

Called after modification of the element geometry using handles

Parameters:

Returns:

Source code in src\PythonPartsScriptTemplates\StandardPythonPart.py 
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
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)

set_active_palette_page_index 

set_active_palette_page_index(active_page_index: int) -> None

Parameters:

  • active_page_index (int) –

    index of the active page, starting from 0

Source code in src\PythonPartsScriptTemplates\StandardPythonPart.py 
153
154
155
156
157
158
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
    """

create_preview 

create_preview(
    build_ele: BuildingElement, doc: DocumentAdapter
) -> CreateElementResult

Function for the creation of the library preview elements.

Parameters:

Returns:

  • CreateElementResult –

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

Source code in src\PythonPartsScriptTemplates\StandardPythonPart.py 
176
177
178
179
180
181
182
183
184
185
186
187
188
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=[...])

migrate_parameter 

migrate_parameter(parameter_list: list, version: float) -> None

Migrate the parameter

This function is called only during the modification of a PythonPart

Parameters:

  • parameter_list (list) –

    parameter list

  • version (float) –

    current PythonPart version

Source code in src\PythonPartsScriptTemplates\StandardPythonPart.py 
32
33
34
35
36
37
38
39
40
41
def migrate_parameter(parameter_list: list,
                      version: float) -> None:
    """Migrate the parameter

    This function is called only during the modification of a PythonPart

    Args:
        parameter_list: parameter list
        version:        current PythonPart version
    """
Placeholder