TBD: Basic concept and some screen shots.

How to Select a Theme at Runtime

In FWD, there are available these builtin themes, via these keys:
  • Windows Classic, via classic, ClassicTheme or com.goldencode.p2j.ui.client.gui.theme.ClassicTheme
  • Windows 10, via win10, Windows10Theme or com.goldencode.p2j.ui.client.gui.theme.Windows10Theme
  • Windows 8, via win8, Windows8Theme or com.goldencode.p2j.ui.client.gui.theme.Windows8Theme
  • Google Material, via com.goldencode.p2j.ui.client.gui.theme.MaterialTheme

All custom themes will need to be specified as the full class name.

This section will describe how to configure a theme for a specific user or globally. If you don't explicitly configure a theme, the default used theme will be Windows 10. The bellow examples show how to set the theme to Google Material; to set it to another theme, change the com.goldencode.p2j.ui.client.gui.theme.MaterialTheme text to the desired theme's key.

The configuration is done in the FWD Application Server's directory.xml or client's configuration (via config file or command line).

Specify a theme for all users or a specific user

To change the default theme for all users, add this node under /server/default/ in the directory:

        <node class="container" name="theme">
          <node class="string" name="name">
            <node-attribute name="value" value="com.goldencode.p2j.ui.client.gui.theme.MaterialTheme"/>

To set the theme for specific users, the above theme/name node must be added under the /server/default/runtime/<account-or-group>/ node.

Changing the theme for embedded mode clients

To allow the embedded mode clients use a different theme than Virtual Desktop/Swing clients, first you need to ensure the spawned client is allowed to set the theme. Identify the /security/acl/remotelaunchoption/ node and add this child:

          <node class="container" name="000050">
            <node class="resource" name="resource-instance">
              <node-attribute name="reference" value="client:driver:theme"/>
              <node-attribute name="reftype" value="TRUE"/>
            <node class="remoteLaunchOptionRights" name="rights">
              <node-attribute name="allow" value="true"/>
            <node class="strings" name="subjects">
              <node-attribute name="values" value="ehotel"/>

TODO: explain how ehotel user is the account used by the embedded application to authenticate with the FWD server.

To set explicitly set the theme, it requires for you to edit (or add, if it does not exist) this node under /server/default/embeddedWebApp/, so that the client:driver:theme=com.goldencode.p2j.ui.client.gui.theme.MaterialTheme value appears in the value attribute:

              <node class="string" name="cfgOverrides">
                <node-attribute name="value" value="client:driver:theme=com.goldencode.p2j.ui.client.gui.theme.MaterialTheme"/>

If the /server/default/embeddedWebApp/cfgOverrides already exists, separate the value entries via a space character.

Theme selection for FWD Virtual Desktop clients

In FWD's Virtual Desktop GUI clients, it is possible to allow the user to select a specific theme, before loging in. The themes the user can choose from are configured under /server/default/available-themese node - add this node under the /server/default/ node:

        <node class="container" name="available-themes">
          <node class="entry" name="theme1">
            <node-attribute name="key" value="com.goldencode.p2j.ui.client.gui.theme.Windows10Theme"/>
            <node-attribute name="value" value="Windows 10"/>
          <node class="entry" name="theme2">
            <node-attribute name="key" value="com.goldencode.p2j.ui.client.gui.theme.Windows8Theme"/>
            <node-attribute name="value" value="Windows 8"/>
          <node class="entry" name="theme3">
            <node-attribute name="key" value="com.goldencode.p2j.ui.client.gui.theme.ClassicTheme"/>
            <node-attribute name="value" value="Windows Classic"/>
          <node class="entry" name="theme4">
            <node-attribute name="key" value="com.goldencode.p2j.ui.client.gui.theme.MaterialTheme"/>
            <node-attribute name="value" value="Material Theme"/>

The entry node must have an unique name under the available-themes node; the theme is specified via a key and a custom name you want to use. Any builtin or custom theme can be added here, as long as the theme is in the FWD server's and client's classpath.

TODO: theme selection for embedded web clients?

Theme selection for the FWD Swing GUI clients

For the FWD's Swing GUI clients, the theme is set at the command line, when starting the client, via the client:driver:theme=com.goldencode.p2j.ui.client.gui.theme.MaterialTheme config. You can define this in the client startup script or passing it when you start the client, as ./ client:driver:theme=com.goldencode.p2j.ui.client.gui.theme.MaterialTheme.

The alternative is to configure this in the client's bootstrap configuration file, usually named client.xml. The node to add (as a child of the root node) will look like:

      <driver theme="com.goldencode.p2j.ui.client.gui.theme.MaterialTheme"/>

Configuring custom themes

When building custom themes, you must ensure that this is found at runtime, by the Java classloader. This is done by providing the custom theme's jar to the FWD server's and client's classpath.

For FWD Web clients, you need to configure the full classpath in the /server/default/clientConfig/classpath node, as:

          <node class="string" name="classpath">
            <node-attribute name="value" value="/full/path/to/p2j/build/lib/p2j.jar:/full/path/to/custom/theme.jar"/>

If you are on Windows OS, replace the : with the ; path separator and provide Windows specific paths.

For the FWD server, ensure the theme's jar is placed under the deploy/lib folder by the build process - this will allow the server startup scripts to pick it up automatically and add it to the FWD server's classpath.

If using FWD's Swing GUI client, you need to edit the startup script (client.cmd or and ensure the theme's jar is added to the classpath.

How Themes Work

TBD: Detail the core idea of the Theme interface, the class hierarchy that implements the themes and how widgets call the theme APIs to render the UI.

Building a Custom Theme

TBD: Detail the idea of extending a theme class. If there are some important concepts/approaches to know, explain them.

Understanding the Theme API

TBD: This is intended to describe the API such that one would understand each method and the specific element that is being customized when one overrides that method.

Understanding the Primitive Drawing Operations

TBD: Some description of the API that is used and any key limitations/constraints/conventions to follow.

Example Drawing Recipes

TBD: How do we do common things? This provides some examples to demonstrate how to achieve certain effects.

Extending Themes with Widget-Specific Hooks

When we add new widgets, we often have new kinds of elements that must be drawn. The right way to do this is to add these to the core interface and implementation hierarchy so that all themes support the new widget.

TBD: more detail here

© 2019 Golden Code Development Corporation. ALL RIGHTS RESERVED.