WaBis

walter.bislins.ch

CP: TextField

Die CpTextField Klasse ist von der CpField Klasse abgeleitet. Sie implementiert Ein-/Ausgabefelder für Texte und Zahlen.

CpTextField Klasse

Ein Objekt der Klasse CpTextField wird mit der Funktion AddTextField() erzeugt und einem ControlPanel zugewiesen.

CpTextField : CpField = {
Panel: ControlPanel; Inherited; ReadOnly; Init = Parent ControlPanel
Name: String; Inherited; ReadOnly; Init = 'Field' + FieldCounter
Label: String; Inherited; ReadOnly; Init = Name
ValueRef: CpObjectRef; Inherited; Private; Init = [ModelRef + '.' +] Name
ReadOnly: Boolean; Inherited; ReadOnly; Init = ControlPanel.ReadOnly
ConvFromModelFunc: function(any):string; ReadOnly; Init = null
ConvToModelFunc: function(string):any; ReadOnly; Init = null
Enabled: Boolean; Inherited; Private; Init = true
EnabledRef: CpObjectRef; Inherited; Private; Init = ''
Description: String; Inherited; ReadOnly; Init = ''
Link: String; Inherited; ReadOnly; Init = ''
ColSpan: Integer(>0); Inherited; ReadOnly; Init = 1
Inc: Number(>=0); Inherited; ReadOnly; Init = 1
Mult: Number or [ SetModel(x), GetModel(x) ]; ReadOnly; Init = 1
Format: string; ReadOnly; Init = ControlPanel.Format
Digits: Integer(>=0); ReadOnly; Init = ControlPanel.Digits
Units: String; ReadOnly; Init = ''
UnitsData: Object; ReadOnly; Init = null
MultRef: CpObjectRef; ReadOnly; Init = ''
FormatRef: CpObjectRef; ReadOnly; Init = ''
DigitsRef: CpObjectRef; ReadOnly; Init = ''
UnitsRef: CpObjectRef; ReadOnly; Init = ''
HiliChanges: Boolean; ReadOnly; Init = ControlPanel.HiliChanges
DimmDefault: Boolean; ReadOnly; Init = ControlPanel.DimmDefault
Attr: String; Inherited; ReadOnly; Init = ''
}

Ein CpTextField stellt ein Ein-/Ausgabefeld dar, welches mit einer globalen Variablen oder einem Modell-Property verknüpft ist. Der Wert dieser Variablen oder dieses Property wird im Feld in vielen wählbaren Formaten dargestellt. Wenn das Feld nicht ReadOnly definiert wird, kann man den Wert im Feld verändern und diese Änderung wird an das Modell weitergereicht (siehe Funktionsprinzip).

Einige der Properties des Textfeldes werden von seiner Basis-Klasse, dem CpField, geerbt.

CpTextField Properties

Panel Verweis auf das übergeordnete ControlPanel Objekt. Das CpField Objekt wird in der Liste ControlPanel.Fields verlinkt.
Name Standardwert für Label und ValueRef
Label Label für das ControlPanel-Feld. Label dürfen HTML-Tags enthalten.
ValueRef Referenz auf eine globale Variable oder ein Objekt-Property.
ReadOnly true → Feld kann nicht verändert werden
Enabled false → Feld ist deaktiviert. Dieses Property kann nur mit der Funktion IsEnabled() abgefragt werden
EnabledRef Referenz auf ein Modell-Property, welches den Enabled-Zustand fernsteuert oder eine function, welche den enabled Zusatand berechnet.
Description wird eingeblendet, wenn die Maus über dem Label oder dem HelpImage steht
Link HTML- oder Wiki-Link zu einer Help-Seite mit der Beschreibung des Ein-/Ausgabefeldes.
ColSpan Anzahl Tabellen-Spalten, welche das Werte-Feld überspannen soll
Attr Zusätzliche HTML-Attribute für das Werte-Feld
ConvFromModelFunc Funktion, mit welcher ein oder mehrere Modellwerte in einen String für ein Textfeld aufbereitet werden können, wenn nicht nur eine einfache Zahl angezeigt werden soll.
ConvToModelFunc Funktion, mit welcher ein String eines Textfeldes in einen Modellwert konvertiert werden kann, falls dieser keine einfache Zahl ist, welche automatisch konvertiert werden kann.
Inc Wert um den eine Zahl in Feld erhöht oder erniedrigt werden soll, wenn die Pfeil auf/ab Tasten gedrückt werden.
Mult Eingabewerte werden mit Mult multipliziert, bevor sie im Modell gespeichert werden und durch Mult dividiert, wenn sie vom Modell gelesen werden
Format Zahlen-Formatierung
Digits Ausgabegenauigkeit der Zahlen (Anzahl Stellen)
Units Masseinheit, welche hinter dem Ein-/Ausgabefeld angezeigt werden soll
UnitsData Datenzusammenfassung anstelle von diversen XxxRef properties für variable units
MultRef Referenz auf ein Modell-Property, welches Mult definiert
FormatRef Referenz auf ein Modell-Property, welches Format definiert
DigitsRef Referenz auf ein Modell-Property, welches Digits definiert
UnitsRef Referenz auf ein Modell-Property, welches Units definiert
HiliChanges true → Wenn der Wert im Text-Feld nicht dem Initialwert entspricht, wird er farblich hervorgehoben
DimmDefault true → Wenn der vom Text-Feld referenzierte Modell-Wert noch nicht berechnet worden ist, wird der Wert grau dargestellt

