Creating a skin for the BOINC Manager

From BOINC
Jump to: navigation, search

Contents

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 are 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.

It is possible to create a skin which works with both version 1 and version 2. We will describe this throughout this document.

Localization

Version 1 only:

BOINC Manager attempts to find and use localized skin references. It falls back to a suitable language and if none can be found it will fall back to English. Overriding the language being searched for can be done in the Advanced GUI's option dialog.

If the current locale is 'pt_BR' and it cannot be found in the selected skin then the next language searched for is 'pt'. If 'pt' cannot be found then the manager resorts to 'en'.

Skin choice Example
Locale pt_BR
Language pt
English en
BOINC built-in skin BOINC built-in skin

Version 2:

Only the data for the 'en' locale is used. Localization is done in the Manager's code, not by having different sections of the skin for each language.

Layout

The skin.xml file is described as follows:

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

Both the advanced and wizards collections are optional.

Version 2:

Only the data for the 'en' locale is used; data for all other locales is ignored.

Samples

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 a logo in the top left corner of the main background image, the new Simple View anchors that corner.  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.

For backward compatibility, if the background bitmap is too small, the right side and bottom are filled in with the background color specified in the skin.xml file by the <background_color> sub-tag of the <background_image> tag.

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 frame 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, and will be anchored at its top left corner.

The new main and preferences background images are all you need to be compatible with the new Simple View.  But many other images, and their corresponding skin.xml tags, which were needed by the old Simple View are no longer required and can be eliminated.

The Simple collection contains the following elements:

