X4 Produktdokumentation
X4 Produktdokumentation
Breadcrumbs

ComboBox

With <ComboBox> controls, you can offer users a choice from a list of predefined options, usually with only one choice. They are particularly useful when the number of options is manageable and you want to save space in the form, as the list is only visible when you click on the field. For long lists, it is recommended to use <ComboBoxAutocomplete> controls, which allow you to enter text and dynamically display matching options.

Instructions for use

A <ComboBox> control is created with the <ComboBox> element.

<ComboBox>
...
</ComboBox>

<ComboBox> controls can be used in all available layout types: For more information, see Layouts.

Attribute

Note:

There are a number of default attributes that can be set for all controls. For more information about the default attributes, see Default attributes.

In addition to the default attributes, you can define the following attributes for <ComboBox> controls.

Attribute

Description

displayName

Title of the ComboBox. Appears small above the input/output field.

  • Translatable

  • Data binding possible

Possible values:

Any string

displayProperty

Must be specified if optionsList is set. Text that is displayed in the ComboBox as a selection option.

Possible values:

String that corresponds to a defined property

Note:

The specified string must correspond to a valid subproperty used in optionsList. If no displayProperty is specified, then the first subproperty of the property specified for optionsList is automatically used.

iconColorProperty

Name of the property that contains the color information of the icon.

Note:

This attribute is only used for Material Icons. The color can be a hexadecimal color value (e.g. ff5a00) or a color code from the Web App color palette (see Theming), e.g. A200.

  • Data binding possible

Possible values:

String that corresponds to a defined property

Note:

For relative bindings, the hashtag # must be used as a prefix for the property, e.g. #Country.Id.

iconProperty

Name of the property that contains the URL of the icon resource.

Note:

The icon can either be a resource from the Resources folder in the X4 project, a Material Icon or an icon embedded via an external URL.
If the icon is integrated via an external link, the additional attribute type="external" must be specified in the property.

  • Data binding possible

Possible values:

String that corresponds to a defined property

For relative bindings, the hashtag # must be used as a prefix for the property, e.g. #Country.Id.

optionsAutoWidth

Enable automatic width for the options list.

Possible values:

  • true (default): The width of the options list automatically adjusts to the width of the option values.

  • false: The width of the options list depends on the width of the ComboBox.

optionsList

For swapped-out options list: Source of the list. Can only be used in conjunction with displayProperty.

  • Is activated via data binding (list).

Possible values:

String (data binding)

optionsMaxWidth

Maximum width of the options list in percent or pixels, where percent refers to the screen width.

Possible values: Any integer

optionsUnits

Defines the unit for the optionsMaxWidth attribute.

Possible values:

  • percents

  • pixels (default)

value

Required

Value that is displayed and stored.

  • Data binding possible

Possible values:

Any string

valueProperty

Value that is technically processed. If this attribute is set, the property defined for this value must also be called this. If this attribute is not set, value is used.

Possible values: Any string

Note:

The specified string must correspond to a valid subproperty used in optionsList. If no valueProperty is specified, the value specified for displayProperty is automatically used.

A ComboBox control contains at least one <Option> element that creates a selection option. The options in the pick list can either come from a Technical Process or be entered manually.

Note:

You can insert an empty <Option> element if you do not want the first entry in the pick list to be pre-selected automatically. For connected ComboBox elements, you must add an empty <Option> element in each element.

If you add an empty <Option> element and have added a display name for the ComboBox using the displayName attribute, the display name (for example, please select) is displayed as the first entry:

image-20260216-140152.png

For the <Option> element, you can define the following attributes:

Attribute

Description

displayName

Required

Display name of the selection option.

  • Translatable

  • Data binding possible

Possible values:

Any string

Note:

If you want to quickly switch to a specific option in a ComboBox with many selection options instead of scrolling through the entire list, click in the ComboBox and enter all or part of the display name of the option.

value

Value of the selection option

  • Data binding possible

Possible values:

Any string

iconColor

Color of the icon

This attribute is only used for Material Icons.

Possible values:

  • Hexadecimal color value, e.g. ff5a00

Note:

  • Do not use a hash before the color value.

  • Do not use an abbreviated notation of the color value.

  • Color code from the color palette of the Web App, e.g. A200
    For more information, see Theming.

iconUrl

Path to the icon used

The icon can either be a resource from the Resources folder in the X4 project, a Material Icon or an icon embedded via an external URL.

Possible values:

  • String (URI), e.g. clock.png

  • Specification of a material icon according to the pattern icon:<MaterialIconName>, e.g. icon:extension

With Ctrl+Space, you get an overview of the available icons. The selection may differ from the actual available Material Icons.

  • External URL

The data for an outsourced option list must be XML data. The options must be included in a list:

XML
<example>
	<listElement>list element 1</listElement>
</example>
<example>
	<listElement>list element 2</listElement>
</example>

Properties are defined according to the XML data. Note that an additional property saveValue is created, which is used as the initial value and container for saving the user input.

XML
<Property name="example" type="List">
	<Property name="listElement" type="String" />
</Property>
<Property name="saveValue" type="String" />

Actions

The following action is available for <ComboBox> controls. For more information about actions, see Actions.

<SelectAction>

You can insert the Select action using the <SelectAction/> element within <ComboBox>. The action is triggered as soon as the user activates or deactivates the ComboBox.

Note:

You must insert the <SelectAction> element before the desired layout type (BoxLayout, FlowLayout, GridLayout, ResponsiveLayout, TabLayout).

Examples

Example 1: <ComboBox> with two options

ComboBox control in the Detail Component
XML
<DetailComponent name="ExampleComboBox" path="ExampleComboBox" displayName="Example ComboBox" process="ComboBox.wrf">
	<FlowLayout>
		<ComboBox value="#saveValue">
			<Option displayName="Answer A"/>
			<Option displayName="Answer B"/>
		</ComboBox>
	</FlowLayout>
</DetailComponent>
image2019-1-23_15-17-0.png
image2019-1-23_15-16-41.png

Example 2: <ComboBox> with outsourced option list

The following example uses a outsourced option list. The displayed name and associated technical value differ.

The data for an outsourced option list must be XML data. The options, including the technical values, must be included in a list:

Options list
XML
<?xml version="1.0" encoding="UTF-8"?>
<Ok>
	<ComboBoxValue></ComboBoxValue>
	<OptionList>
		<OptionValue>Red</OptionValue>
		<TechnicalValue>#FF0000</TechnicalValue>
	</OptionList>
	<OptionList>
		<OptionValue>Green</OptionValue>
		<TechnicalValue>#008000</TechnicalValue>
	</OptionList>
	<OptionList>
		<OptionValue>Blue</OptionValue>
		<TechnicalValue>#0000FF</TechnicalValue>
	</OptionList>
</Ok>
Properties definition according to the XML data
XML
<Properties>
  <Property name="ComboBoxValue" type="String"></Property>
  <Property name="OptionList" type="List">
			<Property name="OptionValue" type="String"></Property>
			<Property name="TechnicalValue" type="String"></Property>
  </Property>	
</Properties>

The ComboBox control in the Detail Component contains a SelectAction. The SelectAction sends the data to the defined Technical Process when an option is selected from the ComboBox.

The data from the outsourced option list (optionsList attribute) is used in the ComboBox. The OptionValue elements are displayed, but the technical data from the TechnicalValue element is selected in the background.

ComboBox control in the Detail Component
XML
<?xml version="1.0" encoding="UTF-8"?>
<DetailComponent
	xmlns="http://softproject.de/webapp/1.0"
	process="LoadData.wrf">
<Properties>
  <Property name="ComboBoxValue" type="String"></Property>
  <Property name="OptionList" type="List">
			<Property name="OptionValue" type="String"></Property>
			<Property name="TechnicalValue" type="String"></Property>
  </Property>
</Properties>
	<FlowLayout>
		<Header value="Welcome to my new Web App!" />
		<ComboBox
			value="#ComboBoxValue"
			optionsList="#OptionList"
			valueProperty="#TechnicalValue"
			displayProperty="#OptionValue">
			<SelectAction process="SaveData.wrf" />
		</ComboBox>
	</FlowLayout>
</DetailComponent>

Note:

The XML data to be used for the options must be provided by a Technical Process (in the example LoadData.wrf and SaveData.wrf).

Example 3: <ComboBox> with icons and an outsourced option list

The following example shows the use of the <ComboBox> element with icons and an outsourced option list. The options are provided as a selection option via a Technical Process.

Options list
XML
<?xml version="1.0" encoding="UTF-8"?>
<OkList>
	<Country>
		<Id>6</Id>
		<Name>Worldwide</Name>
		<icon>icon:public</icon>
		<color>ff5a00</color>
	</Country>
	<Country>
		<Id>2</Id>
		<Name>Italy</Name>
		<icon>italy.png</icon>
	</Country>
	<Country>
		<Id>5</Id>
		<Name>Germany</Name>
		<icon>germany.png</icon>
	</Country>
	<Country>
		<Id>3</Id>
		<Name>Portugal</Name>
		<icon>portugal.png</icon>
	</Country>
	<Country>
		<Id>4</Id>
		<Name>Spain</Name>
		<icon>spain.png</icon>
	</Country>
	<selected>6</selected>
</OkList>


ComboBox controls with icons in the Detail Component
XML
<DetailComponent default="true" displayName="Dashboard" path="Dashboard" 
                 process="folder_1/Options.wrf">
	<Properties>
		<Property name="selected" type="Integer"/>
		<Property name="direction" type="Integer"/>
		<Property name="Country" type="List">
			<Property name="Id" type="Integer"/>
			<Property name="Name" type="String"/>
			<Property name="icon" type="Image"/>
			<Property name="color" type="Color"/>
		</Property>
		<Property name="image" type="Image"/>
	</Properties>
	<FlowLayout>
		<ComboBox displayName="$Country" displayProperty="#Name" 
                  iconColorProperty="#color"
                  iconProperty="#icon"
                  optionsList="#Country"
                  value="#selected"
                  valueProperty="#Id"/>
		<ComboBox displayName="Means of transport" value="#direction">
			<Option displayName="Bike" iconColor="A200" iconUrl="icon:directions_bike" value="1"/>
			<Option displayName="Walk" iconColor="A200" iconUrl="icon:directions_walk" value="4"/>
			<Option displayName="Subway" iconColor="A200" iconUrl="icon:directions_subway" value="3"/>
		</ComboBox>
	</FlowLayout>
</DetailComponent>
image-20251107-103919.png