ComponentOne. LinearGauge for ASP.NET Wijmo

Transcription

1 ComponentOne LinearGauge for ASP.NET Wijmo

2 Copyright GrapeCity, Inc. All rights reserved. ComponentOne, a division of GrapeCity 201 South Highland Avenue, Third Floor Pittsburgh, PA USA Internet: info@componentone.com Web site: Sales sales@componentone.com Telephone: or (Pittsburgh, PA USA Office) Trademarks The ComponentOne product name is a trademark and ComponentOne is a registered trademark of GrapeCity, Inc. All other trademarks used herein are the properties of their respective owners. Warranty ComponentOne warrants that the original CD (or diskettes) are free from defects in material and workmanship, assuming normal use, for a period of 90 days from the date of purchase. If a defect occurs during this time, you may return the defective CD (or disk) to ComponentOne, along with a dated proof of purchase, and ComponentOne will replace it at no charge. After 90 days, you can obtain a replacement for a defective CD (or disk) by sending it and a check for $25 (to cover postage and handling) to ComponentOne. Except for the express warranty of the original CD (or disks) set forth here, ComponentOne makes no other warranties, express or implied. Every attempt has been made to ensure that the information contained in this manual is correct as of the time it was written. We are not responsible for any errors or omissions. ComponentOne s liability is limited to the amount you paid for the product. ComponentOne is not liable for any special, consequential, or other damages for any reason. Copying and Distribution While you are welcome to make backup copies of the software for your own use and protection, you are not permitted to make copies for the use of anyone else. We put a lot of time and effort into creating this product, and we appreciate your support in seeing that it is used by licensed users only. This manual was produced using ComponentOne Doc-To-Help.

3 Table of Contents ComponentOne LinearGauge for ASP.NET Wijmo Overview...1 Help with ComponentOne Studio for ASP.NET Wijmo... 1 Key Features...1 LinearGauge for ASP.NET Wijmo Quick Start...3 Step 1 of 3: Adding C1LinearGauge to the Page... 3 Step 2 of 3: Customizing C1LinearGauge's Appearance... 4 Step 3 of 3: Customizing C1LinearGauge's Behavior... 5 Wijmo Top Tips...7 Working with C1LinearGauge...7 Why Use Gauge Controls?... 8 C1LinearGauge Values... 8 C1LinearGauge Orientation... 8 C1LinearGauge Indicators... 9 C1LinearGauge Pointer C1LinearGauge Face and Cover LinearGauge for ASP.NET Wijmo Samples LinearGauge for ASP.NET Wijmo Task-Based Help Creating a C1LinearGauge in Code Resizing the Control Setting the Start Value Setting the Minimum and Maximum Values LinearGauge for ASP.NET Wijmo Client-Side Reference iii

4

5 ComponentOne LinearGauge for ASP.NET Wijmo Overview ComponentOne LinearGauge for ASP.NET Wijmo lets you easily display information in a dynamic, unique manner. ComponentOne LinearGauge for ASP.NET Wijmo includes one control, C1LinearGauge. For a list of the latest features added to ComponentOne Studio for ASP.NET Wijmo, visit What's New in Studio for ASP.NET Wijmo. Getting Started Get started with the following topics: - Key Features - Quick Start - Samples Help with ComponentOne Studio for ASP.NET Wijmo Getting Started For information on installing ComponentOne Studio for ASP.NET Wijmo, licensing, technical support, namespaces and creating a project with the control, please visit Getting Started with Studio for ASP.NET Wijmo. What's New For a list of the latest features added to ComponentOne Studio for ASP.NET Wijmo, visit What's New in Studio for ASP.NET Wijmo. Key Features C1LinearGauge includes several unique features, including the following: Styling Made Easy All gauge elements can be customized to fit your needs. Restyling the ComponentOne Gauge controls is as simple as changing a property. All of the key elements in the gauge are surfaced. You can create gauges with custom colors, fills, fonts, and more. Ranges Add colored ranges to the gauge to draw attention to a certain range of values. Use simple properties to customize their start and end points, as well as location, size, and appearance. Create non-linear ranges by specifying a start and end width to show growth and add visual appeal to any gauge. Tick Marks and Labels Define marks and labels. Use simple properties to customize their interval, location, and appearance. Apply formatting to the gauge labels; for example, format labels in currency or percentage format using standard.net format strings. Orientation You can place the linear gauge horizontally or vertically on the page with the Orientation property. Rich Customization 1

