WaBis

walter.bislins.ch

CP: ControlPanel

ControlPanel werden z.B. mit der Funktion ControlPanels.NewPanel() erzeugt. Mit Feld-Funktionen werden die verschiedenen Ein-/Ausgabe-Elemente in den Zellen eines ControlPanel Objektes erzeugt.

ControlPanel Klasse

Ein ControlPanel-Objekt verwaltet ein mehrspaltiges Tabellen-Layout mit Labeln und Ein-/Ausgabe-Elementen. ö

ControlPanel = {
Name: String; ReadOnly; Init = 'ControlPanel' + ControlPanels.Counter
ModelRef: String; ReadOnly; Init = ''
NCols: Integer(>0); ReadOnly; Init = 1
OnModelChange: Function; ReadOnly; Init = null
Format: String; ReadOnly; Init = 'fix'
FormatTab: Boolean; ReadOnly; Init = true
Digits: Integer(>=0); ReadOnly; Init = 2
ReadOnly: Boolean; ReadOnly; Init = false
Enabled: Boolean; Private; Init = true
EnabledRef: CpObjectRef; Private; Init = ''
HiliChanges: Boolean; ReadOnly; Init = false
DimmDefault: Boolean; ReadOnly; Init = false
Attr: String; ReadOnly; Init = ''
PanelFormat: Sring; ReadOnly; Init = ''
PanelClass: String; ReadOnly; Init = 'ControlPanel'
HelpImage: String; ReadOnly; Init = 'q.gif'
ValuePos: String; ReadOnly; Init = 'left'
FieldCounter: Integer(>=0); ReadOnly; Init = 0
Fields: Array of CpField; ReadOnly; Init = [ ]
}

Ein ControlPanel-Objekt wird mit der Funktion ControlPanels.NewPanel() erzeugt. Mit AddHeader() können Überschriften definiert werden und mit diversen Funktionen wie AddTextField(), AddSliderField() usw. können verschiedenen Ein- und Ausgabefelder erzeugt werden. Der zugehörige HTML-Code wird mit der Funktionen Render() in die Webseite eingebaut, nachdem die Tabelle vollständig aufgebaut ist.

Ein ControlPanel-Objekt enthält einige Properties, welche an bestimmte ControlPanel-Felder vererbt werden oder mit Properties von Feldern kombiniert werden.

Die Properties eines ControlPanel Objektes dürfen nur gelesen werden. Ihre Werte werden beim Erzeugen des Objektes mit ControlPanels.NewPanel() festgelegt.

ControlPanel Properties

Name Teil der HTML-ID der Tabelle und der Tabellen-Felder
ModelRef Name einer globalen Variablen, welcher das Modell zugewiesen ist
OnModelChange wird aufgerufen, nachdem das Modell durch Userinteraktion geändert wurde
NCols Anzahl Layout-Spalten. Eine Layout-Spalte entspricht 2 Tabellen-Spalten
Format Format der Zahlendarstellung. Standardwert für CpTextFields
FormatTab Bestimmt die Zahlengruppierung bei nur 4 Stelligen Zahlen
Digits Anzahl dargestellte Ziffern, abhängig vom Format. Standardwert für CpTextFields
Attr Zusätzliche Attribute für die Tabelle
PanelFormat Zusätzliche Klassen zur Formatierung der ControlPanel-Tabelle bzw. deren Felder
PanelClass Klasse, welche der Tabelle zugewiesen wird (default ControlPanel)
ReadOnly true → Wert im Eingabefeld kann nicht verändert werden. Standardwert für CpTextFields
Enabled false → Felder sind deaktiviert. Enabled wird als Standardwert an die Felder des Panels verwendet.
EnabledRef Referenz auf ein Modell-Property, welches den Enabled-Zustand fernsteuert. Dieser Wert dient als Standardwert für die Felder des Panels
HiliChanges true → Geänderte Werte werden hervorgehoben (z.B. rote Schrift). Standardwert für CpTextFields
DimmDefault true → Noch nicht berechnete Werte von ReadOnly Text-Feldern werden gedimmt angezeigt. Standardwert für CpTextFields
HelpImage Pictogramm, welches hinter einem Feld angezeigt wird, wenn Link definiert ist
Fields Liste der ControlPanel-Felder
FieldCounter Zählt die Felder der Tabelle. Teil von Standard-Feld-Namen
ValuePos Gibt an, ob die Funktion AddValueSliderField() das Werte-Feld links oder rechts des Sliders platzieren soll

ControlPanel Funktionen

ControlPanel Konstruktoren

NewPanel() Erzeugt ein ControlPanel
NewSliderPanel() Erzeugt ein spezielles Panel nur für Slider-Felder

Feld-Funktionen

AddHeader() Erzeugt eine Überschrift in einem ControlPanel Objekt
AddEmptyField() Erzeugt ein CpHtmlField ohne Text in einem ControlPanel Objekt
AddHtmlField() Erzeugt ein CpHtmlField in einem ControlPanel Objekt
AddTextField() Erzeugt ein CpTextField in einem ControlPanel Objekt
AddSliderField() Erzeugt ein CpSliderField in einem ControlPanel Objekt
AddCheckboxField() Erzeugt ein CpCheckboxField in einem ControlPanel Objekt
AddRadiobuttonField() Erzeugt ein CpRadiobuttonField in einem ControlPanel Objekt
GetField() Sucht ein bestimmtes Feld in der Fields Liste des ControlPanel