CpTextField Funktionen

AddTextField() Erzeugt ein CpTextField und fügt es einem ControlPanel hinzu
GetType() Fragt den Typ des Feldes ab
GetValueRef() Gibt den String-Wert des ValueRef Properties zurück. Auf ValueRef darf nicht direkt zugegriffen werden.
IsEnabled() Gibt den Enabled-Zustand des Feldes zurück. Auf Enabled darf nicht direkt zugegriffen werden.
SetEnabled() Setzt den Enabled-Zustand des Feldes.
GetHtmlID() Gibt die HTML-ID eines ControlPanel-Feldes oder Items zurück
GetDomObj() Gibt eine Referenz auf das DOM-Element eines ControlPanel-Feldes oder Items zurück

ControlPanel.AddTextField()

ControlPanel.AddTextField( Parameter )

Parameter: TextFieldDef; Optional; Default = { }
Return this: ControlPanel
TextFieldDef = {
Name: String; Optional; Default = 'Field' + FieldCounter
Standardwert für Label und ValueRef. Teil des id und name Attributes des Input-Elementes.
Label: String; Optional; Default = Name
Label dürfen HTML-Tags enthalten. Verwende '-', wenn kein Label angezeigt werden soll.
ValueRef: String; Optional; Default = [ControlPanel.ModelRef + '.' +] Name
Referenz auf eine globale Variable oder ein Objekt-Property.
ConvFromModelFunc: function(any):string; Optional; Default = null
Funktion zur Konvertierung des Modellwertes ValueRef in einen Anzeigestring, falls nicht die Standardkonvertierung von Zahlen verwendet werden soll
ConvToModelFunc: function(string):any; Optional; Default = null
Funktion zur Konvertierung des Strings im Eingabefeld zur Speicherung im Modell ValueRef, falls nicht die Standardkonvertierung von Zahlen verwendet werden soll
Format: String; Optional; Default = ControlPanel.Format
Format der Zahlendarstellung.
FormatRef: String; Optional; Default = ''
Falls definiert, wird das Format von dieser Modell-Referenz übernommen.
Digits: Number(>=0); Optional; Default = ControlPanel.Digits
Anzahl dargestellte Ziffern, abhängig vom Format.
DigitsRef: String; Optional; Default = ''
Falls definiert, wird Digits von dieser Modell-Referenz übernommen.
Mult: Number or [ SetModel(x), GetModel(x) ]; Optional; Default = 1
Multiplikator zwischen Modell und Text-Field.
UnitsData: Object; Optional; Default = null
Falls definiert werden die entsprechenden XxxRef properties gesetzt
MultRef: String; Optional; Default = ''
Falls definiert, wird Mult von dieser Modell-Referenz übernommen.
Units: String; Optional; Default = ''
Masseinheit, welche hinter dem Eingabefeld angezeigt wird.
UnitsRef: String; Optional; Default = ''
Falls definiert, wird Units von dieser Modell-Referenz übernommen.
ReadOnly: Boolean; Optional; Default = ControlPanel.ReadOnly
true → Element kann nicht verändert werden.
Enabled: Boolean; Optional; Default = true
false → Element ist deaktiviert und wird ausgegraut angezeigt
EnabledRef: String; Optional; Default = ''
Falls definiert, wird Enabled von dieser Modell-Referenz gesteuert
HiliChanges: Boolean; Optional; Default = ControlPanel.HiliChanges
true → geänderte Werte werden hervorgehoben (z.B. rote Schrift).
DimmDefault: Boolean; Optional; Default = ControlPanel.DimmDefault
true → noch nicht berechnete Werte von ReadOnly-Textfeldern werden gedimmt angezeigt.
Description: String; Optional; Default = ''
Beschreibung wird eingeblendet, wenn die Maus über dem Label oder HelpImage steht. Die Beschreibung darf HTML-Tags enthalten.
Link: String; Optional; Default = ''
HTML- oder Wiki-Link zu einer Help-Seite.
ColSpan: Integer(>0); Optional; Default = 1
Anzahl Tabellen-Spalten, welche das Werte-Feld überspannen soll.
Inc: Number(>=0); Optional; Default = 1
Schrittweite für Pfeil auf/ab in Textfeld
Attr: String; Optional; Default = ''
Zusätzliche Attribute für die Werte-Zelle
}

CpTextField.ConvFromModelFunc, ConvToModelFunc

CpTextField.ConvFromModelFunc: function(any):string; ReadOnly 
CpTextField.ConvToModelFunc: function(string):any; ReadOnly 

Falls in einem Textfeld nicht bloss eine einfache Zahl dargestellt werden soll, kann über diese Funktionen der Modell-Wert ValueRef entsprechend formatiert und rückgewandelt werden.

Anwendungsbeispiel:

In einem Textfeld soll eine Kombination von zwei Zahlen der Form '<n> of <total>' dargestellt werden, wobei n und total zwei Modell-Properties sind. Dem Textfeld ist in ValueRef n zugewiesen.

form.AddTextField( {
  Name: 'n',
  ConvFromModelFunc: function( n ) {
    return n + ' of ' + model.total;
  },
  ConvToModelFunc: function( s ) {
    return parseInt( s );
  },
  :
} );

CpTextField.Format, Digits

CpTextField.Format: String; ReadOnly; Init = ControlPanel.Format 
CpTextField.Digits: Integer(>=0,<17); ReadOnly; Init = ControlPanel.Digits 

Das Format definiert die Formatierung von Zahlen im Ein-/Ausgabefeld, wobei Digits die Genauigkeit angibt, welche je nach Format unterschiedlich interpretiert wird.

Format und Digits können global für alle Text-Felder eines ControlPanel oder für jedes CpTextField separat gesetzt werden.

Wenn beim CpTextField Format oder Digits nicht definiert sind, werden Format bzw. Digits des ControlPanel übernommen.

Die Formatierung der Zahlen eines Text-Feldes übernimmt der NumFormatter. Einige Grundeinstellungen können direkt am NumFormatter eingestellt werden. Zahlenformat und Genauigkeit können für jedes Text-Feld separat eingestellt werden. Folgende Formate stehen zur Verfügung:

