Handles

Abstract

Handles are a way of parameter input. Instead of typing the length, the user is grabbing a handle in the viewport and moves it to the desired position. The parameter value is calculated for him based on this new position (e.g. length of the box).
A handle can introduce an action. In this case, it behaves like a button.
You as a PythonPart developer need to define a handle and process the event of moving it

Handle

Handles allow the PythonPart user to input a parameter value directly in the viewport. For parameters, that directly affects the geometry of the created element (e.g. its length) this is a more intuitive way of input than typing a value in the property palette.

Common use-cases, that can be covered by a handle are:

changing dimensions with dimension handle
defining a coordinate with coordinate handle
executing an action with button handle
hiding or displaying a component with checkbox handle
increment a dimension with increment handle
changing an angle with rotation handle

A single handle one or more parameters. It consists if two elements: a handle (the blue circle the user can drag) and an input field. You can show/hide both elements independently.

Definition

Handle as a whole is represented by the class HandleProperties. A basic definition of a handle controlling the height if a cube may look like:

z_handle = HandleProperties(
    handle_id         = "HeightHandle",
    handle_point      = AllplanGeometry.Point3D(0,0, build_ele.Height.value),
    ref_point         = AllplanGeometry.Point3D(),
    handle_param_data = [HandleParameterData("Height", HandleParameterType.Z_DISTANCE)],
    handle_move_dir   = HandleDirection.Z_COORD)

In the above definition, here are the relevant points:

Handle point (Point3D) is where the handle is located.
Reference point (Point3D) is the anchor of the handle. The calculated parameter value is done based on the vector from reference point to handle point.
Handle parameter data (HandleParameterData) describes the connection between the handle and the parameter. In other words, how the value of the parameter should be calculated. A handle must be connected to one parameter, but can be connected to multiple parameters (see example coordinate handle). This is why handle_param_data is a list.
Handle direction (HandleDirection) defined the direction, in which the handle can be moved.
Handle type (ElementHandleType) defines the handle appearance (defaults to HANDLE_CIRCLE). Following layouts are possible:

Layout Type

HANDLE_ARROW

HANDLE_CIRCLE

HANDLE_SQUARE_BLUE

HANDLE_SQUARE_EMPTY

HANDLE_SQUARE_RED

HANDLE_SQUARE_RIGHT

After you define a handle append it to a regular Python list. You will need it later during handle processing .

handle_list = list[HandleProperties]()
handle_list.append(z_handle)

Tip

For typical cases, it's easier to use the helper utility HandleCreator to populate the list with HandleProperties objects representing your handles. Creating a handle like above looks like:

from Utils.HandleCreator import HandleCreator
...
handle_list = list[HandleProperties]()
HandleCreator.z_distance(
    handle_list  = handle_list,
    name         = "Height",
    handle_point = AllplanGeometry.Point3D(0,0, build_ele.Height.value),
    ref_point    = AllplanGeometry.Point3D())

In the following examples we show both ways: the classic and the simplified one.

The graph below shows the complete composition of the HandleProperties class and the role, that HandleCreator can have in the process of creating handles.

classDiagram
    direction BT

class Point3D {
    float X
    float Y
    float Z
}
class ElementHandleType{
    <<Enumeration>>
    HANDLE_ARROW
    HANDLE_CIRCLE
    HANDLE_SQUARE_BLUE
    HANDLE_SQUARE_EMPTY
    HANDLE_SQUARE_RED
    HANDLE_SQUARE_RIGHT
}
class HandleDirection{
    <<Enumeration>>
    X_DIR
    Y_DIR
    Z_DIR
    XY_DIR
    XZ_DIR
    YZ_DIR
    XYZ_DIR
    POINT_DIR
    ANGLE
    Z_COORD
    PLANE_DIR
    VECTOR_DIR
    CLICK
}
class HandleParameterType{
    <<Enumeration>>
    X_DISTANCE
    Y_DISTANCE
    Z_DISTANCE
    POINT
    POINT_DISTANCE
    ANGLE
    Z_COORD
    VECTOR_DISTANCE
    CHECK_BOX
    INCREMENT_BUTTON
    DECREMENT_BUTTON
}
class HandleParameterData{
    <<Dataclass>>
    +str param_prop_name
    +HandleParameterType param_type
}
class HandleProperties{
    +str handle_id
    +Point3D handle_point
    +Point3D ref_point
    +List[HandleParameterData] parameter_data
    +HandleDirection handle_move_dir
    +ElementHandleType handle_type
}

