--- source/text/sbasic/shared/03/sf_exception.xhp | 125 ++++++++++++-------------- 1 file changed, 58 insertions(+), 67 deletions(-) (limited to 'source/text') diff --git a/source/text/sbasic/shared/03/sf_exception.xhp b/source/text/sbasic/shared/03/sf_exception.xhp index 46a5e3525c..2f6ed4a2d5 100644 --- a/source/text/sbasic/shared/03/sf_exception.xhp +++ b/source/text/sbasic/shared/03/sf_exception.xhp @@ -8,21 +8,20 @@ * file, You can obtain one at http://mozilla.org/MPL/2.0/. * --> - - ScriptForge.Exception service (SF_Exception) + ScriptForge.Exception service (SF_Exception) /text/sbasic/shared/03/sf_exception.xhp

- + Exception service -

ScriptForge.Exception service

- The Exception service is a collection of methods to assist in code debugging in Basic and Python scripts and in error handling in Basic scripts. - In Basic scripts, when a run-time error occurs, the methods and properties of the Exception service help identify the error context and allow to handle it. +

ScriptForge.Exception service

+ The Exception service is a collection of methods to assist in code debugging in Basic and Python scripts and in error handling in Basic scripts. + In Basic scripts, when a run-time error occurs, the methods and properties of the Exception service help identify the error context and allow to handle it.

@@ -35,20 +34,21 @@ Use the Raise method to interrupt processing. The RaiseWarning method can be used to trap an anomaly without interrupting the macro execution. - Errors and warnings raised with the Exception service are stored in memory and can be retrieved using the Console method. - - The Exception service console stores events, variable values and information about errors. Use the console when the Basic IDE is not easily accessible, for example in Calc user defined functions (UDF) or during events processing. + Errors and warnings raised with the Exception service are stored in memory and can be retrieved using the Console method. + The Exception service console stores events, variable values and information about errors. Use the console when the Basic IDE is not easily accessible, for example in Calc user defined functions (UDF) or during events processing. Use the DebugPrint method to add any relevant information to the console. Console entries can be dumped to a text file or visualized in a dialog window. - When an error occurs, an application macro may: + When an error occurs, an application macro may: - Report the error in the Exception console - Inform the user about the error using either a standard message or a custom message - Optionally stop its execution + Report the error in the Exception console + Inform the user about the error using either a standard message or a custom message + Optionally stop its execution In Python scripts the Exception service is mostly used for debugging purposes. Methods such as DebugPrint, Console and DebugDisplay are useful to quickly print messages, log data and open the console window from within a Python script. Not all methods and properties are available for Python scripts since the Python language already has a comprehensive exception handling system. -

Service invocation

+ Before using the Exception service the ScriptForge library needs to be loaded or imported: +

The following examples show three different approaches to call the method Raise. All other methods can be executed in a similar fashion. @@ -71,8 +71,7 @@ exc.DebugPrint("Value of someVar", someVar) exc.Console() - -

Properties

The properties listed below are only available for Basic scripts.

@@ -92,10 +91,10 @@ Description - No + No - The error message text. + The error message text. Default value is "" or a string containing the Basic run-time error message. @@ -104,10 +103,10 @@ Number - No + No - The code of the error. It can be a numeric value or text. + The code of the error. It can be a numeric value or text. Default value is 0 or the numeric value corresponding to the Basic run-time error code. @@ -116,10 +115,10 @@ Source - No + No - The location in the code where the error occurred. It can be a numeric value or text. + The location in the code where the error occurred. It can be a numeric value or text. Default value is 0 or the code line number for a standard Basic run-time error. @@ -127,7 +126,6 @@ Raising or clearing an Exception resets its properties.

@@ -159,10 +157,9 @@

Clear -------------------------------------------------------------------------------------------------------------------------- - + Exception service;Clear

Clear

@@ -185,21 +182,20 @@ Exit Sub Catch: If SF_Exception.Number = 11 Then SF_Exception.Clear() - 'If division by zero, ignore the error + 'If division by zero, ignore the error End Sub For a complete list of Basic run-time error codes, refer to Debugging a Basic Program.

Console -------------------------------------------------------------------------------------------------------------------------- - + Exception service;Console

Console

Displays the console messages in a modal or non-modal dialog. In both modes, all the past messages issued by a DebugPrint() method or resulting from an exception are displayed. In non-modal mode, subsequent entries are added automatically. - If the console is already open, when non-modal, it is brought to the front. - A modal console can only be closed by the user. A non-modal console can either be closed by the user or upon macro termination. + If the console is already open, when non-modal, it is brought to the front. + A modal console can only be closed by the user. A non-modal console can either be closed by the user or upon macro termination.

exc.Console(modal: bool = True) @@ -216,10 +212,9 @@ exc.Console(modal = False)

