Graphical User Interface Development with Eqela

(4) GRAPHICAL USER
INTERFACES

Graphical user interface
development with Eqela

General approach

Widgets

Reusable user interface elements or components

Provide one or both of the following:
− Draws something graphically on the screen
− Reacts to user input, such as mouse pointer events, touch
events, and/or keyboard events

Represent rectangular areas on the screen, the basic
parameters of which are the x/y coordinates, width and
height

Are by default transparent, and can thus represent any
kind of shape (not just rectangles)

General approach

Widget hierarchies

The way to combine widgets together to form a complete user
interface is through means of adding widgets as children of
other widgets.
Example:
Container widget
(dark gray box)
Text box
(search)
Button
(OK)
Button
(Cancel) Child widgets
Parent/root widget
User interface

General approach

Rendering model

Displaying the visual representation of the widget is
called rendering

The Eqela framework calls the render() method of the
root widget to draw a part (or all) of a screen

General approach

Input events

Pointer events for mouse-based devices
− “pointer-enter”, “pointer-leave”, “pointer-move”, etc.

Touch events for touch-based devices
− An event signifying that a press on the screen was started, the finger was
moved, released, etc.

Keyboard events for devices with a keyboard, and/or key
presses performed on a virtual on-screen keyboard

Incoming pointer/touch events will always be sent to the root
widget of the application.

For keyboard events, the focused widget will be the one to
automatically receive any keyboard events.

General approach

Application windows

In other GUI frameworks, there is
a concept of a “window” that is
used as the top level container for
UI elements.

In Eqela,there is no requirement of
a “window”, but all UI elements
are widgets.
− An Eqela GUI app, the main
application class is a widget.
− The main “window” is an instance of
a widget.

Common concepts

Colors

Represented by com.eqela.libgui.Color class

Color components: red, green, blue, and alpha

Represented as double precision floating point
numbers.

Eqela GUI framework does not make any
determination as to how many colors would be
available.
− No limitation by Eqela
− Limitations will come from the underlying platform and
hardware


Color information can be supplied to the framework in
two ways:
− As a string with a double-digit hex-coded value for each
component.
− Color components can also be supplied directly as four
double-precision floating point numbers.

Common ways:
var mycolor1 = Color.instance("#FF0000"); // construct a red color
var mycolor2 = Color.instance(null);
mycolor2.parse("#FF0000"); // equivalent to above
var mycolor3 = Color.instance_double(1.0, 0.0, 0.0, 1.0); // red also
var mycolor4 = Color.instance("#000000").set_r(1.0); // red
var str1 = mycolor1.to_string(); // returns "#FF0000FF"
var str2 = mycolor1.to_rgb_string(); // returns "#FF0000"

Common concepts

Fonts and text

General approach
− Eqela uses the system fonts through the native APIs, and
does not introduce any new fonts or font libraries in itself.
− Any font information supplied to Eqela will relate to the font
database of the underlying operating system or platform.

Font objects
− com.eqela.libgui.Font

Describes the name, size and style of the font to be used.
− Constructing a Font object can be done as follows:
var myfont = Font.instance("bold 10mm Arial"); // bold, 1cm high arial
var defaultfont = Font.instance(); // default font
var largefont = Font.instance("50mm"); // 5cm high default face


Font objects
− The components can be a combination of the following:

Size information (in “mm” or “px”)

Font face/family name (eg. “Arial”)

Font style (eg. “bold” or “italic”)
− The Font object instance is not the font itself, but a
description of it
− If the specific font is not available, then the closest match
will end up displayed

Text layouts
− Drawing of text is done through an assistance mechanism
referred to as a text layout.

Text is laid out first, and the layouts are then passed to the rendering
API


Text layouts
− To create a text layout, the for_properties() static method in
the com.eqela.libgui.TextLayout class must be used.
− Requires three parameters:

A com.eqela.libgui.TextProperties class instance

A com.eqela.libgui.Frame class instance

