Panel Design Principles

In the µPanel architecture, the graphical panel is not stored in the APP that runs on the mobile device, but it is completely defined and sent by the micro-controller connected to the WiFi Module. The panel definition is based on a super compact line of text, that carries not only the definition of the panel’s elements but also the layout. Thanks to this architecture, every micro-controller can easily send to the µPanel the description of the required layout and objects, using a very limited amount of memory. In addition, the micro-controller can even change the panel during the run-time simply by sending a new string. Imagine a panel that dynamically changes implementing a multi page graphical menu or application… isn’t it cool? Let’s examine the design principles!

The Panel can be designed organising its content in tables and sub-tables of arbitrary dimensions. The Panel structure is very similar to that of a web page! As you probably know very well, the HTML combined with style sheets CSS is a very powerful language, that permits to create complex and nice layouts. Unfortunately, the HTML also requires a lot of tags and characters, that would consume a lot of micro-controller memory. Don’t worry! µPanel uses a special language that has been specifically conceived for this application by the µPanel engineers. This language is named HCTML (Hyper Compressed Text Markup Language) and permits to codify many equivalent HTML elements with a single character or so. You are not familiar with HTML and web programming? Don’t worry! The HCTML is so intuitive that there is no need to know any programming language to design the panel. Just describe what you need on your panel and the HCTML will do the rest for you.

The Online Panel Simulator will help you to test the panel during its design.

 

In the HCTML, there are 6 kinds of entities:

Constructors

Constructors

Constructors are characters that define the panel layout. The current supported constructors are:

  • { }
  • _
  • |

The curly brackets define a container that can be used to contain panel elements or other constructors. Actually, you can think of this container as a (HTML) table. The table starts at the opening bracket and ends at the closing bracket. The horizontal line (underscore) defines either the first or the next table lines, while the vertical line (pipe) defines either the first or the next columns. Please note that: a) an opening bracket has to have the corresponding closing bracket; b) each row has to have the same number of columns.

Example
Create a container for containing objects (or sub-containers) arranged on a 2×2 table:
{ some content | some content _ some content | some content }

Please note that in the previous example the symbols for the first row (_) and the first column (|) have been avoided since the system automatically inserts them as soon as some content (objects or sub-container) is inserted into the container. The same 2×2 table can be obtained specifying also those two symbols if you wish, as follow:

{_| some content | some content _ some content | some content }

You will find out later that the first row and column symbols are necessary when you need to modify the styles or events of the first row or column.

Stylers

Styler

Stylers are sequences of one or more lower-case characters that specify graphical appearance of containers or objects. Usually, each styler defines or changes single graphical characteristics. Each styler corresponds to one or more style definition of HTML. Some stylers take effect only on the container in which they are used, others in all the contained objects and sub-containers. Stylers that take effect only on a single container or object are classified and marked as spot styler, the others as block styler.

One of the most important graphical parameters that we have to get acquainted with is represented by the size. µPanel scales all the containers with respect to the horizontal size of their parent container. For the first container, the horizontal size of the whole display is used. All sizes are specified in percentage. The size of objects is usually scaled with respect to the whole display horizontal size by using a user defined scale factor that takes effect on the current container and in all its sub-containers (block styler).

Please note that, unless specifically requested, also the vertical size of objects and containers is scaled with respect to the horizontal size of containers. Therefore, a container with size of 50% x 50% will appear square on every display and will cover the 50% of the horizontal space.

To apply a styler to an object please refer to the general object syntax.

To apply a styler to a constructor simply use the styler after the constructor’s symbol. In this case, please note the difference between the following cases (in which a table with a single cell is created):

  • {styler content} The styler takes effect on the constructor symbol on its left, which means on the whole container table
  • {_styler content} The styler takes effect on the constructor symbol on its left, which means on the whole table row
  • {_|styler content} The styler takes effect on the constructor symbol on its left, which means on the table cell

The following table reports the list of currently available stylers (to make the description clearer, for each styler one or more examples are reported. These examples can be tried in the online simulator. Some examples make use of the text object. Text can be added to the panel using the syntax: T:some text;)

