iWheel - Usage tutorial

Chapters

1. Placing on the form
2. Working with Cylinders
3. TextCylinder
4. ImageCylinder
5. Customizing iWheel’s look
6. Further customizations with custom cylinder
7. Rotate cylinders from code

Placing on the form

To add iWheel control to the form simply double-click it in the toolbox. This is how it should appear:

You can adjust its position and size by manipulating the Size and Location properties. You can also use the Dock property to dock the control to any of the edges of the form.

Working with Cylinders

iWheel’s Cylinders are objects which are used to display lists of data. Cylinder class is an abstract class, it is designed for the inheritors to create their own Cylinders. Currently iWheel contains a TextCylinder and an ImageCylinder. A TextCylinder is designed to display a list of string objects. ImageCylinder can be used to display images. Cylinders are maintained by iWheel using a CylinderCollection class. iWheel has one CylinderCollection and it can be accessed via its Cylinders property.

Click Cylinders property in the designer and click the button with “…” (it should be selected by default). A Cylinder Collection Editor will appear:

Notice a little arrow next to Add button. Click the arrow and you will find out that you can add either TextCylinder or ImageCylinder.

TextCylinder

Add a TextCylinder to the Cylinder Collection:

Adjust its properties. Here’s an explanation of the properties:

The Strings property is used to assign a list of string items to a TextCylinder. Click the “…” button next to Strings property and a String Collection Editor appears. Type the strings you would like the TextCylinder to contain. Separate them by pressing Enter key. Click OK. Notice how the items appeared in the designer of your form. You can use the SelectedIndex property to set an index of the item which should be selected.

ImageCylinder

If you want to use an ImageCylinder to display images over the surface of the Cylinder, you have to add an ImageList object to your project first. So look for an ImageList (NOT TImageList) in Visual Studio toolbox (it should be inside ‘Device Components’ tab).

• Add images to your ImageList.
• Give your ImageList a name.
• Add an ImageCylinder to iWheel’s CylinderCollection.
• Set its ImageList property to the ImageList object you added to your project.

Adjust the properties of ImageCylinder. Here’s an explanation of the properties:

Your iWheel designer should now look similar to this:

Customizing iWheel’s look

Notice that there are margins to iWheel’s cylinders – distance between the edges of iWheel and the cylinders themselves. You can adjust the size of these margins using Margins property.

Margins property allows you to set the distance of Cylinders from the edges of iWheel. Expand the Margins property by clicking the “plus” sign in the property list. You will see properties for Left, Right, Top and Bottom margin. The length of each margin can be specified either in pixels (in which case the value is automatically scaled on high resolution displays) or in percentage. The percentage relates to width (for left and right margins) and to height (for top and bottom margins) of the whole iWheel.

This is a great functionality if you want the ratio of margin lengths to size of iWheel remain the same even if iWheel is resized.

iWheel’s background can be customized using BackColorFill property. The property can take on the following values:

In order to take a full advantage of this feature, you can use a BeeMobile.TForm as the project’s form instead of standard System.Windows.Forms.Form.

Once you add a reference to this library to your project, you can change the standard form for TForm. To do that, just right-click the form in the designer and hit ‘View code’ to go into the code of your project. Then change:

namespace iWheelTutorial
{
    public partial class Form1 : Form
    {
        public Form1()
        {
            InitializeComponent();
        }
    }
}

to

namespace iWheelTutorial
{
    public partial class Form1 : BeeMobile.TransparentControls.TForm
    {
        public Form1()
        {
            InitializeComponent();
        }
    }
}

Notice that Form1 inherits from TForm now. If you display the designer of your form now, you will notice that it contains a BackgroundImage property and a StretchBackground property. Assign a background image to the TForm. Then change BackColorFill property to Transparent. You should get a result similar to this:

Further customizations with custom cylinder

For advanced customization you can create a custom Cylinder object by inheriting from Cylinder class. Cylinder class is designed in such way that it accepts an array of objects. These objects form a list of items. The items are then drawn over the surface of the Cylinder. If you are implementing a custom Cylinder, you need to provide it the array of objects and then ‘explain’ it how it should draw these objects. You provide the data to the Cylinder by assigning it to its m_Data data member. The type of this data member is array of objects.

To ‘explain’ it how should the object be drawn, override the abstract DrawItem(Graphics, RectangleF, Int32) method. The first parameter is a Graphics object used to perform the drawing. RectangleF object gives you the bounderies for the drawing. Int32 parameter is an index to m_Data array and points to object that should be drawn.

For example let’s say we want to create a cylinder which will accept a list of colors (Color objects) and then it will draw each color by drawing a filled ellipse in that particular color. We will call this cylinder a ColorCylinder. The ColorCylinder will be derived from Cylinder. It must have a property which we will use to assign the array of colors to it. It also has to override the DrawItem method. Here is the code in C#:

class ColorCylinder : Cylinder
    {

        public ColorCylinder()
            : base()
        {
        }

        public Color[] Colors
        {
            get
            {
                Color[] cArray = new Color[m_Data.Length];
                m_Data.CopyTo(cArray, 0);
                return cArray;
            }
            set
            {
                object[] oArray = new object[value.Length];
                value.CopyTo(oArray, 0);
                this.SetData(oArray);
            }
        }

        protected override void DrawItem(Graphics aGraphics, RectangleF aRectF, int aIndex)
        {
            using (SolidBrush sb = new SolidBrush((Color)m_Data[aIndex]))
            {
                float fWidth = aRectF.Width * 0.6f;
                float fHeight = aRectF.Height * 0.6f;
                RectangleF rectF = new RectangleF(aRectF.X + 0.2f * fWidth, aRectF.Y + 0.2f * fHeight,
                    fWidth, fHeight);
                aGraphics.FillEllipse(sb, Rectangle.Round(rectF));
            }
        }
    }

The Colors property is of type array of Color objects. Since we cannot cast type object[] to Color[] (and vice-versa) directly, we have to copy the array to a new one. The SetData method makes sure that our ColorCylinder is redrawn if the user assigns a new array of Colors to our ColorCylinder.

The DrawItem method creates a new SolidBrush and it uses it to paint a filled ellipse as a graphical representation of the color The actual colors are taken directly from the m_Data object using the aIndex parameter. This is the result:

Rotate cylinders from code

There are methods in iWheel which allow you to rotate the cylinders from your code. Notice that iWheel also contains a IgnoreMouseEvents property. If you set it to true, iWheel will not respond to any mouse clicks. That way you can prevent the user from rotating the cylinders himself.

To scroll any cylinder by specified amount of pixels use its Scroll(Int32) method. You can get to a particular cylinder through iWheel’s Cylinders property. So if you want to scroll a Cylinder which index is 0 by 5 pixels use this code:

iWheel1.Cylinders[0].Scroll(5);

The problem with this approach is that it is likely that the cylinder will not end up scrolling with its selected item centered in the middle of the cursor. You can call CenterSelectedItem(bool) method to center it:

iWheel1.Cylinders[0].CenterSelectedItem(true);

If you set the Boolean parameter to true, the item which is closest to the cursor will be centered. Otherwise that item will be centered into position which is the nearest one in the direction of the last scrolling of the Cylinder.

If you are into more advanced scrolling, notice the BeginSpinning and EndSpinning methods. BeginSpinning has only one parameter which type is List<SpinInfo>. SpinInfo class specifies which cylinder should be scrolled, how fast it should be scrollend and in which direction, how long it should scroll and which item should be selected once the scrolling is over. For each cylinder which you would like to spin, you have to create a SpinInfo object. Let’s say we want to spin Cylinder with index of 0. We want it to finish scrolling so that item with index 5 is selected. We want it to spin with speed of 14 pixels in each refresh (or -14 to spin upwards) and we want it to spin at least for 2500 miliseconds. We have to create a SpinInfo object like this:

SpinInfo si1 = new SpinInfo(0, 5, 14, 2500);

We will do this for another 2 cylinders (their indices are 1 and 2). Then we have to create a list of these SpinInfo objects and call iWheel’s BeginSpinning method and give it this list of SpinInfo objects as its only parameter:

SpinInfo si0 = new SpinInfo(0, 5, 14, 2500);
SpinInfo si1 = new SpinInfo(1, 4, -14, 1500);
SpinInfo si2 = new SpinInfo(2, 3, 14, 750);
List list = new List();
list.Add(si0);
list.Add(si1);
list.Add(si2);
iWheel1.BeginSpinning(list);

You can call the EndSpinning method to stop the spinning immediatelly. It is likely though, that the Cylinders will not be aligned. That is why you can call the CenterSelectedItem for each Cylinder, if you want to. The SpinningComplete event can inform you when the spinning has completed.