Overview

This document provides an overview of the SEssentialsSlidingOverlay control. It describes the features of the control and its associated concepts, together with some step-by-step guides for achieving common tasks.

The SEssentialsSlidingOverlay component offers an easy way to show and hide a small panel, allowing it to be shown when needed, without it taking up screen space when it is no longer required. It works in a similar way to the UISplitViewController, but while the Split View Controller only displays both views in landscape, and only one in portrait, the SlidingOverlay allows you to hide or display the underlay whenever you need to.

If you simply want to get up and running, follow the Quick Start Guide - Objective-C, or the Quick Start Guide - Swift. Alternatively, for a more detailed description of how the SlidingOverlay works and the features it presents, see the ~!@[ShinobiEssentials](../../../Classes/ShinobiEssentials.html) SlidingOverlay Control Overview@!~ SlidingOverlay Control Overview). Finally, for guides that tackle specific usage scenarios, look at the ~!@[ShinobiEssentials](../../../Classes/ShinobiEssentials.html) SlidingOverlay How-to Guides@!~ SlidingOverlay How-to Guides).

The SlidingOverlay has a complete set of Xamarin.iOS bindings, allowing you to make use of all of its features from within applications written in C#. In order to get up and running, follow the Quick Start Guide for Xamarin iOS.

Quick Start Guide - Objective-C

Introduction

The following guide will get you up-and-running with the SEssentialsSlidingOverlay component as quickly as possible. In this guide, we will introduce you to the key features of the SlidingOverlay, including initial project setup, customizing the overlay and underlay, and getting the two to communicate properly. You can follow along with our related code sample: SlidingOverlayGettingStarted.xcodeproj.

Creating a SlidingOverlay

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

Within your newly created project, add a reference to the ShinobiEssentials framework, and the bundle which contains its resources. Instructions for doing this can be found in the first section of the EssentialsUserGuide.

In ViewController.m, import the header, and create a reference to the SlidingOverlay;

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

@implementation ViewController {
    SEssentialsSlidingOverlay *slidingView;
}

In viewDidLoad, we create the SlidingOverlay, and add it to the main view:

- (void)viewDidLoad
{
    [super viewDidLoad];
    // Do any additional setup after loading the view, typically from a nib.
    slidingView = [[SEssentialsSlidingOverlay alloc] initWithFrame:self.view.frame andToolbar:YES];
    [self.view addSubview:slidingView];
    [self setupSubviews];
}

And in only a few lines of code, we can run the app and start to see the SlidingOverlay already working. We can already use the button to open and close the underlay, and swipe left and right to open or close it;

Customizing the Views

To start with, we will add a small “Hello world” messages to the Overlay and Underlay. We could just define it in the scope of viewDidLoad, but we will need ivars, so let’s add them:

@implementation ViewController {
    UILabel *myOverlayLabel;
    UILabel *myUnderlayLabel;
    SEssentialsSlidingOverlay *slidingView;
}

Then in viewDidLoad, initialize the labels and add them as a subviews of the SlidingOverlay’s overlay and underlay respectively. As a styling point, we recommend setting the background to be transparent.

-(void)setupSubviews
{
    //Setup Overlay
    myOverlayLabel = [[UILabel alloc] initWithFrame: CGRectMake(10, 10, 100, 100)];
    myOverlayLabel.backgroundColor = [UIColor clearColor];
    myOverlayLabel.text = @"Hello, World!";
    myOverlayLabel.textColor = [UIColor whiteColor];
    [slidingView.overlay addSubview: myOverlayLabel];

    //Setup Underlay
    myUnderlayLabel = [[UILabel alloc] initWithFrame: CGRectMake(10, 10, 200, 100)];
    myUnderlayLabel.backgroundColor = [UIColor clearColor];
    myUnderlayLabel.text = @"Hello, Underlay!";
    myUnderlayLabel.textColor = [UIColor whiteColor];
    [slidingView.underlay addSubview: myUnderlayLabel];
}

