Package swingtree.style

Class ComponentExtension<C extends JComponent>

java.lang.Object
swingtree.style.ComponentExtension<C>
public final class ComponentExtension<C extends JComponent> extends Object
Is attached to UI components in the form of a client property. It exists to give Swing-Tree components some custom style and animation capabilities.

  • Method Details

    • from

      public static <C extends JComponent> ComponentExtension<C> from(C comp)
      Returns the ComponentExtension associated with the given component. If the component does not have an extension, a new one is created and associated with the component.
      Type Parameters:
      C - The type of the component.
      Parameters:
      comp - The component for which to get the extension.
      Returns:
      The extension associated with the component.

    • initializeFor

      public static void initializeFor(JComponent comp)
      Initializes the given component with a new ComponentExtension. This method is called by a SwingTree builder node when it receives and builds a new component. The former extension of the component is replaced by a new one.
      Parameters:
      comp - The component to initialize.

    • addDragAwayConf

      public void addDragAwayConf(Function<Position,DragAwayComponentConf<C>> supplier)

    • getDragAwayConf

      public Optional<DragAwayComponentConf<C>> getDragAwayConf(Position mousePosition)
      If it exists, this method invokes the user internal configurator function previously set by the addDragAwayConf(Function) method and returns an optional of the resulting DragAwayComponentConf object, which holds the configuration for starting a drag away operation using the AWT native DragSource.
      Parameters:
      mousePosition - The current mouse position.
      Returns:
      An optional of the resulting DragAwayComponentConf object.

    • getOrSet

      public <P> P getOrSet(Class<P> type, Supplier<P> fetcher)
      Allows for extra state to be attached to the component extension. (Conceptually similar to how Swing components can have client properties.)
      If the component already has an object of the given type attached, that object is returned. Otherwise, the given fetcher is used to create a new object of the given type, which is then attached to the component and returned.
      Type Parameters:
      P - The type of the extra state.
      Parameters:
      type - The type of the extra state to attach.
      fetcher - A supplier which is used to create a new object of the given type.
      Returns:
      The extra state object of the given type which is attached to the component.

    • setStyleGroups

      public void setStyleGroups(String... groupTags)
      This method is used by UIForAnySwing.group(String...) to attach so called group tags to a component.
      They are used by the SwingTree style engine to apply styles with the same tags, which is conceptually similar to CSS classes.
      It is advised to use the setStyleGroups(Enum[]) method instead of this method, as the usage of enums for modelling group tags offers much better compile time type safety!
      Parameters:
      groupTags - An array of group tags.

    • setStyleGroups

      @SafeVarargs public final <E extends Enum<E>> void setStyleGroups(E... groupTags)
      This method is used by UIForAnySwing.group(String...) to attach so called group tags to a component.
      They are used by the SwingTree style engine to apply styles with the same tags, which is conceptually similar to CSS classes.
      It is advised to use this method over the setStyleGroups(String[]) method, as the usage of enums for modelling group tags offers much better compile time type safety!
      Type Parameters:
      E - The type of the enum.
      Parameters:
      groupTags - An array of group tags.

    • setId

      public final void setId(String id)
      Sets the id of the component. The id is used by the SwingTree style engine to apply styles to components with the same id, which is conceptually similar to CSS ids.
      The preferred way to set the id is by using an enum to avoid typos and to get better compile time type safety.
      Parameters:
      id - The id to set.

    • setId

      public final <E extends Enum<E>> void setId(E id)
      Sets the id of the component based on an enum. The id is used by the SwingTree style engine to apply styles to components with the same id, which is conceptually similar to CSS ids.
      This is the preferred way to set the id, as it offers better compile time type safety. Also check out the UIForAnySwing.id(Enum) to set the id as part of a UI declaration.
      Type Parameters:
      E - The type of the enum.
      Parameters:
      id - The id to set.

    • hasId

      public final boolean hasId(String id)
      Checks if the component has the given id.
      Parameters:
      id - The id to check.
      Returns:
      true if the component has the given id.

    • hasId

      public final boolean hasId(Enum<?> id)
      Checks if the component has the given id.
      Parameters:
      id - The id to check.
      Returns:
      true if the component has the given id.

    • getStyleGroups

      public List<String> getStyleGroups()
      A component can have multiple group tags, which are used by the SwingTree style engine to apply styles with the same tags, which is conceptually similar to CSS classes. This method returns the group tags associated with the component.
      Returns:
      The group tags associated with the component in the form of an unmodifiable list of Strings.

    • belongsToGroup

      public boolean belongsToGroup(String group)
      A style group is a tag which is used by the SwingTree style engine to apply styles to things with the same tags making it conceptually similar to CSS classes. This method lets you check if the component belongs to a given String based group.
      Parameters:
      group - The group to check.
      Returns:
      true if the component belongs to the given group.

    • belongsToGroup

      public boolean belongsToGroup(Enum<?> group)
      A style group is a tag which is used by the SwingTree style engine to apply styles to things with the same tags making it conceptually similar to CSS classes. This method lets you check if the component belongs to a given enum based group.
      Parameters:
      group - The group to check.
      Returns:
      true if the component belongs to the given group.

    • getStyle

      public StyleConf getStyle()
      Exposes the current StyleConf configuration of the component, which holds all the SwingTree style information needed to render the component.
      Returns:
      The current StyleConf configuration of the component which is calculated based on the Styler lambdas associated with the component.

    • getComponentArea

      public Optional<Shape> getComponentArea(UI.ComponentArea area)
      Allows for the retrieval of a specific Shape which represents a specific area of the component identified by the given UI.ComponentArea. The following areas are available:
      • UI.ComponentArea.ALL - The entire component, which is the union of all other clip areas (INTERIOR + EXTERIOR + BORDER + CONTENT).
      • UI.ComponentArea.INTERIOR - The inner component area, which is defined as ALL - EXTERIOR - BORDER.
      • UI.ComponentArea.EXTERIOR - The outer component area, which can be expressed as ALL - INTERIOR - BORDER, or ALL - CONTENT.
      • UI.ComponentArea.BORDER - The border of the component, which is the area between the inner and outer component area and which can be expressed as ALL - INTERIOR - EXTERIOR.
      • UI.ComponentArea.BODY - The body of the component is the inner component area including the border area. It can be expressed as ALL - EXTERIOR, or INTERIOR + BORDER.
      Parameters:
      area - The area of the component to retrieve.
      Returns:
      An optional Shape which represents the given area of the component or an empty optional. If the area is not available, then this means that the style of the component did not lead to the calculation of the given area. This may happen for the EXTERIOR in case of there being no margin or corner radius, and the BORDER in case of there being no border width.

    • clearAnimations

      public void clearAnimations()
      Removes all animations from the component. This includes both Painter based animations as well as Styler based animations.

    • addAnimatedPainter

      public void addAnimatedPainter(AnimationStatus status, UI.Layer layer, UI.ComponentArea clipArea, Painter painter)
      Use this to add a Painter based animation to the component.
      Parameters:
      status - The AnimationStatus which defines when the animation is active.
      layer - The UI.Layer which defines the layer on which the animation is rendered.
      clipArea - The UI.ComponentArea which defines the area of the component which is animated.
      painter - The Painter which defines how the animation is rendered.

    • addAnimatedStyler

      public void addAnimatedStyler(AnimationStatus state, Styler<C> styler)
      Use this to add a Styler based animation to the component.
      Parameters:
      state - The AnimationStatus which defines when the animation is active.
      styler - The Styler which defines how the style of the component is changed during the animation.

    • installCustomUIIfPossible

      public void installCustomUIIfPossible()
      SwingTree overrides the default Swing look and feel to enable custom styling and animation capabilities. This method is used to install the custom look and feel for the component, if possible.

    • addStyler

      public void addStyler(Styler<C> styler)
      Adds a Styler to the component. The styler will be used to calculate the style of the component.
      Parameters:
      styler - The styler to add.

    • gatherStyle

      public StyleConf gatherStyle()
      Calculates a new StyleConf object based on the Styler lambdas associated with the component...
      Returns:
      A new immutable StyleConf configuration.

    • gatherApplyAndInstallStyle

      public void gatherApplyAndInstallStyle(boolean force)
      Calculates a new StyleConf object based on the Styler lambdas associated with the component and then applies it to the component after which a new StyleEngine is installed for the component. If the calculated style is the same as the current style, nothing happens except in case the force parameter is set to true.
      Parameters:
      force - If set to true, the style will be applied even if it is the same as the current style.

    • applyAndInstallStyle

      public void applyAndInstallStyle(StyleConf styleConf, boolean force)
      Applies the given StyleConf to the component after which a new StyleEngine is installed for the component. If the given style is the same as the current style, nothing happens except in case the force parameter is set to true.
      Parameters:
      styleConf - The style to apply.
      force - If set to true, the style will be applied even if it is the same as the current style.

    • viewStateHashCode

      public int viewStateHashCode()
      This method tries to hash everything relevant in the visual appearance of the component and it subcomponents into a single integer value. It is based on the current SwingTree style information as well as more general component information like the current value of a slider, text of a text component, etc.

      You may use this for rough cache invalidation purposes. So when you want to render the component into a BufferedImage and then only rerender it if the state hash changes, you can use this method.

      But keep in mind however, it cannot capture look and feel related changes which are not controlled by SwingTree.
      So this hash code is not a perfect solution, but it can be useful in some cases. Like visualizing a drag and drop of a component...

      Returns:
      The current state hash of the component and all of it subcomponents, which includes SwingTree style information, as well as component specific information.