Merge branch 'feature/M0078DDG-544_add_GNSS_foundation_documentation'…

… of github.com:MicroEJ/docs into feature/M0078DDG-544_add_GNSS_foundation_documentation

ApplicationDeveloperGuide/UI/MWT/how-to-animate-widget.rst

@@ -50,7 +50,7 @@ Performing an animation step
 ----------------------------
 
 The `tick()`_ method is called by the animator in order to update the widget. It is called in the UI thread once the display has been flushed.
-This method should not render the widget but should update its state and request a new render if necessary.
+This method should not render the widget but should update its state and request a new render.
 The `tick()`_ method should return whether or not the animation should continue after this increment.
 
 For example, the following snippet updates the state of the widget when it is ticked, requests a new render and keeps the animation going until 5 seconds have passed:
@@ -81,6 +81,8 @@ For example, the following snippet renders the current state of the widget by di
 		Painter.drawString(g, Long.toString(this.elapsedTime), style.getFont(), 0, 0);
 	}
 
+.. note:: Since an animator ticks its animations as often as possible, the animator may take 100% CPU usage if none of its animations requests a render. For more information on how to debug animators, see the :ref:`How to Debug Animators <section_monitoring_animators>` section.
+
 .. _tick(): https://repository.microej.com/javadoc/microej_5.x/apis/ej/mwt/animation/Animation.html#tick-long-
 .. _renderContent(): https://repository.microej.com/javadoc/microej_5.x/apis/ej/mwt/Widget.html#renderContent-ej.microui.display.GraphicsContext-int-int-
 .. _Util.platformTimeMillis(): https://repository.microej.com/javadoc/microej_5.x/apis/ej/bon/Util.html#platformTimeMillis--

ApplicationDeveloperGuide/UI/MWT/how-to-debug.rst

@@ -35,6 +35,98 @@ Here is an example of a ``xxx.constants.list`` file with the result in an applic
 	:align: center
 
 .. note:: Available since MWT 3.3.0.
+
+Monitoring the render operations
+--------------------------------
+
+When developing a GUI application, it may not be obvious what/how exactly the UI is rendered.
+Especially, when a widget can be re-rendered from a distant part of the application code.
+Or simply because of the ``RenderPolicy`` used.
+
+MWT provides a way to inject a monitor for the following render operations:
+
+* Render requests done by the Application.
+* Successive render executions triggered by the ``RenderPolicy``.
+
+Setting the ``ej.mwt.debug.render.enabled`` constant to ``true`` will enable the monitoring of above render operations.
+For more information about the monitoring mechanism, see `RenderPolicy Javadoc <https://repository.microej.com/javadoc/microej_5.x/apis/ej/mwt/render/RenderPolicy.html>`_.
+For more information about constants, see the :ref:`section.classpath.elements.constants` section.
+
+The Widget library provides a default monitor implementation that prints the operations on the standard output.
+The logs produced also contain information about what is rendered (widget and area) and what code requested the rendering.
+For more information about this monitor implementation, see `RenderMonitor Javadoc <https://repository.microej.com/javadoc/microej_5.x/apis/ej/widget/debug/RenderMonitor.html>`_.
+
+To use a different implementation (and if Widget is not in the classpath), set the ``ej.mwt.debug.render.monitor`` constant
+to the FQN of the monitor implementation class.
+
+Here is an example of a ``xxx.constants.list`` file with the result in an application:
+
+.. code-block::
+
+	ej.mwt.debug.render.enabled=true
+	ej.mwt.debug.render.monitor=ej.widget.debug.RenderMonitor
+
+.. figure:: images/renderWidgetBefore.png
+	:alt: Demo-Widget's Radio Button page with "Money" selected
+	:align: center
+
+	Screenshot before click
+
+.. code-block::
+	:caption: Application logs after click
+
+	rendermonitor@ INFO: Render requested on com.microej.demo.widget.common.PageHelper$2 > SimpleDock > OverlapContainer > SimpleDock > List > RadioButton at {0,0 87x25} of {221,116 87x25} by com.microej.demo.widget.radiobutton.widget.RadioButtonGroup.setChecked(RadioButtonGroup.java:47)
+	rendermonitor@ INFO: Render requested on com.microej.demo.widget.common.PageHelper$2 > SimpleDock > OverlapContainer > SimpleDock > List > RadioButton at {0,0 87x25} of {221,166 87x25} by com.microej.demo.widget.radiobutton.widget.RadioButtonGroup.setChecked(RadioButtonGroup.java:50)
+	rendermonitor@ INFO: Render executed on  com.microej.demo.widget.common.PageHelper$2 > SimpleDock > OverlapContainer > SimpleDock > List > RadioButton at {-221,-116 87x25} of {221,116 87x25}
+	rendermonitor@ INFO: Render executed on  com.microej.demo.widget.common.PageHelper$2 > SimpleDock > OverlapContainer > SimpleDock > List > RadioButton at {-221,-141 87x25} of {221,141 87x25}
+	rendermonitor@ INFO: Render executed on  com.microej.demo.widget.common.PageHelper$2 > SimpleDock > OverlapContainer > SimpleDock > List > RadioButton at {-221,-166 87x25} of {221,166 87x25}
+	rendermonitor@ INFO: Render executed on  com.microej.demo.widget.common.PageHelper$2 > SimpleDock > OverlapContainer > ImageWidget at {133,116 87x25} of {44,0 20x16}
+	rendermonitor@ INFO: Render executed on  com.microej.demo.widget.common.PageHelper$2 > SimpleDock > OverlapContainer > ImageWidget at {133,-140 87x25} of {44,256 20x16}
+	rendermonitor@ INFO: Render executed on  com.microej.demo.widget.common.PageHelper$2 > SimpleDock > OverlapContainer > SimpleDock > List > RadioButton at {-221,-116 87x25} of {221,166 87x25}
+	rendermonitor@ INFO: Render executed on  com.microej.demo.widget.common.PageHelper$2 > SimpleDock > OverlapContainer > ImageWidget at {133,166 87x25} of {44,0 20x16}
+	rendermonitor@ INFO: Render executed on  com.microej.demo.widget.common.PageHelper$2 > SimpleDock > OverlapContainer > ImageWidget at {133,-90 87x25} of {44,256 20x16}
+
+.. figure:: images/renderWidgetAfter.png
+	:alt: Demo-Widget's Radio Button page with "Energy" selected
+	:align: center
+
+	Screenshot after click
+
+.. note:: Available since MWT 3.5.0 & Widget 5.0.0.
+
+.. _section_monitoring_animators:
+
+Monitoring the Animators
+------------------------
+
+Since an animator ticks its animations as often as possible, the animator may take 100% CPU usage if none of its animations requests a render.
+
+MWT provides a way to inject a monitor to be notified when none of the animations has requested a render during an animator tick.
+
+Setting the ``ej.mwt.debug.animator.enabled`` constant to ``true`` will enable animator monitoring.
+For more information about constants, see the :ref:`section.classpath.elements.constants` section.
+
+The Widget library provides a default monitor implementation which logs warning messages.
+The logs produced also contain information about the animations running on the animator.
+The Animation instances are logged using their ``toString()`` method, so it can be a good idea to override this method
+in the Animation subclasses to be able to identify them.
+
+To use a different implementation (and if Widget is not in the classpath), set the ``ej.mwt.debug.animator.monitor`` constant
+to the FQN of the monitor implementation class.
+
+Here is an example of a ``xxx.constants.list`` file with the result in an application:
+
+.. code-block::
+
+	ej.mwt.debug.animator.enabled=true
+
+.. code-block::
+	:caption: Application logs when the watchface update animation is started but it doesn't request a render
+
+	animatormonitor WARNING: No render requested during animator tick. Animations list: [Watchface update animation]
+
+.. note:: Available since MWT 3.5.0 & Widget 5.0.0.
+
 ..
    | Copyright 2021-2023, MicroEJ Corp. Content in this space is free 
    for read and redistribute. Except if otherwise stated, modification 