Verwaltungs-Funktionen

Render() Schreibt den HTML-Code des ControlPanel in die Webseite
GetHtml() Erzeugt den HTML-Code des ControlPanel und gibt ihn als String zurück
Init() Liest die aktuellen Modell-Werte als Standardwerte für die ControlPanel-Felder
Update() Liest die aktuellen Modell-Werte und zeigt sie in den ControlPanel-Feldern an
UpdateLayout() Veranlasst die Neuberechnung der Grössen der ControlPanel-Felder. Diese Funktion wird automatisch gerufen, wenn die Fenstergrösse oder das Layout der Webseite geändert wurde.
IsDisplayed() gibt true zurück, wenn das ControlPanel und alle übergeordneten Dom-Elemente sichtbar sind.
Invalidate() Erzwingt ein Update aller ControlPanel-Felder beim nächsten Aufruf von Update()
Reset() Setzt alle Modell-Properties auf die Standardwerte zurück
IsEnabled() Gibt true zurück, wenn ein bestimmtes Feld aktiviert ist
SetEnabled() Setzt den Zustand Enabled eines oder mehrerer Felder
Delete() Löscht das ControlPanel und gibt den Speicher Frei
GetHtmlID() Gibt die HTML-ID eines ControlPanel zurück
GetDomObj() Gibt eine Referenz auf das DOM-Element (eine HTML-Tabelle) eines ControlPanel zurück

ControlPanels.NewPanel()

ControlPanels.NewPanel( Parameter )

Parameter: ControlPanelDef; Optional; Default = { }
Return: ControlPanel

Beachte, dass NewPanel() eine Memberfunktion der Klasse ControlPanels ist und nicht der Klasse ControlPanel (ohne s am Ende)!

Erzeugt ein ControlPanel Objekt und initialisiert es entsprechend den Angaben in Parameter.

Alle Funktionen zum Erzeugen von ControlPanel-Feldern geben dieses ControlPanel Objekt zurück. Damit lassen sich die Funktionsaufrufe verknüpfen. Wenn nur ein einziges ControlPanel Objekt pro Seite benötigt wird, muss man das ControlPanel Objekt nicht einmal einer Variablen zuweise. Die Funktion Update() kann für alle ControlPanels einer Seite über ControlPanels.Update() aufgerufen werden.

ControlPanelDef

ControlPanelDef = {
Name: String; Optional; Default = 'ControlPanel' + ControlPanels.Counter
Name und HTML-ID des Panels. Counter ist eine fortlaufende Nummer 1..N. Die id und name Attribute von ControlPanel-Feldern setzen sich zusammen aus Name und CpField.Name.
ModelRef: String; Optional; Default = ''
Name einer globalen Variablen, welcher das Modell zugewiesen ist.
NCols: Integer(>0); Optional; Default = 1
Anzahl Layout-Spalten. Eine Layout-Spalte entspricht 2 Tabellen-Spalten.
OnModelChange: Function(CpField,Value:Any); Optional; Default = null
wird aufgerufen, nachdem das Modell durch Userinteraktion geändert wurde.
Format: String; Optional; Default = 'fix'
Format der Zahlendarstellung. Standardwert für CpTextFields.
FormatTab: Boolean; Optional; Default = true
Bestimmt die Zahlengruppierung bei nur 4 Stelligen Zahlen
Digits: Integer(>=0); Optional; Default = 2
Anzahl dargestellte Ziffern, abhängig vom Format. Standardwert für CpTextFields.
ReadOnly: Boolean; Optional; Default = false
true → Wert im Eingabefeld kann nicht verändert werden. Standardwert für CpTextFields.
Enabled: Boolean; Optional; Default = true
false → Werte in Feldern können nicht verändert werden. Dieser Wert dient als Standardwert für die Felder des Panels.
EnabledRef: CpObjectRef; Optional; Default = ''
Referenz auf ein Modell-Property, welches den Enabled-Zustand fernsteuert. Dieser Wert dient als Standardwert für die Felder des Panels.
HiliChanges: Boolean; Optional; Default = false
true → Geänderte Werte werden hervorgehoben (z.B. rote Schrift). Standardwert für CpTextFields.
DimmDefault: Boolean; Optional; Default = false
true → Noch nicht berechnete Werte von ReadOnly Text-Feldern werden gedimmt angezeigt. Standardwert für CpTextFields.
Attr: String; Optional; Default = ''
Zusätzliche Attribute für die Tabelle, z.B: 'style="background:yellow"'
PanelFormat: Sring; Optional; Default = ''
Zusätzliche Klassen zur Formatierung der ControlPanel bzw. deren Felder.
PanelClass: String; Optional; Default = 'ControlPanel'
Standardklasse, welche der ControlPanel-Tabelle zugewiesen wird.
HelpImage: String; Optional; Default = 'q.gif'
Pictogramm, welches hinter einem Feld angezeigt wird, wenn Link definiert ist.
ValuePos: String; Optional; Default = 'left'
Position des Werte-Feldes neben einem Slider: 'left' oder 'right'. Dieses Property hat nur bei Slider-Panels eine Bedeutung, siehe NewSliderPanel()
AutoInit: Boolean; Optional; Default = true
true → die Funktion Init() wird automatisch nach dem Lader der Seite gerufen
}

