Perfect Widgets Designer Documentation

Perfect Widgets Designer Documentation


Destination and Basic Features


The Perfect Widgets is intended for creating and using indication and graphic user interface controls for HTML5 and JavaScript.
Nowadays most developers strive to create the most naturally looking, convenient and unique application interfaces. The Perfect Widgets is an ideal solution of this task.

Full-featured visual designer allows creating new visual components with the unique look and functionality by means of only a few mouse clicks. It can be both common controls such as Progress Bars, Meters, Dials, Sliders, Gauges, Odometers, Thermometers, Switches etc. and specialized elements for your industry: Manipulators, Scales, Special-Purpose Devices and many others.

Each Perfect Widgets control consists of visual and non-visual objects interacting with each other. Due to these objects use, a developer can create any necessary visual control.

To assign separate element properties the expressions can be used; it helps to adjust the property depending on the current instrument status, as well as on the mouse status.

A created instrument can be saved to a file for further use.

Perfect Widgets Concepts


The main concept of Perfect Widgets is the ability for quick and convenient creation of control objects according to the specified requirements without challenging a developer to have some special knowledge or high qualifications.

The Perfect Widgets contains components able to display an instrument and to manage it.

The Instrument is a compound object with hierarchical structure. There are primitives designed to assign instrument appearance and behavior in the instrument structure. 

To create an instrument, the designer included in the Perfect Widgets delivery package is used. The designer allows creating an instrument with the help of more primitive elements, included in it in different combinations. It’s also possible to set separate properties of the primitives, using convenient graphic means. To bind the primitives together and to assign the complex functionality, the expressions can be used.
Different combinations of primitives included in the instrument, flexibility in setting element properties, and use of expressions allow creating a control element, according to the developer’s requirements.

Elements Description


General Instrument Model


The Instrument is a compound object with a hierarchical structure. Any elements can be included in the instrument. The elements can be structurally divided into two groups: 

· simple;
· compound (elements that can include any other elements).

The elements can be functionally divided into:

· visual (are intended to assign instrument appearance); 
· non-visual (intended to bind and group elements, as well as to assign instrument behavior).

The elements can be included in the instrument in different combinations. However, for practical use, the instruments specifically intended for displaying and assigning some certain values are utilized.
Such elements are built according to the following scheme. One or several scales assigning and displaying value range are included in the instrument. Several sliders displaying (assigning) the current value are included. The elements, displaying the value in some other form, for example in the form of a text line, can also be included.

For example, the following structure is used to build a simple instrument:


 

Description of General Properties


Let’s consider the Instrument class properties, inherent in all descendants elements in details. 

The Name property assigns a unique name within the entire instrument. 
The Fill property assigns fill, which will be used for element drawing. 
Tracing line style, which will be used for element drawing, is assigned by the Stroke property. 
The Style property assigns element’s style name used for element drawing. Available styles are assigned in the Styles property of the instrument the element belongs to. If an element has no Fill and/or Stroke properties assigned, the style set in the instrument Style property will be applied. 
The Visible property assigns element visibility. 
The Active property indicates whether an element will handle mouse events.
The RecalculateAll property indicates for what elements the expressions will be recalculated if the element state is changed. If RecalculateAll is set to false, the expressions will be recalculated only for the selected element and all the elements included in it, otherwise the expressions of all instrument elements will be recalculated. 
The Size property is the size of the instrument work area. 
The Enabled property indicates whether an instrument will react on the user actions. 
The following properties are used only in the instrument design mode and saved with the instrument: SnapToGrid – snap to grid, the ShowGrid property - the grid visibility, the GridStep property – the step of the grid, the MeasureUnit property –the measurement units used.

Description of All Elements and Their Properties


Joint


The Joint element is a circular trajectory. 

It’s is assigned by center (the Center property), radius (the Radius property), starting angle (the StartAngle property) and total angle (the TotalAngle property). The angles are counted clockwise, from the horizontal axis. The Joint element is used to create circular gauges.


Guide


The Guide element is a linear trajectory.

The line is assigned by the start (the StartPoint property) and end (the EndPoint property) points. This element is used to create linear gauges.


Scale


A Scale element is a non-visual element that assigns the scale value range. The range is assigned with the help of Minimum and Maximum properties. Ticks, NumericLabels and TextLabels are included into the Scale element to visualize a scale.



Slider


A Slider element is a non-visual element that assigns the current value (the Value property) on the scale, in which this slider is included. The Slider handles mouse events in the following way: it synchronizes the Value property according to the current position of the mouse pointer and the geometry of the trajectory, in which it is included. As the Slider element is non-visual, it cannot directly get mouse events. Mouse events are passed to the Slider by the visual elements included in it. Thus, in order to make the Slider react to the mouse moves, it is necessary to include some visual element in it.

The MaxLimit and MinLimit assign value range and can process both absolute and relative values. The UseLimit property defines if the assigned range is used.
Various visual elements, included in the Slider and bound to it by an expression, can be used for visualizing current Slider value.

Group


A Group element is a non-visual element used to group other elements.


PushButton



A PushButton element is a non-visual element that is used to create buttons and checkboxes. This is an element of combined designation. All elements inside PushButton are the button body. It has the following properties: on, pressed, hot and the onClick event.

The On property displays Checked/Unchecked state. 
The Hot property: true – mouse pointer is over the button, false – mouse pointer is next to the button.
The Pressed property: true – mouse button is clicked inside the button and is hold, otherwise - false.


Label


A Label element is a visual element intended for text output.

 
The Text property assigns the output text. The rectangle, in which the text is displayed, is assigned by center (the Center property) and by size (the Size property). Text alignment relatively to the rectangle is assigned by the TextAlign property. The Font property assigns the text font. The Angle property assigns the figure rotation clockwise relatively to the center.

Custom Labels