''
Natives JavaScript-Format, wie es die Funktion Number.toString() produziert.
'std'
Standardformat: Dieses Format ist vergleichbar mit dem Standard-Format von JavaScript Number.toString(), wobei jedoch auf Digits Stellen gerundet wird.
'fix0'
Fix-Format: Es werden immer Digits Nachkommastellen angezeigt. Wenn die Zahl eine bestimmte Länge überschreitet, wird auf das Format 'sci' oder 'eng' umgeschaltet (einstellbar im NumFormatter).
'fix'
Wie 'fix0', jedoch werden Nullen nach dem Dezimalpunkt abgeschnitten.
'weak0'
Schwaches Fix-Format: Wie 'fix', jedoch werden sehr kleine Zahlen nicht als 0.00... dargestellt, sondern es wird in das Format 'sci' oder 'eng' umgeschaltet. Dieses Format entspricht am ehesten dem Fix-Format eines Taschenrechners.
'weak'
Wie 'weak0', jedoch werden Nullen nach dem Dezimalpunkt abgeschnitten.
'prec'
Es werden immer Digits gerundete Stellen angezeigt, auch wenn diese 0 sind. Man sieht der Zahl also an, wie viele Stellen relevant sind.
'sci'
Wissenschaftliches Format: Es werden immer Digits gerundete Stellen und ein Exponent angezeigt. Es ist immer genau eine Ziffer vor dem Dezimalpunkt.
'eng'
Ingenieur-Format: Es werden Digits gerundete Stellen, jedoch mindestens 3 Stellen, und ein Exponent angezeigt. Der Exponent zählt in 3-er Schritten und die Mantisse hat entsprechend vor dem Dezimalpunkt 1 bis 3 Ziffern. In dieser Darstellung kann man am besten Tausender-Einheiten erfassen (Milli, Kilo, Mega usw.).
'unit'
Entspricht dem 'eng' Format, wobei jedoch anstelle eines Exponenten Eingeitsgrössen wie Milli (m), Kilo (k), Mega (M) usw. hinter der Zahl und vor Units angezeigt werden. Wenn die Zahl einen Bereich überschreitet, für den entsprechende Einheitsgrössen definiert sind, wird in das 'eng' Format umgeschaltet.

CpTextField.Mult

CpTextField.Mult: Number or [ SetModel(x), GetModel(x) ]; ReadOnly; Init = 1 

Eine Zahl im Eingabefeld wird mit Mult multipliziert, bevor sie im Modell gespeichert wird. Umgekehrt wird eine Modell-Zahl durch Mult dividiert, bevor sie im Eingabefeld angezeigt wird. Wenn Mult = 0 ist, wird die Eingabe des Feldes nicht verarbeitet sondern direkt im Modell gespeichert. Auf diese Weise können reine Text-Felder implementiert werden (Strings).

Mit diesem Mechanismus können Eingabefelder Modell-Werte in anderen Einheiten anzeigen. Wenn z.B. das Modell Werte in Metern speichert, kann mit Mult = 1000 der User Werte in km eingeben und die Modellwerte werden ebenfalls in km angezeigt. Es sind auch beliebig kompliziertere Umrechnungen möglich wie Lichtjahre, Parsec, Astronomische Einheiten (AE) usw, in Meter.

Wenn die Umrechnung zwischen Modell-Variablen und Anzeigewert nicht durch einen einfachen Faktor bewerkstelligt werden kann, kann man auch zwei Umrechnungsfunktionen in einem Array übergeben. Hat man zum Beispiel ein Eingabefeld für eine Temperatur, welche in Fahrenheit angezeigt wird, aber im Modell muss der Wert in Kelvin vorliegen, so kann man die Umrechnung folgendermassen festlegen:

function ConvertKelvinToFahrenheit( t ) { return t * 1.8 - 459.67; }
function ConvertFahrenheitToKelvin( t ) { return (t + 459.67) / 1.8; }

myForm.AddTextField( {
  Mult: [ ConvertFahrenheitToKelvin, ConvertKelvinToFahrenheit ],
   :
} );

Siehe auch MultRef und UnitsData.

CpTextField.Units

CpTextField.Units: String; ReadOnly; Init = '' 

Mit Units kann definiert werden, welche Masseinheit hinter dem Eingabefeld angezeigt werden soll. Wenn das Zahlenformat Format = 'unit' ist, werden automatisch Einheiten-Vorsätze wie Milli (m), Kilo (k), Mega (M) usw. vor die Units gesetzt.

Mit <sup> und <sub> können auch hoch- und tiefgestellte Texte definiert werden. Z.B. kann man Quadratmeter wiefolgt definieren: Units = 'm<sup>2</sup>'.

Siehe auch UnitsRef.

CpTextField.UnitsData

CpTextField.UnitsData: Object; Private; Init = null 

Wenn die Units eines Textfeldes über externe properties verändert werden sollen, kann man die entsprechenden Referenzen auf steuernden Properties entweder mit MultRef, FormatRef, DigitsRef und UnitsRef definieren, oder in einem einzelnen Object dem Property UnitsData zuweisen.

