Aide LibreOffice 25.8
Le service Exception est un ensemble de méthodes pour aider au débogage du code dans les scripts Basic et Python et à la gestion des erreurs dans les scripts Basic.
Dans les scripts de base, lorsqu'une erreur d'exécution se produit, les méthodes et propriétés du service Exception aident à identifier le contexte de l'erreur et permettent de le gérer.
Le service SF_Exception est similaire à l'objet VBA Err.
La propriété Number identifie l'erreur.
Utilisez la méthode Raise pour interrompre le traitement. La méthode RaiseWarning peut être utilisée pour intercepter une anomalie sans interrompre l'exécution de la macro.
Les erreurs et les avertissements générés avec le service Exception sont stockés en mémoire et peuvent être récupérés à l'aide de la méthode Console.
La console de service Exception stocke les événements, les valeurs des variables et les informations sur les erreurs. Utilisez la console lorsque l'IDE de base n'est pas facilement accessible, par exemple dans les fonctions définies par l'utilisateur (UDF) de Calc ou lors du traitement d'événements.
Utilisez la méthode DebugPrint pour ajouter toute information pertinente à la console. Les entrées de la console peuvent être copiées dans un fichier texte ou visualisées dans une fenêtre de dialogue.
Lorsqu'une erreur se produit, une macro d'application peut :
Signaler l'erreur dans la console Exception
Informer l'utilisateur de l'erreur à l'aide d'un message standard ou d'un message personnalisé
Arrêter éventuellement son exécution
Dans les scripts Python, le service Exception est principalement utilisé à des fins de débogage. Des méthodes telles que DebugPrint, Console et DebugDisplay sont utiles pour imprimer rapidement des messages, enregistrer des données et ouvrir la fenêtre de la console à partir d'un script Python.
Toutes les méthodes et propriétés ne sont pas disponibles pour les scripts Python car le langage Python dispose déjà d'un système complet de gestion des exceptions.
Avant d'utiliser le service Exception, la bibliothèque ScriptForge doit être chargée ou importée :
Les exemples suivants montrent trois approches différentes pour appeler la méthode Raise. Toutes les autres méthodes peuvent être exécutées de la même manière.
    SF_Exception.Raise(...)
  
    Dim exc : exc = SF_Exception
    exc.Raise(...)
  
    Dim exc : exc = CreateScriptService("Exception")
    exc.Raise(...)
  L'extrait de code ci-dessous crée une instance du service Exception, consigne un message et affiche la fenêtre Console.
    from scriptforge import CreateScriptService
    exc = CreateScriptService("Exception")
    someVar = 100
    exc.DebugPrint("Value of someVar", someVar)
    exc.Console()
  Les propriétés listées ci-dessous ne sont disponibles que pour les scripts Basic.
| Nom | En lecture seule | Description | 
|---|---|---|
| Description | Non | Le texte du message d'erreur. La valeur par défaut est "" ou une chaîne contenant le message d'erreur d'exécution Basic. | 
| Number | Non | Le code de l'erreur. Il peut s'agir d'une valeur numérique ou de texte. La valeur par défaut est 0 ou la valeur numérique correspondant au code d'erreur d'exécution Basic. | 
| Source | Non | L'emplacement dans le code où l'erreur s'est produite. Il peut s'agir d'une valeur numérique ou de texte. La valeur par défaut est 0 ou le numéro de ligne de code pour une erreur d'exécution Basic | 
Lever ou effacer une Exception réinitialise ses propriétés.
| Liste des méthodes dans le service Exception | ||
|---|---|---|
Réinitialise l'état d'erreur actuel et efface les propriétés SF_Exception.
    SF_Exception.Clear()
  L'exemple suivant montre comment intercepter une exception de division par zéro, dont le code d'erreur est 11.
    Sub Example_Clear()
        Dim a, b, c
        On Local Error GoTo Catch
        Try:
            a = 10 : b = 0
            c = a / b
            '...
            Exit Sub
        Catch:
            If SF_Exception.Number = 11 Then SF_Exception.Clear()
            'Si division par zéro, ignorer l'erreur
    End Sub
  Pour une liste complète des codes d'erreur d'exécution Basic, reportez-vous à Débogage d'un programme Basic.
