Archive:Basic overview of the XBMC source code

GUI Library

XBMC uses a coded from scratch gui library to handle all windows, dialogs and controls. The main entry point for the gui library is the Window Manager, GUIWindowManager.

Window Opening and Closing procedure

Windows are activated and deactivated via the GUIWindowManager::ActivateWindow() routine, and it's counterparts, PreviousWindow() and ReplaceWindow(). The window history (ie previous windows) is kept in m_windowHistory in the GUIWindowManager.

Window Opening

Windows are activated by sending the GUI_MSG_WINDOW_INIT message.

The base class (GUIWindow in guilib) then does the following:

• AllocResources() is called.
  • The windows xml skin file is loaded if not already, and OnWindowLoaded() is called.
  • Controls are created + allocated (other than image textures)

• OnInitWindow() is called.
  • Control states are restored if applicable, including the last focused control. Windows by default remember the default control.
  • Initial control visibility is set.
  • Window open animation is queued.
• Overlay state (whether or not the Music or Video overlays are shown) is updated.

Thus, the derived classes should:

• Do anything that needs to be done before the xml skin file is loaded in the OnMessage() routine.
• Do anything that must be done once the xml is loaded and before resources are allocated in OnWindowLoaded() – the base class just sets m_bDynamicResourceAllocation to true.
• Do anything that must be initialized before the window is shown in OnInitWindow(), and call the base class once everything is ready so that it can restore the saved control states and queue animations etc. Calling ResetControlStates() before calling the base class implementation will open the window in a clean state.

Window Closing

Windows are closed when the GUI_MSG_WINDOW_DEINIT message is sent.

The base class (GUIWindow in guilib) then does the following:

• OnWindowDeinit() is called.
  • WindowCloseAnimation() is performed. This generally means that the CApplication::Render() loop is run until the close animation is finished. No user interaction happens during this phase.
  • Control states (list, thumb, scroller positions, and the currently focused control) are saved.

• FreeResources() is called.
  • Control resources are free'd and the xml file is unloaded.
  • OnWindowUnloaded() is called.

Thus, the derived classes should:

• Call the base class first so that any exit animations can be handled.
• Free any dynamically created memory in OnWindowDeinit() after having called the base class implementation.
• Anything that must be free'd after the controls etc. are out of the way should be done in OnWindowUnloaded(), after calling the base class implementation.

Extremely quick overview

Here is a short list of useful key code features in xbmc. This will only be a very quick mockup. For details refer to the code...

a) The filesystem: One of the more elegant features of xbmc is its filesystem classes. These are all located in xbmc/FileSystem. The main interface classes here is IDirectory, IFile and IFileDirectory (virtual directories, e.g. multi-track sid files). Inheriting these we have implemented smb, local, dvd, ftp, rar, zip, xbms, xns, lastfm, shoutcast etc.

b) The DLL loader: Another very important part of xbmc is it's dll-loader. It enables you to add stuff like codecs (see xbmc/cores/paplayer/ICodec.h) in dll's as well as players such as mplayer and the dvdplayer. We have defined macros to make it easy to import from a dll, see DynamicDll?.h or e.g. DllDumb?.h for an example.

The DLL-Loader exports its own versions of the standard io functions such as fopen, fwrite, fseek etc. These versions use the xbmc filesystem. this means that anything living in dll-space can just fopen(smb://foo/bar.foo), very handy.

c) Settings classes: There are two of these, g_guiSettings (GUISettings.cpp) for stuff you can configure from the gui and g_stSettings (Settings.cpp?) for stuff configured from xbmc.xml. See the classes on how to add stuff (fairly easy).

d) Handy stuff: Lots of handy functions in CUtil (Utils.cpp?).

e) The media windows: Example source path: xbmc/GUIWindowVideoFiles.cpp. This is where the actual sections of xbmc are implemented. Admittingly quite a lot of code duplication going one here, but fortunately this means that taking the time to study the workings in one window will get you a very good idea how it works in the others... Key classes of interest here: CFileItem (represents files), CGUIInfoManager (the guru that knows stuff like which song is playing now etc).

To see how the windows are managed see the guilib. Key classes: CGUIWindowManager (the windowmanager that manages stuff like dialogs and windows), CGUIWindow (a window) and CGUIDialog (a dialog like yes/no etc).

f) Other classes of interest: IMusicInfoTagLoader – tag loaders. CStdString – our preferred string implementation Application.cpp – main code

g) There's a fair amount of libs used in xbmc, such as smb, rar, daap client etc or dlls such as the mp3codec. These are not a part of the main project, the source is packed in docs/ or xbmc/lib and the binaries are in cvs..

If you have any further questions, developers can be found in #xbmc on FreeNode from time to time.