Das UnitsData Object muss folgendes Format haben:

UnitsDataObject = {
  Selection: integer | string(propertyName),
  Mults: array of number | array[2] of function(converterFunction),
  Units: array of string,
  Formats: array of string,
  Digits: array of string
}
Selection
definiert, welche unit momentan verwendet werden soll. Ist entweder ein Index in eine der Tabellen Mults bis Digits oder ein String der ein Property referenziert, in welchem der Index gespeichert ist. So kann ein einzelnes Index Property mehrere Text Felder Units gleichzeitig steuern.
Selection kann ein Property eines globalen Objectes Referenzieren: 'Object.Selection' oder ein Property des im zugehörigen Panel definierten ModelRef '.Selection''ModelRef.Selection.
Mults
definiert die verschiedenen Multiplikatoren, siehe Mult.
Units
(optional) definiert die verschiedenen Einheiten, siehe Units.
Formats
(optional) definiert verschiedenen Zahlen-Formatierungen, siehe Format.
Digits
(optional) definiert verschiedenen Ausgabe Genauigkeiten, siehe Digits.

Wenn MultRef, FormatRef, DigitsRef oder UnitsRef definiert werden, haben diese proprität vor UnitsData.

Beispiel

var MyApp = {
  myLength: 0,
  LengthUnits: {
    Selection: 0,
    Units: [ 'm', 'mi', 'ft' ],
    Mults: [ 1, 1609.344, 0.3048 ]
  },
  :
};

ControlPanels.NewSliderPanel( {
  ModelRef: 'MyApp',
  OnModelChange: UpdateAll,

} ).AddValueSliderField( {
  Name: 'myLength',
  Label: 'Length',
  UnitsData: 'LengthUnits',
  Min: 0,
  Max: 5,

} ).AddRadiobuttonField( {
  Name: 'LengthUnits.Selection',
  Label: 'Units',
  ValueType: 'int',
  Items: [
    {
      Name: 'm',
      Value: 0
    }, {
      Name: 'mi',
      Value: 1
    }, {
      Name: 'ft',
      Value: 2
    }
  ]

} ).Render();

Wenn für mehrere Units ein gemeinsamer Index verwendet werden soll, um zum Beispiel zwischen metrischen und imperialen Untis umzuschalten, kann das Property Selection auf ein gemeinsames Selection-Property verweisen:

var MyApp = {
  unitsSelection: 0,
  myLength: 0,
  LengthUnits: {
    Selection: '.unitsSelection',  // or 'MyApp.unitsSelection'
    Units: [ 'm', 'mi', 'ft' ],
    Mults: [ 1, 1609.344, 0.3048 ]
  },
  :
};

ControlPanels.NewSliderPanel( {
  ModelRef: 'MyApp',
  OnModelChange: UpdateAll,

} ).AddValueSliderField( {
  Name: 'myLength',
  Label: 'Length',
  UnitsData: 'LengthUnits',
  Min: 0,
  Max: 5,

} ).AddRadiobuttonField( {
  Name: 'unitsSelection',
  Label: 'Units',
  ValueType: 'int',
  Items: [
    {
      Name: 'm',
      Value: 0
    }, {
      Name: 'mi',
      Value: 1
    }, {
      Name: 'ft',
      Value: 2
    }
  ]

} ).Render();

CpTextField.MultRef, FormatRef, DigitsRef, UnitsRef

CpTextField.MultRef: CpObjectRef; Private; Init = null 
CpTextField.FormatRef: CpObjectRef; Private; Init = null 
CpTextField.DigitsRef: CpObjectRef; Private; Init = null 
CpTextField.UnitsRef: CpObjectRef; Private; Init = null 

Referenzen auf eine globale Variable oder ein Objekt-Property. Diese Werte können nicht ausgelesen werden. Sie werden nur für interne Zwecke verwendet. Beim Erzeugen eines CpTextField mit AddTextField() werden diese Properties als String vorgegeben. Intern werden diese Strings in ein CpObjectRef umgewandelt.

