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) · `n_pbt_menubar_menu` (un menu della barra)
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 "file/open"; of_open_document()
	case "file/save"; of_save_document()
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`	la sua chiave, `file`
La voce di un menu	`of_add_item`	l'indirizzo `menu/voce`, `file/open`
La sotto-voce di una voce	`of_add_item`	l'indirizzo `menu/voce/sottovoce`, `file/export/pdf` — profondo quanto serve

Una chiave è unica solo sotto il suo genitore: per questo una voce si designa sempre con il suo indirizzo completo, prima il menu — mai con la sola chiave. Due menu possono quindi avere ciascuno la propria voce open, e due sottomenu il proprio pdf (file/export/pdf, file/print/pdf), senza disturbarsi. Una chiave non contiene né / né |, non è vuota e non inizia con __: le aggiunte la rifiutano (-5), come rifiutano un indirizzo già preso o un genitore mai aggiunto.

Un separatore non ha chiave: of_add_separator traccia una linea alla fine di un menu (file) o della cascata di una voce (file/export), e dopo non c'è nulla da rileggere.

Proprietà #

Proprietà	Tipo	Predefinito	Ruolo
`is_theme_style`	string	`""`	Stile visivo del componente (costanti `THEME_STYLE_*`); vuoto = quello dell'applicazione, seguito a ogni cambio
`is_theme_mode`	string	`""`	Variante chiara o scura (costanti `THEME_MODE_*`); vuoto = quella dell'applicazione, seguita a ogni cambio
`il_theme_accent`	long	`-1`	Colore d'accento di questo componente (`-1` = accento dell'applicazione, o quello 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
`ib_wrap`	boolean	`false`	`false` (predefinito): la barra resta su una riga; i titoli che non entrano, a partire dalla fine, passano nel menu di un chevron in fondo (le loro voci in cascata), e l'altezza non cambia più. `true`: la barra va a capo e annuncia la nuova altezza (`ue_auto_height`) — ciò che faceva prima della 4.0
`ib_track_hover`	boolean	`false`	Sottoscrizione a `ue_item_hover`: senza di essa i menu a discesa non segnalano nemmeno la voce puntata — un evento scatenato a ogni movimento del puntatore viene inviato solo a un'applicazione che lo ha chiesto

Proprietà di una voce — `n_pbt_menubar_item` #

Ottenute con of_item(indirizzo) — of_item("file/export/pdf"). Un indirizzo di un solo livello designa un menu, non una voce: il suo handle non cambia nulla, usate of_menu.

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. Una scorciatoia sospesa conserva la sua combinazione: non arriva nemmeno alla sua applicazione; `is_shortcut = ""` gliela restituisce
`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. Tasti: una lettera, una cifra, da `F1` a `F24`, `Enter`, `Esc`, `Del`, `Insert`, `Home`, `End`, `PageUp`, `PageDown`, e con Ctrl o Alt anche `+`, `-`, `,`, `.`, le frecce (`Left`…), `Space`, `Tab`, `Backspace` (`Ctrl++` per lo zoom). Una scorciatoia va su una foglia: su una voce che apre una cascata non è né mostrata né attivata. Una stringa vuota toglie entrambi
`ib_checked`	boolean	`false`	Spunta mostrata davanti alla voce — per un'opzione che si attiva e si disattiva
`is_image`	string	`""`	L'icona della voce, cambiata al volo: la voce conserva il suo posto nell'elenco. Stessi percorsi di `of_add_item` (`mono:`, `tint:`, `file.dll:NOME`); una stringa vuota la toglie
`is_group`	string	`""`	Rende la voce una voce radio: le voci di uno stesso gruppo sotto lo stesso genitore si escludono — spuntarne una (`ib_checked = true`, o la scelta dell'utente) toglie la spunta alle altre, e un pallino tondo sostituisce la spunta. `ue_item_selected` dice sempre quale è stata scelta. Una stringa vuota la rende di nuovo una voce ordinaria
`il_accent`	long	`-1`	Accento di questa voce: la spunta e il bordo quando è puntata (`-1` = quello del tema)
`il_back_color`	long	`-1`	Sfondo di questa voce nell'elenco, a riposo
`il_text_color`	long	`-1`	Colore del testo di questa voce
`il_back_color_hover`	long	`-1`	Sfondo di questa voce quando è puntata
`il_text_color_hover`	long	`-1`	Colore del testo di questa voce quando è puntata
`is_tooltip`	string	`""`	Conservata e rileggibile, ma una voce dell'elenco non mostra alcun tooltip: l'elenco nativo non ne ha. Solo i titoli dei menu mostrano il loro (`of_menu`)
`is_super_tooltip_title`	string	`""`	Titolo del suo tooltip avanzato — conservato, non mostrato (vedi `is_tooltip`)
`is_super_tooltip_text`	string	`""`	Testo del suo tooltip avanzato — conservato, non mostrato
`is_super_tooltip_image`	string	`""`	Immagine del suo tooltip avanzato — conservata, non mostrata

Proprietà di un menu — `n_pbt_menubar_menu` #

Ottenute con of_menu(chiave) — of_menu("file"). Colori e tooltip appaiono sul titolo del menu nella barra.

Proprietà	Tipo	Predefinito	Ruolo
`is_text`	string	—	Etichetta del menu, `&` compreso (mnemonico), cambiata senza ricostruire la barra
`ib_enabled`	boolean	`true`	Menu ingrigito: non si apre più, le sue voci e le loro scorciatoie con lui; la tastiera lo salta
`ib_visible`	boolean	`true`	Il menu lascia la barra — voci e scorciatoie addormentate con lui — e vi torna tale e quale. Le scorciatoie addormentate conservano la loro combinazione: non arriva nemmeno alla sua applicazione
`is_align`	string	`"start"`	`u_pbt_menubar.ALIGN_END` colloca il menu in fondo alla barra, come Aiuto — con quelli che lo seguono nello stesso allineamento, dopo di esso; `ALIGN_START` (predefinito) lo rimette tra gli altri. Logico: il fondo è il lato sinistro in un layout da destra a sinistra. Con il chevron, i titoli in fondo si ripiegano per primi
`il_accent`	long	`-1`	Accento di questo menu: una linea sotto il titolo finché il suo elenco è aperto (`-1` = nessuno)
`il_back_color`	long	`-1`	Sfondo del suo titolo, a riposo
`il_text_color`	long	`-1`	Colore del testo del suo titolo, a riposo
`il_back_color_hover`	long	`-1`	Sfondo del suo titolo al passaggio o aperto
`il_text_color_hover`	long	`-1`	Colore del testo del suo titolo al passaggio o aperto
`is_tooltip`	string	`""`	Tooltip mostrato quando il puntatore sosta sul suo titolo
`is_super_tooltip_title`	string	`""`	Titolo del tooltip avanzato del suo titolo
`is_super_tooltip_text`	string	`""`	Testo di quel tooltip avanzato (markup ricco accettato)
`is_super_tooltip_image`	string	`""`	Immagine di quel tooltip avanzato

Metodi #

Metodo	Ruolo
`of_add_menu (string as_key, string as_text)`	Aggiunge un menu alla barra. Restituisce `0` una volta applicato, `-5` se la chiave è rifiutata (vuota, con `/` o una barra verticale, che inizia con `__`, o già presa), `-2` se il componente non è creato
`of_add_item (string as_keys, string as_text)`	Aggiunge una voce al suo indirizzo: `file/open` nel menu File, `file/export/pdf` sotto la voce Export, profondo quanto serve. Restituisce `0` una volta applicato, `-5` se l'indirizzo è rifiutato: meno di due livelli, un livello vuoto, una chiave con `/` o una barra verticale o che inizia con `__`, un menu o una voce genitore mai aggiunti, o un indirizzo già preso. `-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 e la spunta. Per ingrigire la voce, ora o più tardi, passate dal suo handle: `of_item(indirizzo).ib_enabled = false`. Restituisce `0` una volta applicato, `-5` se l'indirizzo è rifiutato: meno di due livelli, un livello vuoto, una chiave con `/` o una barra verticale o che inizia con `__`, un menu o una voce genitore mai aggiunti, o un indirizzo già preso. `-2` se il componente non è creato
`of_add_separator (string as_keys)`	Traccia una linea di separazione alla fine di un menu (`file`) o della cascata di una voce (`file/export`). Restituisce `0` una volta applicato, `-5` se a quell'indirizzo non è stato aggiunto nulla, `-2` se il componente non è creato
`of_add_header (string as_keys, string as_text)` → `long`	Aggiunge un'intestazione di sezione alla fine di un menu (`view`) o della cascata di una voce (`view/panels`): una riga di titolo sopra le voci che la seguono, fino alla prossima intestazione o separatore. Non è una voce — mai scelta, mai contata da `of_count`, né nel limite demo — e non viene disegnata quando tutte le voci che introduce sono nascoste. Restituisce `0` una volta aggiunta, `-5` se a quell'indirizzo non è stato creato nulla, `-2` se il componente non è creato
`of_item (string as_keys)` → `n_pbt_menubar_item`	Handle di una voce, tramite il suo indirizzo — `of_item("file/export/pdf")` —, per leggerne o impostarne le proprietà. È esattamente ciò che restituisce `ue_item_selected`: l'argomento si ridà tale e quale qui. Mai la sola chiave: due sottomenu possono avere ciascuno il proprio `pdf`, e solo l'indirizzo li distingue. Un indirizzo di un livello designa un menu: il suo handle non cambia nulla, usate `of_menu`
`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`	Rimuove una voce, al suo indirizzo (`file/open`, `file/export/pdf`) — con la sua cascata; le altre restano. I suoi handle sono liberati e la sua scorciatoia disarmata: il tasto torna alla vostra applicazione. Senza di essa c'era solo `of_clear`, che svuota tutto — il menu dinamico più comune, un elenco di file recenti, costringeva a radere l'intera barra a ogni documento aperto. Restituisce `0` una volta applicato, `-5` se a quell'indirizzo non vive alcuna voce, `-2` se il componente non è creato
`of_remove_menu (string as_key)` → `long`	Rimuove un menu di primo livello, con le sue voci — handle liberati, scorciatoie disarmate. La barra viene ridisegnata e la sua altezza riannunciata. Restituisce `0` una volta applicato, `-5` per un menu mai aggiunto, `-2` se il componente non è creato
`of_clear ( )`	Svuota la barra — menu e voci; i loro handle sono liberati e le scorciatoie delle voci disarmate. 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 quando un menu di primo livello sta per aprirsi — e l'elenco aspetta: si apre solo quando l'evento è tornato. Attivate, ingrigite o riempite qui le sue voci: la modifica si vede a questa apertura, non alla successiva. Senza di esso l'intera barra andava tenuta al passo con lo stato dell'applicazione in permanenza, o mostrava voci che mentono
`ue_menu_closed (string as_key)`	Il menu a tendina di un menu di primo livello si è chiuso senza scelta: per mano dell'utente (clic fuori, Esc, o scivolamento verso il menu vicino), oppure dal suo codice che rimuove, svuota, nasconde o disattiva il menu aperto (`of_remove_menu`, `of_clear`, `ib_visible`, `ib_enabled`) — anche un ordine lo solleva. Annulli qui ciò che `ue_menu_opening` aveva preparato (un'anteprima, una selezione). Una scelta solleva invece `ue_item_selected`, e `of_reset` non solleva nulla
`ue_item_selected (string as_keys)`	L'utente ha scelto una voce, o premuto la sua scorciatoia. `as_keys` è il suo indirizzo, prima il menu — `file/open`, `file/export/pdf`: la sola chiave non dice da quale sottomenu viene, e due sottomenu possono avere ciascuno la propria. Lo stesso testo si ridà tale e quale a `of_item`. Una voce ingrigita, nascosta o rimossa mentre il suo elenco era aperto non solleva nulla
`ue_item_hover (string as_keys)`	Con `ib_track_hover = true`: la voce sotto il puntatore o la tastiera in un menu a discesa aperto, con il suo indirizzo (`file/export/pdf`) — anche una voce disattivata, il suo aiuto può dire perché. Scatenato una volta per voce, poi con un indirizzo vuoto alla chiusura del menu (prima di `ue_item_selected` su una scelta): scrivete il testo di aiuto di una barra di stato, poi svuotatelo
`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`)

