commandpalette — `n_pbt_commandpalette` #

← Riferimento dei componenti · Sommario della guida

Palette dei comandi: l'utente preme una combinazione, digita tre lettere e raggiunge qualsiasi azione della sua applicazione — senza cercarla nei menu.

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

In breve #

Oggetto	`n_pbt_commandpalette` — non visuale: niente da posare nella finestra
Serve a	Rendere ogni azione dell'applicazione raggiungibile da tastiera, in tre lettere
Ritorno	Non bloccante: `of_open()` restituisce subito il controllo; la scelta torna come evento

La palette è una finestra staccata, tutta sua: fluttua sopra l'applicazione, prende il fuoco per il tempo in cui l'utente digita e lo restituisce chiudendosi.

Avvio rapido #

// Una volta, all'avvio : le azioni della sua applicazione
inv_palette.ipo_owner = this
inv_palette.of_add_command(/*key*/ "new",  /*label*/ "N", /*group*/ "F")
inv_palette.of_add_command(/*key*/ "open", /*label*/ "O", /*group*/ "F")
inv_palette.of_add_command(/*key*/ "save", /*label*/ "S", /*group*/ "F")
inv_palette.of_register_shortcut()

// event ue_command_selected : (string as_key)
choose case as_key
	case "new";  of_new()
	case "open"; of_open()
	case "save"; of_save()
end choose

Il collegamento: la finestra ospite #

La palette è un oggetto non visuale, ma non hai alcun ricevitore né messaggio da collegare: imposta ipo_owner sulla tua finestra, e la palette preleva da sola i suoi eventi e li solleva su quell'oggetto.

Due righe, una volta sola, all'apertura della finestra:

// La finestra a cui la palette appartiene
inv_palette.ipo_owner = this

// La palette deve rispondere al suo tasto
inv_palette.of_register_shortcut()

È tutto ciò che c'è da collegare. La scelta dell'utente, l'apertura e la chiusura le tornano poi come semplici eventi su ipo_owner — nessun ricevitore, nessun messaggio da mappare, nessun timer.

La combinazione: è la DLL a sentirla #

La combinazione che apre la palette non è ascoltata dalla pagina: è registrata presso la DLL, la sola a vedere i tasti premuti mentre il fuoco è su un altro controllo. È tutta la differenza fra una palette che si trova e una che risponde solo dopo averci cliccato sopra.

La DLL sente la combinazione, ma non apre nulla da sé: la avverte con ue_shortcut, e decide lei. Una palette che si apre sopra una finestra modale non aiuterebbe nessuno.

// event ue_shortcut : il tasto e caduto
if not ib_dialog_open then inv_palette.of_open()

is_shortcut sceglie la combinazione; of_register_shortcut() la consegna. La chiami una volta all'apertura della finestra — altrimenti la palette risponde al suo tasto solo dopo essere già stata aperta una volta. of_open la riconsegna al passaggio, quindi una combinazione cambiata dopo non richiede altro.

// La combinazione dell'abitudine, quella degli editor di codice
inv_palette.is_shortcut = inv_palette.SHORTCUT_DEFAULT

// Oppure la sua
inv_palette.is_shortcut = "ctrl+shift+p"

// Oppure nessuna : la palette si apre solo con of_open()
inv_palette.is_shortcut = inv_palette.SHORTCUT_NONE