Die Parameter Mult, Format, Digits und Units müssen nicht beim CpTextField festgelegt werden, sondern können auch über eine Modell-Referenz dynmisch bezogen werden. Wenn eine Modell-Referenz per MultRef, FormatRef, DigitsRef bzw. UnitsRef definiert ist, wird das entsprechende Property Mult, Format, Digits bzw. Units irgnoriert.

Wenn ControlPanel.ModelRef nicht definiert ist, verweist XxxRef entweder auf eine globale Variable oder direkt auf ein Modell-Property. Wenn ControlPanel.ModelRef eine globale Variable referenziert, verweist XxxRef auf ein Property des Modells, das dieser Variablen zugewiesen ist. Wenn jedoch XxxRef einen Punkt enthält, wird ControlPanel.ModelRef ignoriert:

ModelRef = '';         XxxRef = 'Variable'          → Variable
ModelRef = 'Variable'; XxxRef = 'Property'          → Objekt.Property
ModelRef = ?;          XxxRef = 'Variable.Property' → Objekt.Property

Es sind auch Referenzen auf Objekt-Properties eines Modells möglich. Zum Beispiel:

ModelRef = 'Model.Child'; XxxRef = 'Prop' → 'Model.Child.Prop'

Hinweis: Sobald XxxRef einen Punkt enthält, wird ControlPanel.ModelRef ignoriert!

CpTextField.Inc

CpTextField.Inc: Number; ReadOnly; Init = 1 

In einem Textfeld können Zahlen mit den Pfeiltasten auf/ab erhöht und erniedrigt werden. Mit Ctrl-Pfeil wird der Wert um 10*Inc verändert, mit Alt-Pfeil wird um Inc/10 verändert und mit Ctrl-Alt-Pfeil wird um Inc/100 verändert.

Wenn Format = 'fix' oder 'fix0' ist, bestimmt Digits den Standardwert für Inc wiefolgt:

  • Digits = 2: Inc = 0.1
  • Digits > 2: Inc = 0.01
  • sonst: Inc = 1

CpTextField.HiliChanges

CpTextField.HiliChanges: Boolean; ReadOnly; Init = ControlPanel.HiliChanges 

true → geänderte Werte werden hervorgehoben (rote Schrift).

HiliChanges kann global für ein ganzes ControlPanel Objekt oder für individuelle CpTextField Objekte separat gesetzt werden. Wenn beim CpTextField Objekt HiliChanges nicht definiert wird, gilt HiliChanges des zugehörigen ControlPanel Objektes.

Wenn bei einem CpTextField HiliChanges = true ist und das CpTextField editierbar ist (ReadOnly = false), wird der Wert hervorgehoben, sobald er vom initialen Wert abweicht. Durch Drücken der Esc-Taste, wenn der Cursor in diesem Text-Feld steht, oder durch Löschen des Inhaltes und drücken der Enter-Taste, wird der Wert im Text-Feld auf den initialen Wert zurückgesetzt.

Durch Umdefinieren der Klasse Changed kann das Aussehen eines hervorgehobenen Feldes bestimmt werden:

<style>
table.ControlPanel input.Changed { /* styles */ }
</style>

CpTextField.DimmDefault

CpTextField.DimmDefault: Boolean; ReadOnly; Init = ControlPanel.DimmDefault 

true → noch nicht berechnete Werte von ReadOnly-Textfeldern werden gedimmt angezeigt.

DimmDefault kann global für ein ganzes ControlPanel Objekt oder für individuelle CpTextField Objekte separat gesetzt werden. Wenn beim CpTextField Objekt DimmDefault nicht definiert wird, gilt DimmDefault des zugehörigen ControlPanel.

Wenn bei einem CpTextField DimmDefault = true ist und das CpTextField nicht editierbar ist (ReadOnly = true), wird der Wert gedimmt dargestellt, solange dieser noch nicht berechnet worden ist. Sobald das erste Mal die Funktion Update() ausgeführt wird, werden gedimmte Werte normal angezeigt.

Durch Umdefinieren der Klasse Dimmed kann das Aussehen eines gedimmten Feldes verändert werden:

<style>
table.ControlPanel input.Dimmed { /* styles */ }
</style>

Weitere Infos zur Seite
Erzeugt Montag, 8. August 2016
von wabis
Zum Seitenanfang
Geändert Mittwoch, 12. September 2018
von wabis