ribbon — u_pbt_ribbon #

← Referência dos componentes · Índice do guia

Faixa de opções ao estilo Office: separadores, grupos, doze tipos de controlos ricos, menu da aplicação, barra de acesso rápido, separadores contextuais com faixa e keytips.

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

Em resumo #

A regra de ouro: tudo passa pelo caminho #

A faixa de opções é uma hierarquia de quatro níveis: separador → grupo → controlo → entrada de menu. Não há qualquer identificador global a gerir: cada objeto é alcançado pelo caminho que a ele conduz e cada adição é feita sobre o handle do elemento pai.

// Ler ou comandar um controlo: o caminho completo, sempre
uo_ruban.of_tab("accueil").of_group("presse_papier").of_item("coller").ib_enabled = false

Daqui resultam duas consequências práticas e confortáveis: dois grupos diferentes podem utilizar o mesmo identificador de controlo sem colidirem, e os eventos entregam o caminho completo — sabe-se sempre de onde vem o clique.

Início rápido #

// event open da window
n_pbt_ribbon_tab   lnv_onglet
n_pbt_ribbon_group lnv_groupe

lnv_onglet = uo_ruban.of_add_tab("accueil", "Início")

lnv_groupe = lnv_onglet.of_add_group("presse_papier", "Área de transferência")
lnv_groupe.of_add_big_button("coller", "Colar", "mono:img\paste.svg")
lnv_groupe.of_add_button("couper", "Cortar", "mono:img\cut.svg")
lnv_groupe.of_add_button("copier", "Copiar", "mono:img\copy.svg")

uo_ruban.of_select_tab("accueil")

// event ue_clicked de uo_ruban: (string as_tab, string as_group, string as_id)
choose case as_id
    case "coller" ; of_coller()
    case "couper" ; of_couper()
    case "copier" ; of_copier()
end choose

Propriedades #

Constante — ACCENT_LIGHT (-1): deve ser passada como cor de um separador ou de um grupo contextual para que este siga o acento do tema, mais claro, em vez de uma cor fixa.

Propriedades de um separador — n_pbt_ribbon_tab #

Obtidas através de of_tab(id), podem ser alteradas em tempo real.

Propriedades de um grupo — n_pbt_ribbon_group #

Obtidas através de of_tab(id).of_group(id).

Constantes de modo do seletor de cor: COLORMODE_PALETTE (paleta de pastilhas, modo predefinido) e COLORMODE_OPEN (paleta completa com validação).

Propriedades de um controlo — n_pbt_ribbon_item #

Obtidas através de of_tab(id).of_group(id).of_item(id). Aplicam-se a todos os tipos de controlos; as propriedades sem pertinência para um dado tipo são simplesmente ignoradas.

Propriedades de uma entrada de menu — n_pbt_ribbon_menu_item #

Obtidas através de of_tab(id).of_group(id).of_item(id).of_menu_item(id).

Os doze tipos de controlos #

Todos são adicionados sobre o handle de um grupo e devolvem o handle do controlo criado — é assim possível encadear de seguida o preenchimento de um menu ou de uma lista.

of_add_colorpicker aceita um quinto argumento as_mode: COLORMODE_PALETTE (paleta de pastilhas) ou COLORMODE_OPEN (paleta completa com botões Validar e Cancelar).

Métodos #

Construir a faixa de opções #

Preencher os menus e as listas #

Todos estes métodos são invocados sobre o handle de um controlo.

Menu da aplicação e barra de acesso rápido #

Separadores contextuais #

Comuns #

Eventos #

Todos os eventos de controlo transportam o caminho completo: nunca é necessário um identificador único em toda a aplicação.

Exemplos #

Uma faixa de opções completa, do menu da aplicação aos grupos #

// event open: toda a construcao e agrupada numa unica representacao
n_pbt_ribbon_tab   lnv_onglet
n_pbt_ribbon_group lnv_groupe
n_pbt_ribbon_item  lnv_item

uo_ruban.of_set_redraw(false)
uo_ruban.is_app_button = "Ficheiro"

// Menu da aplicacao, com uma cascata sob "Guardar como"
uo_ruban.of_add_app_menu_item(/*id*/ "nouveau", /*rotulo*/ "Novo", /*imagem*/ "mono:img\new.svg")
uo_ruban.of_add_app_menu_item("ouvrir", "Abrir...", "mono:img\open.svg")
uo_ruban.of_add_app_menu_item("enr_sous", "Guardar como", "mono:img\saveas.svg")
uo_ruban.of_add_app_menu_item(/*pai*/ "enr_sous", /*id*/ "sous_pdf", "Documento PDF", "")
uo_ruban.of_add_app_menu_item(/*pai*/ "enr_sous", /*id*/ "sous_csv", "Ficheiro CSV", "")
uo_ruban.of_add_app_menu_separator("sep1")
uo_ruban.of_add_app_menu_item("quitter", "Sair", "mono:img\exit.svg")

// Barra de acesso rapido, por cima dos separadores
uo_ruban.of_add_qat(/*id*/ "qat_enr", /*imagem*/ "mono:img\save.svg", /*tooltip*/ "Guardar")
uo_ruban.of_add_qat("qat_annuler", "mono:img\undo.svg", "Anular")

// Separador Inicio
lnv_onglet = uo_ruban.of_add_tab("accueil", "Início")
lnv_onglet.is_keytip = "A"

lnv_groupe = lnv_onglet.of_add_group("presse_papier", "Área de transferência")
lnv_item = lnv_groupe.of_add_big_split("coller", "Colar", "mono:img\paste.svg")
lnv_item.of_add_menu_item("coller_texte", "Colar sem formatação", "")
lnv_item.of_add_menu_item("coller_lien", "Colar como ligação", "")
lnv_groupe.of_add_button("couper", "Cortar", "mono:img\cut.svg")
lnv_groupe.of_add_button("copier", "Copiar", "mono:img\copy.svg")
lnv_groupe.ib_launcher = true       // seta de opcoes no canto inferior direito

uo_ruban.of_set_redraw(true)
uo_ruban.of_select_tab("accueil")

Um encaminhamento de cliques único #

// event ue_clicked de uo_ruban: (string as_tab, string as_group, string as_id)
// O caminho completo chega com o evento: basta um unico encaminhamento,
// e dois grupos podem reutilizar o mesmo identificador sem se estorvarem.
choose case as_group + "/" + as_id
    case "presse_papier/couper" ; of_couper()
    case "presse_papier/copier" ; of_copier()
    case "presse_papier/coller" ; of_coller()
    case "police/gras"          ; of_basculer_gras()
end choose

Comandar o estado dos controlos consoante os direitos #

// Sempre pelo caminho: separador > grupo > controlo
uo_ruban.of_tab("accueil").of_group("presse_papier").of_item("coller").ib_enabled = of_presse_papier_non_vide()
uo_ruban.of_tab("accueil").of_group("outils").of_item("pinceau").ib_checked = true
uo_ruban.of_tab("admin").ib_visible = gb_administrateur

// Desativar a cinzento uma entrada DENTRO de um menu pendente (nivel 4)
uo_ruban.of_tab("accueil").of_group("presse_papier").of_item("coller") &
        .of_menu_item("coller_lien").ib_enabled = false

Separadores contextuais com faixa #

O princípio do Office: separadores que só aparecem quando a seleção o justifica, encimados por uma faixa intitulada e colorida.

// event open: prepara-se o grupo contextual, oculto por predefinicao
n_pbt_ribbon_ctx_group lnv_ctx
n_pbt_ribbon_tab       lnv_onglet
n_pbt_ribbon_group     lnv_groupe

// Sem cor, a faixa segue o acento do tema; RGB(...) para a impor
lnv_ctx = uo_ruban.of_add_contextual_group(/*id*/ "img", /*titulo*/ "Ferramentas de Imagem", &
                                           /*cor*/ RGB(224, 32, 96))
lnv_onglet = lnv_ctx.of_add_tab("format", "Formatar")
lnv_groupe = lnv_onglet.of_add_group("ajuster", "Ajustar")
lnv_groupe.of_add_big_button("rogner", "Recortar", "mono:img\crop.svg")
lnv_groupe.of_add_button("pivoter", "Rodar", "mono:img\rotate.svg")

// Ao selecionar uma imagem: revela-se o separador e ativa-se
uo_ruban.of_tab("format").ib_visible = true
uo_ruban.of_select_tab("format")

// Ao desselecionar: oculta-se, a faixa desaparece com ele
uo_ruban.of_tab("format").ib_visible = false

Caixa de lista, contador, seletor de cor e galeria #

n_pbt_ribbon_group lnv_groupe
n_pbt_ribbon_item  lnv_item

lnv_groupe = uo_ruban.of_tab("accueil").of_add_group("police", "Tipo de letra")

// Caixa de lista editavel: preenche-se pelo seu handle
lnv_item = lnv_groupe.of_add_combo(/*id*/ "nom_police", /*largura_px*/ 140, /*modificavel*/ true)
lnv_item.of_add_combo_item("Segoe UI")
lnv_item.of_add_combo_item("Arial")
lnv_item.of_add_combo_item("Calibri")
lnv_item.is_text = "Segoe UI"

// Contador numerico: minimo, maximo, incremento, valor inicial
lnv_groupe.of_add_spinner(/*id*/ "taille", /*largura_px*/ 70, /*minimo*/ 6, /*maximo*/ 96, &
                          /*incremento*/ 1, /*valor*/ 11)

// Seletor de cor no modo de paleta completa (com Validar / Cancelar)
lnv_groupe.of_add_colorpicker(/*id*/ "couleur", /*rotulo*/ "Cor", &
                              /*imagem*/ "mono:img\font-color.svg", &
                              /*cor*/ RGB(0, 0, 0), &
                              /*modo*/ lnv_groupe.COLORMODE_OPEN)

// Galeria de estilos: mosaicos ilustrados deslizantes
lnv_item = lnv_groupe.of_add_gallery(/*id*/ "styles", /*largura_px*/ 220, &
                                     /*largura_mosaico*/ 64, /*altura_mosaico*/ 48)
lnv_item.of_add_gallery_item("st_normal", "img\style-normal.png", "Normal")
lnv_item.of_add_gallery_item("st_titre",  "img\style-titre.png",  "Título")
lnv_item.of_add_gallery_item("st_note",   "img\style-note.png",   "Nota")
lnv_item.of_add_gallery_item("st_code",   "img\style-code.png",   "Código")

// A faixa recolhida mostra 4 miniaturas de cada vez; as restantes continuam
// acessiveis atraves das setas, ou na grelha expandida.
lnv_item.ii_visible_items = 4

lnv_item.of_select_item("st_normal")

// event ue_value_changed de uo_ruban: (string as_tab, string as_group, string as_id, double ad_value)
if as_id = "taille" then of_appliquer_taille(ad_value)

// event ue_color_changed de uo_ruban: (string as_tab, string as_group, string as_id, long al_color)
if as_id = "couleur" then of_appliquer_couleur(al_color)

Recusar a escolha de uma miniatura de galeria #

// A pergunta e colocada por PREDEFINICAO: nada a ativar. Esta linha faz o
// contrario, elimina-a quando arbitrar nao serve.
uo_ruban.ib_veto_gallery = false

// event ue_gallery_selection_changing de uo_ruban:
//   (string as_tab, string as_group, string as_id, string as_from_item, string as_item)
// Devolver FALSE conserva a miniatura atual (as_from_item).
if as_item = "st_code" and not of_document_supporte_code() then
    MessageBox("Estilo", "Este documento não pode assumir o estilo Código.")
    return false
end if
return true

O iniciador de caixa de diálogo #

// A pequena seta no canto inferior direito do grupo
uo_ruban.of_tab("accueil").of_group("police").ib_launcher = true

// event ue_launcher de uo_ruban: (string as_tab, string as_group)
// O caminho identifica o grupo: abre-se a window de opcoes correspondente.
choose case as_group
    case "police"        ; open(w_options_police)
    case "presse_papier" ; open(w_options_collage)
end choose

Keytips: conduzir a faixa de opções pelo teclado #

// Alt apresenta as letras; Alt seguido de A e depois C aciona "copier"
uo_ruban.of_tab("accueil").is_keytip = "A"
uo_ruban.of_tab("accueil").of_group("presse_papier").of_item("copier").is_keytip = "C"
uo_ruban.of_tab("accueil").of_group("presse_papier").of_item("couper").is_keytip = "X"

Premir Alt esteja o foco onde estiver na window entrega o comando à faixa de opções: esta recebe o foco de teclado e mostra as suas letras. Não tem nada a ligar — basta que esteja declarada pelo menos uma keytip. Esc, um segundo Alt ou a escolha de um comando devolvem o foco ao controlo que o utilizador tinha abandonado.

ue_keytips avisa-o de cada mudança de estado e indica-lhe o nível atual:

// event ue_keytips de uo_ruban: (boolean ab_on, integer ai_level)
// O teclado conduz a faixa de opcoes: apagar a ajuda da barra de estado, que
// fala do rato, e repo-la quando as letras desaparecerem.
if ab_on then
    uo_statut.of_item("main").is_text = "Escreva uma letra (nivel " + String(ai_level) + ")"
else
    uo_statut.of_item("main").is_text = ""
end if

Tooltips enriquecidos num controlo #

n_pbt_ribbon_item lnv_item

lnv_item = uo_ruban.of_tab("accueil").of_group("presse_papier").of_item("coller")
lnv_item.is_super_tooltip_title = "Colar (Ctrl+V)"
lnv_item.is_super_tooltip_text  = "Insere o conteúdo da área de transferência." &
                                + "[br][br][size-=15]Utilize a seta para colar sem formatação.[/size-=15]"
lnv_item.is_super_tooltip_image = "img\paste.png"

Estas quatro propriedades são exatamente as mesmas de qualquer outro item da biblioteca. Para um tooltip de uma só linha basta is_tooltip.

Altura automática #

A faixa de opções dimensiona-se sozinha: não há nada para ativar. Avisa-o sempre que a altura muda (recolhimento, separador contextual, mudança de tema) para que possa reposicionar o que está por baixo.

// event ue_auto_height de uo_ruban: (long al_height)
// A faixa de opcoes ja se redimensionou: reposiciona-se o que esta por baixo.
uo_contenu.y      = uo_ruban.y + uo_ruban.height
uo_contenu.height = this.height - uo_contenu.y

Recolher a faixa de opções para ganhar espaço #

uo_ruban.ib_minimized = true

// event ue_minimized de uo_ruban: (boolean ab_minimized)
// Memoriza-se a preferencia do utilizador para a proxima abertura.
of_enregistrer_preference("ruban_replie", ab_minimized)

Recomeçar com uma faixa de opções vazia #

// of_reset esvazia separadores, grupos, controlos, barra de acesso rapido e menu
uo_ruban.of_reset()
uo_ruban.of_add_tab("accueil", "Início")

A partir de um menu PowerBuilder existente #

Uma aplicação PowerBuilder já descreveu os seus comandos uma vez: no seu menu. Etiquetas, atalhos, imagens, separadores, submenus, dicas — está tudo lá. n_pbt_menu2ribbon relê esse menu por RTTI e escreve o PowerScript que constrói o friso correspondente.

// Uma so vez, a mao : o gerador ESCREVE codigo, nao corre em producao.
// Cole o resultado no open da sua janela.
n_pbt_menu2ribbon lnv_gen
string ls_code

lnv_gen = create n_pbt_menu2ribbon
ls_code = lnv_gen.of_generate(/*menu*/ m_principal, /*variavel*/ "uo_ruban")
destroy lnv_gen

ClipBoard(ls_code)

A conversão é determinista: sem IA, sem chamada de rede, nada que saia da máquina. E os identificadores gerados mantêm o caminho do menu (m_principal.m_fichier.m_ouvrir), pelo que o choose case das suas ações existentes funciona tal como está a partir de ue_clicked.

O código produzido é um ponto de partida para rever, não um entregável: um menu é uma lista, um friso é uma disposição. Agrupe, escolha os seus botões grandes, retire o que não merece estar sempre à vista. O exemplo 9 da página do friso na aplicação de demonstração mostra um resultado completo.

Boas práticas #

• Enquadre toda a construção com of_set_redraw(false) / of_set_redraw(true): uma faixa de opções completa é então desenhada de uma só vez, sem cintilação.
• Conserve os handles devolvidos (n_pbt_ribbon_tab, n_pbt_ribbon_group, n_pbt_ribbon_item) em variáveis locais durante a construção: o código mantém-se curto e legível. Para comandar um controlo mais tarde, basta voltar a passar pelo caminho.
• Invoque of_preload_icons no arranque: sem isso, a primeira apresentação de um separador nunca aberto revela um breve atraso antes dos seus ícones.
• Um identificador só precisa de ser único dentro do seu grupo. Aproveite para nomear os controlos de forma simples (copier, coller) em vez de recorrer a prefixos.
• Reserve os separadores contextuais para os comandos que não têm qualquer sentido fora de contexto: um separador permanente desativado a cinzento é mais tranquilizador do que um separador que aparece e desaparece.
• A pergunta é colocada por predefinição: um ue_gallery_selection_changing deixado vazio autoriza sempre a escolha, não tem nada a fazer. Desative-a com ib_veto_gallery = false se arbitrar não lhe serve, porque cada pergunta custa uma ida e volta ao PowerBuilder.
• Um único iniciador de caixa de diálogo por grupo, e apenas se o grupo tiver realmente opções avançadas a oferecer.
• Para reconstruir uma faixa de opções inteira, prefira of_clear() (ou of_reset()) a uma série de of_remove_tab: sem isso, a reutilização de um identificador de separador falha.
• Para uma barra de comandos mais leve, sem separadores nem grupos, consulte toolbar; para uma navegação lateral, listbar.

← Referência dos componentes · Índice do guia