contextmenu — u_pbt_contextmenu #

← Referência dos componentes · Índice do guia

O menu de contexto do Windows, com o tema da aplicação: uma lista em cascata que se abre no cursor, sob um controlo ou num ponto do ecrã — ícones, atalhos mostrados, marcas de verificação, entradas de opção, cabeçalhos de secção, listas longas que deslizam e respondem à escrita.

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

Em resumo #

Início rápido #

// The menu of a grid : three commands, a separator, a cascade
uo_menu.of_add_item(/*keys*/ "copy", /*text*/ "&Copy")
uo_menu.of_add_item(/*keys*/ "paste", /*text*/ "&Paste")
uo_menu.of_add_item(/*keys*/ "delete", /*text*/ "&Delete")
uo_menu.of_add_separator(/*keys*/ "")
uo_menu.of_add_item(/*keys*/ "export", /*text*/ "&Export")
uo_menu.of_add_item(/*keys*/ "export/pdf", /*text*/ "PDF")
uo_menu.of_add_item(/*keys*/ "export/csv", /*text*/ "CSV")

// It opens from the right-click event of the grid : see Where to call of_show

// event ue_item_selected of uo_menu : (string as_keys)
// as_keys is the ADDRESS of the chosen entry
choose case as_keys
	case "copy"
		of_copy_selection()
	case "export/pdf"
		of_export("pdf")
end choose

Abrir o menu #

O componente em si é invisível: não ocupa espaço na janela. Coloque-o em qualquer lado, largura e altura nulas — só existe enquanto o menu está aberto. Quatro maneiras de o abrir:

• of_show() — no cursor, a partir do clique direito do controlo que recebe o gesto — veja a tabela abaixo.
• of_show_under(controlo) — sob um controlo: o menu pende do seu bordo inferior, alinhado pelo seu bordo de início (o bordo direito numa disposição da direita para a esquerda), e abre-se por cima quando o ecrã acaba por baixo. O que um botão Mais ou … precisa — e o teclado: of_show_under(controlo, true) destaca a primeira entrada ativa.
• of_show(x, y) — num ponto do ecrã, em píxeis. Coordenadas negativas são um ponto real: um ecrã colocado à esquerda ou acima do principal.
• of_show_at(controlo, x, y) — num ponto dentro de um controlo, em unidades PowerBuilder a partir do seu canto superior esquerdo: o ponto que PopMenu recebia, nada a converter. of_source() nomeia depois esse controlo em ue_item_selected — um só menu para vários controlos.

// event rbuttondown of a DataWindow : the row under the cursor first
if row > 0 then dw_list.SetRow(/*row*/ row)
uo_menu.of_show()

// event ue_clicked of a "More" button : the menu hangs from it
uo_menu.of_show_under(/*control*/ uo_more)

// event rbuttondown of a DataWindow, another way : the point in the control, in
// PowerBuilder units, as PopMenu took it
uo_menu.of_show_at(/*control*/ dw_list, /*x*/ dw_list.PointerX(), /*y*/ dw_list.PointerY())

Onde chamar of_show #

of_show() abre-se onde está o cursor, ou seja, onde o utilizador clicou: nenhuma unidade a converter. of_show(x, y) espera píxeis do ecrã, nunca as unidades PowerBuilder de um xpos/ypos relativo ao controlo. Para um ponto dentro de um controlo, em unidades PowerBuilder, há of_show_at(controlo, x, y).

Pelo teclado — Shift+F10 ou a tecla Menu — o rato está em qualquer lado: abra o menu sob o controlo que tem o foco, com of_show_under(controlo, true). Como no Windows, a sua primeira entrada ativa fica destacada: Enter escolhe-a, as setas partem daí. Com o PowerBuilder 10, pbm_contextmenu só recebe o clique direito, e Shift+F10 não chega a um campo de introdução (medido: nem pbm_contextmenu, nem pbm_keydown, nem pbm_syskeydown). A tecla que abre o menu num controlo PowerBuilder é portanto a tecla Menu (KeyApps!), tomada num evento de utilizador em pbm_keydown — pbm_dwnkey para um DataWindow, cujo clique direito passa pelo seu evento rbuttondown: pbm_contextmenu não chega aí com um clique numa célula (medido). Shift+F10 continua a ser recebido pelos próprios componentes PBToolboxAI (o seu ue_rclicked).

