.. wxPython Phoenix documentation

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

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

.. include:: headings.inc



.. _wx.VarScrollHelperBase:

==========================================================================================================================================
|phoenix_title|  **wx.VarScrollHelperBase**
==========================================================================================================================================

This class provides all common base functionality for scroll calculations shared among all variable scrolled window implementations as well as automatic scrollbar functionality, saved scroll positions, controlling target windows to be scrolled, as well as defining all required virtual functions that need to be implemented for any orientation specific work.          

Documentation of this class is provided specifically for referencing use of the functions provided by this class for use with the variable scrolled windows that derive from here. You will likely want to derive your window from one of the already implemented variable scrolled windows rather than from :ref:`wx.VarScrollHelperBase`  directly. 







         



.. seealso:: :ref:`wx.HScrolledWindow`, :ref:`wx.HVScrolledWindow`, :ref:`wx.VScrolledWindow`    







|

|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>VarScrollHelperBase</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.VarScrollHelperBase_inheritance.png" alt="Inheritance diagram of VarScrollHelperBase" usemap="#dummy" class="inheritance"/></center>
   </div>
   <script type="text/javascript">toggleVisibilityOnLoad(document.getElementById('toggleBlock'))</script>
   <map id="dummy" name="dummy"> <area shape="rect" id="node1" href="wx.VarScrollHelperBase.html" title="wx.VarScrollHelperBase" alt="" coords="5,5,176,35"/> </map> 
   </p>

|


|sub_classes| Known Subclasses
==============================

:ref:`wx.VarHScrollHelper`, :ref:`wx.VarVScrollHelper`

|


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

