User Guide for EmTK Developer

This document contains instructions for setup development enviroment and develop ui application under X86 and ARM platform.

Table of content

System Requirement
Build procedure
Programming details

System Requirement

Red Hat 7.3 OR Red Hat 9.0

Build procedure

Preparing source environment

Copy SDK source sdk-<version>.tar.gz to home directory
Extract SDK source
- cd ~
- tar -xzvf sdk-<version>.tar.gz
Setting up environment (only required for PC first time install this package)
root permission is required for this operation:
1. cp ~/sdk-<version>/rfs-x86/etc/RGB.txt /etc/RGB.txt. (Default RGB mapping (RGB.txt) for system. Application may use other RGB mapping, if enviroment variable NANOGTK_RGB_FILE_TXT defined.)
2. mkdir -p /etc/emtk (optional needed if required to use font other than default font)

Build procedure for EmTK demo Application

demo applications for each EmTK widgets: ~/sdk-<version>/EmLinux/EmTK/demo/
to compile and run samples on desktop PC
- cd ~/sdk-<version>/EmLinux/EmTK/
- make clean
- make x86 demo
- cd ~/sdk-<version>/rfs-x86/root/
- ./run.sh emtk_demos/<demo> [arguments]
to compile and run samples for board
- on desktop PC
  - cd ~/sdk-<version>/EmLinux/EmTK/
  - make clean
  - make arm7 demo
- on board
  - set up system eviroment (refer to Running EmTK Application)
  - start nano-X only if it is not started
  - cd <application path>
  - ./<application> [arguments] &

Running EmTK Application

Create Run Script

Run script will run in following format: run.sh [-gb|-big5|-jis|-ks] {program_name arg1, arg2, ....}

