.. 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

.. currentmodule:: wx.lib.agw.rulerctrl

.. highlight:: python



.. _wx.lib.agw.rulerctrl.RulerCtrl:

==========================================================================================================================================
|phoenix_title|  **wx.lib.agw.rulerctrl.RulerCtrl**
==========================================================================================================================================

:class:`RulerCtrl` implements a ruler window that can be placed on top, bottom, left or right
to any wxPython widget. It is somewhat similar to the rulers you can find in text
editors software, though not so powerful.



|

|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>RulerCtrl</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.lib.agw.rulerctrl.RulerCtrl_inheritance.png" alt="Inheritance diagram of RulerCtrl" 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.lib.agw.rulerctrl.RulerCtrl.html" title="wx.lib.agw.rulerctrl.RulerCtrl" alt="" coords="5,392,212,421"/> <area shape="rect" id="node2" href="wx.Panel.html" title="wx.Panel" alt="" coords="69,315,149,344"/> <area shape="rect" id="node3" href="wx.Window.html" title="wx.Window" alt="" coords="60,237,157,267"/> <area shape="rect" id="node4" href="wx.WindowBase.html" title="wx.WindowBase" alt="" coords="44,160,173,189"/> <area shape="rect" id="node5" href="wx.EvtHandler.html" title="wx.EvtHandler" alt="" coords="50,83,167,112"/> <area shape="rect" id="node6" href="wx.Object.html" title="wx.Object" alt="" coords="5,5,92,35"/> <area shape="rect" id="node7" 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.lib.agw.rulerctrl.rulerctrl.png
   :alt: wxMSW
   :figclass: floatleft

   **wxMSW**


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

   **wxMAC**


.. figure:: _static/images/widgets/fullsize/wxgtk/wx.lib.agw.rulerctrl.rulerctrl.png
   :alt: wxGTK
   :figclass: floatcenter

   **wxGTK**


|




|super_classes| Known Superclasses
==================================

:class:`wx.Panel`

|


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

