What is skinning?

Controlling Attributes
What attributes can I control in a Droplets GUI?
How do I change the background color of an application?
How do I change the foreground color of an application?
How do I change the font of a single label?
How do I assign the same font change to multiple components?
How do I change the layout of an application using skins?
How do I control images on buttons using skins?
How do I skin images onto my application panels?
How do I skin ImageLink components?
How do I create a graphical UI from images created by a graphic designer?

Deployment
How do I deploy a new skin?
Where do I put params.txt, and what do I change in the DRP file?
How do I use imagejars to improve performance?
How do I make it possible for user to change skins?
How do I create skinned icons for my application?

One advantage of using the Droplets Platform to write and deliver online applications is the ability to "skin" your applications, which provides flexible, total control over their color and appearance. You can also offer end-users a variety of skins to choose from, and let them swap their application's skin dynamically using the "Change Skin" control in the Droplets client menu. Independent software developers can thus offer customizable applications that can simply be re-skinned without changing any code.

This document covers the various ways in which you can skin a Droplets application in order to manipulate its visual properties without changing application behavior.

What is skinning?

Skinning provides you with a mechanism for modulating the color and appearance of your Droplets GUI without altering application code. The color of the GUI and its components can be changed, and image files can be added at select points in the GUI for branding purposes. It also allows you to alter the layout of your components on the GUI, or to alter application functionality by making components visible and/or invisible.

Default appearance parameters for your application are defined in the application code itself. If your GUI is to be "skinnable", the developer also includes "Skin Names" as parameters for each of the GUI's component attributes to be skinned (background and foreground colors, GUI Layout parameters, etc.). Skinning begins after the application has been completed. A small file called params.txt stores the skin's new appearance parameters. This text file is accessible to the Droplets Client (which presents the GUI) from the Web; the Client knows where to find its params.txt file via a parameter named imagedir in the application's DRP file. This parameter's value is the exact URL or IP address of the appropriate params.txt.

Graph: Skinning involves both the Droplets Server and the Web server. The Droplets Client begins by reading application parameters from the DRP file, then calls the Droplets Server for a GUI description. Once these instructions are received, the Client gets the application skin's additional appearance parameters from the skin's imagedir, which is typically located on the Web server.

If you wish, you can also make multiple skins available to a single Droplets application, and allow end-users to dynamically choose among these skins via a "Change Skins" menu item that is found within the application's Droplets Menu. In this event, you will deploy an additional file called skins.txt (which resides on your Web server) that contains the name and location of each of the application's skins.

Controlling Attributes

This section of the document covers a range of possible ways in which you can use the Droplets skinning capability to alter the visual appearance of your applications.

What attributes can I control in a Droplets GUI?

How do I change the background color of an application?

By default, the Droplets GUI background is the same utilitarian grey that you will find with most Windows-style applications. This default background color can be changed by creating a small text file called params.txt. Within this text file, you should create a parameter named bgrgb and then assign it an RGB color value, for example:

Deployment of your params.txt file is covered at the end of this document.

How do I change the foreground color of an application?

Same as above, but the parameter in params.txt should be named fgrgb:

How do I change the font of a single label?

Droplets components support all fonts that are supported by the Java API. The font of a label - as with other component appearance parameters - are initially defined within your application logic via the setFont() method. To allow yourself to later override these parameters in a skin, you need to add a second argument to the setFont() method, a string which will act as the "Skin Name" for your attribute:

Important Note: These Skin Names are going to be transmitted over the network when the Client loads its application, so you should keep them as short as possible for the sake of performance.

How do I assign the same font changes to multiple components?

Simply assign the same Skin Name to all your Labels' setFont() methods:

You will now alter the font of all your components with a single assignment of value to the LabelFont parameter:

How do I change the layout of an application using skins?

Let's say that you would like to allow your skin designer the flexibility to shuffle around a set of labels on a bar within your GUI. As with other component attributes, all gridbag properties in the application logic can be over-ridden by params.txt. All you need do in order to rearrange the gridbag properties of the labels is:

1. Designate a Skin Name for each gridbag attribute, for each component in the window:

2. Define the new gridbag parameters within your params.txt.

How do I control images on buttons using skins?

In order to associate an image file with a button on your Droplets GUI, you will have to use the Image Button, a subclass that is derived from Button in the Droplets API. The Image Button expects to have a set of three GIFs associated with it. One of these images will be presented when the button's display area is inactive, another when a mouse runs over the button's display area (Over), and a third when it is actually clicked by the mouse (Down). It's important to note that the Over and Down GIFs will be presented whenever the mouse interacts with any part of the display area, not just the button as defined in the GIF; for example, if you create an Image Button GIF that contains a button plus other graphics, whenever a user's mouse runs over any part of that GIF, the Over GIF will be displayed.

Keep in mind that you're not required to have Over and Down versions of your Image Button if you don't wish to simulate physical button movement during MouseOver and Click events. The Droplets Platform will automatically look for these GIFs, but if they're not in your imagedir location, the Client will simply present the default GIF instead.

