X4 Produktdokumentation
X4 Produktdokumentation
Breadcrumbs

ComboBox

Mit <ComboBox>-Controls können Sie Benutzern eine Auswahl aus einer Liste vordefinierter Optionen anbieten, wobei in der Regel nur eine Auswahl möglich ist. Sie eignen sich besonders, wenn die Anzahl der Optionen überschaubar ist und Platz im Formular gespart werden soll, da die Liste erst beim Klicken auf das Feld sichtbar wird. Bei langen Listen empfiehlt sich die Verwendung von <ComboBoxAutocomplete>-Controls, die es ermöglichen, Text einzugeben und passende Optionen dynamisch anzuzeigen.

Hinweise zur Verwendung

Ein <ComboBox>-Control wird mit dem Element <ComboBox> erzeugt.

<ComboBox>
...
</ComboBox>

<ComboBox>-Controls können in allen verfügbaren Layouttypen verwendet werden. Weitere Informationen finden Sie unter Layouts.

Attribute

Hinweis:

Es gibt eine Reihe von Standardattributen, die für alle Controls festgelegt werden können. Weitere Informationen zu den Standardattributen finden Sie unter Standardattribute.

Zusätzlich zu den Standardattributen können Sie die folgenden Attribute für <ComboBox>-Controls definieren:

Attribut

Beschreibung

displayName

Titel der ComboBox. Wird klein über dem Ein-/Ausgabefeld angezeigt.

  • Übersetzbar

  • Data Binding möglich

Mögliche Werte:

Beliebige Zeichenkette

displayProperty

Muss angegeben werden, wenn optionsList gesetzt ist. Text, der in der ComboBox als Auswahlmöglichkeit angezeigt wird.

Mögliche Werte:

Zeichenkette, die einer definierten Property entspricht

Hinweis:

Die angegebene Zeichenkette muss einer validen Subproperty entsprechen, die in optionsList verwendet wird. Wenn kein displayProperty angegeben wird, dann wird automatisch die erste Subproperty der Property verwendet, die für optionsList angegeben ist.

iconColorProperty

Name der Property, die die Farbangaben des Icons enthält.

Hinweis:

Dieses Attribut wird nur für Material Icons verwendet. Dabei kann die Farbangabe ein hexadezimaler Farbwert, z. B. ff5a00 oder ein Farbcode aus der Farbpalette der Web App (vgl. Theming), z. B. A200 sein.

  • Data Binding möglich

Mögliche Werte:

Zeichenkette, die einer definierten Property entspricht

Hinweis:

Für relative Bindings muss das Hashtag # als Präfix für die Property verwendet werden, z. B. #Country.Id.

iconProperty

Name der Property, die die URL der Icon-Ressource enthält.

Hinweis:

Beim Icon kann es sich entweder um eine Ressource aus dem Ordner Resources im X4 Projekt, ein Material Icon oder ein über eine externe URL eingebundenes Icon handeln.
Wird das Icon über einen externen Link eingebunden, muss in der Property das zusätzliche Attribut type="external" angegeben werden.

  • Data Binding möglich

Mögliche Werte:

Zeichenkette, die einer definierten Property entspricht

Für relative Bindings muss das Hashtag # als Präfix für die Property verwendet werden, z. B #Country.Id.

optionsAutoWidth

Automatische Breite für die Optionsliste aktivieren.

Mögliche Werte:

  • true (Standard): Die Breite der Optionsliste passt sich automatisch der Breite der Optionswerte an.

  • false: Die Breite der Optionsliste richtet sich nach der Breite der ComboBox.

optionsList

Bei ausgelagerter Optionsliste: Quelle der Liste. Kann nur zusammen mit displayProperty verwendet werden.

  • Wird per Data Binding (Liste) angesteuert.

Mögliche Werte:

Zeichenkette (Data Binding)

optionsMaxWidth

Maximale Breite der Optionsliste in Prozent oder Pixel, wobei Prozent sich auf die Bildschirmbreite bezieht.

Mögliche Werte: Beliebige ganze Zahl

optionsUnits

Definiert die Einheit für das Attribut optionsMaxWidth.

Mögliche Werte: 

  • percents

  • pixels (Standard)

value

Erforderlich

Wert, der angezeigt und gespeichert wird.

  • Data Binding möglich

Mögliche Werte:

Beliebige Zeichenkette

valueProperty

Wert, der technisch verarbeitet wird. Wenn dieses Attribut gesetzt ist, muss auch die für diesen Wert definierte Property so heißen. Wenn dieses Attribut nicht gesetzt wird, wird value verwendet.

Mögliche Werte: Beliebige Zeichenkette

Hinweis:

Die angegebene Zeichenkette muss einer validen Subproperty entsprechen, die in optionsList verwendet wird. Wenn kein valueProperty angegeben wird, dann wird automatisch die der Wert verwendet, der für displayProperty angegeben ist.

Ein <ComboBox>-Control enthält mindestens ein <Option>-Element, das eine Auswahloption erzeugt. Die Optionen der Auswahlliste können entweder aus einem Technical Process kommen oder manuell eingetragen werden.

