Module java.desktop
Package java.awt

Class Scrollbar

java.lang.Object
java.awt.Component
java.awt.Scrollbar
所有已实现的接口:
Adjustable, ImageObserver, MenuContainer, Serializable, Accessible
public class Scrollbar extends Component implements Adjustable, Accessible
Scrollbar类体现了滚动条，这是一个熟悉的用户界面对象。滚动条提供了一个方便的方式，让用户从一系列值中进行选择。以下三个垂直滚动条可以用作滑块控件，用于选择颜色的红色、绿色和蓝色分量：

图像显示3个垂直滑块，依次排列。

在这个示例中，每个滚动条可以通过类似以下代码创建：

 redSlider=new Scrollbar(Scrollbar.VERTICAL, 0, 1, 0, 255);
 add(redSlider);

另外，滚动条也可以表示一系列值。例如，如果滚动条用于滚动文本，"气泡"（也称为"拇指"或"滚动框"）的宽度可以表示可见文本的数量。以下是表示范围的滚动条示例：

图像显示具有起始范围0和结束范围300的水平滑块。滑块标记为60。

在这个示例中，气泡表示的值范围是可见数量。这个示例中的水平滚动条可以通过以下代码创建：

 ranger = new Scrollbar(Scrollbar.HORIZONTAL, 0, 60, 0, 300);
 add(ranger);

请注意，滚动条的实际最大值是maximum减去visible amount。在前面的示例中，因为maximum是300，visible amount是60，实际最大值是240。滚动条轨道的范围是0 - 300。气泡的左侧指示滚动条的值。

通常，用户通过鼠标手势来更改滚动条的值。例如，用户可以拖动滚动条的气泡上下，或者单击滚动条的单位增量或块增量区域。键盘手势也可以映射到滚动条上。按照惯例，Page Up和Page Down键等效于单击滚动条的块增量和块减量区域。

当用户更改滚动条的值时，滚动条会接收一个AdjustmentEvent实例。滚动条处理此事件，并将其传递给任何已注册的侦听器。

任何希望被通知滚动条值更改的对象应该实现AdjustmentListener，这是在包java.awt.event中定义的一个接口。侦听器可以通过调用方法addAdjustmentListener和removeAdjustmentListener来动态添加和移除。

AdjustmentEvent类定义了五种调整事件类型，列在这里：

  • AdjustmentEvent.TRACK 当用户拖动滚动条的气泡时发送。
  • AdjustmentEvent.UNIT_INCREMENT 当用户单击水平滚动条的左箭头或垂直滚动条的顶部箭头，或者从键盘进行等效手势时发送。
  • AdjustmentEvent.UNIT_DECREMENT 当用户单击水平滚动条的右箭头或垂直滚动条的底部箭头，或者从键盘进行等效手势时发送。
  • AdjustmentEvent.BLOCK_INCREMENT 当用户单击轨道，位于水平滚动条气泡左侧或垂直滚动条气泡上方时发送。按照惯例，如果用户使用定义了Page Up键的键盘，则等效。
  • AdjustmentEvent.BLOCK_DECREMENT 当用户单击轨道，位于水平滚动条气泡右侧或垂直滚动条气泡下方时发送。按照惯例，如果用户使用定义了Page Down键的键盘，则等效。

JDK 1.0事件系统支持向后兼容，但不建议在较新版本的平台上使用。JDK 1.1引入的五种调整事件类型对应于以前平台版本中与滚动条相关的五种事件类型。以下列表给出了调整事件类型及其替换的JDK 1.0事件类型。

  • AdjustmentEvent.TRACK 替换了Event.SCROLL_ABSOLUTE
  • AdjustmentEvent.UNIT_INCREMENT 替换了Event.SCROLL_LINE_UP
  • AdjustmentEvent.UNIT_DECREMENT 替换了Event.SCROLL_LINE_DOWN
  • AdjustmentEvent.BLOCK_INCREMENT 替换了Event.SCROLL_PAGE_UP
  • AdjustmentEvent.BLOCK_DECREMENT 替换了Event.SCROLL_PAGE_DOWN

