模块 java.desktop
包 java.awt

类 Scrollbar

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

Image shows 3 vertical sliders, side-by-side.

此示例中的每个滚动条都可以使用类似于以下的代码创建：

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

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

Image shows horizontal slider with starting range of 0 and ending range of 300. The slider thumb is labeled 60.

本例中气泡所代表的取值范围为visible amount。本例中的水平滚动条可以使用如下代码创建：

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

请注意，滚动条的实际最大值是 maximum 减去 visible amount 。上例中，因为maximum为300，visible amount为60，所以实际最大值为240。滚动条轨迹的范围为0-300。气泡左侧表示滚动条的值。

通常，用户通过使用鼠标做出手势来改变滚动条的值。例如，用户可以上下拖动滚动条的气泡，或者点击滚动条的单位增量或块增量区域。键盘手势也可以映射到滚动条。按照惯例，向上翻页和向下翻页键相当于点击滚动条的块递增和块递减区域。

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

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

AdjustmentEvent 类定义了五种类型的调整事件，在此处列出：

  • AdjustmentEvent.TRACK 在用户拖动滚动条的气泡时发出。
  • AdjustmentEvent.UNIT_INCREMENT 在用户单击水平滚动条的左箭头或垂直滚动条的顶部箭头或从键盘做出等效手势时发出。
  • AdjustmentEvent.UNIT_DECREMENT 在用户单击水平滚动条的右箭头或垂直滚动条的底部箭头，或从键盘做出等效手势时发出。
  • AdjustmentEvent.BLOCK_INCREMENT 当用户在水平滚动条上的气泡左侧或垂直滚动条上的气泡上方单击轨道时发送。按照惯例，向上翻页key 是等价的，如果用户使用的键盘定义了一个向上翻页钥匙。
  • AdjustmentEvent.BLOCK_DECREMENT 当用户在水平滚动条上的气泡右侧或垂直滚动条上的气泡下方的轨道中单击时发送。按照惯例，向下翻页key 是等价的，如果用户使用的键盘定义了一个向下翻页钥匙。

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
参见：

  • 字段详细信息

    • HORIZONTAL

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

    • VERTICAL

      public static final int VERTICAL
      一个常量，表示垂直滚动条。
      参见：

  • 构造方法详细信息

    • Scrollbar

      public Scrollbar() throws HeadlessException
      构造一个新的垂直滚动条。滚动条的默认属性如下表所示：
      滚动条默认属性
      属性 Description 默认值
      方向 指示滚动条是垂直的还是水平的 Scrollbar.VERTICAL
      value 控制滚动条气泡位置的值 0
      可见量 滚动条范围的可见量，通常由滚动条气泡的大小表示 10
      最低限度 滚动条的最小值 0
      最大限度 滚动条的最大值 100
      单位增量 按下 Line Up 或 Line Down 键或单击滚动条的结束箭头时值更改的量 1
      块增量 按下 Page Up 或 Page Down 键或单击滚动条轨道时值的变化量
      在气泡的两侧      		 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。
      参见：

  • 方法详情

    • 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 提供的值不是合法值
      自从：
      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 - 此滚动条的新最小值
      自从：
      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()
      已弃用。
      从 JDK 1.1 版开始，由 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)
      已弃用。
      从 JDK 1.1 版开始，由 setUnitIncrement(int) 取代。
      设置此滚动条的单位增量。
      参数：
      v - 增量值

    • getUnitIncrement

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

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

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

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

    • getLineIncrement

      @Deprecated public int getLineIncrement()
      已弃用。
      从 JDK 1.1 版开始，由 getUnitIncrement() 取代。
      返回此滚动条的单位增量。
      返回：
      此滚动条的单位增量

    • setBlockIncrement

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

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

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

    • setPageIncrement

      @Deprecated public void setPageIncrement(int v)
      已弃用。
      从 JDK 1.1 版开始，由 setBlockIncrement() 取代。
      设置此滚动条的块增量。
      参数：
      v - 块增量

    • getBlockIncrement

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

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

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

    • getPageIncrement

      @Deprecated public int getPageIncrement()
      已弃用。
      从 JDK 1.1 版开始，由 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 s 或空数组（如果当前未注册任何调整监听器）
      自从：
      1.4
      参见：

    • getListeners

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

      您可以使用类文字指定 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 对象来处理它们。

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

      • AdjustmentListener 对象通过 addAdjustmentListener 注册。
      • 调整事件通过 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 中
      返回：
      一个 AccessibleAWTScrollBar 作为这个 ScrollBar 的 AccessibleContext
      自从：
      1.3