Dialogs

Parameters like plane references or file paths need an extra dialog to be displayed for an easier input. Instead of e.g., making the user of the PythonPart to have to type the complete file path, we can provide him a file selection dialog. This is done with the tag <ValueDialog> and in this chapter, we will go through all the dialogs currently available in the palette.

Library

You can provide the user a dialog to select an entry from the ALLPLAN library, such as symbols, smart symbols or fixtures. In the palette, a button to open the library will show up. After the user is done with selection, the name of the selected symbol will appear on the button.

<Parameter>
    <Name>SymbolPath</Name>
    <Text>SymbolDialog</Text> 
    <Value><!--(1)!--></Value>
    <ValueType>String</ValueType>
    <ValueDialog>SymbolDialog<!--(2)!--></ValueDialog>
</Parameter>

1. The default path and filename can be set here. By using one of the following shortcuts, path can point to ALLPLAN standard folders.

   shortcut	directory
   etc	standard directory
   std	office standard directory
   usr	user's private directory
   prj	current project directory

2. See table below, what options are available

Depending on the value set in the <ValueDialog>, the shown dialog will filter the elements for selection accordingly. Following entries are possible:

Dialog type	Element types
SymbolDialog	Only symbols
FixtureDialog	Only fixtures (point, line and area)
SmartSymbolDialog	Only smart symbols (macros)
OpeningSymbolDialog	Smart symbols and SmartParts

Dialog

The dialog shown on the left is an example for selecting a symbol (SymbolDialog). Other dialogs will look exactly the same, just their content will differ.

In the script, the value of the property parameter will, depending on the used dialog, contain a string with either a full path to the symbol file, like this:

>>> build_ele.SymbolPath.value
"C:\ProgramData\Nemetschek\Allplan\2025\etc\Library\2D Objects\Artist\abstract trees\Abstract tree 2.sym"

or a relative path, with a keyword etc, usr,prj, etc... like this:

>>> build_ele.FixturePath.value
"etc\Library\Fixtures\Walls\Electric\1Dose + ELR unten.gfx"

Info

The LibraryElement will need a full path to the object. To turn a relative path into a global path, use the method get_global_standard_path:

>>> FileNameService.get_global_standard_path("etc\\Library\\Fixtures\\Walls\\Electric\\1Dose + ELR unten.gfx")
'C:\\ProgramData\\Nemetschek\\Allplan\\2025\\etc\\Library\\Fixtures\\Walls\\Electric\\1Dose + ELR unten.gfx'

Trade

With Trade the user is being provided a dialog for a trade selection. After the selection an integer representing the trade is assigned to the parameter value and the name of the selected trade is being displayed on the button.

<Parameter>
    <Name>TradeID</Name>
    <Text>Trade</Text>
    <Value>0</Value>
    <ValueType>Integer</ValueType>
    <ValueDialog>Trade</ValueDialog>
</Parameter>

Dialog

Attribute

With AttributeSelection the user is being provided a dialog for an attribute selection. After the selection an integer of the attribute ID is assigned to the parameter value and the name of the selected attribute is being displayed on the button.

<Parameter>
    <Name>AttributeID</Name>
    <Text>Attribute</Text>
    <Value>0</Value>
    <ValueType>Integer</ValueType>
    <ValueDialog>AttributeSelection</ValueDialog><!--(1)!-->
</Parameter>

1. To limit the attributes that can be selected, different type of dialogs can be displayed. Here is a brief overview:

   Dialog	Limitation
   AttributeSelection	No limitation. All attributes can be selected.
   AttributeSelectionInsert	Allow to select the insert attributes (additional to the default object attributes).
   AttributeSelectionProject	Allow to select the project attributes.

Dialog

RGB color

With RGBColorDialog the user is being provided a dialog for the definition of a RGB color. After the selection an RGB integer of the defined color is assigned to the parameter value and the color itself is being displayed on the button.

<Parameter>
    <Name>ColorID</Name>
    <Text>Color</Text>
    <Value>255</Value>
    <ValueType>Integer</ValueType>
    <ValueDialog>RGBColorDialog</ValueDialog>
</Parameter>

Dialog

Tip