A DPI value
− Example of creating a simple text layout:
var layout = TextLayout.for_properties(TextProperties.instance()
.set_text("This is my text")
.set_font(Font.instance("10mm"))
.set_color(Color.instance("#FF0000")), get_frame(), get_dpi());

Common concepts

Images

General approach
− The Eqela framework does not requires for images to be of
any specific format
− Precise format support is platform dependent: All platforms
support at least PNG and JPG
− Eqela utilizes the functionalities offered by the underlying
platform for imaging support where possible.


Reading images from files
− Reading of an image from a file is done with the read_file()
method:
* As long as the file format is supported by the underlying platform, the
image object is returned and usable.

Icon resources
− An "icon" is thought to be a resource of an application, and can be
retrieved by a short name or id rather than by a full pathname.
− Icons can be retrieved from the underlying system through the use
of the for_resource() method of Image. The preferred method,
however, is to use IconCache:
var image = Image.for_file(File.for_eqela_path("/my/test.png"));
var image = Image.for_resource("arrow_up");
var img2 = IconCache.get(“arrow_up”);


Icon resources
− The exact storage location of an icon is very much platform
dependent. However, all image files placed in the source
code directory will be considered an icon resource.
− Example of a source code directory:
− The .png files above could be retrieve in the application as
follows:
Main.eq
SecondaryWidget.eq
TestWidget.eq
arrow_up.png
arrow_down.png
var up = IconCache.get("arrow_up");
var down = IconCache.get("arrow_down");


Resizing images
− To resize an image, use the resize() method of Image:
* This would make a new copy of the image "img", and resize it to 100x100 pixels.
Note that the original image is not modified.
var newimage = img.resize(100, 100);

Common concepts

Length, sizes and positions

Units and sizes
− The following units are accepted by Eqela as length/size
specifications:

“px” - pixels

"mm" - millimeters

"um" - micrometers

"nm" - nanometers

"in" - inches
Example:

"100px" - one hundred pixels

"10mm" - ten millimeters (which is one centimeter)

"1in" - one inch


Units and sizes
− It is a very strong recommendation to use physical sizes
when implementing the user interfaces of their applications.
− Use either inches, millimeters, nanometers or micrometers,
(instead of pixel values), to retain the look of the user
interface regardless of the density and type of the screen
used.

The Length class
− The support for the different units is practically made
available through the eq.gui.Length class.

This can be used to convert the different units into pixels.
Example:
var tenmm = Length.to_pixels("10mm", get_dpi());
var up = IconCache.get("arrow_up", tenmm, tenmm);


The px method
− The eq.gui.Widget offers a shortcut to convert the different
units into pixels
− Using the px() method:

Size types
− Commonly used size types available in the Eqela GUI API:
− com.eqela.libgui.Size, com.eqela.libgui.Position,
com.eqela.libgui.Rectangle
− These can be constructed as follows:
var tenmm = px("10mm");
var up = IconCache.get("arrow_up", tenmm, tenmm);
var size = Size.instance(100, 200); // width=100, height=200
var position = Position.instance(10, 20); // x=10, y=20
var rect = Rectangle.instance(10,20,100,200); // combination of the two

Developing widgets

Creating a new widget

To create a new widget, simply inherit either the
com.eqela.libwidget.Widget class or another class that
is derived from it.

A very basic widget can be created as follows:
* This is a full-featured widget, can be used as an application main class and added to
other widgets.
class MyWidget : Widget
{
}


A slightly more useful example is here:
− This widget is derived from
com.eqela.libwidget.LabelWidget.
class MyLabelWidget : LabelWidget
{
public MyLabelWidget() {
set_text("This is my text");
}
}

Developing widgets

Widget lifecycle
1. Constructed

An instance of the class is created and the constructor of
the class has been called
1. Initialized

The widget has been added to another widget that itself
has been added to a widget engine backend.
1. Started

The widget becomes visible on the screen.

Developing widgets

Drawing your widget

The render method
− To create a widget that draws itself, simply inherit the
com.eqela.libwidget.Widget class.
− Then override the render() method of the Widget.
* The override specifier is optional but recommended.
class MyRenderableWidget : Widget
{
public override Collection render() {
}
}


