radialmenu — u_pbt_radialmenu #

← Referência dos componentes · Índice do guia

Menu de contexto radial: os comandos em coroa à volta do cursor, escolhidos pela direção em vez de lidos numa lista.

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

Em resumo #

Arranque rápido #

// Uma roda montada para o que esta sob o cursor
uo_wheel.of_add_item(/*keys*/ "cut",    /*text*/ "Cut")
uo_wheel.of_add_item(/*keys*/ "copy",   /*text*/ "Copy")
uo_wheel.of_add_item(/*keys*/ "paste",  /*text*/ "Paste")
uo_wheel.of_add_item(/*keys*/ "delete", /*text*/ "Delete")

// Abre-se ao soltar o botao direito: ver ue_rclicked

Abrir e depois escolher #

A roda abre-se ao largar o botão direito, e é preciso um segundo clique para escolher. Não é um detalhe de implementação: se abrisse ao premir, o largar desse mesmo clique selecionaria de imediato o setor caído sob o cursor, e o utilizador lançaria um comando sem o ter visto.

É por isso que of_show() é chamado a partir do evento de clique direito do controlo sobre o qual o utilizador faz o gesto (um statictext, um button, uma grelha…): nesse instante o botão já está em cima, e o clique seguinte é mesmo o que escolhe. O menu radial, esse, não tem superfície nenhuma — logo, nenhum evento de rato próprio.

O componente em si é invisível: não ocupa lugar na janela. Coloque-o onde quiser, com largura e altura nulas — só existe enquanto a roda está aberta.

O ramo apontado — com o rato ou o teclado — mostra o rótulo inteiro, por cima dos vizinhos: um setor guarda no máximo duas linhas (uma só a partir de nove ramos), e é isso que lhe permite levar um rótulo curto sem mentir sobre o que faz. O cubo central é a saída: clicar nele fecha a roda; dentro de uma sub-roda, sobe um nível. Enquanto a roda está aberta a aplicação continua a correr: um ramo retirado, desativado ou ocultado entretanto já não se escolhe (em vez disso, ue_dismissed); of_clear, of_reset, of_close e um segundo of_show fecham a roda aberta, e também of_remove_item quando a roda mostrava o ramo retirado — ue_dismissed é disparado de imediato, e of_is_open responde falso assim que a chamada regressa.

// Abre-se ao soltar o botao direito: ver ue_rclicked
uo_wheel.of_show()

Pelo teclado, as setas percorrem os ramos saltando os desativados, Enter ou Espaço escolhe, ← e Retrocesso sobem um nível, e Escape sobe um nível numa sub-roda — só fecha a roda na raiz. Nenhuma destas teclas chega à aplicação enquanto a roda está aberta. Em leitura da direita para a esquerda, a coroa gira no outro sentido e ← e → trocam de papel: → sobe um nível.

Para a abrir pelo teclado — a tecla Menu, Shift+F10 —, chame of_show_over a partir do controlo que tem o foco, com ab_keyboard a verdadeiro: a roda centra-se nesse controlo, esteja onde estiver o rato, e o seu primeiro ramo que responde fica aceso — Enter escolhe-o, as setas continuam a partir daí. of_show_over(controlo) sem esse segundo argumento serve também um botão de barra de ferramentas: a roda abre-se sobre ele.

As sub-rodas #

Um endereço pendura ramos sob outro: export/pdf. Escolher o ramo pai não escolhe nada: a roda é substituída pela dos seus filhos, e o cubo passa a ser o caminho de volta.

Porquê substituir em vez de acrescentar uma segunda coroa? Porque um anel exterior dividiria os setores por dois em cada nível. Oito ramos já é o máximo legível; não há espaço para mostrar dois níveis ao mesmo tempo.

O evento ue_item_selected comunica o endereço completo (export/pdf), não a chave da folha sozinha. Duas sub-rodas podem portanto nomear os seus ramos da mesma forma.

// A branch, then two entries at its address
uo_wheel.of_add_item(/*keys*/ "export", /*text*/ "Export")
uo_wheel.of_add_item(/*keys*/ "export/pdf", /*text*/ "PDF")
uo_wheel.of_add_item(/*keys*/ "export/csv", /*text*/ "CSV")

Para retirar um ramo — com a sua sub-roda — sem reconstruir toda a roda: of_remove_item("export/csv"). Os outros ramos ficam no lugar.

Quando há ramos a mais #

Uma roda lê-se pela direção, e para além de oito setores as fatias deixam de se distinguir. ii_max_sectors fixa esse teto (de 3 a 12, 8 por predefinição).

