Configuration Applet

Introduction

This sample exposes the codebase for the configuration applet shipped with the device server. This material is offered for demonstration purposes so users may learn how to create custom java applications that configure and control the device server.

Although the device ships with this applet as the installed default, users can replace the shipped applet with one of their choosing to customize the user interface to the device. Customized applets could be minor twists on the current applet or they could be totally unique representations of the device that the server is attached to (see the messanger applet as an example).

The configuration applet is built upon a set of Digi utility classes found in the common.jar library. The classes available in this library are described in the accompanying java doc. You can build and run this code as an applet or as a standalone application.

Please be aware that this is sample code that is provided AS-IS. There is no written or expressed warantee or support for this code. Feel free to examine and extend the code to your liking but understand that future releases of this code may changed without notice.

The configuration applet runs by pointing a browser at the IP address of the device server. This opens the index.htm file on the device which in turn downloads and invokes the applet within the browser's jvm plugin. This applet is written such that it requires the Sun java plugin version 1.4.2 or newer. This was done to take advantage of the advanced UI and networking features available in this jvm. Your custom written applets and applications can be written to run on jvm's offered by other vendors as you see fit.

This configuration application has been developed with a number of customer extention points in mind. The current implementation allows users to customize some of the look and feel of the application without having to re-code the applet. Things such as changing string labels, changing screen colors, or setting background images can all be done easily without changing a line of code.

How To Build

This sample has been written and tested with the J2SE 1.4.2 SDK and can be built using Apache Ant 1.5.3. These can be downloaded from the following locations:

• http://java.sun.com/j2se/1.4.2/download.html (download the appropriate SDK for your platform under the Download J2SE v 1.4.2 section)
• http://ant.apache.org/bindownload.cgi

To build this sample

1. Open a command prompt.
2. Go to the configapp directory.
3. Execute the build.bat file, specifying the target 'all' (e.g. build all)

Two environment variables are required to build the sample: JAVA_HOME and ANT_HOME. The default values for these are C:\j2sdk1.4.2 and C:\apache-ant-1.5.3-1, respectively. If you install Java or Ant into different directories you will need to set these environment variables appropriately.

Output of the build

The build creates 2 subdirectories: build and dist. The build subdirectory contains the all the generated class files, javadoc files, jar files, etc. The dist subdirectory is intended to be used as a self-contained distribution of the application and contains the jar files and associated files to execute the application or applet.

How To Run

This sample can be run as an applet or an application. When run as an applet the configapp resides on the device and is downloaded and run from within a browser on your PC. When run as an application the configapp resides on your PC and is executed from there.

To run as an applet:

You must load the jar and HTML files onto the device (this only has to be done once). When executed, the configuration applet will connect back to the device it was loaded from.

1. Access the administration web interface by entering the following URL in in a browser's URL window:
       http://ip-address-of-device/admin/administration.htm