ConsoleClear -------------------------------------------------------------------------------------------------------------------------- - + Exception service;ConsoleClear

ConsoleClear

@@ -241,10 +236,9 @@ exc.ConsoleClear(10)

ConsoleToFile -------------------------------------------------------------------------------------------------------------------------- - + Exception service;ConsoleToFile

ConsoleToFile

@@ -265,10 +259,9 @@ exc.ConsoleToFile(r"C:\Documents\myFile.txt")

DebugDisplay -------------------------------------------------------------------------------------------------------------------------- - + Exception service;DebugDisplay

DebugDisplay

@@ -290,10 +283,9 @@ exc.DebugDisplay("Current Value", someVar)

DebugPrint -------------------------------------------------------------------------------------------------------------------------- - + Exception service;DebugPrint

DebugPrint

@@ -316,10 +308,9 @@ # None [1, 2, 3] line1\nline2

PythonPrint -------------------------------------------------------------------------------------------------------------------------- - + Exception service;PythonPrint

PythonPrint

@@ -339,10 +330,9 @@ In Python use a print statement to print to the APSO console or use the DebugPrint method to print to ScriptForge's console.

PythonShell -------------------------------------------------------------------------------------------------------------------------- - + Exception service;PythonShell

PythonShell

@@ -351,25 +341,29 @@

- exc.PythonShell(variables: dict) + exc.PythonShell(opt variables: dict, background = 0xFDF6E3, foreground = 0x657B83)

variables: a Python dictionary with variable names and values that will be passed on to the APSO Python shell. By default all local variables are passed using Python's builtin locals() function. + background: Background color of the console specified as RGB 24 bits integer value. Default background is that of APSO. + foreground: Foreground color of the console specified as RGB 24 bits integer value. Default foreground is that of APSO.

- The example below opens the APSO Python shell passing all global and local variables considering the context where the script is running. + The example below opens the APSO Python shell passing all global and local variables considering the context where the script is running. Console is displayed with white characters on a black background. - exc.PythonShell({**globals(), **locals()}) + exc.PythonShell({**globals(), **locals()}, \ + background = 0x0, foreground = 0xFFFFFF) When the APSO Python shell is open, any subsequent output printed by the script will be shown in the shell. Hence, the string printed in the example below will be displayed in the Python shell. - exc.PythonShell() + s = CreateScriptService('Basic') + RED, BLUE = s.RGB(255,0,0), s.RGB(0,0,255) + exc.PythonShell(background=RED, foreground=BLUE) print("Hello world!")

Raise -------------------------------------------------------------------------------------------------------------------------- - + Exception service;Raise

Raise

@@ -379,7 +373,7 @@ SF_Exception.Raise([Number As Variant], [Source As Variant], [Description As String]) - The code snippets presented next are equivalent. They show alternative ways to raise an exception with code 2100. + The code snippets presented next are equivalent. They show alternative ways to raise an exception with code 2100. SF_Exception.Raise(2100) @@ -394,8 +388,8 @@

Number: The error code, as a number or as a string. Default value is that of Err Basic builtin function.

- Source: The location of the error, as a number or as a string. Default value is that of Erl Basic builtin function. - Description: The message to display to the user and to report in the console. Default value is that of Error$ Basic builtin function. + Source: The location of the error, as a number or as a string. Default value is that of Erl Basic builtin function. + Description: The message to display to the user and to report in the console. Default value is that of Error$ Basic builtin function.

@@ -408,39 +402,38 @@ '... Exit Sub Catch: - 'See variants below ... + 'See variants below ... End Sub - To raise an exception with the standard values: + To raise an exception with the standard values: Catch: SF_Exception.Raise() - To raise an exception with a specific code: + To raise an exception with a specific code: Catch: SF_Exception.Raise(11) - To replace the usual message: + To replace the usual message: Catch: - SF_Exception.Raise(, , "It is not a good idea to divide by zero.") + SF_Exception.Raise(, , "It is not a good idea to divide by zero.") - To raise an application error: + To raise an application error: Catch: - SF_Exception.Raise("MyAppError", "Example_Raise()", "Something wrong happened !") + SF_Exception.Raise("MyAppError", "Example_Raise()", "Something wrong happened !")

RaiseWarning -------------------------------------------------------------------------------------------------------------------------- - + Exception service;RaiseWarning

RaiseWarning

- This method has exactly the same syntax, arguments and behavior as the Raise() method. - However, when a warning is raised, the macro execution is not stopped. + This method has exactly the same syntax, arguments and behavior as the Raise() method. + However, when a warning is raised, the macro execution is not stopped.

@@ -451,14 +444,12 @@

SF_Exception.RaiseWarning(Source:="Example_Raise()", _ - Description:="Something wrong happened !", _ - Number:="MyAppError") + Description:="Something wrong happened !", _ + Number:="MyAppError")

- - + \ No newline at end of file -- cgit