Una riga, per impostazione predefinita. I titoli che non entrano passano nel chevron in fondo alla barra (ib_wrap = false, il valore predefinito): l'altezza resta quella di una riga e ue_auto_height viene scatenato una volta. Con ib_wrap = true la barra va a capo: non scorre mai, la sua altezza segue le righe e ue_auto_height vi dice di quanto a ogni cambio di larghezza.

Da tastiera #

Tasto	Effetto
Alt · F10	Dà la tastiera alla barra e sottolinea le lettere dei menu, come in qualunque applicazione Windows; una seconda pressione la restituisce
»	Il chevron dei titoli che non entrano: le frecce vi si fermano come su un titolo, Invio o Giù apre l'elenco dei menu nascosti, e Alt + la lettera di un menu nascosto apre quel menu dal chevron
Alt + lettera	Apre il menu di quella lettera (`&File`) da qualunque controllo della finestra — un campo, un DataWindow. Una scorciatoia `Alt+lettera` registrata dalla sua applicazione ha la precedenza. Due menu sulla stessa lettera: la banda passa dall'uno all'altro, Invio apre. Una lettera accentata o non latina si digita come sulla tastiera (`&Édition`: Alt + il tasto della É)
Frecce	Percorrono i menu e le loro voci, saltando i menu ingrigiti; la destra apre una sotto-voce, la sinistra risale. In scrittura da destra a sinistra (`RTL`) tutto si capovolge: sulla barra, nel menu a tendina (allineato al bordo destro del suo titolo) e nelle cascate, che si aprono a sinistra — la sinistra apre, la destra risale
Invio	In un menu a tendina: sceglie la voce evidenziata (`ue_item_selected`). Su un titolo della barra, Invio, Spazio o Freccia giù aprono il menu. Spazio non sceglie una voce — è anche la regola di Windows
Esc	Chiude il menu aperto, poi restituisce il focus al controllo che lo aveva