6 Create any look desired by customizing the face and cover shapes of the gauge using the rich set of style attributes available. You can even simulate a glassing effect using simple shapes. If shapes are not enough, you may add images. It's possible to apply various effects to images, such as rotation, flipping, changing the hue, saturation, lightness, and opacity. Scale Customization Use simple properties to set the start and sweep angle of the gauge scale. Pointer Customization Choose from many predefined pointer shapes, customize the shape, or import your own custom image to use as the pointer. Specify the exact position of the pointer origin in radial and linear gauges. This allows you to decentralize the pointer to either side or the bottom of the gauge. Animation Gauges come out-of-the-box with smooth animations. You can customize the animations. For example, for the pointer animation, you may set the time interval for the animation as the value changes. You can also decrease the frequency of redrawing for the gauge control if the source value is changed too frequently for observation. Live Data Gauges are optimized for streaming live data. The gauge will animate as the data changes. Logarithmic Markers With the Islogarithmic and LogarithmicBase properties, you can get the logarithmic markers. 2

7 LinearGauge for ASP.NET Wijmo Quick Start In this quick start you'll explore the functionality of the C1LinearGauge control. C1LinearGauge provides the ability to display data in a unique view. Step 1 of 3: Adding C1LinearGauge to the Page In this step you'll create and set up a Web site and add an empty C1LinearGauge control. Complete the following steps to add the C1LinearGauge control to a Web site: 1. From the Visual Studio File menu select New Project. The New Project dialog box will appear. 2. In the New Project dialog box expand a language in the left-hand pane and select Web. In the right pane, choose ASP.NET Empty Web Application, enter a Name for your application, and select OK. A new application will be created. 3. In the Solution Explorer, right-click the project and choose Add Reference. 4. In the Add Reference dialog box, locate and select the C1.Web.Wijmo.Controls and C1.Web.Wijmo.Controls.Design assemblies and click OK. The references will be added. 5. Right-click the project in the Solution Explorer and from the context menu choose Add New Item. 6. In the Add New Item dialog box choose Web Form from the list of templates, name the item "Default.aspx", and click Add. The new page should open. 7. In Source view, add the following markup at the top of the page to register the C1LinearGauge assembly: <%@ Register Assembly="C1.Web.Wijmo.Controls.4" Namespace="C1.Web.Wijmo.Controls.C1LinearGauge" TagPrefix="wijmo" %> Depending on the assembly added, you may need to replace "C1.Web.Wijmo.Controls.4" with "C1.Web.Wijmo.Controls.3" above. 8. Place your mouse between the page's initial <div></div> tags, and add the following markup to add the C1LinearGauge control to the page: <wijmo:c1lineargauge ID="C1LinearGauge1" runat="server"></wijmo:c1lineargauge> 9. Run your application, and observe that the page now looks similar to the following image: In this step you added a C1LinearGauge control to the form, but the control is currently I unformatted. In the next step of the quick start, you'll add content to the control. 3

