MicroEJ Developer
Get Started



Demo Widget

This demo illustrates the Widget library based on MicroUI 3 and MWT 3.
EXAMPLE for UI
Supported MicroEJ Version: 5.x
Supported MicroEJ Edition: Studio & SDK
Last updated:
21 October 2020
+
# Overview

This repository provides a demo illustrating the widgets and containers
available in the widget library: `ej.library.ui#widget-3.0.0`.

---  
_Copyright 2020 MicroEJ Corp. All rights reserved._  
_Use of this source code is governed by a BSD-style license that can be found with this software._  

MicroUI (Foundation Library API)

The MicroEJ User Interface and User eXperience API.
LIBRARY for UI
Supported MicroEJ Version: 5.x
Supported MicroEJ Edition: Studio & SDK
Last updated:
23 September 2020
+
<!--
	Markdown
	Copyright 2015-2016 IS2T. All rights reserved.
	IS2T PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.
-->

# Overview
This library contains classes and interfaces stubs of Micro User Interface API (ESR002).

# Usage
Add the following line to your `module.ivy` or your `ivy.xml`:
> `<dependency org="ej.api" name="microui" rev="2.+"/>`

# Requirements
  - EDC-1.2 or higher
  - BON-1.2 or higher

# Dependencies
None.

# Source
N/A

# Restrictions
None.

MWT

This library contains all that is necessary to create an HMI with widgets.
LIBRARY for UI
Supported MicroEJ Version: 5.x
Supported MicroEJ Edition: Studio & SDK
Last updated:
23 September 2020
+
# Overview

This library contains all that is necessary to create an HMI with widgets.

# Usage

Add the following line to your `module.ivy`:
	
    <dependency org="ej.library.ui" name="mwt" rev="2.3.1"/>
	
# Requirements

This library requires the following Foundation Libraries:

    BON-1.2, EDC-1.2, MICROUI-2.0

# Dependencies

_All dependencies are retrieved transitively by MicroEJ Module Manager_.


# Source

N/A

# Restrictions

None.

---  
_Copyright 2018-2019 MicroEJ Corp. All rights reserved._  
_This library is provided in source code for use, modification and test, subject to license terms._  
_Any modification of the source code will break MicroEJ Corp. warranties on the whole library._  

Motion

Motion library, providing animated tasks and a set of defined motions.
LIBRARY for UI
Supported MicroEJ Version: 5.x
Supported MicroEJ Edition: Studio & SDK
Last updated:
23 September 2020
+
<!--
	Markdown
	Copyright 2014-2016 IS2T. All rights reserved.
	IS2T PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.
-->

# Overview
A motion library, providing animated tasks and a set of defined motions 
(linear, elastic, bounce, etc.), useful for HMI animations.

# Usage
Add the following line to your `module.ivy` or your `ivy.xml`:
> `<dependency org="ej.library.runtime" name="components" rev="3.+"/>`

# Requirements
  - EDC-1.2 or higher
  - BON-1.2 or higher

# Dependencies
None.

# Source
N/A

# Restrictions
None.

Widget

Widget library.
LIBRARY for UI
Supported MicroEJ Version: 5.x
Supported MicroEJ Edition: Studio & SDK
Last updated:
23 September 2020
+
# Overview

This library contains all that is necessary to create an HMI on MWT 2:

- a dynamic style resolution (_ej.style_),
- a set of widgets (_ej.widget_),
- a set of containers (_ej.widget.container_),
- an animation framework (_ej.animation_),
- a navigation framework (_ej.widget.navigation_),
- some color utilities (_ej.color_).

# Style

The style framework is used to customize a user interface.

A style is a set of attributes to apply to an element (spacing, coloring, font, size, etc.).

The stylesheet is augmented with rules: a selector associated with a partial style. The rules are ordered from the most specific to the least one. The resolution of an element style is done by applying the rules matching the element (in order), then inheriting a part of its parents style (recursively), then completing it by the default style. 

# Widgets

The widgets are graphical elements on which a style can be applied.

The framework contains a set of predefined widgets: label, image, button, toggle, radio, check, switch, text, slider, scrollbar, progress bar.

It is also possible to create its own widgets by subclassing StyledWidget.

# Containers

The containers are graphical elements on which a style can be applied and that can contain other elements (widgets or containers). Each container defines a policy to lay out its children.

The framework contains a set of predefined layout policies: canvas, dock, grid, list, scroll, split.

It is also possible to create its own layout policies by subclassing StyledComposite.

# Animation

The animation framework provides an animator that can schedule several animations at the same framerate.

# Navigation

The navigation framework provides the capability to navigate from one page to another and going back to pages history.

The pages are composed of widgets and containers. A page is represented by a URL.

A URL resolver is responsible for creating the pages from a URL.

A pages stack manages the history of pages. It can either keep the pages in cache or create it again while going back to history.