2. Select File Management under the Administration menu.
3. Click Browse. Locate and select the common.jar file in the configapp\dist\bin\applet directory. Click Open.
4. Click Upload.
5. Click Browse. Locate and select the configapp.jar file in the configapp\dist\bin\applet directory. Click Open.
6. Click Upload.
7. Click Browse. Locate and select the index.htm file in the configapp\dist\bin\applet directory. Click Open.
8. Click Upload.
9. Click Browse. Locate and select the config.ini file in the configapp\dist\bin\applet directory. Click Open.
10. Click Upload.
11. Click index.htm to run the configuration applet from the device (to access the applet directly use the URL http://ip-address-of-device/FS/WEB/index.htm).

To run as an application:

Execute the batch file provided. You must specify the IP address of the device you want the configuration application to connect to.

1. Open a command prompt.
2. Go to the configapp\dist\bin\applet directory.
3. Execute the configme.bat file, specifying the IP address of the device (e.g. configme 192.168.1.100).

Configuring the device:

Once started, the configuration utility can be used to configure various aspects of the device server. Details on using the configuration utility can be found in the Getting Started Guide.

Customizing the Configuration Application

Overview

There are a number of ways to customize the provided configuration application that range from simply editing a configuration file to actually writing or changing java code. The customization options can be broken down as follows:

• Look and Feel adjustments can be made by editing the config.ini file
• UI label and message text adjustments can be made by editing the resource .properties files
• Custom views and content adjustments can be made by editing the .java source files

Each of these options will be described in more detail below.

Look and Feel Adjustments

The config.ini file contains a number of settings that control the look and feel of the configuration application. Some of these settings are global and affect the entire UI while others are specific to one of the views in the UI.

Global Settings

The following settings apply to the entire user interface:

• TextColor=R,G,B specifies the color of text and most component outlines.
• MenuColor=R,G,B specifies the color of menu text.
• ControlColor=R,G,B specifies the background color of controls such as buttons, dialogs, etc...
• DisableColor=R,G,B specifies the color of disabled components.
• BackgroundColor=R,G,B specifies the color application background.
• HeadingBarBackgroundColor=R,G,B,A specifies the color of heading bars in some views.
• TabbedPaneBackgroundColor=R,G,B,A specifies the color of a tabbed pane background.
• TextFont=name,size,style specifies the font to use for all text in the application. Style value can be 0 (Plain), 1 (Bold), 2 (Italics), or 3 (BoldItalics).

The User Interface of the configuration utility is made up of several different subpanels. Each of these panels can be configured to have a unique background color or background image. The background color can be set to be solid, transparent, or semitransparent. Each panel in the user interface has a unique name and that name should be used in specifying the configuration of that panel. The default config.ini file contains the names and settings for each panel. Many of these settings are commented out but you can uncomment the settings to alter the look of the user interface.

View Background Color

The background color of a panel can be expressed by the use of the BackgroundColor keyword. For example, to set the background color of the message panel specify the panel name & keyword followed by the R,G,B,A values that make up the desired background color. All values range from 0-255. R,G,and B specify the Red, Green, and Blue components of the color and the A value represents the Alpha Channel (ie transparency) of the background. A value of 0 means the background is completely transparent and a value of 255 means the background is solid. Some examples and their meanings follow:

                  MessagePanelBackgroundColor   = 255,0,0,255
                

This line sets the background color of the MessagePanel to be solid Red.

                  NavigationPanelBackgroundColor   = 255,255,255,255
                

This line sets the background color of the navigation panel (the menu area) to be solid WHITE.

                  ContentPanelBackgroundColor   = 200,200,255,50
                

This line sets the background color of the content panel (the main view area) to be a translucent light blue. Using this setting, the user will be able to see through the content panel to see the application panel that is behind it.

View Background Image

The background of a panel can contain an image of the users choice by using the BackgroundImage keyword. For example, to set the background image of the message panel, specify the panel name and keyword followed by the name of the image to be displayed. The image must be stored in the .gif format and the image must be placed in the \src\main\com\digi\config\images directory before rebuilding the configuration application. Additional keywords allow the user to specify if the background image should be tiled, stretched or positioned at a specific location in the panel. The following examples show use of these keywords:

                  AppPanelBackgroundImage   = digi_logo_embossed.gif
                  AppPanelBackgroundTile    = true
                  AppPanelBackgroundStretch = false
                

The lines above specify that the application panel (backdrop for all other panels) should be painted with the digi_logo_embossed.gif image. Furthermore, the image should be tiled across the entire application background.

                  NavigationPanelBackgroundImage   = digi_logo.gif
                  NavigationPanelBackgroundImagePos= 8;
                  NavigationPanelBackgroundTile    = false
                  NavigationPanelBackgroundStretch = false
                

The lines above specify that the navigation panel should be painted with the digi_logo.gif image. Furthermore, the image should not be tiled or stretched but instead placed in its natural size in bottom center of the panel.

                  RebootViewPanelBackgroundImage  = sunset.gif
                  RebootPanelBackgroundTile       = false
                  RebootPanelBackgroundStretch    = true
                

The lines above specify that the reboot view panel should be painted with the sunset.gif image. Furthermore, the image should be stretched to fit the size of the reboot view panel.

One thing to note is that if a panel specifies a background image, the user must specify a background color that is transparent or semi-transparent. Otherwise, the background image will not show through the specified background color. The default background color for all panels is transparent but this too can be customized (see DefaultPanelBackgroundColor).

The following config.ini files are provided for your reference.

• config.ini - the default Digi theme
• white_config.ini - a basic white background theme
• black_config.ini - a basic black background theme
• fancy_config.ini - a theme that mixes various background bitmaps and colors

You can use try these ini files by renaming them to config.ini and uploading them to your device. You will then need to reload your applet for the new theme to take effect.

Text Adjustments

The configuration application stores all text strings displayed in the GUI in a set of resource files. The resource files are all found in the \src\main\com\digi\config\resources directory. By editing the text strings in these files and rebuilding the application, you can change the text that is displayed when the application is run.

The resource files are partitioned as follows:

• Basic Labels are found in the ConfigUIResourceBundle.properties file. These are labels used on menus, buttons, as well as strings displayed in the various configuration view panels.
• Error Messages are found in the ConfigResourceBundle.properties file. This file contains the primary and secondary text associated the various error messages that are displayed in the scrolling message area of the configuration application. This file has special formatting that is described in the heading of the file.
• Application Image file names are found in the ConfigImgResourceBundle.properties file. The configuration application refers to images used on buttons and other UI controls by name. This file maps those names to the associated .gif image file. The .gif image files must be placed in the \src\main\com\digi\config\images directory before building the application.

Custom View Adjustments

Customers familiar with java devlopment can use the sample configuration applet as a base to create more extensive customizations. The configuration sample applet is packaged such that views can be removed, modified, or added fairly easily.

The configuration application is packaged in the configapp.jar and consists primarily of user interface classes. The application also makes use of the common.jar shared library which provides the underlying communication and device management classes.The details about how these jar files are organized and how the classes should be used can be found in the corresponding javadoc links below:

• configapp.jar javadoc
• common.jar javadoc