Creating a skin for the BOINC Manager

This page describes how to customize the appearance of the BOINC Manager.

Skins

Skins allow you to customize how the BOINC Manager looks in the simple view, the advanced view, and wizard dialogues.

Skins are all collected in the "skins" subdirectory of the working directory.

A skin.xml file needs to be created for any customized skin. This page describes the layout of the skin.xml file.

A skin.xml file should be contained within its own directory under the 'skins' directory.

An example would look like this:

+ /BOINC
|
+---+ /skins
    |
    +---+ /Skin_Name
        |
        +---+ skin.xml
        |
        +---+ <skin resources>

Versions

There have been 2 versions of the Simple View:

• Version 1 had fixed positions for all the window's elements, used bit map images for most of the controls (such as buttons), lacked support for accessibility aids such as screen readers, and was difficult to localize because it required a different set of images for each language.

• Version 2 was introduced with BOINC version 7.0.25 in April 2012. It requires fewer custom bitmap images and window elements, supports screen readers and other accessibility aids, and uses a single set of elements for all languages because it uses standard native controls instead of bitmap images. Because the controls are automatically resized to fit their text in various languages, the window's elements are no longer at fixed predetermined positions. Localization is done at run time by the BOINC Manager's code, using the translation file BOINC-Manager.mo in the locale directory for the desired language.

Version 1 is now considered obsolete. This document describes only version 2.

Layout

The skin.xml file is described as follows:

<skin>
    <en>
        <simple />
        [ <advanced /> ]
        [ <wizards /> ]
    </en>
</skin>

Both the advanced and wizards collections are optional.

Even though localization is no longer handled in the skin.xml file, the 'en' locale tag is still needed for backward compatibility; any data for other locales is ignored.

Skin Collections

Simple

The Simple collection contains all the elements need to construct the Simple GUI.

Version 2 of the Simple View eliminates the need for many of the images in the skins, along with their corresponding entries in the skin.xml file.  It also requires a larger background image and in some cases may require changes to the background artwork of older skins.

The new Simple View is slightly larger than the old version, but the actual size varies depending on the platform (Windows, Macintosh or Linux.)  Since the new version is localizable, the size of the window also varies depending on the selected language.  If you have a custom skin, you should create a larger version of the main background image (specified by the <background_image> tag in the skin.xml file), allowing plenty of extra area to accommodate very long translation strings.

Because most skins have had a logo in the top left corner of the main background image, the new Simple View anchors that corner by default.  In other words, the top left corner of the background will always be at the top left corner of the window, and more or less of the bottom and right-hand areas of the background image will be included depending on the size of the window. As of BOINC version 7.5.1, the background images can optionally be anchored at any of 9 positions, as described later in this document.

If the background bitmap is too small to fill the window, the areas of the window not covered by the bitmap are filled in with the background color specified in the skin.xml file by the <background_color> sub-tag of the <background_image> tag. For example, If a background bitmap is anchored to the top left corner of the window and it is smaller than the window, then the right side and bottom of the window will be filled with the specified color.

Note also that the task information and project information areas will vary in size and position.  Some older skins included 2 contrasting rectangles as part of the main background image, which framed these two areas.  If your skin has these, you should eliminate them as they will no longer align with the controls.  The new Simple View simulates a semi-transparent background for the task information and project information areas, allowing your main background to partially show through.  This will automatically set these areas apart in a manner consistent with your custom skin.  

The same is true for the background of the Simple Preferences dialog specified by the <dialog_background_image> tag in the skin.xml file; it needs to be larger. By default, the dialog_background_image will be anchored at its center. As of BOINC version 7.5.1, the Simple Preferences dialog background images can also be anchored at any of 9 positions.

The new main background image is all you need to be compatible with the new Simple View, though many skins will also provide a dialog background image.  But many other images, and their corresponding skin.xml tags, which were needed by the old Simple View are no longer used and should be eliminated.

The Simple collection now contains the following elements:

Tag	Type	Image Width	Image Height	Notes
background_image	Image	600px or more	750px or more	Used as the Simple GUI background image. A background color should be specified for this element. By default, the image is anchored at its top left corner, so that corner is always visible, but part of the right side and bottom may be cut off depending on the size of the controls after adjusting for localization. As of BOINC version 7.5.1, the image can be anchored at any of 9 positions.
static_line_color	String			The color is represented as an RGB value with the token being ':' Refers to the color of a separator line in the Simple Preferences dialog.
notice_alert_color	String			The color is represented as an RGB value with the token being ':' Refers to the color of the box that blinks around the notices button when new notices are available.
project_image	Image	40px	40px	Default image to display for a project that does not currently have an image defined.
workunit_running_image	Image	16px	16px	Optional icon to show next to tasks which are running. The default workunit_running_image icon will be used if this is not specified.
workunit_waiting_image	Image	16px	16px	Optional icon to show next to tasks which are waiting to run. The default workunit_waiting_image icon will be used if this is not specified.
workunit_suspended_image	Image	16px	16px	Optional icon to show next to tasks which are suspended. The default workunit_suspended_image icon will be used if this is not specified.
panel_opacity	Number			Optional value between 0 and 255 to set the opacity of the semi-transparent background for the task information and project information areas. The default value 153 will be used if this is not specified.
dialog_background_image	Image	800px	600px	The image to be used as the background of the Simple Preferences dialog. This item is optional. The dialog's height and width change according to the configuration of the computer and the locale. By default, the image is anchored at its center, so the center portion of the image is what is drawn on to the dialog. As of BOINC version 7.5.1, the image can be anchored at any of 9 positions. NOTE: This background is also used for the Simple View Notices dialog. If it is smaller than the dialog window, it is stretched as needed to fill that dialog. The user can resize the Simple View Notices dialog, so you may want to make this background larger than 800X600 pixels to minimize the stretching needed. The Simple View Notices dialog background image is always anchored at its center.

As of BOINC version 7.5.1, the following sub-tags may optionally be added under the <background_image> and <dialog_background_image> tags; they are ignored for all other images. Older versions of of BOINC will ignore these tags and will always anchor the images at their default positions (top left for <background_image>, centered for <dialog_background_image>):

Tag	Effect
anchor_horizontal_left	The left side of the image will be anchored to the left side of the window.
anchor_horizontal_center	The image will be centered in the window horizontally.
anchor_horizontal_right	The right side of the image will be anchored to the right side of the window.
anchor_vertical_top	The top of the image will be anchored to the top of the window.
anchor_vertical_center	The image will be centered in the window vertically.
anchor_vertical_bottom	The bottom of the image will be anchored to the bottom of the window.

If conflicting tags appear for the same image, the later one will be honored.

The Simple collection is described as follows:

<simple>
    <background_image>
    [background image details go here]
   </background_image>
   <static_line_color>30:45:59</static_line_color>
    ...
</simple>

Advanced

The Advanced collection contains all the elements needed to construct the Advanced GUI.

The Advanced collection contains the following elements:

Tag	Type	Image Width	Image Height	Notes
application_name	String			Displayed in title bar.
application_short_name	String			Shorter version of the application name
application_help_name	String			Optional application name displayed in text of Help menu item for help with GUI. The default application_name will be used if this is not specified. New in BOINC 7.14.
application_icon	Icon	16px	16px	Taskbar icon. This icon is also displayed in the title bar on Windows systems.
application_icon32	Icon	32px	32px	32-bit version of application_icon
application_disconnected_icon	Icon	16px	16px	Taskbar icon when disconnected.
application_snooze_icon	Icon	16px	16px	Taskbar icon when snoozing.
application_logo	String	50px	50px	Name of the image file for the application logo that should appear in the about box. (This has no background color or transparency mask.)
organization_name	String			Organization associated with the release of the client software package.
organization_website	String			Organization website.
organization_help_url	String			Organization's help url.Parameters: target = which view launched the help request. version = the version of boinc that launched the help request. controlid = which control within the view was the user trying to get help with. See Manager Help System? for further details.
open_tab	Number			Which tab to open by default in the Advanced GUI. A value of '0' means open the last tab used.
exit_message	String			What message should be sent to the user when they close BOINC manager.
is_branded	Number			Set to a value of 1 for customized versions of BOINC distributed by account managers. It should be omitted for all others.