================================================================================ ================================================================================
:meth:`~wx.lib.agw.rulerctrl.RulerCtrl.__init__`                                 Default class constructor.
:meth:`~wx.lib.agw.rulerctrl.RulerCtrl.AddIndicator`                             Adds an indicator to :class:`RulerCtrl`. You should pass a unique `id` and a starting
:meth:`~wx.lib.agw.rulerctrl.RulerCtrl.CheckStyle`                               Adjust the :class:`RulerCtrl` style accordingly to borders, units, etc...
:meth:`~wx.lib.agw.rulerctrl.RulerCtrl.Draw`                                     Actually draws the whole :class:`RulerCtrl`.
:meth:`~wx.lib.agw.rulerctrl.RulerCtrl.DrawOnParent`                             Actually draws the thin line over the drawing parent window.
:meth:`~wx.lib.agw.rulerctrl.RulerCtrl.FindLinearTickSizes`                      Used internally.
:meth:`~wx.lib.agw.rulerctrl.RulerCtrl.GetBounds`                                Returns the :class:`RulerCtrl` bounds (its client rectangle).
:meth:`~wx.lib.agw.rulerctrl.RulerCtrl.GetDrawingParent`                         Returns the window to which :class:`RulerCtrl` draws a thin line over.
:meth:`~wx.lib.agw.rulerctrl.RulerCtrl.GetFormat`                                Returns the format used to display values in :class:`RulerCtrl`.
:meth:`~wx.lib.agw.rulerctrl.RulerCtrl.GetIndicator`                             Returns the indicator located at the mouse position `mousePos` (if any).
:meth:`~wx.lib.agw.rulerctrl.RulerCtrl.GetTimeFormat`                            Returns the time format.
:meth:`~wx.lib.agw.rulerctrl.RulerCtrl.Invalidate`                               Invalidates the ticks calculations.
:meth:`~wx.lib.agw.rulerctrl.RulerCtrl.LabelMajor`                               Sets whether the major ticks should be labeled or not.
:meth:`~wx.lib.agw.rulerctrl.RulerCtrl.LabelMinor`                               Sets whether the minor ticks should be labeled or not.
:meth:`~wx.lib.agw.rulerctrl.RulerCtrl.LabelString`                              Used internally.
:meth:`~wx.lib.agw.rulerctrl.RulerCtrl.OfflimitsPixels`                          Used internally.
:meth:`~wx.lib.agw.rulerctrl.RulerCtrl.OnEraseBackground`                        Handles the ``wx.EVT_ERASE_BACKGROUND`` event for :class:`RulerCtrl`.
:meth:`~wx.lib.agw.rulerctrl.RulerCtrl.OnMouseEvents`                            Handles the ``wx.EVT_MOUSE_EVENTS`` event for :class:`RulerCtrl`.
:meth:`~wx.lib.agw.rulerctrl.RulerCtrl.OnPaint`                                  Handles the ``wx.EVT_PAINT`` event for :class:`RulerCtrl`.
:meth:`~wx.lib.agw.rulerctrl.RulerCtrl.OnSize`                                   Handles the ``wx.EVT_SIZE`` event for :class:`RulerCtrl`.
:meth:`~wx.lib.agw.rulerctrl.RulerCtrl.SetBackgroundColour`                      Sets the :class:`RulerCtrl` background colour.
:meth:`~wx.lib.agw.rulerctrl.RulerCtrl.SetBounds`                                Sets the bounds for :class:`RulerCtrl` (its client rectangle).
:meth:`~wx.lib.agw.rulerctrl.RulerCtrl.SetDrawingParent`                         Sets the window to which :class:`RulerCtrl` draws a thin line over.
:meth:`~wx.lib.agw.rulerctrl.RulerCtrl.SetFlip`                                  Sets whether the orientation of the tick marks should be reversed.
:meth:`~wx.lib.agw.rulerctrl.RulerCtrl.SetFonts`                                 Sets the fonts for minor and major tick labels.
:meth:`~wx.lib.agw.rulerctrl.RulerCtrl.SetFormat`                                Sets the format for :class:`RulerCtrl`.
:meth:`~wx.lib.agw.rulerctrl.RulerCtrl.SetIndicatorColour`                       Sets the indicator colour.
:meth:`~wx.lib.agw.rulerctrl.RulerCtrl.SetIndicatorValue`                        Sets the indicator value.
:meth:`~wx.lib.agw.rulerctrl.RulerCtrl.SetLabelColour`                           Sets the labels colour.
:meth:`~wx.lib.agw.rulerctrl.RulerCtrl.SetLabelEdges`                            Sets whether the edge values should always be displayed or not.
:meth:`~wx.lib.agw.rulerctrl.RulerCtrl.SetLog`                                   Sets whether :class:`RulerCtrl` should have a logarithmic scale or not.
:meth:`~wx.lib.agw.rulerctrl.RulerCtrl.SetOrientation`                           Sets the :class:`RulerCtrl` orientation.
:meth:`~wx.lib.agw.rulerctrl.RulerCtrl.SetRange`                                 Sets the :class:`RulerCtrl` range.
:meth:`~wx.lib.agw.rulerctrl.RulerCtrl.SetSpacing`                               Sets the :class:`RulerCtrl` spacing between labels.
:meth:`~wx.lib.agw.rulerctrl.RulerCtrl.SetTickPenColour`                         Sets the pen colour to draw the ticks.
:meth:`~wx.lib.agw.rulerctrl.RulerCtrl.SetTimeFormat`                            Sets the time format.
:meth:`~wx.lib.agw.rulerctrl.RulerCtrl.SetUnits`                                 Sets the units that should be displayed beside the labels.
:meth:`~wx.lib.agw.rulerctrl.RulerCtrl.Tick`                                     Ticks a particular position.
:meth:`~wx.lib.agw.rulerctrl.RulerCtrl.TickMajor`                                Sets whether the major ticks should be ticked or not.
:meth:`~wx.lib.agw.rulerctrl.RulerCtrl.TickMinor`                                Sets whether the minor ticks should be ticked or not.
:meth:`~wx.lib.agw.rulerctrl.RulerCtrl.Update`                                   Updates all the ticks calculations.
================================================================================ ================================================================================


|


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