class HandleCreator{
    checkbox()
    click()
    point()
    x_distance()
    y_distance()
    z_distance()
}

class list

Point3D --o "2" HandleProperties
ElementHandleType --o "1" HandleProperties
HandleDirection --o "1" HandleProperties
HandleParameterData --o "1..*" HandleProperties
HandleParameterType --o "1" HandleParameterData
HandleProperties --* "*" list
HandleCreator ..> HandleProperties : creates
HandleCreator ..> list : populates

Examples

Dimension handle

To allow the user to input a single dimension (e.g. height) with a handle, first define a length parameter:

<Parameter>
    <Name>CubeHeight</Name>
    ...
    <ValueType>Length</ValueType>
</Parameter>

Then, in the script define the handle like:

using HandleCreatorclassic way

handle_list = list[HandleProperties]()

HandleCreator.z_distance(
    handle_list  = handle_list,
    name         = "CubeHeight", #(1)!
    handle_point = AllplanGeometry.Point3D(0,0, build_ele.Height.value),
    ref_point    = AllplanGeometry.Point3D())

It's enough to provide the parameter name to connect the handle to it

handle_list = list[HandleProperties]()

param_data = [
    HandleParameterData(
        param_prop_name = "CubeHeight",#(1)!
        param_type      = HandleParameterType.Z_DISTANCE)#(2)!
    ]

handle_height = HandleProperties(
    handle_id         = "HeightHandle",
    handle_point      = AllplanGeometry.Point3D(0, 0, build_ele.CubeHeight.value),
    ref_point         = AllplanGeometry.Point3D(),
    handle_param_data = param_data,
    handle_move_dir   = HandleDirection.Z_DIR) #(3)!

handle_list.append(handle_height)

The handle is connected here to the parameter CubeHeight
Only the Z component of the vector between reference point and handle point will be taken as the new value of the parameter CubeHeight.
The handle can only be moved in the local Z-direction of the PythonPart.

Coordinate handle

You can offer one handle to control multiple length parameters (e.g. width and height).

Assuming, the parameter names are CubeLength and CubeWidth and both are of value type Length, the handle can be defined as follows:

using HandleCreatorclassic way

handle_list = list[HandleProperties]()

HandleCreator.xy_distance(
    handle_list  = handle_list,
    x_name       = "CubeLength",    #(1)!
    y_name       = "CubeWidth",
    handle_point = AllplanGeometry.Point3D(
        x = build_ele.CubeLength.value,
        y = build_ele.CubeWidth.value,
        z = 0),
    ref_point    = AllplanGeometry.Point3D(),
    info_text    = "Ground view dimensions") #(2)!

It's enough to provide both parameter names to connect the handle to them.
You can add a tool tip, that will be shown when hovered over the handle.

handle_list = list[HandleProperties]()

xy_handle_parameter_data = [ #(1)!
    HandleParameterData(
        param_prop_name = "CubeLength",
        param_type      = HandleParameterType.X_DISTANCE,
        has_input_field = False), #(2)!

    HandleParameterData(
        param_prop_name = "CubeWidth",
        param_type      = HandleParameterType.Y_DISTANCE,
        has_input_field = False),
    ]

handle_length_width = HandleProperties(
    handle_id         = "LengthWidthHandle",
    handle_point      = AllplanGeometry.Point3D(
        x = build_ele.CubeLength.value,
        y = build_ele.CubeWidth.value,
        z = 0),
    ref_point         = AllplanGeometry.Point3D(),
    handle_param_data = xyz_handle_parameter_data,
    handle_move_dir   = HandleDirection.XY_DIR,
    info_text         = "Ground view dimensions" #(3)!
    )