8 Step 2 of 3: Customizing C1LinearGauge's Appearance In this step you'll customize the appearance of the C1LinearGauge control. The following steps assume you've completed Step 1 of 3: Adding C1LinearGauge to the Page topic and added a C1LinearGauge control to the page. Complete the following steps to customize the C1LinearGauge control: 1. In Source view, edit the <wijmo:c1lineargauge></wijmo:c1lineargauge> tag so it looks like the following:: <wijmo:c1lineargauge ID="C1LinearGauge1" runat="server" Width="400" Height="100" Value="50"> This sets the Width and Height of the control, as well as the gauge's initial Value at run time. 2. Place your mouse between the <wijmo:c1lineargauge></wijmo:c1lineargauge> tags, and add the following markup to style various aspects of the C1LinearGauge control: <Animation Duration="400" /> <Labels> <LabelStyle Fill-Color="#1E395B" FontSize="12pt" FontWeight="800"></LabelStyle> </Labels> <TickMajor Position="Inside" Offset="-11" Interval="20" Factor="12"> <TickStyle Fill-Color="#1E395B" Width="2"></TickStyle> </TickMajor> <TickMinor Position="Inside" Offset="-11" Visible="true" Interval="4" Factor="10"> <TickStyle Fill-Color="#1E395B" Width="1"></TickStyle> </TickMinor> <Pointer Shape="Tri" Length="0.5"> <PointerStyle Fill-Color="#1E395B" Stroke="#1E395B"></PointerStyle> </Pointer> <Face> <FaceStyle Fill-LinearGradientAngle="270" Fill-ColorBegin="#FFFFFF" Fill-ColorEnd="#7BA0CC" Fill-Type="LinearGradient" StrokeWidth="4"></FaceStyle> </Face> Note that you set styles for the following items: Animation: Sets the animation options. Here you set the Duration of the animation. Labels: Sets options and the style of the gauge labels. Here you set the Style of the labels, including the color and font. TickMajor: Sets options and the style of the major tick lines. Here you set the Position, Offset, Interval, and Factor of the major tick lines, as well as the color and width. TickMinor: Sets options and the style of the minor tick lines. Here you set the Position, Offset, Interval, and Factor of the minor tick lines, as well as the visibility, color, and width. Pointer: Sets options and the style of the gauge pointer. Here you set the Style of the pointer, including the color and stroke. Face: Sets options and the style of the gauge face. Here you set the Style of the labels, including the fill color and style. 3. Run your application, and observe that the gauge now looks similar to the following image: 4

9 Notice the style changes that you made are reflected in the control. In this step you customized the appearance of the C1LinearGauge control. In the next step you'll customize the behavior of the control. Step 3 of 3: Customizing C1LinearGauge's Behavior In this step you'll add a slider control. When the thumb button of the slider is moved at run time, the value of the gauge control will change. The following steps assume you've completed Step 2 of 3: Customizing C1LinearGauge's Appearance topic. Complete the following steps: 1. In Source view, add the following markup just below the </wijmo:c1lineargauge> tag to add text: <p>drag and release the slider's thumb button to change the gauge's value:</p> 2. In Source view, add the following markup just below the </p> tag you just added to add a slider control to the page: <div id="slider" style="width: 400px"></div> The page now includes a slider control. 3. In Source view, add the following markup just below the </div> tag you just added to enable the slider control: <script type="text/javascript"> $(document).ready(function () { $("#slider").slider({ value: $("#<%= C1LinearGauge1.ClientID %>").c1lineargauge("option", "value"), change: function (event, ui) { $("#<%= C1LinearGauge1.ClientID %>").c1lineargauge("option", "value", ui.value); } }); }); </script> Now when the slider's value changes, the gauge's value will also change to reflect the new value. 4. Run the application and observe that the control displays the changes that you made: 5

10 5. Click the slider's thumb button and preform a drag-and-drop operation. Notice the C1LinearGauge control's value changes to reflect the value of the slider control. In this step you customized the behavior of the controls. Congratulations, you've completed this quick start guide! 6

11 Wijmo Top Tips The following tips may help you troubleshoot when working with Studio for ASP.NET Wijmo. Tip 1: Prevent poor page rendering in quirks mode by editing the meta tag to fix rendering. If a user's browser is rendering a page in quirks mode, widgets and controls may not appear correctly on the page. This is indicated by a broken page icon in the address bar. In Compatibility View, the browser uses an older rendering engine. Users can set this view that causes the issue. To prevent rendering in quirks mode, you can force the page to render with the latest browser. Add the following meta tag to the header of the page: <meta http-equiv="x-ua-compatible" content="ie=edge,chrome=1" /> Working with C1LinearGauge C1LinearGauge uses a linear pointer to show a value along a linear scale. The value is represented by a Value property and the range is defined by the Min and Max properties. The C1LinearGauge control appears similar to a typical thermometer: Creating and using a C1LinearGauge control typically involves the following steps: 1. Create the C1LinearGauge control and set its main properties: Min, Max, and Orientation. 2. Adding TickMajor and TickMinor decorators to show the scale and GaugeLabel to customize the label. 3. Optionally adding GaugelRange decorators to highlight parts of the scale. Ranges are typically used to indicate ranges that are too low, acceptable, or too high. Ranges can also be dynamic, moving automatically when the Value property changes. 4. Optionally customizing gauge elements with templates. 5. Setting the Value property to display the value you want to show. 7

