Notes on Entrance's Edje Format
----------------------------------------------------------------------------

Each Entrance theme will consist of Two main groups "Main" and "Session"

Themes are edjes(eet files) and work like this:
1. A Parts Collection Must be Present, Titled "Main"
2. Entrance makes use of the parts of Main.  If the required column is
    set to No it is an optional feature for the themer.
3. A Background collection must also be present, titled "Background", and
   must be defined before the "Main" collection.
----------------------------------------------------------------------------
A Complete listing of Edje parts Entrance is aware of
-------------------------------------------------------------------------
| Part Name(state1, state2, ... , staten)	| Type         |  Required |
-------------------------------------------------------------------------
| entrance.entry.pass(default) 			    | TEXT	       | Yes       |
-------------------------------------------------------------------------
| entrance.entry.user(default) 			    | TEXT	       | Yes       |
-------------------------------------------------------------------------
| entrance.date(default)		       	    | TEXT	       | No        |
-------------------------------------------------------------------------
| entrance.time(default)		       	    | TEXT	       | No        |
-------------------------------------------------------------------------
| entrance.hostname(default)		        | TEXT	       | No        |
-------------------------------------------------------------------------
| entrance.xsessions.selected (default)   	| RECT	       | No        |
| The currently selected Session is         |              |           |
| swallowed                                 |	           |           |
-------------------------------------------------------------------------
| entrance.user.avatar(default)   		    | RECT	       | No        |
| The currently selected User is swallowed  |              |           |
| here                                      | 	           |           |
-------------------------------------------------------------------------
| entrance.xsessions.list (default)   		| RECT	       | No        |
| Based on system configuration information |              |           |
| the list of the other group "Session"     |              |           |
| available to the system is contained here	|	           |           |
-------------------------------------------------------------------------
| entrance.users.list(default)   		    | RECT	       | No        |
| Based on system configuration information |              |           |
| the list of the users on the systems.     |              |           |
| Each user  has their own edje				|	           |           |
-------------------------------------------------------------------------

3. The following signals are emitted by entrance and need to be caught in
programs.
-------------------------------------------------------------------------
| Signal		                | Description   		            
-------------------------------------------------------------------------
| entrance,user,auth,success    | After successful authentication this  
| Required: Yes                 | signal is emitted, you can do your own
|                               | animation here if you want.  You must 
|                               | emit "entrance,user,auth,success,done" ""
|                               | after it though in order for
|                               | entrance to start your x session 
|                               |"entrance,user,auth,success,done" ""
---------------------------------------------------------------------------
| entrance,user,fail	        | When the user is unknown the system  
| Required: No                  |
---------------------------------------------------------------------------
| entrance,user,auth,fail       | When a user fails a login attempted 
| Required: No                  |
---------------------------------------------------------------------------
| entrance,user,success         | When the user is known to the system,
| Required: No                  | it's time to prompt for their password
---------------------------------------------------------------------------
| entrance,xsession,selected    | When the user selects a new session
| Required: No                  | The cloned Session item is swallowed
|                               | into entrance.xsessions.selected
---------------------------------------------------------------------------
| entrance,user,selected        | When a user is selected from the user
| Required: No                  | list.  The user's icon is cloned and
|                               | swallowed into entrance.user.avatar
---------------------------------------------------------------------------
| entrance,user,unselected      | When a user icon choice needs to be
| Required: No                  | reset to the default.
---------------------------------------------------------------------------
| entrance,user,xsession,set    | The current xsession was requested to be 
| Required: No                  | saved as the user's default session
|                               | Source should be ""
---------------------------------------------------------------------------

4. The following signals can be emitted by your application in order
to change states in entrance
---------------------------------------------------------------------------
| Signal		                    | Description/Source
---------------------------------------------------------------------------
| "In"                              | entrance.entry.user or
| Required: No                      | entrance.entry.pass 
|                                   | key input focus will go to the 
|                                   | specified source
---------------------------------------------------------------------------
| "Out"                             | entrance.entry.user or
| Required: No                      | entrance.entry.pass 
|                                   | key input focus will go to the 
|                                   | other entry 
---------------------------------------------------------------------------
| entrance,system,reboot       	    | Reboot System if config allows for it
| Required: No                      | Source should be ""
---------------------------------------------------------------------------
| entrance,system,halt              | Halt System if config allows for it
| Required: No                      | Source should be ""
---------------------------------------------------------------------------
| entrance,user,auth,success,done   | When the theme wants to let the user
| Required: Yes                     | in after succesful authentication.
|                                   | Useful for doing neat things after 
|                                   | success.
|                                   | Source should be ""
----------------------------------------------------------------------------