ControlPanels.NewSliderPanel()

ControlPanels.NewSliderPanel( Parameter )

Parameter: ControlPanelDef; Optional; Default = { }
Return: ControlPanel

Beachte, dass NewSliderPanel() eine Memberfunktion der Klasse ControlPanels ist und nicht der Klasse ControlPanel (ohne s am Ende)!

Erzeugt ein ControlPanel über die Funktion NewPanel(). Dieses ControlPanel ist speziell für ein Formular mit Slidern und zugehörigen Werte-Feldern gemacht. Ein entsprechender Slider mit Werte-Feld kann mit der Funktion AddValueSliderField() erzeugt werden.

Wenn NCols in Parameter nicht definiert ist, wird NCols = 1 gesetzt, was einer Tabelle mit 4 Spalten entspricht. Diese sind wiefolgt aufgeteilt:

ValuePos Spalte1 Spalte2 Spalte3 Spalte4
'left' Label Wertefeld Slider
'right' Label Slider Wertefeld

Wenn NCols = 2 gesetzt wird, hat die Tabelle entsprechend 8 Kolonnen.

Dem Property PanelFormat werden die Klassen Slider Left oder Slider Right je nach Wert von ValuePos hinzugefügt. Die Spalten-Zellen der Tabelle erhalten die Klassen Label, Value und Slider. Über Standard-CSS werden die Spaltenbreiten passend formatiert (siehe ControlPanel.inc).

ControlPanel.Name

ControlPanel.Name: String; ReadOnly; Init = 'ControlPanel' + ControlPanels.Counter 

Counter ist eine fortlaufende Nummer 1..N. Jede ControlPanel-Tabelle bekommt eine HTML-ID. Über die HTML-ID kann die Tabelle per JavaScript oder Stylesheet referenziert werden.

Der ControlPanel.Name wird Bestandteil der id und name Attribute von Feld-Elementen:

Input-ID         = ControlPanel.Name + '-' + CpField.Name
TextFieldUnit-ID = ControlPanel.Name + '-' + CpField.Name + '-Unit'
HtmlField-ID     = ControlPanel.Name + '-' + CpField.Name
Slider-ID        = ControlPanel.Name + '-' + CpField.Name + '-Slider'
Radiobutton-Name = ControlPanel.Name + '-' + CpRadiobuttonItem.Name
Radiobutton-ID   = ControlPanel.Name + '-' + CpRadiobuttonItem.Name + '-' + i
Checkbox-Name    = ControlPanel.Name + '-' + CpCheckboxItem.Name
Checkbox-ID      = ControlPanel.Name + '-' + CpCheckboxItem.Name

ControlPanel.ModelRef

ControlPanel.ModelRef: String; ReadOnly; Init = '' 

Optionaler Name einer globalen Variablen, welcher das Modell zugewiesen ist.

Die Verknüpfung eines Ein-/Ausgabe-Elementes mit einem Objekt-Property kann entweder ganz mit dem Parameter ValueRef eines Feldes erfolgen, oder über die Kombination ModelRef und ValueRef. Wenn alle Felder mit Properties des selben Modells verknüpft werden sollen, bietet es sich an, in ModelRef auf das Modell zu verweisen und in ValueRef jeweils nur das entsprechende Modell-Property anzugeben. Es sind folgende Kombinationen möglich:

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

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

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

Achtung: Sobald ValueRef einen Punkt enthält, wird ModelRef ignoriert!

ControlPanel.OnModelChange

ControlPanel.OnModelChange: Function(CpField,Value:Any); ReadOnly; Init = null 

OnModelChange() wird aufgerufen, nachdem der User über ein Eingabe-Element einen Wert des Modells geändert hat. Eine übliche Implementation einer solchen Funktion ist z.B:

var tabform = ControlPanels.NewPanel( { OnModelChange: Compute, ...} );
 :

function Compute( ) {
  model.ComputeAllProperties();
  tabform.Update();
}

ControlPanel.NCols

ControlPanel.NCols: Integer(>0); ReadOnly; Init = 1 

Anzahl Layout-Spalten. Eine Layout-Spalte entspricht 2 Tabellen-Spalten.

Jedes ControlPanel-Feld besteht aus zwei Teilen: einem Label-Feld und einem Werte-Feld mit dem Ein-/Ausgabe-Element. Mit NCols kann spezifiziert werden, wie viele ControlPanel-Felder nebeneinander angezeigt werden sollen.

Wenn bei mehrspaltigem Layout nicht genügend ControlPanel-Felder definiert werden, um auch die letzte Tabellen-Zeile zu füllen, werden automatisch entsprechend viele leere Felder erzeugt, um die Zeile zu füllen.

Beachte, dass für jedes ControlPanel-Feld zwei Header-Zellen erzeugt werden. Wenn nicht 2 x NCols Header mit der Funktion AddHeader() definiert werden, muss mindestens einer der Header mehrere Tabellen-Spalten überspannen. Dies wird mit dem Parameter ColSpan der Funktion AddHeader() erreicht.

ControlPanel.Format, FormatTab, Digits