================================================================================ ================================================================================
:meth:`~wx.VarScrollHelperBase.__init__`                                         Constructor taking the target window to be scrolled by this helper class.
:meth:`~wx.VarScrollHelperBase.CalcScrolledPosition`                             Translates the logical coordinate given to the current device coordinate.
:meth:`~wx.VarScrollHelperBase.CalcUnscrolledPosition`                           Translates the device coordinate given to the corresponding logical coordinate.
:meth:`~wx.VarScrollHelperBase.EnablePhysicalScrolling`                          With physical scrolling on (when this is ``True``), the device origin is changed properly when a :ref:`wx.PaintDC`  is prepared, children are actually moved and laid out properly, and the contents of the window (pixels) are actually moved.
:meth:`~wx.VarScrollHelperBase.EstimateTotalSize`                                When the number of scroll units change, we try to estimate the total size of all units when the full window size is needed (i.e.
:meth:`~wx.VarScrollHelperBase.GetNonOrientationTargetSize`                      This function needs to be overridden in the in the derived class to return the window size with respect to the opposing orientation.
:meth:`~wx.VarScrollHelperBase.GetOrientation`                                   This function need to be overridden to return the orientation that this helper is working with, either  ``HORIZONTAL``   or   ``VERTICAL`` .
:meth:`~wx.VarScrollHelperBase.GetOrientationTargetSize`                         This function needs to be overridden in the in the derived class to return the window size with respect to the orientation this helper is working with.
:meth:`~wx.VarScrollHelperBase.GetTargetWindow`                                  This function will return the target window this helper class is currently scrolling.
:meth:`~wx.VarScrollHelperBase.GetVisibleBegin`                                  Returns the index of the first visible unit based on the scroll position.
:meth:`~wx.VarScrollHelperBase.GetVisibleEnd`                                    Returns the index of the last visible unit based on the scroll position.
:meth:`~wx.VarScrollHelperBase.IsVisible`                                        Returns ``True`` if the given scroll unit is currently visible (even if only partially visible) or ``False`` otherwise.
:meth:`~wx.VarScrollHelperBase.OnGetUnitSize`                                    This function must be overridden in the derived class, and should return the size of the given unit in pixels.
:meth:`~wx.VarScrollHelperBase.OnGetUnitsSizeHint`                               This function doesn't have to be overridden but it may be useful to do so if calculating the units' sizes is a relatively expensive operation as it gives your code a chance to calculate several of them at once and cache the result if necessary.
:meth:`~wx.VarScrollHelperBase.RefreshAll`                                       Recalculate all parameters and repaint all units.
:meth:`~wx.VarScrollHelperBase.SetTargetWindow`                                  Normally the window will scroll itself, but in some rare occasions you might want it to scroll (part of) another window (e.g.
:meth:`~wx.VarScrollHelperBase.UpdateScrollbar`                                  Update the thumb size shown by the scrollbar.
:meth:`~wx.VarScrollHelperBase.VirtualHitTest`                                   Returns the virtual scroll unit under the device unit given accounting for scroll position or  ``NOT_FOUND``   if none (i.e.
================================================================================ ================================================================================


|


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

================================================================================ ================================================================================
:attr:`~wx.VarScrollHelperBase.NonOrientationTargetSize`                         See :meth:`~wx.VarScrollHelperBase.GetNonOrientationTargetSize`
:attr:`~wx.VarScrollHelperBase.Orientation`                                      See :meth:`~wx.VarScrollHelperBase.GetOrientation`
:attr:`~wx.VarScrollHelperBase.OrientationTargetSize`                            See :meth:`~wx.VarScrollHelperBase.GetOrientationTargetSize`
:attr:`~wx.VarScrollHelperBase.TargetWindow`                                     See :meth:`~wx.VarScrollHelperBase.GetTargetWindow` and :meth:`~wx.VarScrollHelperBase.SetTargetWindow`
:attr:`~wx.VarScrollHelperBase.VisibleBegin`                                     See :meth:`~wx.VarScrollHelperBase.GetVisibleBegin`
:attr:`~wx.VarScrollHelperBase.VisibleEnd`                                       See :meth:`~wx.VarScrollHelperBase.GetVisibleEnd`
================================================================================ ================================================================================


|


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


.. class:: wx.VarScrollHelperBase(object)

   **Possible constructors**::

       VarScrollHelperBase(winToScroll)
       
   
   This class provides all common base functionality for scroll
   calculations shared among all variable scrolled window implementations
   as well as automatic scrollbar functionality, saved scroll positions,
   controlling target windows to be scrolled, as well as defining all
   required virtual functions that need to be implemented for any
   orientation specific work.



   .. method:: __init__(self, winToScroll)

      Constructor taking the target window to be scrolled by this helper class.                  

      This will attach scroll event handlers to the target window to catch and handle scroll events appropriately.                  


      :param `winToScroll`: 
      :type `winToScroll`: wx.Window







   .. method:: CalcScrolledPosition(self, coord)

      Translates the logical coordinate given to the current device coordinate.                  

      For example, if the window is scrolled 10 units and each scroll unit represents 10 device units (which may not be the case since this class allows for variable scroll unit sizes), a call to this function with a coordinate of 15 will return -85. 

                


      :param `coord`: 
      :type `coord`: int




      :rtype: `int`







      .. seealso:: :meth:`CalcUnscrolledPosition`     








   .. method:: CalcUnscrolledPosition(self, coord)

      Translates the device coordinate given to the corresponding logical coordinate.                  

      For example, if the window is scrolled 10 units and each scroll unit represents 10 device units (which may not be the case since this class allows for variable scroll unit sizes), a call to this function with a coordinate of 15 will return 115. 

                


      :param `coord`: 
      :type `coord`: int




      :rtype: `int`







      .. seealso:: :meth:`CalcScrolledPosition`     








   .. method:: EnablePhysicalScrolling(self, scrolling=True)

      With physical scrolling on (when this is ``True``), the device origin is changed properly when a :ref:`wx.PaintDC`  is prepared, children are actually moved and laid out properly, and the contents of the window (pixels) are actually moved.                  

      When this is ``False``, you are responsible for repainting any invalidated areas of the window yourself to account for the new scroll position.                  


      :param `scrolling`: 
      :type `scrolling`: bool







   .. method:: EstimateTotalSize(self)

      When the number of scroll units change, we try to estimate the total size of all units when the full window size is needed (i.e.                  

      to calculate the scrollbar thumb size). This is a rather expensive operation in terms of unit access, so if the user code may estimate the average size better or faster than we do, it should override this function to implement its own logic. This function should return the best guess for the total virtual window size. 

                

      :rtype: :ref:`wx.Coord`







      .. note:: 

         Although returning a totally wrong value would still work, it risks resulting in very strange scrollbar behaviour so this function should really try to make the best guess possible.   








   .. method:: GetNonOrientationTargetSize(self)

      This function needs to be overridden in the in the derived class to return the window size with respect to the opposing orientation.                  

      If this is a vertical scrolled window, it should return the height. 

                

      :rtype: `int`







      .. seealso:: :meth:`GetOrientationTargetSize`     








   .. method:: GetOrientation(self)

      This function need to be overridden to return the orientation that this helper is working with, either  ``HORIZONTAL``   or   ``VERTICAL`` .                   

      :rtype: :ref:`wx.Orientation`








   .. method:: GetOrientationTargetSize(self)

      This function needs to be overridden in the in the derived class to return the window size with respect to the orientation this helper is working with.                  

      If this is a vertical scrolled window, it should return the width. 

                

      :rtype: `int`







      .. seealso:: :meth:`GetNonOrientationTargetSize`     








   .. method:: GetTargetWindow(self)

      This function will return the target window this helper class is currently scrolling.                  

                

      :rtype: :ref:`wx.Window`







      .. seealso:: :meth:`SetTargetWindow`     








   .. method:: GetVisibleBegin(self)

      Returns the index of the first visible unit based on the scroll position.                  

      :rtype: `int`








   .. method:: GetVisibleEnd(self)

      Returns the index of the last visible unit based on the scroll position.                  

      This includes the last unit even if it is only partially visible.                  

      :rtype: `int`








   .. method:: IsVisible(self, unit)

      Returns ``True`` if the given scroll unit is currently visible (even if only partially visible) or ``False`` otherwise.                  


      :param `unit`: 
      :type `unit`: int




      :rtype: `bool`








   .. method:: OnGetUnitSize(self, unit)

      This function must be overridden in the derived class, and should return the size of the given unit in pixels.                  


      :param `unit`: 
      :type `unit`: int




      :rtype: :ref:`wx.Coord`








   .. method:: OnGetUnitsSizeHint(self, unitMin, unitMax)

      This function doesn't have to be overridden but it may be useful to do so if calculating the units' sizes is a relatively expensive operation as it gives your code a chance to calculate several of them at once and cache the result if necessary.                  

      :meth:`OnGetUnitsSizeHint`   is normally called just before :meth:`OnGetUnitSize`   but you shouldn't rely on the latter being called for all units in the interval specified here. It is also possible that :meth:`OnGetUnitSize`   will be called for units outside of this interval, so this is really just a hint, not a promise. 

      Finally, note that `unitMin`  is inclusive, while `unitMax`  is exclusive.                  


      :param `unitMin`: 
      :type `unitMin`: int
      :param `unitMax`: 
      :type `unitMax`: int







   .. method:: RefreshAll(self)

      Recalculate all parameters and repaint all units.                   





   .. method:: SetTargetWindow(self, target)

      Normally the window will scroll itself, but in some rare occasions you might want it to scroll (part of) another window (e.g.                  

      a child of it in order to scroll only a portion the area between the scrollbars like a spreadsheet where only the cell area will move). 

                


      :param `target`: 
      :type `target`: wx.Window






      .. seealso:: :meth:`GetTargetWindow`     








   .. method:: UpdateScrollbar(self)

      Update the thumb size shown by the scrollbar.                   





   .. method:: VirtualHitTest(self, coord)

      Returns the virtual scroll unit under the device unit given accounting for scroll position or  ``NOT_FOUND``   if none (i.e.                   

      if it is below the last item).                  


      :param `coord`: 
      :type `coord`: int




      :rtype: `int`








   .. attribute:: NonOrientationTargetSize

      See :meth:`~wx.VarScrollHelperBase.GetNonOrientationTargetSize`


   .. attribute:: Orientation

      See :meth:`~wx.VarScrollHelperBase.GetOrientation`


   .. attribute:: OrientationTargetSize

      See :meth:`~wx.VarScrollHelperBase.GetOrientationTargetSize`


   .. attribute:: TargetWindow

      See :meth:`~wx.VarScrollHelperBase.GetTargetWindow` and :meth:`~wx.VarScrollHelperBase.SetTargetWindow`


   .. attribute:: VisibleBegin

      See :meth:`~wx.VarScrollHelperBase.GetVisibleBegin`


   .. attribute:: VisibleEnd

      See :meth:`~wx.VarScrollHelperBase.GetVisibleEnd`