12 Why Use Gauge Controls? You might be asking why you'd need to use gauge controls after all, gauges just display a single value and you could display that value using a simple label instead of a gauge. Gauges are better because they also display a range, allowing users to determine instantly whether the current value is low, high, or intermediate. You could use two additional labels to display the range as well as the current value, but that would make your user interface more confusing. That is why many applications use progress indicators that are simple linear gauges, instead of showing progress simply as a label. Gauges are also more visually attractive than simple labels (or sliders or scrollbars), and that adds value to your applications. C1LinearGauge Values You can use the C1LinearGauge control's Min, Max, and Value properties to specify the available range and the selected value in that range: The Min and Max properties specify the range of values the gauge is designed to show. For example, a thermometer may have a scale ranging from -40 to 100 degrees, and a speedometer may have range of 0 to 140 miles per hour. The range is specified through the Min and Max properties (of type double). The default range for a C1LinearGauge control is from 0 to 100. The Value property indicates the current value of the gauge. In the C1LinearGauge control, this is indicated visually by the value the Pointer element is pointing to. The default Value for a C1LinearGauge control is 0; in the above image, the Value was set to 50. C1LinearGauge Orientation C1LinearGauge controls have an Orientation property that you can use to create vertical or horizontal gauges. By default, the Orientation property is set to Horizontal and the gauge appears displayed horizontally in the application: You can set the Orientation property to Vertical to create a vertical gauge: 8

13 For example, a vertical linear gauge could be used as a thermometer. C1LinearGauge Indicators By default, the C1LinearGauge control displays only a plain horizontal linear gauge. In most applications, you'll also want to display a scale composed of custom labels and tick marks that allow users to see what the current value is and where it lies within the gauge's range. This is done by adding TickMajor, TickMinor, GaugelRange, and GaugeLabel elements: In the image above, you'll see customized TickMajor and TickMinor elements: <!-- Tick marks --> <TickMajor Position="Inside" Offset="-11" Interval="20" Factor="12"> <TickStyle Width="2"> </TickStyle> </TickMajor> <Fill Color="#1E395B"></Fill> <TickMinor Position="Inside" Visible="true" Offset="-11" Interval="4" Factor="10"> 9

14 <TickStyle Width="1"> <Fill Color="#1E395B"></Fill> </TickStyle> </TickMinor> The GaugeLabel is also set: <!-- Add labels --> <Labels> <LabelStyle FontSize="12pt" FontWeight="800"> <Fill Color="#1E395B"></Fill> </LabelStyle> </Labels> In addition to showing the scale, you may want to highlight parts of the scale range. For example, you may want to add a red marker to indicate that values in that range are too low (sales) or too high (expenses). This can be done easily by adding one or more GaugelRange elements. In the image above, you'll see a colored GaugelRange element: <!-- Add a colored range --> <Ranges> <Wijmo:GaugelRange StartValue="20" EndValue="80" StartDistance="0.85" EndDistance="0.85" StartWidth="0.5" EndWidth="0.5"> <RangeStyle> <Fill LinearGradientAngle="90" ColorBegin="#3DA1D8" ColorEnd="#3A6CAC" Type="LinearGradient"></Fill> </RangeStyle> </Wijmo:GaugelRange> </Ranges> The GaugelRange element displays a colored swath along the scale. The color of the swath is determined by the RangeStyle property, and the position is determined by the StartValue and EndValue properties. You can control the thickness of the ranges using the StartWidth and EndWidth properties. C1LinearGauge Pointer The C1LinearGauge control includes a pointer which indicates the selected Value of the control. The pointer consists of the Pointer element: 10

15 The Pointer element appears by default as a blue tapering element, but you can customize the appearance of the Pointer element by setting several properties in the GaugePointer class, including the Length, Offset, Shape, PointerStyle, Template, Visible, and Width properties. In the image above, the Pointer element is customized: <! Pointer --> <Pointer Length="0.5" Shape="Rect"> <PointerStyle Stroke="#1E395B"> </PointerStyle> </Pointer> <Fill Color="#1E395B"></Fill> C1LinearGauge Face and Cover Like a watch, the C1RadialGauge control includes a Face element. The Face appears above the background but behind the pointer and other elements. For example, in the image below the Face is a plain gray circle that appears behind the elements in the gauge: In the image above, the Face element is customized: <! Face --> <Face> <FaceStyle Stroke="#7BA0CC" StrokeWidth="4"> <Fill LinearGradientAngle="270" ColorBegin="#FFFFFF" ColorEnd="#D9E3F0" Type="LinearGradient"></Fill> </Face> </FaceStyle> The Face element appears by default as a blue-gray circle, but you can customize the appearance of the Face element by setting several properties in the GaugeFace class, including the FaceStyle property. LinearGauge for ASP.NET Wijmo Samples Please be advised that this ComponentOne software tool is accompanied by various sample projects and/or demos which may make use of other development tools included with the ComponentOne Studios. Samples can be accessed from the ComponentOne ControlExplorer. To view samples, on your desktop, click the Start button and 11

16 then click All Programs ComponentOne Studio for ASP.NET Wijmo Samples. The ControlExplorer sample includes a section that details some of the functionality available in the C1LinearGauge control. C# Samples The following pages within the ControlExplorer sample installed with ComponentOne Studio for ASP.NET Wijmo detail the C1LinearGauge control's functionality: Sample Overview Interactive Level Orientation Temperature Volume Description This sample illustrates how to create a basic C1LinearGauge control. The sample demonstrates how to create an interactive C1LinearGauge control. Changes to a slider control are reflected in the gauge. This sample uses the TickMarker, TickMinor, and Pointer properties to customize the appearance of the control. This sample illustrates the horizontal and vertical orientations of C1LinearGauge. This example display a linear gauge styled to appear like a thermometer. This example displays a linear gauge styled like a volume gauge. 12

17 LinearGauge for ASP.NET Wijmo Task-Based Help The task-based help assumes that you are familiar with programming in ASP.NET and know how to use controls in general. By following the steps outlined in the help, you will be able to create projects demonstrating a variety of C1LinearGauge's features, and get a good sense of what the C1LinearGauge control can do. Each topic provides a solution for specific tasks using the C1LinearGauge control. Each task-based help topic also assumes that you have created a new ASP.NET project and added references to the appropriate assemblies. Creating a C1LinearGauge in Code Creating a C1LinearGauge control in code is fairly simple. In the following steps you'll add a PlaceHolder control to the page, add an import statement, add and customize the C1LinearGauge, and add the control to the PlaceHolder. Complete the following steps: 1. In Design view, double-click the page to create the Page_Load event and switch to Code view. 2. Add the following statement to the top of the Code Editor to import the appropriate namespace: Visual Basic Imports C1.Web.Wijmo.Controls.C1Gauge C# using C1.Web.Wijmo.Controls.C1Gauge; 3. Add the following code to the Page_Load event to create and customize the C1LinearGauge control. Visual Basic ' Create a new C1LinearGauge. Dim C1LG As New C1LinearGauge ' Set the control's size and value. C1LG.Height = 100 C1LG.Width = 500 C1LG.Min = 0 C1LG.Max = 100 C1LG.Value = 60 ' Add the C1LinearGauge to the PlaceHolder control. Dim PlaceHolder1 As New PlaceHolder PlaceHolder1.Controls.Add(C1LG) form1.controls.add(placeholder1) C# // Create a new C1LinearGauge. C1LinearGauge C1LG = new C1LinearGauge(); // Set the control's size and value. C1LG.Height = 100; C1LG.Width = 500; C1LG.Min = 0; C1LG.Max = 100; C1LG.Value = 60; // Add the C1LinearGauge to the PlaceHolder control. PlaceHolder PlaceHolder1 = new PlaceHolder(); 13

