propertygrid — u_pbt_propertygrid #

← Komponentenreferenz · Inhalt des Handbuchs

propertygrid ist das Eigenschaftenfenster einer IDE, für Ihre eigenen Daten: benannte Werte, in einklappbare Kategorien geordnet, jeder mit dem Editor seines Typs — Text, Zahl, Kontrollkästchen, Auswahlliste, Farbe, Datum, Kennwort. Zwei Ansichten (nach Kategorie, alphabetisch), ein Suchfeld, ein Hilfebereich, der die ausgewählte Eigenschaft beschreibt, und eine Schaltfläche …, die einen eigenen Dialog öffnet. Der Benutzer ändert, ue_value_changed teilt es Ihnen mit.

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

Auf einen Blick #

Schnellstart #

// The settings of a report : one value at the top, then a category
uo_grid.of_add_property(/*keys*/ "title", /*label*/ "Title", /*type*/ u_pbt_propertygrid.TYPE_STRING, /*value*/ "Monthly sales")
uo_grid.of_add_category(/*key*/ "page", /*title*/ "Page")
uo_grid.of_add_property(/*keys*/ "page/landscape", /*label*/ "Landscape", /*type*/ u_pbt_propertygrid.TYPE_BOOLEAN, /*value*/ "true")
uo_grid.of_add_property(/*keys*/ "page/margin", /*label*/ "Margin (mm)", /*type*/ u_pbt_propertygrid.TYPE_NUMBER, /*value*/ "12.5")

// The help pane describes the selected property
uo_grid.of_property(/*keys*/ "page/margin").is_description = "Around the printed area, in [b]millimetres[/b]."

// event ue_value_changed of uo_grid : (string as_keys, string as_value)
// The value is already written ; the address says which one
choose case as_keys
    case "title"
        of_set_report_title(as_value)
    case "page/landscape"
        of_set_landscape(as_value = "true")
end choose

Eine Adresse pro Eigenschaft #

Eine Eigenschaft wird über ihre Adresse benannt: oben ihr Schlüssel allein ("title"), unter einer Kategorie die Kategorie und dann die Eigenschaft, durch / verbunden ("page/margin"). Eine aufklappbare Eigenschaft (TYPE_GROUP) enthält ihrerseits Eigenschaften, die an ihrer Adresse hinzugefügt werden: "appearance/font/size" in der Gruppe font der Kategorie appearance, "margin/left" in einer Gruppe der obersten Ebene — und eine Gruppe kann eine weitere enthalten. Worin eine Eigenschaft liegt, ist also eine Kategorie (nur eine Ebene) oder eine Gruppe. Eine Kategorie wird über ihren Schlüssel allein benannt. Oben benennt ein Schlüssel nur eine Sache: eine Kategorie und eine Eigenschaft der obersten Ebene können ihn nicht teilen. Die Events tragen dieselbe Adresse, die Sie geschrieben haben.

// A category by its key, a property by its address
uo_grid.of_category(/*key*/ "page").ib_collapsed = true
uo_grid.of_property(/*keys*/ "page/margin").is_value = "15"

// A property held by a group : the address goes through the group
uo_grid.of_property(/*keys*/ "appearance/font/size").is_value = "11"

Werttypen #

Der Typ wird einmal gewählt, in of_add_property, und bestimmt den Editor der Zeile. Der Wert selbst ist immer Text — übergeben, gelesen, von den Events geliefert — gleich geschrieben, unabhängig von der Sprache des Arbeitsplatzes.

Ein Wert, den sein Typ nicht fassen kann, wird abgelehnt — von of_add_property (-5) wie über is_value oder is_default (der alte bleibt) — und of_get_last_error sagt warum: eine Zahl, die keine ist, ein Boolean außer true / false / 1 / 0, ein Datum, das kein echtes yyyy-mm-dd ist, eine Farbe, die keine ganze Zahl ab -1 ist, ein TYPE_STRING oder TYPE_PASSWORD über mehrere Zeilen (das Feld des Rasters fasst eine Zeile). "" (kein Wert) wird immer angenommen. Ein Listenwert, den keine Option anbietet, wird angenommen und so angezeigt, wie er ist: eine Liste kann nach ihrem Wert geladen werden. Die Farbe -1 — die des Themas, die Konvention der ganzen Bibliothek — wird „(Standard)“ angezeigt; eine Systemfarbe und die true / false einer Zusammenfassung erscheinen in der Anzeigesprache.