Read Input Arguments: language=$1 (Get system locale to be used, i.e. gb, big5, etc) command=$@ (Get program_name arg1, arg2, ...)
Setup system enviroment variable NANOGTK_RGB_TXT_FILE - Path where RGB.txt located. (Optional, willing to use different RGB mapping) LD_LIBRARY_PATH - Path where all neccessary libraries located. (for example: emtk library, GDK library, etc.) FONT_PATH - Path where all fonts located (By default, FONT_PATH = /rom/fonts EMTK_ICON_PATH - Path where all image will be used by the application. If this enviroment variable not defined, developer need to provide full path/relative path. EMTK_CONFIG_DIR - Path where fonts.dir (information about user define fontset) and emtkrc (default rc file) located.
Set system locale if [ "xgbx" = "x${language}x" ]; then export LC_ALL=zh_CN.GB2312 elif [ "xbig5x" = "x${language}x" ]; then export LC_ALL=zh_TW.Big5 elif [ "xjisx" = "x${language}x" ]; then export LC_ALL=ja elif [ "xksx" = "x${language}x" ]; then export LC_ALL=ko else export LC_ALL=en_US fi
Run Microwin (Nano-X) ~/sdk-<version>/EmLinux/microwin/bin-[x86|arm7]/nano-X
Run Application ./${command}

Assume running on X86 Platform and application in ~/sdk-<version>/EmTKApp/bin-x86.

Running EmTK Application using given run script run.sh

copy application to (or make symbolic-link on) ~/sdk-<version>/rfs-x86/root
- cd ~/sdk-<version>/rfs-x86/root
- ln -s ../../EmTKApp/bin-x86/<application> .
run application
- cd ~/sdk-<version>/rfs-x86/root
- ./run.sh <application> &
stop application
- close microwindow window

Running EmTK Application manually

Setup system enviroment variable (See above)
Launch nano-X (Assume enviroment variables are setted)
- cd ~/sdk-<version>/EmLinux/microwin/bin-x86/
- ./nano-X -p &
Run application
- cd ~/sdk-<version>EmTK/App/bin-x86
- ./<application>
Stop application
- press Ctrl+c to quit application OR close microwindow.

  P.S. 
	Microwindow (Nano-X) require user execute itself MUST be the user who loginX-window. 
	Otherwise the following error will show up.

	Nano-X version 089Pre8
	Xlib: connection to ":0.0" refused by server
	Xlib: No protocol specified

	nano-X: Can't connect to X11 server
	Xlib: connection to ":0.0" refused by server
	Xlib: No protocol specified

	Cannot initialise screen

Programming details

EmTK

What is EmTK

EmTK consists of a set of static, pre-defined widgets running on Microwindow (nano-X) using GDK APIs
it is a light-weight UI toolkit for embedded system
it provides simple API for writing UI applications
it provides customized appearance/response on all widgets

Why use EmTK

applications which need to use standard widgets like button, list, text input, etc.
consistent look-and-feel across all UI applications
programmer may focus on programing logic rather than spending time on drawing or event handling.
less prone to error than using low-level APIs such as Nano-X or GDK.
increase productivity because of shorter development cycle

When to use GDK

plenty of premitive drawings or moving objects
require high response/performance
do not need widgets
ONLY experienced GDK application programmer is recommended

Writing EmTK applications

use emtk_init() to initialize EmTK
use emtk_root() to create toplevel window and initialize event filters
use emtk_run() to start EmTK main loop
use emtk_close() to quit EmTK main loop

Customized EmTK Window with EmTK LAF (Look And Feel) Library

EmTK Look And Feel library (LAF) provides routines for creating application window frames, dialog boxes and toolbars.
Enable applications have consistent appereance and easier to change style.

Screen shot:
- Window
- Dialog
- Toolbar

EmTK widget set

please refer to File List of EmTK API documentation

Using EmTK

widget focus
- when a widget has the focus, all the key events will be sent to this widget
- only one (1) widget in a window has focus at one time, while
- only one (1) window has the focus in the system
widget id
- an unique id is given when creating any EmTK widget
- id is required for manipulating a widget, such as add to window, changing text, etc.
- you may want to keep the id of several widgets until the application ends
- id with value of 0 means the widget is either destroyed or invalid
EmTK widgets cannot overlap each other when adding to a container

Use User Define Fontset

By default, EmTK application load 3 fontsets on startup (FONT1, FONT2, FONT3).
To use fonts with different style (i.e. different from those preload fonts FONT1, FONT2, FONT3).
Simply create file fonts.dir in /etc/emtk

Here is the steps to define different font(s):
If system enviroment variable EMTK_CONFIG_DIR NOT defined

change permission to root
cd /etc/emtk (if /etc/emtk not exist, type mkdir -p /etc/emtk)
create file fonts.dir using any file editor.
For detail about fonts.dir format, please refer to ~/sdk-<version>/rfs-x86/rom/fonts.dir

If system enviroment variable EMTK_CONFIG_DIR defined

cd <EMTK_CONFIG_DIR>
create file fonts.dir using any file editor.
For detail about fonts.dir format, please refer to ~/sdk-<version>/rfs-x86/rom/fonts.dir

P.S. For each system, user fontset may only define up to maximum of 16.
fonts.dir is a subset of <FONT_PATH>/fonts.dir

EmTKRC (Customize EmTK Application behaviour)

Default rc file emtkrc in <EMTK_CONFIG_DIR> OR /etc
If rc file exist, EmTK application will follow rule(s) defined

Sample EmTK rc file # EmTK button with default borderwidth = 0 class .button borderwidth=0 # EmTK Entry widget treat key 0xF802 as it's left key class .entry nav_left=0xF802 # EmTK Entry widget treat key 0xF803 as it's right key class .entry nav_right=0xF803 # EmTK Text widget treat key 0xF802 as it's left key class .text nav_left=0xF802 # EmTK Text widget treat key 0xF803 as it's right key class .text nav_right=0xF803 # EmTK Window with default background color #FF0000(RED) class .window background_color=#FF0000 # EmTK Window use image /root/flower.jpg as default background image class .window background_image=/root/flower.jpg # EmTK Window with default foreground color #00FF00 class .window foreground_color=#00FF00

Application may override window background color, background image and foreground color with EmTK APIs after EmTK window created.

Sample code (helloworld)

#include <stdio.h>
#include <stdlib.h>
#include <unistd.h>

#include "emtk.h"
#include "window.h"
#include "label.h"

#define WINDOW_X		0
#define WINDOW_Y		0
#define WINDOW_W		160
#define WINDOW_H		100
int main (int argc, char **argv)
{
	int window_id;
	int label_id;
		
	emtk_init (&s;argc, &s;argv);
	emtk_root (WINDOW_X, WINDOW_Y, WINDOW_W, WINDOW_H);
		
	window_id = emtk_window_new (WINDOW_X, WINDOW_Y, WINDOW_W, WINDOW_H);
		
	label_id = emtk_label_new (window_id, 20, 20, FONT1, FALSE, "Hello World!!!");
	emtk_window_add_object (window_id, label_id);
	emtk_window_show (window_id);

	emtk_run ();
	emtk_close ();
	exit (0);
}

Sample code (EmTK mix with GDK APIs)

#include <stdlib.h>
#include <time.h>
#include <math.h>
#include <string.h>
#include "nano-X.h"

#include "gdk/gdk.h"

#include "emtk.h"
#include "window.h"
#include "label.h"


#if (DEBUG == 1)
#define Dprintf             printf
#else
#define Dprintf(ignore...)
#endif

#ifndef PI
#define PI 3.14 // 3.14159265358979
#endif

#define WINDOW_X 0
#define WINDOW_Y 0
#define WINDOW_W 240
#define WINDOW_H 160

#define LABEL_X 30
#define LABEL_Y 140

#define CLOCK_CENTER_X 120
#define CLOCK_CENTER_Y 60
#define CLOCK_RADIUS   50
#define CLOCK_H_RADIUS 30
#define CLOCK_M_RADIUS 40
#define CLOCK_S_RADIUS 45


/*******************************************************************************
 * gdk_pixmap_new (NULL, width, height, 16);
 * gdk_pixmap_unref (pixmap);
 * gdk_draw_line (pixmap, gc, ...);
 * gdk_draw_rectangle (pixmap, gc, ...);
 * gdk_window_copy_area (drawable, gc, destx, desty, pixmap, srcx, srcy, srcw, srcy);
 ******************************************************************************/


/***********************************************************************
                            Internal data
 ***********************************************************************/
static int wid;
static int labelid=0;
static guint tid=0;


/***********************************************************************
                            Internal functions
 ***********************************************************************/
static gint gdkwin_draw (gpointer data)
{
	GdkWindow *gdkwin = (GdkWindow*)data;
	static GdkGC *fg_gc = NULL, *bg_gc = NULL;
	GdkColor gdkcolor;
	time_t now;
	struct tm *now_tm;
	const char *now_str;
	float dRadians;

	g_return_val_if_fail (gdkwin!=NULL, 0);

	if (fg_gc == NULL) {
		fg_gc = gdk_gc_new (NULL);
		gdk_color_black (gdk_colormap_get_system(), &gdkcolor);
		gdk_gc_set_foreground (fg_gc, &gdkcolor);
	}
	if (bg_gc == NULL) {
		bg_gc = gdk_gc_new (NULL);
		gdk_color_white (gdk_colormap_get_system(), &gdkcolor);
		gdk_gc_set_foreground (bg_gc, &gdkcolor);
	}

	/* get current time */
	time(&now);
	/* convert time to numbers */
	now_tm = localtime(&now);
	
	/* clear clock area */
	gdk_draw_rectangle (gdkwin, bg_gc, 1,
		CLOCK_CENTER_X - CLOCK_RADIUS,
		CLOCK_CENTER_Y - CLOCK_RADIUS,
		CLOCK_RADIUS * 2, CLOCK_RADIUS * 2
		);

	/* draw clock border */
	gdk_draw_arc (gdkwin, fg_gc, FALSE, CLOCK_CENTER_X - CLOCK_RADIUS,
		CLOCK_CENTER_Y - CLOCK_RADIUS,
		2 * CLOCK_RADIUS, 2 * CLOCK_RADIUS,
		0, 360 * 64
		);

	/* draw second */
	dRadians = now_tm->tm_sec * PI / 30.0;
	gdk_draw_line (gdkwin, fg_gc,
		CLOCK_CENTER_X, CLOCK_CENTER_Y,
		CLOCK_CENTER_X + (CLOCK_S_RADIUS * sin (dRadians)),
		CLOCK_CENTER_Y - (CLOCK_S_RADIUS * cos (dRadians)));
	/* draw minute */
	dRadians = now_tm->tm_min * PI / 30.0;
	gdk_draw_line (gdkwin, fg_gc,
		CLOCK_CENTER_X, CLOCK_CENTER_Y,
		CLOCK_CENTER_X + (CLOCK_M_RADIUS * sin (dRadians)),
		CLOCK_CENTER_Y - (CLOCK_M_RADIUS * cos (dRadians)));
	/* draw hour */
	dRadians = now_tm->tm_hour * PI / 6.0;
	gdk_draw_line (gdkwin, fg_gc,
		CLOCK_CENTER_X, CLOCK_CENTER_Y,
		CLOCK_CENTER_X + (CLOCK_H_RADIUS * sin (dRadians)),
		CLOCK_CENTER_Y - (CLOCK_H_RADIUS * cos (dRadians)));

	/* convert time to string */
	now_str = ctime(&now);
	/* update time on EmTK label */
	emtk_label_set_string (labelid, (char*)now_str, strlen(now_str));

	return 1;
}

static GdkFilterReturn gdkwin_event_handler (GdkXEvent *xevent,
GdkEvent *event, gpointer data)
{
	if (((GR_EVENT *)xevent)->type == GR_EVENT_TYPE_EXPOSURE) {
		/* expose event, draw the clock  */
		gdkwin_draw (data);
	}

	return GDK_FILTER_CONTINUE;
}

static void build_test()
{
	GdkWindow *gdkwin;

	// create main window
	wid = emtk_window_new(WINDOW_X, WINDOW_Y, WINDOW_W, WINDOW_H);

	gdkwin = emtk_window_get_drawable(wid);
	gdk_window_add_filter (gdkwin, gdkwin_event_handler, (gpointer)gdkwin);

	emtk_window_set_background_color(wid, "#B6FFEE");

	/* create label */
	labelid = emtk_label_new (wid, LABEL_X, LABEL_Y, FONT1, 
			0, "Current Time here");
	emtk_window_add_object(wid, labelid);

	/* create timer */
	tid = g_timeout_add (1000, gdkwin_draw, gdkwin);

	emtk_window_show(wid);
}


/***********************************************************************
                            External functions
 ***********************************************************************/
int main(int argc, char **argv)
{
	emtk_init(&argc, &argv);
	emtk_root(WINDOW_X, WINDOW_Y, WINDOW_W, WINDOW_H);

	build_test();

	emtk_run();

	exit(0);
}

EmTK demo applications

demo binaries location: ~/sdk-<version>/EmLinux/EmTK/bin-x86/ and ~/sdk-<version>/EmLinux/EmTK/bin-arm7/

you may run the following samples on desktop PC or target board

Screen shot:

big clist - emtk big clist widget (LAF)	canvas - emtk canvas widget
clist - emtk clist widget	form - emtk form widget
label - emtk label and button widget	labellist - emtk labellist widget
labellist2 - emtk labellist widget	oclock - emtk oclock widget
otimer - emtk otimer widget	popupmenu - emtk menu widget
simplemenu - emtk clist and button widget	slider - emtk slider widget
spinbutton - emtk spinbutton widget	text - emtk text widget
vscrollbar - emtk clist and vscrollbar widget	window - emtk window widget
window_gdk - emtk window widget mix with GDK APIs

API reference

API reference is available on ~/sdk-<version>EmLinux/EmTK/docs/html

GLib 1.2

Documentation

GLib API Reference by GTK+
The Main Event Loop from GLib API Reference

EmGdkPixbuf™

Documentation

please refer to EmGdkPixbuf™ Developer's Guide

General UI programming

when entered an event callbacks, UI will stop responding since the UI main loop is still blocked by the callback funcion
do not run more than one instance of nano-X server at any time