ApplicationDeveloperGuide/UI/Widgets/widget.rst

@@ -71,9 +71,9 @@ The `LightHelper`_ proposes several primitives concerning the luminance of the c
 The luminance of a color is computed from the luminance and the quantity of each of its components.
 The green being the brighter, then the red and finally the blue.
 
-.. _ColorHelper: https://repository.microej.com/javadoc/microej_5.x/apis/ej/widget/util/color/ColorHelper.html
-.. _GradientHelper: https://repository.microej.com/javadoc/microej_5.x/apis/ej/widget/util/color/GradientHelper.html
-.. _LightHelper: https://repository.microej.com/javadoc/microej_5.x/apis/ej/widget/util/color/LightHelper.html
+.. _ColorHelper: https://repository.microej.com/javadoc/microej_5.x/apis/ej/widget/color/ColorHelper.html
+.. _GradientHelper: https://repository.microej.com/javadoc/microej_5.x/apis/ej/widget/color/GradientHelper.html
+.. _LightHelper: https://repository.microej.com/javadoc/microej_5.x/apis/ej/widget/color/LightHelper.html
 
 .. _widget_library_debug_utilities:
 
@@ -102,7 +102,7 @@ For example:
     |  |  +--Label
     |  +--Label
 
-.. _HierarchyInspector.hierarchyToString(Widget): https://repository.microej.com/javadoc/microej_5.x/apis/ej/widget/util/debug/HierarchyInspector.html#hierarchyToString-ej.mwt.Widget-
+.. _HierarchyInspector.hierarchyToString(Widget): https://repository.microej.com/javadoc/microej_5.x/apis/ej/widget/debug/HierarchyInspector.html#hierarchyToString-ej.mwt.Widget-
 
 Print the Path to a Widget
 ~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -115,8 +115,8 @@ It may be used to identify a widget in a trace.
 It is also possible to choose the separator by using `HierarchyInspector.pathToWidgetToString(Widget, char)`_ method.
 For example: ``Desktop ; Scroll ; ScrollableList ; Label``.
 
