13.1.13.4.2. Wert-Steuerelemente#

Dies sind die Steuerelemente, die eine Einstellung halten. Jedes trägt einen value, und Speichern schreibt den bearbeiteten value zurück in das Steuerelement. Die untenstehende Tabelle ist die schnelle Zuordnung vom Steuerelement zum JSON-Typ, den es speichert; die folgenden Abschnitte dokumentieren jeden Schlüssel.

Steuerelement

Speichert

checkbox

boolean oder integer 0/1/2

combobox

der gewählte Wert oder sein Index

radio

der gewählte Wert oder sein Index

spinbox

integer

doublespinbox

number (Fließkomma)

slider

integer

lineedit

string

Alle Wert-Steuerelemente akzeptieren zudem die allgemeinen Schlüssel (name, label, tooltip, enabled); siehe die Übersicht. Das label wird neben dem Steuerelement angezeigt (bei einer checkbox auf dem Kästchen selbst).

13.1.13.4.2.1. checkbox#

Ein Ein-/Aus-Schalter. Optional dreistufig, für Einstellungen, die eine „nicht gesetzte“ Mitte haben.

{ "type": "checkbox", "name": "draw_overlays", "label": "Draw Overlays", "value": true }

Argumente:

  • label (string) – der neben dem Kästchen angezeigte Text. Nur Klartext (im Gegensatz zu den anderen Steuerelementen, deren Labels Rich Text aufnehmen).

  • tristate (boolean, Standard false) – erlaubt einen dritten, teilweise aktivierten Zustand.

  • value – der Anfangszustand. Zweistufig: ein boolean. Tristate: 0 (aus), 1 (teilweise) oder 2 (an).

Speichert: einen boolean für ein zweistufiges Kästchen; einen integer 0, 1 oder 2 für ein Tristate-Kästchen.

13.1.13.4.2.2. combobox#

Ein Dropdown-Menü mit Auswahlmöglichkeiten.

{
  "type": "combobox",
  "name": "resolution",
  "label": "Resolution",
  "options": ["QQVGA", "QVGA", "VGA"],
  "values": ["qqvga", "qvga", "vga"],
  "value": "qvga"
}

Argumente:

  • options (array of strings) – die im Menü angezeigten Einträge.

  • values (array) – ein optionales paralleles Array der zu speichernden Werte, einer pro option. Mit values zeigt das Menü options[i] an, speichert aber values[i] – der Benutzer sieht also „QVGA“, während die Datei "qvga" speichert. Die Einträge können ein beliebiger JSON-Typ sein. Ohne values speichert das Steuerelement stattdessen den index des ausgewählten Eintrags.

  • value – die anfängliche Auswahl. Mit values der Eintrag, der einem der values entspricht. Ohne values der Index des auszuwählenden Eintrags (Standard 0).

Speichert: den passenden values-Eintrag (beliebiger Typ), wenn values angegeben ist; andernfalls den ausgewählten index (integer).

13.1.13.4.2.3. radio#

Eine Gruppe von Optionsfeldern – jeweils eine Auswahl sichtbar, wie eine combobox, aber vollständig ausgelegt.

{
  "type": "radio",
  "name": "mode",
  "label": "Mode",
  "options": ["Idle", "Track", "Record"],
  "values": ["idle", "track", "record"],
  "value": "idle",
  "orientation": "horizontal"
}

Argumente:

  • options (array of strings) – ein Button pro Eintrag.

  • values (array) – die optionalen zu speichernden Werte, einer pro option, genau wie bei combobox. Ohne sie speichert das Steuerelement den ausgewählten index.

  • value – die anfängliche Auswahl, abgeglichen mit values oder als Index verwendet, wie bei combobox.

  • orientation (string, Standard "vertical") – "horizontal", um die Buttons in einer Reihe anzuordnen, andernfalls eine Spalte.

Speichert: den passenden values-Eintrag (beliebiger Typ) oder den ausgewählten index.

13.1.13.4.2.4. spinbox#

Ein Zahlenfeld für Ganzzahlen, mit Aufwärts-/Abwärtspfeilen.