ControlPanel.Format: String; ReadOnly; Init = 'fix' 
ControlPanel.FormatTab: Boolean; ReadOnly; Init = true 
ControlPanel.Digits: Integer(0..16); ReadOnly; Init = 2 

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.

Mit FormatTab kann gesteuert werden, ob bei vierstelligen Zahlen die erste, bzw. bei Nachkommastellen die letzte Zahl durch die Zahlengruppierung alleine stehen darf oder nicht:

FormatTab = true FormatTab = false
1234 → 1 234 1234 → 1234
12345 → 12 345 12345 → 12 345
0,1234 → 0,123 4 0,1234 → 0,1234
0,12345 → 0,123 45 0,12345 → 0,123 45

FormatTab kann pro Tabelle eingestellt werden. Der Entsprechende Parameter des NumFormatters heisst TableLike. Dieser Parameter wird vom ControlPanel nach der Ausgabe wieder auf den alten Wert zurückgesetzt.

ControlPanel.Attr

ControlPanel.Attr: String; ReadOnly; Init = '' 

Zusätzliche Attribute für die ControlPanel-Tabelle. Attr muss im Format von Tag-Attributen definiert werden. Inline-Styles z.B. werden wiefolgt definiert:

Attr: 'style=\"color: green; font-weight: bold;\"'

Styles werden jedoch besser über Stylesheets definiert. Dabei kann auf die ID eines ControlPanels zugegriffen werden. So kann z.B. ein Style für das erste ControlPanel einer Seite mit dem Standardnamen 'ControlPanel1' definiert werden:

<style>
#ControlPanel1 { font-weight: bold; color: #444; }
</style>

ControlPanel.PanelFormat

ControlPanel.PanelFormat: String; ReadOnly; Init = '' 

Zusätzliche Klassen zur Formatierung der ControlPanel-Tabelle. Mit zusätzlichen Klassen, welche einem ControlPanel zugewiesen werden können, kann die Formatierung beeinflusst werden. Es können mehrere Klassennamen mit einem Leerzeichen dazwischen angegeben werden.

Folgende Klassen sind in ControlPanelStyles.css vordefiniert:

InputLeft
Platziert Werte in Eingabefeldern linksbündig.
LabelLeft
Platziert die Label linksbündig.
MathLabels
Verwendet einen Serifen-Font in Schrägschrift für Labels, um mathematischen Textsatz zu immitieren.
WideFieldGrid
Checkboxen und Radiobuttons werden standardmässig so eng wie möglich aneinander gereiht, wobei jedoch jedes Element gleich viel Platz zugewiesen bekommt. Mit WideFieldGrid wird der Platz auf die ganze Spaltenbreite ausgedehnt.
InputXxxWidth
Vergrössert oder Verkleinert die Eingabefelder. Standard ist InputNormalWidth. Es stehen folgende Klassen für die Grösse der Eingabefelder bereit:
  • InputMiniWidth = 35px
  • InputShortWidth = 65px
  • InputMediumWidth = 100px
  • InputNormalWidth = 150px
  • InputBigWidth = 160px
  • InputLongWidth = 200px
  • InputMaxWidth = 100%
  • InputWidth35 = 35px
  • InputWidth45 = 45px
  • InputWidth55 = 55px
  • InputWidth65 = 65px
  • InputWidth75 = 75px
  • InputWidth185 = 185px
OneCol
Für Tabellenlayouts mit nur einer Spalte, aber so, dass die Labels und Werte-Felder zu einem zweispaltigen Layout passen. Praktisch, wenn Input-Elemente über 3 Spalten definiert werden und der Label gleich viel Platz wie bei einem 2-spaltigen Layout einnehmen soll.

Um z.B. alle Label linksbündig statt rechtsbündig anzuzeigen und kürzere Eingabefelder zu erzeugen, gibt man die Klasen LabelLeft und InputShortWidth an:

ControlPanels.NewPanel( { 
  PanelFormat: 'LabelLeft InputShortWidth', ... 
} );

Es können natürlich beliebige weitere Klassen selbst in einem Stylesheet definiert und verwendet werden. Tabellen und Felder können darin über ihre Klassen und Id's referenziert werden.

ControlPanel.PanelClass

ControlPanel.PanelClass: String; ReadOnly; Init = 'ControlPanel' 

Diese Klasse wird der Panel-Tabellen zugewiesen. Über diese Klasse können die Tabellen individuell per CSS gestyled werden.

ControlPanel.ReadOnly

ControlPanel.ReadOnly: Boolean; ReadOnly; Init = false 

Standardwert des Properties ReadOnly für CpTextField.

true → Eingabe-Elemente können nicht editiert oder verändert werden, sondern dienen als blosse Anzeigen.

Wenn alle Text-Felder eines ControlPanel nicht editierbar sein sollen (ReadOnly sind), kann dies mit dem Parameter ReadOnly = true des ControlPanel erreicht werden. Bei Schiebereglern, Checkbox- und Radiobutton-Feldern, wird das ReadOnly Property nicht automatisch vom ControlPanel vererbt, sondern es muss explizit bei diesen Feldern gesetzt werden, siehe AddSliderField(), AddValueSliderField(), AddCheckboxField() und AddRadiobuttonField().

Der globale Wert ControlPanel.ReadOnly kann beim Erzeugen jedes Text-Feldes überschrieben werden.

