webbrowser — u_pbt_webbrowser #

← Référence des composants · Sommaire du guide

Navigateur web intégré à votre fenêtre : affichage d'une page, barre d'adresse, historique Précédent / Suivant, menu contextuel de navigation.

▶ Le voir en vrai — Application de démonstration, tuile Web browser : l'aperçu, le code qui le produit et cette page, côte à côte.

En bref #

Démarrage rapide #

// event open de la fenetre
uo_browser.ib_address_bar = true    // barre d'adresse + boutons de navigation
uo_browser.is_address = "https://fr.wikipedia.org/wiki/PowerBuilder"

Poser is_address est l'acte de navigation : chaque affectation ouvre la page demandée. Une adresse sans protocole ("exemple.com") reçoit automatiquement https://. Un chemin disque (C:\dossier\page.html, \\serveur\partage\page.html) devient une adresse file:///. Des mots qui ne sont pas une adresse ("facture 2026") partent vers le moteur de recherche de is_search_url ; sans moteur, ils sont refusés et ue_error le dit. Un nom de serveur d'un seul mot suivi de /, ? ou # (office/, intranet/home) est une adresse, comme une adresse IPv6 entre crochets ([::1]/x) ; le mot seul (intranet) reste un texte libre. Un serveur sans HTTPS s'écrit avec http:// explicite.

Propriétés #

Méthodes #

Événements #

Naviguer #

La barre d'adresse intégrée #

C'est la solution la plus rapide : une propriété, et l'utilisateur dispose d'un champ URL et des boutons Précédent / Suivant / Recharger, thémés comme le reste de l'application.

// La barre d'adresse, puis la page a ouvrir
uo_browser.ib_address_bar = true
uo_browser.is_address = "https://fr.wikipedia.org/wiki/PowerBuilder"

Les boutons se grisent tout seuls quand il n'y a nulle part où aller. Dans le champ d'adresse, F5 (ou Ctrl+R) recharge, Alt+← / Alt+→ reviennent et avancent (inversés en écriture de droite à gauche), Échap rend l'adresse courante après une frappe abandonnée, et le premier clic sélectionne toute l'adresse.

Vos propres boutons #

Si vous préférez piloter la navigation depuis votre propre barre d'outils, masquez la barre intégrée et utilisez les méthodes :

// Boutons Precedent / Suivant de votre fenetre
uo_browser.of_go_back()
uo_browser.of_go_forward()

// event ue_load_completed de uo_browser : (string as_url)
// Mettre a jour l'etat de vos boutons apres chaque page
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()

// Et refleter l'adresse reelle (redirections comprises)
sle_url.text = as_url

Le menu contextuel de navigation #

ib_context_menu ajoute au clic droit un petit menu Précédent / Suivant / Recharger, thémé et rendu par l'application. Il suit ce qui est sous la souris : Copier sur un texte sélectionné, Ouvrir le lien et Copier l'adresse du lien sur un lien, Copier l'image sur une image. Ouvert au clavier (Maj+F10, touche Menu), il se pose sur l'élément. Il partage exactement le même historique que la barre d'adresse : les deux restent donc toujours cohérents.

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

Arrêter un chargement #

// Bouton Stop : interrompt une page qui tarde
uo_browser.of_stop()

Des mots plutôt qu'une adresse #

Par défaut, un texte qui n'est pas une adresse est refusé (ue_error), sans rien bloquer : l'adresse suivante se charge normalement. Pour en faire une recherche, choisissez le moteur :

// 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"

Nouvelles fenêtres et téléchargements #

Un lien « ouvrir dans un nouvel onglet » ou une fenêtre de connexion ouverte après un clic s'affiche dans la vue, et ue_new_window vous le dit. Un téléchargement continue comme dans Edge, et ue_download_starting vous donne l'adresse et le fichier. Les deux se changent en question quand vous le demandez :

// 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"

Rester sur ses serveurs #

ue_navigating est levé chaque fois que le site part vers une autre page — un lien, un formulaire, un script —, jamais pour une adresse posée par votre code. Avec ib_veto_navigation, c'est une question : renvoyer false y laisse la page courante. Une page autorisée est rouverte à l'adresse demandée par le site ; un formulaire envoyé en POST y perd ses données.

// 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

Caméra, micro, position #

Quand un site demande la caméra, le micro, la position, les notifications ou la lecture du presse-papiers, c'est ue_permission_requested qui décide, et la réponse par défaut est non : un site n'allume pas une caméra par une invite que l'utilisateur ne comprend pas. C'est la seule question de la bibliothèque où le silence vaut refus. Rien n'est retenu : la question revient à chaque demande.

// 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