// User event ue_contextmenu of an edit field, mapped on pbm_contextmenu :
// the right-click opens the menu at the cursor
uo_menu.of_show()

// The field does not open its own Windows menu as well
return 1

// User event ue_key of the same field, mapped on pbm_keydown : the Menu key
// opens the menu under the field, its first entry highlighted
if key = KeyApps! then
	uo_menu.of_show_under(/*control*/ this, /*keyboard*/ true)
	return 1
end if

// User event ue_key of a DataWindow, mapped on pbm_dwnkey : the Menu key
if key = KeyApps! then
	uo_menu.of_show_under(/*control*/ this, /*keyboard*/ true)
	return 1
end if

Uma única resposta por abertura: um menu aberto termina com uma escolha (ue_item_selected) ou sem ela (ue_dismissed — um clique fora, Esc, of_close). Um menu que não tem nada para mostrar não se abre: ue_dismissed chega de imediato. Enquanto o menu está no ecrã a aplicação continua a correr: uma entrada desativada, oculta ou retirada entretanto já não pode ser escolhida (ue_dismissed em vez disso), e of_remove_item, of_clear ou of_reset fecham o menu aberto. ue_dismissed(as_reason) diz porquê: REASON_ESCAPE (Esc), REASON_OUTSIDE (um clique fora), REASON_FOCUS (outra janela tomou o foco), REASON_USER (de outra forma, outro menu que toma o lugar), REASON_CODE (of_close, uma entrada retirada ou o menu esvaziado), REASON_REPLACED (um segundo of_show), REASON_EMPTY (nada para mostrar), REASON_UNAVAILABLE (a entrada escolhida já não estava disponível).

Um menu de cada vez: um segundo of_show substitui o menu aberto, que responde primeiro ue_dismissed. E of_close chamado logo depois de of_show fecha o menu antes mesmo de ser desenhado — também se segue ue_dismissed.

Pelo teclado, as setas percorrem as entradas saltando as desativadas, → abre uma cascata e ← fecha-a, Enter escolhe, Esc sobe um nível e depois fecha. A letra sublinhada — a que segue & no rótulo, && para um e comercial — escolhe a entrada de imediato; fora disso, escrever as primeiras letras de um rótulo leva a essa entrada, espaços incluídos («report 2»). Uma lista longa (quinhentas entradas e mais) desliza e mantém-se fluida. Lido da direita para a esquerda, o menu alinha-se à direita e as cascatas abrem-se para a esquerda.

Cascatas, secções e marcas #

Uma entrada designa-se pelo seu endereço: a sua chave sozinha no primeiro nível (copy), as chaves dos pais e depois a sua, unidas por /, numa cascata (export/pdf). O pai tem de existir; uma chave não contém / nem | e não começa por __. ue_item_selected devolve esse mesmo endereço: duas cascatas podem dar o mesmo nome às suas entradas.

Um separador (of_add_separator) e um cabeçalho de secção (of_add_header) colocam-se no fim do menu (endereço vazio) ou da cascata de uma entrada. Nenhum dos dois é uma entrada: nunca escolhidos, nunca contados. Um separador nunca aparece no início, no fim nem duplicado; um cabeçalho cujas entradas estão todas ocultas desaparece com elas.

