Class ComponentState
- java.lang.Object
-
- org.pushingpixels.radiance.theming.api.ComponentState
-
public final class ComponentState extends java.lang.Object
Instances of this class correspond to states of Swing core and custom controls. This class provides a number of predefined static instances to cover most action-based controls such as buttons, check boxes and menu items. In addition, application code can define custom component states that create fine grained mapping between arbitrary states of controls and specific color scheme bundles in custom skins.
Each component state is defined by two arrays of component state facets (available in
RadianceThemingSlices.ComponentStateFacet
class). The first array specifies the facets that are on, and the second array specifies the facets that are off. For example, when a selected toggle button is pressed, it transitions toPRESSED_SELECTED
state. This state hasRadianceThemingSlices.ComponentStateFacet.ENABLE
,RadianceThemingSlices.ComponentStateFacet.SELECTION
andRadianceThemingSlices.ComponentStateFacet.PRESS
as its on facets. If a selected toggle button is disabled, it hasRadianceThemingSlices.ComponentStateFacet.SELECTION
in its on facets andRadianceThemingSlices.ComponentStateFacet.ENABLE
in its off facets.The
RadianceThemingSlices.ComponentStateFacet
class defines a number of core facets. TheRadianceThemingSlices.ComponentStateFacet.ENABLE
facet is universal - it is relevant for all Swing controls. Some facets apply to a wider range of controls. For example,RadianceThemingSlices.ComponentStateFacet.ROLLOVER
facet applies to all controls that can show rollover effects - including buttons, menu items, comboboxes, sliders, scrollbars and many more. Some facets apply to a very narrow range of controls. For example,RadianceThemingSlices.ComponentStateFacet.DETERMINATE
is only relevant for progress bars.The static instances of
ComponentState
defined in this class do not aim to cover all possible combinations of on and off facets. In addition to making this class too unwieldy, it is not possible to do since application code can define its own facets. Instead, Radiance provides three ways to fine-tune the mapping between the component states and the color schemes used to paint the components.- When the skin is queried for the color scheme that matches the specific
component state - let's say
PRESSED_SELECTED
- the skinning layer first looks for the exact state (as passed toRadianceColorSchemeBundle.registerColorScheme(RadianceColorScheme, RadianceThemingSlices.ColorSchemeAssociationKind, ComponentState...)
or similar APIs). If the exact match is found, it is used. If there is no exact match, the skinning layer will look at all color schemes registered for the specific color scheme association kind in the matching color scheme bundle. The decision is made based on how "close" the registered component state is to the component state of the currently painted component. For example,PRESSED_SELECTED
is a better match forPRESSED_UNSELECTED
thanROLLOVER_SELECTED
- since theRadianceThemingSlices.ComponentStateFacet.PRESS
has more weight than theRadianceThemingSlices.ComponentStateFacet.ROLLOVER
in the decision process. The skinning layer will choose the "closest" registered component state that is sufficiently close. For example,DISABLED_SELECTED
will never be chosen forSELECTED
, even if there are no other registered component states. This way the application code can register a few color schemes in the specific bundle, and have all other states "fall back" to the smaller subset of states. - Custom application components may have facets that do not directly map to
the core facets defined in the
RadianceThemingSlices.ComponentStateFacet
class. In this case, the application code can create its own facet instances, and its own component states that use those facets in the on and off lists. Part of the custom code will be in the UI delegates that compute the current state of the custom component using the new facets. Other part of the custom code will be in the skin definition that maps the component states defined with the new facets to the specific color schemes.
Note that you do not have to create explicit dependency between custom component states used in the skin definition and custom component states used in the painting routines (in the UI delegates). In fact, the custom component states defined in the Radiance UI delegate for progress bar are not accessible to the application code. The recommended way to separate the skin definition from the model lookups in the painting is:
- The skin definition defines a sufficiently broad set of custom component states that use the new facets. Note that you do not have to create a custom state for every possible permutation of new facets (along with the relevant core facets). A well defined set of component states will provide a good fallback state for every relevant permutation of facets, keeping the skin definition small and manageable.
- The UI delegate that queries the component model will use accurate
component states that account for all the relevant on and off facets -
including the core facets defined in the
RadianceThemingSlices.ComponentStateFacet
class. When this (perhaps elaborate) state is passed toRadianceColorSchemeBundle.getColorScheme(RadianceThemingSlices.ColorSchemeAssociationKind, ComponentState, boolean)
API, the procedure described above will match the this state to one of the "base" states defined in your skin, and use the matching color scheme.
Note that the matching algorithm only looks at the facets in the on and off lists, and ignores the component state name. This allows you to create a broad component state in your skin, and a number of narrow component states during the painting - and have the Radiance skinning layer find the best match.
When the matching algorithm cannot find a sufficiently close match, the skinning layer will fall back on one of the three base color schemes passed to the
RadianceColorSchemeBundle(RadianceColorScheme, RadianceColorScheme, RadianceColorScheme)
constructor. States withRadianceThemingSlices.ComponentStateFacet.ENABLE
in their off list will fall back to the disabled color scheme. TheENABLED
will fall back to the enabled color scheme. The rest of the states will fall back to the active color scheme. To change the fallback behavior pass a non-null fallback color scheme to theComponentState(String, ComponentState, RadianceThemingSlices.ComponentStateFacet[], RadianceThemingSlices.ComponentStateFacet[])
constructor as the second parameter. - When the skin is queried for the color scheme that matches the specific
component state - let's say
-
-
Field Summary
Fields Modifier and Type Field Description private static java.util.Set<ComponentState>
allStates
static ComponentState
ARMED
Armed.static ComponentState
DEFAULT
Default.static ComponentState
DETERMINATE
Determinatestatic ComponentState
DISABLED_DEFAULT
Disabled default.static ComponentState
DISABLED_DETERMINATE
Disabled and determinate.static ComponentState
DISABLED_INDETERMINATE
Disabled and indeterminate.static ComponentState
DISABLED_MIXED
Disabled and mixed.static ComponentState
DISABLED_SELECTED
Disabled selected.static ComponentState
DISABLED_UNSELECTED
Disabled and not selected.static ComponentState
ENABLED
Enabled state.private java.util.Set<RadianceThemingSlices.ComponentStateFacet>
facetsTurnedOff
Facets that are turned on for this state.private java.util.Set<RadianceThemingSlices.ComponentStateFacet>
facetsTurnedOn
Facets that are turned on for this state.private ComponentState
hardFallback
static ComponentState
INDETERMINATE
Indeterminateprivate java.util.Map<RadianceThemingSlices.ComponentStateFacet,java.lang.Boolean>
mappingOn
static ComponentState
MIXED
Mixprivate java.lang.String
name
static ComponentState
PRESSED_MIXED
Pressed and mix.static ComponentState
PRESSED_SELECTED
Pressed selected.static ComponentState
PRESSED_UNSELECTED
Pressed and not selected.static ComponentState
ROLLOVER_ARMED
Armed and rolled over.static ComponentState
ROLLOVER_MIXED
Mix and rolled over.static ComponentState
ROLLOVER_SELECTED
Selected and rolled over.static ComponentState
ROLLOVER_UNSELECTED
Not selected and rolled over.static ComponentState
SELECTED
Selected.
-
Constructor Summary
Constructors Constructor Description ComponentState(java.lang.String name, ComponentState hardFallback, RadianceThemingSlices.ComponentStateFacet[] facetsOn, RadianceThemingSlices.ComponentStateFacet[] facetsOff)
Creates a new component state.ComponentState(java.lang.String name, RadianceThemingSlices.ComponentStateFacet[] facetsOn, RadianceThemingSlices.ComponentStateFacet[] facetsOff)
Creates a new component state.
-
Method Summary
All Methods Static Methods Instance Methods Concrete Methods Modifier and Type Method Description ComponentState
bestFit(java.util.Collection<ComponentState> states)
boolean
equals(java.lang.Object obj)
private int
fitValue(ComponentState state)
static ComponentState[]
getActiveStates()
Returns all active component states.static ComponentState[]
getAllStates()
Returns all component states.ComponentState
getHardFallback()
static ComponentState
getState(boolean isEnabled, boolean isRollover, boolean isSelected)
Returns the component state that matches the specified parameters.static ComponentState
getState(javax.swing.AbstractButton button)
Returns the state of the specified button.static ComponentState
getState(javax.swing.ButtonModel model, javax.swing.JComponent component)
Retrieves component state based on the button model (required parameter) and component itself (optional parameter).static ComponentState
getState(javax.swing.ButtonModel model, javax.swing.JComponent component, boolean toIgnoreSelection)
Retrieves component state based on the button model (required parameter) and button itself (optional parameter).static ComponentState
getState(TriStateButtonModel model, boolean toIgnoreSelection)
int
hashCode()
boolean
isActive()
boolean
isDisabled()
Checks whether this state is disabled.boolean
isFacetActive(RadianceThemingSlices.ComponentStateFacet stateFacet)
Returns indication whetherthis
component state is "active" under the specified facet.java.lang.String
toString()
-
-
-
Field Detail
-
allStates
private static java.util.Set<ComponentState> allStates
-
DISABLED_DEFAULT
public static final ComponentState DISABLED_DEFAULT
Disabled default. Used for disabled buttons that have been marked asdefault
withJRootPane.setDefaultButton(JButton)
API.
-
DEFAULT
public static final ComponentState DEFAULT
Default. Used for enabled buttons that have been marked asdefault
withJRootPane.setDefaultButton(JButton)
API.
-
DISABLED_SELECTED
public static final ComponentState DISABLED_SELECTED
Disabled selected.
-
DISABLED_UNSELECTED
public static final ComponentState DISABLED_UNSELECTED
Disabled and not selected.
-
DISABLED_INDETERMINATE
public static final ComponentState DISABLED_INDETERMINATE
Disabled and indeterminate.
-
DISABLED_DETERMINATE
public static final ComponentState DISABLED_DETERMINATE
Disabled and determinate.
-
DISABLED_MIXED
public static final ComponentState DISABLED_MIXED
Disabled and mixed.
-
PRESSED_SELECTED
public static final ComponentState PRESSED_SELECTED
Pressed selected.
-
PRESSED_UNSELECTED
public static final ComponentState PRESSED_UNSELECTED
Pressed and not selected.
-
PRESSED_MIXED
public static final ComponentState PRESSED_MIXED
Pressed and mix.
-
SELECTED
public static final ComponentState SELECTED
Selected.
-
ROLLOVER_SELECTED
public static final ComponentState ROLLOVER_SELECTED
Selected and rolled over.
-
ROLLOVER_UNSELECTED
public static final ComponentState ROLLOVER_UNSELECTED
Not selected and rolled over.
-
ROLLOVER_MIXED
public static final ComponentState ROLLOVER_MIXED
Mix and rolled over.
-
ARMED
public static final ComponentState ARMED
Armed.
-
ROLLOVER_ARMED
public static final ComponentState ROLLOVER_ARMED
Armed and rolled over.
-
DETERMINATE
public static final ComponentState DETERMINATE
Determinate
-
INDETERMINATE
public static final ComponentState INDETERMINATE
Indeterminate
-
MIXED
public static final ComponentState MIXED
Mix
-
ENABLED
public static final ComponentState ENABLED
Enabled state.
-
facetsTurnedOn
private java.util.Set<RadianceThemingSlices.ComponentStateFacet> facetsTurnedOn
Facets that are turned on for this state. For example,ROLLOVER_SELECTED
containsRadianceThemingSlices.ComponentStateFacet.ROLLOVER
andRadianceThemingSlices.ComponentStateFacet.SELECTION
.
-
facetsTurnedOff
private java.util.Set<RadianceThemingSlices.ComponentStateFacet> facetsTurnedOff
Facets that are turned on for this state. For example,DISABLED_UNSELECTED
containsRadianceThemingSlices.ComponentStateFacet.ENABLE
andRadianceThemingSlices.ComponentStateFacet.SELECTION
.
-
mappingOn
private java.util.Map<RadianceThemingSlices.ComponentStateFacet,java.lang.Boolean> mappingOn
-
name
private java.lang.String name
-
hardFallback
private ComponentState hardFallback
-
-
Constructor Detail
-
ComponentState
public ComponentState(java.lang.String name, RadianceThemingSlices.ComponentStateFacet[] facetsOn, RadianceThemingSlices.ComponentStateFacet[] facetsOff)
Creates a new component state.- Parameters:
name
- Component state name. Does not have to be unique. The name is only used in thetoString()
.facetsOn
- Indicates that are turned on for this state. For example,ROLLOVER_SELECTED
should pass bothRadianceThemingSlices.ComponentStateFacet.ROLLOVER
andRadianceThemingSlices.ComponentStateFacet.SELECTION
.facetsOff
- Indicates that are turned on for this state. For example,DISABLED_UNSELECTED
should pass bothRadianceThemingSlices.ComponentStateFacet.ENABLE
andRadianceThemingSlices.ComponentStateFacet.SELECTION
.
-
ComponentState
public ComponentState(java.lang.String name, ComponentState hardFallback, RadianceThemingSlices.ComponentStateFacet[] facetsOn, RadianceThemingSlices.ComponentStateFacet[] facetsOff)
Creates a new component state.- Parameters:
name
- Component state name. Does not have to be unique. The name is only used in thetoString()
.hardFallback
- The fallback state that will be used inRadianceColorSchemeBundle.getColorScheme(RadianceThemingSlices.ColorSchemeAssociationKind, ComponentState, boolean)
in casebestFit(Collection)
returnsnull
facetsOn
- Indicates that are turned on for this state. For example,ROLLOVER_SELECTED
should pass bothRadianceThemingSlices.ComponentStateFacet.ROLLOVER
andRadianceThemingSlices.ComponentStateFacet.SELECTION
.facetsOff
- Indicates that are turned on for this state. For example,DISABLED_UNSELECTED
should pass bothRadianceThemingSlices.ComponentStateFacet.ENABLE
andRadianceThemingSlices.ComponentStateFacet.SELECTION
.
-
-
Method Detail
-
toString
public java.lang.String toString()
- Overrides:
toString
in classjava.lang.Object
-
isFacetActive
public boolean isFacetActive(RadianceThemingSlices.ComponentStateFacet stateFacet)
Returns indication whetherthis
component state is "active" under the specified facet. For example,ROLLOVER_SELECTED
will returntrue
for bothRadianceThemingSlices.ComponentStateFacet.ROLLOVER
andRadianceThemingSlices.ComponentStateFacet.SELECTION
.- Parameters:
stateFacet
- State facet.- Returns:
true
ifthis
component state is "active" under the specified facet (for example,ROLLOVER_SELECTED
will returntrue
for bothRadianceThemingSlices.ComponentStateFacet.ROLLOVER
andRadianceThemingSlices.ComponentStateFacet.SELECTION
),false
otherwise.
-
isDisabled
public boolean isDisabled()
Checks whether this state is disabled. A disabled state hasRadianceThemingSlices.ComponentStateFacet.ENABLE
facet in itsoff
set.- Returns:
true
if this state is disabled,false
otherwise.
-
getActiveStates
public static ComponentState[] getActiveStates()
Returns all active component states. Note that the result will not containENABLED
.- Returns:
- All active component states.
-
getAllStates
public static ComponentState[] getAllStates()
Returns all component states.- Returns:
- All component states
-
isActive
public boolean isActive()
-
getState
public static ComponentState getState(javax.swing.ButtonModel model, javax.swing.JComponent component)
Retrieves component state based on the button model (required parameter) and component itself (optional parameter).- Parameters:
model
- Button model (required).component
- Component (optional).- Returns:
- The matching component state.
-
getState
public static ComponentState getState(javax.swing.AbstractButton button)
Returns the state of the specified button.- Parameters:
button
- Button.- Returns:
- The state of the specified button.
-
getState
public static ComponentState getState(javax.swing.ButtonModel model, javax.swing.JComponent component, boolean toIgnoreSelection)
Retrieves component state based on the button model (required parameter) and button itself (optional parameter).- Parameters:
model
- Button model (required).component
- Component (optional).toIgnoreSelection
- Iftrue
, theButtonModel.isSelected()
will not be checked. This can be used for tracking transitions on menu items that usearmed
state instead, when we don't want to use different rollover themes for selected and unselected checkbox and radio button menu items (to preserve consistent visual appearance of highlights).- Returns:
- The matching component state.
-
getState
public static ComponentState getState(TriStateButtonModel model, boolean toIgnoreSelection)
-
getState
public static ComponentState getState(boolean isEnabled, boolean isRollover, boolean isSelected)
Returns the component state that matches the specified parameters.- Parameters:
isEnabled
- Enabled flag.isRollover
- Rollover flag.isSelected
- Selected flag.- Returns:
- The component state that matches the specified parameters.
-
fitValue
private int fitValue(ComponentState state)
-
bestFit
public ComponentState bestFit(java.util.Collection<ComponentState> states)
-
getHardFallback
public ComponentState getHardFallback()
-
hashCode
public int hashCode()
- Overrides:
hashCode
in classjava.lang.Object
-
equals
public boolean equals(java.lang.Object obj)
- Overrides:
equals
in classjava.lang.Object
-
-