The Ribbon panel has a number of tabs which, in fact, duplicate some other panel options ( for example, elements from the Insert tab resemble the options available  in the Toolbox panel, and the Properties tab has the best part of the options presented in the Property Grid panel). The main difference here is that the Ribbon panel provides a user with the most frequently used components, while each particular panel gives more room for creativity.

So, let’s get back to creating our sample widget, and assume we want to create a mechanical speedometer-like widget that displays the values we pass to it. Our choice is determined by the fact that we have a clear view of speedometer elements commonly used in such devices thus making it easier for us to develop our widget model.

Defining the Logical Structure

To start with, we should see what logical elements of the Designer are available and choose the ones we can use in our example. So let’s review the components of the Structure section of the Toolbox.

The upper two elements of this section are the primary elements we should start our design with. They are called Joint and Guide and represent two main trajectory types that can be used when creating a widget. As the icon above the element depicts, the Guide is the trajectory having the form of the line, whereas the Joint is the trajectory having the form of the arc. Since the speedometer model implies some kind of circular arrow movement, the Joint would be our choice here.

The sample widget model with Joint element structure

The sample widget model with the Guide implemented.

To put the Joint element onto the form you can drag-n-drop it from the Toolbox panel.

The element’s name is defined as Joint1 in the Instrument Tree.  From now on, we should take special attention to the hierarchical structure of our widget, since it’s very important. As we see, the Instrument element as such is the compound element that includes all elements embedded. After defining the trajectory type we, obviously, should place some scale for our values range.  For this purpose we can use a Scale element. To put the Scale onto the form you can also drag-n-drop it from the Toolbox panel.

As a result we see a dialog window that provides us with two options: to set the name for our Scale element and specify a parent container for the Scale. The Joint1 is automatically provided as a default parent container for our Scale element, so we will stick to it.  Actually, if we need to create and define some other parent container for our Scale, then pressing the green plus button to the right of the parent container field will save our time. It’s quicker than adding the required parent element from the Toolbox.

After the Scale is added, we can see this element placed in the Joint1 group of our component.

It is also worth mentioning that double clicking the element in the Instrument tree panel will open the appropriate tab in the Ribbon bar as displayed in the figure above,and this appears very handy in our work.

The two main parameters we should specify for the Scale element now are the Minimum and Maximum values for the Scale. We specify the Minimum value as 0 while the Maximum value is set to 220.

The next and the last step in our logical structure is to place a Slider to be able to display the current value passed to our widget. This is also performed by drag-n-drop and, reasonably, the Slider element would be put in the Scale1 group since it should point to the values specified in our Scale value range.

The current hierarchical structure of our logical elements after this step is displayed in the figure below.

Working with Visual Elements

The steps we would take further relate to the visual representation of our widget and look no less interesting and appealing.  As the defined logical structure has no direct visual representation and running the widget for our test will result in a blank form, we should add visual elements to our logical framework; these are, namely, a Needle to point out the speedometer value and the dial elements, such as Labels and Tick marks.

The Needle element is located in the Polygonal section of the Toolbox.  Let’s place it on our form by drag-n-drop. Obviously, we should place the Needle in our Slider1 group since it would directly interact with Slider movement.  It should be also mentioned that it’s possible to customize the Needle appearance by replacing the initial Needle form with the predefined Needle template. To do this, double click the element in the Instrument Tree to open the Needle tab in the Ribbon panel and click NeedleType to see the available templates.

As for our example, we won’t change the Needle form because the initial one suits just fine for our speedometer widget.

The main parameters we should set for the Needle in this step are the Bindings that represent the start and end points accordingly. The values are already predefined in the drop-down menu and all we have to do is to choose the one.

Specifying the start point as To the center of Joint will automatically place the Needle start point to this position so we don’t have any bother specifying the Needle placement manually. The end point would be defined as To the position of Joint’s Slider which means that the Needle would rotate according to the Slider trajectory.

To finish up with the Needle we should set some fill for it so it would be colored.  The fill editor is called by clicking the Fill field in the Property Grid.  In our example we define the red solid fill for our Needle element.

 

Next we should define some measuring Tick marks for our speedometer dial and provide Labels for them.

To do this, we can use both ScaleLabels and Ticks elements from the Scale Elements section of the Toolbox. Both elements should be placed inside the Scale1 group as the opened window suggests by default.

 

 

Divisions and SubDivisions properties of the Ticks element are defined as shown in the figure above. So, in our example we have 11 divisions for our dial and 7 subdivisions inside each division. The tick length in our division equals 20 pixels and we set the length for the subdivision length half as much to 10 pixels.

Check the figure below for reference.

As for the Scale Labels, the main properties we define for the element are as follows:

a)      Divisions = 11 ( the value should be the same as for the Ticks element)

b)      Format = General

c)       TextRotationMode = Screen

As we see, the values for our Labels are automatically set in the range from 0 to 220 according to the Minimum and Maximum scale values that we specified in one of our previous steps.

To fine tune the precise position of our elements on the dial we can use ItemMargins and Padding properties.  Also, we should specify the Dock value for ScaleLabels, Ticks and SubTicks. The Dock property adjusts the elements in relation to the Joint’s border.  Let’s select the Inside value for ScaleLabels , Center for the Ticks and Far for the SubTicks accordingly. Alternatively we can choose a docking preset template to simplify this process. See the figure below.

Finally, we should customize the appearance of speedometer dial to look more attractive. In our sample, we used a number of different sized circles from the Primitives section of the Toolbox as well as the predesigned Picture element to represent the Needle cup.

The complete elements hierarchy of our sample and the widget representation are shown in the figures below.

             

Adding Visual Effects

Actually we can go a little further in our imagination and implement an interesting feature that should add more interactivity to our widget. Namely, we can make the rounded Needle cup in the center of the speedometer dial rotate simultaneously to the Needle, since the initial example lacks this feature.  As it turned out, this can be easily done. To do this, select the Picture1 element from the Slider1 section and specify the following binding expressions in the Bindings panel.

To elaborate on this, we had to specify two points for our circular element; the first one is the center point, which should always be the same since it’s bound to the Joint1.center, which is static, and the second Needle1.Angle expression binds the element so it would simultaneously rotate to the same angle as the Needle does. The bindings are set with the help of the Expression Editor which is displayed in the figure below.

As we can see, the editor has quite a vast set of options which would definitely suit for a variety of binding expressions.

Testing a Widget

After the widget is created it would be great to see the widget’s functionality in action. To do this, we can create an HTML based page and add the widget to it.  Then, for example, we can add a textbox to pass an input value to our widget, so we can see how it works.  The sample content of the page is as follows:

1. <head>  
2.     <title></title>  
3.     <!--importing ScriptSharp library-->  
4.     <script src="mscorlib.js" type="text/javascript"></script>   
5.     <!--importing Perfectwidgets library-->  
6.     <script src="PerfectWidgets.js" type="text/javascript"></script>  
7.     <script type="text/javascript">  
8.    
9.         var widget;  
10.         var jsonModel;  
11.         var slider;       
12.    
13.         window.onload = function () {  
14.             //widget model  
15.             jsonModel = <!-- place here the widget JSON code imported from the Designer with semicolon at the end -->  
16.             //creating a widget  
17.             widget = new PerfectWidgets.Widget("root", jsonModel);             
18.         }  
19.         function updateSliderValue() {  
20.             slider = widget.getByName("Slider1");  
21.             slider.setValue(document.getElementById("ValueBox").value);  
22.         }  
23.     </script>  
24. </head>  
25. <body>  
26.     <!--creating a container for the widget-->  
27.     <div id="root"></div>  
28.     <!--creating a container for the input box-->  
29.     <div><input type="text" id="ValueBox" value="0"/><button onclick="updateSliderValue();">Set value</button></div>  
30. </body>  

As a result, we have the widget displayed on the page and can use the control below for passing a value.

Conclusion

The instrument sample used in this guide as well as a sample test page can be downloaded from http://perpetuumsoft.com/sf/support/Speedometer.zip. The demo sample can also be viewed at http://perpetuumsoft.com/Demo/pw/GettingStarted/SpeedometerSample.htm.

Every effort has been made to ensure that this document is an accurate representation of the functionality of Perfect Widgets software.  As with every software application, development continues after the documentation has gone to press so small inconsistencies may occur. We would appreciate any feedback on this manual. Send comments via email to: support@perpetuumsoft.com.