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 #
Posi n_pbt_commandpalette sulla finestra come oggetto non visuale (qui chiamato inv_palette): i suoi eventi si scrivono su di esso, come quelli di un controllo.
// Una volta, all'avvio : le azioni della sua applicazione
inv_palette.ipo_owner = this
inv_palette.of_add_command(/*key*/ "new", /*label*/ "New project", /*group*/ "File")
inv_palette.of_add_command(/*key*/ "open", /*label*/ "Open file...", /*group*/ "File")
inv_palette.of_add_command(/*key*/ "save", /*label*/ "Save", /*group*/ "File")
inv_palette.of_register_shortcut()// event ue_command_selected of inv_palette : (string as_key)
// parent is the window : the palette runs nothing by itself
choose case as_key
case "new"; parent.wf_new()
case "open"; parent.wf_open()
case "save"; parent.wf_save()
end chooseIl collegamento: la finestra ospite #
La palette è un oggetto non visuale, ma non c'è alcun ricevitore né messaggio da collegare: preleva da sola i suoi eventi e li solleva su se stessa — ue_command_selected, ue_shortcut, ue_opened e ue_closed si scrivono sull'oggetto palette posato nella finestra (o su un suo discendente). ipo_owner dice a quale finestra appartiene.
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 tornano poi come semplici eventi dell'oggetto palette (non di
ipo_owner) — nessun ricevitore, nessun messaggio da mappare, nessun timer. Un evento può aprire una MessageBox o chiudere la finestra («Esci»): i successivi aspettano che sia finito, e una palette distrutta con la sua finestra si ferma in modo pulito.
Dove scrivere gli event #
PowerBuilder offre gli event di un oggetto non visuale in due soli posti: la palette posta nella finestra (nel painter, Insert > Object, poi n_pbt_commandpalette, chiamata inv_palette: i suoi event si scrivono come quelli di un controllo — è ciò che presuppongono gli esempi di questa pagina), oppure un discendente di n_pbt_commandpalette (n_my_palette), i cui event portano i vostri script e che la finestra crea con create n_my_palette. Una variabile n_pbt_commandpalette creata con create non ha script: la palette si apre, ma la scelta dell'utente non arriva a nessuno.
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_NONELa 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, e la sua combinazione risponde in quella finestra. Da impostare prima di of_open. Lasciata vuota, la combinazione risponde in tutte le finestre dell'applicazione. Gli eventi non vengono sollevati su di essa ma sull'oggetto palette stesso. Due oggetti palette sulla stessa finestra mantengono ciascuno la propria combinazione e i propri eventi: nessuno riceve quelli dell'altro |
ipo_receiver | powerobject | — | Facoltativo, ereditato: una finestra il cui pbm_custom02 viene suonato a ogni evento, per il codice precedente che vi chiamava of_process_events. Lo lasci vuoto — la palette consegna i suoi eventi da sola, su se stessa |
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, il più recente per primo, separati da virgole. La palette li fa salire in cima; quando si filtra, la recenza spareggia soltanto risultati che corrispondono più o meno allo stesso modo — non fa mai passare una corrispondenza più debole davanti a una migliore, qualunque sia il_max_recent. Gli spazi attorno agli id e i doppioni vengono ripuliti, e la lista pulita torna qui. La rilegga dopo l'uso e la conservi; la reimposti all'avvio. Una palette che riparte da zero ogni mattina non impara nulla |
il_max_recent | long | 8 | Quanti ne tiene il blocco « Usati di recente ». 8 per impostazione predefinita. Un limite abbassato taglia is_recent all'apertura successiva. 0 lo spegne: un'applicazione i cui utenti preferiscono i gruppi intatti può dirlo — is_recent resta allora così com'è, inutilizzato. 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. Un comando dal gruppo vuoto viene **per primo**, senza intestazione; of_get_last_error` dice perché una chiave è stata rifiutata |
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. Un comando dal gruppo vuoto viene **per primo**, senza intestazione; of_get_last_error` dice perché una chiave è stata rifiutata |
of_insert_command (string as_key, string as_label, string as_group, long al_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_insert_command (string as_key, string as_label, string as_group, string as_hint, string as_shortcut, string as_keywords, long al_index) | La forma completa, come la prende of_add_command: la spiegazione, la combinazione da mostrare e le parole chiave arrivano con il comando, al suo rango. Stessi valori restituiti | |
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. Una chiave che nessun comando porta dà un handle che non designa nulla: i suoi booleani si rileggono FALSE, i suoi testi "", e una scrittura va persa — of_get_last_error lo dice | |
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, compresi i comandi letti da un menu (of_load_menu). 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. Un controllo (o una finestra) che si legge da destra a sinistra dà il suo angolo in basso a destra: la palette si allinea su quel bordo e si apre verso sinistra | |
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. I comandi letti da un menu (of_load_menu) prendono lo stato della loro voce in quel momento | |
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. La combinazione ripresa da un secondo oggetto torna al primo quando il secondo viene distrutto. Finché una finestra è attiva, la combinazione della palette passa prima degli acceleratori del suo menu PowerBuilder: una voce di menu sullo stesso tasto non la sente più | |
of_process_events ( ) | Preleva gli eventi in attesa e li solleva sull'oggetto palette stesso. Il componente lo chiama da solo finché la palette vive: non deve farlo lei. Un evento che apre una MessageBox non si vede sollevare i successivi nel mezzo, e un evento che chiude la finestra della palette ferma il prelievo in modo pulito | |
of_reset ( ) → long | 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. Anche i comandi letti da un menu se ne vanno Rende 0 una volta fatto. | |
of_load_menu ( menu am_menu ) | Riempie la palette da un menu PowerBuilder: ogni voce senza sottovoci diventa un comando, senza dichiarare due volte le azioni — passi this.MenuID o una delle sue voci. Chiave = il ClassName della voce, etichetta = il suo testo senza & né la scorciatoia scritta dopo una tabulazione, gruppo = i testi delle voci sopra di essa, scorciatoia = quella che mostra, parole chiave = il suo MicroHelp. Il menu resta il padrone: riletto a ogni of_open, una voce disattivata, nascosta o rinominata si mostra com'è (una voce padre porta con sé le sue). Scegliere un comando solleva ue_command_selected e non esegue nulla. Una seconda chiamata sostituisce i comandi della prima; quelli di of_add_command restano. Restituisce 0, -5 quando il menu non è valido | |
of_loaded_item ( string as_key ) → menu | La voce di menu PowerBuilder da cui viene un comando (of_load_menu): in ue_command_selected, of_loaded_item(as_key).TriggerEvent(Clicked!) esegue ciò che esegue il menu. Una chiave che non viene da un menu dà un riferimento non valido: lo verifichi con IsValid | |
of_get_last_error ( ) → string | Perché l'ultima chiamata ha restituito -5 (una chiave rifiutata, un menu non valido, una combinazione che la tastiera non sa riportare), o l'ultima scrittura di un handle di comando che non ha raggiunto alcun comando. "" quando nulla è andato storto: ogni chiamata che agisce lo svuota prima |
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. Il tasto sinistro, Invio o la combinazione mostrata su una riga scelgono; un clic destro o centrale non fa nulla. L'evento può aprire una MessageBox o chiudere la finestra |
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 |
| Pag su / Pag giù | Spostano la selezione di una schermata |
| Home / Fine | Con del testo digitato: all'inizio / alla fine della ricerca. Campo vuoto: al primo / ultimo comando. Ctrl+Home / Ctrl+Fine: sempre il primo / ultimo comando; Maiusc+… seleziona nel campo |
| Tab | Resta nel campo di ricerca (la palette è un dialogo modale) |
| Un clic destro o centrale su una riga | Non fa nulla: solo il tasto sinistro sceglie |
Mentre un metodo di input (giapponese, cinese, coreano) compone, Invio e le frecce gli appartengono: confermare una conversione non lancia mai un comando.
Esempi #
Alimentare la palette dal proprio menu #
// Every action of your menu becomes a command : nothing declared twice
inv_palette.of_load_menu(/*menu*/ this.MenuID)
// The palette answers its key from the window's opening
inv_palette.of_register_shortcut()// Local variables
menu lm_item
// event ue_command_selected of inv_palette : run what the menu item runs
lm_item = inv_palette.of_loaded_item(/*key*/ as_key)
if IsValid(lm_item) then lm_item.TriggerEvent(Clicked!)Le parole che la ricerca legge #
// 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*/ "Export", /*group*/ "File", /*hint*/ "PDF, CSV or xlsx", /*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 = "Type a command..."
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 #
- Ha già un menu PowerBuilder?
of_load_menu(this.MenuID)ne fa dei comandi, e il menu resta il padrone. - 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.