handle_list.append(handle_length_width)

One handle should control two parameters hence the list has two entries.
In this case, hide the input field as it could be confusing.
You can add a tool tip, that will be shown when hovered over the handle

Click handle

Button handle

A handle can act like a button - a one time action can be introduced in case of clicking on it. Define it as follows:

using HandleCreatorclassic way

handle_list = list[HandleProperties]()

HandleCreator.click(
    handle_list  = handle_list,
    name         = "ActionHandle", #(1)!
    handle_point = AllplanGeometry.Point3D(
        x = build_ele.CubeLength.value/2, 
        y = build_ele.CubeWidth.value/2,
        z = build_ele.CubeHeight.value/2),
    handle_type  = AllplanIFW.ElementHandleType.HANDLE_SQUARE_BLUE, #(2)!
    info_text    = "Click me!")

Unlike in other cases, this is the handle id and not a name of any parameter in the PYP file. This kind of handle is not linked to any parameter, but it has to have an ID to be able to refer to it when introducing the action.
To distinguish the handle from others we recommend to use a square

handle_list = list[HandleProperties]()

action_handle = HandleProperties(
    handle_id    = "ActionHandle",
    handle_point = AllplanGeometry.Point3D(
        x = build_ele.CubeLength.value/2,
        y = build_ele.CubeWidth.value/2,
        z = build_ele.CubeHeight.value/2),
    ref_point         = AllplanGeometry.Point3D(),
    handle_param_data = [], #(1)!
    handle_move_dir   = HandleDirection.CLICK, #(2)!
    info_text         = "Click me!",
    )

action_handle.handle_type = AllplanIFW.ElementHandleType.HANDLE_SQUARE_BLUE #(3)!

handle_list.append(action_handle)

Handle does not control any parameter value, thus the list is empty
The handle cannot be moved.
To distinguish the handle from others we recommend changing its appearance

The action that should follow the click must be implemented in the move_handle() method/function like:

standard PythonPartscript object

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

    if handle_prop.handle_id == "ActionHandle": #(1)!
        # -------> implement your action here <--------
    else:
        HandlePropertiesService.update_property_value(build_ele, handle_prop, input_pnt)

    return create_element(build_ele, doc)

Catch the event by the ID of the clicked handle

def move_handle(self,
                handle_prop: HandleProperties,
                input_pnt:   AllplanGeometry.Point3D) -> CreateElementResult:

    if handle_prop.handle_id == "ActionHandle": #(1)!
        # -------> implement your action here <--------
    else:
        HandlePropertiesService.update_property_value(self.build_ele, handle_prop, input_pnt)

    return self.execute()

Catch the event by the ID of the clicked handle

Handle point list

List of points

When one of the parameters is a list of 3D points (e.g. controlling the outline of a polygon) defined like:

<Parameter>
    <Name>OutlinePoints</Name>
    <Text/>
    <Value>[Point3D(...); ...]<!--(1)!--></Value>
    <ValueType>Point3D</ValueType>
</Parameter>

For the upcoming code example keep in mind that this list is not closed (last point ≠ first point)!

using HandleCreatorclassic way

You can create the handles for all the points in the list like:

handle_list = list[HandleProperties]()

HandleCreator.point_list(
    handle_list        = handle_list,
    name               = "OutlinePoints",
    handle_points      = build_ele.OutlinePoints.value,
    info_text_template = Template("Shift + click = delete point $index"),#(1)!
    delete_point       = True) #(2)!

If you want to show the point index in the tool tip, use built-in python object Template with the placeholder $index. You can import it like:
```
from string import Template
```
This optional argument enables the user to delete the point from the list by holding Shift when clicking.

Tip

Add point handle

You can add handles, that allow the user to insert new points into the list, like on the gif to the right. You can do it with point_list_segment_center(), like:

closed_pnt_list = build_ele.OutlinePoints.value
closed_pnt_list.append(build_ele.OutlinePoints.value[0]) #(1)!

HandleCreator.point_list_segment_center(
    handle_list        = handle_list,
    name               = "OutlinePoints",
    handle_points      = closed_pnt_list,
    info_text_template = Template("Split segment $index"),
    index_offset       = 1)

In this example, the parameter OutlinePoints was defined as a list of points, where last point ≠ first point. For creating the handles, the list must be closed, so that the last segment of the polygon can also be split.

You can create handles (one for each point) like:

handle_list = list[HandleProperties]()

for idx, pnt in enumerate(build_ele.OutlinePoints.value): #(2)!
    handle_param_data = HandleParameterData(
        param_prop_name = "OutlinePoints",
        param_type      = HandleParameterType.POINT,
        has_input_field = False,
        list_index      = idx) #(1)!

    handle_list.append(HandleProperties(
        handle_id         = f"OutlinePoint{idx}",
        handle_point      = pnt,
        ref_point         = AllplanGeometry.Point3D(),
        handle_param_data = [handle_param_data],
        handle_move_dir   = HandleDirection.XYZ_DIR,
        info_text         = f"Point {idx + 1}"))

This argument is required, because OutlinePoints is a list. In case of one-dimensional list, it's an integer. For two-dimensional lists, it's a list like: [index_row, index_column].
One handle must be generated for each point.

Handle increment

Value decrement / increment

You can create a handle, that will only increase/decrease the value of the linked length parameter by a certain value, but not allow the user to move it freely.

In the example below, the parameter Length is defined like:

<Parameter>
    <Name>Length</Name>
    ...
    <ValueType>Length</ValueType>
    <IntervalValue>100</IntervalValue><!--(1)!-->
</Parameter>

It makes sense to add this tag to the parameter definition. Otherwise, the user could change the length freely in the palette.

using HandleCreatorclassic way

handle_list = list[HandleProperties]()

point = AllplanGeometry.Point3D(
    x = build_ele.Length.value,
    y = build_ele.Width.value,
    z = build_ele.Height.value)

HandleCreator.increment(
    handle_list     = handle_list,
    name            = "Length",
    handle_point    = point + AllplanGeometry.Point3D(200, 100, 0),
    increment_value = 100.)

HandleCreator.decrement(
    handle_list     = handle_list,
    name            = "Length",
    handle_point    = point + AllplanGeometry.Point3D(200, -100, 0),
    decrement_value = 100.)

handle_list = list[HandleProperties]()

point = AllplanGeometry.Point3D(
    x = build_ele.Length.value,
    y = build_ele.Width.value,
    z = build_ele.Height.value)

#---------- incrementation handle

increm_handle_param_data = [
    HandleParameterData(
        param_prop_name    = "Length",
        param_type         = HandleParameterType.INCREMENT_BUTTON,
        in_decrement_value = 100.)
    ]

handle_list.append(HandleProperties(
    handle_id         = "IncrementHandle",
    handle_point      = point + AllplanGeometry.Point3D(200, 100, 0),
    ref_point         = AllplanGeometry.Point3D(),
    handle_param_data = increm_handle_param_data,
    handle_move_dir   = HandleDirection.CLICK))

#---------- decrementation handle

decrem_handle_param_data = [
    HandleParameterData(
        param_prop_name    = "Length",
        param_type         = HandleParameterType.DECREMENT_BUTTON,
        in_decrement_value = 100.)
    ]

decrement_handle = HandleProperties(
    handle_id         = "DecrementHandle",
    handle_point      = point + AllplanGeometry.Point3D(200, -100, 0),
    ref_point         = AllplanGeometry.Point3D(),
    handle_param_data = decrem_handle_param_data,
    handle_move_dir   = HandleDirection.CLICK)

decrement_handle.handle_angle = AllplanGeometry.Angle.FromDeg(180)

handle_list.append(decrement_handle)