A CustomLabels element represents text labels on the scale that are not bound to scale values.


 
Text labels as well as corresponding scale values are assigned in the Labels collection. Scale value can be assigned by both absolute value and relative value (in percentage from the scale range). Labels, which value is set to Auto, will be evenly distributed along the scale subject to the bench mark assigned by the Origin property. Shift form the Scale is assigned by the Distance property.

The Dock property defines relative position of the CustomLabels element subject to shifts assigned in the Padding property. The OddLabelDistance property sets shift of odd labels relative to even ones. Labels alignment relative to each other is assigned by the Position property. The TextAlingment property defines marks alignment relative to the corresponding scale value. Text angle is assigned by the Angle property, and text orientation is set in the TextRotationMode property. The ItemMargins property defines text shift from the label area margins. The ShowSuperposableLabels defines if the superposable labels will be displayed. If you need to display labels only in the specified range, use the MaxLimit and MinLimit properties assigning the range bounds. The UseLimit property indicates that limitation of element output will be executed. This element should be included in the scale.


Scale Labels


A ScaleLabels element represents numeric labels on the scale.


 
Values are displayed within the range, set in the scale, and step, defined by the Step property. If the Step property is set to Auto, divisions’ amount is set in the Divisions property. The origin property defines a benchmark. If the UseRoundValues is set to true, scale marks will be distributed along the scale in the way that the corresponding values contain minimal amount of fractional numbers; the number of divisions will be less or equal to the Divisions property value. When the element is drawn, these labels will be evenly distributed along the scale. Shift from the scale is assigned by the Distance property.

The Dock property defines relative position of the ScaleLabels subject to shifts, assigned in the Padding property. The OddLabelDistance property sets shift of the odd labels relative to even ones. Labels alignment relative to each other is set in the Position property. The TextAlignment property sets marks alignment relative to the corresponding scale value. Label angle is set by the Angle property, and label orientation is set in the TextRotationMode property. The ShowSuperposableLabels defines if the superposable labels will be displayed. The ItemsMargins property defines text shift from the Label area bounds. If you need to display Labels only within the assigned range, use the MaxLimit and MinLimit properties that set range bounds. The UseLimit property indicates that limitation of the element output will be applied. This element should be included in the scale.


Scale Title


A ScaleTitle element represents a scale title. 


Title text is defined in the Text property. Element position is set by the Origin property. The Dock property assigns relative position of the ScaleTitle subject to shifts set by the Padding property. The TextAlignment defines title alignment. Text angle is set by the Angle property, and text orientation is assigned by the TextRotationMode property.

Ticks


A Ticks element represents ticks on the scale.


Values are displayed within the range assigned in the scale and step defined by the Step property. The number of ticks is assigned by the Divisions property. The Origin property specifies the bench mark. If the UseRoundValues property is set to true, scale ticks will be distributed in the way that the corresponding values contain minimal amount of the fractional numbers; the number of divisions will be less or equal to the Divisions property value. The length of the tick is assigned by the Length property. The sub-ticks, which divide this range according to the SubDivisions property, are output between the ticks in the range. The length of the sub-ticks is assigned in the SubLength property. The positional relationship of the ticks and the sub-ticks can be assigned with the help of the SubTicksPosition property. When drawing the element, the ticks will be evenly spread on the whole scale. The indent from the scale is assigned with the help of the Distance property. The Dock property determines the Ticks element position subject to shifts set in the Padding property. If there is a necessity to output the ticks only in the assigned range, use MaxLimit and MinLimit properties that assign the range borders. The UseLimits property indicates that the limitation on element output will be applied. This element is included in the scale.


Scale Marks


A ScaleMarks element represents graphic markers on the scale.


Shape type is assigned by the Shape property. Values are displayed within the range set in the scale, and step is assigned in the Step property. If the Step property value is set to Auto, division amount is set in the Divisions property. The Origin property sets the benchmark. Marks size is assigned by the MarkSize property. Submarks are displayed within the range between marks, and divide this range according to the SubDivisions property. Submarks size is assigned by the SubMarkSize property.
Marks and Submarks relative position is set by the SubTicksPosition property. When the element is drawn, marks will be evenly distributed along the scale. Shift from the scale is set by the Distance property. The Dock property determines relative position of the marks subject to shifts set by the Padding property. Marks angle is assigned by the MarksAngle property. If you need to display marks only in the specified range, use MaxLimit and MinLimit properties, which assign range bounds. The UseLimit property indicates that limitation of the element output will be applied. The ScaleMarks element should be included in the scale.


Ranged Level

A RangedLevel element is intended for displaying intervals on the scale. 


The Value property assigns value the element will be displayed up to. The StartWidth and EndWidth property set width of the element at the beginning and at the end of the scale. If the Fill property is not set, the RangedLevel element will be painted with colors assigned by the Colors property. If the Colors property is not set, the element will be painted with colors set by StartColor and EndColor. The Divisions property determines divisions’ amount. The DivisionsStroke property assigns type of lines used to separate divisions. The AlignmentMode property assigns the way in which an element will be bound to the scale. If you need to display markers only within the specified range, use MaxLimit and MinLimit properties that set range bounds.

Linear Level

A LinearLevel element is intended for displaying intervals on the linear scale.


The Value property sets value the element will be displayed up to. The Divisions property determines divisions’ amount. The DivisionsStroke property assigns type of lines used to separate divisions. If the Fill property is not set, the RangedLevel element will be painted with colors assigned by the Colors property. If the Colors property is not set, the element will be painted with colors set by StartColor and EndColor.

The Width property determines element width. The StartCap and EndCap properties assign style of displaying element start and element end. Style of the whole element is determined by the Effect3D property. The ShowAsThermometer property determines if the element will be displayed as thermometer, i.e. there will be a circle with radius set by the PocketRadius property at the beginning of the scale. The Dock property determines a type of the element’s docking relatively to the scale.


Tank

