GUI Style Guidelines

From Openmoko

Jump to: navigation, search



Openmoko is a platform targeted at small screen devices. This means that many of the usual desktop paradigms of windows and menus do not apply very well due to the limited space. Different form factors mean that displays on these devices are often at different orientations and aspect ratios. The Openmoko platform tries to address some of these differences by providing a framework in which application authors do not need to be too concerned about the final layout of their application.

Top Level Overview

Openmoko applications are designed as a number of "pages", which may have a number of relationships between them. Each page contains one task, such as selecting a contact or viewing a calendar.

Layout Abstraction

Pages that are not affected by changes in other pages are known as Primary pages. These work independently of any other pages. Pages which are affected by changes in a primary page are known as secondary pages. For example, in a contacts application, the primary page would be the list of contacts. Secondary pages would be the pages that display information about the selected contact.

Every page has a label, icon and content associated with it. This is used to identify and display the page when necessary.

The relationships between pages are described in a model created when the application is started. The application then instantiates a further object which acts as the view and controller to the model. This deals with creating the initial layout of the application.

Neo1973 Layout

On this form factor, the layout is portrait and constrained by a very small screen size. To accommodate this, all pages are full screen and the target area for buttons must be as large as possible. Borders and spacing between widgets is kept to a minimum to ensure best use of available screen estate.


  • 1) Toolbar -- Additional actions related to the current page.
  • 2) Filter/Search -- Filtering options for the current page.
  • 3) Pages Navigation -- Method to switch between pages.
  • 4) Title -- The window title is not part of the application itself. It is embedded into the main panel and is automatically set to the current applications name. It also serves as a quick way to navigate between open applications.


Switching between pages is achieved by a series of tabs laid horizontally across the bottom of the screen. Each tab contains an icon depicting the purpose of the page it is attached to.


Toolbars appear at the top of the screen, with tool buttons expanded to fill the space available. This ensures maximum target hit area. There should be no more than four items in a toolbar.


The filter/search bar is an optional component, composed of three widgets. A toggle button switches between filter (combo box) and search (entry box). Typing in the search box should re-filter the data after each keypress.

MokoSearchBar is a convenience widget available that implements the above logic. It is part of libmokoui2.

Input Considerations


For devices which require on screen keyboards, the keyboard will automatically appear whenever a widget that requires key input is focused.

Touch Screen

The touch screen should be used for single click (tap) and drag options only. A tap and hold will activate button three on the mouse ("right" click). The "double click" action is strongly discouraged.

General Application Guidelines

Data Persistence

All applications that manipulate data should aim to follow the "instant apply" model so that there is no need for the user to explicitly save any data entered.

State Persistence

Applications should save their state if possible between sessions. This might include current view details or "unsaved" data.

Using GTK+ and libmokoui

GTK+ is a C library that uses GObject for pseudo object orientation. This allows it to be very portable and flexible.

General Guidelines

Openmoko code mostly uses the c99 standard for C.

Spacing,widgets sizes and fonts must not be hard coded into Openmoko applications. Openmoko is a framework for small screen devices, which may include anything as small as QVGA (320x240) to 800x600. Therefore, for applications to work on these different resolutions, programs must not hard code anything to do with the specific appearance of widgets.

Programming Guidelines

Most on screen elements such as buttons and entry boxes are sub classed from the GtkWidget base class. The normal practice is to cast up from this class. For this reason, all the creator functions return GtkWidget rather than the class of which they are creating. GTK+ has many macros that check the type and then cast for you, for example, GTK_TREE_VIEW(foo) will check the pointer "foo" is a GtkTreeView and then cast the pointer to a GtkTreeView pointer.

Personal tools