{
  "type": "spinbox",
  "name": "server_port",
  "label": "Port",
  "value": 8080,
  "min": 0,
  "max": 65535,
  "group_separator": true
}

Argumente:

  • value (integer, Standard 0) – die anfängliche Zahl.

  • min (integer, Standard 0 oder value, je nachdem, was kleiner ist) – der niedrigste zulässige Wert.

  • max (integer, Standard 100 oder value, je nachdem, was größer ist) – der höchste zulässige Wert.

  • step (integer, Standard 1) – das Aufwärts-/Abwärts-Inkrement.

  • prefix (string) – Text, der vor der Zahl angezeigt wird, z. B. "0x".

  • suffix (string) – Text, der nach der Zahl angezeigt wird, z. B. eine Einheit wie " px".

  • base (integer, Standard 10) – die Anzeigebasis; auf 16 setzen, um die Zahl in Hexadezimal anzuzeigen und zu bearbeiten.

  • group_separator (boolean, Standard false) – gruppiert die Ziffern mit Tausendertrennzeichen.

  • special_value_text (string) – Text, der anstelle der Zahl angezeigt wird, wenn sie bei min liegt, z. B. „Off“ bei 0 anzeigen.

Speichert: einen integer.

13.1.13.4.2.5. doublespinbox#

Ein Zahlenfeld für Dezimalzahlen.

{
  "type": "doublespinbox",
  "name": "sensitivity",
  "label": "Sensitivity",
  "value": 50.0,
  "min": 0,
  "max": 100,
  "step": 0.5,
  "decimals": 1,
  "suffix": " %"
}

Argumente:

  • value (number, Standard 0) – die anfängliche Zahl.

  • min (number, Standard 0 oder value, je nachdem, was kleiner ist) – der niedrigste zulässige Wert.

  • max (number, Standard 100 oder value, je nachdem, was größer ist) – der höchste zulässige Wert.

  • decimals (integer, Standard 2) – wie viele Ziffern nach dem Dezimalpunkt angezeigt werden.

  • step (number, Standard 1.0) – das Aufwärts-/Abwärts-Inkrement.

  • prefix (string) – Text, der vor der Zahl angezeigt wird, z. B. "max ".

  • suffix (string) – Text, der nach der Zahl angezeigt wird, z. B. eine Einheit wie " %".

  • group_separator (boolean, Standard false) – Tausendertrennzeichen.

  • special_value_text (string) – Text, der angezeigt wird, wenn die Zahl bei min liegt.

Speichert: eine number (Fließkomma).

13.1.13.4.2.6. slider#

Ein horizontaler Schieberegler mit einer numerischen Live-Anzeige daneben.

{
  "type": "slider",
  "name": "brightness",
  "label": "Brightness",
  "value": 50,
  "min": 0,
  "max": 100,
  "step": 1,
  "suffix": " %",
  "ticks": 25
}

Argumente:

  • value (integer, Standard 0) – die anfängliche Position.

  • min (integer, Standard 0 oder value, je nachdem, was kleiner ist) – das untere Ende der Bahn.

  • max (integer, Standard 100 oder value, je nachdem, was größer ist) – das obere Ende der Bahn.

  • step (integer, Standard 1) – das Tastatur- und Ziehinkrement; Ziehbewegungen rasten am nächsten Vielfachen ein.

  • prefix (string) – Text, der vor der numerischen Anzeige neben dem Schieberegler angezeigt wird, z. B. "x".

  • suffix (string) – Text, der nach der Anzeige angezeigt wird, z. B. " %".

  • ticks (integer) – der Abstand der unter der Bahn gezeichneten Teilstriche.

Speichert: einen integer.

13.1.13.4.2.7. lineedit#

Ein einzeiliges Textfeld, für Namen, Passwörter, Adressen und dergleichen.

{
  "type": "lineedit",
  "name": "hostname",
  "label": "Hostname",
  "value": "openmv-cam",
  "placeholder": "letters, digits, dashes",
  "regex": "[A-Za-z0-9-]+",
  "clear_button": true
}