Short description table

Styler Mnemonic Type SHORT Description
% Size Spot Define size and scale of either the container or the container-like object see details
* Object Size Block Define the size of the object that contains the styler, or of all the objects and sub-container. see details
! Background
color
Spot Define the background colour to be used in the container or for drawing the related object see details
# Color Block Define the colour to be used in the container, in all objects of the container and in all sub-containers see details
t Top Block Vertically align objects or sub-containers at the top of the container see details
b Bottom Block Vertically align objects or sub-containers at the bottom of the container see details
m Middle Block Vertically align objects or sub-containers in the middle of the container. see details
< Left Block Horizontally align objects or sub-containers at the left side of the container see details
^ Center Block Horizontally align objects or sub-containers in the center of the container. see details
> Right Block Horizontally align objects or sub-containers at the right side of the container. see details
w Window (overflow) Block Prevent the appearance of the scroll bars in the case the panel size exceeds the display area. see details
Border Spot Define the border to be used for the current container or object. see details
f Font Block Define the font to be used in the current container or object and in all the sub-containers. see details
r Radius Spot Define the radius for drawing objects in the current container or object. see details
p Padding Spot Define the distance between border (container boundaries) and content for drawing objects in the current container or object. see details
d Displacement Spot Displace the current container or object with respect to its expected position see details
o Opacity Spot Define the opacity of the container or object. see details
a Angle (rotation) Spot Define the rotation of the container or object. see details
g Background image Spot Define the image to be used for the container background or object. see details
h Shadow Spot Display either the container’s shadow or the object’s shadow. see details
n Line height Spot Define the text line height. see details
k Display Spot Define the display type for the current container or object. see details
w Window
(overflow)
Spot Hide the scroll-bars that will appear when the content is bigger than the container. see details
@ At
(Absolute position)
Spot Manually set the position of either the container or the object on the display. see details
z z-index Spot Set the z-index of either the container or the object. Elements with higher z-index will appear in front of elements with lower z-index. see details
s Styler Class Load Spot Recall a previously stored styler class. This styler permits to load a styler class, which has to be previously saved, and to apply it to multiple containers or objects. see details
~ global ID Spot This styler tags a panel’s element (object or constructor) with a number called global ID. The global ID permits to refer to the tagged object/constructor during the panel usage (run time). Please note that the global ID is not the object ID, and that objects can have global ID as well (in addition to their object ID) see details

Full description table

Styler Mnemonic Type Description
% Size Spot Define size and scale of either the container or the container-like objects

The syntax is %x,py,a,b where x and y are the percentages of the horizontal and vertical size, respectively. a and b are optional parameters that represent the scale factor, for x and y respectively. Negative scale factors can be used to obtain a mirror effect on the corresponding axis. p is an optional flag that precedes y.

The only valid option for p: y
and used to scale the size with respect to the container height instead of the container width.

The last styler parameters can be omitted, so all the following stylers are valid:

%x,y
%x
%,y
%,,a,b
%,,,b

Examples

Create a container with size 80% x 40%:

{%80,40}

Create a container with size 80% x 40% with y-mirrored content:

{%80,40,,-1}

Create a container that cover the whole display area:

{%100,y100}

* Object Size Block Define the size of the object that contains the styler, or of all the objects and sub-container.

The syntax is *x where x is the size factor, multiplied by 10, to be applied to the object size. The initial objects’ size is automatically scaled with respect to the display width.

Please note that, x = 10 will not change the object size; x = 20 will double the object size with respect the the current size, and so on…
Please note also that the scale factor is a block styler and it is thus applied on the current object or all the object of the container and sub-containers.

A particular function is obtained if x is . (dot). In this case the object size is reset to the default value proportional to the parent container size. This function is useful when objects with size proportional to the container are required.

Due to the block nature of this styler, it is possible to scale the object size of all the panel’s object simply prefixing the panel definition with the * styler.

Example

Create a container with two texts of double size

*20{T:A;_T:B;}

! Background
color
Spot Define the background colour to be used in the container or for drawing the related object.

