.. wxPython Phoenix documentation

   This file was generated by Phoenix's sphinx generator and associated
   tools, do not edit by hand.

   Copyright: (c) 2011-2020 by Total Control Software
   License:   wxWindows License

.. include:: headings.inc



.. _wx.ScrollBar:

==========================================================================================================================================
|phoenix_title|  **wx.ScrollBar**
==========================================================================================================================================

A :ref:`wx.ScrollBar`  is a control that represents a horizontal or vertical scrollbar.          

It is distinct from the two scrollbars that some windows provide automatically, but the two types of scrollbar share the way events are received. 


^^  



.. _ScrollBar-styles:

|styles| Window Styles
================================

This class supports the following styles: 

  

- ``wx.SB_HORIZONTAL``: Specifies a horizontal scrollbar.  
- ``wx.SB_VERTICAL``: Specifies a vertical scrollbar. ^^ 

^^






.. _ScrollBar-events:

|events| Events Emitted by this Class
=====================================

Handlers bound for the following event types will receive a :ref:`wx.ScrollEvent` parameter.


- EVT_SCROLL: Process all scroll events.  
- EVT_SCROLL_TOP: Process  ``wxEVT_SCROLL_TOP``   scroll to top or leftmost (minimum) position events.   
- EVT_SCROLL_BOTTOM: Process  ``wxEVT_SCROLL_BOTTOM``   scroll to bottom or rightmost (maximum) position events.   
- EVT_SCROLL_LINEUP: Process  ``wxEVT_SCROLL_LINEUP``   line up or left events.   
- EVT_SCROLL_LINEDOWN: Process  ``wxEVT_SCROLL_LINEDOWN``   line down or right events.   
- EVT_SCROLL_PAGEUP: Process  ``wxEVT_SCROLL_PAGEUP``   page up or left events.   
- EVT_SCROLL_PAGEDOWN: Process  ``wxEVT_SCROLL_PAGEDOWN``   page down or right events.   
- EVT_SCROLL_THUMBTRACK: Process  ``wxEVT_SCROLL_THUMBTRACK``   thumbtrack events (frequent events sent as the user drags the thumbtrack).   
- EVT_SCROLL_THUMBRELEASE: Process  ``wxEVT_SCROLL_THUMBRELEASE``   thumb release events.   
- EVT_SCROLL_CHANGED: Process  ``wxEVT_SCROLL_CHANGED``   end of scrolling events (MSW only).   
- EVT_COMMAND_SCROLL: Process all scroll events.  
- EVT_COMMAND_SCROLL_TOP: Process  ``wxEVT_SCROLL_TOP``   scroll to top or leftmost (minimum) position events.   
- EVT_COMMAND_SCROLL_BOTTOM: Process  ``wxEVT_SCROLL_BOTTOM``   scroll to bottom or rightmost (maximum) position events.   
- EVT_COMMAND_SCROLL_LINEUP: Process  ``wxEVT_SCROLL_LINEUP``   line up or left events.   
- EVT_COMMAND_SCROLL_LINEDOWN: Process  ``wxEVT_SCROLL_LINEDOWN``   line down or right events.   
- EVT_COMMAND_SCROLL_PAGEUP: Process  ``wxEVT_SCROLL_PAGEUP``   page up or left events.   
- EVT_COMMAND_SCROLL_PAGEDOWN: Process  ``wxEVT_SCROLL_PAGEDOWN``   page down or right events.   
- EVT_COMMAND_SCROLL_THUMBTRACK: Process  ``wxEVT_SCROLL_THUMBTRACK``   thumbtrack events (frequent events sent as the user drags the thumbtrack).   
- EVT_COMMAND_SCROLL_THUMBRELEASE: Process  ``wxEVT_SCROLL_THUMBRELEASE``   thumb release events.   
- EVT_COMMAND_SCROLL_CHANGED: Process  ``wxEVT_SCROLL_CHANGED``   end of scrolling events (MSW only). ^^ 






|phoenix_title| The difference between ``EVT_SCROLL_THUMBRELEASE`` and ``EVT_SCROLL_CHANGED``
=============================================================================================

