public class UIManager

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

Methods

public static int getThemeGeneration()The current theme generation; see themeGeneration.
public static UIManager getInstance()Singleton instance method
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
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.
public static Resources initNamedTheme(String resourceFile, String resName)Same as the initFirstTheme method, but unlike that method this allows specifying the theme resource name
public boolean isUseLargerTextScale()Checks if larger text scaling is enabled.
public void setUseLargerTextScale(boolean useLargerTextScale)Enables or disables scaling fonts when larger text is enabled on the device.
public boolean wasThemeInstalled()Indicates if a theme was previously installed since the last reset
public LookAndFeel getLookAndFeel()Returns the currently installed look and feel
public void setLookAndFeel(LookAndFeel plaf)Sets the currently installed look and feel
public void setComponentStyle(String id, Style style)Allows a developer to programmatically install a style into the UI manager
public void setComponentStyle(String id, Style style, String type)Allows a developer to programmatically install a style into the UI manager
public void setComponentSelectedStyle(String id, Style style)Allows a developer to programmatically install a style into the UI manager
public final Style getComponentStyle(String id)Returns the style of the component with the given id or a new instance of the default style.
public String getIconUIIDFor(String id)Gets the IconUIID for the given UIID.
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.
public Style getComponentSelectedStyle(String id)Returns the selected style of the component with the given id or a new instance of the default style.
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.
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.
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.
public String getThemeName()
public void setThemeProps(Hashtable themeProps)Allows manual theme loading from a hashtable of key/value pairs
public void addThemeProps(Hashtable themeProps)Adds the given theme properties on top of the existing properties without clearing the existing theme first
public void zoomFonts(float factor)Scales the font sizes of the current theme by the given factor, e.g. a factor of 1.2 increases all font sizes by 20% and a factor of 0.8 decreases them by 20%.
public void refreshTheme()Invalidates the cached Style instances and re-runs the theme build pass against the currently installed theme properties.
public int getThemeConstant(String constantName, int def)Returns a theme constant defined in the resource editor
public final String getThemeConstant(String constantName, String def)Returns a theme constant defined in the resource editor
public final boolean isThemeConstant(String constantName, boolean def)Returns a theme constant defined in the resource editor as a boolean value
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
public Image getThemeImageConstant(String constantName)Returns a theme constant defined in the resource editor
public Object getThemeMaskConstant(String constantName)Returns a theme mask constant
public Hashtable getResourceBundle()Deprecated 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.
public void setResourceBundle(Hashtable resourceBundle)Deprecated 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.
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.
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.
public final String localize(String key, String defaultValue)Localizes the given string from the resource bundle if such a String exists in the resource bundle.
protected void onLocalize(String key, String defaultValue)Callback for subclasses that wish to track localization invocations.
public void addThemeRefreshListener(ActionListener l)Adds a Theme refresh listener.
public void removeThemeRefreshListener(ActionListener l)Removes a Theme refresh listener.

Inherited methods

From Object

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

Method details

getThemeGeneration

public static int getThemeGeneration()
The current theme generation; see themeGeneration.

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

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:

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

Parameters

resourceFile String
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 String
the name of the resource file starting with / and without the res extension
resName String
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

isUseLargerTextScale

public boolean isUseLargerTextScale()
Checks if larger text scaling is enabled.

Returns

true if larger text scaling should be applied.

setUseLargerTextScale

public void setUseLargerTextScale(boolean useLargerTextScale)
Enables or disables scaling fonts when larger text is enabled on the device. This can also be enabled via the useLargerTextScaleBool theme constant.

Parameters

useLargerTextScale boolean
true to apply Display#getLargerTextScale() when Display#isLargerTextEnabled() is true.

wasThemeInstalled

public boolean wasThemeInstalled()
Indicates if a theme was previously installed since the last reset

Returns

true if setThemeProps was invoked

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 LookAndFeel
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 String
the component id matching the given style
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 String
the component id matching the given style
style Style
the style object to install
type String
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 String
the component id matching the given style
style Style
the style object to install

getComponentStyle

public final 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 String
the component id whose style we want

Returns

the appropriate style (this method never returns null)