The Advanced collection is described as follows:

<advanced>
    application_name>MyCustomBOINCName</application_name>
    <application_short_name>MyBOINC</application_short_name>
    ...
</advanced>

Wizards

The Wizards collection consists of two elements which are broken out into the attach to project wizard and the attach to account manager wizard.

The attach to project element is described like this:

<attach_to_project>
    <title>Attach to Project</title>
</attach_to_project>

The title is displayed in the wizard's title bar.

The attach to account manager element is described like this:

<attach_to_account_manager>
     <account_info_message></account_info_message>
</attach_to_account_manager>

The account_info_message is text that is displayed when the user is asked for username/email address and password information for the account manager.

The Wizards collection is described as follows:

<wizards>
    <attach_to_project />
    <attach_to_account_manager />
    ...
</wizards>

Skin Basic Elements

Image

Images are used for backgrounds and miscellaneous visual elements.

Images are described as follows:

<image>
    <imagesrc>image.jpg</imagesrc>
    [ <background_color>255:0:255</background_color> ]
</image>

imagesrc describes the name and location of the image in question. Images can be any of the following types: PNG, JPG, GIF, and BMP. The image location should be specified as a path relative to the skin.xml description file. The path separator should be a '/' for all platforms.

NOTE: we have had reports of JPG files not working with background_image and dialog_background_image. If you experience this issue switch the image file format to PNG.

background_color is optional and describes the background color that should be painted on to the dialog before the image is drawn over the top of it. The color is represented as an RGB value with the token being ':'

Here is an example of a background image for the main Simple View window, with the top right corner of the image anchored to the top right corner of the window, and painting a solid magenta color over any areas not covered by the image:

    <background_image>
         <imagesrc>main_background_image.png</imagesrc>
          <background_color>255:0:255</background_color>
          <anchor_vertical_top>
          <anchor_horizontal_right>
   </background_image>

The background_color and anchor tags are optional, but we recommended that you always specify an appropriate background_color for the <background_image> and <dialog_background_image> tags,

Icon

These elements are used to describe the taskbar icons in various states.

Icons are described as follows:

<image>
    <imagesrc>my_icon_image.jpg</imagesrc>
    <transparency_mask>255:0:255</transparency_mask>
</image>

imagesrc describes the name and location of the image in question. Images can be any of the following types: PNG, JPG, GIF, and BMP. The image location should be specified as a path relative to the skin.xml description file. The path separator should be a '/' for all platforms.

transparency_mask describes the background color that should be used as the transparency mask. The color is represented as an RGB value with the token being ':'

Debugging Your Skin

The BOINC Manager has a built-in debugging feature which you can use to list any elements missing from your skin. As of BOINC version 7.3.10, the error messages will be written to the stderrgui.txt file in the per-user BOINC data folder. On Windows, this file can be found at C:\Users\{UserName}\AppData\Roaming\BOINC\stderrgui.txt. On the Mac it is at /Users/{UserName}/Library/Application Support/BOINC/stderrgui.txt.

To enable these messages (as of BOINC 6.6.4), launch the BOINC Manager from the command line with the -c option. On Windows, run the Command Prompt utility (from the start menu: start->All Programs->Accessories->Command Prompt). Then (assuming BONC is installed in its default location) type the following and press the Enter key:

 "C:\Program Files\BOINC\boincmgr.exe" -c

On a Macintosh, run the Terminal application at /Applications/Utilities/Terminal, then type the following and press the return key:

 "/Applications/BOINCManager.app/Contents/MacOS/BOINCManager -c"

It is best to test with different platforms (Windows, Mac, Linux) and different languages.