Skip to content

Dynamic property palette

The property palette can be created and changed dynamically during the runtime of a PythonPart. In this chapter we are going to focus on various methods, which can control the look and layout of the elements of the property palette.

Control properties

The class ControlProperties represents the internal data structure behind controls in the PythonPart property palette. A control has properties responsible for:

  • text shown on the left side of the palette
  • value checking (minimal / maximal value, value list)
  • background color of the control field
  • hiding/showing and enabling/disabling a control

To modify these control properties during the runtime of the PythonPart, use the methods provided in the ControlPropertiesUtil. Using this utility, properties mentioned above can be changed in the script when the palette is initialized or with each property modification done by the user.

In a standard PythonPart the ControlPropertiesUtil object is passed as an argument to the following functions:

Implement them in your script to get the access to the methods provided in the utility.

In a script object PythonPart, the ControlPropertiesUtil is part of the BaseScriptObjectData - an object that is prepared and given to you by the framework as an argument in the create_script_object function.

In an interactor PythonPart the ControlPropertiesUtil must be constructed first.

from ControlPropertiesUtil import ControlPropertiesUtil
...
ctrl_prop_util = ControlPropertiesUtil(control_props_list, build_ele_list) #(1)!
  1. The control_props_list and build_ele_list are python lists containing ControlProperties and BuildingElement objects respectively. These lists are passed by the framework directly to the create_interactor function based on the .pyp file when the PythonPart is initialized.

After the utility is constructed, its methods can be used as follows:

if ...:
    ctrl_prop_util.set_text("Distance", "Distance from left") #(1)!
else:
    ctrl_prop_util.set_text("Distance", "Distance from right")
  1. In this case the text shown in the palette for the parameter Distance is changed from the default value defined in the <Text> tag in the .pyp file into Distance from left.

Hide or disable a control

Sometimes it's useful to disable or hide a control inside the property palette dynamically e.g., based on a value of another parameter. Based in the complexity of the condition, this behavior can be implemented directly in the .pyp file or in the script.

In the .pyp file

Managing the visibility and enable state of a specific input control can be done dynamically directly in the .pyp file by adding the tags <Enable> and/or <Visible> in the <Property> node.

<Parameter>
    <Name>String</Name>
    <Text>String parameter</Text>
    <Value>This is a string</Value>
    <ValueType>String</ValueType>
    <Enable>True</Enable>
    <Visible>0</Visible>
</Parameter>

To apply the condition to multiple directly consecutive parameters, put them into one virtual parameter called condition group

<Parameter>
    <ValueType>ConditionGroup</ValueType>
    <Visible>FooParameter == 2</Visible>

    <Parameter>
        <Name>BarParameter</Name>
        ...
    </Parameter>

    <Parameter>
        <Name>BazParameter</Name>
        ...
    </Parameter>
</Parameter>

Example

Here are some examples of more complex conditions for controlling the visibility.

<Enable>FooParameter == True</Enable>  <!--(1)!-->
<Visible>RadioButtonValue in [1, 5]</Visible>

<Enable>FooParameter == __StringTable.get_string("1220", "Column")</Enable>  <!--(2)!-->

<Enable>$list_row != FooParameter</Enable>  <!--(3)!-->
<Visible>NamedTupleParameter[$list_row].TupleItem</Visible>

<Visible>__is_visible_control("FooParameter") and FooParameter > 0</Visible>  <!--(4)!-->

<Enable>__is_input_mode()</Enable>  <!--(5)!-->

<Visible> <!--(6)!-->
if FooParameter &lt; 1000:
    return True:

if BarParameter &gt;<!--(7)!--> 1000:
    return True

return False
</Visible>  
  1. A logical formula including other parameters
  2. A logical formula including access to the string table
  3. A logical formula including access to the list row (in case of list parameter)
  4. A logical formula including a check for the visibility of another parameter
  5. A logical formula checking the input mode. The function __is_input_mode() returns False for PythonPart modification
  6. A multi-line logical formula
  7. Because the .pyp file uses the xml syntax, use &lt; and &gt; instead of < and > operators.

In the script

If the complexity of the enable or visible condition is so high that it cannot be implemented in the .pyp file, you must implement it in the script. Use the ControlPropertiesUtil class mentioned above. First, define a function returning True, when the control should be visible/enabled:

def initialize_control_properties(build_ele, ctrl_prop_util, _doc):
    ...
    def visible_foo_parameter(...) -> bool: #(1)!
        #perform operations to determine the visibility
        return ...

    def enable_bar_parameter(...) -> bool:
        #perform operations to determine the enable state
        return ...
  1. Provide the right parameter in (...) depending on the type of the parameter value:

    value type parameter
    single value ()
    list of values (row_index: int)
    single namedtuple (field_name: str)
    list of namedtuple (row_index: int, field_name: str)