18 PlaceHolder1.Controls.Add(C1LG); form1.controls.add(placeholder1); What You've Accomplished Run your application and observe that the C1LinearGauge control was created. Resizing the Control You can easily change the height and width on the C1LinearGauge by setting the Height and Width properties. By default the height of the control is set to 80px and the width of the control is set to 600px. You can easily change the control's height and width in Source view, from the Properties window, or in code. In Source View In Source view add Height="100px" and Width="500px" in the <wijmo:c1lineargauge> tag to the size you wish to set the control's height and width to, for example: <wijmo:c1lineargauge ID="C1LinearGauge1" runat="server" Height="100px" Width="500px"> The above will resize the control to 100 pixels tall and 500 pixels wide. From the Properties Window You can change the Height and Width properties to set the control's height and width in the Properties window: In Code 1. Click on the C1LinearGauge to select it. 2. Navigate to the Properties window and if needed expand the Layout node to locate the Height and Width properties. 3. Next to Height, enter a value for the size you want the control's height to be, for example "200px". 4. Next to Width, enter a value for the size you want the control's width to be, for example "500px". 5. Press the ENTER key or click outside of the Properties window for the height and width you set to be applied to the C1LinearGauge control. Add the following code to the Page_Load event to set the Height and Width properties 100 pixels tall and 500 pixels wide: Visual Basic Me.C1LinearGauge1.Height = 100 Me.C1LinearGauge1.Width = 500 C# this.c1lineargauge1.height = 100; this.c1lineargauge1.width = 500; Setting the Start Value In this topic you'll change the C1LinearGauge control's Value property. The Value property determines the currently selected number. By default the C1LinearGauge control starts with its Value set to 0 but you can customize this number at design time, in XAML, and in code. Note that although this topic sets the Value of the C1LinearGauge control, the same steps can be used to customize the Value of other controls. At Design Time To set the C1LinearGauge control's Value property at run time, complete the following steps: 1. Click the C1LinearGauge control once to select it. 14

19 In XAML 2. Navigate to the Properties window, and enter a number, for example "20", in the text box next to the Value property. This will set the Value property to the number you chose. For example, to set the Value property add Value="20" to the <wijmo:c1lineargauge> tag so that it appears similar to the following: <wijmo:c1lineargauge Value="20"> In Code For example, to set the Value property, add the following code to your project: Visual Basic C1LinearGauge1.Value = 20 C# c1lineargauge1.value = 20; Run your project and observe: Initially the gauge's Pointer will be set to the Value you selected. Setting the Minimum and Maximum Values You can use the Min and Max properties to set a numeric range that the gauge would be limited to. You can customize the Min and Max values at design time, in XAML, and in code. Note: When setting the Min and Max properties, the Min should be smaller than the Max. Also be sure to set the Value property to a number within the Min and Max range (in the example below, the Value is set to 0, which falls within the range set below). At Design Time To set the Min and Max for the C1LinearGauge at run time, complete the following steps: In XAML 1. Click the C1LinearGauge control once to select it. 2. Navigate to the Properties window, and enter a number, for example 50, next to the Max property. 3. In the Properties window, enter a number, for example -50, next to the Min property. This will set Min and Max values. To set the C1LinearGauge control's Min and Max in XAML add Maximum="50" Minimum="-50" to the <wijmo:c1lineargauge> tag so that it appears similar to the following: <wijmo:c1lineargauge Name="C1LinearGauge1" Maximum="50" Minimum="-50"> In Code To set the C1LinearGauge control's Min and Max add the following code to your project: Visual Basic C1LinearGauge1.Minimum = -50 C1LinearGauge1.Maximum = 50 C# c1lineargauge1.minimum = -50; c1lineargauge1.maximum = 50; Run your project and observe: 15

20 The gauge will be limited to the selected range at run time. LinearGauge for ASP.NET Wijmo Client-Side Reference As part of the amazing ComponentOne Web stack, the Wijmo jquery UI widgets are optimized for client-side Web development and utilize the power of jquery for superior performance and ease of use. The ComponentOne Wijmo Web site at provides everything you need to know about Wijmo widgets, including demos and samples, documentation, theming examples, support and more. The client-side documentation provides an overview, sample markup, options, events, and methods for each widget. To get started with client-side Web development for LinearGauge for ASP.NET Wijmo, click one of the external links to view our Wijmo wiki documentation. Note that the Overview topic for each of the widgets applies mainly to the widget, not to the server-side ASP.NET Wijmo control. wijlineargauge dependencies wijlineargauge options 16