Eigenschaften #

Eigenschaften einer Kategorie — n_pbt_propertygrid_category #

Eigenschaften einer Eigenschaft — n_pbt_propertygrid_property #

Methoden #

Auf der Komponente #

Auf einer Kategorie und auf einer Eigenschaft #

Eine Kategorie enthält Eigenschaften; eine Gruppe (TYPE_GROUP) enthält ihre Untereigenschaften; eine Listeneigenschaft (TYPE_ENUM) enthält ihre Optionen, über ihren Wert benannt. Die drei Methoden durchlaufen sie.

Ereignisse #

Tastatur und Maus #

Beispiele #

Die Einstellungen eines Fensters #

// The whole grid in one paint
uo_grid.of_set_redraw(/*on*/ false)

// At the top, without a category : the name of the window
uo_grid.of_add_property(/*keys*/ "name", /*label*/ "Name", /*type*/ u_pbt_propertygrid.TYPE_STRING, /*value*/ "Customers")

// A value given by the application : shown, not editable
uo_grid.of_add_category(/*key*/ "identity", /*title*/ "Identity")
uo_grid.of_add_property(/*keys*/ "identity/id", /*label*/ "Id", /*type*/ u_pbt_propertygrid.TYPE_STRING, /*value*/ "W-0042")
uo_grid.of_property(/*keys*/ "identity/id").ib_readonly = true
uo_grid.of_add_property(/*keys*/ "identity/created", /*label*/ "Created on", /*type*/ u_pbt_propertygrid.TYPE_DATE, /*value*/ String(Today(), "yyyy-mm-dd"))

// A number, a check box and a list of choices
uo_grid.of_add_category(/*key*/ "layout", /*title*/ "Layout")
uo_grid.of_add_property(/*keys*/ "layout/width", /*label*/ "Width", /*type*/ u_pbt_propertygrid.TYPE_NUMBER, /*value*/ "1200")
uo_grid.of_add_property(/*keys*/ "layout/resizable", /*label*/ "Resizable", /*type*/ u_pbt_propertygrid.TYPE_BOOLEAN, /*value*/ "true")
uo_grid.of_add_property(/*keys*/ "layout/state", /*label*/ "Window state", /*type*/ u_pbt_propertygrid.TYPE_ENUM, /*value*/ "normal")
uo_grid.of_add_option(/*keys*/ "layout/state", /*value*/ "normal", /*text*/ "Normal")
uo_grid.of_add_option(/*keys*/ "layout/state", /*value*/ "maximized", /*text*/ "Maximized")

// A colour, as its RGB long written out
uo_grid.of_add_category(/*key*/ "appearance", /*title*/ "Appearance")
uo_grid.of_add_property(/*keys*/ "appearance/back_color", /*label*/ "Back colour", /*type*/ u_pbt_propertygrid.TYPE_COLOR, /*value*/ String(RGB(/*red*/ 240, /*green*/ 244, /*blue*/ 250)))

// One single paint, then the first value to edit
uo_grid.of_set_redraw(/*on*/ true)
uo_grid.of_select_property(/*keys*/ "layout/width")

Ein Inspektor, der jede Änderung anwendet #

// event ue_value_changed of uo_grid : (string as_keys, string as_value)
// The address says which setting of the window the user changed
choose case as_keys
    case "name"
        w_customers.title = as_value
    case "layout/width"
        w_customers.width = Long(as_value)
    case "layout/resizable"
        w_customers.resizable = (as_value = "true")
    case "appearance/back_color"
        w_customers.backcolor = Long(as_value)
end choose

Die Schaltfläche …: ein eigener Dialog #

// The icon : typed by hand, or chosen through the "..." button
uo_grid.of_add_property(/*keys*/ "appearance/icon", /*label*/ "Icon", /*type*/ u_pbt_propertygrid.TYPE_STRING, /*value*/ "img\customers.png")
uo_grid.of_property(/*keys*/ "appearance/icon").ib_ellipsis = true

