Illume2 Documentation

Illume2 Version 0.17.0 What is Illume2? Illume2 is a module for Enlightenment (www.enlightenment.org) that modifies the user interface of enlightenment to work cleanly and nicely on a mobile device - such as an OpenMoko phone. It is currently geared more for a 480x640 (VGA) portrait mode screen but can be trivially modified to work on QVGA or any other resolution. The Final goal is to have it work on a wide range of resolutions seamlessly. It combines an application launcher interface along with an application manager and switcher, as well as forcing certain simple layout policies on applications (such as making their main windows borderless and fullscreen except for Illume's control bar). Please be aware that illume2 code and documentation is subject to change as ideas evolve.

First, let's define some terms

Status Bar

Also known as the Indicator window, this is the bar across the top of the screen that is mostly thin and holds gadgets like the battery charge, signal strength etc.

Softkey

This is the bar at the bottom of applications that almost always has the back-button on the bottom-right and possibly other buttons for actions.

Basic App

This is an app that has minimal or no effort made to use toolkits that support the target or the programmer just wanted to avoid writing the code to use the API’s to support it. These API’s currently draw the “status bar” and ‘softkey” at the bottom for example. These apps will not have “softkeys” or “status bars” in them. They will be simply like xterm, or for that matter any other normal linux gui app. It will work, and controls will be provided outside of the app window.

Conformant App

This is an application that either uses the toolkits provided AND uses them appropriately to provide and/or account for controls that conform to the UI designs/standards desired for the platform.

Fullscreen App

This is a mode that any application can request for its window. This mode intends to get ALL (or as much of the screen without interference) as possible. This is useful for watching movies, games and anything else that needs screen real-estate as losing it is a major loss to the application functionality, look and feel. An application, when fullscreen, should always provide an easy/obvious way to exit or exit fullscreen mode (without requiring a keyboard).

Focused Window

This is the window that is the one that receives all keyboard input (from a physical or virtual keyboard). In X11 there can be only 1 window that has focus (ignoring MPX here).

Multihead

This is a mode of X11 display where you can have 2 root windows on 2 screens. They can be different sizes (resolutions) even different screen depths (one 8bit, one 16bit for example). Input is managed with each root window having mouse input sent as if it were a stand-alone xserver screeen except that the mouse and keyboard can only be active on 1 of the root windows at once, and the mouse exits the other root window screen when it enders the current one.

Xinerama

This is a modern multi-screen display system for X11 where you have a single framebuffer (a single root window) where 1 or more screens “view” regions of that root window. This means all screens have the same depth (all 16bit or all 32bit or all 8bit), but they can be different resolutions. The single keyboard and mouse input is handled as if it were 1 big screen with 2 input regions and 1 keyboard attached.

Policy

Illume2 allows for layout code to be separated into a 'policy'. Policies are modularized code (very similar to Enlightenment modules) that handle arranging windows on screen. Illume2 allows for dynamic switching of the active policy.

Policies

Requirements (please note that these requirements are subject to change)

A policy is required to implement 2 basic functions so that illume2 may dynamically load it:

- init - This is the function that illume2 will call to initialize the policy. It is expected that in here the policy will assign any other functions it handles.
- shutdown - This function will be called by illume2 when the policy is being unloaded. This occurs when policy is changed to a different one, or when illume2 module is unloaded. This is the ideal place for a policy to do any cleanup it needs to.

A policy may optionally implement the following functions:

- border_add - This function gets called by illume2 when a border is added to the screen.
- border_del - This function gets called by illume2 when a border is removed from the screen.
- border_focus_in - This function gets called by illume2 when a border receives focus.
- border_focus_out - This function gets called by illume2 when a border losses focus.
- border_activate - This function gets called by illume2 when a border is activated (usually from a NETWM ACTIVATE request).
- border_property_change - This function gets called by illume2 when a property on any given border changes. This is ideal for handling events like a border changing between fullscreen and non-fullscreen.
- zone_layout - This function gets called by illume2 when the actual screen layout needs updating. Typically used to position windows.
- zone_move_resize - This function gets called by illume2 when a zone gets moved or resized. Typically called when the screen resolution changes.
- drag_start - This function gets called by illume2 when the indicator window gets moved by the user.
- drag_end - This function gets called by illume2 when the indicator window is finished moving (in response to the user moving it).