A Tank element is a visual element, intended for emulating a tank, filled with liquid. The element is assigned by the Width property, determining tank width, the Depth property, assigning tank depth, and the TankWidth, determining width of the tank walls. The TankColor and LiquidColor set tank color and liquid color correspondingly. Style of the whole element is determined by the Effect3D property. The Dock property determines a type of the element docking to the scale.


Circle

A Circle element is a visual element representing the figure in the form of a circle. 


The circle is assigned with the help of center (the Center property) and radius (the Radius property).

Ellipse

An Ellipse element is a visual element representing the figure in the form of an ellipse.


It is assigned with the help of center (the Center property) and size (the Size property). The Angle property assigns figure rotation clockwise relatively to the center.

Rectangle

A Rectangle element is a visual element representing the figure in the form of a rectangle.


It is assigned with the help of center (the Center property) and size (the Size property). The Angle property assigns figure rotation clockwise relatively to the center.

Rounded Rectangle

A RoundedRectangle element is a visual element representing the figure in the form of a rectangle with the rounded corners. 


It is assigned with the help of center (the Center property) and size (the Size property). The smoothing radius is assigned by the Radius property. The Angle property assigns figure rotation clockwise relatively to the center.

Polygon

A Polygon element is a visual element representing a regular polygon inscribed in the circle with the center assigned by the Center property. 


A polygon size is assigned by the radius of a circle circumscribed round it (the Radius property). The number of polygon sides is assigned by the Side property. The Angle property assigns figure rotation clockwise relatively to the center.

Star

A Star element is a visual element representing the figure in the form of a star.  


The star position is assigned by the center (the Center property) and the radius of a circle circumscribed round it (the Radius property) and the radius of an inscribed circle (the InternalRadius property). The number of star sides is assigned by the Sides property. The Angle property assigns figure rotation clockwise relatively to the center.

Gear

A Gear element is intended for emulating gears. 


Element position is assigned by the Center and Radius properties, setting center coordinates and element’s radius. The Count property defines amount of the gear claws. The Depth property determines claws size. The DimensionsRatio defines relative claws width. 


Needle

A Needle element is a visual element representing the figure in the form of a needle. This element is intended for the current Slider value visualization. The StartPoint property assigns the start point of the needle. The EndPoint property assigns the end point of the needle. The needle base width is assigned by the StartWidth property and the needle tip width is assigned by the EndWidth property. To assign the complex geometry of the needle the NeedlePoints property is used. NeedlePoints is the collection of intermediate needle point’s descriptors. Each intermediate point descriptor is assigned by the needle width at a given point and the ratio between the distance from the needle base to a given point and the needle length. (See the figure below). The ShowMode property assigns the needle display mode.


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 Ribbon panel and click NeedleType to see the available templates.


Pie

A Pie element is a visual element representing the figure in the form of an ellipse sector.


An ellipse is assigned with the help of center (the Center property) and size (the Size property). A sector is assigned by the starting angle (the StartAngle property) and the total angle (SweepAngle property). The Angle property assigns figure rotation clockwise relatively to the center.


Ring Sector

A RingSector element is a visual element representing the figure in the form of an ellipse ring sector. 


An ellipse is assigned with the help of center (the Center property) and size (the Size property). A sector is assigned by the starting angle (the StartAngle property) and the total angle (the SweepAngle property). The ratio of the internal radius to the outer one is assigned by the InternalRadius property. The Angle property assigns figure rotation clockwise relatively to the center.

Highlight

A Highlight element is intended for emulating highlights on the circular instruments.


Element position is set by the Center and Radius properties assigning center coordinates and radius. The Angle and SweepAngle properties set element’s start angle and its angle of turn. 


Line

A Line element is a visual element representing the figure in the form of a line.


A line is assigned with the help of the StartPoint property and the EndPoint property.

Spring

A Spring element is a visual element representing the figure in the form of a spring.


A spring is assigned by the starting point (the StartPoint property). Spring width is assigned by the Amplitude property. The number of coils is assigned by the CoilCount property.

Arc

An Arc element is a visual element representing the figure in the form of an elliptical arc.


An ellipse is assigned with the help of center (the Center property) and size (the Size property). The Arc element is assigned by the starting angle (the StartAngle property) and the total angle (the SweepAngle property). The Angle property assigns figure rotation clockwise relatively to the center.

Circular Notches

A CircularNotches element creates the radial notches effect.


It is used to design gauge elements. The notches inside the circle are assigned by center (the Center property) and radius (the Radius property). The number of the notches is assigned by the Count property, their length is assigned by the Length property. Colors, assigned by DarkColor and LightColor properties, are used for drawing the notches. The Angle property assigns figure rotation clockwise relatively to the center.

Linear Notches

A LinearNotches element creates the linear notches effect. It is used to design gauge elements.


The notches are placed in parallel to the line assigned by the start and end points (the StartPoint and EndPoint properties). The distance between the extreme notches is assigned by the Width property. The number of the notches is assigned by the Count property. Colors assigned by DarkColor and LightColor properties are used to draw the notches.

Frame

A Frame element is a visual element in the form of a frame with the bevel.


The frame coordinates are assigned by center (the Center property) and size (the Size property). The bevel style is assigned by the BevelStyle property. DarkColor, LightColor, OuterColor, InnerColor properties assign the colors used to draw the bevel. The Angle property assigns figure rotation clockwise relatively to the center.

Picture

A Picture element is intended for the picture output. 


A picture is assigned by the Image property. Picture position and size are assigned by the Center and Size properties. The Angle property assigns figure rotation clockwise relatively to the center.

Picture Set

A PictureSet element is intended for the output of one picture from the assigned pictures set. Picture collection is assigned by the Image property. The number of output pictures is assigned by the ImageIndex property. Picture position and size are assigned by the Center and Size properties. The Angle property assigns figure rotation clockwise relatively to the center.


Digits

A Digits element is intended for emulation of a digital indicator. 


