menubar — `u_pbt_menubar` #

← Riferimento dei componenti · Indice della guida

Barra dei menu dell'applicazione: menu, sottomenu, voci spuntabili, separatori, icone e scorciatoie — tutto disegnato dalla libreria, senza alcun menu di Windows.

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

In breve #

Userobject	`u_pbt_menubar`
Classe di item	`n_pbt_menubar_item` (una voce)
Serve a	Dare alla Sua finestra la barra dei menu dell'applicazione, con lo stesso tema di tutto il resto
Principio	Dichiara i menu, poi le loro voci; ogni voce si ritrova tramite l'indirizzo `menu/id`

Avvio rapido #

// event open della finestra
uo_menus.of_add_menu(/*key*/ "file", /*text*/ "File")
uo_menus.of_add_item(/*keys*/ "file/open", /*text*/ "Apri")
uo_menus.of_add_item(/*keys*/ "file/save", /*text*/ "Salva")

// event ue_item_selected : (string as_keys)
choose case as_keys
	case "open"; of_ouvrir()
	case "save"; of_enregistrer()
end choose

Il modello: tre livelli, una chiave per livello #

Una barra dei menu ha tre livelli, e ciascuno si indica con la sua chiave:

Livello	Aggiunto da	Chiave
Il menu della barra	`of_add_menu`	il suo `id`
La voce di un menu	`of_add_item`	l'indirizzo `menu/id`
La sotto-voce di una voce	`of_add_item`	l'indirizzo `menu/voce/sotto-voce` — tre livelli

Un id di voce è unico solo all'interno del suo menu: per questo of_item ne chiede due. Due menu possono quindi avere ciascuno la propria voce "open" senza disturbarsi.

Un separatore non ha chiave: of_add_separator traccia una linea nel punto in cui lo chiama, e non c'è nulla da rileggere in seguito.

Proprietà #

Proprietà	Tipo	Predefinito	Ruolo
`is_theme_style`	string	`fluent`	Stile visivo del componente (costanti `THEME_STYLE_*`)
`is_theme_mode`	string	`light`	Variante chiara o scura (costanti `THEME_MODE_*`)
`il_theme_accent`	long	`-1`	Colore d'accento di questo componente (`-1` = accento del tema)
`is_tooltip`	string	`""`	Tooltip semplice mostrato al passaggio sul componente
`is_super_tooltip_title`	string	`""`	Titolo del tooltip avanzato (prevale su `is_tooltip`)
`is_super_tooltip_text`	string	`""`	Testo del tooltip avanzato (markup avanzato accettato)
`is_super_tooltip_image`	string	`""`	Immagine del tooltip avanzato

Proprietà di una voce — `n_pbt_menubar_item` #

Ottenute con of_item(menu/id):

Proprietà	Tipo	Predefinito	Ruolo
`is_text`	string	—	Cambia l'etichetta della voce, a caldo
`ib_enabled`	boolean	`true`	Voce attiva; una voce disattivata non risponde più al clic
`ib_visible`	boolean	`true`	Voce tolta dall'elenco senza essere rimossa — sottomenu e scorciatoia sospesi con lei; conserva la sua chiave e torna com'era
`is_shortcut`	string	`""`	L'acceleratore mostrato a destra della voce (`Ctrl+S`) — e attivo: la combinazione solleva `ue_item_selected` per quella voce, ovunque sia il focus. In un menu si imparano le scorciatoie di un'applicazione; un tasto mostrato che non fa nulla insegna il contrario. Una stringa vuota toglie entrambi
`ib_checked`	boolean	`false`	Spunta mostrata davanti alla voce — per un'opzione che si attiva e si disattiva
`is_tooltip`	string	`""`	Tooltip di questa voce
`is_super_tooltip_title`	string	`""`	Titolo del suo tooltip avanzato
`is_super_tooltip_text`	string	`""`	Testo del suo tooltip avanzato (markup avanzato accettato)
`is_super_tooltip_image`	string	`""`	Immagine del suo tooltip avanzato

Metodi #