Then assign the function to the parameter whose visibility/enable state you want to control with it. Use the set_enable_function to control the enable state or set_visible_function to control the visibility.

    ctrl_prop_util.set_visible_function("FooParameter", visible_length)
    ctrl_prop_util.set_enable_function("BarParameter", enable_length)

Example on GitHub

Refer to the example Visibility ( PYP | PY) to see how the controls can be hidden/shown/disabled/enabled dynamically in the PYP file or in the script. Additionally, you can also have a look at the example ValueList ( PYP | PY)

Active page

Sometimes it's useful to do display the handles or some preview data depending on which page of the property palette is currently active. This behavior can be implemented with the set_active_palette_page_index function. You can implement it into your standard PythonPart as well as into your interactor

Dynamic text

If the text inside the property palette needs to be dynamic, this can be implemented in the script (as described in the chapter before) or directly in the PYP file using the <TextDyn> tag. The same can be done for the <ValueTextDyn> tag, which creates a dynamic value text.

A single line Python expression can be implemented in this tag like this:

<TextDyn>__StringTable.get_string(1003, "Placement") + ("Right" if DistanceHeader else "Left")<!--(1)!--></TextDyn>
  1. Functions from the math package are possible and can be used by math.xxx.

A multi-line Python expression can also be implemented. The Python source code for the expression must be left aligned in the .pyp file. Because the .pyp file uses the XML syntax, &lt; and &gt; operators must be used instead of < and >.

<TextDyn>
if not Dimension:
    return "Length"
if Dimension == 1:
    return "Width"
return "Height"
<TextDyn>

In case of a list parameter, the row index can be accessed with $list_row.

Example on GitHub

Have a look at the example TextDyn ( PYP | PY) to see the full implementation.

Palette handling in interactor

In an interactor PythonPart, the developer is responsible for handling the palette. Showing and closing it is the easy part. The tricky part is to get the input values back into the BuildingElement object and update the controls' visibility states (show or hide, disable or enable) which might be influenced by the new value. This must be handled by the interactor inside appropriate events.

To do this, use BuildingElementPaletteService. Here are the steps you have to implement:

  1. When initializing the interactor:

    • Initialize the palette service:

      def __init__(...):
          self.build_ele = build_ele_list[0]
          ...
          self.palette_service = BuildingElementPaletteService(
              self.build_ele,
              build_ele_composite,
              self.build_ele.script_name,
              control_props_list,
              self.build_ele.pyp_file_name + "\\" #(1)!
          )
      
      1. You can provide the path with all the picture assets, that you use in the palette. Whenever you define e.g. a picture parameter, or any other control with a defined path to a picture file, the framework will look for the file under this path.

        The path parts must be separated with a backslash \ and there must be a trailing backslash at the end, e.g.: C:\\path\\to\\picture\\assets\\.

        The build_ele.pyp_file_name will get you the path to the directory of the PYP file, however without the trailing backslash!

    • Show the palette:

      self.palette_service.show_palette(self.build_ele.pyp_file_name)
      
  2. During the runtime of a PythonPart, on every property modification (in the modify_element_property event):

    • Write the new value back into the BuildingElement and recalculate other parameter values, that might depend on the modified one. Do it by calling the modify_element_property method.

    • New parameter value might have result in some controls change their appearance (they get disabled, hidden, text may changed, etc..). To show the up-to-date state of the palette to the user, you must update it by calling update_palette.

    Here is how the implementation may look like:

    def modify_element_property(self, page, name, value):
        update_necessary = self.palette_service.modify_element_property(page, name, value)
    
        # here you can implement some additional calculations
    
        if update_necessary
            self.palette_service.update_palette(-1, False) #(1)!
    
    1. The -1 wil update the currently active page
  3. During the runtime of a PythonPart, on each event triggered by pressing a button (during the on_control_event):

    Note

    The implementation shown below is needed only, if pressing a button actually changes the appearance of the palette. Otherwise the update is not necessary and should be avoided!

    Here is how the implementation may look like:

    def on_control_event(self, event_id) -> bool:
        self.palette_service.on_control_event(event_id)
        self.palette_service.update_palette(-1, False)
    
  4. At the end of the PythonPart runtime, close the palette. This must be handled in both on_cancel_function event, like:

    def on_cancel_by_menu_function(self) -> None:
        self.palette_service.close_palette()
    

    ... as well as in the on_cancel_by_menu_function event, like:

    def on_cancel_function(self) -> bool:
        self.palette_service.close_palette()
        return True
    
Placeholder