The basic syntax is !abc where a,b and c are 3 hexadecimal digits representing the R G B components of the colour. This syntax corresponds to the classic short HTML representation of colours (3 digits). It is also possible to create colour gradients specifying two colours with the following extended syntax: !abc,def where def represents the second colour

Examples

Create a container of size 80% x40% with background color gradient from white to blue

{%80,40!FFF,00F}

Create a container with background color blue, with a single cell of background color red containing the text “OK”;

{!00F|!F00T:OK;}

# Color Block Define the colour to be used in the container, in all objects of the container and in all sub-containers.

The syntax is #abc where a,b and c are 3 hexadecimal digits representing the R G B components of the colour. This syntax corresponds to the classic short HTML representation of colours (3 digits).

Example

Create a container with colour red and text OK

{#F00T:OK;}

t Top Block Vertically align objects or sub-containers at the top of the container.

The syntax is t

Example

Create a container of size 50% x 50%, border, vertical align top and text OK

{-%50,50tT:OK;}

b Bottom Block Vertically align objects or sub-containers at the bottom of the container.

The syntax is b

Example

Create a container of size 50% x 50%, border, vertical align top and text OK

{-%50,50bT:OK;}

m Middle Block Vertically align objects or sub-containers in the middle of the container.

The syntax is m

Example

Create a container of size 50% x 50%, border, middle align and text OK

{-%50,50mT:OK;}

< Left Block Horizontally align objects or sub-containers at the left side of the container.

The syntax is <

Example

Create a container of size 50% x 50%, border, left align and text OK

{%50,50<-T:OK;}

^ Center Block Horizontally align objects or sub-containers in the center of the container.

The syntax is ^

Example

Create a container of size 50% x 50%, border, center align and text OK

{%50,50-^T:OK;}

> Right Block Horizontally align objects or sub-containers at the right side of the container.

The syntax is >

Example

Create a container of size 50% x 50%, right align and text OK

{%50,50->T:OK;}

w Window (overflow) Block Prevent the appearance of the scroll bars in the case the panel size exceeds the display area. This styler is normally used to style the desktop (panel first container). Please refer to the Desktop object to know more about it.

The syntax is w (the use of stylers in the Desktop object is Dstylers;)

Example

create a blue table of 50% x 1000% preventing the appearance of scroll bars

Dw;{%50,1000!00F}

Border Spot Define the border to be used for the current container or object.

The syntax is -xxxxN where xxxx are one or more style options and N is the border width (in pixels scaled with respect to the display width).

The current supported style options are: d (dotted), h (dashed), s (solid), b (double), g (groove), c (collapse), e (separate). The default style is solid.

In addition to these standard flags, two special flags j and k can be used to enable and disable, respectively, the border of all the elements during the development of the layout. Knowing exactly the size of the different containers and object may be of great help during the panel design.

A special meaning is assigned to N = 0: border and margins are cleared so that the object or container can use 100% of the available area

Examples

1. Create a container with size 50% x 50% and dashed border line of width 5 scaled pixels

{%50,50-h5}

2. Create a flag with text taking advantage of the zero border -0

{{-0%10,6|!0F0|!FFF|!F00}|T:Made in Italy;}

f Font Block Define the font to be used in the current container or object and in all the sub-containers.

The syntax is fxxx where xxxx are one or more style options.

The current supported style options are: b (bold), i (italic), a (arial), c (courier), n (disable font).

Example

Create a container with bold-italic-arial font and the text OK

{fbiT:OK;}

r Radius Spot Define the radius for drawing objects in the current container or object. Currently, this styler takes effect only on the border.

The syntax is rN where N is the radius in scaled pixels

Example

Create a container 50% x 50% with solid border with radius 50 eq. pixels

{%50,50-1r50}

p Padding Spot Define the distance between border (container boundaries) and content for drawing objects in the current container or object.

The syntax is pN where N is the distance in scaled pixels

Example

Create a container with border, the text OK and padding 20 eq pixels

{p20-T:OK;}

d Displacement Spot Displace the current container or object with respect to its expected position

The syntax is dx,y where x and y are respectively the horizontal and vertical displacements scaled with respect to the horizontal display size.

Example

Create two containers, white and blue, of size 50% x 50% overlapping them almost completely

{%50,50!FFF}{d10,-40%50,50!00F}

o Opacity Spot Define the opacity of the container or object.

The syntax is oN where N is the opacity in percentage. Opacity of 100 means full opacity (not transparent). Opacity of 0 means full transparent.

Example

Create two containers, white and blue, of size 50% x 50% overlapping them almost completely and making the blue one transparent (opacity 70%)

{%50,50!FFF}{o70d10,-40%50,50!00F}

a Angle (rotation) Spot Define the rotation of the container or object.

The syntax is aN,x,y where N is the rotation angle in degrees (clockwise), x and y represent respectively the horizontal and vertical position of the rotation centre in percentage of the object size (e.g. to rotate an object by 90 degrees around its right top corner: a90,100,0)

X and Y are optional and if not specified their values will be assigned to 50 (i.e. the object is rotated around its centre)

Example

Create two nested centered containers of size 50% x 50%, white and blue with the nested one rotated by 45 degrees (around its centre)

{%50,50!FFF^{a45%50,50!00F}}

g Background image Spot Define the image to be used for the container background or object

The syntax is gxxxN where xxxx are styler otions and N is the number of the picture to be used. Please refer to the list of pictures.

The available options are: n (do not repeat the image if the area to cover is larger than the picture. If this happens the image will be enlarged to cover the whole area)

Example

Create a containers of size 50% x 50% and cover the background with the image number 1

{%50,50g1}

h Shadow Spot Display either the container’s shadow or the object’s shadow.

The syntax is hxN,CCC,M where x is one char option, N represents the position of the shadow in pixels, CCC the shadow 12-bit color represented with 3 hexadecimal digits, M the blur distance.

The available shadow options are: t

The t options applies the shadow to the text instead of the container.

Example

Create a square blue container with faint defined white shadow:

{%50,50!00Fh5,FFF,30}

n Line height Spot Define the text line height.

The syntax is nN where N represents the line-height with respect the font-size. N = 10 corresponds to a line height equals to the font-size.

Example

Create a box with the text “Hello World” over 2 lines whose height is 2 times the font height

{-%1n20T:Hello World;}

k Display Spot Define the display type for the current container or object. Currently this styler set the display type to block. This styler can be used for instance to make text objects as block.

The syntax is k

Example

Create a block of text with size 80% blue background, rotated by 15 degrees

Tka15,0%80!00F:Hello World!;

@ At
(Absolute position)
Spot Manually set the position of either the container or the object on the display.

The syntax is @x,py where x and y are the horizontal and vertical position to be assigned to the container or object, and p is one char option. Please note that, by default, both the coordinates are scaled with respect to the display width and are given in percentage.

The available option are: y

The y option asks to scale the vertical position with respect to the display height instead of the display width.

Example

Display a X at the display centre

{@50,y50T:X;} Please note the y option before the height coordinate.

z z-index Spot Set the z-index of either the container or the object. Elements with higher z-index will appear in front of elements with lower z-index. This styler is useful when some elements overlaps as a consequence of the displacement styler (d) of absolute positioning styler (@). By default, each element has z-index of 0. Positive and negative indexes can be used. The maximum allowed value is 999.

Example

Overlap two boxes at the centre of the display, making the red one in front of the blue one.

{z1@40,y40%20,20!F00}{@50,y50%20,20!00F}

s Styler Class Load Spot Recall a previously stored styler class. This styler permits to load a styler class, which has to be previously saved, and to apply it to multiple containers or objects. Styler class can be saved using the virtual S object. Please refer to the object table to know more about this virtual object.

The syntax is: sn where n is the number of saved styler class to be loaded.

Example

Define a styler class with blue background, rounded solid border, yellow color, white box shadow, padding, big fonts, and apply it to 3 text boxes.

S1*20r20-!00F#FF0p15h3,FFF,5;/Ts1:1;Ts1:2;Ts1:3;

~ Global ID assignment Spot This styler assigns a decimal number, called Global ID, to objects or containers. The global ID permits to identify a panel element (object/container) during the run time.

The syntax is: ~n where n is the global ID number, which can be any decimal value (integer).

Example

Define a container with size 50% x 50%, background color white and assign to it the Global ID number 31

{~31%50,50!FFF}

Styler Classes

Styler Classes are virtual objects that can be used to save a set of stylers to be used with other objects or container. All the stylers defined in this object are stored and can be recalled with the s styler. The syntax is:

S ID stylers ;
Events

Events

Events are sequences of lower-case characters that specify how the system has to react when the user interacts with the container or object. Some objects, as buttons and switches, have their own default events already defined. The user, however, can add events to other panel elements. As an example, the designer can add a click event on a LED, a picture, or a container as well. When the user generates a touch (click), the µPanel will send the corresponding event to the WiFi module to be eventually delivered to the controller. The syntax of Events is similar to that of Stylers.

When an event triggers, a message will be sent by the WiFi Module to the controller. The message has the following format:

#.EVT:N:C

Where N is the event number specified by the designer in the HCTML code and C is the code of the specific event.

Event Mnemonic Type Description
. Click / Touch Spot Enable the click event on the container or object. The event fires when the user click or touch the element.

The syntax is .xN where x is one or more option characters and N is the event number to be used. The event number will be sent to the controller when the event triggers.

The available options are: . (dot)

The option . (dot) enables the touch-down and touch-up events instead of click/touch

Event Codes

Click / Touch: 1
Mouse down / Touch down: 2
Mouse up / Touch up: 3

Example

Create a container with size 50% x 50%, blue color with click event (number 1)

{%50,50!00F.1}

Example 2

Create a container with size 50% x 50%, blue color with touch-down and touch-up events (number 1)

{%50,50!00F..1}

Objects

Objects

Objects represent the actual content of the panel. There are two kinds of objects: 1) standard objects, which are the elements the user sees on the panel and interact with; 2) virtual objects, which are invisible elements used to implement some special functions.