Os ramos a mais não se perdem: o último lugar da coroa passa a ser um ramo que os contém a todos e que abre como sub-roda. Um menu que deixasse cair a cauda seria um menu que mente sobre o que oferece.

Apertar a coroa é muitas vezes um ganho: quatro ramos largos apontam-se mais depressa do que oito estreitos.

Propriedades #

Métodos #

Eventos #

Um clique num canto da janela, fora do disco, conta como um clique fora: a roda fecha-se (ue_dismissed) e o clique passa para a aplicação que está atrás, em vez de ser engolido por um quadrado invisível.

Propriedades de item #

Um ramo não mostra nenhuma dica: a janela redonda não tem espaço fora do disco. O is_tooltip herdado pelo manípulo é guardado e relê-se, mas nunca é mostrado — é o ramo apontado que mostra o rótulo inteiro.

Exemplos #

Uma roda por contexto #

// Uma roda montada para o que esta sob o cursor
uo_wheel.of_clear()
uo_wheel.of_add_item(/*keys*/ "bold", /*text*/ "Bold", /*image*/ "mono:img\packimages.dll:svg/samples/bold", /*checked*/ true)
uo_wheel.of_add_item(/*keys*/ "find", /*text*/ "Find", /*image*/ "mono:img\packimages.dll:svg/samples/find", /*checked*/ false)

Reagir ao caminho escolhido #

// Evento ue_item_selected do menu radial
// as_keys traz o caminho completo, p. ex. "export/pdf"
choose case as_keys
	case "export/pdf"
		of_export_pdf()
	case "delete"
		of_delete_selection()
end choose

Marcar, desativar, apertar #

// Mark a branch as being on
uo_wheel.of_item(/*keys*/ "bold").ib_checked = true

// Grey out the one that makes no sense here
uo_wheel.of_item(/*keys*/ "paste").ib_enabled = false

// No maximo quatro ramos numa coroa
uo_wheel.ii_max_sectors = 4

Pelo teclado, e fechada pelo código #

// Tecla Menu na grelha: a roda abre-se centrada nela, primeiro ramo aceso
uo_wheel.of_show_over(/*control*/ dw_orders, /*keyboard*/ true)

// Mais tarde, a partir de um temporizador: a roda fecha sem escolha (ue_dismissed)
if uo_wheel.of_is_open() then uo_wheel.of_close()

Um grupo de opção, um comando que destrói #

// Tres ramos exclusivos: escolher um desmarca os outros dois
uo_wheel.of_item(/*keys*/ "align/left").is_group = "align"
uo_wheel.of_item(/*keys*/ "align/center").is_group = "align"
uo_wheel.of_item(/*keys*/ "align/right").is_group = "align"

// Delete assume o tom do perigo, claro ou escuro
uo_wheel.of_item(/*keys*/ "delete").is_tone = u_pbt_radialmenu.TONE_DANGER

Boas práticas #

• Abra ao LARGAR o clique direito do controlo, nunca ao premir. É o que separa abrir de escolher, e o utilizador precisa de ambos.
• Rótulos curtos. Uma ou duas palavras. O setor está lá para a direção; o texto inteiro só se lê ao apontar o ramo.
• Quatro a seis ramos valem mais que oito. Uma roda recorda-se pela posição; quantas menos posições, mais depressa se aprendem.
• Ponha os comandos mais frequentes em cima e em baixo. São as duas direções que a mão alcança sem pensar.
• Mantenha a ordem estável de uma abertura para a outra: todo o interesse de uma roda é que o gesto acabe por preceder a leitura.
• Um menu radial não substitui um menu de lista. Vinte comandos raros leem-se melhor numa lista; guarde a roda para o punhado que se usa a toda a hora.

Herdado da base comum #

Estes membros existem em todos os componentes visuais — não são próprios deste. São detalhados uma só vez, nos capítulos transversais; esta tabela apenas diz onde os ler.

Neste lançador invisível, of_count e of_keys_at percorrem o que adicionou, ramos ocultos incluídos — não o que a roda vai desenhar. A exportação como imagem, a impressão, of_focus_webview e of_set_redraw não têm aqui efeito útil: o componente não desenha nada de próprio, a roda vive na sua própria janela.

Duas ajudas não são herdadas: of_icon e of_escape_markup vivem em n_pbt_utils. Declare um — n_pbt_utils lnv_utils, nada a criar — e chame-as nele.

← Referência dos componentes · Índice do guia