GUI Framework API#

It is called within the oasis::ui namespace category.

Header File#

OasisUI.h

Setup and Cleanup#

The key-value map required for oasis::ui initialization is as follows:

The display module of the chipset supports multiple channels per purpose, and multiple layers per channel. It supports at least one channel and one layer. Oasis manages the GUI side by dividing it into HLAYER to match the layer structure supported by the display module of each chipset.

HLAYER is a 32-bit integer value and has a 3-tuple structure with (channel, hard layer, soft layer) as its elements. When having a (channel, layer) structure depending on the chipset, the hLAYER string format is specified as a 2-tuple like "0:1". For example, if there are multiple cores responsible for display control, channel specifies the core index as 0, 1, 2, etc., hard layer specifies the layer supported by each core, and soft layer can have a structure generated by Oasis as needed.

Touch calibration data values are calculated using 5 points obtained by touching, as shown in the function below.

struct {
  int32_t x;
  int32_t y;
} touch[5] = { 0, };

int32_t cal[9] = { 0, };

void calibrate() 
{
    double dx_min, dy_min, dx_max, dy_max;
    double dx_ratio, dy_ratio, scale = 65536.0;
    int32_t i;

    double x_distance = 0.0, y_distance = 0.0;

    x_distance += (double)(touch[4].x-touch[0].x);
    x_distance += (double)(touch[4].x-touch[3].x);
    x_distance += (double)(touch[1].x-touch[4].x);
    x_distance += (double)(touch[2].x-touch[4].x);
    x_distance /= 4.0;
    dx_ratio = (double)(screen[4].x-screen[0].x)/x_distance;

    y_distance += (double)(touch[4].y-touch[0].y);
    y_distance += (double)(touch[4].y-touch[1].y);
    y_distance += (double)(touch[3].y-touch[4].y);
    y_distance += (double)(touch[2].y-touch[4].y);
    y_distance /= 4.0;
    dy_ratio = (double)(screen[4].y-screen[0].y)/y_distance;

    dx_min = dx_max = 0.0;
    dy_min = dy_max = 0.0;

    for(i=0; i<5; i++) {
        dx_min += (double)touch[i].x - (double)screen[i].x/dx_ratio;
        dx_max += (double)touch[i].x + (double)(width_-screen[i].x)/dx_ratio;
        dy_min += (double)touch[i].y - (double)screen[i].y/dy_ratio;
        dy_max += (double)touch[i].y + (double)(height_-screen[i].y)/dy_ratio;
    }
    dx_min /= 5.0;
    dy_min /= 5.0;
    dx_max /= 5.0;
    dy_max /= 5.0;

    cal[0] = (int32_t)dx_min;
    cal[1] = (int32_t)dx_max;
    cal[2] = (int32_t)dy_min;
    cal[3] = (int32_t)dy_max;
    cal[4] = (int32_t)(dx_ratio*scale);
    cal[5] = (int32_t)(dy_ratio*scale);
    cal[6] = (int32_t)scale;
    cal[7] = 480;  //display width
    cal[8] = 320;  //display height
}

size_t save(const char *path)
{
    FILE *f = fopen(path, "w");
    if(!f) {
        return 0;
    }

    char cal_buffer[256];
    ssize_t len = sprintf(cal_buffer,"%d %d %d %d %d %d %d %d %d", 
            cal[0], cal[1], cal[2], cal[3], cal[4], cal[5], cal[6], cal[7], cal[8]);
    fwrite (cal_buffer, 1, len, f);
    fclose(f);

    return len;
}

Physical (x, y) coordinates obtained when a touch event occurs are converted into screen coordinates used by the GUI, as shown in the function below.

struct {
  int32_t x;
  int32_t y;
} ui_touch;

void touchToScreen(int32_t x, int32_t y)
{
    ui_touch.x = (x - cal[0])*cal[4]/cal[6];
    ui_touch.y = (y - cal[2])*cal[5]/cal[6];
}

Below is an initialization example.

oasis::key_value_map_t parameters;

parameters["system-font-size"] = "11";
parameters["system-font-path"] = "/mnt/sd/NanumGothicCoding.ttf";
parameters["display-rotation"] = "0";
parameters["enable-touch"] = "1";
parameters["touch-cal-data-path"] = "/mnt/sd/cal.dat";

parameters["vi0-hlayer"] = "1:0:0";
parameters["fb0-hlayer"] = "1:1:0";
parameters["hide-unmanaged-ui-layer"] = "1:2:0";

ui::setup(parameters);