Valeurs de as_kind : PERMISSION_CAMERA, PERMISSION_MICROPHONE, PERMISSION_GEOLOCATION, PERMISSION_NOTIFICATIONS, PERMISSION_CLIPBOARD, PERMISSION_SENSORS, PERMISSION_DOWNLOADS (plusieurs téléchargements d'affilée), PERMISSION_FILES, PERMISSION_AUTOPLAY, PERMISSION_FONTS, PERMISSION_MIDI, PERMISSION_WINDOWS, PERMISSION_UNKNOWN.

Pourquoi une page n'a pas chargé #

al_status de ue_load_failed se compare aux constantes LOADSTATUS_* du composant :

// 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

Exécuter un script dans la page #

of_execute_javascript lit ou modifie la page affichée (son titre, un champ, un compteur). Il n'est pas bridé par la licence, y compris sur une page about:blank ou data: : exécuter un script dans la page est le métier d'un navigateur, et le composant est gratuit.

// 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 qui refusent l'affichage intégré #

Certains sites — Google, la plupart des banques, beaucoup d'applications SaaS — envoient des en-têtes de sécurité qui interdisent leur affichage à l'intérieur d'une autre page. Le composant n'est pas concerné : il n'affiche jamais un site dans un cadre. La page est ouverte comme document principal, exactement comme le fait votre navigateur, et ces en-têtes ne s'appliquent alors plus.

Il n'y a donc rien à régler, et aucun cas particulier à prévoir dans votre code.

// Un site qui refuse d'etre integre dans une page : rien de special a faire
uo_browser.ib_address_bar = true
uo_browser.is_address = "https://www.google.com"

En contrepartie, la page occupe toute la surface du composant sous la barre d'adresse : les habillages posés par-dessus (bandeaux, superpositions thémées) ne sont pas visibles pendant la navigation.

Contenu HTML sans réseau #

of_show_html affiche une page HTML construite par votre application : un aperçu de courrier, un ticket, une facture ou un rapport, sans aucun appel réseau ni fichier temporaire. La page est encodée pour vous : une couleur #c00, une ancre, un % ou un accent s'affichent tels qu'écrits (2 Mo au plus).

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

Posée directement dans is_address, une adresse data:text/html, n'est pas encodée : un # y coupe la page (tout ce qui suit passe pour une ancre) et un % la brouille. Préférez of_show_html, ou encodez vous-même (# → %23, % → %25).

Un fichier local s'ouvre de la même façon avec file:///C:/temp/rapport.html, ou simplement son chemin C:\temp\rapport.html.

Repartir de zéro #

of_reset() ne se contente pas de vider la page : il efface aussi l'historique de navigation. Un utilisateur ne peut donc pas revenir, par le bouton Précédent, sur une page consultée par l'utilisateur précédent ou dans un autre dossier. Il ne touche pas à ce que les sites ont retenu : cookies, sessions ouvertes, stockage local, permissions. Sur un poste partagé, l'utilisateur suivant arriverait connecté sous le compte du précédent — c'est of_clear_browsing_data() qui l'efface. Les sites vivent dans un profil de navigation à part, séparé des composants de l'application.

// Changement de dossier : on repart d'un navigateur vierge, sans historique
uo_browser.of_reset()

// Puis le dossier, avec sa barre d'adresse
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()

Pour que rien ne soit jamais écrit sur le disque, posez ib_private = true avant la première adresse : cookies et stockage disparaissent avec la vue.

C'est le réflexe à avoir chaque fois qu'un même composant sert à afficher des contenus de contextes différents.

Exemple complet #

// event open de la fenetre : page d'accueil du portail interne
uo_browser.of_reset()                  // repartir propre (historique compris)

// Les outils de navigation, puis la page d'accueil
uo_browser.ib_address_bar  = true      // champ URL + Precedent / Suivant / Recharger
uo_browser.ib_context_menu = true      // meme navigation au clic droit
uo_browser.is_address = "https://intranet.example.com/home"

// event ue_load_completed de uo_browser : (string as_url)
uo_status.of_panel(/*key*/ "main").is_text = "Page chargee : " + as_url

Bonnes pratiques #

• Affectez is_address, n'appelez pas de méthode de navigation : c'est la propriété qui déclenche l'ouverture de la page.
• Activez ib_address_bar dès que l'utilisateur peut naviguer librement ; réservez le pilotage par vos propres boutons aux parcours contraints.
• Fiez-vous à of_can_go_back() / of_can_go_forward() pour l'état de vos boutons plutôt que de compter les pages vous-même : les redirections fausseraient votre compte.
• Rien à prévoir pour les sites qui refusent l'affichage intégré : la page est toujours ouverte comme document principal, ces en-têtes ne s'appliquent pas.
• Appelez of_reset() en changeant de contexte : c'est le seul moyen de garantir qu'aucune page précédente n'est accessible par le bouton Précédent. Quand l'utilisateur du poste change, ajoutez of_clear_browsing_data() : sans lui, cookies et sessions des sites restent.
• Le composant a besoin du runtime web installé sur le poste : traitez ue_runtime_missing comme pour tout autre composant (Installation).
• Un site peut jouer du son sans geste de l'utilisateur : la lecture automatique sonore est permise dans tout l'environnement WebView2 de l'application (le lecteur vidéo et le lecteur de sons en ont besoin, une page cachée n'a pas de geste). Une page qui lance une vidéo sonore à l'ouverture la jouera ; si c'est gênant, ouvrez des adresses que vous connaissez.

Hérité du socle commun #

Ces membres existent sur tous les composants visuels — ils ne sont pas propres à celui-ci. Ils sont détaillés une seule fois, dans les chapitres transverses ; cette table dit seulement où les lire.

Deux aides ne sont pas héritées : of_icon et of_escape_markup vivent sur n_pbt_utils. Déclarez-en une — n_pbt_utils lnv_utils, rien à créer — et appelez-les dessus.

← Référence des composants · Sommaire du guide