To extract the individual RGB channels from the integer e.g., in order to construct an ARGB object, use this code snippet:

AllplanBasisElements.ARGB(red   = (build_ele.ColorID.value >> 16) & 255,
                          green = (build_ele.ColorID.value >> 8) & 255,
                          blue  = build_ele.ColorID.value & 255,
                          alpha = 0)

Bitmap

With BitmapResourceDialog the user is being provided a dialog for the selection of a bitmap. After the selection the complete path to the symbol is being assigned to the parameter value. On the button only the file name is being displayed.

<Parameter>
    <Name>BitmapName</Name>
    <Text>Bitmap</Text>
    <Value><!--(1)!--></Value> 
    <ValueType>String</ValueType>
    <ValueDialog>BitmapResourceDialog</ValueDialog>
</Parameter>

1. The default path and filename can be set here. By using one of the following shortcuts, path can point to ALLPLAN standard folders.

   shortcut	directory
   etc	standard directory
   std	office standard directory
   usr	user's private directory
   prj	current project directory

Dialog

Plane references

To let the user define a reference to a plane, provide a dialog for the plane selection. You can do it by defining a parameter of type PlaneReferences. The object returned by this parameter is of type PlaneReferences.

Warning

If your script creates a PythonPart element, plane references will be saved in it (as any other parameter) to be used during the modification. Beside that, the PythonPart element will be updated in case a referenced plane has been modified. To prevent ALLPLAN getting stuck during this process, make sure, that reactivating your PythonPart with double-click and hitting Esc directly afterwards leads to a clean script termination.

There are three ways a user can define a plane reference, each requires a different dialog:

• by defining the top reference only
• by defining the bottom reference only
• by defining both bottom and top plane references

Top onlyBottom onlyTop and bottom

<Parameter>
    <Name>TopPlane</Name>
    <Text>Top plane</Text>
    <Value></Value>
    <ValueType>PlaneReferences</ValueType>
    <ValueDialog>TopPlaneReferences</ValueDialog>
</Parameter>

Dialog

<Parameter>
    <Name>BottomPlane</Name>
    <Text>Bottom plane</Text>
    <Value></Value>
    <ValueType>PlaneReferences</ValueType>
    <ValueDialog>BottomPlaneReferences</ValueDialog>
</Parameter>

Dialog

<Parameter>
    <Name>PlaneReferences</Name>
    <Text>Top and bottom plane</Text>
    <Value></Value>
    <ValueType>PlaneReferences</ValueType>
    <ValueDialog>PlaneReferences</ValueDialog>
</Parameter>

Dialog

Warning

When the planes are changed by the user in floor manager, all PythonParts with plane connections (the ones where one of the parameters has value type set to PlaneReferences) are checked and, if necessary, updated.

Prepare your PythonPart for being updated!.

Make sure, that reactivating your PythonPart with double-click and hitting Esc directly after, leads to a clean termination. If that is not the case, ALLPLAN will get stuck during the update.

Note

Note that the object PlaneReferences holds information about references to both top and bottom level. Providing a dialog to define only one of them will make the other one refers to the default level.

Hide individual control

To hide the edit control of the height or elevation, include the <Visible> tag and specify the control name followed by a colon : and the boolean statement True or False:

<Parameter>
    <Name>ExampleParameter</Name>
    <Text>Top and bottom plane</Text>
    <Value></Value>
    <ValueType>PlaneReferences</ValueType>
    <ValueDialog>PlaneReferences</ValueDialog>
    <Visible>|ExampleParameter.Height:False<!--(1)!--></Visible>
</Parameter>

1. Use following key words for the control name:

   Key word	Value type
   AbsBottomElevation	BottomPlaneReferences
   AbsTopElevation	TopPlaneReferences
   Height	PlaneReferences

Constraints

It is possible to constrain a parameter of type PlaneReferences with another parameter of type Length in order to achieve following behavior:

1. Modification of the Length parameter will change the plane references
2. Modification of the plane references will change the value if the Length parameter

By adding the <Constraint> tag to the PlaneReference parameter we can achieve the first behavior. Adding the tag to the Length parameter will result in the second behavior. Here is an example:

