Advanced management of symbols and palettes

Programmer's documentation > Developing with the JViews Diagrammer SDK > Managing dynamic symbols > Advanced management of symbols and palettes

Addresses advanced users who want to create symbols in memory by themselves without loading an existing palette from a JAR file.

Palettes

Describes the classes used to create and modify palettes.

Categories

Categories are the logical units used to organize symbols.

The category is defined by the IlvPaletteCategory class. As well as symbols, a category can contain other sub-categories. You thus organize symbols in a tree of logical groups. You add a category to a symbol palette by calling:

//Create a new root category

String categoryID = "root";

IlvPaletteCategory rootCategory = new IlvPaletteCategory(categoryID);

//Add the root category to the palette

palette.setRoot(rootCategory);

rootCategory.setName(categoryID);

//Add a subcategory to the root category

IlvPaletteCategory subcategory = palette.addCategory(rootCategory, "subCategory");

subcategory.setName("subcategory");

Palette symbols

An IlvPaletteSymbol can only exist within a palette.

You need first to create an IlvPalette, then set its root category (and more categories if needed), and finally add the symbol to a category in the palette:

IlvPalette palette = new IlvPalette();

palette.setRootCategory("Root");

IlvPaletteSymbol psymbol = palette.addSymbol(palette.getRoot(),"symbol1");

The symbol needs a CSS file and other resources.

You must make sure that the CSS file and the resource files are in the class path; otherwise, you must use the IlvPaletteManager.

Assuming that all the required files are in the class path:

psymbol.setName("Symbol");

psymbol.setClassName("Symbol");

psymbol.addResource(css);

psymbol.setCSSResourceName(css);

Palette parameters

Parameters contain values associated with a symbol. A parameter is bound to a graphic element to cause a transformation, that is, a change in the elements aspect to represent a change in data. For example, an icon that changes color to show an alert.

Parameters are set on a symbol using instances of IlvPaletteSymbolParameter. This class contains the definition of one parameter. You add a parameter to a symbol by calling:

//Create a new palette

IlvPalette palette = new IlvPalette();

palette.setName(name);

palette.setDescription(french, descr);

//Create a root category for the palette

String categoryID = "root";

IlvPaletteCategory rootCategory = new IlvPaletteCategory(categoryID);

palette.setRoot(rootCategory);

rootCategory.setName(categoryID);

//Create a new symbol

String symbolID = "symbol1";

IlvPaletteSymbol s = palette.addSymbol(rootCategory, symbolID);

s.setName(symbolID);

//Create a new parameter

IlvPaletteSymbolParameter p2 = new IlvPaletteSymbolParameter();

p.setID("progress");

p.setName("progress");

p.setValue(new Integer(0));

//Add the parameter to a symbol

s.addParameter(p);

Parameters can accept any value or only an allowed set of values, such as “wait”, “attention”, “go”, or 1, 2, 3. The description of the allowed values for a parameter is set using the IlvPaletteSymbolParameterValueSet class. You set allowed values for a class by calling:

//Create a new value set

String vsetID = "vset1";

IlvPaletteSymbolParameterValueSet vset = new

IlvPaletteSymbolParameterValueSet(vsetID);

vset.setName(vsetID);

vset.setType("Integer");

vset.setValues(new int[] { 1, 2, 3 });

vset.setValueName(0, "one");

vset.setValueName(1, "two");

vset.setValueName(2, "three");

//Add the value set to a palette

palette.setValueSet(vset);

//Create a new parameter

IlvPaletteSymbolParameter p = new IlvPaletteSymbolParameter();

p.setID("progress");

p.setName("progress");

p.setValue(null);

//Add the value set to a parameter

p.setType("set");

p.setValueSet(vset);

Please note that the CSS of the symbol must be consistent with the parameters of the symbol. For example, if you wanted to use the file Dial.css (in ilog/views/palettes/shared/symbols/Dial.css ), you would need to define the parameters name and value for the symbol, as Dial.css refers to these parameters:

s.addParameter(

new IlvPaletteSymbolParameter("value", new Double(0), "double", null));

s.addParameter(

new IlvPaletteSymbolParameter("name", "DefaultName", "string", null));

...

The parameters constitute the visible interface of the symbol. They hide the internals of the CSS, so that it is only through the parameters that you can modify the symbol.

Palette events

When a symbol or a category is added in a palette, a PaletteEvent is fired to notify external objects.

JViews supplies the following classes to track palette events:

PaletteListener - an interface for receiving PaletteEvent s.

PaletteAdapter - the default implementation of PaletteListener.

Palette manager

The following code example shows how to add palettes to an IlvPaletteManager instance.

IlvPalette p1 = new IlvPalette();

IlvPalette p2 = new IlvPalette();

IlvPalette p3 = new IlvPalette();

IlvPaletteManager pm = new IlvPaletteManager();

pm.add(p1);

pm.add(p2);

pm.add(p3);

Palette manager events

When a palette is added or removed from an IlvPaletteManager instance, a PaletteManagerEvent is fired.

Rogue Wave® supplies the following classes to track palette events:

PaletteManagerListener - an interface for receiving PaletteManagerEvent s.

PaletteManagerAdapter - the default implementation of PaletteManagerListener.

Organizing symbols in categories

The following example shows how to create symbols and organize them in palette categories. The example is divided into two steps:

1. Set the root category in a new palette.

IlvPalette palette = new IlvPalette();

palette.setName(¨myPalette¨);

palette.setDescription(¨multiple traffic signals¨);

palette.setPackageName("roadsigns/ ");

//Create and set the root category

IlvPaletteCategory root = new IlvPaletteCategory(rootID);

root.setName("symbols");

palette.setRoot(root);

2. Set a hierarchy of categories in a palette.

//The first categories under the root.

IlvPaletteCategory c1 = palette.addCategory(root, id1);

c1.setName("category 1");

c1.setLongDescription("The first category that contains…");

IlvPaletteCategory c2 = palette.addCategory(root, id2);

c2.setName("category 2");

c2.setLongDescription("The second category that contains…");

//Now create sub categories in the first ones.

IlvPaletteCategory c101 = new IlvPaletteCategory(id101);

c101.setName("category 101");

c1.add(c101);

IlvPaletteCategory c102 = new IlvPaletteCategory(id102);

c102.setName("category 102");

c1.add(c102);

IlvPaletteCategory c201 = new IlvPaletteCategory(id201);

c201.setName("category 201");

c2.add(c201);

//Finally, create some symbols in different categories.

IlvPaletteSymbol s100 = palette.addSymbol(c1, ids101);

s.setName("s100");

s.setCSSResourceName(css100);

s.setClassName(className100);

s.setIconResourceName(resdir + "icon.gif");

s.addResource(resourceURL1);

s.addResource(resourceURL2);

IlvPaletteSymbol s1010 = palette.addSymbol(c101, ids1010);

IlvPaletteSymbol s1011 = palette.addSymbol(c101, ids1011);

IlvPaletteSymbol s1020 = palette.addSymbol(c102, ids1020);

IlvPaletteSymbol s200 = palette.addSymbol(c2, ids200);

IlvPaletteSymbol s201 = palette.addSymbol(c2, ids201);

IlvPaletteSymbol s202 = palette.addSymbol(c2, ids202);

IlvPaletteSymbol s2010 = palette.addSymbol(c201, ids2010);

NOTE 	The Symbol Editor helps you create symbols and palettes very easily and intuitively.