/** 
@file
@brief Entrance/Entranced 1.0.0 Documentation
 
*/

/**

@mainpage Entrance Developers and Themers Documentation
@image html entrance.png
@author Ibukun Olumuyiwa <ibukun@computer.org> 
@author Corey Donohoe <atmos@atmos.org>
@date 2003-2004

<ol>
<li><a href="index.html#intro">What is Entrance?</a>
<li><a href="./index.html#running">How do I use it?</a><BR>
<ul>
    <li><a href="./index.html#config">Config File</a></li> 
    <li><a href="./index.html#config_theme">Setting the Entrance Theme</a></li> 
    <li><a href="./index.html#config_auth">Setting the Authentication Type</a></li> 
    <li><a href="./index.html#config_pointer">Setting the pointer image</a></li> 
    <li><a href="./index.html#config_datetime">Setting up date and time
    formatting</a></li> 
    <li><a href="./index.html#config_system">Enabling/Disabling Shutdown and
    Reboot</a></li> 
    <li><a href="./index.html#config_engine">Setting the Evas Engine</a></li> 
    <li><a href="./index.html#config_users">Setting up user lists</a></li>
    <li><a href="./index.html#config_sessions">Setting up XSessions</a></li>
    </ul></li>
<li><a href="./index.html#theme">Themers documentation</a><BR>
<ul>
    <li><a href="./index.html#theme_groups">Entrance's Appearance: Edje Groups</a><BR>
    <ul>
    <li><a href="./index.html#theme_entrance_session_parts">The Entrance Group</a></li>
    <li><a href="./index.html#theme_entrance_session_parts">The EntranceSession Group</a></li>
    <li><a href="./index.html#theme_entrance_user_parts">The EntranceUser Group</a></li>
    </ul></li>
    <li><a href="./index.html#theme_signals">Communicating with Entrance : Edje Signals</a><BR>
    <ul>
    <li><a href="./index.html#theme_entrance_progs">Signals your theme
    can emit to Entrance</a></li>
    <li><a href="./index.html#theme_entrance_session_progs">Signals your
    Session can emit to Entrance</a></li>
    <li><a href="./index.html#theme_entrance_progs">Signals your
    User Icons can emit to Entrance</a></li>
    <li><a href="./index.html#theme_entrance_progs">Signals your theme should be aware of</a></li>
    </ul></li>
    <li><a href="index.html#example1">Theme Example 1</a>
    <li><a href="index.html#example2">Theme Example 2</a>
    <li><a href="index.html#example3">Theme Example 3</a>
</ul></li>
<li><a href="index.html#requirements">What does Entrance require?</a>
</ol>

@section intro What is Entrance?
Entrance <I>[en-'trans]</I>, v.<BR>
1 : to carry away with delight, wonder, or rapture<BR>
2 : to put into a trance<BR>

Entrance is the Enlightenment Display Manager. And like Enlightenment,
it takes beauty and customization to levels never seen before.  It allows
users to log in and out of the different Xsession types available on the
system. 

@section running How do I use Entrance ?
Entrance is normally started when the system boots.  It's job is to hang
out and look pretty until someone needs to login to the computer.  

@section config How do I customize Entrance ?
Entrance's goal since day one has been configurability.  Since there are so
many wonderful configuration options available there is, of course, a
configuration file that you must edit in order to take advantage of these
options.  Entrance offers the functionality to change these values, but
first you must locate your config file and open it up in an editor.
@verbatim
$ sudo edb_gtk_ed /etc/entrance_config.db
@endverbatim
You'll see quite a few things displayed with edb_gtk_ed pops up and it
should look something like.
@image html edb_gtk_ed.jpg
Henceforth when directions say to "change the key", you should find the in
the list and change the value in the little box to the right.  You will also
have to click save for these changes to be permanent.

@section config_theme Setting the Entrance Theme
Most of the visible beauty to the user comes from the theme.  You can
download themes in .eet format and copy them to
'/usr/share/entrance/themes'.  If the theme you'd like to run has been
installed, changed the key '<strong>/entrance/themes</strong>' to reflect
the filename of the theme you just installed.   If you'd like to test your
theme without changing your config you can issues this command to load a
theme called "mytheme"
@verbatim
$ entrance -T -t mynewtheme
@endverbatim

@section config_pointer Setting the pointer Image
Entrance allows you to pick an image file as the pointer when using the
mouse.  Open up that wonderful thing we call the entrance system
configuration editor and set the key.
@verbatim
/entrance/pointer  pointer.png
@endverbatim
This should be the full path to Image file on disk that you want to load the
pointer from.  Note png is probably the best format here since you'll get
transparency in the evas.

@section config_datetime Setting up date and time formatting
Entrance allows you to pick date formatting displayed in your theme.  Your
best bet to figuring out the format you'd prefer would be to look at the
strftime manpage.
@verbatim
man 3 strftime
@endverbatim
You can change key '<B>/entrance/date_format</B>' to modify how the date
will be displayed in your theme, and you can change the key
'<B>/entrance/time_format</B>' to modify how the time will be displayed in
your theme.

@section config_system Enabling/Disabling Shutdown and Reboot
Entrance gives the themer an option of telling the system when to reboot and
shutdown.  If this isn't acceptable for your system we offer ways to turn it
off.  Load up your system config tool, and edit your db!
@verbatim
/entrance/system/reboot 1
/entrance/system/halt   1
@endverbatim
Simply set those variables to 0, and Entrance won't allow themers to reboot
your box based on some user interaction. :)

@section config_users Setting up user lists
Entrance will automatically generate your user lists for you as users log in
and out by default.  You can disable this elsewhere in the config.  The
easiest way to setup a user is to log in once. 
First find the file you want to represent you at the login screen, copy it
to the system user directory. For an eet you might.
@verbatim
$ sudo cp myusername.eet /usr/share/entrance/users/ 
@endverbatim
For a jpg or png it might look like the following
@verbatim
$ sudo cp myusername.jpg /usr/share/entrance/users/ 
@endverbatim
Next Edit your system's config db with edb_gtk_ed.  You'll see your username
somewhere in the list(unless of course you've disabled this feature)  
@verbatim
/entrance/users/0/name myusername
/entrance/users/0/icon default.eet
/entrance/users/0/session Enlightenment
@endverbatim
You can change the /entrance/users/0/icon attribute to point to the file you
copied to your users directory.  NOTE: The image file must be a format your
evas has a loader for.  

@section config_sessions Setting up XSessions
Hopefully we'll have an application to do this for us soon.  If it makes
sense to you, you'll figure it out, if not sorry it can be rather painful on
some systems.  Do not that <strong>~/.xsession</strong> will be executed
on most systems if you choose the "Default" session from the session list.
If you don't have a <strong>~/.xsession</strong>, create your own!  It
should look something like the following.
@verbatim
eval `ssh-agent`
exec /usr/bin/enlightenment
@endverbatim
Please be sure that <strong>~/.xsession</strong> is executable.  
@verbatim
$ chmod +x ~/.xsession
@endverbatim

@section config_auth Setting up the Authentication Type
Most systems use pam for authentication and you won't need to change this
for the most part.  If you're on a system lacking pam support you can use
the shadow support entrance also offers.  Load up your system's
configuration in edb_gtk_ed and change the 
@verbatim
/entrance/auth 1
@endverbatim
<ol>
<li>Set this variable to 1 if you want pam authentication</li>
<li>Set this variable to 2 if you want shadow authentication</li>
</ol>
@section config_engine Setting the Evas Engine
Some systems have GL built into their evas and ecore_evas systems.  We offer
the ability to use this feature, but don't support any problems you find
running under the GL Engine.  If it works in software_x11 and not in GL it's
considered a GL bug.  To try out Entrance in GL mode you need to 
load up your system's configuration in edb_gtk_ed and change the 
@verbatim
/entrance/engine software 
@endverbatim
<ol>
<li>Set this variable to "software" if you want software_x11 ecore evas</li>
<li>Set this variable to "gl" if you want gl_x11 ecore_evas </li>
</ol>

@section example1 Example One 
You'll need to get comfortable with Edje.  This is not an intro to Edje,
perhaps you'll need to look at examples, or possibly
http://www.cuddletech.com/edje/ but if you don't get Edje, sorry come
back later.  That being said, let's get a barebones entrance theme up
and running.  

@verbatim
$ cd
$ mkdir mytheme
$ cd mytheme
$ mkdir images
$ vim cg
# cg contains the following info
#!/bin/sh -e
if [ -f ./mytheme.eet ]; then
    rm -f mytheme.eet
fi
edje_cc -v -id ./image mytheme.edc mytheme.eet
if [ -f ./mytheme.eet ]; then
    edje mytheme.eet
fi
$ chmod +x cg
$ vim mytheme.edc # your favorite editor will suffice here
// This is the contents of your basic theme.
images { }
collections {
    group {
	name, "Main";
	parts {
	    part {
		name, "bg";
		type, RECT;
		mouse_events, 0;
		description {
		    state, "default" 0.0;
		    visible, 1;
		    rel1 { 
			relative, 0.0 0.0;
			offset, 0 0;
		    } rel2 {
			relative, 1.0 1.0;
			offset, 0 0;
		    }
		    color, 0 0 0 255;
		}
	    }
	    part {
		name, "entrance.entry.user";
		type, TEXT;
		mouse_events, 0;
		description {
		    state, "default" 0.0;
		    rel1 { 
			relative, 0.5 1.0;
			offset, -100 -71;
			to, "bg";
		    } rel2 {
			relative, 0.5 1.0;
			offset, 100 -36;
			to, "bg";
		    }
		    color, 255 255 255 255;
		    text {
			text, "";
			font, "Vera";
			size, 20;
			fit, 0 0;
			align, 0.5 0.5;
		    }
		}
	    }
	    part {
		name, "entrance.entry.pass";
		type, TEXT;
		mouse_events, 0;
		description {
		    state, "default" 0.0;
		    visible, 1;
		    rel1 { 
			relative, 0.5 1.0;
			offset, -100 -35;
			to, "bg";
		    } rel2 {
			relative, 0.5 1.0;
			offset, 100 -5;
			to, "bg";
		    }
		    color, 255 255 255 255;
		    text {
			text, "";
			font, "Vera";
			size, 20;
			fit, 0 0;
			align, 0.5 0.5;
		    }
		}
	    }
	}
	programs {
	    program {
		name, "authed";
		signal, "entrance,user,auth,success";
		source, "";
		action, SIGNAL_EMIT "entrance,user,auth,success,done" "";
	    }
	}
    }
}
@endverbatim

If everything worked ok, you should get something like <a
href="Example1.jpg">Example1</a>.  So what's worth taking notice of? 
The group "Main" is what entrance loads and fills the screen with.<BR>
<B>Edje Parts</B><ul>
<li><B>EntranceUserEntry:</B> is a text part, this is where keyboard
input goes if the system is in a state accepting username
input.<B>REQUIRED</B>
<li> <B>EntrancePassEntry:</B> is a text part, this is where keyboard
input goes if the system is in a state accepting the user's
password.<B>REQUIRED</B>
</ul>
<B>Edje Signals</B><ul>
<li><B>EntranceUserAuthSuccess:</B> Entrance emits this signal when the
user successfully authenticates.  A program must always exist in your
theme that catches this signal.  The idea behind this is that you can
have neat effects after the user successfully logs in.  
<li><B>EntranceUserAuthSuccessDone:</B> It's the themer's job to let
Entrance know that it's done and the user's session should start by
emitting this signal.
</ul>

@section example2 Example Two
You're probably thinking that Example 1 was really lame, and
contemplating skipping Example Two because it's just too basic, but bare
with me.  Example Two shows off a few of the built in features that
themers can take advantage of.  This is where your creativity steps in,
presenting these builtins in a pleasing manner.  You can see a preview
of it <a href="Example2.jpg">here</a>. Notice it's still not the
prettiest thing, but it was made without specifying a single image file.
:)

@verbatim
$ cd
$ mkdir mysecondtheme
$ cd mysecondtheme
$ mkdir images
$ vim cg
# cg contains the following info
#!/bin/sh -e
if [ -f ./mysecondtheme.eet ]; then
    rm -f mysecondtheme.eet
fi
edje_cc -v -id ./image mysecondtheme.edc mysecondtheme.eet
if [ -f ./mysecondtheme.eet ]; then
    edje mysecondtheme.eet
fi
$ chmod +x cg
$ vim mysecondtheme.edc # your favorite editor will suffice here
images { }
collections {
    group {
	name, "Main";
	parts {
	    part {
		name, "bg";
		type, RECT;
		mouse_events, 0;
		description {
		    state, "default" 0.0;
		    visible, 1;
		    rel1 { 
			relative, 0.0 0.0;
			offset, 0 0;
		    } rel2 {
			relative, 1.0 1.0;
			offset, 0 0;
		    }
		    color, 0 0 0 255;
		}
	    }
	    part {
		name, "BottomBar";
		type, RECT;
		mouse_events, 1;
		description {
		    state, "default" 0.0;
		    visible, 1;
		    rel1 {
			relative, 0.0 1.0;
			offset, 0 -50;
		    } rel2 {
			relative, 1.0 1.0;
			offset, 0 0;
		    }
		    color, 100 100 100 96;
		}
	    }
	    part {
		name, "entrance.entry.user";
		type, TEXT;
		mouse_events, 0;
		description {
		    state, "default" 0.0;
		    rel1 { 
			relative, 0.5 1.0;
			offset, -100 -71;
			to, "bg";
		    } rel2 {
			relative, 0.5 1.0;
			offset, 100 -36;
			to, "bg";
		    }
		    color, 255 255 255 255;
		    text {
			text, "";
			font, "Vera";
			size, 20;
			fit, 0 0;
			align, 0.5 0.5;
		    }
		}
	    }
	    part {
		name, "entrance.entry.pass";
		type, TEXT;
		mouse_events, 0;
		description {
		    state, "default" 0.0;
		    visible, 1;
		    rel1 { 
			relative, 0.5 1.0;
			offset, -100 -35;
			to, "bg";
		    } rel2 {
			relative, 0.5 1.0;
			offset, 100 -5;
			to, "bg";
		    }
		    color, 255 255 255 255;
		    text {
			text, "";
			font, "Vera";
			size, 20;
			fit, 0 0;
			align, 0.5 0.5;
		    }
		}
	    }
	    part {
		name, "entrance.hostname";
		type, TEXT;
		mouse_events, 0;
		description {
		    state, "default" 0.0;
		    visible, 1;
		    rel1 { 
			relative, 0.5 0.0;
			offset, -200 -35;
			to, "entrance.entry.user";
		    } rel2 {
			relative, 0.5 0.0;
			offset, 200 -5;
			to, "entrance.entry.user";
		    }
		    color, 255 255 255 255;
		    text {
			text, "";
			font, "Vera";
			size, 20;
			fit, 0 0;
			align, 0.5 0.5;
		    }
		}
	    }
	    part {
		name, "entrance.date";
		type, TEXT;
		mouse_events, 0;
		description {
		    state, "default" 0.0;
		    visible, 1;
		    rel1 { 
			relative, 1.0 1.0;
			offset, -300 -25;
			to, "bg";
		    } rel2 {
			relative, 1.0 1.0;
			offset, -10 -10;
			to, "bg";
		    }
		    color, 255 255 255 255;
		    text {
			text, "";
			font, "Vera";
			size, 10;
			fit, 0 0;
			align, 1.0 0.5;
		    }
		}
	    }
	    part {
		name, "entrance.time";
		type, TEXT;
		mouse_events, 0;
		description {
		    state, "default" 0.0;
		    visible, 1;
		    rel1 { 
			relative, 1.0 1.0;
			offset, -300 -40;
			to, "bg";
		    } rel2 {
			relative, 1.0 1.0;
			offset, -10 -25;
			to, "bg";
		    }
		    color, 255 255 255 255;
		    text {
			text, "";
			font, "Vera";
			size, 10;
			fit, 0 0;
			align, 1.0 0.5;
		    }
		}
	    }
	    part {
		name, "EntranceError";
		type, TEXT;
		mouse_events, 0;
#define ERROR(sname, sdescription) \
description { state, sname 0.0; visible, 1; \
rel1 { relative, 0.0 1.0; offset, 5 -35; to, "bg"; }  \
rel2 { relative, 1.0 1.0; offset, -5 -5; to, "bg"; } \
color, 255 255 255 255; \
text { text, sdescription; \
font, "Vera"; size, 20; fit, 0 0; align, 1.0 0.5; } }
		ERROR("default", "");
		ERROR("userfail", "Unknown User");
		ERROR("passfail", "Authentication Failed");
	    }
	    part {
		name, "entrance.xsessions.list";
		type, RECT;
		mouse_events, 1;
		dragable {
		    x, 1 1 0;
		    y, 1 1 0;
		}
		description {
		    state, "default" 0.0;
		    visible, 1;
		    rel1 {
			relative, 1.0 0.5;
			offset, -205 -180;
		    } rel2 {
			relative, 1.0 0.5;
			offset, -25 180;
		    }
		    color, 255 255 255 64;
		}
	    }
	    part {
		name, "SessionLabel";
		type, TEXT;
		mouse_events, 0;
		effect, SOFT_SHADOW;
		description {
		    state, "default" 0.0;
		    visible, 1;
		    rel1 { 
			relative, 0.0 0.0;
			offset, 0 -30;
			to, "entrance.xsessions.list";
		    } rel2 {
			relative, 1.0 0.0;
			offset, 0 -5;
			to, "entrance.xsessions.list";
		    }
		    color, 255 255 255 255;
		    color3, 0 0 0 192;
		    text {
			text, "Sessions";
			font, "Vera";
			size, 10;
			fit, 0 0;
			align, 0.5 0.5;
		    }
		}
	    }
	    part {
		name, "entrance.users.list";
		type, RECT;
		mouse_events, 1;
		dragable {
		    x, 1 1 0;
		    y, 1 1 0;
		}
		description {
		    state, "default" 0.0;
		    visible, 1;
		    rel1 {
			relative, 0.0 0.25;
			offset, 100 -25;
		    } rel2 {
			relative, 0.0 0.25;
			offset, 210 25;
		    }
		    color, 255 255 255 64;
		}
	    }
	    part {
		name, "UsersLabel";
		type, TEXT;
		mouse_events, 0;
		effect, SOFT_SHADOW;
		description {
		    state, "default" 0.0;
		    visible, 1;
		    rel1 { 
			relative, 0.0 0.0;
			offset, 0 -30;
			to, "entrance.users.list";
		    } rel2 {
			relative, 1.0 0.0;
			offset, 0 -5;
			to, "entrance.users.list";
		    }
		    color, 255 255 255 255;
		    color3, 0 0 0 192;
		    text {
			text, "Users";
			font, "Vera";
			size, 10;
			fit, 0 0;
			align, 0.5 0.5;
		    }
		}
	    }
	    part {
		name, "entrance.users.avatar";
		type, RECT;
		mouse_events, 1;
		description {
		    state, "default" 0.0;
		    visible, 1;
		    rel1 {
			relative, 0.0 0.5;
			offset, 100 -50;
		    } rel2 {
			relative, 0.0 0.5;
			offset, 300 50;
		    }
		    color, 100 100 100 0;
		}
	    }
	    part {
		name, "entrance.xsessions.selected";
		type, RECT;
		mouse_events, 1;
		description {
		    state, "default" 0.0;
		    visible, 1;
		    rel1 {
			relative, 0.0 1.0;
			offset, 0 -45;
		    } rel2 {
			relative, 0.0 1.0;
			offset, 200 -5;
		    }
		    color, 100 100 100 0;
		}
	    }
	}
	programs {
	    program {
		name, "authed";
		signal, "entrance,user,auth,success";
		source, "";
		action, SIGNAL_EMIT "entrance,user,auth,success,done" "";
	    }
	    program {
		name, "errorreset";
		signal, "";
		source, "";
		action, STATE_SET "default" 0.0;
		target, "EntranceError";
		in, 2.0 0.0;
	    }
#define ERROR_PROGRAM(pstate, psignal) \
program { name, pstate; signal, psignal; source, ""; \
action, STATE_SET pstate 0.0; target, "EntranceError"; \
after, "errorreset"; }
	    ERROR_PROGRAM("userfail", "entrance,user,fail");
	    ERROR_PROGRAM("passfail", "entrance,user,auth,fail");
	}
    }
    group
    {
	name, "Session";
	parts
	{
	    part
	    {
		name, "entrance.xsession.icon";
		type, RECT;
		mouse_events, 1;
		description
		{
		    state, "default" 0.0;
		    visible, 1;
		    rel1
		    {
			relative, 0.0 0.0;
			offset, 2 2;
		    }
		    rel2
		    {
			relative, 0.0 0.0;
			offset, 34 34;
		    }
		    color, 255 255 255 0;
		}
	    }
	    part
	    {
		name, "entrance.xsession.title";
		type, TEXT;
		mouse_events, 1;
		effect, SOFT_SHADOW;
		description
		{
		    state, "default" 0.0;
		    visible, 1;
		    rel1
		    {
			relative, 1.0 0.5;
			offset, 2 -17;
			to, "entrance.xsession.icon";
		    }
		    rel2
		    {
			relative, 1.0 0.5;
			offset, 150 17;
			to, "entrance.xsession.icon";
		    }
		    color, 100 100 100 192;
		    color3, 255 255 255 255;
		    text
		    {
			text, "Doesn't Matter";
			font, "Vera";
			size, 13;
			align, 0.0 0.5;
			fit, 0 0;
		    }
		}
	    }
	}
	programs
	{
	    program
	    {
		name, "SessionIconClicked";
		signal, "mouse,clicked,1";
		source, "entrance.xsession.icon";
		action, SIGNAL_EMIT "entrance,xsession,selected" "";
	    }
	    program
	    {
		name, "SessionTitleClicked";
		signal, "mouse,clicked,1";
		source, "entrance.xsession.title";
		action, SIGNAL_EMIT "entrance,xsession,selected" "";
	    }
	}
    }
}
@endverbatim
<B>Oy!</B> That's a lot!  Most notably Example2 has a second Edje group
defined,"Session".<BR><p>Entrance will use the "Session" group as
a template and fill in the different parts with system specific session
information.<BR>
<B>Edje Parts</B><ul> 
<li><B>EntranceSessionTitle</B>, Is a text part, the text will be set by
the system to the appropriate session's name.
<li><B>EntranceSessionIcon</B>.  Is a rect part, the icon is swallowed
into this area if present.
</ul>
<B>Edje Signals</B><ul> 
<li><B>SessionSelected:</B> Your "Session" edje emits this signal when
it requests entrance to accept it as the new chosen session.
<li><B>SessionUnSelected:</B> Your "Session" edje emits this signal when
it requests Entrance to deselect it as the current x session.
</ul>
<p>Now lets focus our attention back to the "Main" group.  <BR>
<B>Edje Parts</B><ul>
<li><B>EntranceHostname:</B> EntranceHostname is a text part that will
be filled with the greeting specified in the system configuration.
<li><B>EntranceTime:</B> EntranceTime is a text part that will be filled
with the current time every second.  The time format is specified in the
system configuration.  If this part is present, it'll display the right
time :)
<li><B>EntranceDate:</B> EntranceDate is a text part that will be filled
with the current date.  The format for the date is specified in the
system configuration file.
<li><B>EntranceSession:</B> EntranceSession is a rect part that will
swallow the currently selected session.  If this part is present, an
instance of the "Session" group will be swallow to this rectangle.
<li><B>EntranceFace:</B> EntranceFace is a rect part that will swallow
the currently selected user icon.  If this part is present a unique
edje specific to that user will be displayed in that region.
<li><B>EntranceSessionList</B> EntranceSessionList is a rect part that
will swallow a list of "Session" group edjes.  The sessions available on
each system may vary, Entrance will properly pack all the available
xsessions into this area that the system configuration specifies.  
<li><B>EntranceUserList</B> EntranceUserList is a rect part that will
swallow a list of users the system knows about.  The themer need only
define the area they should be swallowed into, Entrance will handle
adding them.
</ul>
<B>Edje Signals</B><ul>
<li><B>EntranceUserFail:</B> Emitted if the username entered in
EntranceUserEntry is unknown to the system.
signal.
<li><B>EntranceUserAuthFail:</B> Emitted if the password entered in the
EntrancePassEntry fails to authenticate with the system.
</ul>

@section example3 Example Three

Example Three is the fun and powerful part of Entrance.  As you might have
noticed during <a href="index.html#example2">Example Two</a> we're starting to
have more and more edje parts in this theme.  Before long we could have a few
thousand lines of .edc code that could end up being tough to understand.  Let's
divert our attention to a <a href="./EntranceThemeTemplate.tar.gz">theme
template</a>.  This is a stripped down framework from the example that follows,
and should serve as a decent skeleton for anyone wanting to write their own
Entrance theme.  Armed with this theme template, it's time for the themer to
brainstorm.</p>
<p>You have to have some sort of idea of what you want your login screen to
look like to go any further.  My idea coming into Example 3 was
<ul>
<li>Use all the signals available in Entrance
<li>Keep the different parts of the code readable as an example
<li>Allow for minimization of the SessionList and UserList
<li>Have some sort of animation when no EntranceFace is displayed
<li>Have nice borders for every "window" in the theme
<li>"Shake Off" bad user and password input
<li>Make it pretty
</ul>

So I hit the web and found a high resolution photo that <a
href="http://www.cozmo85.net">a friend</a> had taken, and I had my
background.  I've always been very impressed by the themes <a
hreft="http://tokyo.cored.org">Tokyo</a> comes up with, and I pieced together
the borders from his e16 theme "Presence" in <a
hreft="http://www.gimp.org">The Gimp</a>.  Gathering images was a lengthy
process, but after digging around in other themes long enough I was ready to
begin.  </p>
<p>Using the template file above, I started working on the theme part by
part, testing it as I went along. 
@verbatim
$ ./cg
$ sudo cp mynewtheme.eet /usr/share/entrance/themes/
$ entrance -T -t mynewtheme
@endverbatim
Sub-Edjes, smaller components of the whole edje, can be designed
independently, and reused if they're written with proper care.  In order to
make things more clear, Edje parts that have to do with entrance are
LabeledSoTheyAreEasyToIdentify, while Edje parts that are not relevant to
Entrance are named in lower case. Also notice that the programs for each
sub-edje are broken out for coherency also.</p>
<p>
What follows the main edc for Example3, titled "Headlights".  A short divx4
capture(poor quality) is available <a
href="http://www.atmos.org/files/entrance.avi">here</a>.  A screenshot of
this theme doesn't do it justice, the animation present has to be captured
by video.  The complete <a href="./EntranceExample3.tar.gz">source code</a>
and images are available, and the reader is encouraged to disect this source
code.  

@verbatim
/***************************************************************************
 * Corey Donohoe<atmos@atmos.org>
 * Theme: taillights
 *
 * Borders by Tokyo : tokyo.cored.org
 * Various images by Rephorm: www.rephorm.com
 * Background by Roy Wagner : www.cozmo85.net
 * Various images by Raster : www.rasterman.com
 **************************************************************************/