Below is an initialization example when using the display rotated by 270 degrees.

////////////////////////////////////////////////////////////////////////////////////////////
// display setup
parameters.clear();

parameters["memory-type"] = "ion"; //cma
parameters["screen-width"] = "720";
parameters["screen-height"] = "1920";

display::setup(parameters);


//////////////////////////////////////////////////////////////////////////////////////////
// ui setup
parameters.clear();

parameters["system-font-size"] = "10";
parameters["system-font-path"] = "/mnt/sd/consola.ttf";

parameters["display-rotation"] = "270";
parameters["enable-touch"] = "0";

parameters["fb0-hlayer"] = "0:1:0";
parameters["vi0-hlayer"] = "0:0:0";

err = ui::setup(parameters);
if (err < 0) {
  DLOG(DLOG_ERROR, "Oasis ui::setup failed\n");
  return -1;
}

Screen#

The flags are as follows:

enum UIDevelFlags : uint64_t {
    kUIDevelFlag_Border = 0x0000000000000001ull,
    kUIDevelFlag_PrintCallStackOnLayout = 0x0000000000000002ull
};

kUIDevelFlag_Border draws the border of each widget. The kUIDevelFlag_PrintCallStackOnLayout value is not used.

Widget#

The default class names of widgets are as follows:

Widget Object	Class Name
Button	Button
Dialog	Dialog
DrawingArea	DrawingArea
FixedLayout	Fixed
GridLayout	Grid
BoxLayout	Box
SingleLayout	Single
Image	Image
Label	Label
ListBox	ListBox
Window	Window

When setting an ID string for a widget using ui::setID, the class name is changed to <Class Name>::<ID String>.

The SizeRequestMode values are as follows:

SizeRequestMode	Value	Description
kSize​Request​Height​For​Width	0	The widget calculates its preferred height while its width is known.
kSize​Request​Width​For​Height	1	The widget calculates its preferred width while its height is known. When calling preferredWidth, the container widget calls preferredHeight first to know the height of the widget, and then calls preferredWidthForHeight.
kSize​Request​Constant​Size	2	The widget can respond to any size calculation request from the container widget. In this case, the container widget requests preferredWidth and preferredHeight first.

The horizontal/vertical alignment values are as follows:

AlignType	Value	Description
kAlignFill	0	Fills the widget completely. For vertical alignment, it expands the height. For horizontal alignment, it expands the width.
kAlignStart	1	Aligns the widget to the starting position. For vertical alignment, it places it at the top. For horizontal alignment, it places it on the left.
kAlignEnd	2	Aligns the widget to the ending position. For vertical alignment, it places it at the bottom. For horizontal alignment, it places it on the right.
kAlignFill	3	Aligns the widget to the center position.
kAlignBaseline	4	Limited to vertical alignment, aligns to the baseline of the container of the widget.

raf_bind_t is defined as follows:

To perform animation drawing on a DrawArea widget, implement it in the following manner:

// Creates a drawingArea from a player object and requests rAF on it.
int32_t Player::startDrawPictures()
{
    std::function<void(ui::WidgetRef,GraphicContextRef)> canvas_draw_bind = std::bind(&Player::draw, this, std::placeholders::_1, std::placeholders::_2);
    ui::DrawingAreaRef canvas = ui::createDrawingArea(canvas_draw_bind);
    ui::setID(canvas, "picture_canvas");
    ui::boxPackStart(vbox, canvas, true, true, 0);
    ui::requestAnimatedFrame(canvas, canvas_draw_bind);
}

void Player::draw(ui::WidgetRef widget, GraphicContextRef gc) 
{
    Rect rect;
    ui::getCanvasRect(widget, rect);

    // Perform drawing.

    if(!completed_) {
        // Request rAF again as needed.
        std::function<void(ui::WidgetRef,GraphicContextRef)> canvas_draw_bind = std::bind(&Player::draw, this, std::placeholders::_1, std::placeholders::_2);
        ui::requestAnimatedFrame(widget, canvas_draw_bind);
    }
}

Container Interface#

Oasis GUI layouts child widgets using the following layout containers:

• Box container widget for arranging in vertical or horizontal directions
• Fixed container widget for arranging at fixed positions
• Grid container widget for arranging by specifying rows and columns in a grid manner
• Single container widget that has only a single child widget
• ListBox container widget capable of scrolling in a list style

These are widgets derived from the container interface.

A container widget can include other container widgets.

The container interface is created via createBox, createFixed, createGrid, createWindow, createButton, createListBox, etc.