Example: A basic edc mockup follows.
----------------------------------------------------------------------------
collections { 
group
{
    name, "Main";
    parts
    {
	part {
	name "entrance.entry.pass";
	type, TEXT;
	visible, 1;
	// Doesn't need to be visible, must be present, it gets filled
	// up with *'s as you type, make it invisible to turn echo off
	}
	part {
	name "entrance.entry.user";
	type, TEXT;
	visible, 1;
	text 
	{              
	    text, "";
	    font, "Vera";
	    size, 8;
	    align, 0.5 0.5;
	}               
	// Doesn't need to be visible, must be present, text will be set
	// to the key value for this session
	}
    }
    programs
    {
	program {
	    signal, "entrance,user,auth,success";
	    // After successful login by the user, you can do post auth
	    // animation like thingies here, Emit
	    // "entrance,user,auth,success,done" when finished
	    after, "SuccessDone";
	}
	program {
	    name, "SuccessDone";
	    action, SIGNAL_EMIT "entrance,user,auth,success,done" "";
	    // Let entrance know that post auth anim is over
	    // This MUST be in every theme.
	}
	program {
	    signal, "entrance,user,auth,fail";
	    // Emitted if the password is not accepted, but password failed
	}
	program {
	    signal, "entrance,user,fail";
	    // Emitted if the username is not accepted by the system
	}
	program {
	    signal, "entrance,user,success";
	    // Emitted if the username is accepted by the system
	}
	program {
	    action, SIGNAL_EMIT "entrance,system,reboot" "";
	    // Emitted to tell the system to reboot if config allows
	}
	program {
	    action, SIGNAL_EMIT "entrance,system,halt" "";
	    // Emitted to tell the system to halt if config allows
	}
	program {
	    action, SIGNAL_EMIT "In" "entrance.entry.user";
	    // Emitted to tell the system to move key focus to user
	    // input buffer
	}
	program {
	    action, SIGNAL_EMIT "In" "entrance.entry.pass";
	    // Emitted to tell the system to move key focus to
	    // password input buffer
	}

    }
}
group
{
    name, "Session";
    parts
    {
	part {
	name "entrance.xsessions.selectedIcon";
	type, IMAGE;
	visible, 1;
	// Doesn't need to be visible, or present, the value of
	// /entrance/session/%i/edje gets swallowed here.  It can be an
	// image or another edje
	}
	part {
	name "entrance.xsessions.selectedTitle";
	type, TEXT;
	visible, 1;
	text 
	{              
	    text, "";
	    font, "Vera";
	    size, 8;
	    align, 0.5 0.5;
	}               
	// Doesn't need to be visible, or present, text will be set to
	// the key value for this session
	}
    }
    programs
    {
	program {
	    action, SIGNAL_EMIT "entrance,xsession,selected" "";
	    // Let entrance know that this edje was selected.  See below
	    // for evaluation of the edje on this signal emission
	}
    }
}}
----------------------------------------------------------------------------
FIXME: Document the stuff that's already been implemented :(

/*========================================================================*/
Howto implement sessions in entrance
----------------------------------------------------------------------------
/entrance/session/count - int - the number of users we have
/entrance/session/%i/title - char* - Default text displayed for the session
/entrance/session/%i/icon - char* - path to edje icon file for this session
/entrance/session/%i/session - char* - XSession type to launch 

----------------------------------------------------------------------------
Hash values in two evas hashes
title -> icon mapping
title -> session mapping
----------------------------------------------------------------------------

Each Entrance theme will have their own own defined rect we can swallow
into if they want.  This part should be named entrance.xsessions.list.

Sesssion edjes will look like the following:
A basic edc mockup follows.

----------------------------------------------------------------------------
group
{
    name, "entrance.xsessions.selected";
    parts
    {
	part {
	name "entrance.xsession.icon";
	type, IMAGE;
	visible, 1;
	// Doesn't need to be visible, or present, the value of
	// /entrance/session/%i/edje gets swallowed here.  It can be an
	// image or another edje
	}
	part {
	name "entrance.xsession.title";
	type, TEXT;
	visible, 1;
	text 
	{              
	    text, "";
	    font, "Vera";
	    size, 8;
	    align, 0.5 0.5;
	}               
	// Doesn't need to be visible, or present, text will be set to
	// the key value for this session
	}
    }
    programs
    {
	program {
	    action, SIGNAL_EMIT "entrance,xsession,selected" "";
	    // Let entrance know that this edje was selected.  See below
	    // for evaluation of the edje on this signal emission
	}
    }
}
----------------------------------------------------------------------------
On "entrance,xsession,selected" emissions from sessions we do the following:
1. Query entrance.xsessions.selectedName for the Session we're selecting
2. Lookup the session's edje in in the config system.
3. Load that edje, register a pointer to the object in entrance.xsessions.selected
4. Swallow it into Entrance's main edje in a part called "EnticeSession" if
the part exists.
5. Emit a signal to Entrance's main edje called "entrance,xsession,selected"

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