getIconUIIDFor

public String getIconUIIDFor(String id)
Gets the IconUIID for the given UIID. If the theme defines a style that is named ${id}Icon (i.e. the id with “Icon” suffix) such that it derives from id, then this style is deemed to be the icon style corresponding with id.

Parameters

id String
The UIID to check for a companion UIID.

Returns

The IconUIID corresponding to the given ID - or null if none is defined in the theme.

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 Resources
Theme file used to retrieve images that are referenced by the styleString
baseStyle String
The component ID that serves as the base style for this style. These base styles are overridden by the styles provided in styleString.
id String
the component id into which the resulting style is to be cached.
styleString String...
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 String
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 Resources
Theme file used to retrieve images that are referenced by the styleString
baseStyle String
The component ID that serves as the base style for this style. These base styles are overridden by the styles provided in styleString.
id String
the component id into which the resulting style is to be cached.
styleString String...
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 String
the component id whose custom style we want
type String
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 Resources
Theme file used to retrieve images that are referenced by the styleString
baseStyle String
The component ID that serves as the base style for this style. These base styles are overridden by the styles provided in styleString.
id String
the component id into which the resulting style is to be cached.
type String
the style type
styleString String...
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 Hashtable
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 Hashtable
the properties of the given theme

zoomFonts

public void zoomFonts(float factor)

Scales the font sizes of the current theme by the given factor, e.g. a factor of 1.2 increases all font sizes by 20% and a factor of 0.8 decreases them by 20%. Only fonts that support scaling (TTF or native: fonts, see Font.isTTFNativeFont()) are affected; system fonts are skipped since their size is fixed by the underlying platform.

The zoom is applied relative to the current state of the theme, so calling this method repeatedly compounds the effect. To undo a zoom, either reapply the theme or call this method with the reciprocal factor.

Note: this updates the theme definitions and clears the cached styles, but components already shown on a form continue to render with the Font instances they captured before the call. To apply the new sizes to a live form, invoke refreshTheme() on it (typically CN.getCurrentForm().refreshTheme()) after calling this method.

Parameters

factor float
the multiplier applied to every scalable font size. Must be greater than zero.

refreshTheme

public void refreshTheme()
Invalidates the cached Style instances and re-runs the theme build pass against the currently installed theme properties. Callers use this after state changes that affect style resolution (notably Display.setDarkMode, which makes $Dark<UIID> entries eligible) without reloading the theme from a resource file. Components styled after this call resolve against the refreshed theme; already-resolved Style references on existing components keep their old values until those components re-fetch their styles.

getThemeConstant

public int getThemeConstant(String constantName, int def)
Returns a theme constant defined in the resource editor

Parameters

constantName String
the name of the constant
def int
default value

Returns

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

getThemeConstant

public final String getThemeConstant(String constantName, String def)
Returns a theme constant defined in the resource editor

Parameters

constantName String
the name of the constant
def String
default value

Returns

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

isThemeConstant

public final boolean isThemeConstant(String constantName, boolean def)
Returns a theme constant defined in the resource editor as a boolean value

Parameters

constantName String
the name of the constant
def boolean
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 String
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 String
the name of the constant

Returns

the image if defined

getThemeMaskConstant

public Object getThemeMaskConstant(String constantName)
Returns a theme mask constant

Parameters

constantName String
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

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 Hashtable
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.

localize

public final 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 String
The key used to lookup in the resource bundle
defaultValue String
the value returned if no such key exists

Returns

either default value or the appropriate value

onLocalize

protected void onLocalize(String key, String defaultValue)
Callback for subclasses that wish to track localization invocations.

Parameters

key String
The key used to lookup in the resource bundle
defaultValue String
the value returned if no such key exists

addThemeRefreshListener

public void addThemeRefreshListener(ActionListener l)
Adds a Theme refresh listener. The listenres will get a callback when setThemeProps method is invoked.

Parameters

l ActionListener
an ActionListener to be added

removeThemeRefreshListener

public void removeThemeRefreshListener(ActionListener l)
Removes a Theme refresh listener.

Parameters

l ActionListener
an ActionListener to be removed