Box Container#

The box container widget arranges child widgets horizontally or vertically.

Fixed Container#

The fixed container widget places child widgets at fixed positions.

Grid Container#

The grid container widget arranges child widgets based on rows and columns.

Single Container#

Created via createWindow, createDialog, createButton, etc.

ListBox Container#

The listBox container widget arranges child widgets as a scrollable container.

Window#

Dialog#

Button#

Image#

The pixel formats supported for PNG image files are as follows:

• OASIS_PIXEL_FORMAT_BGRA_8888
• OASIS_PIXEL_FORMAT_BGRX_8888
• OASIS_PIXEL_FORMAT_ABGR_8888
• OASIS_PIXEL_FORMAT_XBGR_8888
• OASIS_PIXEL_FORMAT_ARGB_8888
• OASIS_PIXEL_FORMAT_XRGB_8888

The pixel formats supported for JPEG image files are as follows:

• OASIS_PIXEL_FORMAT_BGRA_8888
• OASIS_PIXEL_FORMAT_RGBA_8888
• OASIS_PIXEL_FORMAT_ARGB_8888
• OASIS_PIXEL_FORMAT_ABGR_8888
• OASIS_PIXEL_FORMAT_XRGB_8888
• OASIS_PIXEL_FORMAT_XBGR_8888
• OASIS_PIXEL_FORMAT_RGBX_8888
• OASIS_PIXEL_FORMAT_BGRX_8888
• OASIS_PIXEL_FORMAT_RGB_888
• OASIS_PIXEL_FORMAT_BGR_888

Label#

The horizontal Justification values are as follows:

Justification	Value	Description
kJustificationLeft	0	Aligns to the left.
kJustificationRight	1	Aligns to the right.
kJustificationCenter	2	Aligns to the center.
kJustificationFill	3	Aligns equally.

The vertical Justification values are as follows:

Justification	Value	Description
kJustificationTop	0	Aligns to the top.
kJustificationBottom	1	Aligns to the bottom.
kJustificationVCenter	2	Aligns to the vertical center.
kJustificationFill	3	Aligns equally.

Graphic Context#

Oasis performs operations to draw on the screen using the graphicContext object.

If hardware acceleration is supported, it uses hardware acceleration.

Drawing can be performed via the drawingArea widget.

The flags value of drawText performs OR'ing of the following values:

flag	Value	Meaning
DT_TOP	0x00000000	Aligns the vertical reference of the text to the top.
DT_LEFT	0x00000000	Aligns the text to the left.
DT_CENTER	0x00000001	Aligns the text to the center.
DT_RIGHT	0x00000002	Aligns the text to the right.
DT_VCENTER	0x00000004	Aligns the vertical reference of the text to the center.
DT_BOTTOM	0x00000008	Aligns the vertical reference of the text to the bottom.
DT_WORDBREAK	0x00000010	Allows line breaking by word unit.
DT_SINGLELINE	0x00000020	Processes as a single line.
DT_CALCRECT	0x00000400	Calculates the region where the string will be drawn. It does not actually draw.
DT_NOPREFIX	0x00000800	Does not process the prefix symbol (&) in the string. If it is \"&abc\", it is drawn as \"abc\".
DT_NOFULLWIDTHCHARBREAK	0x00080010	If a single character exceeds the allowed width, it processes that character without line breaking.

Drawing Area#

Below is an example of creating and drawing a drawingArea:

int32_t App::create()
{
    // Creates a drawingArea object.
    canvas_ = ui::createDrawingArea(std::bind(&App::draw, this, std::placeholders::_1, std::placeholders::_2));
    ui::setID(canvas_, "my_drawingarea");
    ui::gridAttach(grid, canvas_, 0, 0, 1, 1);  
}

void App::draw(ui::WidgetRef widget, GraphicContextRef gc) 
{
    // Paints the entirety in black.
    Color clr_bk(255, 0, 0, 0);
    ui::fillRectangle(gc, 0, 0, width_, height_, clr_bk);

    // Draws a yellow box.
    Color clr_line(255, 255, 255, 0);
    ui::drawRectangle(gc, 10, 10, 100, 100, clr_line);

    // Draws a string.
    std::string text = "안녕하세요!";
    ui::setFont(gc, 11);
    ui::setTextForeColor(gc, Color(255, COLOR_WHITE)());
    ui::drawText(gc, str, 20, 20, 80, 80, DT_CENTER|DT_VCENTER);
}

Keypad#

