.. include:: headings.inc

.. module:: lib.agw.knobctrl

.. currentmodule:: lib.agw.knobctrl

.. highlight:: python



.. _lib.agw.knobctrl:

==========================================================================================================================================
|phoenix_title|  **knobctrl**
==========================================================================================================================================

:class:`KnobCtrl` lets the user select a numerical value by rotating it.


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

:class:`KnobCtrl` lets the user select a numerical value by rotating it. It works like a
scrollbar: just set the ticks range property and read the value property in the
associated ``EVT_KC_ANGLE_CHANGING``/``EVT_KC_ANGLE_CHANGED`` events. Simple but
effective.

It can be easily used if you want to simulate the volume knob of a music player
or similar functionalities.


Usage
=====

Usage example::

    import wx
    import wx.lib.agw.knobctrl as KC

    class MyFrame(wx.Frame):

        def __init__(self, parent):
        
            wx.Frame.__init__(self, parent, -1, "KnobCtrl Demo")

            panel = wx.Panel(self)
            
            knob1 = KC.KnobCtrl(panel, -1, size=(100, 100))
            knob2 = KC.KnobCtrl(panel, -1, size=(100, 100))

            knob1.SetTags(range(0, 151, 10))
            knob1.SetAngularRange(-45, 225)
            knob1.SetValue(45)

            knob2.SetTags(range(0, 151, 10))
            knob2.SetAngularRange(0, 270)
            knob2.SetValue(100)
        
            main_sizer = wx.BoxSizer(wx.VERTICAL)
            main_sizer.Add(knob1, 0, wx.EXPAND|wx.ALL, 20)
            main_sizer.Add(knob2, 0, wx.EXPAND|wx.ALL, 20)

            panel.SetSizer(main_sizer)
            main_sizer.Layout()
            

    # our normal wxApp-derived class, as usual

    app = wx.App(0)

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

    app.MainLoop()



Events
======

:class:`KnobCtrl` implements two events that can be intercepted by the user:

- ``EVT_KC_ANGLE_CHANGING``;
- ``EVT_KC_ANGLE_CHANGED``.

The first one can be "vetoed" by eliminating the `event.Skip()` at the end of the
event handler.


Supported Platforms
===================

:class:`KnobCtrl` has been tested on the following platforms:
  * Windows (Windows XP);
  * Linux Ubuntu (Dapper 6.06)


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

This class supports the following window styles:

================== =========== ==================================================
Window Styles      Hex Value   Description
================== =========== ==================================================
``KC_BUFFERED_DC``         0x1 Flag to use double buffering (recommendeded = 1).
================== =========== ==================================================


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

This class processes the following events:

========================= ==================================================
Event Name                Description
========================= ==================================================
``EVT_KC_ANGLE_CHANGED``  Notify the client that the knob has changed its value.
``EVT_KC_ANGLE_CHANGING`` Notify the client that the knob is changing its value.
========================= ==================================================


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

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

Latest Revision: Andrea Gavana @ 17 Aug 2011, 15.00 GMT

Version 0.3



|

|class_hierarchy| Inheritance Diagram
=====================================

Inheritance diagram for module **knobctrl**

.. raw:: html

   <p class="graphviz">
   <img src="_static/images/inheritance/lib.agw.knobctrl_inheritance.png" alt="Inheritance diagram of knobctrl" usemap="#dummy" class="inheritance"/>
   <map id="dummy" name="dummy"> <area shape="rect" id="node1" href="lib.agw.knobctrl.KnobCtrlEvent.html" title="Represent details of the events that the KnobCtrl object sends." alt="" coords="835,58,1021,89"/> <area shape="rect" id="node4" href="Window.html" title="Window  is the base class for all windows and represents any visible object on screen." alt="" coords="423,5,503,35"/> <area shape="rect" id="node14" href="lib.agw.knobctrl.BufferedWindow.html" title="A Buffered window class." alt="" coords="580,5,785,35"/> <area shape="rect" id="node5" href="EvtHandler.html" title="A class that can handle events from the windowing system." alt="" coords="247,5,345,35"/> <area shape="rect" id="node7" href="Object.html" title="This is the root class of many of the wxWidgets classes." alt="" coords="125,31,197,62"/> <area shape="rect" id="node16" href="Event.html" title="An event is a structure holding information about an event passed to a callback or member function." alt="" coords="260,58,332,89"/> <area shape="rect" id="node9" href="CommandEvent.html" title="This event class contains information about command events, which originate from a variety of simple controls." alt="" coords="395,58,531,89"/> <area shape="rect" id="node13" href="lib.agw.knobctrl.KnobCtrl.html" title="This class can be used to simulate a knob volume control often found in" alt="" coords="855,5,1001,35"/> </map> 
   </p>

|


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

================================================================================ ================================================================================
:ref:`lib.agw.knobctrl.BufferedWindow`                                           A Buffered window class.
:ref:`lib.agw.knobctrl.KnobCtrl`                                                 This class can be used to simulate a knob volume control often found in
:ref:`lib.agw.knobctrl.KnobCtrlEvent`                                            Represent details of the events that the :class:`KnobCtrl` object sends.
================================================================================ ================================================================================


|


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

   lib.agw.knobctrl.BufferedWindow
   lib.agw.knobctrl.KnobCtrl
   lib.agw.knobctrl.KnobCtrlEvent