Click here to Skip to main content
Click here to Skip to main content

CircleControl - A Circular Motion Control

, 13 Sep 2013
Rate this:
Please Sign up or sign in to vote.
A circular motion control

Introduction

This is release 1.2.1 of the library. It fixes a SnapMode bug in the CircleControl.MarkerSet class. Thanks to CodeProject user IrkedScientist for finding the bug AND sending me a fix.

The CircleControl class is a .NET 2.0 control which allows circular motion, for example, rotating a dial, or setting the hands on an analog clock.

The control supports markers - graphical objects which can be positioned programatically and/or dragged with the mouse, and marker sets, which are groups of markers which move in unison. The background may be populated with colored rings, tick marks, and text strings.

All public and protected classes, methods and properties and fully documented using standard C# XML documentation comments. The project includes a HTML help file. Refer to the Overview section in the help file for more details on using the class, and refer to the Sample Program section for a complete source listing of a working application.

The CircleControl_121_Library download includes:

CircleControl.dll Class library
CircleControl.chm Help file.

The CircleControl_121_Demo download includes the above files, as well as:

AnalogClock.exe Sample program showing an analog clock; the time may be changed by dragging the hour and minute hands.
ColorDialer.exe Sample program for picking a color; rotate the red, blue, and green dials to select the RGB values. The program is visually gratuitous demonstration of the control, and is not meant to be a serious color picker.
EditDefaults.exe Sample program demonstrating the effect of changing various CircleControl properties. It also demonstrates the new Snap feature.
GantryControl.exe Sample program as detailed in the Sample Program section of the help file.
ManyRings.exe Sample program showing excessive use of rings. Includes capability to compare paint times with FixedBackground set to true or false.

The CircleControl_121_Source download includes the source for all of above programs, as well as the necessary files for building the help file.

Using the code

To use the CircleControl class, simply add it on an existing form:

    CircleControl cc = new CircleControl();
    cc.Location = new System.Drawing.Point(0, 0);
    cc.Size = new System.Drawing.Size(200, 200);
    form.Controls.Add(cc);

By default, a new instance of CircleControl comes ready to use with a single triangular marker and ten tick marks.

To add a new marker, create a new MarkerSet, and add one or more Marker objects:

    CircleControl.MarkerSet ms = new CircleControl.MarkerSet();
    cc.MarkerSets.Add(ms);

    // Polygon which defines shape of marker
    PointF[] poly = new PointF[4];
    poly[0] = new PointF(0.25F,  0.00F);
    poly[1] = new PointF(0.70F,  0.18F);
    poly[2] = new PointF(0.64F,  0.00F);
    poly[3] = new PointF(0.70F, -0.18F);

    CircleControl.Marker m = new CircleControl.Marker(
                      Color.Brown,       // inside color
                      Color.DarkGreen,   // border color
                      1.0f,              // border thickness
                      poly,              // polygon defining marker shape
                      130.0f,            // angle offset of marker
                      MouseButtons.Left, // which button(s) can drag the marker
                      true);             // is marker visible?

    // Add new marker to MarkerSet, at which point
    // it becomes visible on the control
    ms.Add(m);

The polygon defines the appearance of the marker at angle zero. It uses a cartesian coordinate system, where (0,0) is the center of the control, and 1.0 is the distance to the nearest edge. The internal area of a marker can be a solid color, a hatch pattern, or a variety of color gradients. Borders can be of any color and thickness.

An AngleChanged event is raised whenever the angle of a marker changes, or the mouse state of a dragged marker changes. To receive events, install a handler:

    cc.AngleChanged += new CircleControl.AngleChangedHandler(OnAngleChange);

