pas2js exceptions: what changed

Revision 0 to 1. Removed lines have a minus sign; added lines have a plus sign.

Title: pas2js exceptions

New		Line
1	+	# Exception handling
2	+
3	+	## Uncaught exceptions
4	+
5	+	Pas2js translates exceptions to actual javascript exceptions. You can use the usual mechanisms try..finally..end and try..except..end to handle them.
6	+
7	+	In case you do not handle exceptions, the rtl.js runtime has several mechanisms to deal with uncaught exceptions.
8	+
9	+	In case you don't handle the exception, the default behaviour of the rtl is not to do anything. If you run the program in the browser, you'll see a message in the console, but that is it. To visualize the exception, you can add the following in your html file:
10	+
11	+	<script type="application/javascript">
12	+	rtl.showUncaughtExceptions=true;
13	+	rtl.run();
14	+	</script>
15	+
16	+	the browser will then use a window.alert() to show any uncaught exceptions.
17	+
18	+	Note that this is handled by the small rtl.js runtime, the pas2js system units do not handle this (but see below).
19	+
20	+	## Exceptions in event handlers
21	+
22	+	When an exception is raised in an event handler, the rtl will not catch it. In fact, you will not see it.
23	+
24	+	The way to handle this is to use the safecall calling convention on event handler types.
25	+
26	+	When you do this, the compiler will create a callback that does what a normal callback does, but inserts code to catch exceptions and route them to the rtl.
27	+
28	+	The event handlers in the web.pas unit are declared using this calling convention (version 1.5.1 and above only):
29	+
30	+	TJSRawEventHandler = reference to Procedure(Event: TJSEvent); safecall;
31	+
32	+	This means that the event handler will catch an exception and route it to the rtl event handling mechanism.
33	+
34	+	## Hooking into exception handling
35	+
36	+	As explained above, the default way to deal with exceptions is to show them using window.alert().
37	+
38	+	It is possible to override this behaviour using the sysutils unit.
39	+
40	+	Type
41	+	TShowExceptionHandler = Procedure (Const Msg : String);
42	+	TUncaughtPascalExceptionHandler = reference to Procedure(aObject : TObject);
43	+	TUncaughtJSExceptionHandler = reference to Procedure(aObject : TJSObject);
44	+
45	+	// Handler to show an exception (used when showexception is called)
46	+	OnShowException : TShowExceptionHandler = nil;
47	+
48	+	Function SetOnUnCaughtExceptionHandler(aValue : TUncaughtPascalExceptionHandler) : TUncaughtPascalExceptionHandler;
49	+	Function SetOnUnCaughtExceptionHandler(aValue : TUncaughtJSExceptionHandler) : TUncaughtJSExceptionHandler;
50	+	Procedure HookUncaughtExceptions;
51	+
52	+	The HookUncaughtExceptions call hooks into the rtl handler for uncaught exceptions.
53	+
54	+	After a call to HookUncaughtExceptions the exceptions caught by the rtl handling mechanism will be displayed using ShowException.
55	+
56	+	You can set your own handlers for uncaught exceptions with SetOnUnCaughtExceptionHandler.
57	+
58	+	There are 2 handlers: one for every object that is an actual pascal object, one for Javascript objects such as JSError. This is because the roots of these 2 object trees are different.
59	+
60	+	These calls return the old exception handler, if there were any. And if you set your own handler, HookUncaughtExceptions will be called automatically.
61	+
62	+	# Navigation
63	+
64	+	- Back to [[pas2js]]
65	+	- Back to [[lazarus pas2js integration]]
66	+
67	+	---
68	+	From the Free Pascal wiki, page "pas2js exceptions", as it stood on 2020-08-01 after a change by Michael, out of the wiki's dump of 2024-05-26. Copyright stays with the author who wrote it, according to the old wiki's [[Licensing]] page. If you have concerns about this material, [message the admin](/wiki-contact).
69	+	Category: Pas2js

Back to history