shinobigauges userguide

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 Trial Key

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

AppDelegate.m

- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions
{
  ShinobiGauges.trialKey = @""; // Add trial key here
  ...

or

ViewController.m

- (void)viewDidLoad
{
  ShinobiGauges.trialKey = @""; // Add trial key here
  ...

The trial 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 trial 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.