commandpalette — n_pbt_commandpalette #

← Referência dos componentes · Índice do guia

Paleta de comandos: o utilizador prime um atalho, escreve três letras e alcança qualquer acção da sua aplicação — sem a procurar nos menus.

▶ Ver ao vivo — Aplicação de demonstração, mosaico Command palette: a pré-visualização, o código que o produz e esta página, lado a lado.

Em resumo #

A paleta é uma janela destacada, sua: paira sobre a aplicação, toma o foco enquanto o utilizador escreve e devolve-o ao fechar-se.

Início rápido #

// Uma vez, no arranque : as accoes da sua aplicacao
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 choose

A ligação: o receptor #

Um objecto não visual não tem identificador de janela: o Windows não sabe a quem entregar as mensagens da paleta. É esse o papel de ipo_receiver — um objecto visual, a sua janela por exemplo, que escuta e recolhe.

Três linhas, uma só vez, ao abrir a janela:

inv_palette.ipo_owner    = this   // a janela a que a paleta pertence
inv_palette.ipo_receiver = this   // a que recebera os eventos
inv_palette.of_register_shortcut()  // a paleta tem de responder a sua tecla

Depois, no receptor, o evento que recolhe:

// event ue_palette_msg pbm_custom02
inv_palette.of_process_events()

Sem essa recolha a paleta abre e funciona, mas nada lhe volta: nem a escolha, nem a abertura, nem o fecho.

O atalho: é a DLL que o ouve #

O atalho que abre a paleta não é escutado pela página: é registado junto da DLL, a única que vê as teclas premidas enquanto o foco está noutro controlo. É toda a diferença entre uma paleta que se encontra e uma que só responde depois de se ter clicado nela.

A DLL ouve o atalho, mas não abre nada por si: avisa-o através de ue_shortcut, e é o senhor que decide. Uma paleta a abrir por cima de um diálogo modal não ajudaria ninguém.

// event ue_shortcut : a tecla caiu
if not ib_dialog_open then inv_palette.of_open()

is_shortcut escolhe o atalho; of_register_shortcut() entrega-o. Chame-o uma vez ao abrir a janela — caso contrário a paleta só responde à sua tecla depois de já ter sido aberta uma vez. of_open volta a entregá-lo de passagem, portanto um atalho alterado mais tarde não precisa de mais nada.

// O atalho do costume, o dos editores de codigo
inv_palette.is_shortcut = inv_palette.SHORTCUT_DEFAULT

// Ou o seu
inv_palette.is_shortcut = "ctrl+shift+p"

// Ou nenhum : a paleta so abre por of_open()
inv_palette.is_shortcut = inv_palette.SHORTCUT_NONE

Dois componentes a pedir o mesmo atalho: ganha o que tem o foco, senão o primeiro registado. O capítulo do teclado detalha-o.

Onde a paleta aparece #

is_position diz onde a janela assenta. É sempre trazida de volta para dentro do ecrã: uma paleta ancorada sob um campo no fundo da janela não desaparece atrás da barra de tarefas.

O PowerBuilder trabalha em PBU: converta antes de preencher il_x / il_y.

A sua altura acompanha o número de comandos mostrados e diminui à medida que se filtra — sem que o canto superior se mexa, senão a caixa de pesquisa fugia debaixo dos dedos. Está limitada a meio ecrã: acima disso a lista desliza por dentro e a caixa de pesquisa fica em cima.

Um clique noutro sítio da aplicação fecha a paleta, e esse clique atinge na mesma o seu alvo — como ao sair de um menu. Nada a fazer para isso.

Propriedades #

Métodos #

Propriedades de um comando — n_pbt_commandpalette_command #

Obtida com of_command(chave). A paleta reconstrói a sua janela a partir da sua lista a cada of_open: uma propriedade alterada enquanto está aberta vê-se na abertura seguinte.

Eventos #

A paleta não faz nada por si. Comunica o identificador escolhido e fecha-se. É a sua aplicação que age — a mesma acção, accionada a partir de um menu ou da paleta, passa pelo mesmo código.

Pelo teclado #

Exemplos #

Alimentar a paleta a partir do seu menu #

// As palavras-chave nao se veem, mas a pesquisa le-as :
// escrever "pdf" encontra a exportacao mesmo que a etiqueta nao o diga
inv_palette.of_add_command(/*key*/ "export", /*label*/ "E", /*group*/ "F", /*hint*/ "H", /*shortcut*/ "Ctrl+E", /*keywords*/ "pdf csv xlsx")

Escolher outro atalho #

// Ctrl+K ja usado pela sua aplicacao ? Escolha outro.
// of_register_shortcut entrega-o, e o anterior sai sozinho.
inv_palette.is_shortcut = "ctrl+shift+p"
inv_palette.of_register_shortcut()

Ancorá-la sob um campo #

// Ancorada sob um campo : o PB conta em PBU, a DLL em pixeis
// A paleta e trazida de volta para dentro do ecra se transbordasse
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()

Boas práticas #

• Dê a cada comando o mesmo identificador que no seu menu: uma só função trata ambos, e o utilizador obtém exactamente a mesma coisa.
• Chame of_register_shortcut() ao abrir a janela, não no primeiro of_open: uma paleta que só responde à sua tecla depois de aberta com o rato não serve de nada.
• Preencha as palavras-chave: é o que separa uma paleta que se usa de uma onde nunca se encontra nada. Pense nas palavras do utilizador, não nas suas.
• Mostre o atalho da acção em as_shortcut: a paleta torna-se assim a maneira de os aprender.
• Ponha lá apenas acções imediatas. Um comando que abre um diálogo de configuração, sim; um que precisa de três parâmetros, não.
• Retire os comandos que já não fazem sentido em vez de os deixar falhar: uma paleta que oferece o impossível perde a confiança de uma vez.

← Referência dos componentes · Índice do guia