ShinobiGauges are visual indicators of a single value, styled and created by ShinobiControls.

Installing the ShinobiGauges framework

ShinobiGauges ships with an installer, to make it easier to get started. To run the installer, run the ShinobiGauges.dmg file which you downloaded from ShinobiControls. When it opens up, it should look as below.

The easiest way to install the ShinobiGauges framework is to run the install.pkg file. This will install the framework into Xcode for you, along with the framework documentation. This means you can add the framework to your project in the same way as you would any of the frameworks which are automatically shipped with Xcode.

If you don’t want to run the installer, the framework is also contained within the ShinobiGauges folder in the disk image. Regardless of whether you ran the installer, you will need to copy this folder onto your machine, so let’s do that now. Drag the ShinobiGauges folder onto the Library icon in the disk image or onto your desktop, whichever you prefer.

The ShinobiGauges folder contains:

  • A copy of the framework.
  • A copy of the documentation for the framework.
  • A set of samples to demonstrate getting started with ShinobiGauges.
  • An uninstall script for uninstalling the ShinobiGauges framework from Xcode.
  • The Xamarin.iOS version of the framework.
  • A README file with setup steps.
  • A text file containing the version number.
  • A copy of the ShinobiControls license.
  • A change log containing the changes made to this release.

Adding ShinobiGauges to your project

To add ShinobiGauges to your Xcode project, you need to add a reference to the ShinobiGauges framework. There are two ways of doing this:

  • If you have run the Gauges installer, the easiest way to add the framework is to open up the project window, go to the Build Phases tab, and select to add frameworks in the “Link Binary With Libraries” section. In the menu which is displayed, select ShinobiGauges.framework.
  • If you didn’t run the pkg installer, you can drag the framework into your project from the ShinobiGauges folder on your desktop.

ShinobiGauges makes use of the QuartzCore.framework, so you should add this to your project from the “Link Binary With Libraries” section of the project window. Trial users will need to import Security.framework too.

To check you have done all of this correctly, open up the project window, go to the Build Phases tab and check that ShinobiGauges.framework and QuartzCore.framework are both under “Link Binary With Libraries”.

Quick Start Guide

Introduction

The following guide will get you up and running with the SGauge component as quickly as possible. In this guide, we will introduce you to the key features of the Gauge, including initial project setup and configuring the style. It may help to follow along with our related code sample: GaugesGettingStarted.xcodeproj

Creating a Gauge

Start up Xcode and create a new project (File / New / Single View Application).

Within your newly created project, add a reference to the ShinobiGauges.framework. Instructions for doing this can be found in the Framework Guide. If you are a trial user, you will also need to setup the license key.

Firstly, add an instance variable for the Gauge, and import the main ShinobiGauges header in ViewController.m, defining the variable as follows:

#import "ViewController.h"
#import <ShinobiGauges/ShinobiGauges.h>

@implementation ViewController
{
    SGaugeRadial *gauge;
}
...

In viewDidLoad, create the Gauge instance as follows:

- (void)viewDidLoad
{
    [super viewDidLoad];
    // Do any additional setup after loading the view.

    gauge = [[SGaugeRadial alloc] initWithFrame:CGRectMake(0, 0, 400, 400) fromMinimum:@0 toMaximum:@1000];
    gauge.center = self.view.center;
    [self.view addSubview:gauge];
}

At this point, build and run the project to check that everything has been set up correctly. You should see something similar to the gauge below:

Configuring the Gauge

The gauge has been built with styling in mind, allowing you to change virtually every aspect of the gauge, needle and the axis. For more detail on this, see the Styling section below.

Instead of the default style, apply the Dashboard style as follows:

- (void)viewDidLoad
{
    ...
    gauge.style = [SGaugeDashboardStyle new];
}

Next, make the range take up more of the circle by setting the start and end angle of the axis arc:

- (void)viewDidLoad
{
    ...
    gauge.arcAngleStart = -M_PI_4 * 3.0;
    gauge.arcAngleEnd = M_PI_4 * 3.0;
}

Thicken the bevel around the edge:

- (void)viewDidLoad
{
    ...
    gauge.style.bevelWidth = 30;
}

Finally, give the gauge a value:

- (void)viewDidLoad
{
    ...
    gauge.value = 375;
}

This is only a small part of what the Gauge can do, but there are plenty of options on how to customize it exactly how you need it. If you got stuck at any point, take a look at our related code sample:

Quick Start Guide - Swift

Introduction

The following guide will get you up and running with the SGauge component as quickly as possible. In this guide, we will introduce you to the key features of the Gauge, including initial project setup and configuring the style. It may help to follow along with our related code sample: GaugesGettingStartedSwift.xcodeproj

