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.ipo_receiver = 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_nouveau()
case "open"; of_ouvrir()
case "save"; of_enregistrer()
end chooseIl cablaggio: il ricevitore #
Un oggetto non visuale non ha handle di finestra: Windows non sa a chi consegnare i messaggi della palette. È il compito di ipo_receiver — un oggetto visuale, la sua finestra per esempio, che ascolta e preleva.
Tre righe, una volta sola, all'apertura della finestra:
inv_palette.ipo_owner = this // la finestra a cui la palette appartiene
inv_palette.ipo_receiver = this // quella che ricevera gli eventi
inv_palette.of_register_shortcut() // la palette deve rispondere al suo tastoPoi, sul ricevitore, l'evento che preleva:
// event ue_palette_msg pbm_custom02
inv_palette.of_process_events()Senza quel prelievo la palette si apre e funziona, ma non le torna nulla: né la scelta, né l'apertura, né la chiusura.
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_NONEDue componenti che chiedono la stessa combinazione: vince quello che ha il fuoco, altrimenti il primo registrato. 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: converta prima di riempire il_x / il_y.
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. Da impostare prima di of_open |
ipo_receiver | powerobject | — | L'oggetto visuale che riceve gli eventi. Dichiara event xxx pbm_custom02 e vi chiama of_process_events |
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 applicato, -5 per un argomento non valido (chiave vuota, indirizzo errato), -2 se il componente non è creato |
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 parole chiave che la ricerca legge senza mostrarle. Restituisce 0 una volta applicato, -5 per un argomento non valido (chiave vuota, indirizzo errato), -2 se il componente non è creato |
of_remove_command (string as_key) | Toglie un'azione; le altre restano. Restituisce 0 una volta applicato, -5 per un argomento non valido (chiave vuota, indirizzo errato), -2 se il componente non è creato |
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_clear_commands ( ) | Svuota la palette. Restituisce 0 una volta applicato, -2 se il componente non è creato |
of_count ( ) → integer | Quanti comandi porta la palette |
of_keys_at ( integer ai_index ) → string | L'identificatore del comando di rango ai_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 evita di dichiararne un secondo sotto un identificatore già preso |
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 aperta, -1 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 |
of_close ( ) | La richiude. 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 finestra: 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 l'ha tolta |
of_process_events ( ) | Preleva gli eventi in attesa e li solleva su questo oggetto. Da chiamare dal pbm_custom02 di ipo_receiver — è l'unica via di ritorno |
of_reset ( ) | Svuota i comandi e riporta le proprietà ai valori predefiniti. ipo_owner e ipo_receiver restano intatti: sono il cablaggio, non il contenuto. Restituisce 0 una volta applicato, -2 se il componente non è creato |
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) |
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(). Può anche rifiutare |
ue_opened ( ) | La palette è a schermo — tramite of_open |
ue_closed ( ) | Si è appena chiusa, con o senza scelta |
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 » |
| 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 #
Alimentare la palette dal proprio menu #
// 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 : PB conta in PBU, la DLL in pixel
// La palette viene riportata dentro lo schermo se sporgeva
inv_palette.is_position = inv_palette.POSITION_ABSOLUTE
inv_palette.il_x = UnitsToPixels(sle_1.x, XUnitsToPixels!)
inv_palette.il_y = UnitsToPixels(sle_1.y + sle_1.height, YUnitsToPixels!)
inv_palette.is_placeholder = "P"
inv_palette.of_open()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 primoof_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.