Affiche les messages de la console dans une boîte de dialogue modale ou non modale. Dans les deux modes, tous les messages passés émis par une méthode DebugPrint() ou résultant d'une exception sont affichés. En mode non modal, les entrées suivantes sont ajoutées automatiquement.
Si la console est déjà ouverte, lorsqu'elle est non modale, elle est amenée au premier plan.
Une console modale ne peut être fermée que par l'utilisateur. Une console non modale peut être fermée par l'utilisateur ou lors de l'arrêt de la macro.
exc.Console(modal: bool = True)
modal : détermine si la fenêtre de la console est modale (True) ou non modale (False). La valeur par défaut est True.
        SF_Exception.Console(Modal := False)
  
    exc.Console(modal = False)
  Efface la console en conservant un nombre facultatif de messages récents. Si la console est activée en mode non modal, elle est rafraîchie.
exc.ConsoleClear(keep: int = 0)
keep : le nombre de messages récents à conserver. La valeur par défaut est 0.
L'exemple suivant efface la console en conservant les 10 messages les plus récents.
        SF_Exception.ConsoleClear(10)
  
    exc.ConsoleClear(10)
  Exporte le contenu de la console dans un fichier texte. Si le fichier existe déjà et que la console n'est pas vide, il sera écrasé sans avertissement. Renvoie True en cas de succès.
exc.ConsoleToFile(filename: str): bool
filename : le nom du fichier texte dans lequel la console doit être copiée. Le nom est exprimé en fonction de la propriété FileNaming actuelle du service SF_FileSystem. Par défaut, la notation d'URL et le format du système d'exploitation natif sont tous deux admis.
        SF_Exception.ConsoleToFile("C:\Documents\myFile.txt")
  
    exc.ConsoleToFile(r"C:\Documents\myFile.txt")
  Concatène tous les arguments en une seule chaîne lisible par l'homme et l'affiche dans une MsgBox avec une icône d'information et un bouton OK.
La chaîne finale est également ajoutée à la console.
exc.DebugDisplay(arg0: any, [arg1: any, ...])
arg0[, arg1, ...] : n'importe quel nombre d'arguments de n'importe quel type.
    SF_Exception.DebugDisplay("Current Value", someVar)
  
    exc.DebugDisplay("Current Value", someVar)
  Assemble tous les arguments donnés en une seule chaîne lisible par l'homme et l'ajoute en tant que nouvelle entrée dans la console.
exc.DebugPrint(arg0: any, [arg1: any, ...])
arg0[, arg1, ...] : n'importe quel nombre d'arguments de n'importe quel type.
    SF_Exception.DebugPrint(Null, Array(1, 2, 3), "line1" & Chr(10) & "Line2", DateSerial(2020, 04, 09))
    ' [NULL]   [ARRAY] (0:2) (1, 2, 3)  line1\nLine2  2020-04-09
  
    exc.DebugPrint(None, [1, 2, 3], "line1\nline2")
    # None  [1, 2, 3]  line1\nline2
  Affiche la liste des arguments sous une forme lisible dans la console de la plateforme. Les arguments sont séparés par un caractère TAB (simulé par des espaces).
La même chaîne est ajoutée à la console de débogage ScriptForge.
Si Python shell (APSO) est actif, le contenu PythonPrint est écrit sur la console APSO à la place de la console de la plate-forme.
  exc.PythonPrint(arg0: any, [arg1: any, ...])
  arg0[, arg1, ...] : n'importe quel nombre d'arguments de n'importe quel type. La longueur maximale de chaque argument individuel est de 1024 caractères.
    exc.PythonPrint(a, Array(1, 2, 3), , "line1" & Chr(10) & "Line2", DateSerial(2020, 04, 09))
  En Python, utilisez une instruction print pour imprimer sur la console APSO ou utilisez la méthode DebugPrint pour imprimer sur la console de ScriptForge.
