[[TOC]]

== Introduction ==
HTML and !JavaScript have become the predominate rendering technologies on the web.  Used for everything from web browsing to mobile phone applications.  HTMLGfx attempts to bring HTML rendering technologies into the BOINC graphics and screensaver environment.

By providing precompiled binaries the barrier to entry is greatly reduced allowing projects to deploy customized graphics for their applications. All projects would need to supply is the HTML/CSS/JavaScript required to display something about what is going on with the currently executing job.

In theory, volunteers could even get in on the act and create graphics for whatever applications suit their interests and share them with the community.  It is conceivable that projects may even hold yearly competitions to include a volunteers graphics bundle to be deployed with the project's application.

Currently HTMLGfx is only supported on Windows at this time.

References: [GraphicsApi Making graphics applications for BOINC]

== System Overview ==
HTMLGfx leverages existing operating system dependent libraries for rendering HTML.  By leveraging the operating systems HTML renderer HTMLGfx will be able to support whatever the latest technologies the operating systems browser supports.

== Design Considerations ==

=== Goals and Guidelines ===

Top level goals are:
 * Projects should only need to create HTML/CSS/!JavaScript to have a fully functional graphics application.

=== Development Methods ===
Use whatever framework/tools are required to build a customized browser-based application.

On Windows:
 * Use Visual Studio
 * Use Active Template Library

== Detailed System Design ==

=== CHTMLBrowserWnd ===
This component is responsible for creating the main frame window used for hosting the web browser 
control via CHTMLBrowserHost.

As part of the normal operations of the window, it should update the URL the web browser control is
displaying as state changes are detected.  It should also publish updated information to the !JavaScript
interface.

It supports whatever requirements are described for BOINC graphics applications.

Reference: [GraphicsApi#Graphicsapps Making graphics applications for BOINC]

=== CHTMLBrowserHost ===
This component hosts the web browser control and exposes whatever interfaces/callbacks the control
requires for logging and display purposes.  As part of its creation process it creates/exposes 
the !JavaScript interface for CHTMLBrowserWnd to use.

=== CHTMLBrowserHostUI ===
This component acts as the !JavaScript interoperability component.  It should only support single 
threaded access.

=== Configuration File ===
The graphics description file has the logical name of '''boinc_graphics.xml'''
(its physical name should include a version number and other info).
It has following structure:

{{{
<boinc_graphics>
    [ <default_url>filename</default_url> ]
    [ <running_url>filename</running_url> ]
    [ <suspended_url>filename</suspended_url> ]
    [ <network_suspended_url>filename</network_suspended_url> ]
    [ <exiting_url>filename</exiting_url> ]
</boinc_graphics>
}}}
Optional elements:
 '''default_url'''::
    document to display if no state specific URL is defined.
 '''running_url'''::
    document to display while the task is running.
 '''suspended_url'''::
    document to display while the task is suspended.
 '''network_suspended_url'''::
    document to display while the network is suspended.
 '''exiting_url'''::
    document to display before the task exits in 5 seconds or less.

=== Graphics Status File ===
It is read once a second and is generally managed via the worker applications via
the boinc_write_graphics_status() BOINC API.

Reference: [BasicApi#GraphicsStatus boinc_graphics_status.xml]

=== Vboxwrapper WebAPI Port ===

Reference: [VboxApps#WebAPIstatefile vbox_webapi.xml]

=== Vboxwrapper Remote Desktop Port ===

Reference: [VboxApps#RemoteDesktopstatefile vbox_remote_desktop.xml]

=== !JavaScript Extension on Windows ===
Currently HTMLGfx can pass information to the HTML DOM via the 'window.external' extension.

==== Methods ====

|| Name                  || Returns || Description ||
|| !IsAppInitDataUpdated || Boolean || Informs the HTML document to refresh all the UI state information ||
|| !IsScreensaver        || Boolean || Was the graphics application launched in screensaver mode    ||
|| !IsSuspended          || Boolean || Whether the task is currently suspended ||
|| !IsNetworkSuspended   || Boolean || Should the UI suspend Internet activity ||
|| !IsExiting            || Boolean || Should the UI prepare to exit ||
|| !IsVboxwrapperJob     || Boolean || Is this task a vboxwrapper task? ||
|| !SetAppInitDataUpdate || void    || Sets the Boolean value to the specified input ||

==== Properties ====

|| Name                  || Data Type || Description ||
|| !ApplicationName      || string    || ||
|| !ApplicationVersion   || long      || ||
|| !WorkunitName         || string    || ||
|| !ResultName           || string    || ||
|| !TeamName             || string    || ||
|| !UserName             || string    || ||
|| !UserCreditTotal      || float     || ||
|| !UserCreditAverage    || float     || ||
|| !HostCreditTotal      || float     || ||
|| !HostCreditAverage    || float     || ||
|| !ExitCountdown        || float     || ||
|| CPUTime               || float     || ||
|| !ElapsedTime          || float     || ||
|| !FractionDone         || float     || ||
|| !RemoteDesktopPort    || long      || ||
|| WebAPIPort            || long      || ||


==== Examples ====
Example of refreshing the state of various controls:
{{{
    refresh() {
        if (window.external.IsAppInitDataUpdated()) {
            window.external.SetAppInitDataUpdate(false);
            username = window.external.UserName;
            teamname = window.external.TeamName;
        }
        fractiondone = window.external.FractionDone;
    }
}}}