ChumbOS Launcher Files

ChumbOS Launcher - Version 0.99.57 (1stRelease)
===============================================

Written by: Odo Bogdan (odobogdan[@]gmail.com)

    ChumbOS Launcher - Native Application Launcher for Chumby
	Copyright (C) 2012, by Odo Bogdan.

    This program is free software: you can redistribute it and/or modify
    it under the terms of the GNU General Public License as published by
    the Free Software Foundation, either version 3 of the License, or
    (at your option) any later version.

    This program is distributed in the hope that it will be useful,
    but WITHOUT ANY WARRANTY; without even the implied warranty of
    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
    GNU General Public License for more details.

    You should have received a copy of the GNU General Public License
    along with this program.  If not, see <http://www.gnu.org/licenses/>.
	
This software is conveyed under the GPLv3 license.
See LICENSE file for more details.

RELEASE NOTES
-------------------------------------------------------------------------
Patch to debugchumby in the initial release (23-Apr-2012 22:41 BST)
	ChumbOS-BIN-v0.99.58a.zip
	Added:
		Stopping of the control panel in debugchumby.
		Only the binary package is modified.
		Minor addition but with great importance.

Initial release (23-Apr-2012 08:24 BST)
	ChumbOS-BIN-v0.99.58.zip
	ChumbOS-SRC-v0.99.58.zip
	
INTRODUCTION
-------------------------------------------------------------------------

    ChumbOS Launcher is a native C application that is designed to break
the shackles of the Chumby, so that not only flash applications can take
advantage of the cute little colour screen, touchscreen input, rotary
encoder and it's majestic Chumby Button.
By the way, not that it had too many shackles, don't get me wrong, but
the limitation of using only flash widgets on a device having the horse
power of a 450MHz full blown computer, seems to me, a bit of a waste and
just a bit annoying.
    So, what does this application do? It enables you to design a simple
Graphical User Interface (GUI) which can start and stop other applications
on the Chumby.
I believe this is very inportant from two perspectives:
    1) Native C applications that take advantage of the screen, touch
        input, and other sensors do not need to be lauched via SSH, or
        require you to reboot the device.
    2) The Control Panel that is shipped with the device can behave
        erratically and thus requiring you to reboot your device,
        which takes time. Time away from your Chumby's fun activities!

    This package already contains a GUI with all its resources and some
sample "widgets".

More exactly, this is what you get in this package:
    README            ===> This read-me file!
    ChumbOS            ===> The main application compiled for ChumbyOne
    GUIchumbOS.ini    ===> INI file describing the layout of the GUI
    res/            ===> Directory with the images in RAW format that
                         make up the GUI
    swf/            ===> Directory with sample widgets


INSTALATION
-------------------------------------------------------------------------

    You just run it on the Chumby! This can be achieved in many ways, the
simplest and usual way is to unpack the contents of this archive onto a
USB stick, making sure that the  "debugchumby"  file is the one from this
archive and not other programs. Apart from that you don't need to reformat
the USB drive, it only needs to be recognizable by the Chumby.
    Then just reboot your device with this USB stick plugged in the Chumby!

    That's it! Hopefully there will be no problems and you will see the
new GUI show up on the screen quite fast!

ChumbOS Launcher was tested only on 1(one) single ChumbyONE, it might or
might not work with other flavours of Chumby, but I don't know that! Yet!

So, help me out here, try it out, and see how it feels!


OPERATION
-------------------------------------------------------------------------

    The operation is self explanatory, you tap and you launch an app.
There is a "Next" button, which takes you to the next page of apps, that
you can launch from ChumbOS.
    When an application starts, ChumbOS, fades away in the background and
lets the app update the screen and receive input from the touchscreen.
However the Chumby Button and the Rotary Encoder(Knob) are still controlled
by ChumbOS for some applications or is left to be the responsibility of the
launched app to use them. While still looking out for a press on the Big
button longer than 3 seconds to quit any app, and get back to ChumbOS!

    So, there are two ways to quit an application started by ChumbOS.
1) Just pres once shortly on the Chumby Button (the big one on top!)
2) Press and hold for more than 3 seconds on the same Chumby Button
    (this is for apps that need to use the Chumby Button, like the
    stock control panel)

    The knob on the side controls the backlight at the moment, but
I will change that to control the volume, while I will implement an
alternative "gesture" to control the backlight in the next release.


GUI CUSTOMIZATION ("Advanced stuff";)
-------------------------------------------------------------------------

    In order to control the look of the ChumbOS Launcher, you have the
possibility to do it via a simple text editor, by editing "GUIchumbOS.ini"
This file defines sections and name-value pairs like this:

[ThisIsASection]
Name=Value

    The name designators ARE case sensitive! So locationx is not the same
