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.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

A ligação: a janela anfitriã #

A paleta é um objeto não visual, mas não tem qualquer recetor nem mensagem a ligar: defina ipo_owner na sua janela, e a paleta recolhe sozinha os seus eventos e dispara-os nesse objeto.

Duas linhas, uma só vez, ao abrir a janela:

// A janela a que a paleta pertence
inv_palette.ipo_owner = this

// A paleta tem de responder a sua tecla
inv_palette.of_register_shortcut()

É tudo o que há para ligar. A escolha do utilizador, a abertura e o fecho voltam depois como simples eventos em ipo_owner — sem recetor, sem mensagem a mapear, sem temporizador.

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

O atalho da paleta só é consultado depois dos atalhos dos outros componentes da janela, com ou sem foco: um botão de barra de ferramentas com o mesmo atalho ganha. O atalho desta janela passa antes de um atalho registado sem ipo_owner (toda a aplicação). Só são aceites as teclas que o gancho sabe nomear — letras, algarismos, F1 a F24, Enter, Esc, Del, Ins, Home, End, PgUp, PgDn e, com Ctrl ou Alt, as setas, Espaço, Tab, Retrocesso, + - , .; qualquer outra devolve -5. 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, e a posição de um controlo é relativa à sua janela: para ancorar a paleta sob um controlo, of_anchor_under(controlo) faz a conversão e define as três propriedades. Com dois ecrãs, abre no ecrã do ponto pedido.

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, em pixeis de ecra
// A paleta e trazida de volta para dentro do ecra se transbordasse
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()

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