Una barra dei menu non tiene mai il focus. Un clic su un titolo, poi una scelta col mouse: la tastiera torna al controllo in cui si digitava prima che ue_item_selected parta. Modifica > Incolla incolla quindi nel campo in modifica, e GetFocus() lo nomina nell'evento.

Esempi #

// Bloccare il disegno durante la costruzione
uo_menus.of_set_redraw(/*on*/ false)

// Il menu File, con un'icona su Apri e una linea prima di Esci
uo_menus.of_add_menu(/*key*/ "file", /*text*/ "&File")
uo_menus.of_add_item(/*keys*/ "file/open", /*text*/ "&Apri...", /*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*/ "&Esci")

// Un sottomenu: Esporta, poi i suoi due formati
uo_menus.of_add_item(/*keys*/ "file/export", /*text*/ "&Esporta")
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*/ "&Visualizza")
uo_menus.of_add_item(/*keys*/ "view/grid", /*text*/ "&Griglia", /*image*/ "", /*checked*/ true)

// Un solo ridisegno, con tutto
uo_menus.of_set_redraw(/*on*/ 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

Voci radio e una scorciatoia di zoom #

// Due voci RADIO: spuntarne una toglie la spunta all'altra, un pallino sostituisce la spunta
uo_menus.of_add_item(/*keys*/ "view/small", /*text*/ "Icone &piccole")
uo_menus.of_add_item(/*keys*/ "view/large", /*text*/ "Icone &grandi")
uo_menus.of_item(/*keys*/ "view/small").is_group = "size"
uo_menus.of_item(/*keys*/ "view/large").is_group = "size"
uo_menus.of_item(/*keys*/ "view/large").ib_checked = true

// Lo zoom: Ctrl++ e mostrato E attivo, ovunque sia il focus
uo_menus.of_add_item(/*keys*/ "view/zoomin", /*text*/ "&Ingrandisci")
uo_menus.of_item(/*keys*/ "view/zoomin").is_shortcut = "Ctrl++"

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(/*on*/ false)
uo_menus.of_clear()
uo_menus.of_add_menu(/*key*/ "tools", /*text*/ "&Strumenti")
uo_menus.of_set_redraw(/*on*/ true)

Una barra stretta, Aiuto in fondo, un testo di aiuto nella barra di stato #

// Help at the end of the bar ; what does not fit goes into the chevron
uo_menubar.of_menu(/*key*/ "help").is_align = u_pbt_menubar.ALIGN_END

// Section headers in View
uo_menubar.of_add_header(/*keys*/ "view", /*text*/ "Panels")
uo_menubar.of_add_item(/*keys*/ "view/tree", /*text*/ "Tree")
uo_menubar.of_add_item(/*keys*/ "view/output", /*text*/ "Output")

// A help text in the status bar for the pointed entry
uo_menubar.ib_track_hover = true

// ue_item_hover (string as_keys) of uo_menubar
choose case as_keys
	case "file/save"
		st_status.Text = "Saves the document"
	case ""
		st_status.Text = ""
end choose

Buone pratiche #

Dia una chiave di dominio stabile a ogni livello (file, save): ue_item_selected restituisce l'indirizzo file/save, mai l'etichetta — non 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.
Le etichette sono sue: le traduca prima di of_add_item, o le cambi al volo con of_item(...).is_text / of_menu(...).is_text. of_set_translation traduce solo i testi propri di un componente, e la barra dei menu non ne ha.
Metta una & in ogni titolo (&File): Alt + la lettera apre il menu da ovunque, come in qualunque applicazione Windows.

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.