The background may be populated with colored rings, tick marks, and text strings. The following code snippet adds a beige-colored ring, and four text items, as they would be placed on a compass:

    cc.Rings.Add(new CircleControl.Ring(0.6f,        // size as radius
                                        Color.Beige, // internal color
                                        Color.Black, // border color
                                        2.0f);       // border thickness

    Font f = new Font("Arial", 8.0f);
    cc.TextItems.Add(new CircleControl.TextItem(f,         // font
                                                Color.Red, // color
                                                "N",       // text
                                                0.8f,      // distance from origin
                                                90.0f);    // angle
    cc.TextItems.Add(new CircleControl.TextItem(f, Color.Red, "S", 0.8f, 270.0f);
    cc.TextItems.Add(new CircleControl.TextItem(f, Color.Red, "E", 0.8f,   0.0f);
    cc.TextItems.Add(new CircleControl.TextItem(f, Color.Red, "W", 0.8f, 180.0f);

The internal area of a ring can be a solid color, a hatch pattern, or a variety of color gradients. Borders can be of any color and thickness. Text items can be of any font, color, or rotation. They can be a fixed size, or made to be relative to the size of the control.

The above code snippets only provide a brief overview. Refer to project help file for complete class documentation.

Points of Interest

Writing, refining, and debugging the code was, as always, a joyful experience. But documenting every public and protected class, method and property was not. It was drudgery. The pain of writing full and proper documentation was offset in part by Sandcastle Help File Builder, a freely available tool used to generate the help file. But documenting everything was a learning experience, and I've developed immense respect for programmers who write complete and useful documentation, especially for those at Microsoft who are responsible for the creation of the extensive .NET documentation.

History

  • September 14, 2013 - Release 1.2.1
    • Fixed bug in private method CircleControl.MarkerSet.CalcSnapDist() where the snap angle may be improperly calculated if CircleControl.AngleWraps is false.
  • September 8, 2012 - Release 1.2
    • Added SnapMode and SnapAngles properties CircleControl.MarkerSet.
  • July 21, 2011 - Release 1.1.2
    • Fixed bug in CircleControl.Collections.Insert() method where the Cc parameter was improperly being set to null.
  • November 1, 2010 - Release 1.1.1
    • Fixed bug in CircleControl.SetAngleMinMax() method where the call was ignored unless both min and max parameters were different from the current values.
    • Fixed bug where marker angles were not always calculated properly if AngleWraps was false.
  • October 12, 2010 - Release 1.1
    • Added FixedBackground property to CircleControl.
  • September 12, 2010 - First release

License

This article, along with any associated source code and files, is licensed under The Code Project Open License (CPOL)

About the Author

Graham Wilson
Software Developer (Senior)
Canada Canada
No Biography provided

Comments and Discussions

 
GeneralMy vote of 5 PinmemberJohann Krenn14-Sep-13 23:49 
GeneralRe: My vote of 5 PinmemberGraham Wilson15-Sep-13 15:37 
QuestionGreat Work!! PinmemberAureocad26-Aug-13 23:20 
AnswerRe: Great Work!! PinmemberGraham Wilson15-Sep-13 15:37 
GeneralMy vote of 5 PinmemberKD0YU30-Nov-12 3:13 
QuestionCool Pinmembersam.hill8-Sep-12 16:27 
QuestionInvert Primary Marker PinmemberTodd Denlinger8-Aug-12 12:07 
AnswerRe: Invert Primary Marker PinmemberGraham Wilson8-Aug-12 15:58 
GeneralRe: Invert Primary Marker PinmemberTodd Denlinger9-Aug-12 4:27 
GeneralMy vote of 5 PinmemberProEnggSoft13-Mar-12 1:06 
GeneralMy vote of 4 Pinmembermariazingzing15-Feb-12 12:56 
GeneralMy vote of 5 PinmemberpeteSJ22-Jul-11 6:57 
Questionexcellent, and fully documented code PinmemberBillWoodruff21-Jul-11 12:06 
QuestionCool PinmemberCIDev21-Jul-11 5:22 
QuestionGood work PinmemberShahriar Iqbal Chowdhury21-Jul-11 4:58 
GeneralMy vote of 5 Pinmemberashishkumar00831-May-11 12:19 
GeneralMarkers and rings Pinmemberjrwakeen6-Feb-11 17:19 
GeneralRe: Markers and rings PinmemberGraham Wilson8-Feb-11 16:29 
GeneralRe: Markers and rings PinmemberGraham Wilson8-Feb-11 17:20 
GeneralMy vote of 5 PinmemberVistaHacker2-Nov-10 4:07 
GeneralMy vote of 5 PinmemberRoger Wright1-Nov-10 19:59 
GeneralMy vote of 5 PinmemberMember 154261529-Oct-10 7:17 
GeneralMy vote of 5 PinmemberYogi Yang19-Oct-10 1:09 
GeneralRe: My vote of 5 PinmemberGraham Wilson19-Oct-10 16:31 
GeneralMy vote of 5 PinmemberR&D_Man17-Oct-10 22:16 
GeneralRe: My vote of 5 PinmemberGraham Wilson19-Oct-10 16:30 
GeneralMy vote of 5 PinmemberWilliamCruisoring8-Oct-10 16:48 
GeneralRe: My vote of 5 PinmemberGraham Wilson19-Oct-10 16:29 
GeneralSandcastle is useful, but ironically poorly documented Pinmembermsorens21-Sep-10 12:59 
GeneralRe: Sandcastle is useful, but ironically poorly documented PinmemberGraham Wilson21-Sep-10 16:44 
GeneralRe: Sandcastle is useful, but ironically poorly documented Pinmembertlhintoq18-Oct-10 7:19 
GeneralRe: Sandcastle is useful, but ironically poorly documented Pinmembermsorens18-Oct-10 9:15 
GeneralRe: Sandcastle is useful, but ironically poorly documented Pinmembertlhintoq18-Oct-10 9:21 
GeneralRe: Sandcastle is useful, but ironically poorly documented Pinmembermsorens18-Oct-10 10:11 
GeneralMy vote of 5 PinmemberJaime Olivares20-Sep-10 15:33 
GeneralRe: My vote of 5 PinmemberGraham Wilson21-Sep-10 16:38 
Generalawesome control PinmemberChrist Kennedy13-Sep-10 2:59 
GeneralRe: awesome control PinmemberGraham Wilson21-Sep-10 16:36 
GeneralMore Info PinmentorKunalChowdhury12-Sep-10 22:44 
Generalmy anti-virus hates you! PinmemberChrist Kennedy12-Sep-10 16:41 
GeneralRe: my anti-virus hates you! PinmentorKunalChowdhury12-Sep-10 22:49 
GeneralRe: my anti-virus hates you! PinmemberGraham Wilson13-Sep-10 15:59 
GeneralRe: my anti-virus hates you! PinmemberChrist Kennedy14-Sep-10 3:21 

General General    News News    Suggestion Suggestion    Question Question    Bug Bug    Answer Answer    Joke Joke    Rant Rant    Admin Admin   

Use Ctrl+Left/Right to switch messages, Ctrl+Up/Down to switch threads, Ctrl+Shift+Left/Right to switch pages.

| Advertise | Privacy | Mobile
Web02 | 2.8.140709.1 | Last Updated 14 Sep 2013
Article Copyright 2010 by Graham Wilson
Everything else Copyright © CodeProject, 1999-2014
Terms of Service
Layout: fixed | fluid