Argumente:

  • value (string, Standard "") – der anfängliche Text.

  • placeholder (string) – grauer Hinweistext, der angezeigt wird, solange das Feld leer ist.

  • max_length (integer) – die maximale Anzahl von Zeichen, die das Feld akzeptiert.

  • mask (string) – eine Eingabemaske, die die Anordnung des Eingebbaren festlegt, z. B. "000.000.000.000;_" für eine IPv4-Adresse. Siehe Input masks unten.

  • regex (string) – ein regulärer Ausdruck, dem der gesamte Eintrag entsprechen muss. Siehe Regular expressions unten.

  • clear_button (boolean, Standard false) – zeigt einen kleinen Löschbutton innerhalb des Feldes an.

  • password (boolean, Standard false) – verbirgt den Text als Punkte und fügt einen Augen-Button hinzu, um ihn anzuzeigen.

Speichert: einen string.

Eine mask und ein regex beschränken beide, was das Feld akzeptiert, aus entgegengesetzten Blickwinkeln – eine Maske legt die Anordnung des Textes fest, ein Regex beschränkt seinen Inhalt. Ein Feld mit einem der beiden ist das einzige Steuerelement, das ein Speichern blockieren kann: wenn sein Text unvollständig ist oder nicht passt, listet der Editor das Feld anhand seines label auf und verweigert das Speichern, bis es korrigiert oder geleert ist. Verwenden Sie höchstens eines der beiden bei einem Feld.

13.1.13.4.2.7.1. Eingabemasken#

Eine mask legt das Feld Zeichen für Zeichen fest: Trennzeichen werden für den Benutzer eingezeichnet, der nur die Lücken füllt. Jedes Maskenzeichen steht für eine Eingabeposition:

  • 9 – eine erforderliche Ziffer; 0 – eine optionale Ziffer.

  • A / a – ein erforderlicher / optionaler Buchstabe.

  • N / n – ein erforderlicher / optionaler Buchstabe oder eine Ziffer.

  • X / x – ein erforderliches / optionales Zeichen beliebiger Art.

  • H / h – eine erforderliche / optionale Hexadezimalziffer.

  • > / < – wandelt die folgenden Buchstaben in Groß- / Kleinschreibung um; ! stoppt die Umwandlung.

Jedes andere Zeichen – der . in 000.000.000.000, ein - in einer Seriennummer – ist ein wörtliches Trennzeichen: es wird automatisch platziert und beim Tippen übersprungen. Um ein Maskenzeichen wörtlich zu verwenden, setzen Sie einen Backslash davor.

Ein ; gegen Ende legt den Platzhalter fest, der für nicht gefüllte Positionen angezeigt wird: "000.000.000.000;_" zeigt ein leeres Feld als ___.___.___.___ an. Lassen Sie es weg, und die Lücken sind Leerzeichen. Solange eine erforderliche Position noch leer ist, ist der Eintrag unvollständig, was das Speichern blockiert.

13.1.13.4.2.7.2. Reguläre Ausdrücke#

Ein regex prüft den Inhalt statt der Anordnung und passt besser, wenn die Regel „diese Zeichen, dieses Muster“ lautet und nicht ein festes Feld. Der gesamte Eintrag muss passen – der Ausdruck ist an beiden Enden verankert, sodass "[A-Za-z0-9-]+" nur Buchstaben, Ziffern und Bindestriche von Anfang bis Ende bedeutet, nicht bloß „enthält eines“.

Die Prüfung läuft bei jedem Tastenanschlag. Ein Zeichen wird akzeptiert, solange der Text noch zu einer vollständigen Übereinstimmung heranwachsen könnte, und in dem Moment abgelehnt, in dem er es nicht mehr könnte, sodass der Benutzer sich nie zu etwas Ungültigem tippen kann. Das Feld gilt erst dann als gültig – und das Speichern ist erlaubt –, wenn der gesamte Ausdruck passt; ein Teileintrag auf dem Weg dorthin bleibt bestehen, blockiert aber das Speichern, bis er vollständig ist.

Um ein Muster zu erstellen und zu testen, erklärt regex101.com jeden Teil während der Eingabe – stellen Sie seinen Dialekt auf PCRE2 ein, die vom Editor verwendete Syntax.