ReadOnly-Felder werden anders dargestellt, als Elemente, die geändert werden können. Diese Darstellung kann teilweise durch Umdefinieren der Klasse ReadOnly geändert werden, z.B. für Text-Felder:

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

ControlPanel.Enabled

ControlPanel.Enabled: Boolean; Private; Init = true 

Standardwert die Properties Enabled der ControlPanel-Felder.

Gibt an, ob ein Feld aktiviert (enabled) oder deaktiviert ist. Felder können dynamisch aktiviert und deaktiviert werden, nicht zu verwechseln mit statischen ReadOnly Feldern.

Hinweis: Dieses Property kann nicht verändert oder ausgelesen werden. Für das Auslesen und Verändern des enstprechenden Feld-Properties verwende die Funktionen IsEnabled() und SetEnabled().

Der Zustand Enabled kann auch indirekt automatisch über ein Modell-Property gesteuert werden, indem in EnabledRef eine Referenz auf ein entsprechendes Modell-Property definiert wird.

Der Unterschied zwischen ReadOnly und Enabled Feldern ist der, dass ReadOnly statisch ist, während der Enabled Zustand dynamisch per Javascript geändert werden kann. Ein ReadOnly Feld kann auch dann nicht verändert werden, wenn Enabled = true ist.

ControlPanel.EnabledRef

ControlPanel.EnabledRef: CpObjectRef; Private; Init = '' 

Wird hier ein Property-Name eines Modells angegeben, welches vom Typ Boolean sein muss, so steuert dieses Property den Enabled-Zustand. Dieser Zustand kann auch mit IsEnabled() abgefragt werden.

Der EnabledRef Wert des Panels kann nicht abgefragt oder geändert werden. Er wird lediglich als Standardwert für die Felder des Panels verwendet. Zum Abfragen und Ändern des Enabled Zustandes eines Feldes verwende die Funktionen IsEnabled() und SetEnabled(), welche sowohl auf Ebene alles ControlPanels, als auch auf Ebene ControlPanel und auf Ebene CpField existieren.

ControlPanel.HiliChanges

ControlPanel.HiliChanges: Boolean; ReadOnly; Init = false 

Standardwert des Properties HiliChanges für CpTextField Objekte.

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>

ControlPanel.DimmDefault

ControlPanel.DimmDefault: Boolean; ReadOnly; Init = false 

Standardwert des Properties DimmDefault für CpTextField Objekte.

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>

ControlPanel.HelpImage

ControlPanel.HelpImage: String; ReadOnly; Init = 'q.gif' 

Pictogramm, welches hinter einem Feld angezeigt wird, wenn der Parameter Link definiert ist.

Wenn für ein ControlPanel-Feld der Parameter Link definiert ist, wird standardmässig ein Pictogramm hinter dem Feld angezeigt. Ein Klick darauf bringt die verlinkte Seite zur Anzeige. Wenn HelpImage = '' gesetzt wird, wird kein Pictogramm angezeigt. Es kann auch der Filename eines beliebigen anderen Pictogrammes definiert werden.

Das Pictogramm wird relativ zum Verzeichnis von ControlPanelX.js gesucht. Dieses Verzeichnis kann über die folgende Variable abgefragt werden:

ControlPanel.prototype.ScriptPath
ControlPanels.NewPanel( {
 :
 HelpImage = ControlPanel.prototype.ScriptPath + 'myHelpPic.gif'
} );

ControlPanel.Fields

ControlPanel.Fields: Array of CpField; ReadOnly; Init = [ ] 

Alle ControlPanel-Felder werden in der Liste Fields des ControlPanel gespeichert.

ControlPanel.FieldCounter

ControlPanel.FieldCounter: Integer(>=0); ReadOnly; Init = 0 

FieldCounter ist ein interner Zähler. Er wird bei jedem erzeugten ControlPanel-Feld um 1 erhöht und dient der automatischen Namensgebung der Felder → CpField.Name.

ControlPanel.ValuePos

ControlPanel.ValuePos: String('left', 'right'); ReadOnly; Init = 'left' 

ValuePos hat nur eine Bedeutung, wenn das ControlPanel Objekt mit der Funktion NewSliderPanel() erzeugt wird. Es bestimmt die Position des Werte-Feldes neben einem Slider, welcher mit der Funktion AddValueSliderField() erzeugt wird.

ControlPanel.AddHeader()

ControlPanel.AddHeader( Parameter )

Parameter: HeaderDef; Optional; Default = { }
Return this: ControlPanel
HeaderDef = {
Text: String; Optional; Default = ' '
Text, der in der Überschriftenspalte angezeigt werden soll; darf HTML-Tags enthalten.
ColSpan: Integer(>0); Optional; Default = 1
Anzahl Tabellen-Spalten, welche zu dieser Titel-Zelle zusammengefasst werden sollen.
Attr: String; Optional; Default = ''
Zusätzliche Attribute für die Header-Zelle.
}

Fügt ein Titel-Feld in das ControlPanel ein.