Name 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. The top left corner is always visible, but part of the right side and bottom will be cut off depending on the size of the controls after adjusting for localization.
spacer_image Image 2px 11px Used to separate the links on the bottom of the Simple GUI (version 1 only; not used in version 2.)
static_line_color String The color is represented as an RGB value with the token being ':'
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.
state_indicator_background_image Image 264px 35px (version 1 only; not used in version 2.)
connecting_indicator_image Image 14px 15px (version 1 only; not used in version 2.)
error_indicator_image Image 69px 20px (version 1 only; not used in version 2.)
workunit_active_tab Simple Tab 16px 16px (version 1 only; not used in version 2.)
workunit_suspended_tab Simple Tab 16px 16px (version 1 only; not used in version 2.)
workunit_tab_area_background_image Image 343px 24px (version 1 only; not used in version 2.)
workunit_area_background_image Image 343px 314px (version 1 only; not used in version 2.)
workunit_animation_background_image Image 294px 146px (version 1 only; not used in version 2.)
workunit_animation_image Image 290px 126px (version 1 only; not used in version 2.)
workunit_gauge_background_image Image 258px 18px (version 1 only; not used in version 2.)
workunit_gauge_progress_indicator_image Image 8px 7px (version 1 only; not used in version 2.)
project_area_background_image Image 343px 113px (version 1 only; not used in version 2.)
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 (version 2 only; 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 (version 2 only; 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 (version 2 only; 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 (version 2 only; 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.
attach_project_button Simple Button 81px 18px (version 1 only; not used in version 2.)
right_arrow_button Simple Button 20px 20px (version 1 only; not used in version 2.)
left_arrow_button Simple Button 20px 20px (version 1 only; not used in version 2.)
save_button Simple Button 57px 16px (version 1 only; not used in version 2.)
synchronize_button Simple Button 81px 18px (version 1 only; not used in version 2.)
cancel_button Simple Button 57px 16px (version 1 only; not used in version 2.)
close_button Simple Button 57px 16px (version 1 only; not used in version 2.)
help_button Simple Button 18px 18px (version 1 only; not used in version 2.)
copy_all_button Simple Button 85px 18px (version 1 only; not used in version 2.)
copy_button Simple Button 85px 18px (version 1 only; not used in version 2.)
messages_link_image Simple Link 70px 20px (version 1 only; not used in version 2.)
messages_alert_link_image Simple Link 70px 20px (version 1 only; not used in version 2.)
suspend_link_image Simple Link 59px 20px (version 1 only; not used in version 2.)
resume_link_image Simple Link 59px 20px (version 1 only; not used in version 2.)
preferences_link_image Simple Link 81px 20px (version 1 only; not used in version 2.)
advanced_link_image Simple Link 101px 20px (version 1 only; not used in version 2.)
dialog_background_image Image 800px 600px The dialogs height and width change according to the configuration of the computer (and in version 2 the locale), so the center of the image is what is drawn on to the dialog. NOTE: This background is also used for the Simple View Notices dialog, and is stretched as needed to fit 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 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 need to construct the Advanced GUI.

The Advanced collection contains the following elements:

Name Type Image Width Image Height Notes
application_name String Displayed in title bar.
application_short_name String Shorter version of the application name
application_icon Icon 16px 16px Taskbar icon. This icon is also displayed in the title bar on Windows systems.
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>
    <logo>graphic/logo.png</logo>
</attach_to_project>

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

version 1 only: The logo is placed on each wizard page and should have a height of 280px and a width of 115px. Logos can be any of the following types: PNG, JPG, GIF, and BMP. The logo location should be specified as a path relative to the skin.xml description file. The path separator should be a '/' for all platforms.

The attach to account manager element is described like this:

<attach_to_account_manager>
    <title>Attach to Account Manager</title>
    <logo>graphic/logo.png</logo>
    <account_info_message></account_info_message>
</attach_to_account_manager>

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

version 1 only: The logo is placed on each wizard page and should have a height of 280px and a width of 115px. Logos can be any of the following types: PNG, JPG, GIF, and BMP. The logo location should be specified as a path relative to the skin.xml description file. The path separator should be a '/' for all platforms.

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>graphics/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, project_area_background_image, dialog_background_image, and workunit_area_background_image. If you experience this issue switch the image file format to PNG. We'll try to address this issue in 5.10.x.

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 ':'.

Icon

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

Icons are described as follows:

<image>
    <imagesrc>graphics/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 ':'.

Simple Tab

Simple Tabs are used in version 1 only.

The different types of simple tabs represent the different states an active task can be displayed as.

Tabs are described as follows:

<tab>
    <imagesrc>graphic/icon.png</imagesrc>
    <border_color>51:102:102</border_color>
    <gradient_from_color>51:102:102</gradient_from_color>
    <gradient_to_color>134:179:176</gradient_to_color>
</tab>

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.

border_color describes the color that surrounds the tab. The color is represented as an RGB value with the token being ':'.

gradient_from_color describes the color that should start the gradient effect. The color is represented as an RGB value with the token being ':'.

gradient_to_color describes the color that should finish the gradient effect. The color is represented as an RGB value with the token being ':'.

Simple Link

Simple Links are used in version 1 only.

Links are images that cause an action to happen. Links do not change state when clicked.

Links are described as follows:

<image>
    <imagesrc>graphic/image.png</imagesrc>
</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.

Simple Button

Simple Buttons are used in version 1 only.

Buttons are images that cause an action to happen. Buttons can be at rest or in a clicked state. When the button is clicked it changes to the clicked image.

Buttons are described as follows:

<button>
    <imagesrc>graphic/button.png</imagesrc>
    <imagesrc_clicked>graphic/button_clicked.png</imagesrc_clicked>
</button>

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.

imagesrc_clicked 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.

Stencils

Stencils apply to version 1 only.

Making skins is simplified with the use of the following 3 'stencils' (these are transparent GIFs).

  • To use the templates, use a graphical application such as Photoimpact that supports objects in multiple layers, allowing you to move the templates above the appropriate (background-) image to the desired position.
  • The meaning of the template colors is as follows: The green lines / edges serve the positioning of the template above the respective (background-) image. The area tagged with red lines corresponds to the space to cut / paste for sequential images.
  • The source for the creation of a skin is an existing, complete background image with the size of 410 x 540 pixels.
  • Beginning with template_1 (to be moved, positioned and copied across the background_image) the creation of the workunit_area_background_image and the project_area_background_image takes place.
  • Now, if desired, the workunit_area_background_image and the project_area_background_image can be designed separately depending on the desired effects (i.e. transparency).
  • Subsequently template_2 (by copying, moving or positioning) can be used on the background_image, workunit_background_image or project_background_image to achieve the desired effects (i.e. transparency) in order to create further desired images (i.e. workunit_tab_area_background_image, workunit_gauge_background_image etc.)

Stencil 1.gif
Stencil 2.gif
Stencil 3.gif

Debugging Your Skin

The BOINC Manager has a built-in debugging feature which you can use to list any elements missing from your skin. The error messages will be written to the stderrgui.txt file in the BOINC data folder. On Windows, this file can be found at C:\Documents and Settings\All Users\Application Data\BOINC\stderrgui.txt. On the Mac it is at /Library/Application Support/BOINC Data/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"

Be sure to debug under both BOINC version 7.0.25 or later (to test with version 2), and BOINC 6.12.43 or earlier (to test with version 1.) Note: Back up your data before switching to the older version of BOINC or you may lose any unreported work. For version 2, it is best to test with different platforms (Windows, Mac, Linux) and different languages.

Personal tools