With that, you should have labels attached to your Overlay and Underlay:

Removing the title bar

The SlidingOverlay has a title bar by default, which contains a button to open and close the Underlay. Swiping inside the control will also open and close the overlay, so it’s not required that the top bar is displayed. Whether or not a SlidingOverlay has a toolbar is determined at construction time, so to remove the toolbar simply change YES to NO:

...
slidingView = [[SEssentialsSlidingOverlay alloc] initWithFrame:self.view.frame andToolbar:NO];
...

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

Quick Start Guide - Swift

Introduction

The following guide will get you up-and-running with the SEssentialsSlidingOverlay component as quickly as possible. In this guide, we will introduce you to the key features of the SlidingOverlay, including initial project setup, customizing the overlay and underlay, and getting the two to communicate properly. You can follow along with our related code sample: SlidingOverlayGettingStarted.swift.

Setting up the project

Start up Xcode and create a new project (File / New / Single View Application). Within your newly created project, add a reference to the ShinobiEssentials framework, and the bundle which contains its resources. Instructions for doing this can be found in the first section of the EssentialsUserGuide.

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 ShinobiEssentials-Bridging-Header.h file, which is inside the Headers directory of the ShinobiEssentials.framework.

Setting the Swift project's bridging header file

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

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

Note that this path will vary based on the location of the framework on your file system.

Adding a SlidingOverlay

In ViewController.swift’s viewDidLoad, create the SlidingOverlay, and add it to the main view:

let slidingView = SEssentialsSlidingOverlay(frame: view.bounds, andToolbar: true)
view.addSubview(slidingView)

And in only a few lines of code, we can run the app and start to see the SlidingOverlay already working. We can already use the button to open and close the underlay, and swipe left and right to open or close it;

Customizing the Views

Next, we will add some “Hello” messages to the Overlay and Underlay. In viewDidLoad, initialize the labels and add them as a subviews of the SlidingOverlay’s overlay and underlay respectively.

let overlayLabel = UILabel(frame: slidingView.overlay.bounds)
overlayLabel.text = "Hello Overlay"
overlayLabel.autoresizingMask = .FlexibleWidth | .FlexibleHeight
overlayLabel.textAlignment = NSTextAlignment.Center
slidingView.overlay.addSubview(overlayLabel)

let underlayLabel = UILabel(frame: slidingView.underlay.bounds)
underlayLabel.text = "Hello Underlay"
underlayLabel.autoresizingMask = .FlexibleWidth | .FlexibleHeight
underlayLabel.textAlignment = NSTextAlignment.Center
slidingView.underlay.addSubview(underlayLabel)

With that, you should have labels attached to your Overlay and Underlay!

Removing the title bar

The SlidingOverlay has a title bar by default, which contains a button to open and close the Underlay. Swiping inside the control will also open and close the overlay, so it’s not required that the top bar is displayed. Whether or not a SlidingOverlay has a toolbar is determined at construction time, so to remove the toolbar simply change true to false:

...
let slidingView = SEssentialsSlidingOverlay(frame: view.bounds, andToolbar: false)
...

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

Quick Start Guide for Xamarin.iOS

Xamarin.iOS: Introduction

The following guide will get you up-and-running with the SEssentialsSlidingOverlay component as quickly as possible. In this guide, we will introduce you to the key features of the SlidingOverlay, including initial project setup, customizing the overlay and underlay, and getting the two to communicate properly. You can follow along with the related code sample: SlidingOverlayGettingStarted.sln.

Xamarin.iOS: Creating a SlidingOverlay

Start up Xamarin Studio and create a new project (File / New / Solution), then selecting C# / iOS / Universal / Single View Application as your project type, naming your project ‘SlidingOverlayGettingStarted’.

