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

.. module:: wx.lib.agw.speedmeter

.. currentmodule:: wx.lib.agw.speedmeter

.. highlight:: python



.. _wx.lib.agw.speedmeter:

==========================================================================================================================================
|phoenix_title|  **wx.lib.agw.speedmeter**
==========================================================================================================================================

:class:`~wx.lib.agw.speedmeter.SpeedMeter` tries to reproduce the behavior of some car controls (but not only),
by creating an "angular" control (actually, circular).


Description
===========

:class:`SpeedMeter` tries to reproduce the behavior of some car controls (but not only),
by creating an "angular" control (actually, circular). I remember to have seen
it somewhere, and i decided to implement it in wxPython.

:class:`SpeedMeter` starts its construction from an empty bitmap, and it uses some
functions of the :class:`wx.DC` class to create the rounded effects. everything is
processed in the `Draw()` method of :class:`SpeedMeter` class.

This implementation allows you to use either directly the :class:`PaintDC`, or the
better (for me) double buffered style with :class:`BufferedPaintDC`. the double
buffered implementation has been adapted from the wxPython wiki example:

http://wiki.wxpython.org/index.cgi/doublebuffereddrawing


Usage
=====

Usage example::

    import wx
    import wx.lib.agw.speedmeter as SM

    class MyFrame(wx.Frame):

        def __init__(self, parent):

            wx.Frame.__init__(self, parent, -1, "SpeedMeter Demo")

            speed = SM.SpeedMeter(self, agwStyle=SM.SM_DRAW_HAND|SM.SM_DRAW_SECTORS|SM.SM_DRAW_MIDDLE_TEXT|SM.SM_DRAW_SECONDARY_TICKS)

            # Set The Region Of Existence Of SpeedMeter (Always In Radians!!!!)
            speed.SetAngleRange(-pi/6, 7*pi/6)

            # Create The Intervals That Will Divide Our SpeedMeter In Sectors
            intervals = range(0, 201, 20)
            speed.SetIntervals(intervals)

            # Assign The Same Colours To All Sectors (We Simulate A Car Control For Speed)
            # Usually This Is Black
            colours = [wx.BLACK]*10
            speed.SetIntervalColours(colours)

            # Assign The Ticks: Here They Are Simply The String Equivalent Of The Intervals
            ticks = [str(interval) for interval in intervals]
            speed.SetTicks(ticks)
            # Set The Ticks/Tick Markers Colour
            speed.SetTicksColour(wx.WHITE)
            # We Want To Draw 5 Secondary Ticks Between The Principal Ticks
            speed.SetNumberOfSecondaryTicks(5)

            # Set The Font For The Ticks Markers
            speed.SetTicksFont(wx.Font(7, wx.FONTFAMILY_SWISS, wx.FONTSTYLE_NORMAL, wx.FONTWEIGHT_NORMAL))

            # Set The Text In The Center Of SpeedMeter
            speed.SetMiddleText("Km/h")
            # Assign The Colour To The Center Text
            speed.SetMiddleTextColour(wx.WHITE)
            # Assign A Font To The Center Text
            speed.SetMiddleTextFont(wx.Font(8, wx.FONTFAMILY_SWISS, wx.FONTSTYLE_NORMAL, wx.FONTWEIGHT_BOLD))

            # Set The Colour For The Hand Indicator
            speed.SetHandColour(wx.Colour(255, 50, 0))

            # Do Not Draw The External (Container) Arc. Drawing The External Arc May
            # Sometimes Create Uglier Controls. Try To Comment This Line And See It
            # For Yourself!
            speed.DrawExternalArc(False)

            # Set The Current Value For The SpeedMeter
            speed.SetSpeedValue(44)


    # our normal wxApp-derived class, as usual

    app = wx.App(0)

    frame = MyFrame(None)
    app.SetTopWindow(frame)
    frame.Show()

    app.MainLoop()



Methods and Settings
====================

:class:`SpeedMeter` is highly customizable, and in particular you can set:

- The start and end angle of existence for :class:`SpeedMeter`;
- The intervals in which you divide the :class:`SpeedMeter` (numerical values);
- The corresponding thicks for the intervals;
- The interval colours (different intervals may have different filling colours);
- The ticks font and colour;
- The background colour (outsize the :class:`SpeedMeter` region);
- The external arc colour;
- The hand (arrow) colour;
- The hand's shadow colour;
- The hand's style ("arrow" or "hand");
- The partial filler colour;
- The number of secondary (intermediate) ticks;
- The direction of increasing speed ("advance" or "reverse");
- The text to be drawn in the middle and its font;
- The icon to be drawn in the middle;
- The first and second gradient colours (that fills the :class:`SpeedMeter` control);
- The current value.


Window Styles
=============

This class supports the following window styles:

=========================== =========== ==================================================
Window Styles               Hex Value   Description
=========================== =========== ==================================================
``SM_ROTATE_TEXT``                  0x1 Draws the ticks rotated: the ticks are rotated accordingly to the tick marks positions.
``SM_DRAW_SECTORS``                 0x2 Different intervals are painted in different colours (every sector of the circle has its own colour).
``SM_DRAW_PARTIAL_SECTORS``         0x4 Every interval has its own colour, but only a circle corona is painted near the ticks.
``SM_DRAW_HAND``                    0x8 The hand (arrow indicator) is drawn.
``SM_DRAW_SHADOW``                 0x10 A shadow for the hand is drawn.
``SM_DRAW_PARTIAL_FILLER``         0x20 A circle corona that follows the hand position is drawn near the ticks.
``SM_DRAW_SECONDARY_TICKS``        0x40 Intermediate (smaller) ticks are drawn between principal ticks.
``SM_DRAW_MIDDLE_TEXT``            0x80 Some text is printed in the middle of the control near the center.
``SM_DRAW_MIDDLE_ICON``           0x100 An icon is drawn in the middle of the control near the center.
``SM_DRAW_GRADIENT``              0x200 A gradient of colours will fill the control.
``SM_DRAW_FANCY_TICKS``           0x400 With this style you can use xml tags to create some custom text and draw it at the ticks position. See :mod:`lib.fancytext` for the tags.
=========================== =========== ==================================================


Events Processing
=================

`No custom events are available for this class.`


License And Version
===================

:class:`SpeedMeter` is distributed under the wxPython license.

Latest revision: Andrea Gavana @ 27 Dec 2012, 21.00 GMT

Version 0.3


|class_summary| Classes Summary
===============================

================================================================================ ================================================================================
`~wx.lib.agw.speedmeter.BufferedWindow`                                          A buffered window class.
`~wx.lib.agw.speedmeter.SpeedMeter`                                              :class:`SpeedMeter` tries to reproduce the behavior of some car controls (but not only),
================================================================================ ================================================================================


|


.. toctree::
   :maxdepth: 1
   :hidden:

   wx.lib.agw.speedmeter.BufferedWindow
   wx.lib.agw.speedmeter.SpeedMeter