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

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

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

def create_docking_points(build_ele: BuildingElement,
                          doc      : AllplanElementAdapter.DocumentAdapter) -> typing.Tuple[typing.List[typing.Tuple[str, AllplanGeometry.Point3D]],
                                                                                            typing.List[typing.Tuple[str, AllplanGeometry.Point3D]],
                                                                                            typing.List[typing.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

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

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

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

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

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.