The ``EVT_SCROLL_THUMBRELEASE`` event is only emitted when actually dragging the thumb using the mouse and releasing it (This ``EVT_SCROLL_THUMBRELEASE`` event is also followed by an ``EVT_SCROLL_CHANGED`` event). The ``EVT_SCROLL_CHANGED`` event also occurs when using the keyboard to change the thumb position, and when clicking next to the thumb (In all these cases the ``EVT_SCROLL_THUMBRELEASE`` event does not happen). In short, the ``EVT_SCROLL_CHANGED`` event is triggered when scrolling/moving has finished independently of the way it had started. Please see the :ref:`Widgets Sample <widgets sample>`  ("Slider" page) to see the difference between ``EVT_SCROLL_THUMBRELEASE`` and ``EVT_SCROLL_CHANGED`` in action.   



.. note:: 

   A scrollbar has the following main attributes: range, thumb size, page size, and position. The range is the total number of units associated with the view represented by the scrollbar. For a table with 15 columns, the range would be 15. The thumb size is the number of units that are currently visible. For the table example, the window might be sized so that only 5 columns are currently visible, in which case the application would set the thumb size to 5. When the thumb size becomes the same as or greater than the range, the scrollbar will be automatically hidden on most platforms. The page size is the number of units that the scrollbar should scroll by, when 'paging' through the data. This value is normally the same as the thumb size length, because it is natural to assume that the visible window size defines a page. The scrollbar position is the current thumb position. Most applications will find it convenient to provide a function called AdjustScrollbars() which can be called initially, from an OnSize event handler, and whenever the application data changes in size. It will adjust the view, object and page size according to the size of the window and the size of the data.  







.. seealso:: :ref:`Scrolled Windows <scrolled windows>`, :ref:`Events and Event Handling <events and event handling>`, :ref:`wx.Scrolled`    







|

|class_hierarchy| Class Hierarchy
=================================

.. raw:: html

   <div id="toggleBlock" onclick="return toggleVisibility(this)" class="closed" style="cursor:pointer;">
   <img id="toggleBlock-trigger" src="_static/images/closed.png"/>
   Inheritance diagram for class <strong>ScrollBar</strong>:
   </div>
   <div id="toggleBlock-summary" style="display:block;"></div>
   <div id="toggleBlock-content" style="display:none;">
   <p class="graphviz">
   <center><img src="_static/images/inheritance/wx.ScrollBar_inheritance.png" alt="Inheritance diagram of ScrollBar" usemap="#dummy" class="inheritance"/></center>
   <script type="text/javascript">toggleVisibilityOnLoad(document.getElementById('toggleBlock'))</script>
   <map id="dummy" name="dummy"> <area shape="rect" id="node1" href="wx.ScrollBar.html" title="wx.ScrollBar" alt="" coords="57,315,160,344"/> <area shape="rect" id="node2" href="wx.Control.html" title="wx.Control" alt="" coords="63,237,155,267"/> <area shape="rect" id="node3" href="wx.Window.html" title="wx.Window" alt="" coords="60,160,157,189"/> <area shape="rect" id="node4" href="wx.EvtHandler.html" title="wx.EvtHandler" alt="" coords="50,83,167,112"/> <area shape="rect" id="node5" href="wx.Object.html" title="wx.Object" alt="" coords="5,5,92,35"/> <area shape="rect" id="node6" href="wx.Trackable.html" title="wx.Trackable" alt="" coords="117,5,223,35"/> </map> 
   </p>
   </div>

|


|appearance| Control Appearance
===============================

|

.. figure:: _static/images/widgets/fullsize/wxmsw/wx.scrollbar.png
   :alt: wxMSW
   :figclass: floatleft

   **wxMSW**


.. figure:: _static/images/widgets/fullsize/wxmac/wx.scrollbar.png
   :alt: wxMAC
   :figclass: floatright

   **wxMAC**


.. figure:: _static/images/widgets/fullsize/wxgtk/wx.scrollbar.png
   :alt: wxGTK
   :figclass: floatcenter

   **wxGTK**


