# webbrowser — `u_pbt_webbrowser` #

← Referência dos componentes · Índice do guia

> Navegador web integrado na janela: apresentação de uma página, barra de endereço, histórico Anterior / Seguinte, menu de contexto de navegação.

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

## Em resumo #

Userobject | `u_pbt_webbrowser`
Classe de items | — (componente sem items)
Serve para | Apresentar uma página web, um portal interno, documentação em linha ou conteúdo HTML gerado, sem sair da aplicação
Dois modos de apresentação | integrado (predefinição) ou página inteira, consoante a tolerância do site visitado

## Início rápido #

    // event open da janela
    uo_navigateur.ib_address_bar = true    // barra de endereco + botoes de navegacao
    uo_navigateur.is_address = "https://pt.wikipedia.org/wiki/PowerBuilder"

Atribuir `is_address` é o ato de navegação: cada atribuição abre a página pedida. Um endereço sem protocolo (`"exemplo.com"`) recebe automaticamente `https://`.

## Propriedades #

Propriedade | Tipo | Predefinição | Função
--- | --- | --- | ---
`is_address` | string | `""` | Endereço apresentado. Atribuir esta propriedade aciona a navegação. Ao relê-la obtém a página realmente apresentada: se o utilizador seguir uma ligação, ela também a segue (`ue_load_completed` avisa). Todos os esquemas são aceites, incluindo `data:` e `file:`
`ib_address_bar` | boolean | `false` | Apresenta a barra de endereço integrada: campo URL, botões Anterior / Seguinte / Recarregar
`ib_context_menu` | boolean | `false` | Ativa o menu de contexto de navegação com o clique direito: Anterior, Seguinte, Recarregar
`is_theme_style` | string | `fluent` | Estilo visual do componente (constantes `THEME_STYLE_*`)
`is_theme_mode` | string | `light` | Variante clara ou escura (constantes `THEME_MODE_*`)
`il_theme_accent` | long | `-1` | Cor de destaque deste componente (`-1` = destaque do tema)

## Métodos #

Método | Função
--- | ---
`of_refresh ( )` | Recarrega a página atual
`of_go_back ( )` | Regressa à página anterior
`of_go_forward ( )` | Avança para a página seguinte
`of_can_go_back ( )` → boolean | `true` se existir uma página anterior — para ativar ou inativar o botão Anterior
`of_can_go_forward ( )` → boolean | `true` se existir uma página seguinte
`of_stop ( )` | Interrompe o carregamento em curso
`of_execute_javascript (string as_script)` | Executa um script na página apresentada e devolve o respetivo valor sob a forma de cadeia (JSON: um texto regressa entre aspas, um número não). Uma só condição, e é estrutural: a página tem de ter terminado o carregamento, por isso chame-a a partir de `ue_load_completed`, nunca logo após definir `is_address`. Devolve uma cadeia vazia se o script falhar ou se não houver página
`of_reset ( )` | Repõe o componente no estado inicial: página esvaziada, histórico de navegação apagado, barra de endereço oculta, menu de contexto desativado, regresso ao modo integrado
`of_save_as_png (string)` · `of_save_as_jpg (string)` | Exporta a representação como imagem

## Eventos #

Evento | Acionado quando
--- | ---
`ue_load_completed (string as_url)` | Uma página terminou de carregar; `as_url` é o endereço efetivamente apresentado
`ue_ready ( )` | O componente terminou o carregamento; tudo o que foi enviado antes foi reproduzido
`ue_runtime_missing ( )` | O runtime WebView2 está ausente: o componente permanece vazio
`ue_bg_color (long al_color)` | O componente calculou a cor de fundo do respetivo tema; o userobject já a adotou (`backcolor`)

## Navegar #

### A barra de endereço integrada #

É a solução mais rápida: uma propriedade e o utilizador dispõe de um campo URL e dos botões Anterior / Seguinte / Recarregar, com o tema do resto da aplicação.

    uo_navigateur.ib_address_bar = true
    uo_navigateur.is_address = "https://pt.wikipedia.org/wiki/PowerBuilder"

Os botões ficam inativos automaticamente quando não há para onde ir.

### Botões próprios #

Se preferir comandar a navegação a partir de uma barra de ferramentas própria, deve ocultar-se a barra integrada e utilizar os métodos:

    // Botoes Anterior / Seguinte da sua janela
    uo_navigateur.of_go_back()
    uo_navigateur.of_go_forward()

    // event ue_load_completed de uo_navigateur : (string as_url)
    // Atualizar o estado dos seus botoes apos cada pagina
    uo_barre.of_bar("main").of_item("precedent").ib_enabled = uo_navigateur.of_can_go_back()
    uo_barre.of_bar("main").of_item("suivant").ib_enabled   = uo_navigateur.of_can_go_forward()

    // E refletir o endereco real (incluindo redirecionamentos)
    sle_url.text = as_url

### O menu de contexto de navegação #

`ib_context_menu` acrescenta ao clique direito um pequeno menu Anterior / Seguinte / Recarregar, com tema e desenhado pela aplicação. Partilha exatamente o mesmo histórico que a barra de endereço: ambos permanecem, por isso, sempre coerentes.

    uo_navigateur.ib_context_menu = true

### Parar um carregamento #

    // Botao Parar : interrompe uma pagina que demora
    uo_navigateur.of_stop()

## Sites que recusam a apresentação integrada #

Alguns sites — Google, a maioria dos bancos, muitas aplicações SaaS — enviam cabeçalhos de segurança que proíbem a sua apresentação dentro de outra página. O componente não é afetado: nunca apresenta um site numa moldura. A página é aberta como documento principal, exatamente como faz o seu próprio navegador, e esses cabeçalhos deixam de se aplicar.

Não há, portanto, nada a definir nem qualquer caso particular a tratar no seu código.

    // Um site que recusa ser integrado numa pagina : nada de especial a fazer
    uo_navigateur.ib_address_bar = true
    uo_navigateur.is_address = "https://www.google.com"

Em contrapartida, a página ocupa toda a superfície do componente sob a barra de endereço: aquilo que desenhasse por cima (faixas, sobreposições com tema) não é visível durante a navegação.

## Conteúdo HTML sem rede #

Qualquer endereço é aceite, incluindo uma página HTML fornecida diretamente. É prático para uma pré-visualização de correio, um ticket, uma fatura ou um relatório gerado pela aplicação, sem qualquer chamada de rede nem ficheiro temporário:

    string ls_html

    ls_html = "<html><head><meta charset='utf-8'></head><body>" &
            + "<h1>Resumo da encomenda</h1>" &
            + "<p>Obrigado pela sua confiança.</p>" &
            + "</body></html>"

    uo_navigateur.is_address = "data:text/html," + ls_html

Um ficheiro local abre-se da mesma forma com `file:///C:/temp/rapport.html`.

## Recomeçar do zero #

`of_reset()` não se limita a esvaziar a página: apaga também o histórico de navegação. Assim, um utilizador não pode regressar, através do botão Anterior, a uma página consultada pelo utilizador anterior ou noutro dossiê.

    // Mudanca de dossie : recomeca-se com um navegador virgem, sem historico
    uo_navigateur.of_reset()

    uo_navigateur.ib_address_bar = true
    uo_navigateur.is_address = ls_url_du_dossier

É o reflexo a ter sempre que um mesmo componente serve para apresentar conteúdos de contextos diferentes.

## Exemplo completo #

    // event open da janela : pagina inicial do portal interno
    uo_navigateur.of_reset()                  // recomecar limpo (incluindo o historico)

    uo_navigateur.ib_address_bar  = true      // campo URL + Anterior / Seguinte / Recarregar
    uo_navigateur.ib_context_menu = true      // mesma navegacao com o clique direito
    uo_navigateur.is_address = "https://intranet.empresa.pt/inicio"

    // event ue_load_completed de uo_navigateur : (string as_url)
    uo_statut.of_item("main").is_text = "Página carregada: " + as_url

## Boas práticas #

- Atribuir `is_address`, sem chamar qualquer método de navegação: é a propriedade que aciona a abertura da página.
- Deve ativar-se `ib_address_bar` sempre que o utilizador possa navegar livremente; o comando através de botões próprios fica reservado aos percursos condicionados.
- Convém confiar em `of_can_go_back()` / `of_can_go_forward()` para o estado dos botões, em vez de contar as páginas manualmente: os redirecionamentos falseariam essa contagem.
- Nada a prever para os sites que recusam a apresentação integrada: a página é sempre aberta como documento principal, esses cabeçalhos não se aplicam.
- Deve chamar-se `of_reset()` na mudança de contexto: é a única forma de garantir que nenhuma página anterior fica acessível através do botão Anterior.
- O componente necessita do runtime web instalado no posto: o event `ue_runtime_missing` deve ser tratado como em qualquer outro componente (Instalação).

← Referência dos componentes · Índice do guia