-.. _HierarchyInspector.pathToWidgetToString(Widget): https://repository.microej.com/javadoc/microej_5.x/apis/ej/widget/util/debug/HierarchyInspector.html#pathToWidgetToString-ej.mwt.Widget-
-.. _HierarchyInspector.pathToWidgetToString(Widget, char): https://repository.microej.com/javadoc/microej_5.x/apis/ej/widget/util/debug/HierarchyInspector.html#pathToWidgetToString-ej.mwt.Widget-char-
+.. _HierarchyInspector.pathToWidgetToString(Widget): https://repository.microej.com/javadoc/microej_5.x/apis/ej/widget/debug/HierarchyInspector.html#pathToWidgetToString-ej.mwt.Widget-
+.. _HierarchyInspector.pathToWidgetToString(Widget, char): https://repository.microej.com/javadoc/microej_5.x/apis/ej/widget/debug/HierarchyInspector.html#pathToWidgetToString-ej.mwt.Widget-char-
 
 Count the Number of Widgets or Containers
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -125,8 +125,8 @@ The methods `HierarchyInspector.countNumberOfWidgets(Widget)`_ and `HierarchyIns
 
 It may be used to evaluate the complexity of a hierarchy of widgets.
 
-.. _HierarchyInspector.countNumberOfWidgets(Widget): https://repository.microej.com/javadoc/microej_5.x/apis/ej/widget/util/debug/HierarchyInspector.html#countNumberOfWidgets-ej.mwt.Widget-
-.. _HierarchyInspector.countNumberOfContainers(Widget): https://repository.microej.com/javadoc/microej_5.x/apis/ej/widget/util/debug/HierarchyInspector.html#countNumberOfContainers-ej.mwt.Widget-
+.. _HierarchyInspector.countNumberOfWidgets(Widget): https://repository.microej.com/javadoc/microej_5.x/apis/ej/widget/debug/HierarchyInspector.html#countNumberOfWidgets-ej.mwt.Widget-
+.. _HierarchyInspector.countNumberOfContainers(Widget): https://repository.microej.com/javadoc/microej_5.x/apis/ej/widget/debug/HierarchyInspector.html#countNumberOfContainers-ej.mwt.Widget-
 
 Count the Maximum Depth of a Hierarchy
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -136,7 +136,7 @@ In other words, the depth of the widget with the biggest number of parents recur
 
 It may be used to evaluate the complexity of a hierarchy of widgets.
 
-.. _HierarchyInspector.countMaxDepth(Widget): https://repository.microej.com/javadoc/microej_5.x/apis/ej/widget/util/debug/HierarchyInspector.html#countMaxDepth-ej.mwt.Widget-
+.. _HierarchyInspector.countMaxDepth(Widget): https://repository.microej.com/javadoc/microej_5.x/apis/ej/widget/debug/HierarchyInspector.html#countMaxDepth-ej.mwt.Widget-
 
 Print the Bounds of a Widget
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -151,7 +151,7 @@ The returned String contains:
 
 For example: ``Label: 0,0 7x25 (absolute: 75,75)``
 
-.. _BoundsInspector.boundsToString(Widget): https://repository.microej.com/javadoc/microej_5.x/apis/ej/widget/util/debug/BoundsInspector.html#boundsToString-ej.mwt.Widget-
+.. _BoundsInspector.boundsToString(Widget): https://repository.microej.com/javadoc/microej_5.x/apis/ej/widget/debug/BoundsInspector.html#boundsToString-ej.mwt.Widget-
 
 Print the bounds of all the widgets in a hierarchy
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -171,7 +171,7 @@ For example:
     |  +--Label: 0,100 480x50 (absolute: 0,100)
   
 
-.. _BoundsInspector.boundsRecursiveToString(Widget): https://repository.microej.com/javadoc/microej_5.x/apis/ej/widget/util/debug/BoundsInspector.html#boundsRecursiveToString-ej.mwt.Widget-
+.. _BoundsInspector.boundsRecursiveToString(Widget): https://repository.microej.com/javadoc/microej_5.x/apis/ej/widget/debug/BoundsInspector.html#boundsRecursiveToString-ej.mwt.Widget-
 
 ..
    | Copyright 2008-2023, MicroEJ Corp. Content in this space is free 

ApplicationDeveloperGuide/eventQueue.rst

@@ -398,7 +398,7 @@ Application project to use the Event Queue Foundation Library.
 
 .. code-block:: xml
 
-   <dependency org="ej.api" name="event" rev="1.0.0"/>
+   <dependency org="ej.api" name="event" rev="2.0.0"/>
 
 To use this API, your VEE Port must implement a compatible version. 
 Please refer to the :ref:`VEE Porting Guide <pack_event>` to port the Event Queue for your project.

ApplicationDeveloperGuide/testsuiteEngine.rst

@@ -26,7 +26,7 @@ test suites on a MicroEJ Platform (either on Simulator or on Device).
 - For Application and Libraries, refer to :ref:`application_testsuite`
   section.
 - For Foundation Libraries Test Suites, refer to
-  :ref:`platform_testsuite` section.
+  :ref:`vee_port_testsuite` section.
 
 Using the MicroEJ Test Suite Ant Tasks
 --------------------------------------