注意：我们建议仅将Scrollbar用于值选择。如果要在容器内实现可滚动组件，建议使用ScrollPane。如果您将Scrollbar用于此目的，可能会遇到绘制、键盘处理、大小和定位等问题。

自版本:
1.0
参见:

  • Field Details

    • HORIZONTAL

      public static final int HORIZONTAL
      表示水平滚动条的常量。
      参见:

    • VERTICAL

      public static final int VERTICAL
      表示垂直滚动条的常量。
      参见:

  • Constructor Details

    • Scrollbar

      public Scrollbar() throws HeadlessException
      构造一个新的垂直滚动条。滚动条的默认属性列在以下表中：
      滚动条默认属性
      属性 描述 默认值
      orientation 指示滚动条是垂直的还是水平的 Scrollbar.VERTICAL
      value 控制滚动条气泡位置的值 0
      visible amount 滚动条范围的可见量，通常由滚动条气泡的大小表示 10
      minimum 滚动条的最小值 0
      maximum 滚动条的最大值 100
      unit increment 当按下向上或向下键或单击滚动条的结束箭头时值改变的量 1
      block increment 当按下向上或向下键或单击滚动条轨道两侧时值改变的量 10
      抛出:
      HeadlessException - 如果 GraphicsEnvironment.isHeadless() 返回 true。
      参见:

    • Scrollbar

      public Scrollbar(int orientation) throws HeadlessException
      用指定的方向构造一个新的滚动条。

      orientation 参数必须取两个值之一：Scrollbar.HORIZONTAL 或 Scrollbar.VERTICAL，分别表示水平或垂直滚动条。

      参数:
      orientation - 指示滚动条的方向
      抛出:
      IllegalArgumentException - 当提供给 orientation 参数的值非法时
      HeadlessException - 如果 GraphicsEnvironment.isHeadless() 返回 true。
      参见:

    • Scrollbar

      public Scrollbar(int orientation, int value, int visible, int minimum, int maximum) throws HeadlessException
      用指定的方向、初始值、可见量和最小和最大值构造一个新的滚动条。

      orientation 参数必须取两个值之一：Scrollbar.HORIZONTAL 或 Scrollbar.VERTICAL，分别表示水平或垂直滚动条。

      提供给此构造函数的参数受到 setValues(int, int, int, int) 中描述的约束。

      参数:
      orientation - 指示滚动条的方向。
      value - 滚动条的初始值
      visible - 滚动条的可见量，通常由气泡的大小表示
      minimum - 滚动条的最小值
      maximum - 滚动条的最大值
      抛出:
      IllegalArgumentException - 当提供给 orientation 参数的值非法时
      HeadlessException - 如果 GraphicsEnvironment.isHeadless() 返回 true。
      参见:

  • Method Details

    • addNotify

      public void addNotify()
      创建 Scrollbar 的对等体。对等体允许您修改 Scrollbar 的外观，而不更改任何功能。
      覆盖:
      addNotify 在类 Component
      参见:

    • getOrientation

      public int getOrientation()
      返回此滚动条的方向。
      指定者:
      getOrientation 在接口 Adjustable
      返回:
      此滚动条的方向，可以是 Scrollbar.HORIZONTAL 或 Scrollbar.VERTICAL
      参见:

    • setOrientation

      public void setOrientation(int orientation)
      设置此滚动条的方向。
      参数:
      orientation - 此滚动条的方向，可以是 Scrollbar.HORIZONTAL 或 Scrollbar.VERTICAL
      抛出:
      IllegalArgumentException - 如果提供给 orientation 的值不是合法值
      自 JDK 版本:
      1.1
      参见:

    • getValue

      public int getValue()
      获取此滚动条的当前值。
      指定者:
      getValue 在接口 Adjustable
      返回:
      此滚动条的当前值
      参见:

    • setValue

      public void setValue(int newValue)
      将此滚动条的值设置为指定值。

      如果提供的值小于当前的 minimum 或大于当前的 maximum - visibleAmount，则会相应地替换为 minimum 或 maximum - visibleAmount。

      通常，程序应该仅通过调用 setValues 来更改滚动条的值。 setValues 方法同时且同步地设置滚动条的最小值、最大值、可见量和值属性，使它们相互一致。

      调用此方法不会触发 AdjustmentEvent。

      指定者:
      setValue 在接口 Adjustable
      参数:
      newValue - 滚动条的新值
      参见:

    • getMinimum

      public int getMinimum()
      获取此滚动条的最小值。
      指定者:
      getMinimum 在接口 Adjustable
      返回:
      此滚动条的最小值
      参见:

    • setMinimum

      public void setMinimum(int newMinimum)
      设置此滚动条的最小值。

      调用 setMinimum 时，最小值会更改，并且其他值（包括最大值、可见量和当前滚动条值）会更改为与新最小值一致。

      通常，程序应该仅通过调用 setValues 来更改滚动条的最小值。 setValues 方法同时且同步地设置滚动条的最小值、最大值、可见量和值属性，使它们相互一致。

      请注意，将最小值设置为 Integer.MAX_VALUE 将导致新的最小值设置为 Integer.MAX_VALUE - 1。

      指定者:
      setMinimum 在接口 Adjustable
      参数:
      newMinimum - 此滚动条的新最小值
      自 JDK 版本:
      1.1
      参见:

    • getMaximum

      public int getMaximum()
      获取此滚动条的最大值。
      指定者:
      getMaximum 在接口 Adjustable
      返回:
      此滚动条的最大值
      参见:

    • setMaximum

      public void setMaximum(int newMaximum)
      设置此滚动条的最大值。

      调用setMaximum时，最大值会更改，并且其他值（包括最小值、可见量和当前滚动条值）会更改为与新最大值一致。

      通常，程序应仅通过调用setValues来更改滚动条的最大值。 setValues方法同时且同步设置滚动条的最小值、最大值、可见量和值属性，以使它们相互一致。

      请注意，将最大值设置为Integer.MIN_VALUE将导致新的最大值设置为Integer.MIN_VALUE + 1。

      指定者：
      setMaximum 在接口 Adjustable
      参数：
      newMaximum - 此滚动条的新最大值
      自：
      1.1
      参见：

    • getVisibleAmount

      public int getVisibleAmount()
      获取此滚动条的可见量。

      当滚动条用于选择一系列值时，可见量用于表示当前可见的值范围。滚动条的气泡（也称为拇指或滚动框）的大小通常提供了可见量与滚动条范围之间关系的视觉表示。请注意，根据平台的不同，可见量属性的值可能不会通过气泡的大小在视觉上表示出来。

      当气泡不可移动时（例如，当它占据整个滚动条轨道的长度，或者当滚动条被禁用时），滚动条的气泡可能不会显示。气泡是否显示不会影响getVisibleAmount返回的值。

      指定者：
      getVisibleAmount 在接口 Adjustable
      返回：
      此滚动条的可见量
      自：
      1.1
      参见：

    • getVisible

      @Deprecated public int getVisible()
      Deprecated.
      As of JDK version 1.1, replaced by getVisibleAmount().
      返回此滚动条的可见量。
      返回：
      此滚动条的可见量

    • setVisibleAmount

      public void setVisibleAmount(int newAmount)
      设置此滚动条的可见量。

      当滚动条用于选择一系列值时，可见量用于表示当前可见的值范围。滚动条的气泡（也称为拇指或滚动框）的大小通常提供了可见量与滚动条范围之间关系的视觉表示。请注意，根据平台的不同，可见量属性的值可能不会通过气泡的大小在视觉上表示出来。

      当气泡不可移动时（例如，当它占据整个滚动条轨道的长度，或者当滚动条被禁用时），滚动条的气泡可能不会显示。气泡是否显示不会影响getVisibleAmount返回的值。

      如果提供的可见量小于one或大于当前maximum - minimum，则会相应地替换为one或maximum - minimum。

      通常，程序应仅通过调用setValues来更改滚动条的值。 setValues方法同时且同步设置滚动条的最小值、最大值、可见量和值属性，以使它们相互一致。

      指定者：
      setVisibleAmount 在接口 Adjustable
      参数：
      newAmount - 新的可见量
      自：
      1.1
      参见：

    • setUnitIncrement

      public void setUnitIncrement(int v)
      设置此滚动条的单位增量。

      单位增量是用户激活滚动条的单位增量区域时添加或减去的值，通常通过滚动条接收为调整事件的鼠标或键盘手势。单位增量必须大于零。尝试将单位增量设置为小于1的值将导致设置为1。

      在某些操作系统中，此属性可能会被底层控件忽略。

      指定者：
      setUnitIncrement 在接口 Adjustable
      参数：
      v - 要增加或减少滚动条值的量
      自：
      1.1
      参见：

    • setLineIncrement

      @Deprecated public void setLineIncrement(int v)
      Deprecated.
      As of JDK version 1.1, replaced by setUnitIncrement(int).
      设置此滚动条的单位增量。
      参数：
      v - 增量值

    • getUnitIncrement

      public int getUnitIncrement()
      获取此滚动条的单位增量。

      单位增量是用户激活滚动条的单位增量区域时添加或减去的值，通常通过滚动条接收为调整事件的鼠标或键盘手势。单位增量必须大于零。

      在某些操作系统中，此属性可能会被底层控件忽略。

      指定者：
      getUnitIncrement 在接口 Adjustable
      返回：
      此滚动条的单位增量
      自：
      1.1
      参见：

    • getLineIncrement

      @Deprecated public int getLineIncrement()
      Deprecated.
      As of JDK version 1.1, replaced by getUnitIncrement().
      返回此滚动条的单位增量。
      返回：
      此滚动条的单位增量

    • setBlockIncrement

      public void setBlockIncrement(int v)
      设置此滚动条的块增量。

      块增量是用户激活滚动条的块增量区域时添加或减去的值，通常通过滚动条接收为调整事件的鼠标或键盘手势。块增量必须大于零。尝试将块增量设置为小于1的值将导致设置为1。

      指定者：
      setBlockIncrement 在接口 Adjustable
      参数：
      v - 要增加或减少滚动条值的量
      自：
      1.1
      参见：

    • setPageIncrement

      @Deprecated public void setPageIncrement(int v)
      Deprecated.
      As of JDK version 1.1, replaced by setBlockIncrement().
      设置此滚动条的块增量。
      参数：
      v - 块增量

    • getBlockIncrement

      public int getBlockIncrement()
      获取此滚动条的块增量。

      块增量是用户激活滚动条的块增量区域时添加或减去的值，通常通过滚动条接收为调整事件的鼠标或键盘手势。块增量必须大于零。

      指定者：
      getBlockIncrement 在接口 Adjustable
      返回：
      此滚动条的块增量
      自：
      1.1
      参见：

    • getPageIncrement

      @Deprecated public int getPageIncrement()
      Deprecated.
      As of JDK version 1.1, replaced by getBlockIncrement().
      返回此滚动条的块增量。
      返回：
      此滚动条的块增量

    • setValues

      public void setValues(int value, int visible, int minimum, int maximum)
      设置此滚动条的四个属性值：value、visibleAmount、minimum和maximum。如果为这些属性提供的值不一致或不正确，则会更改以确保一致性。

      此方法同时且同步设置四个滚动条属性的值，确保这些属性的值相互一致。它强制执行以下约束： maximum必须大于minimum，maximum - minimum不能大于Integer.MAX_VALUE，visibleAmount必须大于零。 visibleAmount不能大于maximum - minimum，value不能小于minimum，value不能大于maximum - visibleAmount

      调用此方法不会触发AdjustmentEvent。

      参数：
      value - 当前窗口中的位置
      visible - 滚动条的可见量
      minimum - 滚动条的最小值
      maximum - 滚动条的最大值
      参见：

    • getValueIsAdjusting

      public boolean getValueIsAdjusting()
      如果值正在更改以响应用户采取的操作，则返回true。
      返回：
      valueIsAdjusting属性的值
      自：
      1.4
      参见：

    • setValueIsAdjusting

      public void setValueIsAdjusting(boolean b)
      设置valueIsAdjusting属性。
      参数:
      b - 新的正在进行调整的状态
      自从:
      1.4
      参见:

    • addAdjustmentListener

      public void addAdjustmentListener(AdjustmentListener l)
      向此滚动条添加指定的调整监听器以接收AdjustmentEvent的实例。如果l为null，则不会抛出异常，也不会执行任何操作。

      有关AWT线程模型的详细信息，请参阅AWT线程问题。

      指定者:
      addAdjustmentListener 在接口 Adjustable
      参数:
      l - 调整监听器
      自从:
      1.1
      参见:

    • removeAdjustmentListener

      public void removeAdjustmentListener(AdjustmentListener l)
      从此滚动条中删除指定的调整监听器，使其不再接收AdjustmentEvent的实例。如果l为null，则不会抛出异常，也不会执行任何操作。

      有关AWT线程模型的详细信息，请参阅AWT线程问题。

      指定者:
      removeAdjustmentListener 在接口 Adjustable
      参数:
      l - 调整监听器
      自从:
      1.1
      参见:

    • getAdjustmentListeners

      public AdjustmentListener[] getAdjustmentListeners()
      返回在此滚动条上注册的所有调整监听器的数组。
      返回:
      所有此滚动条的AdjustmentListener或如果当前没有注册调整监听器，则返回一个空数组
      自从:
      1.4
      参见:

    • getListeners

      public <T extends EventListener> T[] getListeners(Class<T> listenerType)
      返回当前在此Scrollbar上注册为FooListener的所有对象的数组。使用addFooListener方法注册FooListener。

      您可以使用类字面量指定listenerType参数，例如FooListener.class。例如，您可以使用以下代码查询Scrollbar c的鼠标监听器：

      MouseListener[] mls = (MouseListener[])(c.getListeners(MouseListener.class));
      如果不存在这样的监听器，则此方法返回一个空数组。
      覆盖:
      getListeners 在类 Component
      类型参数:
      T - 监听器的类型
      参数:
      listenerType - 请求的监听器类型；此参数应指定从java.util.EventListener继承的接口
      返回:
      在此组件上注册为FooListener的所有对象的数组，如果没有添加此类监听器，则返回一个空数组
      抛出:
      ClassCastException - 如果listenerType未指定实现java.util.EventListener的类或接口
      自从:
      1.3
      参见:

    • processEvent

      protected void processEvent(AWTEvent e)
      处理此滚动条上的事件。如果事件是AdjustmentEvent的实例，则调用processAdjustmentEvent方法。否则，调用其超类的processEvent方法。

      请注意，如果事件参数为null，则行为是未指定的，可能会导致异常。

      覆盖:
      processEvent 在类 Component
      参数:
      e - 事件
      自从:
      1.1
      参见:

    • processAdjustmentEvent

      protected void processAdjustmentEvent(AdjustmentEvent e)
      通过将调整事件分派给任何注册的AdjustmentListener对象来处理此滚动条上发生的调整事件。

      除非为此组件启用了调整事件，否则不会调用此方法。当发生以下情况之一时，将启用调整事件：

      • 通过addAdjustmentListener注册了一个AdjustmentListener对象。
      • 通过enableEvents启用了调整事件。

      请注意，如果事件参数为null，则行为是未指定的，可能会导致异常。

      参数:
      e - 调整事件
      自从:
      1.1
      参见:

    • paramString

      protected String paramString()
      返回表示此Scrollbar状态的字符串。此方法仅用于调试目的，返回的字符串的内容和格式可能因实现而异。返回的字符串可能为空，但不能为null。
      覆盖:
      paramString 在类 Component
      返回:
      此滚动条的参数字符串

    • getAccessibleContext

      public AccessibleContext getAccessibleContext()
      获取与此Scrollbar关联的AccessibleContext。对于滚动条，AccessibleContext采用AccessibleAWTScrollBar的形式。如果需要，将创建一个新的AccessibleAWTScrollBar实例。
      指定者:
      getAccessibleContext 在接口 Accessible
      覆盖:
      getAccessibleContext 在类 Component
      返回:
      作为此ScrollBar的AccessibleContext的AccessibleAWTScrollBar
      自从:
      1.3