Example of rendering
class MyRenderableWidget : Widget
{
public Collection render() {
var v = LinkedList.create();
int sz = px("30mm");
v.add(new FillColorOperation().set_shape(RectangleShape
.create(0, 0, get_width(), get_height()))
.set_color(Color.instance("#FF0000")));
v.add(new FillColorOperation().set_shape(RectangleShape
.create(0, 0, sz, sz))
.set_color(Color.instance("#00FF00"))
.set_x((get_width() - sz) / 2).set_y((get_height() - sz)/2));
return(v);
}
}


Animation
− The AnimationListener interface can be implemented to react to changes in /
progression of animations.
− Animations are executed by various means: Eg. activate() method or
ChangerWidget, or many of the methods of Widget, eg. Resize(), move_resize(),
move(), set_scale(), set_rotation(), set_alpha(), set_align*()
− Consider the following example:
class Main : LayerWidget
{
String color;
MyWidget mw;
public void initialize() {
base.initialize();
mw = new MyWidget();
add(mw);
}
public void start() {
base.start();
move_resize_child(mw, 0, 0, 100, 100);
}
}

public class MyWidget : ChangerWidget, AnimationListener
{
Widget current;
Widget next;
String color;
public void nextcolor() {
if (color.equals(“#FF0000”)) {
color = "#00FF00";
}
else if ("#00FF00".equals(color)) {
color = "#FF0000";
}
next = CanvasWidget.for_color(Color.instance(color));
add_changer(next);
activate(next, true, this);
}
public void on_animation_listener_end() {
remove(current);
current = next;
nextcolor();
}
public void start() {
base.start();
color = "#FF0000";
nextcolor();
}
}
What does this program do?

Making widget layouts

Review on the basics

Widgets can be added as children of other widgets.
− Creates a widget tree

Each widget has a parent and can have multiple
children.

X position, y position, width, and height are inherent
attributes.
− Determines the location of the widget in relation to the parent.

Layout widgets are standard widgets
− Their purpose is not to draw themselves, but to position child
widgets in accordance to layout rules.


Sizing mechanism

Key concepts:
− The size of the widget is determined by its width and its
height.

It is the parent of the widget that will assign a size to each widget.
− The size request of a widget is determined by a width request
and a height request.

The actual size and the size request do not always match

It is legal for a widget to change its size request
dynamically based on a size it has been assigned.
− eg. A multiline label does this when its width has been set,
after which its height request gets recomputed based on the
flow of the text given the new width.


A widget can set its size request in the initialize()
method as follows:
* Always draw to the actual size that can be retrieved using get_width() and
get_height().
* Never assume that the size request has been granted.
class MyWidget : Widget
{
public override void initialize() {
set_size_request(px("40mm"), px("10mm"));
}
}


Layout widgets

com.eqela.libwidget.ContainerWidget
− Not to be used in actual layouts.
− It is a base class that is inherited by most of the layout
widgets in the Eqela GUI API.
− Handles the basic functionality

Add child widgets

Tracking and forwarding events to child widgets
− Not implemented in ContainerWidget is the virtual method
arrange_children()

To develop a layout widget would be to inherit the ContainerWidget,
then implement the arrange_children() method.

com.eqela.libwidget.LayerWidget
− Lays out all its child widgets on top of each other.
− Each child widgets have the same location and size as the
parent LayerWidget
Example:
class MyLayerWidget : LayerWidget
{
base.initialize();
add(LabelWidget.instance().set_text("First label")
.set_color(Color.instance("#FFFFFF")));
add(LabelWidget.instance().set_text("Second label")
}
}

Output:

com.eqela.libwidget.AlignWidget
− Offers a way to flexibly position a widget inside another
widget while also honoring the size requests of the child
widget
− Two extra attributes for alignment:

Horizontal: -1 (far left), 0 (middle), or 1 (far right)

Vertical: -1 (topmost), 0 (middle), or 1 (bottom)
Example:
class MyAlignWidget : AlignWidget
{
base.initialize();
add_align(-1, -1, LabelWidget.instance().set_text("First label")
add_align(1, 1, LabelWidget.instance().set_text("Second label")
}
}


Box widgets
• com.eqela.libwidget.HBoxWidget and
com.eqela.libwidget.VBoxWidget
• These are used to flow widgets dynamically either from top to
bottom (VBoxWidget) or left to right (HBoxWidget).
• The weight parameter:

Used to specify relative weight of widgets that share the same
container.

An integer (default to 0)

Example:
* The “Widget” widget does not draw anything, but because of the weight of 1, it will
be sized to fill all free space in the widget.
class MyVBoxWidget : VBoxWidget
{
base.initialize();
add_vbox(1, new Widget());
add(ButtonWidget.instance().set_text("Click me"));
}
}


Box widgets (both horizontal and vertical) can be mixed, which is
often the case, to create complete GUI layouts:
{
base.initialize();
var hbox = HBoxWidget.instance();
add(hbox);
hbox.add(ButtonWidget.instance().set_text("OK"));
hbox.add(ButtonWidget.instance().set_text("Cancel"));
add_vbox(1, new Widget());
add(ButtonWidget.instance().set_text("Click me"));
}
}

Other GUI features

Scrolling

The Eqela GUI API provides scrolling features through
one or all of:
− com.eqela.libscrollerwidget.ScrollerWidget

Provides scrolling in both directions
− com.eqela.libscrollerwidget.VScrollerWidget

Provides scrolling vertically
− com.eqela.libscrollerwidget.HScrollerWidget

Provides scrolling horizontally

Any widget can be added as a child of one of these
scroller widgets.
− Scroller widgets will always grant the requested size of the
child widget.


Scrolling

The methods of scrolling:
− Dragging the widget up,
down, left or right
− Using the mouse scroll
wheel
− Keyboard scrolling with
up/down keys
The ScrollerWidget

Other GUI features

Handling screen orientation changes

The Eqela API also provides a mechanism for any
widget to be aware of changes in its size class (large or
small) and orientation (landscape or portrait).

An application can know about an orientation / size
class change by overriding the
on_orientation_changed() method:
class MyOrientationWidget : Widget
{
public override void on_orientation_changed() {
// code for handling the change
}
}

●
Eqela live implements screen orientation change
Portrait Landscape


Handling screen orientation changes

Some convenience methods for handling and detecting
the change:
Methods Description
is_small()
is_large()
is_portrait()
is_landscape()
Using these methods, the widget can determine what its
new size and orientation are.
set_current_view()
initialize_view()
These methods provide a mechanism for reinitializing the
widget's user interface as a response to size or orientation
changes.

Example:
class MyOrientationWidget : Widget
{
public override void on_orientation_changed() {
base.on_orientation_changed();
if(is_small()) {
set_current_view("small");
}
else {
if(is_landscape()) {
set_current_view("large_landscape");
}
else {
set_current_view("large_portrait");
}
}
}
public override void initialize_view(String name) {
if("small".equals(name)) {
// add child widgets / do other UI initialization
}

else if("large_landscape".equals(name)) {
}
else if("large_portrait".equals(name)) {
}
}
}

Other GUI features

Handling URLs

com.eqela.libcommonwidget.URLButtonWidget
− Creates a GUI button that, when clicked, opens a URL
address.
Example:
{
public void initialize() {
base.initialize();
add(URLButtonWidget.for_url("http://www.eqela.com"));
}
}

Other GUI features

On-screen keyboards

Eqela also supports virtual, on-screen keyboard

On platforms where a virtual keyboard is needed, one
will automatically appear when a widget is focused that
requires text input.

Thank you

Graphical User Interface Development with Eqela

Recommended

Recommended

More Related Content

What's hot

What's hot (20)

Similar to Graphical User Interface Development with Eqela

Similar to Graphical User Interface Development with Eqela (20)

More from jobandesther

More from jobandesther (7)

Recently uploaded

Recently uploaded (20)

Graphical User Interface Development with Eqela