Rotation handle

To create a rotation handle and allow to rotate the elements as shown in the gif, first define an angle parameter. In this examples, the parameter name is set to Rotation.

Defining this type of handle in the script looks like:

Using HandleCreatorclassic way

handle_list = list[HandleProperties]()

HandleCreator.angle(
    handle_list     = handle_list,
    name            = "Rotation", #(1)!
    handle_point    = rotated_point, #(2)!
    ref_point       = AllplanGeometry.Point3D(),
    angle_placement = AllplanGeometry.AxisPlacement3D() #(3)!
    )

Provide the name of the parameter, you would like to affect with the handle.
Handle is drawn in this point. Make sure, it's the point after rotation.
The local coordinate system for the angle calculation is defined here. The angle is calculated between the local X-axis and a vector going from ref_point to handle_point projected on the local XY plane. In this case, the local system is defined equal to the global.

handle_list = list[HandleProperties]()

rot_handle_param_data = HandleParameterData(
    param_prop_name = "Rotation",
    param_type      = HandleParameterType.ANGLE)

handle_z_rot = HandleProperties(
    handle_id         = "Rotation",
    handle_point      = rotated_point, #(1)!
    ref_point         = AllplanGeometry.Point3D(), #(2)!
    handle_param_data = [rot_handle_param_data],
    handle_move_dir   = HandleDirection.ANGLE,
    abs_value         = True,
    info_text         = "Z rotation handle")

handle_list.append(handle_z_rot)

Handle is drawn in this point. Make sure, it's the point after rotation.

The angle is calculated between the local X-axis of the local coordinate system and a vector going from ref_point to handle_point projected on the XY local plane. The local coordinate system can defined in the argument angle_placement, like

angle_placement = AllplanGeo.AxisPlacement3D(AllplanGeo.Point3D(),
                                             AllplanGeo.Vector3D(1000, 0, 0),
                                             AllplanGeo.Vector3D(0, -1000, 0))

If not defined, local system equals the global one.

Example on GitHub

The full implementation of all the above mentioned handle types is shown in the example Handles ( PYP | PY).

Processing

In standard PythonPart

Creation

In order to create a standard PythonPart with handles, assign the handle_list you have populated according to the instructions above to the handles attribute of the CreateElementResult data class and return it in your create_element() function:

def create_element(build_ele, doc):
    ...
    return CreateElementResult(elements = model_elements_list,
                               handles =  handle_list)

Modification

After every handle modification, the new value of the property must be written back in the property palette and the element must be recreated. To handle this process, implement the function move_handle() in your script. Use the HandlePropertiesService to update the parameter values

Example

def move_handle(build_ele,
                handle_prop: HandleProperties,
                input_pnt:   NemAll_Python_Geometry.Point3D,
                doc:         NemAll_Python_IFW_ElementAdapter.DocumentAdapter):
    if handle_prop.handle_id == build_ele.MirrorCuboid.name: #(1)!
        build_ele.MirrorCuboid.value = not build_ele.MirrorCuboid.value

    else:
        HandlePropertiesService.update_property_value(build_ele, handle_prop, input_pnt) #(3)!

    return create_element(build_ele, doc) #(2)!

You can process a specific handle (in this case the MirrorCuboid handle) differently. as the framework gives the handle name to the move_handle() function.
The PythonPart must be recalculated with every movement of the handle.
For a standard case you just need to implement this line of code in the move_handle function. The update_property_value method updates the values in the property palette after the handle is modified.

In Script Object

In a script object, handle implementation looks similar to the one in a standard PythonPart (see above ). The differences:

Implement the creation in the execute() method.

def execute(self):
    ...
    return CreateElementResult(elements = model_elements_list,
                               handles  = handle_list)

Process the handle movement in the move_handle() method. It's called constantly when the handle is moved (not only once, after the modification). An example implementation may look like this:

def move_handle(self,
                handle_prop: HandleProperties,
                input_pnt  : AllplanGeo.Point3D) -> CreateElementResult:

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

    return self.execute()

