Die CpTextField Klasse ist von der CpField Klasse abgeleitet. Sie implementiert Ein-/Ausgabefelder für Texte und Zahlen.
Ein Objekt der Klasse CpTextField wird mit der Funktion AddTextField() erzeugt und einem ControlPanel zugewiesen.
}
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.
| 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. |
| LowerLimit, UpperLimit | Wenn die Eingabe eine dieser Limiten überschreitet, wird der Wert auf die entsprechende Limite gesetzt. |
| 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 |
| 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( Parameter )
}
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.LowerLimit, UpperLimit: Number; ReadOnly; Init = undefined
Wenn einer dieser Limiten definiert ist und die Benutzereingabe eine dieser Limiten überschreitet, wird die Eingabe auf die entsprechende Limite korrigiert.
Der Wert der Limiten bezieht sich auf den Wert wie er im Modell gespeichert wird. Dies muss beachtet werden, wenn ein Multiplikator Mult oder eine Funktion installiert wird, welche die Eingabewerte umrechnet, bevor sie gegen die Limiten getestet und im Modell gespeichert werden.
Wenn das Textfeld mit einem Slider gekoppelt ist, sollte der Slider-Bereich Min und Max nicht grösser als diese Limiten gesetzt werden! Kleiner ist kein Problem.
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:
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: 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: Object; Private; Init = null
Wenn die Units eines Textfeldes über externe properties verändert werden sollen, kann man die entsprechenden Referenzen auf die 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
}
Wenn MultRef, FormatRef, DigitsRef oder UnitsRef definiert werden, haben diese prioritä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: 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: 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: