Java Question RaisesSynchronousEvents

[Erel]

@RaisesSynchronousEvents is a new annotation added in B4A v3.0. It is only relevant for the rapid debugger.

This annotation tells the debugger engine that the method tagged with this annotation can raise one or more events as a direct result of the call (before the method returns).

In most cases it is not needed. In the official libraries it was only* required in XmlSax library.
Calling SaxParser.Parse or SaxParser.Parse2 causes the XML events to be raised. The method returns only after it calls these events.

* This annotation is also required when showing modal dialogs (Msgbox, Msgbox2,...).

The updated doclet tool is available here: http://www.b4x.com/android/forum/th...-build-libraries-without-eclipse.29918/page-3

 

[Erel]

More information about this annotation.

The rapid debugger is made of two components: debugger engine and device shell app. The code is executed by the debugger engine (which runs on the desktop). The debugger engine sends commands to the shell app. The result is the same as running the code directly on the device.

To avoid network latency the debugger engine doesn't wait for the result of each method. It sends a large chunk of commands and only when it must it waits for a result.

If however an event is raised directly from a call to another method then the debugger engine must wait for the result or else the buffers state will be broken.

For example, consider this code:

'Class module
Sub Class_Globals

End Sub

'Initializes the object. You can add parameters to this method if needed.
Sub Initialize

End Sub

Sub SubThatCanRaiseEvent (target As Object, i As Int)
   If i = 3 Then
     CallSub(target, "test")
   End If
End Sub

CallSub method is marked with @RaisesSynchronousEvents so the engine knows that it can raise an event and it will be ready for it.

If however you compile this code into a library and run it, you will get an error message saying:

Unexpected event (missing RaiseSynchronousEvents): test

The program will then crash.

The engine doesn't know that the method SubThatCanRaiseEvent can raise an event so when the event is raised it corrupts the buffers.

The solution for Java libraries is to add the @RaisesSynchronousEvents annotation on those methods.
For B4A compiled libraries you should use the new RaisesSynchronousEvents attribute:

'Class module
#RaisesSynchronousEvents: SubThatCanRaiseEvent
Sub Class_Globals

End Sub

'Initializes the object. You can add parameters to this method if needed.
Sub Initialize

End Sub

Sub SubThatCanRaiseEvent (target As Object, i As Int)
   If i = 3 Then
     CallSub(target, "test")
   End If
End Sub

Note that you can add this attribute multiple times, for each of the relevant subs.

 

[Erel]

As it will take some time for library developers to update their libraries, a workaround is provided.

The file LibrariesExceptions.txt which is located in Basic4android folder lists methods that should have been marked with this annotation. The IDE reads this file when libraries are loaded. This way the current libraries can continue to work properly (it is exactly the same as adding the annotation).

As of beta #6, the file content is:

1: TweenManager.Update
1: id.InputList1
1: BetterDialogs.CustomDialog
1: BetterDialogs.Msgbox
1: BetterDialogs.InputBox
1: InputDialog.Show
1: DateDialog.Show
1: TimeDialog.Show
1: ColorDialogHSV.Show
1: ColorPickerDialog.Show
1: NumberDialog.Show
1: CustomDialog.Show
1: CustomDialog2.Show
1: CustomDialog3.Show
1: Msgbox3.Show
1: Msgbox3WithoutDim.Show
1: AHViewPager.GotoPage
1: PDFWriter.ConverseDocument
1: UltimateListView.LoadImageAsync

The syntax is (case sensitive):
1: <short name>.<method name>

 

[Rusty]

I'm using the UltimateListView in my MAIN.
How do I specify the #RaisesSynchronousEvents: SubThatCanRaiseEvent within the MAIN (i.e. not within a library)?
Only a problem with Rapid Debugger...
Thanks,
Rusty

 

[Erel]

The library author should do it. If it is a specific method then you can edit the xml file and add RaisesSynchronousEvents="true" to the name element. See XmlSax.xml for an example.

 

[corwin42]

Is the @RaisesSynchronousEvents annotation still required?

I want to update the AHViewPager library and checked the events.

The ViewPager_PageScrolled event is raised with raiseEvent() because this event has to be fired as fast as possible so if you implement a page change indicator with this event you can animate it smooth.

Is AHViewPager.GotoPage in the exceptions list because of the modal dialogs problem?

I currently don't use the @RaisesSynchronousEvents annotation for AHViewPager but a test app runs without problems with the rapid debugger. Maybe that is because I do only some log output in the PageScrolled event sub. So it is not required that the debugger waits for the event to finish. Or do I only need to use the annotation if the library uses the result of raiseEvent()?

In AHSwipeToRefresh library there is an event (STR_CanChildScrollUp) which returns true or false so the library can check if it should start the refresh action or not. This of course needs to be called synchronous because the library needs the feedback. But where should I put the annotation? There is no method which raises the event. It is a gesture the user starts on the display (swiping down).

For me it is still not very clear where and when to use this annotation.

 

[Erel]

Is the @RaisesSynchronousEvents annotation still required?

Yes.

In most cases nothing bad will happen if you don't add this annotation. The event will only fire after the current code completes. You can think of it as if the debugger changed a CallSub to CallSubDelayed.

Is AHViewPager.GotoPage in the exceptions list because of the modal dialogs problem?

Yes.

You can call raiseEvent without this annotation. The annotation is only required if the raiseEvent is called as a result of another method call.
The logs will tell you if there is a missing annotation.

 

[Computersmith64]

I'm seeing this:

Unexpected event (missing RaiseSynchronousEvents): txtapptdate_textchanged

when testing using the rapid debugger. If I understand the previous posts correctly, this won't cause any issues in the release build?

- Colin.

 

[corwin42]

Is AHViewPager.GotoPage in the exceptions list because of the modal dialogs problem?

Yes.

Ok, but if I understand correctly because AHViewPager uses raiseEventFromUI() in the latest versions it is no longer required?

You can call raiseEvent without this annotation. The annotation is only required if the raiseEvent is called as a result of another method call.
The logs will tell you if there is a missing annotation.

Thanks for the info. I think I understand it now.

Seems that I have to use the rapid debugger more often for testing my libraries.

 

[Erel]

Ok, but if I understand correctly because AHViewPager uses raiseEventFromUI() in the latest versions it is no longer required?

That is correct.

If I understand the previous posts correctly, this won't cause any issues in the release build?

Yes. RaisesSynchronousEvents and this warning message are only relevant to debug (rapid) mode.