#define DEBUG 0

/**
 * include our image { } block elsewhere
 */
#include "images/images.edc"

collections {
    group {
	name, "Main";
	parts {

/** provides:
 * EntranceDate 
 * EntranceTime
 * bottom_bar 
 */ 
#include "parts/bg.edc"

/** provides: 
 * error_string 
 * error_string_clip  
 */
#include "parts/error_string.edc"

/**
 * provides: 
 * EntranceSessionList 
 * session_list_border 
 * session_list_clip  
 */
#include "parts/session_list_area.edc"

/**
 * provides: 
 * EntranceUserList 
 * user_list_border 
 * user_list_clip 
 */
#include "parts/user_list_area.edc"

/**
 * provides: 
 * EntranceSession 
 * session_clip 
 * session_description 
 */
#include "parts/entrance_session.edc"

/**
 * provides: 
 * power_button 
 * power_button_description 
 */
#include "parts/power_button.edc"

/**
 * provides: 
 * restart_button 
 * restart_button_description 
 */
#include "parts/restart_button.edc"

/**
 * provides:
 * EntranceFace 
 * EntranceUserEntry 
 * EntrancePassEntry
 * EntranceHostname 
 * login_border 
 * login_area_clip
 */
#include "parts/login_area.edc"

#if DEBUG
#include "parts/debug.edc"
#endif

/**
 * provides:
 * confirmation_reboot_clip
 * confirmation_reboot_yes
 * confirmation_reboot_no
 * 
 * confirmation_halt_clip
 * confirmation_halt_yes
 * confirmation_halt_no
 *
 */
#include "parts/confirmation_dialog.edc"
	}
	programs {
	    program {
		name, "authed";
		signal, "entrance,user,auth,success";
		source, "";
		action, SIGNAL_EMIT "entrance,user,auth,success,done" "";
	    }
#if DEBUG
#include "programs/debug_programs.edc"
#endif

/**
 * emit signals to entrance related to the system, AFTER the user
 * clicks "Yes" on the confirmation dialog
 * Also handle showing/hiding of the confirmation dialogs
 * 
 * EntranceSystemHalt
 * EntranceSystemReboot
 *
 */
#include "programs/confirmation_dialog_programs.edc"

/**
 * handle EntranceSessionList callbacks:
 * minimize, show, etc 
 */
#include "programs/session_list_area_programs.edc"

/**
 * handle EntranceUserList callbacks:
 * minimize, show, etc 
 */
#include "programs/user_list_area_programs.edc"

/** 
 * catch signals from entrance, related to the login area
 *
 * EntranceUserAuth
 * EntranceUserFail
 * EntranceUserAuthFail
 *
 * UserSelected
 * UserUnSelected
 */
#include "programs/login_area_programs.edc"

/** 
 * provide mouse effects to the power button
 */
#include "programs/power_button_programs.edc"

/** 
 * provide mouse effects to the restart button
 */
#include "programs/restart_button_programs.edc"

/** 
 * catch signals from entrance, related to the error messages
 *
 * EntranceUserAuth
 * EntranceUserFail
 * EntranceUserAuthFail
 */
#include "programs/error_string_programs.edc"

/**
  * macro defined to make the fade effect on all the windows easy to
  * maintain
  */
#include "programs/effects_programs.edc"
 
 /**
  * enable user auto save of the sessions they select 
  */
#include "programs/session_save_dialog_programs.edc"

	}
    }
/**
 * Session Group
 */
    group
    {
	name, "Session";
	parts
	{
/**
 * provides the EntranceSessionIcon and EntranceSessionTitle parts
 */
#include "parts/session_group.edc"
	}
	programs
	{
/**
 * emit the following signals to entrance, 
 * SessionSelected and
 * SessionUnSelected
 */
#include "programs/session_group_programs.edc"
	}
    }
    group
    {
	name, "User";
	parts
	{
/**
 * provides the EntranceUserIcon and EntranceUserName parts
 */
#include "parts/user_group.edc"
	}
	programs
	{
/**
 * emit the following signals to entrance, 
 * UserSelected and
 * UserUnSelected
 */
#include "programs/user_group_programs.edc"

	}
    }
}
@endverbatim

