Package swingtree

Class ScrollableComponentDelegate

java.lang.Object
swingtree.ScrollableComponentDelegate
public final class ScrollableComponentDelegate extends Object
This class is an immutable builder which defines the Scrollable behavior of a component within a JScrollPane. So it is in essence a config object that provides information to a scrolling container like JScrollPane.

Instances of this class are exposed to the Configurator lambda of the UIFactoryMethods.scrollPane(Configurator) factory method, where you can configure the scrollable behavior according to your needs.
This includes setting the preferred size, unit increment, block increment, and whether the component should fit the width or height of the viewport.
Here an example demonstrating how the API of this class is typically used: 


 UI.panel()
 .withBorderTitled("Scrollable Panel")
 .add(
     UI.scrollPane(conf -> conf
         .prefSize(400, 300)
         .unitIncrement(20)
         .blockIncrement(50)
         .fitWidth(true)
         .fitHeight(false)
     )
 )

Note that the provided Configurator will be called for every call to a method of the underlying Scrollable component implementation, so the settings you provide can also change dynamically based on the context captured by the lambda.

Also note that this configuration object also exposes some context information you may find useful when defining its properties like fitWidth(boolean), fitHeight(boolean), unitIncrement(int), and so on...
Like for example the current view(), which implements the Scrollable and wraps your content() component. You can also access the viewport() as well as the overarching scrollPane() overall!
Again, the configurator you pass to UIFactoryMethods.scrollPane(Configurator) will be called eagerly, so everything you define in there will be completely dynamic, which means your scroll behaviour can dynamically react to the involved components.

  • Method Details

    • prefSize

      public ScrollableComponentDelegate prefSize(int width, int height)
      Creates an updated scrollable config with the preferred size of the viewport for a view component. For example, the preferred size of a JList component is the size required to accommodate all the cells in its list. However, the value of preferredScrollableViewportSize is the size required for JList.getVisibleRowCount rows. A component without any properties that would affect the viewport size should just return getPreferredSize here.
      Parameters:
      width - The preferred width of a JViewport whose view a Scrollable configured by this config object.
      height - The preferred height of a JViewport whose view a Scrollable configured by this config object.
      Returns:
      A new instance of ScrollableComponentDelegate with the updated preferred size.
      See Also:

    • prefSize

      public ScrollableComponentDelegate prefSize(Size preferredSize)
      Creates an updated scrollable config with the preferred size of the viewport for a view component. For example, the preferred size of a JList component is the size required to accommodate all the cells in its list. However, the value of preferredScrollableViewportSize is the size required for JList.getVisibleRowCount rows. A component without any properties that would affect the viewport size should just return getPreferredSize here.
      Parameters:
      preferredSize - The preferred size of the component.
      Returns:
      A new instance of ScrollableComponentDelegate with the updated preferred size.
      Throws:
      NullPointerException - If the preferred size is null, use Size.unknown() to indicate that the preferred size is unknown.
      See Also:

    • unitIncrement

      public ScrollableComponentDelegate unitIncrement(int unitIncrement)
      Creates an updated scrollable config with the specified unit increment. The unit increment is the amount to scroll when the user requests a unit scroll. For example, this could be the amount to scroll when the user presses the arrow keys. Components that display logical rows or columns should compute the scroll increment that will completely expose one new row or column, depending on the value of orientation. Ideally, components should handle a partially exposed row or column by returning the distance required to completely expose the item.

      Scrolling containers, like JScrollPane, will use this increment value each time the user requests a unit scroll.

      Parameters:
      unitIncrement - The unit increment value.
      Returns:
      A new instance of ScrollableComponentDelegate with the updated unit increment.
      See Also:

    • unitIncrement

      public ScrollableComponentDelegate unitIncrement(ScrollIncrementSupplier unitIncrement)
      Creates an updated scrollable config with the specified unit increment supplier, (see ScrollIncrementSupplier) which takes the visible rectangle, orientation and direction as arguments and returns the unit increment for the given context.
      The unit increment is the amount to scroll when the user requests a unit scroll. For example, this could be the amount to scroll when the user presses the arrow keys. Components that display logical rows or columns should compute the scroll increment that will completely expose one new row or column, depending on the value of orientation. Ideally, components should handle a partially exposed row or column by returning the distance required to completely expose the item.

      Scrolling containers, like JScrollPane, will use this increment value each time the user requests a unit scroll.

      Parameters:
      unitIncrement - A ScrollIncrementSupplier that returns the unit increment for the given context.
      Returns:
      A new instance of ScrollableComponentDelegate with the updated unit increment supplier.
      See Also:

    • blockIncrement

      public ScrollableComponentDelegate blockIncrement(int blockIncrement)
      Creates an updated scrollable config with the specified block increment. The block increment is the amount to scroll when the user requests a block scroll. For example, this could be the amount to scroll when the user presses the page up or page down keys. Components that display logical rows or columns should compute the scroll increment that will completely expose one block of rows or columns, depending on the value of orientation.

      Scrolling containers, like JScrollPane, will use this increment value each time the user requests a block scroll.

      Parameters:
      blockIncrement - The block increment value.
      Returns:
      A new instance of ScrollableComponentDelegate with the updated block increment.
      See Also:

    • blockIncrement

      public ScrollableComponentDelegate blockIncrement(ScrollIncrementSupplier blockIncrement)
      Creates an updated scrollable config with the specified block increment supplier, (see ScrollIncrementSupplier) which takes the visible rectangle, orientation and direction as arguments and returns the block increment for the given context.
      The block increment is the amount to scroll when the user requests a block scroll. For example, this could be the amount to scroll when the user presses the page up or page down keys. Components that display logical rows or columns should compute the scroll increment that will completely expose one block of rows or columns, depending on the value of orientation.

      Scrolling containers, like JScrollPane, will use this increment value each time the user requests a block scroll.

      Parameters:
      blockIncrement - A ScrollIncrementSupplier that returns the block increment for the given context.
      Returns:
      A new instance of ScrollableComponentDelegate with the updated block increment supplier.
      See Also:

    • fitWidth

      public ScrollableComponentDelegate fitWidth(boolean fitWidth)
      Set this to true if a viewport should always force the width of this Scrollable to match the width of the viewport. For example a normal text view that supported line wrapping would return true here, since it would be undesirable for wrapped lines to disappear beyond the right edge of the viewport. Note that returning true for a Scrollable whose ancestor is a JScrollPane effectively disables horizontal scrolling.

      Scrolling containers, like JViewport, will use this method each time they are validated.

      Returns:
      A new scroll config with the desired width fitting mode, which, if true, makes the viewport force the Scrollables width to match its own.

    • fitHeight

      public ScrollableComponentDelegate fitHeight(boolean fitHeight)
      Set this to true if a viewport should always force the height of this Scrollable to match the height of the viewport. For example a columnar text view that flowed text in left to right columns could effectively disable vertical scrolling by returning true here.

      Scrolling containers, like JViewport, will use this method each time they are validated.

      Returns:
      A new scroll config with the desired width fitting mode, which, if true, makes a viewport force the Scrollables height to match its own.

    • scrollPane

      public JScrollPane scrollPane()
      Returns the scroll pane that contains the scrollable component this configuration is for.
      Returns:
      The scroll pane that contains the scrollable component.

    • viewport

      public JViewport viewport()
      Returns the viewport of the scroll pane that contains the Scrollable component this configuration is for.
      Returns:
      The viewport of the scroll pane that contains the scrollable component.

    • content

      public JComponent content()
      Returns the user provided content component that is contained in the scroll pane and which is wrapped by a view component implementing the Scrollable interface configured by this ScrollableComponentDelegate. The content component is effectively the component supplied to the UIForAnything.add(Component[]) method. (Please note that a scroll pane can only ever hold a single content component)
      Returns:
      The content component that is contained within the scroll pane and wrapped by the view() component.

    • view

      public Component view()
      Returns the view component implementing the Scrollable interface and which is placed directly in the scroll panes viewport() through JViewport.setView(Component).
      This is the main UI component that is configured by this ScrollableComponentDelegate.
      Returns:
      The view component that is contained within the scroll pane.

    • toString

      public String toString()
      Overrides:
      toString in class Object

    • equals

      public boolean equals(Object obj)
      Overrides:
      equals in class Object

    • hashCode

      public int hashCode()
      Overrides:
      hashCode in class Object