Metodo	Ruolo
`of_add_menu (string as_key, string as_text)`	Aggiunge un menu alla barra. Restituisce `0` una volta applicato, `-2` se il componente non è creato
`of_add_item (string as_keys, string as_text)`	Aggiunge una voce a un menu. Restituisce `0` una volta applicato, `-5` per un argomento non valido (chiave vuota, indirizzo errato), `-2` se il componente non è creato
`of_add_item (string as_keys, string as_text, string as_image, boolean ab_checked)`	Lo stesso, con l'icona, la spunta e lo stato iniziale. Restituisce `0` una volta applicato, `-5` per un argomento non valido (chiave vuota, indirizzo errato), `-2` se il componente non è creato
`of_add_separator (string as_keys)`	Traccia una linea di separazione in fondo al menu. Restituisce `0` una volta applicato, `-2` se il componente non è creato
`of_item (string as_keys)` → `n_pbt_menubar_item`	Handle di una voce, per impostarne le proprietà. `as_key` accetta entrambe le scritture: l'identificatore nudo della foglia e il percorso completo con le chiavi unite da `/` — `of_item("file", "export/pdf")`. È il percorso che restituisce `ue_item_selected`: i suoi due argomenti si ridanno tali e quali qui. Un identificatore nudo è unico solo dentro il proprio sottomenu
`of_menu (string as_key)` → `n_pbt_menubar_menu`	Handle di un menu di primo livello, per rinominarlo o spegnerlo. `of_add_menu` poteva farlo solo alla creazione: ingrigire Admin alla disconnessione richiedeva di ricostruire tutta la barra; `ib_visible` lo toglie dalla barra, voci e scorciatoie sospese con lui
`of_remove_item (string as_keys)` → `long`	Toglie una voce; le altre restano. `as_key` accetta le due scritture di `of_item`: il percorso completo (`export/pdf`) o l'id nudo. Senza di essa c'era solo `of_clear`, che svuota tutto — il menu dinamico più comune, un elenco di file recenti, imponeva di radere l'intera barra a ogni documento aperto. Restituisce `0` una volta applicato, `-5` per un argomento non valido (chiave vuota, indirizzo errato), `-2` se il componente non è creato
`of_remove_menu (string as_key)` → `long`	Toglie un menu di primo livello, con le sue voci. La barra viene ridisegnata e la sua altezza riannunciata. Restituisce `0` una volta applicato, `-2` se il componente non è creato
`of_clear ( )`	Svuota la barra — menu e voci. Restituisce `0` una volta applicato, `-2` se il componente non è creato
`of_reset ( )`	Svuota la barra e riporta tutte le proprietà ai valori predefiniti. Restituisce `0` una volta applicato, `-2` se il componente non è creato
`of_set_redraw (boolean)`	Raggruppa una raffica di modifiche in un solo rendering. Restituisce `0` una volta applicato, `-2` se il componente non è creato
`of_save_as_png (string)` · `of_save_as_jpg (string)`	Esporta il rendering come immagine. Restituisce `0` una volta scritta l'immagine, `-4` se la scrittura fallisce, `-2` se il componente non è creato

Event #

Event	Scatta quando
`ue_menu_opening (string as_key)`	Sollevato nell'istante in cui si clicca un menu di primo livello, prima che il suo elenco sia costruito. È il momento di attivare, ingrigire o riempire le sue voci appena in tempo — senza di esso l'intera barra andava tenuta al passo con lo stato dell'applicazione in permanenza, o mostrava voci che mentono
`ue_item_selected (string as_keys)`	L'utente ha scelto una voce. `as_key` è un percorso non appena la voce è annidata — `export/pdf`, non `pdf`: la foglia da sola non dice da quale sottomenu proviene, e due sottomenu possono averne ciascuno una propria. Una voce di primo livello conserva il suo identificatore nudo. Lo stesso testo si restituisce tale e quale a `of_item`
`ue_auto_height (long al_height)`	La barra annuncia l'altezza che le serve — riposizioni ciò che sta sotto
`ue_ready ( )`	Il componente ha finito di caricare; tutto ciò che è stato inviato prima è stato riprodotto
`ue_runtime_missing ( )`	Il runtime WebView2 è assente: il componente resta vuoto
`ue_bg_color (long al_color)`	Il componente ha calcolato il colore di sfondo del tema; l'userobject l'ha già adottato (`backcolor`)

L'altezza non si imposta, si annuncia. Una barra dei menu non scorre: un'altezza fissa può solo produrre spazio vuoto sotto la barra o menu troncati. Si adatta quindi sempre, e ue_auto_height Le dice di quanto.

Da tastiera #