Perhaps it's just me, but this edc reads a lot smoother than the first two.
Perhaps because we can see the different components of the Edje at a much
higher level, or perhaps because this one has comments describing what each
of the #include operations are doing.</p>
<p>Somethings to perhaps keep in mind as you're writing themes might be
<ul>
<li>Keep the main .edc simple enough that even someone who isn't an edje
wizard could walk up to this theme and change the background to one that
they'd prefer.
<li>Planning it out on the frontend will save you tons of rewriting
</ul>
</p>
<p>If you found this theme tutorial useful or useless please let <a
href="http://www.atmos.org/contact/">me</a> known.</p>

@section requirements What does Entrance require?

The only distribution we're currently aware of supporting Entrance is <a
href="http://www.gentoo.org/">Gentoo</a>.  You can compile it from cvs
using the following libraries if you're brave.

Entrance relies on a lot of libraries most notably
  - Edb (library)
  - Eet (library)
  - Evas (library)
  - Ecore (library)
  - Edje (library)
  - Esmart (library)

There is no need to reinvent the wheel all the time.

@verbatim
1. You need Edb from cvs

  cvs co e17/libs/edb
  cd e17/libs/edb
  ./autogen.sh
  ./configure
  make
  sudo make install
  cd

2. You need eet from cvs

  cvs co e17/libs/edb
  cd e17/libs/edb
  ./autogen.sh
  ./configure
  make
  sudo make install
  cd

3. You need Evas from cvs

  cvs co e17/libs/evas
  cd e17/libs/evas
  ./autogen.sh
  make
  sudo make install
  cd
  
4. You need Ecore from cvs

  cvs co e17/libs/ecore
  cd e17/libs/ecore
  ./autogen.sh
  make
  sudo make install
  cd

5. You need Edje from cvs

  cvs co e17/libs/edje
  cd e17/libs/edje
  ./autogen.sh
  make
  sudo make install
  cd

6. You need Esmart from cvs

  cvs co e17/proto/esmart
  cd e17/proto/esmart
  ./autogen.sh
  make
  sudo make install
  cd

7. You need entrance from cvs

  cvs co e17/apps/entrance
  cd e17/apps/entrance
  ./autogen.sh
  make
  sudo make install
  cd

@endverbatim

@todo 
<ul>
<li>XDMCP Work
<li>Update Themeing namespace to something cleaner</li>
<li>Redocument theme api...AFTER namespace cleanup</li>
<li>User and Initial boot autologin...</li>
<li>Config opt whether to show theme post auth on autologin, or to just
start the session immediately.</li>
</ul>

*/