Both standard and virtual objects meet the following general syntax, in which each object definition starts with its uppercase identifier and ends with a semicolon (;)

K [ID] [type] [stylers] [events] [: param 1 : param 2 …];

Where:

  • K: is 1 uppercase character that identifies the object kind
  • ID: is a character in the range 0-9 or A-Z (uppercase) that represents the object instance
  • type: is a sequence of 1 or more uppercase alphanumeric characters that specify a sub-type of the K object
  • stylers: is a sequence of 1 or more lowercase alphanumeric characters representing the style to be applied to the object
  • events: is a sequence of 1 or more lowercase alphanumeric characters representing the events to be assigned to the object
  • param: is a sequence of alphanumeric parameters (both lowercase and uppercase) requested by the object. Each parameter is prefixed by a colon symbol (:)
  • ; is the object’s terminator (mandatory)

Please note that, the fields contained in [ ] may be optional or not required for some kinds of objects.

The available standard objects are:

The available virtual objects are:

  • STYLER CLASSESS

Styler Classes are virtual objects that can be used to save a set of stylers to be used with other objects or container. All the stylers defined in this object are stored and can be recalled with the s styler. The syntax is:

S ID stylers ;

Example:
define a styler class (ID=1) with border, white background, red color, double font-size, and use it with a text object
Styler Class definition: S1-1h*20#F00!FFF;
Styler Class usage: Ts1:Hello;