You indicate a set of GIFs to be associated with a given Image Button by using one of the class' methods. For example, if you set the Image Name to "BuyNowButton" in your program logic:

By default, the Droplets Client will now look for image files named "BuyNowButton.gif", "BuyNowButtonOver.gif" and "BuyNowButtonDown.gif". But, because you have set a Skin Name for the button's image, params.txt can also map to the proper set of button images by calling the image's skin name:

How do I skin images onto my application panels?

Panels, which serve as containers for other components, can be associated with image files as well. When you skin a panel, there are two issues to address: how the image is fetched and how it is displayed.

The image can be fetched in one of two ways. If the image is being served remotely, you can give the panel an arbitrary URL by setting its imageUrl property; if it is being served from the same IP address as your Droplets Server, you can use the imageName property.

When using the imageName property, set the imageName property to the name of the image filename. Do not to include the file extension (.gif is automatically added).

If you instead use the imageUrl property and the Droplets Client is running as an applet, it will use an Image Redirector to obtain the image. Therefore, if your Droplet will sometimes be running as an applet, you should set the Image Redirector for this panel using the Panel class' imageRedirector property. The imageRedirector string argument that the method requires is pre-pended to the image's actual URL, allowing the Droplets Server to act as a proxy image fetcher for the applet. The string argument should be formatted as follows:

"http://www.YourCompany.com/YourDropletsServerLocation/?url="

All three of these properties — imageUrl, imageName and imageRedirector — are skinnable, allowing you to set the panel image's location at separate URLs for each skin. For example, an Independent Software Vendor that skins their Droplets-based application for multiple customers can fetch each skin's corporate logo from each customer's Web site.

There are also several choices as to how the image will be displayed. Each one can be defined as a selection within the Panel's ImageMode type. Among the options are centering the image within the panel; fitting it to the panel's exact size; scaling it to fit the panel without changing the aspect ratio; or tiling it along the entire panel using the upper left cell as the starting point.

How do I skin ImageLink components?

Image Links are components that are used, for example, to present a company logo on the application GUI, along with a link to the corporate Web site. As with Image Buttons, you make an image link's actual image skinnable by setting the Image Name with an extra string argument that defines its Skin Name:

You can now use this Skin Name to change images on the Image Link for your skin:

How do I compose a graphical UI from images created by a graphic designer?

Once the image components have been created and assigned their places within the application grid, it remains for the graphic designer to create a design and then divide it into GIFs corresponding to each individual image component.

This is typically done with standard design tools (i.e. Adobe PhotoShop and the like). The image below shows a completed graphic design for a Droplet Email skin, HappyEmail. It consists of a series of background colors plus a set of Image Buttons along the top.

Most of this can be done by simply setting background and foreground colors for the Email window's three panels (in params.txt). But we will need three GIFs to place over each Image Button (Regular, Over and Down). To accomplish this, the graphic designer slices out a separate GIF for each button and gives them to the developer, who places them in the same folder as their corresponding params.txt file and identifies them by name in the application logic.

As we mentioned above, the graphic designer need not be picky about the size of the GIF — Droplet's layout manager will adjust the application window's grid to accommodate the GIF size.

Note also that the Image Button GIFs need not take up the entire space in their panel. The Image Buttons in the toolbar above, for instance, take advantage of the Droplets GridBagLayout scheme for their appearance. The first eight buttons are aligned left and placed left to right relative to one another through the use of the gridx setting. The last button is aligned right, and any extra space is simply taken up by the background color.

Deployment

Once you have created one or more skins for your application, they are served (along with the application) by the Droplets Server in conjunction with a Web server. For the Droplets Platform to have access to your GIFs, their names must be defined at appropriate points in the application logic and the actual GIF files must be located in an image directory known as the imagedir. The location of your imagedir is defined within your application's DRP file. All of this is explained in detail below.

If you wish, the application can also include logic for choosing among multiple GIF skins by the end-user — in this event the .drp file's imagedir parameter tells the Droplets Client which params.txt file it should fetch. All of this is explained in further detail below.

How do I deploy a new skin?

All skins require the following two files:

• A .drp file with a value set for the imagedir variable;
• A params.txt file.

If your skins include GIF image files, you'll also need the following:

• The GIF files (all in the same directory as params.txt);
• An imagejar file that zips up all GIF files
• Your .drp file needs an imagejar variable with the value set to the imagejar location.

And if you're serving more than one skin for a given application, you'll also need:

• A skins.txt file that indicates the name of every application skin being served.

Below is a table with the name, purpose and required location of all files that you may need for your Droplets skin deployment.

Where do I put params.txt, and what do I change in the DRP file?

You can put params.txt wherever you want, accessible via HTTP. Wherever you put it, you must indicate its exact location in the DRP file's imagedir variable. So if you place your params.txt on your Web site, www.mycompany.com, within a subdirectory skins/myapplication, you must indicate this location in the DRP file as follows:

Important note: If you wish to retain the option of serving your Droplets application as an applet, the location of your imagedir must be on the same IP address as your Droplets Server; if not, you are free to serve skins to your Droplet from a remote location.

How do I use imagejars to improve the performance of skin loading?