La combinazione della palette viene consultata solo dopo le scorciatoie degli altri componenti della finestra, con o senza fuoco: un pulsante di barra degli strumenti sulla stessa combinazione vince. La combinazione di questa finestra passa prima di una registrata senza ipo_owner (tutta l'applicazione). Sono accettati solo i tasti che l'hook sa nominare — lettere, cifre, da F1 a F24, Invio, Esc, Canc, Ins, Home, Fine, PgSu, PgGiù e, con Ctrl o Alt, le frecce, Spazio, Tab, Backspace, + - , .; ogni altro restituisce -5. Il capitolo tastiera lo dettaglia.

Dove appare la palette #

is_position dice dove si posa la finestra. Viene sempre riportata dentro lo schermo: una palette ancorata sotto un campo in fondo alla finestra non sparisce dietro la barra delle applicazioni.

Costante	Dove
`POSITION_WINDOW_CENTER`	Centrata su `ipo_owner` — il valore predefinito, e ciò che l'occhio si aspetta
`POSITION_SCREEN_CENTER`	Centrata sullo schermo, qualunque sia la finestra
`POSITION_ABSOLUTE`	A `il_x` / `il_y`, in pixel schermo

PowerBuilder lavora in PBU, e la posizione di un controllo è relativa alla sua finestra: per ancorare la palette sotto un controllo, of_anchor_under(controllo) fa la conversione e imposta le tre proprietà. Su due schermi, si apre sullo schermo del punto richiesto.

La sua altezza segue il numero di comandi mostrati e si riduce man mano che si filtra — senza che l'angolo superiore si sposti, altrimenti la casella di ricerca scivolerebbe via sotto le dita. È limitata a metà schermo: oltre, la lista scorre all'interno e la casella di ricerca resta in alto.

Un clic altrove nell'applicazione chiude la palette, e quel clic raggiunge comunque il suo bersaglio — come uscendo da un menu. Non c'è nulla da fare.

Proprietà #

Proprietà	Tipo	Predefinito	Ruolo
`ipo_owner`	powerobject	—	La finestra a cui la palette appartiene: possiede la finestra popup e le fa da ancora, la sua combinazione risponde in quella finestra, e gli eventi della palette vengono sollevati su di essa. Da impostare prima di `of_open` — è l'unico collegamento da fare. Lasciata vuota, la combinazione risponde in tutte le finestre dell'applicazione. Due oggetti palette sulla stessa finestra mantengono ciascuno la propria combinazione e i propri eventi: nessuno riceve quelli dell'altro
`ipo_receiver`	powerobject	—	Opzionale, retaggio: un oggetto visuale distinto su cui consegnare gli eventi, al posto di `ipo_owner` — è anche l'unica finestra il cui `pbm_custom02` viene suonato a ogni evento. Lo lasci vuoto — la palette ora consegna i suoi eventi da sola tramite `ipo_owner`
`is_shortcut`	string	`"ctrl+k"`	Combinazione che apre la palette, da ovunque nella finestra. Costanti `SHORTCUT_DEFAULT` (`ctrl+k`) e `SHORTCUT_NONE` (nessuna). Ha effetto con `of_register_shortcut`
`is_position`	string	`window-center`	Dove si posa la finestra (costanti `POSITION_*`)
`il_x` · `il_y`	long	`0`	Posizione in pixel schermo, letta solo da `POSITION_ABSOLUTE`
`is_placeholder`	string	`""`	Testo grigio nella casella di ricerca finché non si digita nulla
`is_recent`	string	`""`	Memoria d'uso: gli id lanciati più di recente, dal più recente, separati da virgole. La palette li porta in cima, e la recenza dirime i pari merito durante il filtraggio — non ribalta mai la pertinenza. Rileggetela dopo l'uso e conservatela, rimettetela all'avvio. Una palette che riparte vuota ogni mattina non impara nulla
`il_max_recent`	long	`8`	Quante ne tiene il blocco « Usati di recente ». `8` per impostazione predefinita. `0` lo spegne: un'applicazione i cui utenti preferiscono vedere i gruppi intatti può dirlo. Una voce del blocco resta nel suo gruppo e ne porta il nome — una scorciatoia non sposta ciò che abbrevia

Metodi #

Metodo	Ruolo
`of_add_command (string as_key, string as_label, string as_group)`	Dichiara un'azione: il suo identificatore, la sua etichetta e il gruppo sotto cui appare. Restituisce `0` una volta aggiunta, `-5` se la chiave è vuota, contiene `/`, `	`o una virgola (`is_recent` è un elenco separato da virgole), o è già presa. Decine di migliaia di comandi restano fluidi: la palette disegna solo le righe visibili
`of_add_command (string as_key, string as_label, string as_group, string as_hint, string as_shortcut, string as_keywords)`	Lo stesso, con la spiegazione a destra, la combinazione da mostrare, che lancia il suo comando finché la palette è aperta — è così che la si impara ; fuori, la sua applicazione conserva i propri acceleratori, e durante la digitazione `Ctrl+C`, `Ctrl+V`, `Ctrl+Z` e `Ctrl+A` restano alla casella di ricerca — e parole chiave che la ricerca legge senza mostrarle. Restituisce `0` una volta aggiunta, `-5` se la chiave è vuota, contiene `/`, `	`o una virgola (`is_recent` è un elenco separato da virgole), o è già presa
`of_insert_command (string as_key, string as_label, string as_group, integer ai_index)`	Dichiara un'azione a un rango scelto (1 = in testa) invece che alla fine: un modulo condiviso mette i suoi comandi dove devono stare. `0` o meno, o oltre la fine, aggiunge in coda. Spiegazione, combinazione, parole chiave e icona si impostano poi con `of_command`. Restituisce `0` una volta aggiunta, `-5` per le stesse chiavi di `of_add_command`
`of_remove_command (string as_key)`	Toglie un'azione; le altre restano. Restituisce `0` una volta tolta, `-5` se nessun comando ha quella chiave
`of_command (string as_key)` → `n_pbt_commandpalette_command`	L'handle di un comando, per rinominarlo, cambiarne la combinazione, ingrigirlo o nasconderlo tramite le sue proprietà. Ingrigire invece di togliere: togliere ciò che l'utente non può fare ora gli toglie anche ogni possibilità di scoprire che esiste. Lo stato viaggia con i comandi: una modifica fatta a palette aperta si vede all'apertura successiva
`of_key ( )` → `string`	Sull'handle che `of_command` restituisce: la chiave del comando che designa — ciò che `of_command` ha ricevuto per ottenerlo, e ciò che si conserva quando l'handle passa di mano in mano
`of_clear_commands ( )`	Svuota la palette. Restituisce `0`
`of_count ( )` → `long`	Restituisce il numero di comandi che porta la palette
`of_keys_at ( long al_index )` → `string`	L'identificatore del comando di rango `al_index` (a partire da 1), oppure `""` oltre l'uno o l'altro estremo. Con `of_count`, è ciò che permette di percorrere una palette che non si è riempita da sé — un modulo condiviso vi aggiunge i propri
`of_has ( string as_key )` → `boolean`	Esiste un comando sotto questo identificatore? Chiedere è meglio che indovinare: `of_add_command` rifiuta (`-5`) un identificatore già preso
`of_anchor_under ( dragobject ado_control )`	Ancora la palette sotto un controllo — un campo, un pulsante: imposta `is_position` a `POSITION_ABSOLUTE` e `il_x` / `il_y` sull'angolo in basso a sinistra del controllo, in pixel schermo. Da chiamare prima di `of_open`; la palette resta riportata dentro lo schermo. Restituisce `0`, o `-5` se il controllo non è valido
`of_open ( )`	Apre la palette: una finestra tutta sua, posseduta da `ipo_owner`, posta da `is_position`. Prende il fuoco e lo restituisce chiudendosi. Restituisce `0` una volta richiesta — segue sempre `ue_opened` (a schermo) o `ue_closed` (con il motivo per cui non è apparsa) —, `-6` se manca il runtime WebView2, `-4` se la sua finestra non ha potuto essere creata
`of_is_open ( )`	VERO finché la palette è a schermo. È questo che permette alla combinazione di commutare: premuta una seconda volta una palette si chiude — richiamare `of_open` distruggerebbe la finestra per ricostruirla identica, il che si vede come uno sfarfallio, non come una chiusura. La DLL continua a non decidere nulla: informa. Una volta aperta, la palette tiene il fuoco nella propria finestra: la combinazione premuta lì la richiude da sola. Risponde per la palette di questo oggetto: quando un altro oggetto palette apre la propria, sostituisce questa e `of_is_open` risponde FALSO qui
`of_close ( )`	Richiude la palette aperta da questo oggetto — mai quella aperta nel frattempo da un altro oggetto palette. Anche perdere il fuoco la chiude, come un menu. Restituisce `0`
`of_register_shortcut ( )`	Consegna la combinazione di `is_shortcut` alla DLL. Da chiamare una volta all'apertura della finestra. Una sola combinazione per oggetto palette: richiamarla dopo aver cambiato `is_shortcut` sostituisce la precedente, che smette subito di rispondere — non c'è mai nulla da togliere prima. Restituisce `0` se posata, `1` se ne ha sostituita una, `2` se un `is_shortcut` vuoto non lascia alcuna combinazione (tolta, o non ce n'era), `-5` se il tasto è uno di quelli che l'hook non vede (vedi sopra) — la combinazione precedente resta allora in vigore. Senza `ipo_owner`, la combinazione risponde in tutte le finestre dell'applicazione. Due oggetti palette di una stessa finestra mantengono ciascuno la propria; la stessa combinazione registrata da un secondo oggetto passa a quest'ultimo (`1`). Distruggere l'oggetto toglie la sua combinazione — mai quella tenuta da un altro oggetto palette
`of_process_events ( )`	Preleva gli eventi in attesa e li solleva su `ipo_owner`. Il componente la chiama da solo finché la palette vive: normalmente non devi farlo
`of_reset ( )`	Svuota i comandi e la memoria d'uso (`is_recent`), riporta le proprietà ai valori predefiniti, richiude una palette aperta e riporta una combinazione registrata a `SHORTCUT_DEFAULT`. `ipo_owner` e `ipo_receiver` restano intatti: sono il cablaggio, non il contenuto

Proprietà di un comando — `n_pbt_commandpalette_command` #

Ottenuta con of_command(chiave). La palette ricostruisce la sua finestra dalla sua lista a ogni of_open: una proprietà cambiata mentre è aperta si vede all'apertura successiva.

Proprietà	Tipo	Predefinito	Ruolo
`is_label`	string	—	Il testo della riga
`is_shortcut`	string	`""`	La combinazione mostrata a destra della riga, valida finché la palette è aperta (`Ctrl+Shift+S`)
`is_group`	string	—	Il gruppo sotto cui il comando è elencato; cambiarlo lo sposta senza toglierlo (conserva il suo rango tra i comandi)
`is_hint`	string	`""`	La piccola riga sotto l'etichetta
`is_keywords`	string	`""`	Le parole che la ricerca legge senza mostrarle — le parole dell'utente
`is_icon`	string	`""`	Un'icona a sinistra della riga: un file, un'immagine di libreria, o `mono:` / `tint:` per una che segue il tema
`ib_enabled`	boolean	`true`	Comando ingrigito: visibile, cercabile e inerte — né clic, né Invio, né la sua combinazione
`ib_visible`	boolean	`true`	Comando nascosto: fuori dalla lista e dalle combinazioni, senza essere rimosso; torna com'era

Eventi #

Evento	Scatta quando
`ue_command_selected (string as_key)`	L'utente ha scelto un'azione. La palette si è già chiusa: fare ciò che annuncia spetta a lei
`ue_shortcut ( )`	La combinazione è stata premuta. La DLL riferisce, PB decide. Una palette commuta sul proprio tasto: `if of_is_open() then of_close() else of_open()` — premuta nella palette aperta, la combinazione la richiude da sola. Può anche rifiutare
`ue_opened ( )`	La palette è a schermo — tramite `of_open`
`ue_closed (string as_reason)`	Si è appena chiusa, con o senza scelta. Segue ogni `of_open` che ha restituito `0`: `as_reason` è vuoto per una palette che era a schermo, `cancelled` se è stata chiusa — o sostituita da un'altra palette — prima di apparire, `failed` se la sua finestra non ha potuto nascere, `blocked` sotto debug remoto senza licenza

La palette non fa nulla da sé. Riporta l'identificatore scelto e si chiude. È l'applicazione ad agire — la stessa azione, avviata da un menu o dalla palette, passa quindi per lo stesso codice.

Da tastiera #

Tasto	Effetto
La combinazione di `is_shortcut`	Avverte il suo codice con `ue_shortcut`; è lui ad aprire
Digitazione	Filtra mentre si scrive: le lettere non devono susseguirsi, `nvf` trova « Nuovo file », e gli accenti non contano (`preferences` trova « Préférences »)
Frecce su / giù	Spostano la selezione nell'elenco
Invio	Sceglie l'azione selezionata (`ue_command_selected`)
La combinazione mostrata su una riga	Lancia quel comando, senza doverlo selezionare
Esc	Chiude senza scegliere nulla

Esempi #

// Le parole chiave non si vedono, ma la ricerca le legge :
// digitare "pdf" trova l'esportazione anche se l'etichetta non lo dice
inv_palette.of_add_command(/*key*/ "export", /*label*/ "E", /*group*/ "F", /*hint*/ "H", /*shortcut*/ "Ctrl+E", /*keywords*/ "pdf csv xlsx")

Scegliere un'altra combinazione #

// Ctrl+K gia occupato dalla sua applicazione ? Ne scelga un altro.
// of_register_shortcut la consegna, la precedente se ne va da sola.
inv_palette.is_shortcut = "ctrl+shift+p"
inv_palette.of_register_shortcut()

Ancorarla sotto un campo #

// Ancorata sotto un campo, in pixel schermo
// La palette viene riportata dentro lo schermo se sporgeva
inv_palette.of_anchor_under(/*control*/ sle_1)
inv_palette.is_placeholder = "P"
inv_palette.of_open()

// Remove one command, empty the list, close the palette
inv_palette.of_remove_command(/*key*/ "print")
inv_palette.of_clear_commands()
inv_palette.of_close()

Buone pratiche #

Dia a ogni comando lo stesso identificatore del menu: una sola funzione tratta entrambi, e l'utente ottiene esattamente la stessa cosa.
Chiami of_register_shortcut() all'apertura della finestra, non al primo of_open: una palette che risponde al suo tasto solo dopo essere stata aperta col mouse non serve a niente.
Compili le parole chiave: è ciò che separa una palette che si usa da una in cui non si trova mai nulla. Pensi alle parole dell'utente, non alle sue.
Mostri la combinazione dell'azione in as_shortcut: la palette diventa così il modo per impararle.
Ci metta solo azioni immediate. Un comando che apre una finestra di configurazione, sì; uno che ha bisogno di tre parametri, no.
Tolga i comandi che non hanno più senso invece di lasciarli fallire: una palette che propone l'impossibile perde la fiducia in una volta sola.