// event ue_ellipsis_clicked of uo_grid : (string as_keys)
// Local variables
string ls_path, ls_file
constant unsignedlong OFN_EXPLORER = 2
constant unsignedlong OFN_NOCHANGEDIR = 64

// The application opens its own dialog - in the Explorer style, without moving the current folder of the application - then writes the result (this raises nothing)
if GetFileOpenName("Icon", ls_path, ls_file, "png", "Pictures (*.png),*.png", /*initdir*/ "", OFN_EXPLORER + OFN_NOCHANGEDIR) = 1 then
    uo_grid.of_property(/*keys*/ as_keys).is_value = ls_path
end if

Vor dem Schreiben prüfen #

// The question is OFF by default : turn it on to be able to refuse a value
uo_grid.ib_veto_changes = true

// event ue_value_changing of uo_grid : (string as_keys, string as_value)
// FALSE refuses : the cell shows the old value again. is_error, set before, tells
// the user why : the help pane shows it until the value is edited again
choose case as_keys
    case "layout/width"
        if Long(as_value) < 200 or Long(as_value) > 4000 then
            uo_grid.of_property(/*keys*/ as_keys).is_error = "Between 200 and 4000 pixels."
            return false
        end if
    case "name"
        if Trim(as_value) = "" then
            uo_grid.of_property(/*keys*/ as_keys).is_error = "A window needs a name."
            return false
        end if
end choose

// Any other value is accepted
return true

Standardwerte, Änderungen und Abbrechen #

Zwei getrennte Begriffe, wie im Eigenschaftenfenster von Visual Studio und in einem DataWindow: der Standardwert (is_default) sagt, was fett geschrieben wird und was Entf wiederherstellt; die Referenz (of_load, of_reset_update) sagt, was zu speichern ist (of_is_dirty, of_dirty_keys) und was Abbrechen zurücksetzt (of_revert).

// The defaults of the window : a value that differs is written in bold
uo_grid.of_property(/*keys*/ "layout/width").is_default = "800"
uo_grid.of_property(/*keys*/ "layout/state").is_default = "normal"

// The width the user may type, and what Up / Down add or take
uo_grid.of_property(/*keys*/ "layout/width").is_min = "200"
uo_grid.of_property(/*keys*/ "layout/width").is_max = "4000"
uo_grid.of_property(/*keys*/ "layout/width").id_step = 50

// The saved settings, read back : they become the reference
uo_grid.of_load(/*json*/ is_saved_settings)

// OK : every value right first - otherwise the keyboard goes to the first error
if uo_grid.of_validate() > 0 then return

// Save only what changed (what the user is still typing counts too), then the screen becomes the reference
if uo_grid.of_is_dirty() then
    is_saved_settings = uo_grid.of_values()
    uo_grid.of_reset_update()
end if

// Cancel : every value back to the settings loaded
uo_grid.of_revert()

Eine aufklappbare Eigenschaft #

Eine Schrift passt in eine geschlossene Zeile, die ihre Werte zusammenfasst, und klappt zu ihren drei Eigenschaften auf. Ohne Vorlage lautet die Zusammenfassung Segoe UI; 9; False; is_summary schreibt sie nach Ihrem Geschmack: Segoe UI, 9 pt, dann , bold, solange Bold angehakt ist.

// A group in the category appearance : the font, closed when it is added
uo_grid.of_add_category(/*key*/ "appearance", /*title*/ "Appearance")
uo_grid.of_add_property(/*keys*/ "appearance/font", /*label*/ "Font", /*type*/ u_pbt_propertygrid.TYPE_GROUP, /*value*/ "")

// What it holds is added at its address
uo_grid.of_add_property(/*keys*/ "appearance/font/name", /*label*/ "Name", /*type*/ u_pbt_propertygrid.TYPE_STRING, /*value*/ "Segoe UI")
uo_grid.of_add_property(/*keys*/ "appearance/font/size", /*label*/ "Size", /*type*/ u_pbt_propertygrid.TYPE_NUMBER, /*value*/ "9")
uo_grid.of_add_property(/*keys*/ "appearance/font/bold", /*label*/ "Bold", /*type*/ u_pbt_propertygrid.TYPE_BOOLEAN, /*value*/ "false")