A Droplets skin that includes GIF files will be served far more efficiently if you create an imagejar, a zipped directory that contains all of your skin's GIF files (complete with intact directory structure). It is required that this .zip file be located in the root folder of your Web directory.

You can use most of the standard .zip softwares to create an imagejar file, but you unfortunately can't use Sun's Jar software for this.

How do I make it possible for users to Change Skins within a Droplet?

We mentioned earlier that it's possible to create a Droplets application that comes with multiple skins among which your end-users can choose. There are two ways of doing this:

• Giving your users a choice of skin when they create an application instance (for example, an Email account or a specific picture album on Picture Share);

• Allowing your users to dynamically change their application skin as many times as they like during application sessions.

In either case, your first responsibility is to create a set of separate folders to contain the params.txt and full set of named GIFs (as defined in the application logic) for each of your skins.

Once this has been accomplished, all you need to do is define behavior that allows users to select among the skins you've created.

Let's start with the first option. If you're offering your Droplets from a Web site or an Intranet (as is typically the case), you create a Web page giving your users a choice of skin. Your page will have written into it logic allowing it to tell the Droplets Server to create a new account, and with that information it will indicate which skin the user has chosen. The Droplets Server then creates a new account, and with it a .drp file with an imagedir parameter that points to the selected skin's GIFs and params.txt.

Dynamic skin changes

On the other hand, if you're giving the end-user the option to change their skin mid-session, you can take advantage of one (or both) of the Droplets Client's methods of supporting of dynamic skin changes: (1) the built-in Droplets Menu; or (2) a more prominent button on the GUI that triggers the changing of skins.

All Droplets come with a built-in Droplets Menu which offers a "Change Skins" selection. When the end-user selects "Change Skins" from the Droplet Menu, a sub-menu appears with a selection of available application skins. The Droplets Client gets this listing from a text file called skins.txt. This is simply a listing of skin names along with the URL of their params.txt file and the name of its associated GIF file:

Note: the second position of the URL is reserved, and so should be kept blank as shown above.

If you're working with multiple application skins which can be changed dynamically, you will have to provide your application with a skins.txt file (again, this name is not optional). It must be placed in a very specific location within your application's file structure, namely:

IIS: wwwroot\DropletConfig\apps\MyApp\skins.txt
Apache: htdocs/DropletConfig/apps/MyApp/skins.txt

where "MyApp" signifies the name of the application with which these skins should be associated.

When an end-user downloads the Droplet, the Droplets Server will include a copy of this skins.txt file, allowing the application's Droplets Menu to present the selection of skin's to the end-user, and to alter the .drp's imagedir as appropriate.

Some developers prefer to also have a GUI component dedicated to dynamically changing the application skin. In this event, you'll create a function in your application logic to handle a user-initiated click of a "Change Skins" button. This will involve a call to the Application class' ExecuteDropletMenuItem() method with the string "Skin" as an argument:

This call tells the Client to change the imagedir parameter in the application's .drp file. The next time the application is started, the new skin parameters will take effect. If the skin has a desktop icon associated with it, this icon will automatically be updated on the Client-side PC when the end-user reboots his/her machine.

When your end-user selects their Change Skin component, the Client automatically presents them with a pop-up window (which you do not need to define in your application logic) that offers a list of all available skins:

How do I create skinned icons for my applications?

Since Droplets are online applications that present themselves as desktop software, the notion of skinning is extended to the application's desktop icon as well, which usually matches the look and feel of the GUI. Droplets get their icon information from a block of icondata (really binary code expressed in text) that resides on params.txt and is thus transferred by the Droplets Platform to the application's .drp file. The Droplets SDK includes an Icon Generator Utility (DropletIconGen.exe) which allows you to turn any .ico file into a block of icondata.

In order to create a skinned icon for your Droplet, you need to follow these steps:

1. Get an image file from your graphic designer that matches the look and feel of your GUI skin;

2. Turn that image file into an industry-standard .ico file;

3. Run DropletIconGen.exe, contained in your SDK installation at Droplet\Server;

This is a command-line tool. There are two ways to run it:

• DropletIconGen iconfile.ico
  
  This will create a DRP file called iconfile.ico.drp. You can either cut and paste the icondata into your DRP file, or simply rename the DRP file to correspond to the name of your application and add the other DRP parameters.
  
  
• DropletIconGen iconfile.ico droplet.drp
  
  Where "iconfile.ico" equals the name of your .ico file, and "droplet.drp" equals the name of your application's DRP file. This will insert the icondata directly into an existing DRP file for your application, keeping all other existing parameters intact.
  

If you are hosting more than one skin for your application, you will have to copy the icondata out of either one of the above files and place it in the appropriate params.txt for that skin.

There's one constraint on the .ico files that you should be aware of, namely that the Droplets Platform supports only one .ico per application skin. This is relevant because (since different versions of Windows and other OS support different levels of color depth) many applications support more than one .ico per skin, and present different icons to different OS versions based on their maximum supported color depth. At present, the Droplets Platform does not support this multiple icon scheme.

  Return to Droplets SDK Documentation Home