Setting up the project

Start up Xcode and create a new project (File / New / Single View Application). Chose swift as the langugage to use for your new project.

Within your newly created project, add a reference to the ShinobiGauges.framework. Instructions for doing this can be found in the Framework Guide. If you are a trial user, you will also need to setup the license key.

Linking to the bridging header file

In order for Xcode to use an Objective-C based framework in Swift, it needs to have a bridging header file. We have included a bridging header file in our framework. To link to it, you must open the build settings for the your new target, and search for the Objective-C Bridging Header setting. You must then provide the path to the ShinobiGauges-Bridging-Header.h file, which is inside the Headers directory of the ShinobiGauges.framework.

Setting the Swift project's bridging header file

In the screenshot above, you can see that the framework is three directories above the root of the project, hence it is set to

$(SRCROOT)/ShinobiGauges.framework/Headers/ShinobiGauges-Bridging-Header.h

This path will vary based on the location of the framework on your file system.

Creating a Gauge

First, open up ViewController.swift and in viewDidLoad, create the Gauge instance as follows:

override func viewDidLoad() {
    super.viewDidLoad()

    let gauge = SGaugeRadial(frame: CGRectMake(0, 0, 400, 400), fromMinimum: 0, toMaximum: 1000)
    gauge.center = view.center
}

At this point, build and run the project to check that everything has been set up correctly. You should see something similar to the gauge below:

Configuring the Gauge

The gauge has been built with styling in mind, allowing you to change virtually every aspect of the gauge, needle and the axis. For more detail on this, see the Styling section below.

To customise the default style, add the following lines to the end of viewDidLoad:

gauge.style = SGaugeDashboardStyle()

This will apply the “dashboard” style. Next, make the range take up more of the circle by setting the start and end angle of the axis arc:

gauge.arcAngleStart = CGFloat(-M_PI_4 * 3)
gauge.arcAngleEnd = CGFloat(M_PI_4 * 3)

Thicken the bevel around the edge:

gauge.style.bevelWidth = 30

Finally, give the gauge a value:

gauge.value = 375

This is only a small part of what the Gauge can do, but there are plenty of options on how to customize it exactly how you need it. If you got stuck at any point, take a look at our related code sample: GaugesGettingStartedSwift.xcodeproj.

Quick Start Guide for Xamarin.iOS

Introduction

The following guide will get you up and running with the SGauge component as quickly as possible. In this guide, we will introduce you to the key features of the Gauge, including initial project setup and configuring the style. It may help to follow along with our related code sample: GettingStarted.sln.

Getting Set Up

Start up Xamarin Studio and create a new project (File / New / Solution) then select C# / iOS / Universal / Single View Application as your solution type. Name your solution GettingStarted.

Within your newly created project, add a reference to the ShinobiGauges.dll. To do this, right click the References folder under your newly created project and choose Edit References…, then selected .Net Assembly and browse to where you have saved the ShinobiGauges.dll. Be sure to click Add after selecting the dll to add it to your project, and close the window.

To check you have done all of this correctly, expand the References folder in the Solution Pad and you should see the ShinobiGauges.dll listed as a reference.

Creating a Gauge

The first step is to create an instance of the gauge and add it to the view. Open up the GettingStartedViewController.cs file and add the following using statement:

using Shinobi.Gauges;

Further down the same file add a member variable for the gauge:

public partial class GaugesGettingStartedViewController : UIVIewController
{
    SGaugeRadial _gauge;
    …

In ViewDidLoad, create the Gauge instance as follows:

public override void ViewDidLoad ()
{
    base.ViewDidLoad ();

    ShinobiGauges.LicenseKey = ""; // Add license key here.

    // Create the Gauge.
    _gauge = new SGaugeRadial (new RectangleF (0, 0, 400, 400), 0, 1000);
    _gauge.Center = View.Center;
    View.AddSubview (_gauge);
}   

At this point, build and run the project to check that everything has been set up correctly. You should see something similar to the gauge below:

Configuring the Gauge

The gauge has been built with styling in mind, allowing you to change virtually every aspect of the gauge, needle and the axis. For more information, see the documentation for the class SGaugeStyle.

Instead of the default style, apply the Dashboard style as follows:

public override void ViewDidLoad ()
{
    …
    _gauge.Style = new SGaugeDashboardStyle ();
}

Next, make the range take up more of the circle by setting the start and end angle of the axis arc:

public override void ViewDidLoad ()
{
    …
    _gauge.ArcAngleStart = (float)-Math.PI * 3 / 4;
    _gauge.ArcAngleEnd = (float)Math.PI * 3 / 4;
}

Thicken the bevel around the edge:

public override void ViewDidLoad ()
{
    …
    _gauge.Style.BevelWidth = 30;
}

Finally, give the gauge a value:

public override void ViewDidLoad ()
{
    …
    _gauge.Value = 375;
}

Now build and run your project and your gauge should look like the following:

This is only a small demonstration of what the Gauge can do, there are plenty of options to allow you to customize it exactly how you need it. If you got stuck at any point, take a look at our related code sample: GettingStarted.sln

ShinobiGauges Control Overview

The ShinobiGauge is a control to display a single value, either in a Radial (SGaugeRadial) or Linear (SGaugeLinear) fashion. The value of the gauge is pointed to by the needle (SGaugeNeedle), with tick marks and labels on the axis (SGaugeAxis) allowing the user to read off the value.

Needle

The needle indicates the current value of the gauge. By default, the needle is a small arrow, with a knob on the end. The anchorpoint of the needle is set to allow it to rotate around the knob. The border, fill and size of both the arrow and knob can be styled through the SGaugeStyle.

The needle can also be replaced completely with a custom image. See the How-to Guides on how to do this.

Axis

The axis of the gauge presents values from the minimum to maximum of the gauge’s range, with tick marks at regular intervals and value labels appearing over the major tick marks (unless showTickLabels is set to NO). The major and minor tick marks can be styled seperately through the SGaugeStyle.

While the axis is a numeric axis by default, the delegate allows us some additional control, such as creating an axis which displays categories instead of numbers. To create a gauge measuring from “Cold” through “Moderate” to “Hot”;

-(void)viewDidLoad
{
    ...
    gauge.delegate = self;

    //Set the range and frequencies to display labels at 0, 1 and 2
    gauge.majorTickFrequency = 1;
    gauge.minimumValue = 0;
    gauge.maximumValue = 2;

    //List the values for the tick labels
    categories = @[@"Cold", @"Moderate", @"Hot"];
}

-(void)gauge:(SGauge*)gauge alterTickLabel:(UILabel*)tickLabel atValue:(CGFloat)value
{
    tickLabel.text = [categories objectAtIndex:value];
}

A “Qualitative range” can also be drawn over the axis, giving a clearer visual indication of if the value of the gauge is within an expected or acceptable range. We set the majorTickFrequency to 1 to directly map the value of each major tick to the corresponding label index in the categories array. In the case above, we could highlight the cold/moderate/hot regions as blue, green and red half way between each label as follows:

NSArray* ranges =@[[SGaugeQualitativeRange rangeWithMinimum:nil maximum:@0.5 color:[UIColor blueColor]],
                   [SGaugeQualitativeRange rangeWithMinimum:@0.5 maximum:@1.5 color:[UIColor greenColor]],
                   [SGaugeQualitativeRange rangeWithMinimum:@1.5 maximum:nil color:[UIColor redColor]]];
gauge.qualitativeRanges = ranges;

Styling

The main focus of the gauge is the style used to make it visually appealing. The style (SGaugeStyle) contains a large number of parameters to finely tune the appearance of all aspects of the gauge.

ShinobiGauges come with a few different styles out of the box, such as SGaugeDarkStyle, SGaugeLightStyle and SGaugeDashboardStyle. These are intended as starting points, and can be heavily configured or just used as they come.

To set the style of a gauge, simply set the style property:

[gauge setStyle:[SGaugeDarkStyle new]];

Changing properties on the style can be done either before, or after the style is added to the gauge:

gauge.style.tickMarkAlignment = SGaugeTickAlignCenter;

...

SGaugeStyle *style = [SGaugeDashboardStyle new];
style.showTickLabels = NO;
[gauge setStyle:style];

ShinobiGauges How-to Guides

How to use a Custom Needle

The SGaugeStyle offers plenty of options for styling, including changing the widths and colours of all the basic elements. However sometimes you need a needle with a more complex appearance. The gauge will let you add your own needle easily enough, but will require some configuration.

To create a Custom Needle, you will need to create a UIView using the SGaugeNeedle protocol. The optional properties on the protocol allow you to change the appearance of the Needle based on values, but we won’t need that for this example. When you create your needle, there are a few points you will need to be aware of:

self.layer.zPosition = 2;

//Change anchor, and reposition
self.layer.anchorPoint = CGPointMake(0.5, 1);
self.frame = frame;

//Load custom needle image
...

Firstly, we set the zPosition of the needle to 2. This positions it above the axis, but underneath the glassy shine of the gauge. You can set the zPosition to different values to reorder these however you want.

We also set the anchorPoint of the needle. This controls where the needle will pivot about. In our case, we want the middle of the bottom edge to be our pivot point, however if your needle image is intended to extend past the center of the gauge (such as with a knob in the center of the gauge), then you will need to tweak this value.

After setting the anchorPoint, the needle will try to move positions, so we set the frame back to where it was before.

To add this in to the gauge, we then simply call:

gauge.needle = [[CustomNeedle alloc] initWithFrame:needleFrame];

As we change the value of the gauge, the needle will move to the correct position.

If you got stuck at any point, take a look at our related code sample: GaugesHowToCustomNeedle.xcodeproj.

How to create Custom Tickmarks

While the standard linear tickmarks are the norm, sometimes we want something a little more exciting. The gauge allows you to specify your own tickmarks, both as major and minor types. This can be done either by subclassing the SGaugeAxis, or using the SGaugeDelegate.

To provide custom tickmarks when subclassing, implement the viewForTickMarkAtValue:isMajorTick: method, and return a UIView containing your tickmark. For example, to use small squares instead of the standard lines, you would implement the following;

-(UIView *)viewForTickMarkAtValue:(CGFloat)value isMajorTick:(BOOL)isMajorTick
{
    CGFloat edgeLength = (isMajorTick) ? 12 : 6;
    CGRect squareBounds = CGRectMake(0, 0, edgeLength, edgeLength);

    UIView *customTickMark = [[UIView alloc] initWithFrame:squareBounds];
    customTickMark.backgroundColor = [UIColor blackColor];
    customTickMark.layer.shouldRasterize = YES;

    return customTickMark;
}

Two points to note here are: * We change the size of the tick mark based on the isMajorTick value, making major ticks larger than minor ticks * We set shouldRasterize to YES, to avoid jagged lines when the square is rotated. This is particularly important on the Radial gauge.

To add this in to the gauge, we simply set:

gauge.axis = [[CustomAxis alloc] initWithGauge:gauge];

Alternatively, if subclassing SGaugeAxis sounds like too much hassle, you can use the SGaugeDelegate instead. The delegate offers the gauge:alterTickMark:atValue:isMajorTick: method to modify a tickmark after it has been displayed. For example:

-(void)gauge:(SGauge *)gauge alterTickMark:(UIView *)tickMark atValue:(CGFloat)value isMajorTick:(BOOL)majorTick
{
    if (value >= 80)
        tickMark.backgroundColor = [UIColor redColor];
}

If you got stuck at any point, take a look at our related code sample: GaugesHowToCustomTicks.xcodeproj.

How to format Tick Labels

Using the SGaugeAxis straight out of the box, all Tick Labels are displayed as simple numbers. However sometimes we want something more tailored to our app, such as a percentage. The Gauge offers two ways to do this; one for simple uses, and one for more advanced users.

The simple way to format Tick Labels is to use an NSFormatter. Keeping with our example, we could format the labels to be percentages by setting the formatter on the SGaugeAxis as follows:

NSNumberFormatter *formatter = [NSNumberFormatter new];
[formatter setNumberStyle:NSNumberFormatterPercentStyle];
gauge.axis.formatter = formatter;

The NSFormatter has a number of styles available out of the box, and can also be subclassed to provide a more tailored formatter.

The alternative to using the formatter property would be to use the SGaugeDelegate method gauge:alterTickLabel:atValue:. This allows us to change the Tick Labels on a case-by-case basis, or to apply a single change to all labels. For example;

-(void)gauge:(SGauge *)gauge alterTickLabel:(UILabel *)tickLabel atValue:(CGFloat)value
{
    if (value >= 0.8)
        tickLabel.textColor = [UIColor redColor];
}

If you got stuck at any point, take a look at our related code sample: GaugesHowToFormatLabels.xcodeproj.

Common Concepts

There are some concepts which are common across all ShinobiControls components:

Setting the License Key

ShinobiControls trial downloads require a license key to work. If you have downloaded a trial version of ShinobiGauges you will have been issued with a trial license key. Add the key that you were supplied with at the location indicated below.

AppDelegate.m

- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions
{
  [ShinobiGauges setLicenseKey:@""]; // Add license key here
  ...

or

ViewController.m

- (void)viewDidLoad
{
  [ShinobiGauges setLicenseKey:@""]; // Add license key here
  ...

The license key can be set in the ViewController or the AppDelegate, so long as it is set before any ShinobiGauges controls are created. It only needs setting once across the whole application.

Note: Full featured versions of ShinobiControls do not require a license key to be set in code.

Troubleshooting

If you encounter problems that the documentation cannot answer then the first port of call should be ShinobiDeveloper and the Blog. If you still can’t find an answer, then please do get in touch.