form — u_pbt_form #

← Komponentenreferenz · Inhalt des Handbuchs

form ist ein ganzer Erfassungsbildschirm in einem Steuerelement: typisierte Felder — Text, Zahl, Liste, Optionsfelder, Datum, Uhrzeit, Farbe, Kontrollkästchen, Kennwort, E-Mail, langer Text, Bild, Schlagwörter, Sterne — in Spalten und einklappbaren Abschnitten angeordnet, jedes mit seiner Beschriftung, die in seinen Rahmen aufsteigt. Die Regeln jedes Feldes (Pflichtfeld, Grenzen, Muster, Maske…) und Ihre fachlichen Fehler werden gemeinsam geprüft; of_is_dirty sagt, was sich seit dem Laden geändert hat, of_load_row / of_save_row lesen und schreiben eine Zeile eines DataWindow. Ihre eigene OK-Schaltfläche ruft of_validate auf.

▶ Live ansehen — Demoanwendung, Kachel Form: die Vorschau, der zugehörige Code und diese Seite, nebeneinander.

Auf einen Blick #

Schnellstart #

// Two columns ; a name at the top, then a section
uo_form.ii_columns = 2
uo_form.of_add_field(/*keys*/ "name", /*label*/ "Name", /*type*/ u_pbt_form.TYPE_STRING, /*value*/ "")
uo_form.of_field(/*keys*/ "name").ib_required = true
uo_form.of_add_section(/*key*/ "order", /*title*/ "Order")
uo_form.of_add_field(/*keys*/ "order/qty", /*label*/ "Quantity", /*type*/ u_pbt_form.TYPE_NUMBER, /*value*/ "1")
uo_form.of_add_field(/*keys*/ "order/due", /*label*/ "Due on", /*type*/ u_pbt_form.TYPE_DATE, /*value*/ "")

// event clicked of cb_ok
// Local variables
n_pbt_json lnv_json

// Every error shown at once, the keyboard on the first
if uo_form.of_validate() > 0 then return

// Valid : read the values, typed, along the same addresses
lnv_json.of_load(/*json*/ uo_form.of_values())
of_save_order(lnv_json.of_get_string(/*path*/ "name"), lnv_json.of_get_number(/*path*/ "order/qty"))

Eine Adresse pro Feld #

Ein Feld wird über seine Adresse benannt: oben sein Schlüssel allein ("name"), in einem Abschnitt der Abschnitt und dann das Feld, durch / verbunden ("order/qty") — eine Ebene, nie mehr. Ein Abschnitt wird über seinen Schlüssel allein benannt. Oben benennt ein Schlüssel nur eine Sache: ein Abschnitt und ein Feld der obersten Ebene können ihn nicht teilen. Die Events tragen dieselbe Adresse, die Sie geschrieben haben; der Schlüssel eines Feldes (seine letzte Ebene) ist auch der Name der Spalte, die of_load_row und of_save_row lesen.

// A section by its key, a field by its address
uo_form.of_section(/*key*/ "order").ib_collapsed = true
uo_form.of_field(/*keys*/ "order/qty").is_value = "3"

Feldtypen #

Der Typ wird einmal gewählt, in of_add_field, und bestimmt das Steuerelement. Der Wert selbst ist immer Text — übergeben, gelesen, von den Events geliefert — gleich geschrieben, unabhängig von der Sprache des Arbeitsplatzes. Eine Liste, ein Datum und eine Farbe öffnen sich in den nativen Fenstern, die die ganze Bibliothek teilt, in den Farben des Themas.

Die Prüfung #

Jedes Feld trägt seine Regeln: ib_required (ein Pflicht-Kontrollkästchen muss angehakt sein), is_min / is_max (eine Zahl, ein Datum, eine Uhrzeit), ii_max_length, is_pattern (ein regulärer Ausdruck, dem der ganze Wert folgen muss), is_mask (eine ausgefüllte Maske), is_match (gleich einem anderen Feld) und die Form einer E-Mail, einer Zahl oder einer Uhrzeit. Ihre Anwendung ergänzt ihre fachlichen Fehler (is_error: bereits vergeben), die bleiben, bis der Benutzer das Feld ändert. Nichts erscheint rot, solange der Benutzer kein Feld verlassen hat: ein neues Formular ist nicht rot. of_is_valid und of_invalid_keys antworten, ohne etwas zu zeigen; of_validate zeigt alles auf einmal und setzt die Tastatur auf das erste fehlerhafte Feld. Ein ausgeblendetes, deaktiviertes oder schreibgeschütztes Feld wird nicht nach seinen Regeln beurteilt: der Benutzer könnte es nicht korrigieren.

// A customer code : two capital letters, then four digits
uo_form.of_field(/*keys*/ "code").is_pattern = "[A-Z]{2}[0-9]{4}"
uo_form.of_field(/*keys*/ "code").is_pattern_message = "Two capital letters, then four digits"

// A rule only your database knows
if of_email_taken(uo_form.of_field(/*keys*/ "email").is_value) then
    uo_form.of_field(/*keys*/ "email").is_error = "Already used by another customer"
end if

Eigenschaften #

Eigenschaften eines Abschnitts — n_pbt_form_section #

Eigenschaften eines Feldes — n_pbt_form_field #

Methoden #

Auf der Komponente #

Auf einem Abschnitt und auf einem Feld #

Ein Abschnitt enthält Felder; eine Liste oder Optionsfelder enthalten ihre Optionen, über ihren Wert benannt. Die drei Methoden durchlaufen sie.

Ereignisse #

Tastatur und Maus #

Beispiele #

Ein Kundendatensatz #

// The whole form in one paint, two columns
uo_form.of_set_redraw(/*on*/ false)
uo_form.ii_columns = 2

// Identity : two required names, an e-mail, a phone with its mask
uo_form.of_add_section(/*key*/ "identity", /*title*/ "Identity")
uo_form.of_add_field(/*keys*/ "identity/first_name", /*label*/ "First name", /*type*/ u_pbt_form.TYPE_STRING, /*value*/ "")
uo_form.of_field(/*keys*/ "identity/first_name").ib_required = true
uo_form.of_add_field(/*keys*/ "identity/last_name", /*label*/ "Last name", /*type*/ u_pbt_form.TYPE_STRING, /*value*/ "")
uo_form.of_field(/*keys*/ "identity/last_name").ib_required = true
uo_form.of_add_field(/*keys*/ "identity/email", /*label*/ "E-mail", /*type*/ u_pbt_form.TYPE_EMAIL, /*value*/ "")
uo_form.of_add_field(/*keys*/ "identity/phone", /*label*/ "Phone", /*type*/ u_pbt_form.TYPE_STRING, /*value*/ "")
uo_form.of_field(/*keys*/ "identity/phone").is_mask = "(###) ###-####"

// Account : a credit limit with a bound, shown as a price and typed without the
// dollar sign ; a list ; a switch
uo_form.of_add_section(/*key*/ "account", /*title*/ "Account")
uo_form.of_add_field(/*keys*/ "account/credit_limit", /*label*/ "Credit limit", /*type*/ u_pbt_form.TYPE_NUMBER, /*value*/ "2500")
uo_form.of_field(/*keys*/ "account/credit_limit").is_format = "$#,##0.00"
uo_form.of_field(/*keys*/ "account/credit_limit").is_max = "50000"
uo_form.of_add_field(/*keys*/ "account/country", /*label*/ "Country", /*type*/ u_pbt_form.TYPE_ENUM, /*value*/ "gb")
uo_form.of_add_option(/*keys*/ "account/country", /*value*/ "gb", /*text*/ "United Kingdom")
uo_form.of_add_option(/*keys*/ "account/country", /*value*/ "fr", /*text*/ "France")
uo_form.of_add_field(/*keys*/ "account/vip", /*label*/ "VIP customer", /*type*/ u_pbt_form.TYPE_BOOLEAN, /*value*/ "false")

// Shown at once, the keyboard on the first field
uo_form.of_set_redraw(/*on*/ true)
uo_form.of_focus_field(/*keys*/ "identity/first_name")

Eine DataWindow-Zeile bearbeiten #

Der Schlüssel jedes Feldes ist der Name seiner Spalte: das Formular liest die Zeile, der Benutzer bearbeitet sie, das Formular schreibt sie.