.. class:: RulerCtrl(wx.Panel)

   :class:`RulerCtrl` implements a ruler window that can be placed on top, bottom, left or right
   to any wxPython widget. It is somewhat similar to the rulers you can find in text
   editors software, though not so powerful.

   .. method:: __init__(self, parent, id=-1, pos=wx.DefaultPosition, size=wx.DefaultSize, style=wx.STATIC_BORDER, orient=wx.HORIZONTAL)

      Default class constructor.
      
      :param `parent`: parent window. Must not be ``None``;
      :param `id`: window identifier. A value of -1 indicates a default value;
      :param `pos`: the control position. A value of (-1, -1) indicates a default position,
       chosen by either the windowing system or wxPython, depending on platform;
      :param `size`: the control size. A value of (-1, -1) indicates a default size,
       chosen by either the windowing system or wxPython, depending on platform;
      :param `style`: the window style;
      :param `orient`: sets the orientation of the :class:`RulerCtrl`, and can be either
       ``wx.HORIZONTAL`` of ``wx.VERTICAL``.


   .. method:: AddIndicator(self, id, value)

      Adds an indicator to :class:`RulerCtrl`. You should pass a unique `id` and a starting
      `value` for the indicator.
      
      :param `id`: the indicator identifier;
      :param `value`: the indicator initial value.


   .. method:: CheckStyle(self)

      Adjust the :class:`RulerCtrl` style accordingly to borders, units, etc...


   .. method:: Draw(self, dc)

      Actually draws the whole :class:`RulerCtrl`.
      
      :param `dc`: an instance of :class:`wx.DC`.


   .. method:: DrawOnParent(self, indicator)

      Actually draws the thin line over the drawing parent window.
      
      :param `indicator`: the current indicator, an instance of :class:`Indicator`.
      
      :note: This method is currently not available on wxMac as it uses :class:`ScreenDC`.


   .. method:: FindLinearTickSizes(self, UPP)

      Used internally. 


   .. method:: GetBounds(self)

      Returns the :class:`RulerCtrl` bounds (its client rectangle). 


   .. method:: GetDrawingParent(self)

      Returns the window to which :class:`RulerCtrl` draws a thin line over. 


   .. method:: GetFormat(self)

      Returns the format used to display values in :class:`RulerCtrl`.
      
      :see: :meth:`RulerCtrl.SetFormat` for a list of possible formats.


   .. method:: GetIndicator(self, mousePos)

      Returns the indicator located at the mouse position `mousePos` (if any).
      
      :param `mousePos`: the mouse position, an instance of :class:`wx.Point`.


   .. method:: GetTimeFormat(self)

      Returns the time format. 


   .. method:: Invalidate(self)

      Invalidates the ticks calculations. 


   .. method:: LabelMajor(self, label=True)

      Sets whether the major ticks should be labeled or not.
      
      :param `label`: ``True`` to label major ticks, ``False`` otherwise.


   .. method:: LabelMinor(self, label=True)

      Sets whether the minor ticks should be labeled or not.
      
      :param `label`: ``True`` to label minor ticks, ``False`` otherwise.


   .. method:: LabelString(self, d, major=None)

      Used internally. 


   .. method:: OfflimitsPixels(self, start, end)

      Used internally. 


   .. method:: OnEraseBackground(self, event)

      Handles the ``wx.EVT_ERASE_BACKGROUND`` event for :class:`RulerCtrl`.
      
      :param `event`: a :class:`EraseEvent` event to be processed.
      
      :note: This method is intentionally empty to reduce flicker.


   .. method:: OnMouseEvents(self, event)

      Handles the ``wx.EVT_MOUSE_EVENTS`` event for :class:`RulerCtrl`.
      
      :param `event`: a :class:`MouseEvent` event to be processed.


   .. method:: OnPaint(self, event)

      Handles the ``wx.EVT_PAINT`` event for :class:`RulerCtrl`.
      
      :param `event`: a :class:`PaintEvent` event to be processed.


   .. method:: OnSize(self, event)

      Handles the ``wx.EVT_SIZE`` event for :class:`RulerCtrl`.
      
      :param `event`: a :class:`wx.SizeEvent` event to be processed.


   .. method:: SetBackgroundColour(self, colour)

      Sets the :class:`RulerCtrl` background colour.
      
      :param `colour`: an instance of :class:`wx.Colour`.
      
      :note: Overridden from :class:`Panel`.


   .. method:: SetBounds(self, left, top, right, bottom)

      Sets the bounds for :class:`RulerCtrl` (its client rectangle).
      
      :param `left`: the left corner of the client rectangle;
      :param `top`: the top corner of the client rectangle;
      :param `right`: the right corner of the client rectangle;
      :param `bottom`: the bottom corner of the client rectangle.


   .. method:: SetDrawingParent(self, dparent)

      Sets the window to which :class:`RulerCtrl` draws a thin line over.
      
      :param `dparent`: an instance of :class:`wx.Window`, representing the window to
       which :class:`RulerCtrl` draws a thin line over.


   .. method:: SetFlip(self, flip=True)

      Sets whether the orientation of the tick marks should be reversed.
      
      :param `flip`: ``True`` to reverse the orientation of the tick marks, ``False``
       otherwise.


   .. method:: SetFonts(self, minorFont, majorFont)

      Sets the fonts for minor and major tick labels.
      
      :param `minorFont`: the font used to draw minor ticks, a valid :class:`wx.Font` object;
      :param `majorFont`: the font used to draw major ticks, a valid :class:`wx.Font` object.


   .. method:: SetFormat(self, format)

      Sets the format for :class:`RulerCtrl`.
      
      :param `format`: the format used to display values in :class:`RulerCtrl`. This can be
       one of the following bits:
      
       ====================== ======= ==============================
       Format                  Value  Description
       ====================== ======= ==============================
       ``IntFormat``                1 Integer format
       ``RealFormat``               2 Real format
       ``TimeFormat``               3 Time format
       ``LinearDBFormat``           4 Linear DB format
       ``HHMMSS_Format``            5 HHMMSS format
       ====================== ======= ==============================
       


   .. method:: SetIndicatorColour(self, id, colour=None)

      Sets the indicator colour.
      
      :param `id`: the indicator identifier;
      :param `colour`: a valid :class:`wx.Colour` object.
      
      :note: This method requires PIL to change the image palette.


   .. method:: SetIndicatorValue(self, sendEvent=True)

      Sets the indicator value.
      
      :param `sendEvent`: ``True`` to send a :class:`RulerCtrlEvent`, ``False`` otherwise.


   .. method:: SetLabelColour(self, colour=wx.BLACK)

      Sets the labels colour.
      
      :param `colour`: a valid :class:`wx.Colour` object.


   .. method:: SetLabelEdges(self, labelEdges=True)

      Sets whether the edge values should always be displayed or not.
      
      :param `labelEdges`: ``True`` to always display edge labels, ``False`` otherwise/


   .. method:: SetLog(self, log=True)

      Sets whether :class:`RulerCtrl` should have a logarithmic scale or not.
      
      :param `log`: ``True`` to use a logarithmic scale, ``False`` to use a
       linear one.


   .. method:: SetOrientation(self, orient=None)

      Sets the :class:`RulerCtrl` orientation.
      
      :param `orient`: can be ``wx.HORIZONTAL`` or ``wx.VERTICAL``.


   .. method:: SetRange(self, minVal, maxVal)

      Sets the :class:`RulerCtrl` range.
      
      :param `minVal`: the minimum value of :class:`RulerCtrl`;
      :param `maxVal`: the maximum value of :class:`RulerCtrl`.


   .. method:: SetSpacing(self, spacing)

      Sets the :class:`RulerCtrl` spacing between labels.
      
      :param `spacing`: the spacing between labels, in pixels.


   .. method:: SetTickPenColour(self, colour=wx.BLACK)

      Sets the pen colour to draw the ticks.
      
      :param `colour`: a valid :class:`wx.Colour` object.


   .. method:: SetTimeFormat(self, format=TimeFormat)

      Sets the time format.
      
      :param `format`: the format used to display time values.


   .. method:: SetUnits(self, units)

      Sets the units that should be displayed beside the labels.
      
      :param `units`: the units that should be displayed beside the labels.


   .. method:: Tick(self, dc, pos, d, major)

      Ticks a particular position.
      
      :param `dc`: an instance of :class:`wx.DC`;
      :param `pos`: the label position;
      :param `d`: the current label value;
      :param `major`: ``True`` if it is a major ticks, ``False`` if it is a minor one.


   .. method:: TickMajor(self, tick=True)

      Sets whether the major ticks should be ticked or not.
      
      :param `tick`: ``True`` to show major ticks, ``False`` otherwise.


   .. method:: TickMinor(self, tick=True)

      Sets whether the minor ticks should be ticked or not.
      
      :param `tick`: ``True`` to show minor ticks, ``False`` otherwise.


   .. method:: Update(self, dc)

      Updates all the ticks calculations.
      
      :param `dc`: an instance of :class:`wx.DC`.


