Documentation

1 files changed, 107 insertions, 0 deletions

diff --git a/docs/creating-screens.txt b/docs/creating-screens.txt
new file mode 100644
index 0000000..f0db983
--- /dev/null
+++ b/docs/creating-screens.txt
@@ -0,0 +1,107 @@
+                         ******************************
+                         *   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
+
+