com.codename1.ui.plaf

Class UIManager

java.lang.Object

com.codename1.ui.plaf.UIManager

public class UIManager
extends Object

Central point singleton managing the look of the application, this class allows us to customize the styles (themes) as well as the look instance.

Author:

Chen Fishbein

Method Summary

Modifier and Type	Method and Description
void	addThemeProps(Hashtable themeProps) Adds the given theme properties on top of the existing properties without clearing the existing theme first
void	addThemeRefreshListener(ActionListener l) Adds a Theme refresh listener.
static UIManager	createInstance() This factory method allows creating a new UIManager instance, this is usefull where an application has some screens with different context
Map<String,String>	getBundle() The resource bundle allows us to implicitly localize the UI on the fly, once its installed all internal application strings query the resource bundle and extract their values from this table if applicable.
Style	getComponentCustomStyle(String id, String type) Returns a custom style for the component with the given id, this method always returns a new instance.
Style	getComponentSelectedStyle(String id) Returns the selected style of the component with the given id or a new instance of the default style.
Style	getComponentStyle(String id) Returns the style of the component with the given id or a new instance of the default style.
static UIManager	getInstance() Singleton instance method
LookAndFeel	getLookAndFeel() Returns the currently installed look and feel
Hashtable	getResourceBundle() Deprecated. this method uses the old resource bundle hashtable, use the new getBundle() method
int	getThemeConstant(String constantName, int def) Returns a theme constant defined in the resource editor
String	getThemeConstant(String constantName, String def) Returns a theme constant defined in the resource editor
Image	getThemeImageConstant(String constantName) Returns a theme constant defined in the resource editor
Object	getThemeMaskConstant(String constantName) Returns a theme mask constant
String	getThemeName()
static Resources	initFirstTheme(String resourceFile) This is a shorthand notation for boilerplate code for initializing the first theme in the given resource file and catching/doing nothing with the IOException since this would be invoked too early in the program where we would be out of options if something like that happens.
static Resources	initNamedTheme(String resourceFile, String resName) Same as the initFirstTheme method, but unlike that method this allows specifying the theme resource name
Boolean	isThemeConstant(String constantName) Returns a theme constant defined in the resource editor as a boolean value or null if the constant isn't defined
boolean	isThemeConstant(String constantName, boolean def) Returns a theme constant defined in the resource editor as a boolean value
String	localize(String key, String defaultValue) Localizes the given string from the resource bundle if such a String exists in the resource bundle.
Style	parseComponentCustomStyle(Resources theme, String baseStyle, String id, String type, String... styleString) Returns the selected style of the component with the given baseStyle or a new instance of the default style, but overrides styles based on the directives in the styleStrings.
Style	parseComponentSelectedStyle(Resources theme, String baseStyle, String id, String... styleString) Returns the selected style of the component with the given baseStyle or a new instance of the default style, but overrides styles based on the directives in the styleStrings.
Style	parseComponentStyle(Resources theme, String baseStyle, String id, String... styleString) Returns the style of the component with the given baseStyle or a new instance of the default style, but overrides styles based on the directives in the styleStrings.
void	removeThemeRefreshListener(ActionListener l) Removes a Theme refresh listener.
void	setBundle(Map<String,String> bundle) The resource bundle allows us to implicitly localize the UI on the fly, once its installed all internal application strings query the resource bundle and extract their values from this table if applicable.
void	setComponentSelectedStyle(String id, Style style) Allows a developer to programmatically install a style into the UI manager
void	setComponentStyle(String id, Style style) Allows a developer to programmatically install a style into the UI manager
void	setComponentStyle(String id, Style style, String type) Allows a developer to programmatically install a style into the UI manager
void	setLookAndFeel(LookAndFeel plaf) Sets the currently installed look and feel
void	setResourceBundle(Hashtable resourceBundle) Deprecated. this method uses the old resource bundle hashtable, use the new setBundle() method
void	setThemeProps(Hashtable themeProps) Allows manual theme loading from a hashtable of key/value pairs
boolean	wasThemeInstalled() Indicates if a theme was previously installed since the last reset

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Detail

wasThemeInstalled

public boolean wasThemeInstalled()

Indicates if a theme was previously installed since the last reset

Returns:

true if setThemeProps was invoked

getInstance

public static UIManager getInstance()

Singleton instance method

Returns:

Instance of the ui manager

createInstance

public static UIManager createInstance()

This factory method allows creating a new UIManager instance, this is usefull where an application has some screens with different context

Returns:

a new UIManager instance

