Overview  Package   Class  Tree  Deprecated  Index  Help 
EchoPoint
1.0
 PREV CLASS   NEXT CLASS FRAMES    NO FRAMES    
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

echopoint.stylesheet
Class CssStyleSheet

java.lang.Object
  extended byechopoint.stylesheet.CssStyleSheet
All Implemented Interfaces:
java.util.EventListener, java.beans.PropertyChangeListener, java.io.Serializable, StyleSheet
public class CssStyleSheet
extends java.lang.Object
implements StyleSheet, java.beans.PropertyChangeListener, java.io.Serializable

The CssStyleSheet class implements a StyleSheet for Echo derived Components.

A StyleSheet is a collection of style attributes that can be applied to a Component and any of its children. A StyleSheet object can listen for when child Components are added, and apply the StyleSheet to those child components

CssStyleSheet style data can be loaded from external files or other reader data sources. The format of the CssStyleSheet data is based on w3c Cascading Style Sheets, and has been made to look 'CSS like'. (although pure CSS files cannot be used.)

A CssStyleSheet file contain style instructions for a Component class. Lower level class names can be used. For example the 'font" attribute may be set for the class nextapp.echo.Component to Verdana. This means that all derived Components will have the Verdana font style applied to them unless they have an entry for a more specific class.

A map of all styles and classes is kept and when a given component is to have a CssStyleSheet applied to it, the application is done from least specific Class to most specific Class.

For example if a CssStyleSheet is applied to a PasswordField object, then a style will be searched first for the Component class, then the TextComponent class, the TextField class and then finally the PasswordField class.

This application of styles allows "cascading" style values to be applied to a given Component object. The more specific StyleSheet entries will overrride any previous entries.

CssStyleSheet data has a 'CSS like' format of :

 className1 [,classNameN]  { 				

    attributeName1 : attributeValue2;		

    ...									
		
    [attributeNameN : attributeValueN;]	

 }

Multiple class names can be specified for the one entry. The class names are case senstive however the style attribute names and values are not. Quotes can be used at any time within the entries.

For example :

 // comments allowed 						
 echopoint.DatePicker  { 					
    foreground : #FF00CC;					
    background : color(AA,99,CC);			
    rolloverEnabled : true;				
    font : 'sans serif',bold,12;				
    calendarFont : font(verdana,italic,16) 	
 }

C and C++ style comments (slash slash or slash asterisk) can be used anywhere within the CssStyleSheet data

The className can be in three forms :

Using groupName allows you to "logically" group a number of components under the one name. You do this by setting using an attributed identifier of "stylegroup=xxx", where xxx equals groupName.

Using id, will cause the styles to be applied to Components of a certain class that have the specified identifier or an attributed identifier of "style=xxx", where xxx equals id.

For more information on attributed identifiers, see echopoint.util.IdKit

For example :

 echopoint.PushButton  {					
    foreground : #FF00CC;					
    background : color(AA,99,CC);			
 }										
 

 echopoint.PushButton!large  {			
    font : 'sans serif',bold,24;				
 }
 

 echopoint.PushButton!small {				
    font : 'verdana',plain,8;					
 }
 echopoint.PushButton#pbId  {				
    font : 'serif',bold,12;					
 }

The ordering of application of styles is : className, className and groupName, className and finally id.

Use the CssStyleSheet.getInstance() to create new StyleSheet objects. This method will return a CssStyleSheet with handlers for both Echo and EchoPoint components.

The CssStyleSheet.getEmptyInstance() method returns a CssStyleSheet object with no CssStyleSheetHandlers within it. You would rarely use this method however.

If a Component class has a StyleInfo support class associated with it then the CssStyleSheet will invoke it to find out the class for values of a given style attribute name. This ensures that Style objects are created safely, with little chance of a ClassCastException when applied. This also allows case insensitive CCS attribute names to be turned into case sensitive Style attribute names.

Internally a SmartStyle object is built with all of the information in the style sheet. This is then applied to the Component via the Component.applyStyle() method. If any of the style attributes are not set during the applyStyle() method, then relection is used to find "setter" methods in the Component and this is used to set values.

NOTE : that this StyleInfo is optional, and if not found then the CssStyleSheet will make an intelligent guess about what class of object is required for a given attribute name.

See Also:
StyleSheetIntrospector, StyleInfo, SmartStyle, IdKit, Serialized Form