Within your newly created project, add a reference to the ShinobiEssentials.dll. To do this, right click the References folder under your newly create project and choose ‘Edit References…’. Then select ‘.Net Assembly’ and browse to where you unpacked the ShinobiEssentials zip file. The dll can be found within the Xamarin.iOS / lib folder. Be sure to click ‘Add’ after selecting the dll to add it to your project, and close the window.

To check that the dll is correctly referenced, expand the References folder and you should see the ShinobiEssentials.dll listed as a reference.

Firstly, add a member variable to the view controller for the Sliding Overlay. Open up SlidingOverlayGettingStartedViewController.cs, add a using directive for the ShinobiEssentials namespace, and define the member variable as follows:

...
using ShinobiEssentials;

namespace SlidingOverlayGettingStarted
{
    public partial class SlidingOverlayGettingStartedViewController : UIViewController
    {
        SEssentialsSlidingOverlay slidingView;

        public SlidingOverlayGettingStartedViewController ()
            : base ("SlidingOverlayGettingStartedViewController", null)
        {
        }
        ...
    }
}

Further down the view controller, within the generated ViewDidLoad method create an instance of the SlidingOverlay and add it to the view:

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

    slidingView = new SEssentialsSlidingOverlay (View.Frame, true);
    View.AddSubview (slidingView);
}

And in only a few lines of code, we can run the app and start to see the SlidingOverlay already working. We can already use the button to open and close the underlay, and swipe left and right to open or close it:

Xamarin.iOS: Customizing the Views

The overlay and underlay are standard UIView objects, so we can add sub-views in the standard manner. Add a label to the overlay and underlay by updating the ViewDidLoad method with the following:

public override void ViewDidLoad ()
{
    ...
    // Setup Overlay
    UILabel overlayLabel = new UILabel (new RectangleF(10, 10, 100, 100)) {
        BackgroundColor = UIColor.Clear,
        Text = "Hello, World!",
        TextColor = UIColor.White,
    };
    slidingView.Overlay.AddSubview (overlayLabel);

    // Setup Underlay
    UILabel underlayLabel = new UILabel (new RectangleF(10, 10, 200, 100)) {
        BackgroundColor = UIColor.Clear,
        Text = "Hello, Underlay!",
        TextColor = UIColor.White
    };
    slidingView.Underlay.AddSubview (underlayLabel);
}

If you now run your project you will see labels attached to your overlay and underlay:

Xamarin.iOS: Removing the title bar

The SlidingOverlay has a title bar by default, which contains a button to open and close the Underlay. Swiping inside the control will also open and close the overlay, so it’s not required that the top bar is displayed. Whether or not a SlidingOverlay has a toolbar is determined via the constructor, so to remove the toolbar simply change true to false, inside the ViewDidLoad method:

...
SEssentialsSlidingOverlay slidingView = new SEssentialsSlidingOverlay (View.Frame, false);
...

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

ShinobiEssentials SlidingOverlay Control Overview

The SEssentialsSlidingOverlay offers an easy way to show and hide a small panel, allowing it to be shown when needed, without it taking up screen space when it is no longer required. This section describes the features and concepts behind the SlidingOverlay.

Overlay and Underlay

The Overlay and Underlay are the two panels on the SlidingOverlay. The Overlay shows the majority of your application view, while the underlay allows an additional view to be displayed when required, without navigating off the page or giving up screen space when no longer required.

The Overlay is shown on top of the Underlay, and can be moved across to completely hide the Underlay, or moved back to reveal it. The Underlay will be displayed on the left by default, but can appear at any of the four edges.

The Underlay can be shown or hidden by swiping it in or out, using the button on the toolbar, or by programmatically calling toggleUnderlayAnimated:, showUnderlayAnimated: or hideUnderlayAnimated:. The underlay size can be customized, either as a percentage of the screen size, or as an exact pixel size.

The Delegate