// Its summary, written your way : "Segoe UI, 9 pt", then ", bold" while Bold is checked
uo_grid.of_property(/*keys*/ "appearance/font").is_summary = "{name}, {size} pt{?bold}, bold{/bold}"

// Open it : its three values show under it
uo_grid.of_property(/*keys*/ "appearance/font").ib_expanded = true

// Local variables
n_pbt_json lnv_json
double ld_size

// The group is an object in the values : the same address reads its size
lnv_json.of_load(/*json*/ uo_grid.of_values())
ld_size = lnv_json.of_get_number(/*path*/ "appearance/font/size")

// event ue_property_toggled of uo_grid : (string as_keys, boolean ab_expanded)
// The group that opened or closed, by its address
if ab_expanded then
    lb_log.AddItem(as_keys + " opened")
else
    lb_log.AddItem(as_keys + " closed")
end if

Alle Werte auf einmal lesen #

// Local variables
n_pbt_json lnv_json
string ls_state

// Every value, typed, read along the same addresses as the grid
lnv_json.of_load(/*json*/ uo_grid.of_values())
w_customers.title = lnv_json.of_get_string(/*path*/ "name")
w_customers.width = lnv_json.of_get_number(/*path*/ "layout/width")
w_customers.resizable = lnv_json.of_get_boolean(/*path*/ "layout/resizable")

// One value alone : always text
ls_state = uo_grid.of_property(/*keys*/ "layout/state").is_value

Ansichten, Suche und Breite der Beschriftungen #

// One flat list sorted by label, instead of the categories
uo_grid.is_sort = u_pbt_propertygrid.SORT_ALPHABETICAL

// Keep only what speaks of a colour
uo_grid.is_filter = "colour"

// The labels take half of the width, and the help pane goes away
uo_grid.ii_label_width = 50
uo_grid.ib_help = false

Eine Kategorie durchlaufen #

// Local variables
n_pbt_propertygrid_category lnv_layout
string ls_keys
long ll_i

// Each property of the category, by its full address
lnv_layout = uo_grid.of_category(/*key*/ "layout")
for ll_i = 1 to lnv_layout.of_count()
    ls_keys = lnv_layout.of_keys_at(/*index*/ ll_i)
    lb_values.AddItem(ls_keys + " = " + uo_grid.of_property(/*keys*/ ls_keys).is_value)
next

Eine Auswahlliste neu laden #

// The states offered depend on the kind of window : the old choices go,
// the property keeps its handle, its flags and its place
uo_grid.of_clear_options(/*keys*/ "layout/state")

// The new choices, then the value to show among them
uo_grid.of_add_option(/*keys*/ "layout/state", /*value*/ "docked", /*text*/ "Docked")
uo_grid.of_add_option(/*keys*/ "layout/state", /*value*/ "floating", /*text*/ "Floating")
uo_grid.of_property(/*keys*/ "layout/state").is_value = "docked"

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" — unabhängig von der Sprache des Arbeitsplatzes. Für typisierte Werte of_values und n_pbt_json.
• Der Code schreibt still, der Benutzer meldet sich: is_value löst nichts aus, ue_value_changed spricht nur von den Gesten des Benutzers. Eine einzige Stelle wendet also die Änderungen an, wie im Inspektor-Beispiel.
• Beschreiben Sie: ein Satz in is_description ist mehr wert als eine überlange Beschriftung — der Hilfebereich zeigt ihn, wenn der Benutzer ihn braucht.
• ib_readonly statt ib_visible = false für einen Wert, den der Benutzer sehen, aber nicht ändern soll.
• Demomodus: ohne Schlüssel zeichnet das Raster 8 Eigenschaftszeilen, gezählt in der Reihenfolge des Bildschirms (Ansicht nach Kategorie): eine geschlossene Gruppe zählt als eine Zeile, und ihre Untereigenschaften — die ihre Zusammenfassung zeigt — zählen erst, wenn die Gruppe offen ist; Kategorie-Kopfzeilen zählen nicht. Der Rest bleibt im Speicher und in of_values, aber weder eine Zusammenfassung noch die Suche liest seinen Wert (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