Ouvre un shell APSO Python en tant que fenêtre non modale. Le script Python continue de s'exécuter après l'ouverture du shell. La sortie des instructions print à l'intérieur du script est affichée dans le shell.
Une seule instance du shell APSO Python peut être ouverte à tout moment. Par conséquent, si un shell Python est déjà ouvert, l'appel de cette méthode n'aura aucun effet.
exc.PythonShell(opt variables: dict, background = 0xFDF6E3, foreground = 0x657B83)
variables : un dictionnaire Python avec des noms de variables et des valeurs qui seront transmises au shell APSO Python. Par défaut, toutes les variables locales sont transmises à l'aide de la fonction intégrée locals() de Python.
background : couleur d'arrière-plan de la console spécifiée comme valeur entière RVB 24 bits. L'arrière-plan par défaut est celui d'APSO.
foreground : couleur de premier plan de la console spécifiée comme valeur entière RVB 24 bits. Le premier plan par défaut est celui d'APSO.
L'exemple ci-dessous ouvre le shell Python APSO en transmettant toutes les variables globales et locales en fonction du contexte dans lequel le script est exécuté. La console s'affiche avec des caractères blancs sur fond noir.
    exc.PythonShell({**globals(), **locals()}, \
        background = 0x0, foreground = 0xFFFFFF)
  Lorsque le shell APSO Python est ouvert, toute sortie ultérieure imprimée par le script sera affichée dans le shell. Par conséquent, la chaîne imprimée dans l'exemple ci-dessous sera affichée dans le shell Python.
    s = CreateScriptService('Basic')
    RED, BLUE = s.RGB(255,0,0), s.RGB(0,0,255)
    exc.PythonShell(background=RED, foreground=BLUE)
    print("Hello world!")
  Génère une erreur d'exécution. Un message d'erreur est affiché à l'utilisateur et signalé dans la console. L'exécution est arrêtée. La méthode Raise() peut être placée dans le flux de script normal ou dans une routine de gestion des erreurs dédiée.
    SF_Exception.Raise(Number := Err, [Source := Erl], [Description := Error$])
  Les extraits de code présentés ensuite sont équivalents. Ils montrent d'autres moyens de déclencher une exception avec le code 2100.
    SF_Exception.Raise(2100)
  
    SF_Exception.Number = 2100
    SF_Exception.Raise()
  
    SF_Exception.Raise Number := 2100
  Number : code d'erreur, sous forme de nombre ou de chaîne. La valeur par défaut est celle de la fonction intégrée de base Err, auquel cas Number est facultatif.
Source : l'emplacement de l'erreur, sous forme de nombre ou de chaîne. La valeur par défaut est celle de la fonction Basic intégrée Erl.
Description : le message à afficher à l'utilisateur et à signaler dans la console. La valeur par défaut est celle de la fonction Basic intégrée Error$.
    Sub Example_Raise()
        Dim a, b, c
        On Local Error GoTo Catch
        Try:
            a = 10 : b = 0
            c = a / b
            '...
            Exit Sub
        Catch:
            'Voir les variantes ci-dessous...
    End Sub
  Pour déclencher une exception avec les valeurs standard :
    Catch:
        SF_Exception.Raise()
  Pour déclencher une exception avec un code spécifique :
    Catch:
        SF_Exception.Raise(11)
  Pour remplacer le message habituel :
    Catch:
        SF_Exception.Raise(, , "It is not a good idea to divide by zero.")
  Pour générer une erreur d'application :
    Catch:
        SF_Exception.Raise("MyAppError", "Example_Raise()", "Something wrong happened !")
  Cette méthode a exactement la même syntaxe, les mêmes arguments et le même comportement que la méthode Raise().
Cependant, lorsqu'un avertissement est émis, l'exécution de la macro n'est pas arrêtée.
    SF_Exception.RaiseWarning([Number As Variant], [Source As Variant], [Description As String])
  
    SF_Exception.RaiseWarning(Source:="Example_Raise()", _
        Description:="Something wrong happened !", _
        Number:="MyAppError")