On "entrance,xsession,selected" emissions from entrance's main edje we do the following:
1. Query the EnticeSession edje for entrance.xsessions.selectedName
2. Set the session string to EntranceSesssionName 
(implement entrance_session_xsession_set() )

----------------------------------------------------------------------------
Loading Sessions:
1. Check for part existence in the Main theme edje for
"entrance.xsessions.list". If !exist returns.
2. Create a container object, set direction based on h or w being larger
3. Iterate over the sessions hashes(evas_hash_foreach)
 3.a. Load entrance.xsessions.selected Group from default theme.
 3.b. Set entrance.xsessions.selectedTitle for current item
 3.c. Load icon from current icon's file
 3.c.i. Success, swallow it into entrance.xsessions.selected group
 3.c.ii. Failure, swallow default icon
 3.d  Append current item to container
4. Swallow container into entrance.xsessions.list
/*========================================================================*/
Howto implement login faces in entrance
----------------------------------------------------------------------------
/entrance/user/count - int - the number of users we have
/entrance/%i/edje - char* - path to user edje on disk
/entrance/%i/user - char* - username for this user

we supply a small app, entrance_useradd, to add a new user to the db w/
sane defaults.

entrance_useradd [options] username
-e : specify the edje for the user, refine if previously defined
-d : delete the user from entrance's user db

Each Entrance theme will have their own own defined rect we can swallow
into if they want.  This part should be named entrance.users.list.

User edjes will look like the following:
They will have a group called "User", and there will be three part
definition possibilities.  The "EntranceUser" part is necessary for all
user edjes.  The data attributes "password" and "session" parameters are
optional.  Furthermore user selected sessions in entrance will override
defined sessions in the user file.  A basic edc mockup follows.

data
{
    item, "password" "mypass";
    item, "session"  "Default";
}

collections { group
{
    name, "User";
    parts
    {
	part {
	name "entrance.user.icon";
	type, TEXT;
	visible, 1;
	// Doesn't need to be visible, as long as there is other content
	// in here, Entrance will query this part for a valid text
	// string when it needs the User's name.
	}
    }
    programs
    {
	program {
	    action, SIGNAL_EMIT "entrance,user,selected" "";
	    // Let entrance know that this edje was selected.  See below
	    // for evaluation of the edje on this signal emission
	}
	program {
	    action, SIGNAL_EMIT "entrance,user,unselected" "";
	    // Let entrance know "i messed up! i clicked the wrong edje,
	    // revert back to as if we had never entrance,users,selected in the
	    // first place.
	}
    }
}}
----------------------------------------------------------------------------
On "entrance,user,selected" emissions from faces we do the following:
1. Query EntranceUser for the user's name.
2. Lookup their edje in in the config system.
3. Load that edje, register a pointer to the object in entrance.xsessions.selected
4. Swallow it into Entrance's main edje in a part called "EnticeFace" if
the part exists.
5. Emit a signal to Entrance's main edje called "entrance,user,selected"

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

On "entrance,user,unselected" emissions from faces we do the following:
1. entrance_session_user_reset()
2. Query entrance's main edje for "entrance.user.avatar" part
3. If part exists, delete it from the evas.

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

On "entrance,user,selected" emissions from entice's main edje we do the following:
1. Query the current "entrance.user.avatar" part and get the username.
2. Set the entrance user to this value, attempt user recognition.
3. If user recognition fails, emit "entrance,user,fail" 
4. If user recognition succeeds, query the current "EdjeFace" for the
session string.
5. If the current session as not yet been set, set if session string
returned was non-null.
6. Query the current "EdjeFace" for the password string
7. If the password string is non-null, attempt system auth with password
supplied.
 7.a. If authentication is successful, emit "entrance,user,auth,success"
 7.b. If authentication fails, goto 8 :)
8. If the password string is null, emit "entrance,user,success" so the theme
goes to its next state.
/*========================================================================*/
