Re: status icon API

[Wesley Leggette <wleggette gate net>]

There was a discussion on notification versus status panels on
usability gnome org about a month ago and I wrote the following during
that time. The idea is that there is a server that handles notification
and status messages and an application would access it by passing
messages to the server with an "application handle". Towards to middle
is a rough API that I imagined would handle status messages.

______________________________________________________



Linux Application Manager




what is the Linux Application Manager?


As detailed here, the Linux Application Manager would be a server that
would handle representing programs as applications for the user. Current
user interface models handle programs on a process by process basis
(such as the System Monitor) or by window (such as the Window List). 


It is useful to note that a window centric view is prevalent in many
modern operating systems. Most Linux desktop platforms take this
approach, as does the Microsoft Windows line-up. While this window-based
approach works well for appliations that consist of a single window, the
current trend seems to be shifting towards using the window as a
document container as opposed to an application container. For example,
while the System Monitor may be contained in a single window,
OpenOffice, Gnucash, and Evolution wisely open a new window for each new
document.


This document centric approach makes sense. It is also to be expected.
It has long been known that modern applications often consist of more
than one process. It is not a far reach to expect more than one window
as well.


Internally, the method of dealing with different documents varies from
application to application. Some applications create a new process for
each document, others create new windows but control them from the same
process. But whichever methods are used, it control of an application
remains vague and inconsistant for the end user.



Apple has created a unique solution to this problem. In Mac OS 9, there
was an icon on the top right corner of the screen. When a user clicked
on this icon, a menu would drop down listing the currently open
applications and allowing some basic controls over them (reveal, hide,
hide others). Mac OS X has extended this concept by creating the dock.
On the right hand side of the dock is a structure much like the Window
List or Task Bar, except window entries are represented as icons and are
only present when minimized. But on the left are a set of icons
representing programs. All running programs and quick links to some
closed programs are displayed in this section, allowing easy user access
and manipulation.


Some will note that the drop down structure in Mac OS 9 is similar to
the one present in Gnome 2. However, look carefully at the corner menu.
All windows are listed as they are in the Window Lists for each
workspace. Items are not limited to the applications themselves.


The follwing architecture is not a replication of user interface of
Apple Mac OS features. It is the intention of the creators of this
framework that the user interface be configuratble by the end user in
several unique ways. While this framework will allow a replica of the
dock, it will also allow current configurations such as those found in
Gnome 2.


what kind of features would LAM provide?


The Linux Application Manager is meant as an application management
server. This server will work in conjuction with or be integrated with
any window managers or X protocol compatable windowing servers. In the
future, components of the Linux Application Manager may be responsible
for rendering parts of an application's display (i.e. The menu bar)
using a local widget toolset such as GTK or QT. This framework should be
an integral part of the Linux desktop environment, but the API should
remain consistent across mulitple desktop platforms such as Gnome and
KDE.


One major component of the Linux Application Manager is that it requires
little from the application itself to serve it's basic purposes. In
order for the LAM to work, applications must be registered with it as
they are opened. Instead of relegating this responsibility to new code
within an application, registration will be performed by an external
program. The Gnome concept of “launchers” will be extened to perform
initial application registration and configuration as well as start the
application itself. (Launchers will be similiarly constructed for each
application.) 


The launchers themselves will be contained in “application bundles” or
“application launcher bundles”, an idea spawning from Apple's Mac OS X.
However, these application bundles are designed to meet the needs of
Linux applications. While they should contain the launcher itself, a
configuration file, and any nessesary resource files (only icons at this
point), bundles need not contain the entire application (although they
certainly can), thus allowing applications to be placed within the
normal Linux hierarchy as needed.


It is important to note that an important design goal of these launchers
is that they can operate properly without reconfiguration from any
directory on the file hierarchy as the actual application. This means
that they can be moved at the discretion of the user without unwanted
side effects. Hence, when placed in a clearly accessible folder, they
can be moved around and organized in any way the end user sees fit,
allowing each re-arrangement of any program launcher panel that is
rendered from the launchers themselves.


LAM provides notification and status functions as well


The LAM is also designed to handle the emerging task of “notification
messages” and “status areas”.




API 2 loose c++ function declarations


struct AM_HANDLE {

AM_APP_HANDLE app // application panel

AM_LOADOPTIONS conf // load options

AM_SESSION session // session data

AM_STATUS_HANDLE status // status handle

vector<AM_NOTIFY_HANDLE> notify_queue // queue notification handles.

// place new notifications at the end of vector and display queue
according to end user preferences (oldest or newest first). Dismissed
notifications are removed from the queue.

}


struct DISMISSAL_ACTIONS {

vector<char[]> option_label // menu or button labels

// if a label is “sep” and the structure is used in a status icon, a
seperator is used in the rendered context menu. “sep” options cannot be
the default option. If they are, the first valid label or no label will
be used as the default menu item.


Vector<msg struct???> option_return_message 


// message returned to client application when end user clicks button or
contect menu item


int default_option_index // default action item

(double-click)

}





register an application


AM_HANDLE AM_app_reg( PID, path to launcher.conf, int workspace)

// is this enough?? How are workspaces handled? How/ can messages be
sent if just the PID is known? ...See definition of launcher.conf files.


Void AM_app_unreg( AM_HANDLE, bool message_when_done)



create a notification (where user wants them put)


AM_NOTIFY_HANDLE AM_notify_create( AM_HANDLE, char[] message, bool
notify_on_dismissal) // create simple dismiss only notification