Method Summary
 void addGroup(StyleSheetGroup styleSheetGroup)
          Deprecated. StyleSheetGroup has been deprecated and will be removed in the next version of EchoPoint. Use the new attributed identifier on the Component from now on, eg component.setIdentifier("stylegroup=xxx;");
 void addHandler(CssStyleSheetHandler handler)
          Adds a CssStyleSheetHandler to the CssStyleSheet.
 void applyTo(nextapp.echo.Component c)
          This method applies the StyleSheet to the given Component c and all of its children.
 void applyTo(nextapp.echo.Component c, boolean listenForFutureChildren)
          This method applies the StyleSheet to the given Component c and all of its children.
 void applyTo(nextapp.echo.EchoInstance instance)
          This method applies the StyleSheet to the Windows of the given EchoInstance and all of their children.
 void applyTo(nextapp.echo.EchoInstance instance, boolean listenForFutureChildren)
          This method applies the StyleSheet to the Windows of the given EchoInstance and all of their children.
static CssStyleSheet getEmptyInstance()
          Returns an empty StyleSheet with no StyleSheetHandlers within it.
static CssStyleSheet getInstance()
          Returns a StyleSheet object.
static CssStyleSheet getInstance(java.io.Reader styleSheetReader)
          Returns a StyleSheet object by parsing the given Reader style sheet data.
static CssStyleSheet getInstance(java.lang.String styleSheetFileName)
          Returns a StyleSheet object by parsing the given style sheet file name.
static CssStyleSheet getInstance(java.net.URL styleSheetURL)
          Returns a StyleSheet object by parsing the given URL style sheet data.
 StyleSheetParseException[] getParseExceptions()
          This method returns an array of StyleSheetParseExceptions that have occurred during parsing.
 boolean isExceptionParseFailure()
          This returns true if the CssStyleSheet will throw an StyleSheetParseException if it encounters an invalid or unknown attribute.
 boolean isParseable()
          Returns true if the current CssStyleSheet can be parsed.
 void loadStyleSheet(java.io.Reader styleSheetReader)
          Loads the CssStyleSheet data contained in the Reader.
 void loadStyleSheet(java.lang.String styleSheetFileName)
          Loads the CssStyleSheet data contained in the file named "fileName".
 void loadStyleSheet(java.net.URL styleSheetURL)
          Loads the CssStyleSheet data contained in the URL.
 void propertyChange(java.beans.PropertyChangeEvent evt)
          This method gets called when a bound property is changed.
 void setExceptionParseFailure(boolean newExceptionParseFailure)
          This controls whether the CssStyleSheet will throw a StyleSheetParseException if it encounters an invalid or unknown attribute.
 void stopListeningTo(nextapp.echo.Component c)
          This stops the CssStyleSheet from listening for CHILDREN_PROPERTY_CHANGED events on the given Component c.
 void stopListeningTo(nextapp.echo.EchoInstance instance)
          This stops the StyleSheet from listening for EchoInstance.WINDOWS_CHANGED_PROPERTY and Component.CHILDREN_PROPERTY_CHANGED events on the given EchoInstance.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Method Detail

addGroup

public void addGroup(StyleSheetGroup styleSheetGroup)
Deprecated. StyleSheetGroup has been deprecated and will be removed in the next version of EchoPoint. Use the new attributed identifier on the Component from now on, eg component.setIdentifier("stylegroup=xxx;");

Adds a StyleSheetGroup to the StyleSheet.

Specified by:
addGroup in interface StyleSheet
Parameters:
styleSheetGroup - - the stylesheet group to add

addHandler

public void addHandler(CssStyleSheetHandler handler)
Adds a CssStyleSheetHandler to the CssStyleSheet. Ths allows extension of the known style attribute names and values.

applyTo

public void applyTo(nextapp.echo.Component c)
Description copied from interface: StyleSheet
This method applies the StyleSheet to the given Component c and all of its children.

This method can throw a StyleSheetInvalidValueException if a value of the wrong type is stored in a Style object. The StyleSheet is expected to catch the ClassCastException that might be thrown and then rethrow it as a StyleSheetInvalidValueException.

Specified by:
applyTo in interface StyleSheet
Parameters:
c - - the component to apply the style sheet to
See Also:
StyleSheet.applyTo(nextapp.echo.Component)

applyTo

public void applyTo(nextapp.echo.Component c,
                    boolean listenForFutureChildren)
Description copied from interface: StyleSheet
This method applies the StyleSheet to the given Component c and all of its children.

If listenForFutureChildren is true, then the StyleSheet is expected to listen for Component.CHILDREN_CHANGED_PROPERTY property change events and apply the StyleSheet to any new children.

The can be done by called the Component.addPropertyChangeListener

This method can throw a StyleSheetInvalidValueException if a value of the wrong type is stored in a Style object. The StyleSheet is expected to catch the ClassCastException that might be thrown and then rethrow it as a StyleSheetInvalidValueException.

Specified by:
applyTo in interface StyleSheet
Parameters:
c - - the component to apply the style sheet to
listenForFutureChildren - - whether to listen for future children
See Also:
StyleSheet.applyTo(nextapp.echo.Component, boolean)

applyTo

public void applyTo(nextapp.echo.EchoInstance instance)
Description copied from interface: StyleSheet
This method applies the StyleSheet to the Windows of the given EchoInstance and all of their children.

Be aware when using this function in EchoInstance.init(). Add that stage there are no Windows in the EchoInstance and it does not fire any events once it has finished, and hence the StyleSheet will not be applied. You can get around this issue by applying the StyleSheet to the Window object you must return in EchoInstance.init() as well as the EchoInstance itself. The code might look like this : 

 	public nextapp.echo.Window init() {
      Window window = new Window();
      ...
 		...
 		try {
 			styleSheet.applyTo(this,true);
 			styleSheet.applyTo(window);
 		} catch (StyleSheetParseException e) {
 			....
 		}
 		return window;
  }

This method can throw a StyleSheetInvalidValueException if a value of the wrong type is stored in a Style object. The StyleSheet is expected to catch the ClassCastException that might be thrown and then rethrow it as a StyleSheetInvalidValueException.

Specified by:
applyTo in interface StyleSheet
Parameters:
instance - - the EchoInstance to apply the style sheet to
See Also:
StyleSheet.applyTo(nextapp.echo.EchoInstance)

applyTo

public void applyTo(nextapp.echo.EchoInstance instance,
                    boolean listenForFutureChildren)
Description copied from interface: StyleSheet
This method applies the StyleSheet to the Windows of the given EchoInstance and all of their children.

If listenForFutureChildren is true, then the StyleSheet is expected to listen for EchoInstance.WINDOWS_CHANGED_PROPERTY and Component.CHILDREN_CHANGED_PROPERTY property change events and apply the StyleSheet to any new children.

Be aware when using this function in EchoInstance.init(). Add that stage there are no Windows in the EchoInstance and it does not fire any events once it has finished, and hence the StyleSheet will not be applied. You can get around this issue by applying the StyleSheet to the Window object you must return in EchoInstance.init() as well as the EchoInstance itself. The code might look like this : 

 	public nextapp.echo.Window init() {
      Window window = new Window();
      ...
 		...
 		try {
 			styleSheet.applyTo(this,true);
 			styleSheet.applyTo(window);
 		} catch (StyleSheetParseException e) {
 			....
 		}
 		return window;
  }

This method can throw a StyleSheetInvalidValueException if a value of the wrong type is stored in a Style object. The StyleSheet is expected to catch the ClassCastException that might be thrown and then rethrow it as a StyleSheetInvalidValueException.

Specified by:
applyTo in interface StyleSheet
Parameters:
instance - - the EchoInstance to apply the style sheet to
listenForFutureChildren - - whether to listen for future children
See Also:
StyleSheet.applyTo(nextapp.echo.EchoInstance, boolean)

getParseExceptions

public StyleSheetParseException[] getParseExceptions()
This method returns an array of StyleSheetParseExceptions that have occurred during parsing. Note that this will only have more than 1 entries if setExceptionParseFailure is set to true.

isExceptionParseFailure

public boolean isExceptionParseFailure()
This returns true if the CssStyleSheet will throw an StyleSheetParseException if it encounters an invalid or unknown attribute. The default is true.

Note : this only covers the setting of style attributes values, not the general parsing of the style sheet data. A general parse problem will always throw a StyleSheetParseException.

Returns:
boolean

loadStyleSheet

public void loadStyleSheet(java.io.Reader styleSheetReader)
                    throws StyleSheetParseException
Loads the CssStyleSheet data contained in the Reader.

Specified by:
loadStyleSheet in interface StyleSheet
Parameters:
styleSheetReader - - the Reader containg style sheet information
Throws:
StyleSheetParseException - - if the data cannot be parsed

loadStyleSheet

public void loadStyleSheet(java.lang.String styleSheetFileName)
                    throws StyleSheetParseException
Loads the CssStyleSheet data contained in the file named "fileName".

Throws:
StyleSheetParseException - - if the file cannot be parsed

loadStyleSheet

public void loadStyleSheet(java.net.URL styleSheetURL)
                    throws StyleSheetParseException
Loads the CssStyleSheet data contained in the URL.

Throws:
StyleSheetParseException - - if the data cannot be parsed

propertyChange

public void propertyChange(java.beans.PropertyChangeEvent evt)
This method gets called when a bound property is changed.

The CssStyleSheet class will listen for Component.CHILDREN_CHANGED_PROPERTY and EchoInstance.WINDOWS_CHANGED_PROPERTY events and will then apply any applicable Styles to the new Component and its children, or conversely, stop listening if the child is being removed.

Specified by:
propertyChange in interface java.beans.PropertyChangeListener
Parameters:
evt - A PropertyChangeEvent object describing the event source and the property that has changed.

setExceptionParseFailure

public void setExceptionParseFailure(boolean newExceptionParseFailure)
This controls whether the CssStyleSheet will throw a StyleSheetParseException if it encounters an invalid or unknown attribute.

Note : this only covers the setting of style attributes values, not the general parsing of the style sheet data. A general parse problem will always throw a StyleSheetParseException.

Parameters:
newExceptionParseFailure - boolean

stopListeningTo

public void stopListeningTo(nextapp.echo.Component c)
This stops the CssStyleSheet from listening for CHILDREN_PROPERTY_CHANGED events on the given Component c.

Specified by:
stopListeningTo in interface StyleSheet
Parameters:
c - - the component to stop listening for children on

stopListeningTo

public void stopListeningTo(nextapp.echo.EchoInstance instance)
Description copied from interface: StyleSheet
This stops the StyleSheet from listening for EchoInstance.WINDOWS_CHANGED_PROPERTY and Component.CHILDREN_PROPERTY_CHANGED events on the given EchoInstance.

Specified by:
stopListeningTo in interface StyleSheet
Parameters:
instance - - the EchoINstance to stop listening for children on
See Also:
StyleSheet.stopListeningTo(nextapp.echo.EchoInstance)

getEmptyInstance

public static CssStyleSheet getEmptyInstance()
Returns an empty StyleSheet with no StyleSheetHandlers within it.

The returned object implements StyleSheet and is an instance of CssStyleSheet.

Using this form allows the developer to change the StyleSheetHandlers used and/or the order in which they are applied.

getInstance

public static CssStyleSheet getInstance()
Returns a StyleSheet object.

The returned object implements StyleSheet and is an instance of CssStyleSheet.

getInstance

public static CssStyleSheet getInstance(java.io.Reader styleSheetReader)
                                 throws StyleSheetParseException
Returns a StyleSheet object by parsing the given Reader style sheet data.

The returned object implements StyleSheet and is an instance of CssStyleSheet.

Throws:
StyleSheetParseException

getInstance

public static CssStyleSheet getInstance(java.lang.String styleSheetFileName)
                                 throws StyleSheetParseException
Returns a StyleSheet object by parsing the given style sheet file name.

The returned object implements StyleSheet and is an instance of CssStyleSheet.

Throws:
StyleSheetParseException

getInstance

public static CssStyleSheet getInstance(java.net.URL styleSheetURL)
                                 throws StyleSheetParseException
Returns a StyleSheet object by parsing the given URL style sheet data.

The returned object implements StyleSheet and is an instance of CssStyleSheet.

Throws:
StyleSheetParseException

isParseable

public boolean isParseable()
Returns true if the current CssStyleSheet can be parsed. This does not mean that it is perfectly valid, since the application of the generated Style objects may still pose problems. But it does mean that the CssStyleSheet has validated style attribute name and values as best it can.

Returns:
true if the style sheet could be parsed
Overview  Package   Class  Tree  Deprecated  Index  Help 
EchoPoint
1.0
 PREV CLASS   NEXT CLASS FRAMES    NO FRAMES    
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD