This guide is intended for users
with little or no experience with the Perfect Widgets product. The idea behind
it is to demonstrate the basic capabilities of the product as well as to
provide some initial knowledge of the workflow. After finishing this guide you
will be able to create your own widget from scratch.
After the product is downloaded
and installed on your PC you can find a Perfect Widgets Designer tool in your
applications menu or simply locate the PerfectWidgetsDesigner binary in the Designer
folder of the installed product. The Designer is the main component of Perfect
Widgets product and is used to create and save the widget instruments for
further use.
Run the .exe to start the Perfect Widgets Designer.
You can notice an additional
Perfect Widgets Wizard window in the center of the screen that offers to choose
a sample widget from a set of collections. This comes in handy because you can
choose from a variety of widgets to get the idea about the product
capabilities. The predefined samples are editable and can be further modified
by you according to your needs.
Since we are going to create a
widget from scratch we would rather skip this step for now. So, close the
Wizard by pressing the Cancel
button.
in the upper part of the window.
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:
- <head>
- <title></title>
- <!--importing ScriptSharp library-->
- <script src="mscorlib.js" type="text/javascript"></script>
- <!--importing Perfectwidgets library-->
- <script src="PerfectWidgets.js" type="text/javascript"></script>
- <script type="text/javascript">
-
- var widget;
- var jsonModel;
- var slider;
-
- window.onload = function () {
- //widget model
- jsonModel = <!-- place here the widget JSON code imported from the Designer with semicolon at the end -->
- //creating a widget
- widget = new PerfectWidgets.Widget("root", jsonModel);
- }
- function updateSliderValue() {
- slider = widget.getByName("Slider1");
- slider.setValue(document.getElementById("ValueBox").value);
- }
- </script>
- </head>
- <body>
- <!--creating a container for the widget-->
- <div id="root"></div>
- <!--creating a container for the input box-->
- <div><input type="text" id="ValueBox" value="0"/><button onclick="updateSliderValue();">Set value</button></div>
- </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.