AM_NOTIFY_HANDLE AM_notify_create( AM_HANDLE, char[] message,
DISMISSAL_ACTIONS actions) // create multi option notification


// should there be a pre-empt other notifications option to display
priority messages before others?


Void AM_notify_kill( AM_HANDLE, bool notify_on_done)

// this kills the last created notification before user dismissal

void AM_notify_kill( AM_HANDLE, AM_NOTIFY_HANDLE, bool notify_on_done)

// this kills a specific notifcation message before dismissal



create a status icon (where user wants them put)


void AM_status_create(AM_HANDLE, bitmap icon, char[] message,
DISMISSAL_ACTIONS actions)

// bitmap? PNG? SVG?What's the best way to transfer an image through
memory, anyway? Also, size specifications are needed here. Fixed
dimensions or fixed size? 


// also, should a AM_STATUS_HANDLE be returned here? It would really
only be needed for debuging and such. Apps never need to pass it again.
Of course, this framework only allows one status icon per application.
Will apps need more?


Void AM_status_create(AM_HANDLE, file icon, char[] message,
DISMISSAL_ACTIONS actions)

// read icon or display picture from file


void AM_status_update(AM_HANDLE, bitmap icon, char[] message,
DISMISSAL_ACTIONS actions)

void AM_status_update(AM_HANDLE, file icon, char[] message,
DISMISSAL_ACTIONS actions)

void AM_status_update(AM_HANDLE, bitmap icon, char[] message)

void AM_status_update(AM_HANDLE, file icon, char[] message)

void AM_status_update(AM_HANDLE, char[] message)


// Is there an HIG spec on what status tool-tips or messages should say?
I would propose tool-tips verbalizing the message sent by the picture,
such as “Battery 50% charged” or “Samba Server Active: 50 Connections”


modify registered application status


void AM_app_loadingon(AM_HANDLE) // starts any loading indication

void AM_app_loadingoff(AM_HANDLE) // stops any loading indication





API 2 loose configuration file examples


example file locations


/Applications // root for app loaders

/Applications/Example Program.app // folder for app loader

../launcher // loading binary or script

../launcher.conf // launcher config.

../icons (dir) // icon collection



/etc/Applications // launcher prefs

../applications.conf // config file

../launcher.conf // default launcher config

../launcher.conf.default // shipped defaults


/var/run/app (dir) // LAM session information

../Example Program.session // session file






example configuration files


// /Applications/Example Program.app/launcher will set the set an
APP_BUNDLE_ROOT pathname in memory (from it's current location), which
will be used to determine the bundle root at runtime. Use
“$APP_BUNDLE_ROOT” in any pathnames that require referencing to

bundle roots. This allows you to move bundles around.


---------------------------------------------------

// launcher.conf


[launcher] // processed after [paths]


app_name=”Example Program” [text string]

app_desc=”Shows users how to start things” [text string]

exec=”/opt/exampleprogram1.0/bin/runme” [file path]


# exec=”runme” // search $PATH

# exec=”$APP_BUNDLE_ROOT/bin/runme” // launcher replaces root

# exec=”$BINDIR/runme” // launcher replaces bindir


icon_root=”$APP_BUNLE_ROOT/icons/”


# icon_root=”/opt/exampleprogram1.0/share/pixmaps/”



# SVG for large icon display. The default file type. Large icon is

# displayed in small spaces if no other icon listed.

# Path starts from /Applications/Example Program.app/ or [icon_root]

# as defined above.

icon_svg_high=”exp_high.svg” [file name]


# SVG for small icon display

icon_svg_low=”exp_low.svg” [file name]


# PNG for large icon display. Used if no SVG. Large icon is displayed

# if no small icon is present.

icon_png_high=”exp_high.png” [file name]


icon_png_low=”exp_low.png” [file name]


// I'm thinking that all launcher icons should be in the same

place. That's why I have the above as file names, not paths.

Also, I think it would be best for the icons to stay in the bundles.


[paths] // processed before [launcher]


// Should we bother to have a $PREFIX? I choose not to. It will just

require more processing.


bindir=”/opt/exampleprogram1.0/bin/”

sbindir=”/opt/exampleprogram1.0/sbin/”

libdir=”/opt/exampleprogram1.0/lib/”

datadir=”/opt/exampleprogram1.0/share/”

sysconfdir=”/opt/exampleprogram1.0/etc/”



[signals]


// Is there any way to describe what kind of signals to send to
application processes to pass messages, quit, hide windows, etc? Is it
even nessesary?




---------------------------------------------------


// applications.conf


[launcher]


# I was going to put the following line in, but it doesn't look like 

# it's nessesary if the launcher automatically determines the bundle

# root. Are there any cases where the launcher would not be able to 

# determine the path it was launched from?


# APPLICATIONS_ROOT=”/Applications”


// if LAM is used to render a launcher menu, APPLICATIONS_ROOT should

be defined in that context.



# Application bundle extension. Any launching program should treat

# directories ending in this ex

application_extension=”app”



session_state_path=”/var/run/Applications”



---------------------------------------------------


// Example Program.session


[session]

running=true [boolean]

pid=12345 [unix process ID]


# time of last application exit

last_date=1049178434 [unix time]


[launcher]


// all information from [launcher] sections of config files goes here.


[paths]


// all path information goes here.



-- 
Wesley Leggette <wleggette gate net>