Panels werden als Table-Elemente auf der Webseite implementiert. Jedes ControlPanel-Feld benötigt mindestens 2 Tabellen-Spalten: eine für Labels und eine für Werte-Felder. Wenn z.B. ein ControlPanel mit NCols = 2 definiert wird, hat die zugrundeliegende Tabelle 4 Spalten. Es müssen dann entweder 4 Header-Zellen durch 4-maliges Aufrufen von AddHeader definiert werden, oder eine oder mehrere Header-Zellen müssen durch Angabe von ColSpan mehrere Spalten überspannen.

Header müssen am Anfang einer Tabelle erzeugt werden! Alle erzeugten Header werden in der ersten Zeile der Tabelle angezeigt. Jedes Panel kann nur eine Titelzeile haben!

Diese Funktion gibt das ControlPanel Objekt als Returnwert zurück. Dadurch lassen sich ControlPanel Funktionen verketten.

Attr muss im Format von Tag-Attributen definiert werden. Inline-Styles z.B. werden wiefolgt definiert:

Attr: 'style=\"color: green; font-style: italic;\"'
ControlPanels.NewPanel( {
  NCols: 2,
  :

} ).AddHeader( {
  Text: 'Titel 1',
  ColSpan: 2

} ).AddHeader( {
  Text: 'Titel 2',
  ColSpan: 2

} )....  

ControlPanel.GetField()

ControlPanel.GetField( FieldName )

FieldName: String
Return: CpField | null

Sucht im Panel ein Feld mit dem Name FieldName und gibt eine Referenz darauf zurück. Bei Checkbox-Feldern wird FieldName auch mit den Namen der CpCheckboxItems verglichen. Passt ein solcher Name, wird die Referenz auf das CpCheckboxField zurückgegeben.

Wird FieldName in diesem Panel nicht gefunden, wird null zurückgegeben.

Liegt noch kein ControlPanel vor, kann ein Feld über die Funktion ControlPanels.GetField() gesucht werden.

Jedes Feld hat zum Teil unterschiedliche Properties. Um auf diese zugreifen zu können, muss der Feld-Typ bekannt sein. Dieser kann mit der Funktion GetType() abgefragt werden.

ControlPanel.Render()

ControlPanel.Render( )

Return this: ControlPanel

Erzeugt den HTML-Code für das fertig definierte ControlPanel und fügt diesen an der Stelle des Aufrufes von Render() in die Webseite ein. Weitere Manipulationen am ControlPanel Objekt haben keine Auswirkungen mehr.

Die Verbindung zwischen ControlPanel und Dom-Elementen wird in der automatisch aufgerufenen Funktion Init() hergestellt. Die Funktion Init() wird nach dem vollständigen Laden der Webseite gerufen.

Dadurch, dass Render() das ControlPanel-Objekt this zurückgibt, können alle Feld-erzeugenden Funktionen aneinandergereiht werden:

var myPanel = ControlPanels.NewPanel( {
  :

} ).AddTextField( {
  :

} ).Render();

Dank dem Returnwert von Render() wird am Ende das ControlPanel der Variablen myPanel zugewiesen.

ControlPanel.GetHtml()

ControlPanel.GetHtml( )

Return: String

Erzeugt den HTML-Code für das fertig definierte ControlPanel und gibt diesen in String-Form zurück. Diese Funktion wird intern von Render() gerufen.

Der mit GetHtml() erzeugte String kann zum Beisiel mit der Funktion xInnerHtml() in ein Div-Element geschrieben werden. Danach müssen allerding die Links zwischen Panel- und Dom-Elementen explizit über Init() (für ein Panel) oder ControlPanels.ConnectDom() (für mehrere Panels) hergestellt werden.

ControlPanel.Init()

ControlPanel.Init( GetDefault )

GetDefault: Boolean; Optional; Default = false

Init veranlasst, dass die aktuellen Modell-Werte ausgelesen werden und bei den ControlPanel-Feldern als Startwert gespeichert werden (nur beim ersten Aufruf oder wenn GetDefault true ist). Mit Reset() kann das Modell auf diese Startwerte zurückgesetzt werden. Init() ruft zudem die Funktion Update(), um die Anzeige der Felder zu initialisieren, sodass sie die Startwerte anzeigen. Init() verbinden schliesslich das Panel mit den zugehörigen Dom-Elementen der Webseite.

Init() wird automatisch nach dem vollständigen Laden der Webseite ausgeführt und muss daher in den meisten Fällen nicht explizit aufgerufen werden. Das automatische Aufrufen von Init() kann aber wenn nötig bei der Funktion NewPanel() mit dem Argument AutoInit: false unterdrückt werden.

Die Startwerte werden nur beim ersten Aufruf von Init() oder wenn GetDefault true ist eingelesen.

Für mehrere Panels gemeinsam kann Init mit der Funktion ControlPanels.Init() ausgeführt werden. Vergleiche auch mit der Funktion ControlPanels.ConnectDom(), welche ihrerseits Init() aufruft.

ControlPanel.Update()

ControlPanel.Update( )

Update liest für jedes ControlPanel-Feld den zugehörigen Modell-Wert aus und zeigt ihn an. Update muss gerufen werden, nachdem externe Funktionen die Modell-Werte geändert haben, um die aktuellen Werte in den Panels anzuzeigen.

Update ist so optimiert, dass nur Felder nachgeführt werden, deren Modell-Wert nicht mehr mit der Anzeige übereinstimmen.

Für mehrere Panels gemeinsam kann Update mit der Funktion ControlPanels.Update() ausgeführt werden.