|


|method_summary| Methods Summary
================================

================================================================================ ================================================================================
:meth:`~wx.ScrollBar.__init__`                                                   Default constructor.
:meth:`~wx.ScrollBar.Create`                                                     Scrollbar creation function called by the scrollbar constructor.
:meth:`~wx.ScrollBar.GetClassDefaultAttributes`                                  
:meth:`~wx.ScrollBar.GetPageSize`                                                Returns the page size of the scrollbar.
:meth:`~wx.ScrollBar.GetRange`                                                   Returns the length of the scrollbar.
:meth:`~wx.ScrollBar.GetThumbPosition`                                           Returns the current position of the scrollbar thumb.
:meth:`~wx.ScrollBar.GetThumbSize`                                               Returns the thumb or 'view' size.
:meth:`~wx.ScrollBar.IsVertical`                                                 Returns ``True`` for scrollbars that have the vertical style set.
:meth:`~wx.ScrollBar.SetScrollbar`                                               Sets the scrollbar properties.
:meth:`~wx.ScrollBar.SetThumbPosition`                                           Sets the position of the scrollbar.
================================================================================ ================================================================================


|


|property_summary| Properties Summary
=====================================

================================================================================ ================================================================================
:attr:`~wx.ScrollBar.PageSize`                                                   See :meth:`~wx.ScrollBar.GetPageSize`
:attr:`~wx.ScrollBar.Range`                                                      See :meth:`~wx.ScrollBar.GetRange`
:attr:`~wx.ScrollBar.ThumbPosition`                                              See :meth:`~wx.ScrollBar.GetThumbPosition` and :meth:`~wx.ScrollBar.SetThumbPosition`
:attr:`~wx.ScrollBar.ThumbSize`                                                  See :meth:`~wx.ScrollBar.GetThumbSize`
================================================================================ ================================================================================


|


|api| Class API
===============