Hinweis:

Sie können ein leeres <Option>-Element einfügen, wenn der erste Eintrag der Auswahlliste nicht automatisch vorausgewählt sein soll. Bei verbundenen ComboBox-Elementen müssen Sie in jedem Element ein leeres <Option>-Element hinzufügen.

Wenn Sie ein leeres <Option>-Element hinzufügen und über das Attribut displayName einen Anzeigenamen für die ComboBox hinzugefügt haben, wird der Anzeigename (z. B. Bitte wählen) als erster Eintrag angezeigt:

image-20250905-100014.png

Für das Element <Option> lassen sich folgende Attribute deklarieren:

Attribut

Beschreibung

displayName

Erforderlich

Anzeigename der Auswahloption.

  • Übersetzbar

  • Data Binding möglich

Mögliche Werte:

Beliebige Zeichenkette

Hinweis:

Wenn Sie in einer ComboBox mit zahlreichen Auswahloptionen schnell zu einer bestimmten Option wechseln möchten, anstatt durch die gesamte Liste zu scrollen, klicken Sie in die ComboBox, und geben Sie den Anzeigenamen der Option ganz oder teilweise ein.

value

Wert der Auswahloption

  • Data Binding möglich

Mögliche Werte:

Beliebige Zeichenkette

iconColor

Farbe des Icons

Dieses Attribut wird nur für Material Icons verwendet.

Mögliche Werte:

  • Hexadezimaler Farbwert, z. B. ff5a00

Hinweis:

  • Verwenden Sie keine Raute vor dem Farbwert.

  • Verwenden Sie keine verkürzte Schreibweise des Farbwerts.

  • Farbcode aus der Farbpalette der Web App, z. B. A200
    Weitere Informationen finden Sie unter Theming.

iconUrl

Pfad zum verwendeten Icon

Beim Icon kann es sich entweder um eine Ressource aus dem Ordner Resources im X4 Projekt, einem Material Icon oder einem über eine externe URL eingebundenen Icon handeln.

Mögliche Werte: 

  • Zeichenkette (URI), z. B. clock.png

  • Angabe eines Material Icons nach dem Muster icon:<MaterialIconName>, z. B. icon:extension

Mit Strg+Leertaste erhalten Sie eine Übersicht der verfügbaren Icons. Die Auswahl kann von den tatsächlich verfügbaren Material Icons abweichen.

  • Externe URL

Die Daten für eine ausgelagerte Optionenliste müssen als XML-Daten vorliegen. Dabei müssen die Optionen in einer Liste enthalten sein:

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

Die Properties-Definition erfolgt entsprechend den XML-Daten. Dabei ist zu beachten, dass eine zusätzliche Property saveValue angelegt wird, die als initialer Wert und Container für das Speichern der Benutzereingabe verwendet wird.

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

Actions

Für <ComboBox>-Controls steht Ihnen folgende Action zur Verfügung. Weitere Informationen zu Actions finden Sie unter Actions.

<SelectAction> 

Sie können die Action Select über das Element <SelectAction/> innerhalb von <ComboBox> einfügen. Die Action wird ausgelöst, sobald der Benutzer die ComboBox aktiviert oder deaktiviert.

Hinweis:

Sie müssen das Element <SelectAction> vor dem gewünschten Layouttyp (BoxLayout, FlowLayout, GridLayout, ResponsiveLayout, TabLayout) einfügen.

Beispiele

Beispiel 1: <ComboBox> mit zwei Optionen

ComboBox-Control in der 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

Beispiel 2: <ComboBox> mit ausgelagerter Optionsliste

Im folgenden Beispiel wird eine ausgelagerte Optionsliste verwendet. Der angezeigte Name und der zugehörige technische Wert unterscheiden sich.

Die Daten für eine ausgelagerte Optionsliste müssen als XML-Daten vorliegen. Dabei müssen die Optionen inklusive der technischen Werte in einer Liste enthalten sein.

Optionsliste
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 entsprechend den XML-Daten
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>

Das ComboBox-Control in der Detail Component enthält eine SelectAction. Die SelectAction sendet bei Auswahl einer Option aus der ComboBox die Daten an den definierten Technical Process.

In der ComboBox werden die Daten aus der ausgelagerten Optionsliste (Attribut optionsList) verwendet. Angezeigt werden die Elemente OptionValue, im Hintergrund ausgewählt werden jedoch die technischen Daten aus dem Element TechnicalValue.

ComboBox-Control in der 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>

Hinweis:

Die XML-Daten, die für die Optionen verwendet werden sollen, müssen von einem Technical Process (im Beispiel LoadData.wrf und SaveData.wrf) zur Verfügung gestellt werden.

Beispiel 3: <ComboBox> mit Icons und einer ausgelagerten Optionsliste

In folgendem Beispiel ist die Verwendung des <ComboBox>-Elements mit Icons und einer ausgelagerten Optionsliste gezeigt. Die Optionen werden über einen Technical Process als Auswahloption zur Verfügung gestellt.

Optionsliste
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 mit Icons in der 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