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 #

Início rápido #

// event open da janela
uo_browser.ib_address_bar = true    // barra de endereco + botoes de navegacao
uo_browser.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://. Um caminho de disco (C:\pasta\pagina.html, \\servidor\partilha\pagina.html) torna-se um endereço file:///. Palavras que não são um endereço ("fatura 2026") vão para o motor de pesquisa de is_search_url; sem motor, são recusadas e ue_error indica-o. Um nome de servidor de uma só palavra seguido de /, ? ou # (office/, intranet/inicio) é um endereço, tal como um endereço IPv6 entre parênteses retos ([::1]/x); a palavra sozinha (intranet) continua a ser texto livre. Um servidor sem HTTPS escreve-se com http:// explícito.

Propriedades #

Métodos #

Eventos #

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.

// A barra de enderecos, depois a pagina a abrir
uo_browser.ib_address_bar = true
uo_browser.is_address = "https://pt.wikipedia.org/wiki/PowerBuilder"

Os botões ficam inativos automaticamente quando não há para onde ir. No campo de endereço, F5 (ou Ctrl+R) recarrega, Alt+← / Alt+→ recuam e avançam (invertidos na escrita da direita para a esquerda), Esc repõe o endereço atual depois de uma escrita abandonada, e o primeiro clique seleciona todo o endereço.

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_browser.of_go_back()
uo_browser.of_go_forward()

// event ue_load_completed de uo_browser : (string as_url)
// Atualizar o estado dos seus botoes apos cada pagina
uo_toolbar.of_item(/*keys*/ "main/back").ib_enabled = uo_browser.of_can_go_back()
uo_toolbar.of_item(/*keys*/ "main/forward").ib_enabled   = uo_browser.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. Segue o que está sob o rato: Copiar sobre um texto selecionado, Abrir link e Copiar endereço do link sobre um link, Copiar imagem sobre uma imagem. Aberto pelo teclado (Shift+F10, tecla Menu), aparece sobre o elemento. Partilha exatamente o mesmo histórico que a barra de endereço: ambos permanecem, por isso, sempre coerentes.

// A small menu on a right click : back, forward, refresh
uo_browser.ib_context_menu = true

Parar um carregamento #

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

Palavras em vez de um endereço #

Por omissão, um texto que não é um endereço é recusado (ue_error), sem reter nada: o endereço seguinte carrega normalmente. Para o transformar numa pesquisa, escolha o motor:

// Words typed in the address bar go to this engine (%s = the text)
uo_browser.is_search_url = "https://www.bing.com/search?q=%s"
uo_browser.is_address = "PowerBuilder WebView2"

Novas janelas e transferências #

Uma ligação «abrir num novo separador» ou uma janela de início de sessão aberta após um clique aparece na vista, e ue_new_window indica-o. Uma transferência continua como no Edge, e ue_download_starting dá-lhe o endereço e o ficheiro. Ambos se tornam uma pergunta quando o pede:

// Ask before each download
uo_browser.ib_veto_downloads = true

// ue_download_starting event of uo_browser : (string as_url, string as_path)
// Only PDF files may be downloaded
return Lower(Right(as_path, 4)) = ".pdf"

Ficar nos seus próprios servidores #

ue_navigating é lançado sempre que o site passa para outra página — um link, um formulário, um script —, nunca para um endereço definido pelo seu código. Com ib_veto_navigation é uma pergunta: devolver false mantém a página atual. Uma página autorizada é reaberta no endereço pedido pelo site; um formulário enviado por POST perde os seus dados.

// Ask before the site leaves for another page
uo_browser.ib_veto_navigation = true

// ue_navigating event of uo_browser : (string as_url)
// Only the company servers may be opened
return Pos(Lower(as_url), "://intranet.example.com/") > 0

Câmara, microfone, localização #

Quando um site pede a câmara, o microfone, a localização, as notificações ou a leitura da área de transferência, é ue_permission_requested que decide, e a resposta por omissão é não: um site não liga uma câmara através de um aviso que o utilizador não compreende. É a única pergunta da biblioteca em que o silêncio vale recusa. Nada é memorizado: a pergunta volta a cada pedido.

// ue_permission_requested event of uo_browser : (string as_url, string as_kind)
// The video-call page of the company may use the camera and the microphone
if Pos(Lower(as_url), "://visio.example.com/") = 0 then return false
return as_kind = uo_browser.PERMISSION_CAMERA or as_kind = uo_browser.PERMISSION_MICROPHONE