as LocationX. Values are case sensitive when they represent filenames or
paths, as it is usual in any Linux environment.
    One GUI element is defined by one section, withing each sections there
are the name and value pairs that define the actual properties of the GUI
element.

Here is a list with the names of the properties that an element can have

[SectionName] is just a tag, but to sections CANNOT HAVE the same tag!
            This mostly ignored but is handy when debugging!

PageID => Numeric value to distiguish sepparate pages and designate the
            fact that the element will be drawn on the page with this
            given ID.
          The elements with the same PageID have to follow each other
          consecutively in the INI file. They cannot appear scattered
          around the INI file, the parser is not that smart to deal
          with this.

LocationX  -+===> The properties of the RAW image to be displayed!
LocationY  -+
SizeX      -+
SizeY      -/

ImageNormal =>
ImageNormalPushed =>
            Represent the filenames containing the RAW data, the images should
			have a 24bit RAW format ONLY! No other formats are supported at
			the moment.

ZOrder => Is the order used when trying to determine which element has
            received a tap. It is not used to designate the order in
            which the images are drawn on the screen. This is done by
            the actual order in which they appear in the INI file.

Action => Is the command that will be executed when the element has received
            a tap. Any linux command is accepted but it is advised to start
            programs that do not create loose proceses, because Chumbos
            cannot track down and shut them down if ask so by the user.

And, last but not least:
RunsInTheBackground => This property is probably the most obscure one.
    It controls how ChumbOS behaves when an application is started, and
it has 3 possible values:

RunsInTheBackground =
0 = The application specified by the Action property is started as a
    sepparate process for which the process ID is retained. This PID is
    then used to gracefully shutdown the application with a simple (quick)
    press on the Chumby Button.
    The rotary knob controls backlight level.
    (This is the default setting)

RunsInTheBackground =
1 = The process specified by the Action property is started, and left to
    run in the background.

RunsInTheBackground =
-1 = The same behaviour as when the value is 0(above), but the Chumby
    Button is left to be used by the application that was started
    except for presses longer than 3 seconds when it stops the process,
    and returns to ChumbOS.
    This setting is mainly useful when starting the control panel.


Below is a snippet of the INI file, for ilustration.


;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
; This is the background image
[BackgroundImagePage1]
PageID = 1
LocationX = 0
LocationY = 0
SizeX = 320
SizeY = 240
ImageNormal = res/Sepia0.raw
ZOrder = 0
;--------------------------------------------------;
[Button01]
PageID = 1
Text = Radio Guerrilla
LocationX = 20
LocationY = 30
SizeX = 50
SizeY = 50
ImageNormal = res/RadioGuerilla50.raw
ImagePushed = res/RadioGuerilla50Pressed.raw
Action = btplay --start-daemon http://live.eliberadio.ro:8002
ZOrder = 1
RunsInTheBackground = 1
;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;



There are many limitations in the current version,
    which I did not sort out, due to lack of time but
        they might be corrected in future versions.
		
		Please accept my appologies for any bugs!

You can generate "Segmentation faults" and other erros quite easily!
Please be gentle with this piece of code, it does not have too many safety checks.

It comes with an "AS-IS" WARANTY! I cannot be held liable for any damage arising
from it's usage, you know the drill! You can freely modify the source code but 
you CANNOT make profit out of it! The modified code has to be covered by the same
license GPLv3


LICENSE
-------------------------------------------------------------------------
"ChumbOS" is distributed/conveyed under the GPLv3 license.
See LICENSE file for more details.


ACKNOWLEDGEMENTS
-------------------------------------------------------------------------

ChumbOS uses the "inih" library for parsing INI file(s), because its nice
and I was too lazy to write my own (*AGAIN!*).
Many thanks to its creator benhoyt@gmail.com!
INIH website: http://code.google.com/p/inih/


I would like to thank all the good people that posted articles on the net.

THANK YOU!!!

Hope you enjoy ChumbOS, all the best,
Odo B.


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

The "inih" library is distributed under the New BSD license:

Copyright (c) 2009, Brush Technology
All rights reserved.

Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions are met:
    * Redistributions of source code must retain the above copyright
      notice, this list of conditions and the following disclaimer.
    * Redistributions in binary form must reproduce the above copyright
      notice, this list of conditions and the following disclaimer in the
      documentation and/or other materials provided with the distribution.
    * Neither the name of Brush Technology nor the names of its contributors
      may be used to endorse or promote products derived from this software
      without specific prior written permission.

THIS SOFTWARE IS PROVIDED BY BRUSH TECHNOLOGY ''AS IS'' AND ANY
EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
DISCLAIMED. IN NO EVENT SHALL BRUSH TECHNOLOGY BE LIABLE FOR ANY
DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

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


(eof)