It is used to output digital values. The text, displayed in the indicator, is assigned by the Text property. The following symbols are allowed: numbers (0-9), “point”, “dash”, “colon”, “space”. The position and size are assigned by the Center and Size properties. The Angle property assigns figure rotation clockwise relatively to the center. The indicator number is displayed by the figures, consisting of segments. Segments thickness is assigned by the SegmentThickness property. The interval between the segments is assigned by the SegmentSpace property. The Symbol width is assigned by the DigitWidth property, height is assigned by DigitHeight property, the space between the figures is assigned by the DigitSpace property. The color of figures active segments is assigned by the ActiveColor property, the color of inactive segments is assigned by the InactiveColor property.

Odometer

An Odometer element is intended for emulation of a mechanical meter.


It is used to output numeric value. The output number is assigned by the Value property. The position and size are assigned by the Center and Size properties. The Angle property assigns figure rotation clockwise relatively to the center. The font of displayed figures is assigned by the Font property. The assigned value is output on different meter disks. The disk color, in which the number last rank is displayed, is assigned by the FirstDigitBackFill property; the figure color, output on this disk, is assigned by the FirstDigitForeFill property. The color of other disks is assigned by the BackFill property; color of the symbols that are output on them is assigned by the ForeFill property.

Digital Text

A DigitalText element is intended for displaying the text. 


The text, displayed in the indicator, is assigned by the Text property. The position and size are assigned by the Center and Size properties. The Angle property assigns figure rotation clockwise relatively to the center. The indicator text is displayed in figures that consist of rectangle segments. Color of figures active segments is assigned by the ActiveColor property, color of inactive segments is assigned by the InactiveColor property. The segments vertical and horizontal weight is assigned by the SegmentSize property. Space between the segments is assigned by the SegmentSpaces property. Text offset relatively to the left element boundary is assigned by the TextHorizontalOffset property. Text offset relatively to the top boundary is assigned by the TextVerticalOffset. Besides that, you can specify font with the help of the Font property. 

Expressions

Destination and General Principles of the Expressions Use

Expressions can be used for an instrument and all its elements. An expression, which calculation result will be bound to the property, can be assigned to the majority of instrument properties. The expressions are used to provide elements interaction and to assign the required instrument functionality.
The order of expressions calculation is as follows. If the element state is changed, the recalculation of the expressions of this element as well as of all elements included in it occurs. The expression calculation result is assigned to the appropriate element properties.
In order to have all expressions of the instrument values recalculated when the element state is altered, it is necessary to set the RecalculateAll property to true. The alteration of some properties, assigning element appearance, doesn’t invoke recalculation of the expressions. For example, the alteration of such properties as Fill and Stroke doesn’t invoke recalculation of the expressions; therefore there is no need to apply to the values of such properties.
If the expression contains syntax, semantic errors, or the exception appears in the calculation process, the expression will be ignored.

Expressions Window for the Circle element:


Expression Editor:


Description of Expression Language Syntax and Semantics 

An expression is a task on formula calculation. The expression value is a result of its calculation. The expression is built out of constants, objects and their properties and methods, operators, function callings and round brackets.
Data types used:
All data types, available in .NET framework, are used in the expressions. Also there is a special support for integer-valued, fractional, logical values, strings and vectors.
The PerpetuumSoft.Framework.Drawing.Vector data type is used for vectors.
The following operations are available in expressions:

Arithmetic operations

‘+’ – addition. It is defined for numerical values and vectors.
‘-’ – subtraction. It is defined for numerical values and vectors.
‘-’ – unary minus. It is defined for numerical values.
‘*’ – multiplication. Numerical values and vectors can be the first argument; the numerical value should be the second argument.
‘/’ – division. It is defined for numerical values.
‘%’ – residue of division. It is defined for numerical values.

Logical operations

‘or’ – logical OR. It is defined for logical values;
‘and’ – logical AND. It is defined for logical values;
‘=’ – equals. It is defined for numerical, logical values and vectors;
‘! =’ – inequality. It is defined for numerical, logical values and vectors;
‘<’ – less. It is defined for numerical values;
‘<=’ – less or equal. It is defined for numerical values.
‘>’ – more. It is defined for numerical values.
‘>=’ – more or equal. It is defined for numerical values.
‘not’ – logical negation. It is defined for logical values.

String Operations

‘&’ – strings concatenation. It is defined for string values.
The descending priority operations order.
 ‘–’(unary), ‘not’
‘*’, ‘/’, ‘%’
‘+’, ‘–’, ‘&’
‘>’, ‘>=’, ‘<’, ‘<=’
‘=’, ‘!–’
‘and’
‘or’

Constants assigning

<decimal figure>* - the whole value.
<decimal figure>*.<decimal figure>* - value.
For example, 1234 is the whole, 1234.1234 is the fractional value.
For assigning the linear size in generally accepted units the appropriate postfixes at the end of numerical constant are used.
“in” – value in inches
“mm” – value in millimeters
“cm” – value in centimeters
“pt” – value in 1/72 inch points
“px” – value in pixels
For example 3in is 3 inches, 3cm is 3 centimeters.
String constants are assigned with the help of double apostrophes.
For example: “It is a string value”.
The vector is assigned with the help of “[” and “]”.
[<numerical value>,< numerical value>] – vector assignment.
Logical constants are assigned with the help of two key words: ‘true’ and ‘false’.

Access to variables, objects, their fields and methods.

In the expressions, you can apply to variables, available in the instrument, by their names. The search of variables and objects by their names is executed in the following way: if an address by the object’s name is available in an expression, the GetObject function that should get the desired object is called for the element the given expression is written for. For any element the GetObject function makes the following: the function gets the element itself, in case its name corresponds to the requested one, otherwise it calls GetObject from the parent. Elements-containers execute the search of the desired object through all included elements. Thus, all instrument elements are available in the expressions. For some elements (for example, for the Slider) the Get Object function gets special variables. According to the rule stated above such variables will be available for both element-container and elements included in it. The instrument structure is represented in the picture:


You can refer to the instrument elements (Instrument, Joint1, Scale1, NumericLabels1, Ticks1, Slider1, Needle1) in any element expressions.
Special Slider variables are available in the Slider1 and Needle1 elements expressions.

Special variables

The following special variables are available in the SliderBase element descendants (e.g., the Slider element):

value – the double type variable. The current Slider value.
hot – the logical type variable. Hot is set to true if the mouse pointer hovers over an element.
pressed – the logical type variable. Pressed is set to true if the mouse button is pressed when the pointer is placed over an element.
center – the vector type variable. The point that corresponds to the current Slider value and is distant from the trajectory center at 0 distance.

The following special variables are available in the Joint element descendants (e.g., the Joint element): 

JointRadius - radius of a Joint.
JointCenter – the vector type variable. The point that corresponds to the current Joint value and is distant from the trajectory center at 0 distance. 
JointTotalAngle - total angle of a Joint.
JointStartAngle - the angle of degrees measured clockwise from the X-axis to the start point of a Joint. 
The following special variables are available in the Guide element descendants (e.g., the Guide element): 
GuideLength - length of a Guide.
GuideCenter - center point of a Guide.
GuideEndPoint - end point of a Guide.
GuideStartPoint - start point of a Guide.

To refer to to objects’ fields and methods the point ‘.’ is used.
 
For example:

Slider1.Value – reference to the Value property of the Slider1 element.
Slider1.ToString() – call of ToString() method of the Slider1 element.
Line1.StartPoint.Rotate(30) –call of the Rotate method of Line1.StartPoint property.
[10, 20].Rotate(30).X – X vector coordination [20, 30], rotated on 30 degrees
 
As the expression language is not typed, it is impossible to define what method should be invoked.
In the expressions, you can refer to the functions available in the instrument by their names. The search is executed similarly to the objects search by the names.

The following functions are available for any elements:

The functions of conditional choice:

if (condition, value1, value2), the 1st parameter should be of logical type; the 2nd  and the 3rd parameters should be of object type. If the 1st parameter is true, the function returns the 2nd parameter value, otherwise it returns the 3rd parameter value.
switch (condition[0], value[0], … , value by default), if the condition[i] is set to true, the function gets the value[i], if the condition[i] in any i is false, the value gets by default. 

Formatting Functions

format (object, mask), the object is of object type, the mask is of string type. It gets the object’s string presentation according to the mask.

Mathematical Functions

sin(argument) – calculates the argument sine. The argument is of double type, the calculation result is of double type.
cos(argument) – calculates the argument cosine. The argument is of double type, the calculation result is of double type.
tan(argument) – calculates the argument tangent. The argument is of double type, the calculation result is of double type.
atan(argument) – calculates the argument arctangent. The argument is of double type, the calculation result is of double type.
sqr(argument) – calculates the argument to square. The argument is of double type, the calculation result is of double type.
sqrt(argument) – calculates the argument’s square root. The argument is of double type, the calculation result is of double type.
log(argument) – calculates the argument’s natural logarithm. The argument is of double type, the calculation result is of double type.
exp(argument) – raise E number to the argument degree. The argument is of double type, the calculation result is of double type.
sign(argument) – gets:-1 if the argument is negative, 0 – if the argument is 0, 1 – if the argument is positive. The argument is of double type, the calculation result is of int type.
abs(argument) – gets the argument’s absolute value. The argument is of double type, the calculation result is of double type.
round(argument1, argument2) – rounds the 1st argument value to the symbols amount after the comma, assigned by the 2nd argument. The 1st argument is of double type, the 2nd argument is of int type, the calculation result is of double type.
The expression can be an argument of any function and method. If the expression calculation result doesn’t correspond to the argument type, the expression will not be calculated.

Date Processing Functions

getMonth (argument) – gets the month string name by the date assigned in an argument. An argument should be of System.DateTime type;
getDayOfWeek (argument) – gets the string name of the day of week by the date assigned in an argument. An argument should be of System.DateTime type;
getQuarter (argument) – gets the quarter number of a date specified as an argument. An argument should be of System.DateTime type;
Other properties and methods of System.DateTime type can also be used to get other date values.

Range function

Range (currentValue, range, zeroPoint) – extracts data intervals. All arguments should be of numeric type. currentValue – the current value; range – the range; zeroPoint – the zero point.
In the expression language, the construction for creation of objects  of PerpetuumSoft.Framework.Vector type is provided. A vector is created with the help of the following construction:
[<expression>, <expression>]. The creation of objects of other types directly in the expression is impossible. But it is possible to implement custom functions, used in the expressions for the creation of objects of desired type.
For the SliderBase type elements (for example, the Slider) and for the elements included in it, the following special functions are available:
r(radius) – gets the point that corresponds to the current Slider value and distant from the trajectory center (in which the Slider is included) at a radius distance.
r(value, radius) – gets the point that corresponds to the value and distant from the trajectory center (in which the Slider is included) at a radius distance.
a() – gets the Slider’s rotation angle.

Implementation of custom functions and variables, available in the expressions.

In order to make custom functions and variables available in the element expressions, it is necessary to implement a custom element, which will correspondingly implement the PerpetuumSoft.Framework.Expressions.IExpressionSite interface. 
After that you need to register your function. It can be done in the following way:
PerpetuumSoft.Framework.Expressions.BuiltInFunctions.RegisterFunction(<Function name>, <inplemented IFunction object>);

Use and Capabilities of the Instrument Designer

The Designer is used to create instruments. Its appearance is shown on the picture below. An instrument represents an object to which different elements are added. Each element has a set of properties displayed on the Property Grid panel. You can edit property values in this window. Most of properties can be bound to the expressions, assigned by the special expression language. The expressions are displayed on the Bindings expressions panel. You can edit expressions in this window.


1 – Ribbon Toolbar;
2 – Elements Toolbox;
3 – Instrument Tree panel;
4 – Work Area;
5 – Property Grid panel;
6 – Bindings Expression panel.