Valores de as_kind: PERMISSION_CAMERA, PERMISSION_MICROPHONE, PERMISSION_GEOLOCATION, PERMISSION_NOTIFICATIONS, PERMISSION_CLIPBOARD, PERMISSION_SENSORS, PERMISSION_DOWNLOADS (várias transferências seguidas), PERMISSION_FILES, PERMISSION_AUTOPLAY, PERMISSION_FONTS, PERMISSION_MIDI, PERMISSION_WINDOWS, PERMISSION_UNKNOWN.

Porque é que uma página não carregou #

al_status de ue_load_failed compara-se com as constantes LOADSTATUS_* do componente:

// ue_load_failed event of uo_browser : (string as_url, long al_status)
if al_status = uo_browser.LOADSTATUS_HOST_NOT_RESOLVED then
	st_message.text = "Unknown address : " + as_url
end if

Executar um script na página #

of_execute_javascript lê ou altera a página apresentada (o título, um campo, um contador). Não é limitado pela licença, mesmo numa página about:blank ou data:: executar um script na página é o trabalho de um navegador, e o componente é gratuito.

// ue_load_completed event of uo_browser : (string as_url)
// The page title, as JSON : "PowerBuilder - Wikipedia" (quotes included)
sle_title.text = uo_browser.of_execute_javascript(/*script*/ "document.title")

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_browser.ib_address_bar = true
uo_browser.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 #

of_show_html apresenta uma página HTML construída pela aplicação: a pré-visualização de uma carta, de um ticket, de uma fatura ou de um relatório, sem qualquer chamada de rede nem ficheiro temporário. A página é codificada por si: uma cor #c00, uma âncora, um % ou um acento aparecem tal como escritos (no máximo 2 MB).

// Local variables
string ls_html

// An order summary built by the application : the colour and the "%" come out as written
ls_html = "<html><body>" &
        + "<h1 style='color:#1f6feb'>Order #4152</h1>" &
        + "<p>Discount : 10%</p>" &
        + "</body></html>"
uo_browser.of_show_html(/*html*/ ls_html)

Definido diretamente em is_address, um endereço data:text/html, não é codificado: um # corta ali a página (tudo o que se segue passa por uma âncora) e um % baralha-a. Prefira of_show_html, ou codifique por si (# → %23, % → %25).

Um ficheiro local abre-se da mesma forma com file:///C:/temp/relatorio.html, ou simplesmente com o seu caminho C:\temp\relatorio.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ê. Não toca no que os sites guardaram: cookies, sessões iniciadas, armazenamento local, permissões. Num posto partilhado, o utilizador seguinte chegaria com a sessão do anterior — é of_clear_browsing_data() que a apaga. Os sites vivem num perfil de navegação próprio, separado dos componentes da aplicação.

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

// Depois o dossie, com a sua barra de enderecos
uo_browser.ib_address_bar = true
uo_browser.is_address = ls_folder_url

// The user of the workstation changes : no page, no history, no signed-in session left
uo_browser.of_reset()
uo_browser.of_clear_browsing_data()

Para que nada seja alguma vez escrito no disco, defina ib_private = true antes do primeiro endereço: cookies e armazenamento desaparecem com a vista.

É 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_browser.of_reset()                  // recomecar limpo (incluindo o historico)

// As ferramentas de navegacao, depois a pagina inicial
uo_browser.ib_address_bar  = true      // campo URL + Anterior / Seguinte / Recarregar
uo_browser.ib_context_menu = true      // mesma navegacao com o clique direito
uo_browser.is_address = "https://intranet.empresa.pt/inicio"

// event ue_load_completed de uo_browser : (string as_url)
uo_status.of_panel(/*key*/ "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. Quando o utilizador do posto muda, acrescente of_clear_browsing_data(): sem ele, os cookies e sessões dos sites mantêm-se.
• O componente necessita do runtime web instalado no posto: o event ue_runtime_missing deve ser tratado como em qualquer outro componente (Instalação).
• Um site pode tocar som sem um gesto do utilizador: a reprodução automática com som é permitida em todo o ambiente WebView2 da aplicação (o leitor de vídeo e o leitor de sons precisam dela, uma página oculta não tem gestos). Uma página que lança um vídeo com som ao abrir vai tocá-lo; se isso incomodar, abra endereços que conhece.

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.

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