******************************
                         *   Gentoo  Anaconda  port   *
                         ******************************

                         Creating new installer screens
                     by wiktor w brodlo <wiktor@brodlo.net>


Creating new screens for Anaconda is fairly easy. Each screens has two parts:
- a Glade file with the UI elements
- a Python script with functionality

The Glade files are stored in the ui/ directory, the Python scripts - in ui/.
The actual names of files are irrelevant, but it's useful to follow the
convention - call the Glade file screenname.glade, the Python script -
screenname_gui.py.

Your Glade interface should be inside a containter. You will need the name of
this containter in order to load it with your Python script.

The Python script is mostly free-form, but there are certain things that you
need to do.

First of all, import all the modules that you want to use. You will NEED to
import gtk and gtk.glade, otherwise you won't be able to load your UI.

Create a class, it's good to follow the convention call the class
ScreennameWindow. It has to accept InstallWindow as the only argument.

You're free to do anything you want inside the class, but the dispatcher
assumes you have two functions - getNext(self) and getScreen(self, anaconda).
The second parameter of getScreen is the anaconda object with all the settings
etc that you might want.

getNext should return None, and getScreen should return None if you want to,
for any reason, skip the screen (perhaps it is a special screen that handles
some odd case and is otherwise unneeded), or the container box that will be
displayed inside the screen.

Before the screen is shown, getScreen is called. This is the place to create
any default settings and store whatever you'll need in getNexn. The container
it returns will be displayed on the screen (so it is actually possible to
create screens without a Glade file).

When the "Next" button is clicked by the user, getNext is called. This is the
place to store all the settings that you want in the anaconda object. While it
is technically possible to run whatever code, it is recommended that you store
the information that you'll need in anaconda, and run the code later, when the
system is installing (there are some exceptions, just use common sense).

When your screen is finished, you'll need to add it in three places:
- the dispatcher (dispatch.py)
- the install class (installclass.py)
- the GUI (gui.py).

All three parts need to know about your script in order for it to be
displayed. 

In dispatch.py, find installSteps and add your screen. The dispatcher is a
simple state machine that goes through all the screens and displays them in
sequence, assuming they are in the install class and in the GUI.
The syntax is ( name, Function ) where the name is the screenname, and the
Function can be empty or a function *in the dispatcher* that you want to be
called instead of Screenname.getScreen.

In gui.py, add your screen to stepToClass. The syntax is
name: (screen_file, screen_class), where name is the same name that you put in
the dispatcher, the screen_file is the Python script for your screen without
extension ("screenname_gui"), and screen_class is the class in your script
("ScreennameWindow").

In installclass.py, add the name of the screen (the same as you've used for
the previous two files) to dispatch.setStepList in setSteps.

Now, you need to tell the installer to perform some actions based on the
settings the user has entered. You can do this in the gentoo/livecd.py file.
Find the doPreInstall/doInstall/doPostInstall/writeConfiguration functions (as
appropriate, depending on when you want your actions to run) and simply
program in what you want. It's a good idea to create a separate function for
each action to keep the procedures clean - the best place for such functions
is the gentoo/utils.py file. Add your function to the GentooInstall class in
the gentoo/utils.py file and it will be available in gentoo/livecd.py through
self._gentoo_install (it's an instance of the GentooInstall class from
gentoo/utils.py). 

That's it ;-)

Here's a simple Python template:

import gtk
import gtk.glade

class TemplateWindow(InstallWindow):
	def getNext(self):
		# Save your settings to self.anaconda
		return None

	def getScreen(self, anaconda):
		self.anaconda = anaconda
		(self.xml, self.container) = gui.getGladeWidget("sample.glade",
		"sample_box")
		# your widgets will now be available through
		# self.xml.getWidget(widget_name) - keep the xml in self as
		# you'll most likely need it in getNext.
		return self.containter