Visual and non-visual elements used to create an instrument are available via the Insert menu or via the buttons on the Elements Toolbox. In order to add an element to the instrument it is necessary to select it from the menu in the Elements Toolbox. Then click on the Work Area, or stretch the element to the desired size by pressing and holding the left mouse button.
The instrument structure is displayed on the Instrument Tree panel. You can change elements positional relationship by dragging them in the tree with the mouse.
Let’s review the functions available via the File menu. The commands for file operations are grouped here.
File\New menu item (the  menu button) – allows the creation of a new empty instrument.
File\Template Wizard menu item (the  menu button) – allows the creation of a new instrument with the help of Wizard.
File\Open Ctrl+O menu item (the  toolbar button) – calls the dialog for loading the instrument from the file.
File\Save Ctrl+S menu item (the  toolbar button) saves the instrument.
File\Save As menu item is used for saving the instrument with a new name.
File\Export menu item exports an instrument into one of popular bitmapped or vector graphics formats (JPEG, GIF, PNG, BMP, SVG and Macromedia Flash) and calls the save to file dialog box. It is also possible to export the instrument as JSON representation either to a file or a clipboard.
You can view the recent files history including the system file paths on the right of the separator.
Let’s review the functions available via Home ribbon tab. The commands for the instrument editing are grouped here.
Paste Ctrl+V menu item (the   toolbar button) means the elements pasting from the buffer to the selected element or its parent, if the selected element is not a container.
Copy Ctrl+C menu item (the  toolbar button) means the copying of the selected elements.
Cut Ctrl+X menu item (the   toolbar button) means copying and deleting the selected elements.
Delete Ctrl+Del menu item (the   toolbar button) is intended for deleting of the selected elements.
Fill menu item (the   toolbar button) is used for filling a selected element with color.
Stroke menu item (the  toolbar button) is used for applying a stroke or an outline to a selected element. The Stroke drop-down menu consists of the following elements:
   Line Color is used for setting a stroke color
   Line Width is used for setting the stroke line width
   Line Style is used for setting a stroke line style
   Custom Stroke is used for creating a custom stroke pattern

Colorizer menu item (the  toolbar button) is used for coloring multiple scale elements and can set a color style for particular sectors of such elements. The following options are available: None, Single Color, Custom Color.
Select F2 menu item (the  toolbar button) is used to switch to the Select tool. The Select tool allows selecting the elements in the Work area and editing the elements via their designers.
Pan F4 menu item (the  toolbar button) is used to pan the picture of the Work area.
Test F3 menu item (the   toolbar button) allows switching to the Test tool, used to test the created instrument.
Copy JSON to clipboard menu item (the toolbar button) allows copying the instrument code represented as JSON (JavaScript Object Notation) to clipboard.
Zoom in menu item (the  toolbar button) is used to zoom an element in.
Zoom out menu item (the    toolbar button) is used to zoom an element out.
Move selected objects to forward item (the   toolbar button) raises the selected elements up one position.
Move selected objects to back item (the  toolbar button) lowers the selected elements down one position.
Send selected objects to forward item (the  toolbar button) raises the selected elements to the top.
Send selected objects to back item (the  toolbar button) lowers the selected elements to the bottom.
Note: If the selected elements group position is changed, the relational order inside the group is kept.
Let’s review the functions available via the View tab. The commands that manage designer appearance are grouped here.
View\Show rulers menu item (the  toolbar button) enables/disables the rulers in the Work area.
View\Show grid menu item (the  toolbar button) enables/disables the grid in the Work area.
View\Snap to grid menu item (the   toolbar button) enables/disables the snap of elements’ control points to the grid.
View\Actual Size menu item (the  toolbar button) resets the instrument size to its initial value.
View\Region zoom menu item (the  toolbar button) switches to the Region zoom tool to zoom a selected section (region) in.
View\Dynamic zoom menu item (the  toolbar button) switches to the Dynamic zoom tool to change zoom of a selected section (region).
Let’s review the functions available via the Insert menu. The commands used for adding different elements to the instrument are grouped here. The commands are divided into groups depending on the element destination.
Elements, grouped in the Insert\Structure menu section, are intended to assign the instrument structure.
Insert\Structure\Joint menu item (the  button on the toolbox) adds the circular trajectory (Joint element).
Insert\Structure\Guide menu item (the   button on the toolbox) adds the linear trajectory (Guide element).
Insert\Structure\Scale menu item (the  button on the toolbox) adds a scale (Scale element).
Insert\Structure\Slider menu item (the  button on the toolbox) adds a slider (Slider element).
Insert\Structure\Push button menu item (the  button on the toolbox) adds a button element able to create buttons and checkboxes.
Insert\Structure\Group menu item (the  button on the toolbox) adds a container (Group element), that groups the elements.
Insert\Primitives menu section contains the commands of adding the basic primitives, such as geometrical figures and others.
Insert\Primitives\Linear menu item (the   button) adds a linear element. This menu consists of the following items:

   Line adds a line element.
    Spring adds an element in the form of a spring.
    Arc adds an element in the form of an arc.

Insert\Primitives\Shape menu item (the   button) adds elements with different shapes. It consists of the following items
   Primitives\Circle menu item adds a circular form element.
   Primitives\Ellipse menu item adds an elliptical form element.
   Primitives\Rectangle menu item adds a rectangle form element.
   Primitives\RoundedRectangle menu item adds a rounded rectangle form element. 
   Polygonal\Polygon menu item adds a regular polygon element.
   Polygonal\Star menu item adds a figure in the form of a star.
   Polygonal\Gear menu item inserts the element in the form of a gear.
   Polygonal\Needle menu item adds a pointer in the form of a needle.
   Sectors\Pie menu item adds a pie form element. 
   Sectors\RingSector menu item adds a ring sector element.
   Sectors\TruncatedEllipse menu item adds an element in the form of a truncated ellipse.
   Sectors\Highlight menu item inserts the highlight element.

