propertygrid — u_pbt_propertygrid #

← Riferimento dei componenti · Sommario della guida

propertygrid è la finestra delle proprietà di un IDE, per i vostri dati: valori con nome, ordinati in categorie che si comprimono, ognuno con l'editor del suo tipo — testo, numero, casella di controllo, elenco di scelte, colore, data, password. Due viste (per categoria, alfabetica), una casella di ricerca, un riquadro di guida che descrive la proprietà selezionata e un pulsante … che apre una vostra finestra di dialogo. L'utente modifica, ue_value_changed ve lo dice.

▶ Vederlo dal vivo — Applicazione dimostrativa, riquadro Property grid: l'anteprima, il codice che lo produce e questa pagina, affiancati.

In breve #

Avvio rapido #

// 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

Un indirizzo per proprietà #

Una proprietà si designa con il suo indirizzo: la sola chiave al primo livello ("title"), la categoria poi la proprietà unite da / sotto una categoria ("page/margin"). Una proprietà espandibile (TYPE_GROUP) contiene a sua volta delle proprietà, aggiunte al suo indirizzo: "appearance/font/size" nel gruppo font della categoria appearance, "margin/left" in un gruppo in cima — e un gruppo può contenerne un altro. Ciò che contiene una proprietà è quindi una categoria (un solo livello) o un gruppo. Una categoria si designa con la sola chiave. Al primo livello, una chiave nomina una cosa sola: una categoria e una proprietà in cima non possono condividerla. Gli eventi portano lo stesso indirizzo, quello che avete scritto.

// 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"

I tipi di valore #

Il tipo si sceglie una volta, in of_add_property, e dà l'editor della riga. Il valore invece è sempre testo — dato, letto, consegnato dagli eventi — scritto allo stesso modo qualunque sia la lingua della postazione.

Un valore che il suo tipo non può contenere è rifiutato — da of_add_property (-5) come da is_value o is_default (il vecchio resta) — e of_get_last_error dice perché: un numero che non lo è, un booleano diverso da true / false / 1 / 0, una data che non è un vero yyyy-mm-dd, un colore che non è un intero a partire da -1, un TYPE_STRING o un TYPE_PASSWORD su più righe (il campo della griglia contiene una riga). "" (nessun valore) è sempre accettato. Un valore di elenco che nessuna opzione offre è accettato, e mostrato così com'è: un elenco può essere caricato dopo il suo valore. Il colore -1 — quello che dà il tema, la convenzione di tutta la libreria — appare «(predefinito)»; un colore di sistema e i true / false di un riepilogo si scrivono nella lingua di visualizzazione.

Proprietà #

Proprietà di una categoria — n_pbt_propertygrid_category #

Proprietà di una proprietà — n_pbt_propertygrid_property #

Metodi #

Sul componente #

Su una categoria e su una proprietà #

Una categoria contiene proprietà; un gruppo (TYPE_GROUP) contiene le sue sotto-proprietà; una proprietà elenco (TYPE_ENUM) contiene le sue opzioni, designate dal loro valore. I tre metodi le percorrono.

Eventi #

Tastiera e mouse #

Esempi #

Le impostazioni di una finestra #

// 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")

Un ispettore che applica ogni modifica #

// 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

Il pulsante …: una vostra finestra di dialogo #

// 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

Convalidare prima di scrivere #

// 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

Valori predefiniti, modifiche e Annulla #

Due nozioni distinte, come nella finestra delle proprietà di Visual Studio e in un DataWindow: il valore predefinito (is_default) dice cosa si scrive in grassetto e cosa Canc ripristina; il riferimento (of_load, of_reset_update) dice cosa c'è da salvare (of_is_dirty, of_dirty_keys) e cosa Annulla rimette (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()

Una proprietà espandibile #

Un carattere sta in una riga chiusa, che riassume i suoi valori, e si apre sulle sue tre proprietà. Senza modello il riepilogo è Segoe UI; 9; False; is_summary lo scrive a modo vostro: Segoe UI, 9 pt, poi , bold finché Bold è spuntato.

// 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

Leggere tutti i valori insieme #

// 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

Viste, ricerca e larghezza delle etichette #

// 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

Percorrere una categoria #

// 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

Ricaricare un elenco di scelte #

// 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"

Buone pratiche #

• Un valore è un testo: un numero si scrive con il punto ("12.5"), un booleano "true"/"false", un colore String(RGB(…)), una data "yyyy-mm-dd" — qualunque sia la lingua della postazione. Per valori tipizzati, of_values e n_pbt_json.
• Il codice scrive in silenzio, l'utente avvisa: is_value non solleva nulla, ue_value_changed parla solo dei gesti dell'utente. Un solo punto applica quindi le modifiche, come nell'esempio dell'ispettore.
• Descrivete: una frase in is_description vale più di un'etichetta lunghissima — il riquadro di guida la mostra quando l'utente ne ha bisogno.
• ib_readonly piuttosto che ib_visible = false per un valore che l'utente deve vedere senza poterlo cambiare.
• Modalità dimostrativa: senza chiave, la griglia disegna 8 righe di proprietà, contate nell'ordine dello schermo (vista per categoria): un gruppo chiuso conta per una riga, e le sue sotto-proprietà — che il suo riepilogo mostra — contano solo quando il gruppo è aperto; le intestazioni di categoria non contano. Il resto rimane in memoria e in of_values, ma né un riepilogo né la ricerca ne leggono il valore (vedere Licenza).

Ereditato dalla base comune #

Questi membri esistono su tutti i componenti visivi — non sono propri di questo. Sono descritti una sola volta, nei capitoli trasversali; questa tabella dice solo dove leggerli.

Due aiuti non sono ereditati: of_icon e of_escape_markup vivono su n_pbt_utils. Ne dichiari uno — n_pbt_utils lnv_utils, niente da creare — e li chiami su di esso.

← Riferimento dei componenti · Sommario della guida