thyphoon/PBMap
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
9387a58080a22009e2bd2c66f4cc1225eb19cc8d
PBMap/PBMap_doc_fr.md
Thyphoon 9387a58080 Big Update (Bugs / Cluster
2026-01-12 18:31:37 +01:00

11 KiB
Raw Blame History

PBMap - Documentation FR (usage simple et complet)

Ce document explique comment utiliser pbmap/PBMap.pb facilement, avec un demarrage rapide, des exemples et le detail de chaque procedure publique.

Demarrage rapide

Objectif: afficher une carte, ajouter un marqueur et deplacer la vue.

IncludeFile "pbmap/PBMap.pb"

EnableExplicit
InitNetwork()

UseModule PBMap

Enumeration
  #Win
  #Map
EndEnumeration

If OpenWindow(#Win, 100, 100, 900, 600, "PBMap demo", #PB_Window_SystemMenu)
  #Map = MapGadget(#PB_Any, 0, 0, 900, 600, 1, #Win)

  ; Options utiles
  SetOption(#Map, "ShowScale", "1")
  SetOption(#Map, "ShowZoom", "1")
  SetOption(#Map, "ShowMarkersLegend", "1")

  ; Position de depart
  SetLocation(#Map, 48.8566, 2.3522, 12)

  ; Ajout d'un marqueur
  AddMarker(#Map, 48.8566, 2.3522, "1", "Paris", RGBA(255, 80, 80, 255))

  Repeat
    Select WaitWindowEvent()
      Case #PB_Event_CloseWindow
        Break
    EndSelect
  ForEver
EndIf

Notes importantes:

  • Activez "Create ThreadSafe Executable" dans les options du compilateur.
  • Appelez InitNetwork() avant les telechargements HTTP.
  • Les tuiles sont telechargees automatiquement via HTTP/HTTPS.

Ce que PBMap permet de faire

  • Afficher une carte (tuiles OSM/HERE/GeoServer).
  • Gerer des marqueurs (ajout, selection, edition).
  • Gerer des traces GPX (chargement, affichage, suppression).
  • Changer la vue (zoom, angle, centrage).
  • Configurer le cache disque et memoire.
  • Ajouter des callbacks pour reagir aux mouvements et aux clics.
  • Utiliser un clustering de marqueurs pour une meilleure lisibilite.

Configuration rapide des options utiles

PBMap::SetOption(#Map, "Verbose", "1")
PBMap::SetOption(#Map, "ShowMarkersLegend", "1")
PBMap::SetOption(#Map, "TileLifetime", "1209600") ; 2 semaines
PBMap::SetOption(#Map, "EnableClusters", "1")
PBMap::SetOption(#Map, "ClusterPixelSize", "60")
PBMap::SetOption(#Map, "ClusterMinCount", "2")

API publique - procedures et exemples

Les exemples supposent l'existence d'une carte #Map.

SetDebugLevel(Level.i)

Definit le niveau de debug (0..5).

PBMap::SetDebugLevel(3)

SetOption(MapGadget.i, Option.s, Value.s)

Change une option via une cle texte.

PBMap::SetOption(#Map, "ShowZoom", "1")

GetOption(MapGadget.i, Option.s)

Lit une option sous forme de chaine.

Debug PBMap::GetOption(#Map, "ShowZoom")

LoadOptions(MapGadget.i, PreferencesFile.s = "PBMap.prefs")

Charge les options depuis un fichier.

PBMap::LoadOptions(#Map, "PBMap.prefs")

SaveOptions(MapGadget.i, PreferencesFile.s = "PBMap.prefs")

Sauvegarde les options.

PBMap::SaveOptions(#Map, "PBMap.prefs")

AddOSMServerLayer(MapGadget.i, LayerName.s, Order.i, ServerURL.s)

Ajoute une couche OSM.

PBMap::AddOSMServerLayer(#Map, "OSM", 1, "https://tile.openstreetmap.org/")

AddHereServerLayer(...)

Ajoute une couche HERE (necessite AppId/AppCode).

PBMap::AddHereServerLayer(#Map, "HERE", 2, "APP_ID", "APP_CODE")

AddGeoServerLayer(...)

Ajoute une couche GeoServer.

PBMap::AddGeoServerLayer(#Map, "WMS", 3, "layer-name", "http://localhost:8080/")

IsLayer(MapGadget.i, Name.s)

Teste si une couche existe.

If PBMap::IsLayer(#Map, "OSM")
  Debug "Layer OSM ok"
EndIf

DeleteLayer(MapGadget.i, Name.s)

Supprime une couche.

PBMap::DeleteLayer(#Map, "WMS")

EnableLayer(MapGadget.i, Name.s)

Active une couche.

PBMap::EnableLayer(#Map, "OSM")

DisableLayer(MapGadget.i, Name.s)

Desactive une couche.

PBMap::DisableLayer(#Map, "HERE")

SetLayerAlpha(MapGadget.i, Name.s, Alpha.d)

Change la transparence d'une couche (0..1).

PBMap::SetLayerAlpha(#Map, "WMS", 0.5)

GetLayerAlpha(MapGadget.i, Name.s)

Lit la transparence d'une couche.

Debug PBMap::GetLayerAlpha(#Map, "WMS")

BindMapGadget(MapGadget.i, TimerNB = 1, Window = -1)

Attache PBMap a un Canvas existant.

PBMap::BindMapGadget(#MyCanvas, 1, #Win)

SetCallBackLocation(MapGadget.i, *CallBackLocation)

Callback: appel lors d'un changement de position (lat/lon).

Procedure OnMove(*Pos.PBMap::GeographicCoordinates)
  Debug StrD(*Pos\Latitude) + ", " + StrD(*Pos\Longitude)
EndProcedure
PBMap::SetCallBackLocation(#Map, @OnMove())

SetCallBackMainPointer(MapGadget.i, CallBackMainPointer.i)

Callback pour dessiner le pointeur principal.

Procedure DrawPointer(x.i, y.i)
  ; custom drawing
EndProcedure
PBMap::SetCallBackMainPointer(#Map, @DrawPointer())

SetCallBackDrawTile(MapGadget.i, *CallBackLocation)

Callback pour personnaliser le dessin d'une tuile.

Procedure DrawTile(x.i, y.i, image.i, alpha.d)
  ; custom drawing
EndProcedure
PBMap::SetCallBackDrawTile(#Map, @DrawTile())

SetCallBackMarker(MapGadget.i, *CallBackLocation)

Callback appele quand un marqueur a ete deplace (selection).

Procedure OnMarkerChange(*Marker.PBMap::Marker)
  Debug *Marker\Identifier
EndProcedure
PBMap::SetCallBackMarker(#Map, @OnMarkerChange())

SetCallBackLeftClic(MapGadget.i, *CallBackLocation)

Callback lors d'un clic gauche sur la carte.

Procedure OnLeftClick(*Pos.PBMap::GeographicCoordinates)
  Debug StrD(*Pos\Latitude)
EndProcedure
PBMap::SetCallBackLeftClic(#Map, @OnLeftClick())

SetCallBackModifyTileFile(MapGadget.i, *CallBackLocation)

Callback pour modifier un fichier de tuile apres telechargement.

Procedure.s OnTileFile(FileName.s, Url.s)
  ProcedureReturn FileName
EndProcedure
PBMap::SetCallBackModifyTileFile(#Map, @OnTileFile())

MapGadget(MapGadget.i, X.i, Y.i, Width.i, Height.i, TimerNB = 1, Window = -1)

Cree un canvas + PBMap.

#Map = PBMap::MapGadget(#PB_Any, 0, 0, 800, 600, 1, #Win)

FreeMapGadget(MapGadget.i)

Libere une carte.

PBMap::FreeMapGadget(#Map)

GetLatitude(MapGadget.i)

Latitude courante.

Debug StrD(PBMap::GetLatitude(#Map))

GetLongitude(MapGadget.i)

Longitude courante.

Debug StrD(PBMap::GetLongitude(#Map))

GetMouseLatitude(MapGadget.i)

Latitude sous la souris.

Debug StrD(PBMap::GetMouseLatitude(#Map))

GetMouseLongitude(MapGadget.i)

Longitude sous la souris.

Debug StrD(PBMap::GetMouseLongitude(#Map))

GetAngle(MapGadget.i)

Angle actuel.

Debug StrD(PBMap::GetAngle(#Map))

GetZoom(MapGadget.i)

Zoom actuel.

Debug PBMap::GetZoom(#Map)

GetMode(MapGadget.i)

Mode utilisateur courant.

Debug PBMap::GetMode(#Map)

SetMode(MapGadget.i, Mode.i = #MODE_DEFAULT)

Definit le mode.

PBMap::SetMode(#Map, PBMap::#MODE_HAND)

SetMapScaleUnit(MapGadget.i, ScaleUnit = PBMap::#SCALE_KM)

Definit l'unite d'echelle.

PBMap::SetMapScaleUnit(#Map, PBMap::#SCALE_NAUTICAL)

SetLocation(MapGadget.i, Latitude.d, Longitude.d, Zoom = -1, Mode.i = #PB_Absolute)

Centre la carte.

PBMap::SetLocation(#Map, 48.8566, 2.3522, 12)

SetAngle(MapGadget.i, Angle.d, Mode = #PB_Absolute)

Change l'angle.

PBMap::SetAngle(#Map, 15.0, #PB_Absolute)

SetZoom(MapGadget.i, Zoom.i, Mode.i = #PB_Relative)

Change le zoom.

PBMap::SetZoom(#Map, 1, #PB_Relative)

SetZoomToArea(MapGadget.i, MinY.d, MaxY.d, MinX.d, MaxX.d)

Zoom sur une zone.

PBMap::SetZoomToArea(#Map, 48.80, 48.90, 2.30, 2.40)

SetZoomToTracks(MapGadget.i, *Tracks)

Zoom automatique sur une trace.

PBMap::SetZoomToTracks(#Map, *Track)

NominatimGeoLocationQuery(MapGadget.i, Address.s, *ReturnPosition = 0)

Geocodage d'une adresse via Nominatim.

Define Pos.PBMap::GeographicCoordinates
PBMap::NominatimGeoLocationQuery(#Map, "Paris", @Pos)

LoadGpxFile(MapGadget.i, FileName.s)

Charge un fichier GPX.

Define *Track = PBMap::LoadGpxFile(#Map, "track.gpx")

SaveGpxFile(MapGadget.i, FileName.s, *Track)

Sauvegarde une trace GPX.

PBMap::SaveGpxFile(#Map, "export.gpx", *Track)

ClearTracks(MapGadget.i)

Supprime toutes les traces.

PBMap::ClearTracks(#Map)

DeleteTrack(MapGadget.i, *Ptr)

Supprime une trace.

PBMap::DeleteTrack(#Map, *Track)

DeleteSelectedTracks(MapGadget.i)

Supprime les traces selectionnees.

PBMap::DeleteSelectedTracks(#Map)

SetTrackColour(MapGadget.i, *Ptr, Colour.i)

Change la couleur d'une trace.

PBMap::SetTrackColour(#Map, *Track, RGBA(0, 200, 0, 200))

AddMarker(MapGadget.i, Latitude.d, Longitude.d, Identifier.s = "", Legend.s = "", Color.l = -1, CallBackPointer.i = -1)

Ajoute un marqueur.

PBMap::AddMarker(#Map, 48.86, 2.35, "A", "Point A", RGBA(255, 80, 80, 255))

ClearMarkers(MapGadget.i)

Supprime tous les marqueurs.

PBMap::ClearMarkers(#Map)

DeleteMarker(MapGadget.i, *Ptr)

Supprime un marqueur.

PBMap::DeleteMarker(#Map, *Marker)

DeleteSelectedMarkers(MapGadget.i)

Supprime les marqueurs selectionnes.

PBMap::DeleteSelectedMarkers(#Map)

Drawing(MapGadget.i)

Force un rendu immediat.

PBMap::Drawing(#Map)

FatalError(MapGadget.i, msg.s)

Affiche une erreur et termine.

PBMap::FatalError(#Map, "Erreur critique")

Error(MapGadget.i, msg.s)

Affiche une erreur simple.

PBMap::Error(#Map, "Erreur")

Refresh(MapGadget.i)

Demande un rafraichissement.

PBMap::Refresh(#Map)

ClearDiskCache(MapGadget.i)

Vide le cache disque.

PBMap::ClearDiskCache(#Map)

Clustering des marqueurs (explication)

Le clustering regroupe les marqueurs proches en un seul cercle.

  • EnableClusters: active ou non.
  • ClusterPixelSize: taille de la grille (en pixels).
  • ClusterMinCount: nombre minimum pour afficher un cluster.

Double-clic sur un cluster: zoom sur le centre du cluster.

Astuces pratiques

  • Activez Verbose pour diagnostiquer les chargements de tuiles.
  • Utilisez TileLifetime pour gerer l'expiration du cache.
  • Si vous avez beaucoup de marqueurs, activez le clustering.
  • Pour des couches multiples, ajustez SetLayerAlpha.
  • Si l'interface devient lente, reduisez MaxThreads ou MaxDownloadSlots.

Exemple complet (avec clustering)

IncludeFile "pbmap/PBMap.pb"
InitNetwork()
UseModule PBMap

Enumeration
  #Win
EndEnumeration

OpenWindow(#Win, 0, 0, 1000, 700, "PBMap clustering", #PB_Window_SystemMenu)
Define MapId = MapGadget(#PB_Any, 0, 0, 1000, 700, 1, #Win)

SetOption(MapId, "EnableClusters", "1")
SetOption(MapId, "ClusterPixelSize", "60")
SetOption(MapId, "ClusterMinCount", "2")

SetLocation(MapId, 48.8566, 2.3522, 10)

AddMarker(MapId, 48.85, 2.34, "1", "A", RGBA(255, 80, 80, 255))
AddMarker(MapId, 48.86, 2.35, "2", "B", RGBA(255, 80, 80, 255))
AddMarker(MapId, 48.87, 2.36, "3", "C", RGBA(255, 80, 80, 255))

Repeat
  Select WaitWindowEvent()
    Case #PB_Event_CloseWindow
      Break
  EndSelect
ForEver