Using symbols
Shows how to use symbols.
Provides an overview of symbols and their classes.
Explains symbol palettes and how to load them.
Shows how to save symbol palettes.
Basic concepts
A symbol is made up from graphic elements, parameters, conditions and vector or bitmap images. Each graphic element has attributes which define its look and feel. A symbol is defined by the
IlvPaletteSymbol class. This class defines a symbol. It contains all information necessary for CSS to create instances of the symbol in a GUI application.
Symbol palette classes available in Rogue Wave JViews Diagrammer
An IlvPaletteSymbol instance contains:
The CSS that describes the symbol. This includes graphic element definitions and symbol conditions.
The class name. This acts as the entry point in the CSS.
The symbol parameters.
A
palette (
IlvPalette) is a collection of
palette symbols (
IlvPaletteSymbol ). A palette symbol represents the definition of the symbol. Instances of the symbol based on the same definition may occur in the diagrammer application. An instance of a symbol has a symbol descriptor (
IlvSymbolDescriptor) which helps find the palette symbol that corresponds to this instance.
Inside a palette, the symbols are organized in a hierarchy of
categories (
IlvPaletteCategory). Each palette has at least a root category.
The category path and the symbol name identify a symbol within a palette. For example, Symbols.Controls.Dial corresponds to the Dial symbol inside the subcategory Controls of the root category Symbols.
Part of the palette symbol definition indicates which parameters are defined for the symbol. Symbols can have a different behavior or appearance depending on the actual parameter values of the symbol instance. The palette symbol contains the definition of the formal parameter (
IlvPaletteSymbolParameter), while the actual value of a parameter can be queried using
IlvSymbolDescriptor for each instance of the symbol.
Finally, the
palette manager (
IlvPaletteManager) manages a collection of palettes. The palette manager is only needed when you want to load or save palettes dynamically in the user file system. If you need to load only one fixed palette, it is more convenient to put the palette on the class path and load the palette as resources of the application. This is explained in the next section.
NOTE An IlvPaletteManager must be attached to a Rogue Wave® JViews Diagrammer Designer application to follow the currently loaded palettes.
Loading palettes
A palette is a JAR file. The content of the palette is described in an XML file, palette.xml, which defines the hierarchy of symbols and categories. The JAR file also contains subdirectories which store:
Images used by the palette symbols
The CSS file describing the symbols
Additional resources
The following figure shows the structure of a palette JAR file.
The palette structure
There are two main scenarios when loading a palette:
Scenario 1: The application uses a fixed set of symbols from a palette. In this case, the easiest way is to put the palette on the class path. No palette manager is needed.
Scenario 2: The application uses a variable set of palettes. The application allows you to dynamically load palettes from the user file system at any time. In this case, a palette manager is needed, since only a palette manager can load palettes that are not on the class path.
To load a palette in Scenario 1:
1. Make sure the palette.jar file is in the class path.
2. Create a palette:
new IlvPalette();
3. Load the palette data from the .jar file.
You need to know the path to the palette description. For example, the description of the palette lib/palettes/jviews-palette-shared-symbols-9.0.jar is in ilog/views/palettes/shared/palette.xml. You see the path when you look at the palette in the Symbol Editor.
palette.load(getClass().getResource(pathToPaletteXML));
Now you have an
IlvPalette object filled with the palette data.
4. Retrieve a symbol from the palette by specifying its category and name path.
IlvPaletteSymbol psymbol = palette.getSymbol("Symbols.Controls.Dial");
To load a palette in Scenario 2:
1. The palette.jar must be somewhere on the file system. It does not have to be on the class path. The file system must be accessible.
2. Load the palette through the palette manager:
IlvPalette[] palettes = myIlvPaletteManager.load(new URL("file://c:/
myPalette.jar"));
Since the .jar file can contain multiple palettes, an array of palettes is returned. These palettes are also added to the palette manager.
3. Retrieve a symbol from the palette by specifying its category and name path, like in scenario 1.
For example, if the palettes array contains only one palette:
IlvPaletteSymbol psymbol = palettes[0].getSymbol("Symbols.Controls.Dial");
Saving palettes
Saving a palette on the file system can be done through the palette manager. The palette manager first saves the palette hierarchy in a working directory and then packages the working directory into a .jar file.
To save a palette:
1. Specify the working directory:
myIlvPaletteManager.setWorkingDirectory(new File("/tmp"));
2. Save the palette in the current directory:
myIlvPaletteManager.save(palette, new File("myPalette.jar"));
When a palette is saved, symbol resources, such as images which were imported from outside the palette .jar file are copied into it. Links to these resources are updated accordingly. Therefore, the resulting file myPalette.jar is self-contained, that is, it does no longer contain any reference to external files.
Copyright © 2018, Rogue Wave Software, Inc. All Rights Reserved.