.. class:: wx.ScrollBar(Control)

   **Possible constructors**::

       ScrollBar()
       
       ScrollBar(parent, id=ID_ANY, pos=DefaultPosition, size=DefaultSize,
                 style=SB_HORIZONTAL, validator=DefaultValidator, name=ScrollBarNameStr)
       
   
   A ScrollBar is a control that represents a horizontal or vertical
   scrollbar.



   .. method:: __init__(self, *args, **kw)



      |overload| Overloaded Implementations:

      :html:`<hr class="overloadsep" /><br />`

      
      **__init__** `(self)`
      
      Default constructor.                   
      
      
      
      
      :html:`<hr class="overloadsep" /><br />`

      
      **__init__** `(self, parent, id=ID_ANY, pos=DefaultPosition, size=DefaultSize, style=SB_HORIZONTAL, validator=DefaultValidator, name=ScrollBarNameStr)`
      
      Constructor, creating and showing a scrollbar.                  
      
      
      
      
      :param `parent`: Parent window. Must be non-NULL.   
      :type `parent`: wx.Window
      :param `id`: Window identifier. The value ``wx.ID_ANY`` indicates a default value.   
      :type `id`: wx.WindowID
      :param `pos`: Window position. If :ref:`wx.DefaultPosition`  is specified then a default position is chosen.   
      :type `pos`: wx.Point
      :param `size`: Window size. If :ref:`wx.DefaultSize`  is specified then a default size is chosen.   
      :type `size`: wx.Size
      :param `style`: Window style. See :ref:`wx.ScrollBar`.   
      :type `style`: long
      :param `validator`: Window validator.   
      :type `validator`: wx.Validator
      :param `name`: Window name.  
      :type `name`: string
      
      
      
      
      
      
      
      
      
      
      
      
      
      
      
      
                        
      
      
      
      .. seealso:: :meth:`Create` , :ref:`wx.Validator`    
      
      
      
      
      
      
      
      :html:`<hr class="overloadsep" /><br />`






   .. method:: Create(self, parent, id=ID_ANY, pos=DefaultPosition, size=DefaultSize, style=SB_HORIZONTAL, validator=DefaultValidator, name=ScrollBarNameStr)

      Scrollbar creation function called by the scrollbar constructor.                  

      See :ref:`wx.ScrollBar`  for details.                  


      :param `parent`: 
      :type `parent`: wx.Window
      :param `id`: 
      :type `id`: wx.WindowID
      :param `pos`: 
      :type `pos`: wx.Point
      :param `size`: 
      :type `size`: wx.Size
      :param `style`: 
      :type `style`: long
      :param `validator`: 
      :type `validator`: wx.Validator
      :param `name`: 
      :type `name`: string




      :rtype: `bool`








   .. staticmethod:: GetClassDefaultAttributes(variant=WINDOW_VARIANT_NORMAL)




      :param `variant`: 
      :type `variant`: wx.WindowVariant




      :rtype: :ref:`wx.VisualAttributes`








   .. method:: GetPageSize(self)

      Returns the page size of the scrollbar.                  

      This is the number of scroll units that will be scrolled when the user pages up or down. Often it is the same as the thumb size. 

                

      :rtype: `int`







      .. seealso:: :meth:`SetScrollbar`     








   .. method:: GetRange(self)

      Returns the length of the scrollbar.                  

                

      :rtype: `int`







      .. seealso:: :meth:`SetScrollbar`     








   .. method:: GetThumbPosition(self)

      Returns the current position of the scrollbar thumb.                  

                

      :rtype: `int`







      .. seealso:: :meth:`SetThumbPosition`     








   .. method:: GetThumbSize(self)

      Returns the thumb or 'view' size.                  

                

      :rtype: `int`







      .. seealso:: :meth:`SetScrollbar`     








   .. method:: IsVertical(self)

      Returns ``True`` for scrollbars that have the vertical style set.                  

      :rtype: `bool`








   .. method:: SetScrollbar(self, position, thumbSize, range, pageSize, refresh=True)

      Sets the scrollbar properties.                  




      :param `position`: The position of the scrollbar in scroll units.   
      :type `position`: int
      :param `thumbSize`: The size of the thumb, or visible portion of the scrollbar, in scroll units.   
      :type `thumbSize`: int
      :param `range`: The maximum position of the scrollbar.   
      :type `range`: int
      :param `pageSize`: The size of the page size in scroll units. This is the number of units the scrollbar will scroll when it is paged up or down. Often it is the same as the thumb size.   
      :type `pageSize`: int
      :param `refresh`: ``True`` to redraw the scrollbar, ``False`` otherwise.  
      :type `refresh`: bool












                  



      .. note:: 

         Let's say you wish to display 50 lines of text, using the same font. The window is sized so that you can only see 16 lines at a time. You would use: ::

                      scrollbar.SetScrollbar(0, 16, 50, 15)

         The page size is 1 less than the thumb size so that the last line of the previous page will be visible on the next page, to help orient the user. Note that with the window at this size, the thumb position can never go above 50 minus 16, or 34. You can determine how many lines are currently visible by dividing the current view size by the character height in pixels. When defining your own scrollbar behaviour, you will always need to recalculate the scrollbar settings when the window size changes. You could therefore put your scrollbar calculations and :meth:`SetScrollbar`   call into a function named AdjustScrollbars, which can be called initially and also from a :ref:`wx.SizeEvent`  event handler function.   








   .. method:: SetThumbPosition(self, viewStart)

      Sets the position of the scrollbar.                  




      :param `viewStart`: The position of the scrollbar thumb.  
      :type `viewStart`: int




                  



      .. seealso:: :meth:`GetThumbPosition`     








   .. attribute:: PageSize

      See :meth:`~wx.ScrollBar.GetPageSize`


   .. attribute:: Range

      See :meth:`~wx.ScrollBar.GetRange`


   .. attribute:: ThumbPosition

      See :meth:`~wx.ScrollBar.GetThumbPosition` and :meth:`~wx.ScrollBar.SetThumbPosition`


   .. attribute:: ThumbSize

      See :meth:`~wx.ScrollBar.GetThumbSize`