<Parameter>
    <Name>AbsBoxBottomElevation</Name>
    <Text>Absolute bottom elevation</Text>
    <Value></Value>
    <ValueType>Length</ValueType>
    <Constraint>PlaneReferencesBox.AbsBottomElevation</Constraint><!--(1)!-->
    <Persistent>NO</Persistent><!--(2)!-->
</Parameter>

<Parameter>
    <Name>BoxHeight</Name>
    <Text>Height</Text>
    <Value></Value>
    <ValueType>Length</ValueType>
    <Constraint>PlaneReferencesBox.Height</Constraint><!--(3)!-->
    <Persistent>NO</Persistent><!--(2)!-->
</Parameter>

<Parameter>
    <Name>PlaneReferencesBox</Name>
    <Text>Plane references</Text>
    <Value></Value>
    <ValueType>PlaneReferences</ValueType>
    <ValueDialog>PlaneReferences</ValueDialog>
    <Visible>|PlaneReferencesBox.Height:False</Visible><!--(4)!-->
    <Constraint>AbsBottomElevation=AbsBoxBottomElevation;Height=BoxHeight<!--(5)!--></Constraint>
</Parameter>

1. After the user changes the plane references in the PlaneReferenceBox parameter in any way, the absolute elevation of the bottom plane is recalculated and written back into this parameter.
2. As the tag <Constraint> is added, the value of this parameter is derived from another one (PlaneReferencesBox parameter). Because we do not want to store the same information double, we exclude this parameter from being stored in a favorite file or in the a PythonPart (if we create one at the end).
3. After the user changes the plane references in the PlaneReferenceBox parameter in any way, the height between the bottom and the top plane is recalculated and written back into this parameter.
4. We can hide the edit field of the height, as we already have a separate, constrained parameter with an edit control for it.

5. After the user types in a new value into the BoxHeight or in the AbsBoxBottomElevation, the plane references are recalculated. The key word on the left side of the = tells, how the recalculation is done:

   Key word	Recalculation
   AbsBottomElevation	The bottom plane offset is recalculated to meet the new absolute elevation
   BottomElevation	The new value is set directly as new bottom plane offset
   AbsBottomElevation	The top plane offset is recalculated to meet the new absolute elevation
   BottomElevation	The new value is set directly as new top plane offset
   Height	The top plane offset is recalculate to meet the new height between the planes

Example on GitHub

See the entire implementation in the example PlaneReferencesControls ( PYP | PY).

File

With OpenFileDialog and SaveFileDialog the user is being provided a dialog for respectively opening or saving a file. After closing the dialog, the complete file path is being assigned to the parameter value, and the file name is being displayed on the button.

<Parameter>
<Name>FavoriteFile</Name>
    <Text>Open favorite file</Text>
    <Value><!--(5)!--></Value>
    <ValueType>String</ValueType>
    <ValueDialog>OpenFileDialog</ValueDialog> <!--(4)!-->
    <FileFilter>pyv-files(*.pyv)|*.pyv|</FileFilter> <!--(1)!-->
    <FileExtension>pyv</FileExtension> <!--(2)!-->
    <DefaultDirectories>etc|std|usr|prj</DefaultDirectories> <!--(3)!-->
</Parameter>

1. The format of the filter must look like this:

   _text displayed_|_filter as regex_|_another text_|_another filter_|

2. The default file extension is set here.

3. Optional Add this tag if the button opening default directories is to be added on the left side of the file dialog. The following directories can be displayed.

   Shortcut	Directory
   etc	Standard directory
   std	Office
   usr	Private
   prj	Current project

4. See table below to learn about possible key words for this tag.

5. The default path and filename can be set here. By using one of the following shortcuts, path can point to ALLPLAN standard folders.

   shortcut	directory
   etc	standard directory
   std	office standard directory
   usr	user's private directory
   prj	current project directory

<ValueDialog>	<DefaultDirectories>	Description
OpenFileDialog		Display a file open dialog
SaveFileDialog		Display a file save dialog
OpenFavoriteFileDialog		Display a favorite file open dialog
SaveFavoriteFileDialog		Display a favorite file save dialog

Dialog

Placeholder