Macros

Macros

Macros are HCTML elements whose code can be defined by the user. Macros work in two-steps: 1) definition 2) usage. Macros are useful to make the code compact when some complex elements are required many times in the panel definition.

Macro Definition

Macro can be defined using the following syntax:

K ID HCTML_CODE $
  • K: fixed uppercase character that represents the start of the macro definition
  • ID: one uppercase alphanumeric character in the range 0-9 or A-Z that identifies the macro
  • HCTML_CODE: any HCTML code to be replaced at the macro usage. Every character can be used with exception of the dollar symbol ($) that identifies the end of the macro.
  • $: symbol that ends the macro definition

The Macro’s HCTML_CODE can contain also parameters that can be specified dynamically during the macro usage. To include parameters into a specific point of the code, simply insert a question mark symbol (?)

Example

Create a macro (ID=1) of a user defined button (blue gradient-style background, rounded borders, white color, width 30%) with button ID and text as macro’s parameters.

Macro definition: K1:B?!00F,88Fr20#FFF%30:?;$

The HCTML parser can also automatically assign progressive IDs to objects within the Macro. To use the auto ID simply insert a double question mark (??) immediately after the object to ID. However, please note that, the assignment will start from 0 and will increase by 1 at each macro usage. No mechanisms are implemented to prevent that such assigned ID will not be equal to IDs manually assigned to objects by the designer! Therefore, particular attention must be payed with auto ID.

