CircleControl - A Circular Motion Control

• Download CircleControl_123_Source.zip - 250.3 KB
• Download CircleControl_123_Library.zip - 584.7 KB
• Download CircleControl_123_Demo.zip - 616 KB

Introduction

This is release 1.2.3 of the library. It fixes a bug where CircleControl.AngleChanged() was not always being triggered for mouse up or down events. Added a feature to the EditDefaults sample application to display the most recent AngleChangedArgs.

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_123_Library download includes:

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

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

Compatibility with Other .NET Framework Versions

The CircleControl library is compiled using .NET Framework version 2.0. To confirm that there were no issues with other framework versions, the compiled library was used by an application which was compiled, in turn, under .NET Framework versions 3.0, 3.5, 4.0, and 4.5. The CircleControl functioned properly with all of them.

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

• June 13, 2015 - Release 1.2.3
  • Fixed a bug where CircleControl.AngleChanged() was not always being triggered for mouse up and mouse down events,
• September 5, 2014 - Release 1.2.2
  • Corrected minor documentation errors,
  • Converted .csproj files to Visual Studio 2013 format.
  • Converted help files to work with SandCastle Help File Builder 2014.5.31.0.
• September 14, 2013 - Release 1.2.1
  • Fixed bug in private method <c>CircleControl.MarkerSet.CalcSnapDist() where the snap angle may be improperly calculated if <c>CircleControl.AngleWraps is <c>false.
• September 8, 2012 - Release 1.2
  • Added <c>SnapMode and <c>SnapAngles properties <c>CircleControl.MarkerSet.
• July 21, 2011 - Release 1.1.2
  • Fixed bug in <c>CircleControl.Collections.Insert() method where the Cc parameter was improperly being set to <c>null.
• November 1, 2010 - Release 1.1.1
  • Fixed bug in <c>CircleControl.SetAngleMinMax() method where the call was ignored unless both <c>min and <c>max parameters were different from the current values.
  • Fixed bug where marker angles were not always calculated properly if <c>AngleWraps was <c>false.
• October 12, 2010 - Release 1.1
  • Added <c>FixedBackground property to <c>CircleControl.
• September 12, 2010 - First release