// The current row of dw_customers fills the form ; nothing is dirty yet
uo_form.of_load_row(/*data*/ dw_customers, /*row*/ dw_customers.GetRow())

// event clicked of cb_save
if uo_form.of_validate() > 0 then return

// Write the values back into the row, then save it
if uo_form.of_save_row(/*data*/ dw_customers, /*row*/ dw_customers.GetRow()) < 0 then
    MessageBox("Save", uo_form.of_get_last_error())
    return
end if

// Saved : what is on screen is the new reference
if dw_customers.Update() = 1 then
    COMMIT USING SQLCA;
    uo_form.of_reset_update()
end if

Schlagwörter und Sterne #

Eine Produktbewertung: eine Note von fünf mit halben Sternen und freie Schlagwörter mit Vorschlägen. Beide Werte bleiben Text, den of_save_row in eine Zahlen- und eine Textspalte schreibt.

// Local variables
string ls_score, ls_tags

// The score : five stars, half stars set BEFORE a half value
uo_form.of_add_field(/*keys*/ "score", /*label*/ "Overall", /*type*/ u_pbt_form.TYPE_RATING, /*value*/ "")
uo_form.of_field(/*keys*/ "score").ib_half_stars = true
uo_form.of_field(/*keys*/ "score").is_value = "3.5"

// Tags : free text, the options are suggestions, five at most
uo_form.of_add_field(/*keys*/ "tags", /*label*/ "Tags", /*type*/ u_pbt_form.TYPE_TAGS, /*value*/ "office, led")
uo_form.of_add_option(/*keys*/ "tags", /*value*/ "eco", /*text*/ "Eco-friendly")
uo_form.of_add_option(/*keys*/ "tags", /*value*/ "usb", /*text*/ "USB powered")
uo_form.of_field(/*keys*/ "tags").ii_max_tags = 5

// Read back : "3.5" and "office, led"
ls_score = uo_form.of_field(/*keys*/ "score").is_value
ls_tags = uo_form.of_field(/*keys*/ "tags").is_value

Vor dem Verlust von Änderungen warnen #

// event closequery of the window
if not uo_form.of_is_dirty() then return 0

// Changes since the load : ask, and put them back if the user gives up
if MessageBox("Customer", "Discard your changes ?", Question!, YesNo!) = 2 then return 1
uo_form.of_revert()
return 0

Bewährte Praxis #

• Ein Wert ist Text: eine Zahl wird mit Punkt geschrieben ("12.5"), ein Boolean "true"/"false", eine Farbe String(RGB(…)), ein Datum "yyyy-mm-dd", eine Uhrzeit "hh:mm" — unabhängig von der Sprache des Arbeitsplatzes. Für typisierte Werte of_values und n_pbt_json.
• Ihre OK-Schaltfläche entscheidet: of_validate zeigt die Fehler und liefert ihre Anzahl; das Formular speichert selbst nichts.
• Benennen Sie die Felder wie die Spalten: of_load_row und of_save_row erledigen dann die ganze Arbeit; sonst nennt is_column die Spalte eines Feldes.
• ib_readonly statt ib_enabled = false für einen Wert, den der Benutzer lesen soll: ein schreibgeschützter Text lässt sich markieren und kopieren.
• Demomodus: ohne Schlüssel zeichnet das Formular 6 Felder, die ersten in Bildschirmreihenfolge — ein Feld eines eingeklappten Abschnitts zählt mit, das Aufklappen zeichnet nichts neu; die anderen bleiben im Speicher und in of_values, werden aber weder gezeichnet noch beurteilt (siehe Lizenz).

Vom gemeinsamen Sockel geerbt #

Diese Mitglieder gibt es bei jeder visuellen Komponente — sie sind nicht dieser eigen. Sie werden einmal in den übergreifenden Kapiteln beschrieben; diese Tabelle sagt nur, wo man sie liest.

Zwei Helfer werden nicht geerbt: of_icon und of_escape_markup liegen auf n_pbt_utils. Deklarieren Sie eines — n_pbt_utils lnv_utils, nichts zu erzeugen — und rufen Sie sie darauf auf.

← Komponentenreferenz · Inhalt des Handbuchs