The navigation desktop associates a URL resolver and a pages stack to navigate between the pages. It may also animate the transition between the pages.

# Color

The color utilities provide some convenient functions to manipulate the colors.

The color helper manipulates (decompose, recompose) the color components red, green, blue.

The light helper computes and modifies the level of light in a color.

# Usage

Add the following line to your `module.ivy`:
	
    <dependency org="ej.library.ui" name="widget" rev="2.4.2"/>
	
# Requirements

This library requires the following Foundation Libraries:

    BON-1.3, EDC-1.2, MICROUI-2.0

# Dependencies

_All dependencies are retrieved transitively by MicroEJ Module Manager_.

# Source

N/A

# Restrictions

None.

---    
_Copyright 2016-2019 MicroEJ Corp. All rights reserved._  
_This library is provided in source code for use, modification and test, subject to license terms._  
_Any modification of the source code will break MicroEJ Corp. warranties on the whole library._  

How-to generate fonts using FontForge

This document explains how to use Fontforge to generate a MicroEJ Font.
HOWTO for UI
Supported MicroEJ Version: 5.x
Supported MicroEJ Edition: Studio & SDK
Last updated:
3 December 2019
+
.. Copyright 2019 MicroEJ Corp. All rights reserved.
.. Use of this source code is governed by a BSD-style license that can be found with this software.

Overview
========

This document explains how to use Fontforge to generate a MicroEJ Font.

Requirements
============

This how-to has been tested on

-  MicroEJ Studio or SDK 5.1
-  Python (3.8.0) with Pillow module (6.2.1)
-  FontForge (FontForge-2019-08-01 64-bit)
   -  if you have a 64-bit OS, install a 64-bit font forge
-  Windows 10

Usage
=====

Install the dependencies
------------------------

1. Download and Install Python and Pillow: `how
   to <https://pillow.readthedocs.io/en/3.0.x/index.html>`__
2. Download and install FontForge:
   `website <https://fontforge.github.io>`__
3. Add ffpython, available in `[Fontforge installation directory]/bin`,
   to the system path

Usage
-----

Generate the images
~~~~~~~~~~~~~~~~~~~

Use a command line to execute fontConverter:

::

   python fontConverter fontFilePath sizeInPixel [startRange endRange [bpp [algorithm]]
                   fontFilePath: the path to the font file
                   sizeInPixel: the size in pixel to use for the output (c.f. algorithm)
                   startRange: (default = 0x21) hexadecimal value of the first unicode character to export
                   endRange: (default = 0x24F)  hexadecimal value of the last unicode character last character to export, it is recommanded to export a wide range
                   bpp: (default = 8) the bpp to use for the export
                   algorithm: (default = 0) the algorithm to use :
                           0: bodyHeight => The sizeInPixel define the height of `Xg` (the generated image height will be the biggest height required to print all the character in range)
                           1: capitalHeight => The sizeInPixel define the size of a capital `X` (the generated image height will be the biggest height required to print all the character in range)
                           2: emHeight => The sizeInPixel define the size of an em (the generated image height will be the biggest height required to print all the character in range)
                           3: bestFit => The sizeInPixel define the size of the final output (the size of the font used will be the biggest possible to fit all the characters within the sizeInPixel)

The output should looks like:

::

   Generating images
   Mapping em font size to 14px
   Resizing images to 15px
   Generating EJF
   EJF file can be found at [PATH]\NotoSerif-Regular_capitalHeight_10px.ejf

Algorithm
~~~~~~~~~

-  **bodyHeight** will use the height of ``Xg`` (the generated image
   height will be the biggest height required to print all the character
   in range). In case of increase of the characters range, the size of
   the printed characters will be the same, but the size of the EJF file
   may be different.
-  **capitalHeight** will use the height of a capital ``X`` (the
   generated image height will be the biggest height required to print
   all the character in range). In case of increase of the characters
   range, the size of the printed characters will be the same, but the
   size of the EJF file may be different.
-  **emHeight** will use the height of an em (the generated image height
   will be the biggest height required to print all the character in
   range). In case of increase of the characters range, the size of the
   printed characters will be the same, but the size of the EJF file may
   be different.
-  **bestFit** will use the height of the final output (the size of the
   font used will be the biggest possible to fit all the characters
   within the sizeInPixel). In case of increase of the characters range,
   the size of the printed characters may vary, but the size of the EJF
   file will stay the same.

Import the images into an EJF
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

In MicroEJ SDK:

1. Import the MicroEJ font
2. Adapt the base line to Map your font's base line

Troubleshooting
===============

DLL load failed
---------------

When using a 64-bit Windows and a 32-bit version of FontForge,
the script fails to load some DLL. Using a 64-bit version should
fix the use. `Font forge 64-bit portable <https://sourceforge.net/projects/fontforgebuilds/files/x86_64/Portable/>`__

NLS Usage Example

This example shows how to print a localized string on a display.
EXAMPLE for UI
Supported MicroEJ Version: 5.x
Supported MicroEJ Edition: SDK
Last updated:
3 December 2019
+
# Overview

This example shows how to print a localized string on a display.

- [resource/nls](src/main/resources/nls) contains the `[prefix]_language.po` files with the the translation.
   `.po` files standard can be found at [gnu.org](https://www.gnu.org/software/gettext/manual/html_node/PO-Files.html) 

- [examples.nls.list](src/main/resources/com/microej/example/nls/helloworld/examples.nls.list) describes the generated class to use to get message.

# Usage

## Run on MicroEJ Simulator

1. Right-click on the project
2. Select **Run as -> MicroEJ Application**
3. Select your platform 
4. Press **Ok**

## Run on device

### Build

1. Right-click on the project
2. Select **Run as -> Run Configuration** 
3. Click on **New**
4. Select **Execute on Device**
5. Select **Build & Deploy**
6. Go to **Execution** tab
    * Select your platform 
7. Press **Apply**
8. Press **Run**
9. Copy the generated `.out` file path

### Flash

1. Use the appropriate MicroEJ tool.

# Requirements

This example has been tested on:

* MicroEJ SDK 5.1
* With a platform that contains:
    * EDC-1.2
    * BON-1.3
    * MICROUI-2.0

## Dependencies

_All dependencies are retrieved transitively by Ivy resolver_.

# Source

N/A

# Restrictions

None.


---
_Copyright 2016-2019 MicroEJ Corp. All rights reserved._  
_Use of this source code is governed by a BSD-style license that can be found with this software._  
_MicroEJ Corp. PROPRIETARY. Use is subject to license terms._  

How-to use the MicroUI Library

This library contains simple examples to understand how to use the main MicroUI library APIs.
HOWTO for UI
Supported MicroEJ Version: 5.x
Supported MicroEJ Edition: SDK
Last updated:
29 November 2019
+
.. Copyright 2019 MicroEJ Corp. All rights reserved.
.. Use of this source code is governed by a BSD-style license that can be found with this software.

Overview
========

This library contains simple examples to understand how to use the main
MicroUI library APIs. It is recommended to study them in the following
order :

-  `com.microej.howto.microui.drawing.Primitives </MicroUI-Get-Started/src/
   main/java/com/microej/howto/microui/drawing/Primitives.java>`__

.. figure:: screenshots/Primitives.png
   :alt: Primitives

   Primitives

-  `com.microej.howto.microui.drawing.PrimitivesAntiAliased
   </MicroUI-Get-Started/src/main/java/com/microej/howto/microui/drawing/PrimitivesAntiAliased.java>`__

.. figure:: screenshots/PrimitivesAntiAliased.png
   :alt: PrimitivesAntiAliased

   PrimitivesAntiAliased

-  `com.microej.howto.microui.font.Text
   </MicroUI-Get-Started/src/main/java/com/microej/howto/microui/font/Text.java>`__

.. figure:: screenshots/Text.png
   :alt: Text

   Text

-  `com.microej.howto.microui.font.PictosWithCustomFont
   </MicroUI-Get-Started/src/main/java/com/microej/howto/microui/font/PictosWithCustomFont.java>`__

.. figure:: screenshots/PictosWithCustomFont.png
   :alt: PictosWithCustomFont

   PictosWithCustomFont

-  `com.microej.howto.microui.image.TransparentImages
   </MicroUI-Get-Started/src/main/java/com/microej/howto/microui/image/TransparentImages.java>`__

.. figure:: screenshots/TransparentImages.png
   :alt: TransparentImages

   TransparentImages

-  `com.microej.howto.microui.image.FlippedImages
   </MicroUI-Get-Started/src/main/java/com/microej/howto/microui/image/FlippedImages.java>`__

.. figure:: screenshots/FlippedImages.png
   :alt: FlippedImages

   FlippedImages

-  `com.microej.howto.microui.image.RotatedImages
   </MicroUI-Get-Started/src/main/java/com/microej/howto/microui/image/RotatedImages.java>`__

.. figure:: screenshots/RotatedImages.png
   :alt: RotatedImages

   RotatedImages

-  `com.microej.howto.microui.image.ScaledImages
   </MicroUI-Get-Started/src/main/java/com/microej/howto/microui/image/ScaledImages.java>`__

.. figure:: screenshots/ScaledImages.png
   :alt: ScaledImages

   ScaledImages

-  `com.microej.howto.microui.image.TilingWithImages
   </MicroUI-Get-Started/src/main/java/com/microej/howto/microui/image/TilingWithImages.java>`__

.. figure:: screenshots/TilingWithImages.png
   :alt: TilingWithImages

   TilingWithImages

-  `com.microej.howto.microui.image.DeformedImages
   </MicroUI-Get-Started/src/main/java/com/microej/howto/microui/image/DeformedImages.java>`__

.. figure:: screenshots/DeformedImages.png
   :alt: DeformedImages

   DeformedImages

-  `com.microej.howto.microui.events.InputEvents
   </MicroUI-Get-Started/src/main/java/com/microej/howto/microui/events/InputEvents.java>`__

.. figure:: screenshots/InputEvents.png
   :alt: InputEvents

   InputEvents

-  `com.microej.howto.microui.animation.AnimationSampleWithFullRepaint
   </MicroUI-Get-Started/src/main/java/com/microej/howto/microui/animation/AnimationSampleWithFullRepaint.java>`__

Note that the same set of resources (images and fonts) is used across
all of the examples.

Usage
=====

For each example:

## Run on MicroEJ Simulator
---------------------------

1. Right Click on the example to run ``.java`` file
2. Select **Run as -> MicroEJ Application**
3. Select your platform 4. Press **Ok**

Run on device
-------------

Build
~~~~~

1. Right Click on the example to build ``.java`` file
2. Select **Run as -> Run Configuration**
3. Select **MicroEJ Application** configuration kind
4. Click on **New launch configuration** icon
5. In **Execution** tab

   1. In **Target** frame, in **Platform** field, select a relevant
      platform (but not a virtual device)
   2. In **Execution** frame

      1. Select **Execute on Device**
      2. In **Settings** field, select **Build & Deploy**

6. Press **Apply**
7. Press **Run**
8. Copy the generated ``.out`` file path

Requirements
============

This example has been tested on:

-  MicroEJ SDK 5.1
-  With a Platform that contains:

   -  EDC-1.2
   -  BON-1.2
   -  MiCROUI-2.0

Dependencies
============

*All dependencies are retrieved transitively by Ivy resolver*.

Credits
=======

+------------------+-------------------------------+------------------+
| Font             | Author                        |License           |
+------------------+-------------------------------+------------------+
| Font Awesome     | Dave Gandy                    | `SIL OFL 1.1     |
|                  | http://fontawseome.io         | license -        |
|                  |                               | http://scripts.s |
|                  |                               | il.org/OFL </Mic |
|                  |                               | roUI-Get-Started |
|                  |                               | /src/main/resour |
|                  |                               | ces/fonts/OFL.tx |
|                  |                               | t>`__            |
+------------------+-------------------------------+------------------+
| Sans             | Adobe                         | `SIL Open Font   |
|                  |                               | License.txt </Mi |
|                  |                               | croUI-Get-Starte |
|                  |                               | d/src/main/resou |
|                  |                               | rces/fonts/Adobe |
|                  |                               | -Source-SIL-Open |
|                  |                               | -Font-License.tx |
|                  |                               | t>`__            |
+------------------+-------------------------------+------------------+

Source
======

N/A

Restrictions
============

None.

How-to use the Widget Library

This library contains simple examples to understand how to use the main Widgets library APIs.
HOWTO for UI
Supported MicroEJ Version: 5.x
Supported MicroEJ Edition: SDK
Last updated:
29 November 2019
+
.. Copyright 2019 MicroEJ Corp. All rights reserved.
.. Use of this source code is governed by a BSD-style license that can be found with this software.

Overview
========

This library contains simple examples to understand how to use the main
Widgets library APIs. It is recommended to study them in the following
order :

-  `com.microej.howto.mwt.colors.Gradient <src/main/java/
   com/microej/howto/mwt/colors/Gradient.java>`__

.. figure:: screenshots/Gradient.png
   :alt: Gradient

Usage
=====

For each example:

Run on MicroEJ Simulator
------------------------

1. Right Click on the example to run ``.java`` file
2. Select **Run as -> MicroEJ Application**
3. Select your platform
4. Press **Ok**

Run on device
-------------

Build
~~~~~

1. Right Click on the example to build ``.java`` file
2. Select **Run as -> Run Configuration**
3. Select **MicroEJ Application** configuration kind
4. Click on **New launch configuration** icon
5. In **Execution** tab

   1. In **Target** frame, in **Platform** field, select a relevant
      platform (but not a virtual device)
   2. In **Execution** frame

      1. Select **Execute on Device**
      2. In **Settings** field, select **Build & Deploy**

6. Press **Apply**
7. Press **Run**
8. Copy the generated ``.out`` file path

Requirements
============

This example has been tested on:

-  MicroEJ SDK 5.1
-  With a ST STM32F746G-DISCO (480x272 display) board platform that contains:

   -  EDC-1.2
   -  BON-1.3
   -  MICROUI-2.2

Dependencies
============

*All dependencies are retrieved transitively by Ivy resolver*.

Source
======

N/A

Restrictions
============

None.