var model = new MyModel();

var myPanel = ControlPanels.NewPanel( { OnModelChange: Compute, ... } );
 :

function Compute() {
  // Modell-Werte werden geändert
  model.Update(); 
  // Anzeigen des ControlPanels myPanel werden nachgeführt
  myPanel.Update();
}

oder Variante ohne Variable myPanel:

var model = new MyModel();

ControlPanels.NewPanel( { 
  Name: 'myPanelName', 
  OnModelChange: Compute, 
   :
} )...

function Compute() {
  // Modell-Werte werden geändert
  model.Update(); 
  // Anzeigen des ControlPanels myPanelName werden nachgeführt
  ControlPanels.Update( 'myPanelName' );
}

oder ohne Panel-Name:

var model = new MyModel();

ControlPanels.NewPanel( { 
  OnModelChange: Compute, 
   :
} )...

function Compute() {
  // Modell-Werte werden geändert
  model.Update(); 
  // Anzeigen aller ControlPanels werden nachgeführt
  ControlPanels.Update();
}

Wenn sich zwar nicht der Wert eines Modell-Properties ändert, aber dessen Darstellungsformat, so funktioniert Update() wegen der Optimierung nicht richtig. Um zu erzwingen, dass der gleiche Wert im neuen Format dargestellt wird, muss vor Update() die Funktion Invalidate() gerufen werden. Für eine Anwendung siehe Demo-Code.

ControlPanel.UpdateLayout()

ControlPanel.UpdateLayout( VisiState )

VisiState: Integer(-1,0,1); Optional; Default = -1
-1: unbekannt, 0: unsichtbar, 1: sichtbar

Diese Funktion kann gerufen werden, wenn ein ControlPanel unsichtbar/sichtbar gemacht wurde, um die Geometrie der Elemente neu berechnen zu lassen.

Hinweis: Bei Verwendung Moduls Tabs zum Ein-/Ausblenden von Panels mittels Tabulator-Zeilen werden automatisch UpdateLayout-Funktionen im Modul Tabs installiert. Diese Funktion muss nicht explizit gerufen werden!

Für mehrere Panels gemeinsam kann UpdateLayout mit der Funktion ControlPanels.UpdateLayout() ausgeführt werden.

ControlPanel.IsDisplayed()

ControlPanel.IsDisplayed( )

Gibt true zurück, wenn das ControlPanel und alle übergeordneten Dom-Elemente sichtbar sind.

Hinweis: Dom-Elemente werden mit dem Style display: none unsichtbar gemacht. Diese Funktion funktioniert auch, wenn dieser Style nicht direkt im Dom-Element, sondern per CSS gesetzt wird.

ControlPanel.Invalidate()

ControlPanel.Invalidate( )

Invalidate erzwingt ein Neuzeichnen aller ControlPanel-Felder beim nächsten Aufruf von Update(), auch wenn sich der dargestellte Wert nicht geändert hat.

Anwendung: Wenn FormatRef, DigitsRef oder UnitsRef definiert sind und sich die so referenzierten Modell-Werte (Format, Digits, Units) ändern, werden die Anzeigen durch den Aufruf von Update() wegen der Optimierung nicht automatisch nachgeführt, da sich nur die Formatierung, nicht aber der Modell-Wert geändert hat. Um einen Update zu erzwingen kann vor dem Update() die Funktion Invalidate gerufen werden.

Eine Anwendung der Funktion Invalidate() findest du auf der Seite CP-Anwendung: UnitRef, MultRef.

Für mehrere Panels gemeinsam kann Invalidate mit der Funktion ControlPanels.Invalidate() ausgeführt werden.

ControlPanel.Reset()

ControlPanel.Reset( CallModelChangeCB, Update )

CallModelChangeCB: Boolean; Optional; Default = false
true → ruft die Funktion OnModelChange
Update: Boolean; Optional; Default = false
true → ruft nach dem Reset die Funktion Update()

Reset setzt alle Modell-Werte auf ihre Startwerte zurück. Die Startwerte werden in der Funktion Init() vom Modell abgefragt und bei den Feldern gespeichert. Init() wird automatisch nach dem Laden der Seite gerufen.

Falls man dem User eine Funktion zum Zurücksetzen des Formulares zur Verfügung stellen will, erzeugt man auf der Webseite am besten einen Button (z.B. mit der Funktion ControlPanels.ResetButton()), welcher als Aktion Reset ruft:

function MyModel() {
  // model properties are defined here
  this.Update();
}

MyModel.prototype.Update = function() {
  // compute some stuff that changes some properties
}

var model = new MyModel();

ControlPanels.NewPanel( { 
  OnModelChange: UpdateAll,
   : 

} ).AddHeader( {
  Text: 'Titel' + ControlPanels.ResetButtonR(),
   :

} ).Render()

function Reset() {
  ControlPanels.Reset();
  UpdateAll();
}

function UpdateAll() {
  model.Update();
  ControlPanels.Update();
}

Beachte, dass durch den Aufruf von ControlPanels.Reset() die Funktion UpdateAll() standardmässig nicht automatisch aufgerufen wird, nachdem alle Modellwerte zurückgesetzt wurden. So können Reset() Aufrufe für mehrere Panels zusammengefasst werden, ohne dass nach jedem Aufruf UpdateAll() ausgeführt wird. Wenn jedoch nur ein ControlPanel existiert, kann der Parameter CallModelChangeCB bei ControlPanels.Reset() true gesetzt werden und UpdateAll() muss dann dort nicht aufgerufen werden.

