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

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