getLookAndFeel

public LookAndFeel getLookAndFeel()

Returns the currently installed look and feel

Returns:

the currently installed look and feel

setLookAndFeel

public void setLookAndFeel(LookAndFeel plaf)

Sets the currently installed look and feel

Parameters:

plaf - the look and feel for the application

setComponentStyle

public void setComponentStyle(String id,
                              Style style)

Allows a developer to programmatically install a style into the UI manager

Parameters:

id - the component id matching the given style

style - the style object to install

setComponentStyle

public void setComponentStyle(String id,
                              Style style,
                              String type)

Allows a developer to programmatically install a style into the UI manager

Parameters:

id - the component id matching the given style

style - the style object to install

type - press, dis or other custom type

setComponentSelectedStyle

public void setComponentSelectedStyle(String id,
                                      Style style)

Allows a developer to programmatically install a style into the UI manager

Parameters:

id - the component id matching the given style

style - the style object to install

getComponentStyle

public Style getComponentStyle(String id)

Returns the style of the component with the given id or a new instance of the default style. This method will always return a new style instance to prevent modification of the global style object.

Parameters:

id - the component id whose style we want

Returns:

the appropriate style (this method never returns null)

parseComponentStyle

public Style parseComponentStyle(Resources theme,
                                 String baseStyle,
                                 String id,
                                 String... styleString)

Returns the style of the component with the given baseStyle or a new instance of the default style, but overrides styles based on the directives in the styleStrings. This method will always return a new style instance to prevent modification of the global style object.

Parameters:

theme - Theme file used to retrieve images that are referenced by the styleString

baseStyle - The component ID that serves as the base style for this style. These base styles are overridden by the styles provided in styleString.

id - the component id into which the resulting style is to be cached.

styleString - Array of style strings to override the styles in baseStyle. Style string syntax is is key1:value1; key2:value2; key3:value3; etc.... While this is similar to CSS, it is not CSS. The keys and values correspond to properties of Style and their associated values.

Returns:

the appropriate style (this method never returns null)

getComponentSelectedStyle

public Style getComponentSelectedStyle(String id)

Returns the selected style of the component with the given id or a new instance of the default style. This method will always return a new style instance to prevent modification of the global style object.

Parameters:

id - the component id whose selected style we want

Returns:

the appropriate style (this method never returns null)

parseComponentSelectedStyle

public Style parseComponentSelectedStyle(Resources theme,
                                         String baseStyle,
                                         String id,
                                         String... styleString)

Returns the selected style of the component with the given baseStyle or a new instance of the default style, but overrides styles based on the directives in the styleStrings. This method will always return a new style instance to prevent modification of the global style object.

Parameters:

theme - Theme file used to retrieve images that are referenced by the styleString

baseStyle - The component ID that serves as the base style for this style. These base styles are overridden by the styles provided in styleString.

id - the component id into which the resulting style is to be cached.

styleString - Array of style strings to override the styles in baseStyle. Style string syntax is is key1:value1; key2:value2; key3:value3; etc.... While this is similar to CSS, it is not CSS. The keys and values correspond to properties of Style and their associated values.

Returns:

the appropriate style (this method never returns null)

getComponentCustomStyle

public Style getComponentCustomStyle(String id,
                                     String type)

Returns a custom style for the component with the given id, this method always returns a new instance. Custom styles allow us to install application specific or component specific style attributes such as pressed, disabled, hover etc.

Parameters:

id - the component id whose custom style we want

type - the style type

Returns:

the appropriate style (this method never returns null)

parseComponentCustomStyle

public Style parseComponentCustomStyle(Resources theme,
                                       String baseStyle,
                                       String id,
                                       String type,
                                       String... styleString)

Returns the selected style of the component with the given baseStyle or a new instance of the default style, but overrides styles based on the directives in the styleStrings. This method will always return a new style instance to prevent modification of the global style object.

Parameters:

theme - Theme file used to retrieve images that are referenced by the styleString

baseStyle - The component ID that serves as the base style for this style. These base styles are overridden by the styles provided in styleString.

id - the component id into which the resulting style is to be cached.

type - the style type

styleString - Array of style strings to override the styles in baseStyle. Style string syntax is is key1:value1; key2:value2; key3:value3; etc.... While this is similar to CSS, it is not CSS. The keys and values correspond to properties of Style and their associated values.

Returns:

the appropriate style (this method never returns null)

getThemeName

public String getThemeName()

Returns:

the name of the current theme for theme switching UI's

setThemeProps

public void setThemeProps(Hashtable themeProps)