Below is an example utilizing the keyboard:

void cancel_handler(int sig)
{
    ui::quitAllRunContexts();
    got_interrupt = true;
}

int main(int argc, char *argv[])
{
    int32_t err;

    signal(SIGINT, cancel_handler);

    oasis::key_value_map_t parameters;

    parameters["offs-disable"] = "1";
    if(oasis::initialize(parameters) < 0) {
        DLOG(DLOG_ERROR, "Oasis init failed\n");
        return -1;
    }

    ////////////////////////////////////////////////////////////////////////////////////////////
    // display setup
    parameters.clear();

    parameters["memory-type"] = "ion"; //cma
    parameters["screen-width"] = "480";
    parameters["screen-height"] = "320";

    display::setup(parameters);

    //////////////////////////////////////////////////////////////////////////////////////////
    // ui setup
    parameters.clear();

    parameters["system-font-size"] = "11";
    parameters["system-font-path"] = "/mnt/sd/NanumGothicCoding.ttf";
    parameters["display-rotation"] = "0";
    parameters["enable-touch"] = "1";
    parameters["touch-cal-data-path"] = "/mnt/sd/cal.dat";

    err = ui::setup(parameters);
    if (err < 0) {
        DLOG(DLOG_ERROR, "Oasis ui::setup failed\n");
        return -1;
    }

    //////////////////////////////////////////////////////////////////////////////////////////
    //////////////////////////////////////////////////////////////////////////////////////////

    ui::ScreenRef screen = ui::getDefaultScreen();

    int32_t screen_width = ui::screenWidth(screen);
    int32_t screen_height = ui::screenHeight(screen);

    ui::DialogRef dialog = ui::createDialog(nullptr);
    ui::setBgColor(dialog, Color(255, COLOR_BLACK));
    ui::setBorderSize(dialog, 0, false);

    ui::BoxRef dialog_container = ui::getDialogContainerBox(dialog);
    ui::setHAlign(dialog_container, ui::kAlignFill);
    ui::setVAlign(dialog_container, ui::kAlignFill);
    ui::setMargin(dialog_container, 0);

    ui::BoxRef content_area = ui::getDialogContentArea(dialog); //horz box layout

    ui::KeypadRef keypad = ui::createKeypad(dialog, "암호 입력", "1122334455", "취소", "확인");

    ui::screenAdd(screen, dialog);

    std::string str = ui::showKeypad(keypad);

    err = ui::runDialog(dialog);

    ui::destroyDialog(dialog);

    err = ui::cleanup();

    oasis::finalize();

    return 0;
}

This is the keypad screen displayed in the application example:

Timer#

source_slot_t is defined as follows:

Below is an example triggering a timer at 1-second intervals:

// Creates a timer.
timer_id_ = ui::timeoutAdd("tick_timer", 1000000, sig::mem_fn(*this, &App::tickTimer));
if(timer_id_ > 0) {
  // Starts the timer.
  ui::timeoutEnable(timer_id_, true);
}

bool App::tickTimer()
{
  // Perform timer task.

  // Return false to release the timer.
  //return false;
  return true;
}

Signaling#

Oasis GUI event generation and processing utilizes the signal-slot mechanism.

Oasis utilizes a signaling template for handling the following click and touch events:

• clicked
• touch-up-event
• touch-down-event
• touch-move-event

The types for individual event handler functions are as follows:

Below are Signal connection examples:

// Connects the "clicked" signal handler
uint32_t clicked_sigid = ui::connectSignal(apply_button, "clicked", clicked_slot_t(sig::mem_fn(*this, &App::applyButtonClicked)), 0);

// Connects the "touch-down-event" signal handler
uint32_t touch_down_event_sigid = ui::connectSignal(drawing_canvas, "touch-down-event", touch_down_event_slot_t(sig::mem_fn(*this, &App::touchedDown)), 0);

// Connects the "touch-up-event" signal handler
uint32_t touch_up_event_sigid = ui::connectSignal(drawing_canvas, "touch-up-event", touch_up_event_slot_t(sig::mem_fn(*this, &App::touchedUp)), 0);

// Connects the "touch-move-event" signal handler
uint32_t touch_move_event_sigid = ui::connectSignal(drawing_canvas, "touch-move-event", touch_move_event_slot_t(sig::mem_fn(*this, &App::touchedMove)), 0);

Running Context#

Oasis utilizes RunningLoop for event processing. RunningLoop contains RunContext.

Used when attempting to forcibly terminate the application from a signal handler such as SIGINT.