Insert\Scale Elements menu section contains the commands for adding the elements intended for the scale design.

     Scale Elements\ScaleLabels menu item inserts an element that serves for numbering scale divisions.
     Scale Elements\ScaleTitle menu item inserts a scale title.
   Scale Elements\ScaleMarks menu item adds graphic markers to a scale.
   Scale Elements\CustomLabels menu item adds text labels to a scale.
     Scale Elements\Ticks menu item adds ticks to a scale. 
     Scale Elements\RangedLevel menu item inserts a RangedLevel element.
       Scale Elements\LinearLevel menu item inserts a LinearLevel element.
     Scale Elements\Tank menu item inserts a Tank element.
    Scale Elements\CircularNotches menu item adds a circular notches element.
    Scale Elements\LinearNotches menu item adds a linear notches element.

Insert\Objects menu section contains the commands for adding the elements with a specific destination.

       Objects\Picture menu item adds a picture element.
      Objects\Label menu item adds text inscriptions.
        Objects\Digits menu item adds a digital indicator (a Digits element).
       Objects\Digital Text menu item adds a digital text element.
       Objects\Odometer menu item adds an element emulating odometer (the Odometer element).
         Objects\Frame menu item adds a rectangle element with a bevel (the Frame element).
        Objects\PictureSet menu item adds a picture set (the PictureSet element).

   Let’s review the functions available via Properties menu. The commands that set the most frequently used properties are grouped here. 

     Visible (toggles on/off the visibility of the element).
       Active (indicates whether the events are passed to the element).
      Smooth (indicates whether antialiasing is used for the element).
    Start point (sets the start point for the linear element). The value is specified in pixels.
    End point (sets the end point for the linear element). The value is specified in pixels.
    Center (sets center of the element).The value is specified in pixels.
    Size (sets element size). The value is specified in pixels.
    Radius (sets radius of the element). The value is specified in pixels.

Other miscellaneous functions

The Undo button  in the left upper corner of the title bar is used to undo the action.

Let’s consider the use of the Select tool in the Work Area.

In the Select tool mode, any visual element can be selected in the Work Area with a mouse. It is possible to select a group of elements either by means of selecting each element while holding the Ctrl key pressed or by means of “lassoing” the group of elements holding the left mouse button pressed. Control points in the form of circles are displayed in the selected elements.The selected elements are highlighted in the Instrument Tree.

The edit operations are applicable to the selected elements:

copy to clipboard (Clipboard);
paste from the clipboard;
delete;
change output order;
change properties in Properties Window;
change the element position with the help of the mouse;
change some element’s properties by moving the element control points.

Control points of the selected element are intended to change its main properties. The point position can be changed by dragging it with the mouse.
Each element has its own control points set. For example, the rectangular elements have ten points, one of which is intended for changing of the rectangle center, another one is for changing of rotation angle, and the rest of them are intended for changing of the corresponding size of the rectangle.
Some elements have the control points able to change specific properties typical only for the elements of a certain type. For example, the RingSector.
When the control point position is changed, the appropriate element property also changes. But if the expression is assigned for this property, it makes no sense to change the control point position. Such control points are highlighted with red color. If it’s possible to automatically change the expression that is bound to the property which changes the control point, such point is highlighted with yellow color.
If the element is included in a Slider to indicate the current value, it is possible to bind the element position to the current Slider value. To do so, it is necessary to click on the control point, keeping pressed the Ctrl key. The expression binding is canceled by the similar action.
The Instrument Tree panel displays current structure of the instrument as a tree. When an element is added to the Work Area it is automatically displayed in the Instrument Tree panel. The selected elements are highlighted in the tree with blue color. In this window, it is possible to change the elements positional relationship by dragging them with the mouse.
The Expressions window is intended for editing expressions, bound to the appropriate element properties., The properties available for setting an expression are displayed in the left column. In the right column, you can write an expression script or run the script editor. If a script is not assigned for some property, the white blank rectangle is displayed in the right column. If a script is assigned correctly, the rectangle displays a blue checkmark. If an assigned script contains syntactical errors, the rectangle displays a red cross.
The Properties window displays properties of the selected object and allows developers to edit them.

Technology of the Instrument Design

Designing a Simple Instrument with a Slider

Let’s see how to use the instrument designer to design instruments.

Creating an instrument with a slider.

Let’s determine our requirements to the designed instrument.
1. The instrument should contain a slider moving on the scale within the limited range from 0 to 100.
2. Ticks on the scale should be designed in different colors within the following ranges: [0-80) and [80-100).
3. When the slider exceeds the 80 mark it should change the color.
4. When the mouse is on the slider, the current value should be displayed alongside as text.
5. The instrument should contain a slider moving on the scale within the limited range from 0 to 100.
To begin with, add the linear trajectory to the instrument. The trajectory is intended to assign the scale shape. After that, add the Scale element to the instrument. The scale assigns value range. 
To visualize the scale element you should mark it by ticks and text Labels. So add the Ticks and ScaleLabels elements from the Element toolbox to the Scale1 element. 

The Instrument itself.



Let’s set the Distance property for the Ticks1 to 10. Let’s set the Distance property for the NumericLabels to 20. 


Add the Slider element (  ) to the instrument. The element is intended to represent the current value and its change with the help of mouse, in. The instrument structure is as follows.


To visualize the slider you should add the Needle element (  ) into the Slider1.



Let’s bind Needle1 to the slider value. To do it you should write the following in the Needle1 expressions:
“r(0px)” expression for the StartPoint and "r(-50px)" expression for the EndPoint.
Now the slider is able to move with the mouse.


2. Ticks on the scale should be designed in different colors within the following ranges: [0-80) and [80-100).
Edit the Colorizer property for the Scale1 element using the Colorizer Editor.


After all changes the instrument should have the following look.