Allows manual theme loading from a hashtable of key/value pairs

Parameters:

themeProps - the properties of the given theme

addThemeProps

public void addThemeProps(Hashtable themeProps)

Adds the given theme properties on top of the existing properties without clearing the existing theme first

Parameters:

themeProps - the properties of the given theme

getThemeConstant

public int getThemeConstant(String constantName,
                            int def)

Returns a theme constant defined in the resource editor

Parameters:

constantName - the name of the constant

def - default value

Returns:

the value of the constant or the default if the constant isn't in the theme

getThemeConstant

public String getThemeConstant(String constantName,
                               String def)

Returns a theme constant defined in the resource editor

Parameters:

constantName - the name of the constant

def - default value

Returns:

the value of the constant or the default if the constant isn't in the theme

isThemeConstant

public boolean isThemeConstant(String constantName,
                               boolean def)

Returns a theme constant defined in the resource editor as a boolean value

Parameters:

constantName - the name of the constant

def - default value

Returns:

the value of the constant or the default if the constant isn't in the theme

isThemeConstant

public Boolean isThemeConstant(String constantName)

Returns a theme constant defined in the resource editor as a boolean value or null if the constant isn't defined

Parameters:

constantName - the name of the constant

Returns:

the value of the constant or null if the constant isn't in the theme

getThemeImageConstant

public Image getThemeImageConstant(String constantName)

Returns a theme constant defined in the resource editor

Parameters:

constantName - the name of the constant

Returns:

the image if defined

getThemeMaskConstant

public Object getThemeMaskConstant(String constantName)

Returns a theme mask constant

Parameters:

constantName - the name of the constant

Returns:

the mask if defined

getResourceBundle

public Hashtable getResourceBundle()

Deprecated. this method uses the old resource bundle hashtable, use the new getBundle() method

The resource bundle allows us to implicitly localize the UI on the fly, once its installed all internal application strings query the resource bundle and extract their values from this table if applicable.

Returns:

the localization bundle

getBundle

public Map<String,String> getBundle()

The resource bundle allows us to implicitly localize the UI on the fly, once its installed all internal application strings query the resource bundle and extract their values from this table if applicable.

Returns:

the localization bundle

setBundle

public void setBundle(Map<String,String> bundle)

The resource bundle allows us to implicitly localize the UI on the fly, once its installed all internal application strings query the resource bundle and extract their values from this table if applicable.

Parameters:

resourceBundle - the localization bundle

setResourceBundle

public void setResourceBundle(Hashtable resourceBundle)

Deprecated. this method uses the old resource bundle hashtable, use the new setBundle() method

The resource bundle allows us to implicitly localize the UI on the fly, once its installed all internal application strings query the resource bundle and extract their values from this table if applicable.

Parameters:

resourceBundle - the localization bundle

localize

public String localize(String key,
                       String defaultValue)

Localizes the given string from the resource bundle if such a String exists in the resource bundle. If no key exists in the bundle then or a bundle is not installed the default value is returned.

Parameters:

key - The key used to lookup in the resource bundle

defaultValue - the value returned if no such key exists

Returns:

either default value or the appropriate value

addThemeRefreshListener

public void addThemeRefreshListener(ActionListener l)

Adds a Theme refresh listener. The listenres will get a callback when setThemeProps method is invoked.

Parameters:

l - an ActionListener to be added

removeThemeRefreshListener

public void removeThemeRefreshListener(ActionListener l)

Removes a Theme refresh listener.

Parameters:

l - an ActionListener to be removed

initFirstTheme

public static Resources initFirstTheme(String resourceFile)

This is a shorthand notation for boilerplate code for initializing the first theme in the given resource file and catching/doing nothing with the IOException since this would be invoked too early in the program where we would be out of options if something like that happens. Effectively this is the same as writing:

        try {
            theme = Resources.openLayered(resourceFile);
            UIManager.getInstance().setThemeProps(theme.getTheme(theme.getThemeResourceNames()[0]));
        } catch(IOException e){
            e.printStackTrace();
        }
 

Parameters:

resourceFile - the name of the resource file starting with / and without the res extension

Returns:

the resource file or null in case of a failure

initNamedTheme

public static Resources initNamedTheme(String resourceFile,
                                       String resName)

Same as the initFirstTheme method, but unlike that method this allows specifying the theme resource name

Parameters:

resourceFile - the name of the resource file starting with / and without the res extension

resName - the name of the theme to use from the file if it contains more than one theme

Returns:

the resource file or null in case of a failure