====== WinLibre Control Center ======

In this page I will describe the control center project and the design I had in mind.

===== Requirements =====

WinLibre's control center should provide the user with a clean and easy-to-use GUI that provides the following options:
  * Launch each of WinLibre's programs
  * Display news items from WinLibre's website and other websites as well
  * Launch the updater tool
  * Easy access to various web services such as: Wikipedia, Google search and more

===== Design =====

The control center program can be divided into three main parts:
  * **WLModule** - A module is a class that provides one functionality (e.g: launching programs, getting news, etc').
  * **WLGUI** - A GUI consists of a few classes
  * **WLControlCenter** - This class gets requests from the GUI, loads an appropriate module and runs it

==== WLModule ====

For every task that WinLibre needs to perform there is a single module. Every module must extend the WLModule class, and needs to override the following (and perhaps additional) functions:

  * //run(parameters)// - Run with the given parameters. For example: the launching module's //run// function with parameters <['firefox', 'http://www.winlibre.com']> will open a new browser window showing WinLibre's home page, calling the updater's //run// function will cause it to check for new updates, and so on.

  * //hasDisplay()// - Return a boolean indicating whether this module has a visual display or not.

  * //getHtmlDisplay()// - Return HTML source as a string. Every module will be displayed in the GUI as a HTML window, that way WinLibre has a web-like look and feel that users a used to, and new modules can be written easily (since HTML is very common, and easier to work with than wxWidgets for most users).

When starting, WinLibre's control Ceter reads a text file with all modules names and loads them one by one, that way adding new functionality to WinLibre is easy: just write a WLModule subclass, put the source code in the same directory as the other modules, and add this module name to the  text file.

The following modules must be implemented

=== WLModuleLaunch ===

This module is responsible for launching different programs. Its //hasDisplay()// function returns False (this module has no display), and therefore its //getHtmlDisplay// return an empty string.\\
The //run()// takes a non-empty list of string, where the first item is the name of the program to be lanched, and the rest of the items (if they exist) are command line arguments to the program

For security reasons this module will only launched programs that are registered as WinLibre programs. The list of registered programs will be generated on startup using an XML file. The same file should be used to keep track of the different versions and will probably be used by the [[updater]] as well, since this part is common to both projects I will continue the discussion about it in the [[collaboration]] page.

=== WLModuleWelcome ===

This module generates the main welcome page. Its run method does nothing (it doesn't really do anything except for generating the HTML source of the welcome page)

=== WLModuleNews ===

This module is responsible for getting news.
I did not think of a complete design yet but I am aware of the following notes:
  * WinLibre news will be updated by default, other services are optional (any RSS feed should work)
  * I can use [[http://feedparser.org/|feedparser.py]] an easy-to-use RSS parser that is written in Python and is self contained in one file
  * I should cach old news in a file so that we can watch them off-line
  * I should use E-Tags to decrease web traffic (and make the news load much faster)
  * I should provide the user with the possibility to check for news updates for each news service

=== WLModuleWebAccess ===

This module is responsible for providing quick access to web services such as Wikipedia, google search and more.\\
I did not work on it yet so I don't have a complete design.

==== WLGUI ====

The idea I had for the GUI was a frame with tabs (Notebook and NotebookPage objects in wxPython). There is a single tab for each module (that has a visual display) that consists of a single WLHtmlWindow (a HtmlWindow subclass).
When starting, the control center adds a tab for each module (that has a visual display) it loads and sets the HTML contents, that way future developers can add new functionality without changing existing wxPython code (actually they don't even need to know wxPython, only HTML).

Advantages of using HTML as the display format:
  * Familiar web-like look and feel
  * HTML is very common and easy to use (easy to write new modules)

Disadvantages of using HTML as the display format:
  * We are limiting future modules 
  * The HtmlWindow object in wxPython does not support the full set of HTML tags - [[http://wxwidgets.org/manuals/2.5.3/wx_wxhtml.html#htmltagssupported|A list of supported tags]] (The IE Window supports all tags, but it is specific to Windows platforms only)

=== WLHtmlWindow ===

The WLHtmlWindow is a regular HtmlWindow with the //OnLinkClicked(link)// function implemented as follows:
Each link will be of the form:
<html>
<a href="Module:Function:parameter1;parameter2;parameter3 ..."> link </a>
</html>

Clicking a link will call the appropriate module's function with the given parameters. This mechanism will be used by all modules to provide access to their functionality.

== NOTE ==
To make things easier we will have (at least this one) special case:
<html>
<a href="http://www.somewhere.com"> somewhere </a>
</html>
Clicking that link will do the expected thing - launch Firefox and open the given link.

==== WLControlCenter ====

The WLControlCenter class is the communication tool between the WLGUI (the user) and the WLModules (the program). The usual cycle will be: WLGUI gets request from the user, sends it to the control center, the control center tells a module to do something useful, and finally the control center sets some visual attributes of the GUI (e.g: User clicks the "//get news//" link, the GUI sends the control center the request, the control center asks the //WLModuleNews// module for a HTML page containing updated news and sets this page as the HTML page of the //News// tab in the GUI).

In addition to that the WLControlCenter is in charge of all the error handling. It catches exceptions raised by the modules, and tells the GUI to display a meaningful error message.

==== Issues ====

These are some issues that I need to think about:
  * Threading - Modules might take some time to perform tasks (especially tasks that depend on information from the web), that's why each module should run in a seperate thread. I am not too familiar with programming with threads so I will have to go over it.
  * Internationalization - The GUI should work in a few languages, as for different layout such as right-to-left for some languages I will have to consult with other people since I don't have too much experience with it (I consider supporting right-to-left languages to be in low priority at the moment).
  * Settings - I must be able to import and export all of WinLibre's settings easily (settings may include: installed programs and versions (has more to do with the updater), registered news services, GUI settings, etc').

===== Schedule and Strategy =====

My programming strategy is some hybrid of XP and usual programming. I like to build a simplistic model of my program, see how things work, then write unit tests and start adding functionality and tests as I go.

My approximated schedule is:
  * 2 weeks - Analysis and design, find useful tools, come up with ideas, build stuff in order to learn from mistake.\\
  * 5 weeks  - Coding, out of which the last 2 weeks should be spent on building the modules and enhancing the GUI, but not the control center (it must be done after 3 coding weeks, the latest)
  * 2 weeks - Testing and Documentation. New features will not be added during these two weeks.

===== Deliverables =====

Python files:

  * GUI
  * WLControlCenter
  * All the WLModules mentioned above
  * Unit tests for all modules
  * Additional source files such as: helper classes, exceptions and more

Text documents (text/doc/pdf/whatever):
  * User's guide
  * Developer's guide
  * Project summary

Additional files:
  * various XML files used for configuration
  * Image files used by the GUI