The SEssentialsSlidingOverlay uses a delegate as per the standard UIKit pattern, to notify your application when the user interacts with the SlidingOverlay. In order to react to the user opening and closing the SlidingOverlay, you need to supply the SlidingOverlay with a class adopting the SEssentialsSlidingOverlayDelegate protocol.

The methods on the delegate protocol follow these conventions;

  • should - delegate methods prefixed with ‘should’ are invoked before a user interaction is processed. The ‘should’ methods give you the opportunity to cancel an interaction. For example, you can use a ‘should’ method to cancel the movement of the SlidingOverlay.
  • will - delegate methods prefixed with ‘will’ are invoked just before the interaction is processed. These are not cancellable. You typically implement a ‘will’ method if you need to capture the state of the SlidingOverlay just before a change occurs.
  • did - delegate methods prefixed with ‘did’ are invoked after the interaction has been processed. When the ‘did’ method is invoked the SlidingOverlay state will have changed to reflect the change due to the user interaction.

Styling

You can control the look and feel of the SlidingOverlay using the instance of the SEssentialsSlidingOverlayStyle object which it contains. In the style, you can customize the following aspects of a sliding overlay:

  • The overlay. You can customize its background color, and the texture which is applied to it.
  • The underlay. You can customize its background color, and the texture which is applied to it.
  • The toolbar. You can customize its background color, the texture which is applied to it, and the look of the button on the toolbar.
  • The decoration which is applied to the sliding overlay. This refers to the shine effect which is applied to the toolbar, the chisel which is drawn between the toolbar and the overlay, and the drop shadow which is drawn below the overlay onto the underlay. The images below show a sliding overlay with and without decoration.

With (left) and without (right) shine, chisel and shadow

Customizing the images in the sliding overlay

The sliding overlay contains a set of images:

  • An image for the toolbar button in its normal state.
  • An image for the toolbar button in its pressed state.
  • A mask for the button, which allows you to tint the button.

The style contains these images. Once you’ve created the style, the images are readonly. You can customize the images in the style when you construct it.

To do this, you first create an instance of a SEssentialsSlidingOverlayImagesWrapper object. This has properties for each of the images in the sliding overlay. You can then set the properties on the images wrapper which you would like to customize. Any properties on the images wrapper which aren’t set will just use the default image. An example is shown below where we customize the pressed image for the toolbar button:

SEssentialsSlidingOverlayImagesWrapper *customImagesWrapper = [SEssentialsSlidingOverlayImagesWrapper new];
customImagesWrapper.buttonPressedImage = [UIImage imageNamed:@"myPressedImage.png"];

SEssentialsSlidingOverlayStyle *myStyle = [[SEssentialsSlidingOverlayStyle alloc] initWithTheme:yourTheme customImages:customImagesWrapper];

SEssentialsSlidingOverlay *mySlidingOverlay = [[SEssentialsSlidingOverlay alloc] initWithFrame:myFrame andToolbar:YES style:myStyle];

iOS7 vs. Earlier iOS versions

In the SEssentialsIOS7Theme, we use images very differently from the other themes. By default, iOS7 devices will use the SEssentialsIOS7Theme, while devices on previous versions will use the SEssentialsDarkTheme.

In both cases, the Sliding Overlay’s button is tintable, but in iOS7, we tint the 3 lines, whilst in previous versions we tinted the background, and the lines remained white.

Overlay button in iOS7 theme (left) and Dark theme (right)

In addition, the general style of the images and theme in iOS7 is a much flatter, less cluttered appearance, in keeping with the Apple style guidelines. The shadow is much reduced, and the texture has been removed. The color scheme favors differing shades of light grey, with the occasional splash of color.

To create your own button, you will need to provide buttonImage, buttonPressedImage and buttonMask. If you don’t want to tint the image, then the mask can just be a blank image, of the same dimensions as the other two images in the set. The same applies if you only want the tint, with no background.

Default Style Settings