Beim Anklicken des Reset Buttons passiert im obigen Beispiel folgendes:

  1. Die Funktion Reset() wird aufgerufen
    1. ControlPanels.Reset() bewirkt, dass die Standardwerte der Felder aller Panels im Modell gespeichert werden
    2. UpdateAll() wird gerufen
      1. model.Update() nimmt Berechnungen am Modell vor, um auf die geänderten Modell-Properties zu reagieren
      2. ControlPanels.Update() führt alle Panel-Anzeigen entsprechend den neuen Modell-Berechnungen nach

Für mehrere Panels gemeinsam kann Reset mit der Funktion ControlPanels.Reset() ausgeführt werden.

ControlPanel.IsEnabled()

ControlPanel.IsEnabled( FieldName )

FieldName: String
Name des Feldes, dessen Enabled-Zustand abgefragt werden soll
Return: Boolean
true → das Feld ist aktiviert

Überprüft, ob ein Feld bedienbar ist oder nicht. Dies kann beim Ereugen des Feldes mit dem Parameter Enabled oder später mit der Funktion SetEnabled() gesteuert werden. Auch eine indirekte Steuerung über ein Modell-Property kann mit dem Parameter EnabledRef einiger Felder veranlasst werden.

Hinweis: Da CpCheckboxField Objekte mehrere unabhängige Kontrol-Elemente (Checkbox-Items) haben, gibt FieldName den Namen eines dieser Items an, nicht den Namen des Checkbox-Feldes selbst.

Liegt kein ControlPanel vor, kann der Enabled-Zustand auch mit ControlPanels.IsEnabled() abgefragt werden.

ControlPanel.SetEnabled()

ControlPanel.SetEnabled( FieldName, Enabled )

FieldName: String; Optional; Default = ''
Name des Feldes, das aktiviert/deaktiviert werden soll
Enabled: Boolean; Optional; Default = true
false → Feld soll deaktiviert werden

Aktiviert/Deaktiviert ein ControlPanel-Feld. Deaktivierte Felder werden grau angezeigt und nehmen keinen Eingaben entgegen. Sie zeigen jedoch die aktuellen Modellwerte weiterhin an.

Der aktuelle Zustand wird im Property Enabled festgehalten, welches über IsEnabled() abgefragt werden kann. Der Zustand Enabled kann auch automatisch über eine EnabledRef auf ein Modell-Property gesteuert werden. Wenn EnabledRef definiert ist, hat SetEnabled() keine Wirkung. Der Enabled-Zustand wird dann allein durch das referenzierte Modell-Property gesteuert.

Wenn FieldName nicht definiert oder '' ist, werden alle Felder des ControlPanel auf Enabled gesetzt. Wenn Enabled nicht definiert ist, wird true angenommen.

Hinweis: Da CpCheckboxField Objekte mehrere unabhängige Kontrol-Elemente (Checkbox-Items) haben, gibt FieldName den Namen eines dieser Items an, nicht den Namen des Checkbox-Feldes selbst.

Liegt kein ControlPanel vor, kann der Enabled-Zustand mit der Funktion ControlPanels.SetEnabled() falls erwünscht gleich für mehrere Panels gemeinsam gesetzt werden.

ControlPanel.Delete()

ControlPanel.Delete( DeleteDom )

DeleteDom: Boolean; Optional; Default = false
true → Lösche auch die zum Panel gehörenden Dom-Elemente der Webseite

Delete() löst die Verbindungen zwischen dem Panel und seinen ControlPanel-Feldern und entfernt den Eintrag in der ControlPanels.PanelList für dieses Panel.

Wenn DeleteDom true gesetzt wird, Default ist false, werden auch die Dom-Elemente des Panels gelöscht.

Mehrere Panels gemeinsam kann man über die Funktion ControlPanels.DeletePanels() löschen.

ControlPanel.GetHtmlID()

ControlPanel.GetHtmlID( )

Gibt die HTML-ID des Panels zurück. Die HTML-ID ist die ID des Tabellen-Elementes, welches ein Panel darstellt. Die HTML-ID wird aus dem Name des Panels gebildet. Eine Referenz auf das Tabellen-Element kann per GetDomObj() erfragt werden.

Die HTML-ID von Feldern kann mit CpField.GetHtmlID() abgefragt werden.

ControlPanel.GetDomObj()

ControlPanel.GetDomObj( )

Gibt eine Referenz auf das DOM-Element (Tabelle) zurück, welches das Panel enthält. Die HTML-ID dieses Elementes kann mit GetHtmlID() abgefragt werden.

Referenzen auf die DOM-Feldelemente können mit CpField.GetDomObj() abgefragt werden.

Hinweis: Wenn das DOM-Element noch nicht erzeugt ist, d.h. Render() wurde noch nicht aufgerufen, gibt die Funktion null zurück.

Weitere Infos zur Seite
Erzeugt Sonntag, 7. August 2016
von wabis
Zum Seitenanfang
Geändert Mittwoch, 5. Oktober 2016
von wabis