Tasto	Effetto
Alt	Dà il focus alla barra, come in qualunque applicazione Windows
Frecce	Percorrono i menu e le loro voci; la destra apre una sotto-voce, la sinistra risale
Invio o Spazio	Sceglie la voce con il focus (`ue_item_selected`)
Esc	Chiude il menu aperto, poi restituisce il focus

Esempi #

uo_menus.of_set_redraw(false)

// Il menu File, con un'icona su Apri e una linea prima di Esci
uo_menus.of_add_menu(/*key*/ "file", /*text*/ "F")
uo_menus.of_add_item(/*keys*/ "file/open", /*text*/ "O", /*image*/ "mono:img\packimages.dll:svg/samples/folder-open", /*checked*/ false)
uo_menus.of_add_separator(/*keys*/ "file")
uo_menus.of_add_item(/*keys*/ "file/quit", /*text*/ "Q")

// Un sottomenu: Esporta, poi i suoi due formati
uo_menus.of_add_item(/*keys*/ "file/export", /*text*/ "E")
uo_menus.of_add_item(/*keys*/ "file/export/csv", /*text*/ "CSV")
uo_menus.of_add_item(/*keys*/ "file/export/pdf", /*text*/ "PDF")

// Il menu Visualizza: un'opzione che si spunta
uo_menus.of_add_menu(/*key*/ "view", /*text*/ "V")
uo_menus.of_add_item(/*keys*/ "view/grid", /*text*/ "G", /*image*/ "", /*checked*/ true)

uo_menus.of_set_redraw(true)

Spuntare, togliere, disattivare #

// L'utente ha invertito la visualizzazione della griglia
uo_menus.of_item(/*keys*/ "view/grid").ib_checked = not uo_menus.of_item(/*keys*/ "view/grid").ib_checked

// Una voce che non ha piu senso si disattiva, non sparisce:
// l'utente deve poter vedere che esiste
uo_menus.of_item(/*keys*/ "file/save").ib_enabled = false

Ricostruire la barra #

// Cambiare area di lavoro: si svuota e si ricostruisce
// of_set_redraw evita di ridisegnare a ogni riga
uo_menus.of_set_redraw(false)
uo_menus.of_clear()
uo_menus.of_add_menu(/*key*/ "tools", /*text*/ "T")
uo_menus.of_set_redraw(true)

Buone pratiche #

Dia a ogni voce un identificatore di dominio stabile ("save"): è quello che riceve in ue_item_selected, non un'etichetta che cambia con la lingua.
Disattivi invece di rimuovere: una voce assente lascia l'utente a cercare, una voce disattivata gli dice che esiste e che gli manca qualcosa.
Racchiuda la costruzione tra of_set_redraw(false) / of_set_redraw(true): una barra completa sono presto trenta chiamate.
Riposizioni ciò che sta sotto la barra in ue_auto_height — l'altezza dipende dal tema e dal corpo del carattere, non è la stessa ovunque.
Per le etichette, passi da of_set_translation se la Sua applicazione è multilingue: veda il capitolo sulla lingua.

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.

Membri	Ruolo	Descritto in
`of_count` · `of_keys_at` · `of_has`	Percorrere ciò che il componente contiene	3.2 Gli item
`of_reset`	Riportare il componente a zero	3.6 Riportare un componente a zero: `of_reset()`
`of_register_shortcut` · `of_clear_shortcuts`	Scorciatoie da tastiera del componente	3.5 Le scorciatoie da tastiera
`of_is_created` · `of_is_ready` · `of_get_last_error`	Se è nato, se è pronto, cosa è fallito	3.7 Diagnostica
`of_save_as_png` · `of_save_as_jpg`	Esportare il rendering in immagine	3.8 Esportare il rendering come immagine
`of_set_redraw`	Raggruppare le modifiche in un solo ridisegno	3.10 Buone pratiche
`of_preload_icons`	Icone mostrate senza ritardo	Visualizzazione istantanea: `of_icon`
`of_set_translation`	Tradurre una dicitura del componente	5.2 Adattare un'etichetta: `of_set_translation`
`of_focus_webview`	Dare il focus al componente	6.4 Tastiera e focus
`of_print` · `of_print_to_pdf`	Stampare, o scrivere un PDF	6.9 Stampare
`of_set_property` · `of_get_property` · `of_component_name`	Pilotare una proprietà per nome	3.1 Il motore delle proprietà

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.