An instance of the style object is created using a SEssentialsTheme object. This sets the default values of the style properties. The following default settings are taken from the theme:

  • The primaryTintColor on the theme is used for the overlay (overlayTintColor) and the toolbar (toolbarTintColor).
  • The primaryTexture on the theme is used for the background texture of the overlay (overlayTexture) and the toolbar (toolbarTexture).

  • The secondaryTintColor on the theme is used for the underlay (underlayTintColor).

  • The secondaryTexture on the theme is used for the background texture of the underlay (underlayTexture).

  • The tertiaryTintColor on the theme is used for the toolbar button (buttonTintColor).

The theme provides the following default settings for decoration:

  • The shadowColor and shadowDepth properties on the theme map to the properties with the same name on the style.
  • The shineColor on the theme sets the color of the shine on the toolbar (shineColor).
  • The primaryDecorationTintColor and the secondaryDecorationTintColor set the primary and secondary colors for the chisel between the toolbar and the overlay (chiselPrimaryColor and chiselSecondaryColor).

ShinobiEssentials SlidingOverlay How-to Guides

How-to create overlay and underlay from XIBs

A SlidingOverlay is composed of two views: an overlay and an underlay. You can create content for your overlay and underlay using Xcode’s interface builder. You can follow along with our related code sample: SlidingOverlayHowToCreateOverlayAndUnderlayFromXIBs.xcodeproj.

Firstly you need to create two xib files and size them to match the desired size of your sliding overlay. You can then add content to the xib files as you normally would using interface builder.

Once you have created your xib files you can then add them to your SlidingOverlay.

NSArray *overlayXib = [[NSBundle mainBundle] loadNibNamed:@"Overlay" owner:self options:nil];
UIView *overlayView = overlayXib[0];
[slidingOverlay.overlay addSubview:overlayView];

Firstly you create a UIView from your xib and then simply add it to the overlay as a subview. Similarly for adding your underlay content to the SlidingOverlay’s underlay:

NSArray *underlayXib = [[NSBundle mainBundle] loadNibNamed:@"Underlay" owner:self options:nil];
UIView *underlayView = underlayXib[0];
[slidingOverlay.underlay addSubview:underlayView];

Finally you can set the reveal amount of your underlay to match the size of your view created from the xib.

slidingOverlay.underlaySizeType = SEssentialsUnderlayPixelSize;
slidingOverlay.underlayRevealAmount = underlayView.bounds.size.width;

Here we set underlaySizeType to SEssentialsUnderlayPixelSize so that we can specify the reveal amount in pixels. We then set the underlayRevealAmount to be equal to the width of our underlay view.

Note that you must tell your underlay view not to autoresize when you create it in interface builder. If you do not set autoresizing on the underlay then it may not be the size you expect when setting underlayRevealAmount.

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

How-to create a two-sided SlidingOverlay

The SlidingOverlay allows you to show and hide a second view from one side. However sometimes we may want to have a hidden view on one side, and a different hidden view on the other. For example, having menus on both sides. To do this, we will add a SlidingOverlay as the overlay of another SlidingOverlay, and configure the gestures. You can follow along with our related code sample: SlidingOverlayHowToDoubleOverlay.xcodeproj.

To work properly, we will be using the UIGestureRecognizerDelegate methods, and attaching them to the swipe gesture of each SlidingOverlay, available on the gestureRecognizer property. To do this, make your ViewController adopt the protocol:

@interface ViewController : UIViewController<UIGestureRecognizerDelegate>

When you create your SlidingOverlays, set the ViewController as the delegate of both Overlay’s gestureRecognizer objects, and set the underlayLocation of one to the opposite side of the other:

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

    //Set up left
    overlayLeft = [[SEssentialsSlidingOverlay alloc] initWithFrame:self.view.frame andToolbar:NO];
    overlayLeft.gestureRecognizer.delegate = self;
    [self.view addSubview:overlayLeft];

    //Set up right
    overlayRight = [[SEssentialsSlidingOverlay alloc] initWithFrame:self.view.frame andToolbar:NO];
    overlayRight.underlayLocation = SEssentialsSlidingOverlayLocationRight;
    overlayRight.gestureRecognizer.delegate = self;
    [overlayLeft addSubview:overlayRight];
}