Uma marca de verificação (ib_checked) diz que uma opção está ativa; uma entrada de opção (is_group) é uma escolha entre várias: as entradas de um mesmo grupo sob o mesmo pai excluem-se — marcar uma, pelo código ou pela escolha do utilizador, desmarca as outras, e uma bola redonda substitui a marca. O atalho (is_shortcut) aparece à direita da entrada; é só mostrado: a tecla pertence ao controlo de que o menu fala (um campo de introdução já copia com Ctrl+C), e um menu de contexto que a armasse tirá-la-ia a todos os controlos da janela.

Uma entrada marcada fora de um grupo não alterna sozinha quando o utilizador a escolhe — como em qualquer menu Windows: alterne-a em ue_item_selected. Um comando que destrói distingue-se pelo seu tom: is_tone = TONE_DANGER escreve o seu texto no vermelho do tema, legível em claro como em escuro. Para que uma opção alterne sozinha na escolha, ponha ib_auto_check = true: a marca muda antes de ue_item_selected. Uma opção é uma caixa de verificação — anunciada «não selecionada» por um leitor de ecrã — assim que foi marcada uma vez, ou assim que ib_checkable = true.

// A section of three exclusive entries in the View cascade
uo_menu.of_add_header(/*keys*/ "view", /*text*/ "Layout")
uo_menu.of_add_item(/*keys*/ "view/list", /*text*/ "&List")
uo_menu.of_add_item(/*keys*/ "view/details", /*text*/ "&Details")
uo_menu.of_item(/*keys*/ "view/list").is_group = "layout"
uo_menu.of_item(/*keys*/ "view/details").is_group = "layout"

// Checking one unchecks the other
uo_menu.of_item(/*keys*/ "view/details").ib_checked = true

// The shortcut SHOWN at the right of an entry
uo_menu.of_item(/*keys*/ "copy").is_shortcut = "Ctrl+C"

// A command that destroys : the red of the theme
uo_menu.of_item(/*keys*/ "delete").is_tone = uo_menu.TONE_DANGER

// event ue_item_selected : a check mark outside a group is switched by you
if as_keys = "wrap" then uo_menu.of_item(/*keys*/ as_keys).ib_checked = not uo_menu.of_item(/*keys*/ as_keys).ib_checked

// ... or by the entry itself, before ue_item_selected
uo_menu.of_item(/*keys*/ "grid").ib_auto_check = true

Reaproveitar um menu PowerBuilder #

Os seus menus emergentes já estão escritos? of_load_menu faz deles o menu do componente: passe o elemento sobre o qual chamava PopMenu. Cada elemento torna-se uma entrada, cascatas incluídas, com o seu texto (& incluído), o seu estado (Enabled, Checked, Visible), o seu Shortcut mostrado à direita — como o texto depois de uma tabulação — e a sua imagem de barra de ferramentas quando é um ficheiro presente. A sua chave é o ClassName do elemento, em cada nível. Na escolha, o script Clicked do elemento corre primeiro, depois ue_item_selected: o código escrito para PopMenu continua a servir. O menu fica vivo, como com PopMenu: cada abertura relê os elementos (Text, Enabled, Checked, Visible, Shortcut). O código que precedia PopMenu — m_paste.Enabled = (Clipboard() <> "") — e um Clicked que faz this.Checked = not this.Checked veem-se portanto na abertura seguinte; um elemento desativado ou oculto enquanto o menu está aberto não executa o seu Clicked (ue_dismissed(REASON_UNAVAILABLE)). Mantenha vivo o objeto menu enquanto o componente o usar. of_loaded_item devolve o elemento de uma entrada, para ler o que só o menu sabe (a sua MicroHelp) — teste-o com IsValid, uma entrada acrescentada à mão não tem. Um script Clicked que lê ParentWindow encontra aí uma janela válida — medido com o PowerBuilder 10, mesmo para um menu criado com create e nunca associado a uma janela —, mas é o PowerBuilder que a escolhe: nada garante que seja a janela que tem o menu de contexto. Para que um Clicked alcance uma janela precisa, dê-a ao menu numa variável de instância, definida antes de of_load_menu, ou passe esse código para ue_item_selected.