3. When the slider exceeds the 80 mark it should change the color.
Add two styles in the instrument styles collection (InstrumentStyles): ColdColor style with blue fill and HotColor style with red fill. 


Write the following expression for the Style property of the Needle1 element: if (Slider1.Value < 80, "ColdColor", "HotColor").


The current value is < 80.


The current value is > 80.

4. When the mouse is on the slider, the current value should be displayed alongside as text.
Add the Label element (   ) to the Slider1 element.


Let’s set the BreakEvenBubbling property of the Label1 element to True. This prevents mouse events from being passed from Label1 to Slider1.
Let’s write the following expressions for the Label1 element:
Write "r(-38px) + [120, 20]" expression for the Center. Label1 center will be set depending on the slider value and will be shifted on some distance.
Write "format(value, "0.00")" for the Text. The Label1 element will display the slider current value formatted according to the mask.
Set Visible to “hot”. The Label1 element will be viewed only when mouse is on the Needle1. 


Creating Instruments Using Complex Expressions

Let’s create an instrument, in which the slider will move within a plane.
Firstly, let us define requirements to the instrument.
1. The instrument should comprise two datum lines.
2. The slider should move within a plane.
3. It is necessary to display slider center projection on each of the datum lines.
4. The text showing slider position on the plane should be displayed next to the slider.
1. The instrument should comprise two datum lines.
Let’s add the Guide trajectory (  ) to the instrument. The trajectory is intended to assign the scale form.
Let’s add the Scale element (  ) to the instrument. The Scale assigns values range. In order to make the Scale lie along the trajectory, it is necessary to place it into the trajectory (simply drag-and-drop it onto the form and select the Guide as a parent container in the opened window). 
Let’s add the Slider element (  ).It is intended to represent the current value and its change with a mouse.
To visualize a scale, let us add the ticks and text marks to it. To do that, we should add the Ticks and NumericLabels elements from the Element toolbox to the Scale1 element. After that, the element structure should appear as follows.


The Instrument itself.


Set the Ticks1 Distance property to 10. Set the NumericLabels1 Distance property to 20.


To visualize the slider, add the Needle element (  ) to the Slider1 element.


Let’s set the Needle1 element Stroke property to SimpleStroke.
And now bind the Needle1 element to the slider value. In the expression window for Needle1 write the following: “r(1.3cm)” for StartPoint and “r(0.8cm)” for EndPoint.
Now the slider should be capable of moving when you manipulate it with a mouse.


As a result we shall get the OX axis.
Let us repeat the above mentioned actions for assigning the other linear trajectory, its scale and slider. We shall get the OY axis. Then the element structure should appear as it is shown below. 



The Instrument itself.


2. The slider should move within a plane.
Let us create a slider common for OX and OY axes. To do that, we shall add the Rectangle element (  ) to Slider2. Set the Stroke property of the Rectangle element to SimpleStroke. At the same time we shall add the Guide2 element to Slider1. After we do that, the element structure will be changed as follows.


Now let us write the following expression for the Rectangle.Center property “[Slider1.GetPosition(0).X,  Slider2.GetPosition(0).Y]” The Slider GetPosition function gets the point which corresponds to the value assigned by the argument.
Now the values of Slider1 and Slider2 will vary when the Rectangle1 element is moved by the mouse.


3. It is necessary to display the slider center projection on each of the datum lines.
Add the Line1 element (  ) to Slider1. We shall set the Line1 Stroke element to SimpleStroke and choose red line color in the Stroke properties. For the Line1 element, we shall use the following expressions:
“r(0.42cm)” for StartPoint; and “r(-5.93cm)” for EndPoint. 
We shall get the OX axis projection.
Add the Line2 element (  ) to Slider2. We shall set the Line1 Stroke element to SimpleStroke and choose blue line color in the Stroke properties. For the Line2 element, we shall use the following expressions:
“r(7.2cm)” for StartPoint; and “r(-0.42cm)” for EndPoint. 
We shall get the OY axis projection.
As a result the element structure will take the following look.


The Instrument will look as follows:


4. The text showing slider position on the plane should be displayed next to the slider..
Let’s create the Label element (  ) within the Slider2 element.


Set green color as a fill color in the Label1. Fill property. For the Label1 element, we shall use the following expressions:
“[Slider1.GetPosition(0).X,  Slider2.GetPosition(0).Y] + [35px, -15px]” for Center; and
" "(" & format(Slider2.Value, "00.0") & "; " &  format(Slider1.Value, "00.0") & ")" ” for Text.


You can find the instrument we finally got named Gauge 2D 1 in Widgets template collection of Instrument designer.

Appendix 1 Working with the Expression Editor

Expression editor appearance is displayed in the image below.


Classic operators and expression language functions are located by categories in the TreeView elements on the Operators and Functions tabs. The TreeView located on the right of the window contains available data source fields subject to their hierarchical level. Any construction described in either Tree can be moved to the text entry field by drag-and-drop. Double click on the tree element will paste the construction into the current position of the entry field. After the entry is complete it is required to click the “OK” button to confirm modifications or the “Cancel” button to cancel modifications. If the “OK” button is pressed, syntax checking is executed before the window is closed.

Also you can create your own functions which will be displayed and dragged as the other ones. You can calculate values that you need by the specified parameters. It is necessary to create a class that implements   PerpetuumSoft.Framework.Expressions.ICustomFunction interface. After that you should register PerpetuumSoft.Framework.Expressions.BuiltInFunctions in the static class in the following way: 
PerpetuumSoft.Framework.Expressions.BuiltInFunctions.RegisterFunction("Custom function", new CustomFunction());

The expression editor has a button panel.
The “Save” button (  ) allows saving expression text to a file.
The “Open” button (  ) allows reading expression text from a file.
The “Check expression” button (  ) allows checking syntax. In case a syntax error is found a corresponding warning specifying the initial position of the erroneous construction is displayed.

Add Feedback