To make both overlays work, we need to implement gestureRecognizer:shouldRecognizeSimultaneouslyWithGestureRecognizer: to allow simultaneous gestures, and gestureRecognizer:shouldReceiveTouch: to block both overlays from opening simultaneously:

-(BOOL)gestureRecognizer:(UIGestureRecognizer *)gesture shouldRecognizeSimultaneouslyWithGestureRecognizer:(UIGestureRecognizer *)otherGestureRecognizer
{
    return YES;
}

-(BOOL)gestureRecognizer:(UIGestureRecognizer *)gesture shouldReceiveTouch:(UITouch *)touch
{
    //Only open the underlay if the other underlay is hidden
    return [[self oppositeOverlay:gesture] underlayHidden];
}

-(SEssentialsSlidingOverlay*)oppositeOverlay:(UIGestureRecognizer*)gesture
{
    return (gesture.view == overlayLeft) ? overlayRight : overlayLeft;
}

To simplify the code, we have added a small utility method to find the oppositeOverlay:. The main logic here is that we detect if we are swiping left or right, and only allow one overlay to open if the other is closed (underlayHidden). When both are hidden, either one can open.

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

How-to provide custom styling to a SlidingOverlay

It is easy to style the SlidingOverlay to ensure it looks how you would like. This how-to guide will show you how to change the styling of the SEssentialsSlidingOverlay. You can follow along with the related sample project: SlidingOverlayHowToCustomStyling.xcodeproj.

The code below creates and provides some quick customizations to a SlidingOverlay.

// Create a sliding overlay with a toolbar
SEssentialsSlidingOverlay *slidingOverlay = [[SEssentialsSlidingOverlay alloc] initWithFrame:self.view.frame
                                                                                  andToolbar:YES];

// Change the size and location of the underlay
slidingOverlay.underlayLocation = SEssentialsSlidingOverlayLocationTop;
slidingOverlay.underlayRevealAmount = 0.5;

The location and size of the underlay can be customized through use of the underlayLocation and underlayRevealAmount properties on the SEssentialsSlidingOverlay class. In the above case we have set the underlay to be revealed from the top of the view and for it to be half the height of the overlay.

Every SlidingOverlay has a style property of type SEssentialsSlidingOverlayStyle. By default the properties on the style are set to sensible values or may be inherited from the SEssentialsTheme, see Styling for more details on how the SlidingOverlays style inherits from the theme. It is by using these properties, and setting them to values which you choose, that you can further customize the style of your SlidingOverlay.

// Change the color of the overlay, underlay and toolbar
slidingOverlay.style.overlayTintColor = [UIColor colorWithRed:0.4 green:0.2 blue:0.2 alpha:1.0];
slidingOverlay.style.underlayTintColor = [UIColor colorWithRed:0.2 green:0.2 blue:0.6 alpha:1.0];
slidingOverlay.style.toolbarTintColor = [UIColor colorWithRed:0.6 green:0.2 blue:0.6 alpha:1.0];

// Change the color of the toolbar button
slidingOverlay.style.buttonTintColor = [UIColor blackColor];

The code above changes the colors of various parts of the SlidingOverlay. The overlay, underlay and toolbar all have custom colors set. The final change made here is to apply a custom color to the button on the toolbar.

It is also possible to supply a custom button for the toolbar by changing the button property of the SlidingOverlay’s toolbar. Since this uses a custom button you will need to give it a method to display/hide the underlay when tapped.

There are further properties which can be used to style the SlidingOverlay. A full list is available and documented on the SEssentialsSlidingOverlayStyle API.

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