Example

Create a macro (ID=2) of a user defined button (blue gradient-style background, rounded borders, white color, width 30%) with button ID automatically assigned and text as macro’s parameters.

Macro definition: K2:B??!00F,88Fr20#FFF%30:?;$

Macro can be nested (i.e. a macro definition can contain a macro usage)

Macro Usage

Macro can be used as follow:

J ID (Param 1,Param 2,Param 3)
  • J: fixed uppercase character that represents the macro usage
  • ID: one uppercase alphanumeric character in the range 0-9 or A-Z that identifies the macro to be used
  • Param: one or more comma-separated parameters required by the macro. Parameters must be enclosed between brackets ( ). If the macro does not require parameters, the brackets can be avoided.

Example

Create a macro (ID=3) of a user defined button (blue gradient-style background, rounded borders, white color, width 30%) with button ID automatically assigned and fixed text. Use the macro to create two face-to-face buttons

Macro definition: K3:B??!00F,88Fr20#FFF%30:Press;$
Macro usage: {J3|J3}

Example

Create a macro (ID=4) of a partial button definition (blue gradient-style background, rounded borders, white color, width 30%) with button ID automatically assigned and without text definition. Use the macro to create two face-to-face buttons with different texts.

Macro definition: K4:B??!00F,88Fr20#FFF%30$
Macro usage: {J4:Text1;|J4:Text2;}

Example

Create a macro (ID=1) of a green LED with ID automatically assigned and initial state as parameter. Use the macro to create a 4×4 matrix of LEDs, turning ON the ones of the last column.

Simplest solution (115 characters):

Macro definition: K1:L??G:?;$
Macro usage: /{|J1(0)|J1(0)|J1(0)|J1(1)_|J1(0)|J1(0)|J1(0)|J1(1)_|J1(0)|J1(0)|J1(0)|J1(1)_|J1(0)|J1(0)|J1(0)|J1(1)}

Using nested macro (51 characters):

Macro definitions: K1:L??G:?;$K2:_|J1(0)|J1(0)|J1(0)|J1(1)$
Macro usage: /{J2J2J2J2}

Shortest solution (43 characters):

Macro definitions: K1:|L??G:$K2:_J10;J10;J10;J11;$
Macro usage: /{J2J2J2J2}

Tags

Tags

Tags are symbols that represent simple HTML elements. Tags are used to slightly modify the Panel layout. The following table reports the available tags and describes their usage.

Tag Mnemonic Description
/ New Line
<BR>
Introduce a new line into the layout. The height of the new line corresponds to the current line-height. A different height can be specified.

The tag syntax is: /N where N is an optional number that specifies the height of the new line. N = 10 means a full line-height, N = 20 means a double line-height, and so on…

Example

Create two text messages, one under the other leaving a double line height between them

{^T:First Line;_|/20T:Second Line;}

= Horizontal Line
<HR>
Introduce a horizontal line into the layout.

The tag syntax is: =

Example

Create a list of text separated by horizontal lines

{^T:First;=T:Second;=T:Third;}

& Space
&nbsp;
Introduce a little space into the layout.

The tag syntax is: &

Example

Create two LEDs with a little space between them

{L1G0:0;&L2G0:0;}