// Instance variable of the window : the menu lives as long as it does
// m_popup im_popup

// open event of the window : the items of m_popup.m_edit become the menu
im_popup = create m_popup
uo_menu.of_load_menu(/*menu*/ im_popup.m_edit)

// event rbuttondown of the DataWindow : the code before PopMenu stays,
// of_show replaces PopMenu - the items are read again as it opens
im_popup.m_edit.m_paste.Enabled = (Clipboard() <> "")
uo_menu.of_show()

// event ue_item_hover of uo_menu (ib_track_hover = true) : the MicroHelp
if IsValid(uo_menu.of_loaded_item(/*keys*/ as_keys)) then st_help.text = uo_menu.of_loaded_item(/*keys*/ as_keys).MicroHelp

// A Clicked that must reach ONE given window : the menu keeps that window
// itself. Instance variable of m_popup : window iw_owner
// Clicked of m_edit.m_copy
iw_owner.TriggerEvent("ue_copy")

// open event of the window, before of_load_menu
im_popup.iw_owner = this

Propriedades #

Métodos #

Eventos #

Propriedades de item #

Uma entrada não mostra nenhuma dica: o menu nativo não tem. O is_tooltip que o handle herda é guardado e relê-se, mas nunca é mostrado — para uma ajuda, ib_track_hover e ue_item_hover.

Exemplos #

Um menu conforme o que foi clicado #

// event ue_rclicked of the list : the menu is rebuilt for the current row
uo_menu.of_clear()
uo_menu.of_add_item(/*keys*/ "open", /*text*/ "&Open")
uo_menu.of_add_item(/*keys*/ "rename", /*text*/ "Re&name")
uo_menu.of_add_separator(/*keys*/ "")
uo_menu.of_add_item(/*keys*/ "delete", /*text*/ "&Delete")

// A row the user may not change : its commands are greyed
uo_menu.of_item(/*keys*/ "rename").ib_enabled = ib_can_edit
uo_menu.of_item(/*keys*/ "delete").ib_enabled = ib_can_edit

// At the cursor
uo_menu.of_show()

Um botão Mais #

// event ue_clicked of the button : the menu hangs from it
uo_menu.of_show_under(/*control*/ uo_more)

Uma ajuda na barra de estado #

// Once, after the menu is built : report the pointed entry
uo_menu.ib_track_hover = true

// event ue_item_hover of uo_menu : (string as_keys), "" when the menu closes
choose case as_keys
	case "delete"
		st_help.text = "Deletes the row, without the clipboard."
	case else
		st_help.text = ""
end choose

Boas práticas #

• Abra a partir do evento de clique direito do controlo (veja a tabela): só um premir escolhe uma entrada, o soltar que se segue não escolhe nada.
• Um menu curto. Os comandos frequentes em cima, os destrutivos em baixo, depois de um separador, com TONE_DANGER.
• Desative em vez de ocultar um comando que existe mas aqui não se aplica: o utilizador aprende onde está.
• Mostre os atalhos dos seus comandos: um menu de contexto é onde se aprendem.
• Uma cascata, não duas: para lá de um nível, uma caixa de diálogo lê-se melhor.

Versão de demonstração #

Sem chave, cada lista do menu — a raiz como cada cascata — mostra as suas seis primeiras entradas visíveis; os separadores e os cabeçalhos não contam. A última linha, desativada, diz quantas entradas não são mostradas — ou, sem corte, leva a menção «PBToolboxAI — DEMO». O modelo guarda tudo: uma chave mostra o menu inteiro na abertura seguinte.

O lançador não tem superfície: dos membros herdados abaixo, of_save_as_png, of_print e of_focus_webview não têm nada para capturar, imprimir nem receber. of_register_shortcut continua útil — um atalho da janela que abre o menu com of_show_under.

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