In interactor

In an interactor, each mouse movement and mouse click has to be processed. The same applies to moving and clicking on a handle. The class for the job is HandleModificationService.

Here is a typical standard PythonPart workflow:

flowchart TB
    start((Start)) --> Placement["PLACEMENT"]
    Placement -- "Place PythonPart" --> Input["PARAMETER INPUT"]
    Input --"Grab 
             a handle"--> HandleMod["HANDLE MODIFICATION"]
    HandleMod --"Drop a 
                 handle" --> Input
    HandleMod --"Press ESC" --> Input
    Placement --"Press ESC"--> stop((stop))
    Input --"Press ESC"--> stop((stop))

Following instruction will guide you, how to implement it in an interactor and process the handles correctly.

There are three states, in which a PythonPart can find itself: Placement, Parameter input, and handle modification (see enumeration class InteractorInputMode). This is how you should implement these three states and the transition between them:

Start: At the very beginning (in the __init__()) start the HandleModificationService:

def __init__(...):
    self.handle_modi_service = HandleModificationService(coord_input, 
                                                         build_ele_list,
                                                         control_props_list)

PLACEMENT - now PythonPart follows the mouse cursor. Nothing to do here up to the point, when the user clicks to place the PythonPart. In this moment, handles must be shown. Call start() to do so:

def process_mouse_msg(self, mouse_msg, pnt, msg_info):

    if self.coord_input.IsMouseMove(mouse_msg):
        return True

    # code below this line is executed only when mouse is clicked
    if self.input_mode == self.InteractorInputMode.PLACEMENT:
        self.handle_modi_service.start(self.handles, #(2)!
                                       self.placement_matrix,
                                       self.coord_input.GetInputViewDocument(),
                                       self.coord_input.GetViewWorldProjection(),
                                       True)
        self.coord_input.InitFirstPointInput(AllplanIFWInput.InputStringConvert("Select handle"))
        self.input_mode = self.InteractorInputMode.PARAMETER_INPUT #(1)!

    return True

Transition to the state PARAMETER INPUT
This shows the handles. Here is where you should pass the list of handles. Learn above how to create this list.

PARAMETER INPUT - now PythonPart is placed in a certain point. It does not follow the mouse any more. The user can input parameter values in the property palette OR grab a handle and move it. The latter must be handled in the process_mouse_msg method as follows:

def process_mouse_msg(self, mouse_msg, pnt, msg_info):

    # handling mouse move
    if self.input_mode == self.InteractorInputMode.PLACEMENT:
        #(1)!
    else:
        handle_grabbed = self.handle_modi_service.process_mouse_msg(mouse_msg, pnt, msg_info) #(2)!

    if self.coord_input.IsMouseMove(mouse_msg):
        return True

    # code below this line is executed only when mouse is clicked

    if self.input_mode == self.InteractorInputMode.PLACEMENT:
        ...
    elif self.input_mode == self.InteractorInputMode.PARAMETER_INPUT and handle_grabbed:
        self.handle_modi_service.start_new_handle_point_input(self.global_str_table_service) #(3)!
        self.input_mode = self.InteractorInputMode.HANDLE_MODIFY #(4)!

    return True

In this mode, no handles are shown so regarding handles there's nothing to do here.
This call processes the mouse movement. It highlights the handle, when the mouse hovers over it. When the handle is grabbed, the function will return True
This call makes the handle "follow" the mouse cursor.
Transition to the state HANDLE MODIFY

When at this stage the user presses Esc, the handles need to be destroyed correctly. This must be handled in the on_cancel_function by calling stop(), like:

def on_cancel_function(self) -> bool:

    if self.input_mode == self.InteractorInputMode.PARAMETER_INPUT:
        self.handle_modi_service.stop()
        ...
    return True

HANDLE MODIFICATION - now the handle follows the mouse. The user can drop it in a new position by clicking again. This must be handled as follows:

def process_mouse_msg(self, mouse_msg, pnt, msg_info):
    ...
    if self.coord_input.IsMouseMove(mouse_msg):
        return True

    # code below this line is executed only when mouse is clicked

    if self.input_mode == self.InteractorInputMode.PLACEMENT:
        ...
    elif self.input_mode == self.InteractorInputMode.PARAMETER_INPUT and handle_grabbed:
        ...
    elif self.input_mode == self.InteractorInputMode.HANDLE_MODIFY:
        self.palette_service.update_palette(-1, True) #(1)!
        self.handle_modi_service.start(self.handles,  #(2)!
                                       self.placement_matrix,
                                       self.coord_input.GetInputViewDocument(),
                                       self.coord_input.GetViewWorldProjection(),
                                       True)
        self.input_mode = self.InteractorInputMode.PARAMETER_INPUT  #(3)!

    return True

When the handle is dropped, a new parameter value is calculated and must be shown in the palette. Therefore, the palette must be updated.
The handles must be shown again.
Transition to the state PARAMETER INPUT

When at this stage the user presses Esc, the handle should be dropped and the PythonPart must be restored to the initial state (before grabbing the handle), but not terminated! This must be handled in the on_cancel_function, like:

def on_cancel_function(self) -> bool:
    if self.input_mode == self.InteractorInputMode.PARAMETER_INPUT:
        ...
    elif self.input_mode == self.InteractorInputMode.HANDLE_MODIFY:
        self.handle_modi_service.reset_value() #(1)!
        self.handle_modi_service.start(self.handles,
                                       self.placement_matrix,
                                       self.coord_input.GetInputViewDocument(),
                                       self.coord_input.GetViewWorldProjection(),
                                       True)
        self.input_mode = self.InteractorInputMode.PARAMETER_INPUT  #(2)!
        return False  #(3)!

This resets the parameter values to the state before grabbing the handle
Transition to the state PARAMETER_INPUT
After all, PythonPart should continue to run, so return False.

Modification mode

In the modification mode, the state PLACEMENT is skipped. What you need to do instead, is to show the handles right away, in the __init__() function:

def __init__(...):
    ...
    if self.modification_element_list.is_modification_element():
        self.input_mode = self.InteractorInputMode.PARAMETER_INPUT #(1)!
        self.handle_modi_service.start(self.handles,
                                       self.placement_matrix,
                                       self.coord_input.GetInputViewDocument(),
                                       self.coord_input.GetViewWorldProjection(),
                                       True)

Transition to the state PARAMETER_INPUT right away

Warning

IMPORTANT: Put the above code after showing the palette! Otherwise, the min-max values constraining the handles are not calculated correctly.

Handling special cases

Theoretically, while a handle is grabbed the user can do some input in the property palette. Confirming the input (pressing Enter) should result in the handle being dropped. You can handle this in the modify_element_property as follows:

def modify_element_property(self, page, name, value):
    if self.input_mode == self.InteractorInputMode.HANDLE_MODIFY:
        self.input_mode = self.InteractorInputMode.PARAMETER_INPUT

The other special case is when the user modifies the handle not by grabbing it, but by input in the handle's input field. This case is also handled by the modify_element_property event. What you must do, is update the palette, since the handle modification may have changed some of the values. You can implement it as follows:

def modify_element_property(self, page, name, value):
    if name == "___SubmitChanges___":  #(1)!
        self.palette_service.update_palette(-1, True)
        return #(2)!

When a property has been modified using a handle's input field, the name will be like this
Nothing else to do in this case. You can return from the function at this stage and place your other interactor logic below this return statement.

Example on GitHub

A full implementation of the HandleModificationService processing, including how to start and stop the handle input, is shown in the example HandleUsageInInteractor ( PYP | PY)

Placeholder

Layout	Type
	HANDLE_ARROW
	HANDLE_CIRCLE
	HANDLE_SQUARE_BLUE
	HANDLE_SQUARE_EMPTY
	HANDLE_SQUARE_RED
	HANDLE_SQUARE_RIGHT