Getting Started Guide
- Importing the JotTouchSDK
- Compiling the project with the JotTouchSDK
- Listening for Stylus Connection Events
- Configuring Drawing & Palm Rejection Events
- Listening for Pressure Data
- Enabling Palm Rejection
- Configuring the shortcut buttons
- Adding the Jot Settings Panel
- Persistence
###Download the JotTouchSDK
You can download the latest version of the JotTouchSDK from:
https://github.com/Adonit/JotTouchSDK
or you can clone the repository directly with:
$ git clone https://github.com/Adonit/JotTouchSDK.git###Adding the JotTouchSDK to your project After downloading the SDK, copy the included JotTouchSDK.framework into your project’s folder.
###Building your app with the Jot Touch SDK
Next, it’s time to link the JotTouchSDK framework to your app. To do that, select your project’s name in the Project Navigator in Xcode (1), then select your app’s target (2), then choose Build Phases from the top bar navigation (3), and finally press the + button to link a new framework to your project (4).
Choose the "Add Other" button from the framework modal that appears, and then find and select the JotTouchSDK.framework file from the Finder window.
This will add the JotTouchSDK framework to the list of frameworks that your app will link against when it builds.
The JotTouchSDK also requires two other iOS frameworks: CoreMotion and CoreBluetooth. Press the + button again, and choose these two frameworks from the list provided by the Xcode framework modal.
After you are done, your project should be linking against at least these 3 frameworks:
Lastly, you'll need to set the "Other Linker Flags" in your project's build settings. To edit, simply add "-ObjC" to the linker flags as shown below:
- Select your project’s name in the Project Navigator in Xcode
- Select your app’s Project
- Choose Build Settings
- Double check that All and Combined are selected
- Scroll down to the Linking section to find "Other Linker Flags"
- Double click and add the "-ObjC" flag
Now you’re ready to start using the JotTouchSDK!
# Compiling the project with the JotTouchSDK
###Including the JotTouchSDK To use the JotTouchSDK from any of your project’s source files, simply include the JotStylusManager from the SDK’s folder:
#import <JotTouchSDK/JotTouchSDK.h>###Enable the JotTouchSDK Before you can connect to a Jot stylus, you’ll need to explicitly enable the SDK from within your application. By default, the JotTouchSDK is disabled. This call will enable the SDK to listen for stylus connections over Bluetooth.
[[JotStylusManager sharedInstance] enable];To re-disable the SDK after enabling, simply:
[[JotStylusManager sharedInstance] disable];When the Jot SDK is disabled, it will never send any calls to the delegates you specify on the JotStylusManager or try and connect to any Jots via Bluetooth.
After connecting with a Jot for the first time, the Jot Touch SDK will always look for that Jot for the duration the SDK is enabled. This makes reconnecting extremely quick / reliable for the user, however it requires your application to expose this functionality in one of two ways:
- Expose controls to enable / disable the Jot Touch SDK from the UI. This is required because disabling the Jot Touch SDK clears the preferred stylus.
- Add an instance of the Jot Settings View Controller to your application to manage this for you.
For the best user experience, we recommend showing the connection status in your application's UI at all times.
With this Bluetooth 4.0 based SDK, there is no need for a user to pair the device through iOS Settings. The stylus connectivity and pairing process is conveniently handled within the SDK transparent to your app and end user.
When the SDK is enabled, it will be in one of four possible connection states.
Scanning:
- This means that there are no styluses connected. In this state it is looking for any advertising Jots.
Pairing:
- This means that there are multiple Jots available to be used. In this state all of these Jots have been connected to, and the SDK is waiting for one of them to be drawn with so that it can Pair with that stylus.
Connected:
- This means that there is a single Jot connected.
Disconnected:
- This means that the last stylus used cannot be found or no stylus has ever been connected. The SDK is scanning but will only connect to the last used stylus.
Off
- This means that the last stylus used was powered off. The SDK is no longer scanning for that stylus.
Whenever the SDK switches between any of these states (including the Off state), a notification is sent out. You can listen for this by setting up an observer.
[[NSNotificationCenter defaultCenter] addObserver: self
selector:@selector(connectionChange:)
name: JotStylusManagerDidChangeConnectionStatus
object:nil];This will fire the defined selector (connectionChange: in this case) whenever there is a change.
Then in your method you can access the connectionStatus property on the JotStylusManager and use it to notify the user of the current state. For example, here we are settings the title of a button based on the connection status.
(void)connectionChange:(NSNotification *) note
{
NSString *text;
switch([[JotStylusManager sharedInstance] connectionStatus])
{
case JotConnectionStatusOff:
text = @"Off";
break;
case JotConnectionStatusScanning:
text = @"Scanning";
break;
case JotConnectionStatusPairing:
text = @"Pairing";
break;
case JotConnectionStatusConnected:
text = @"Connected";
break;
case JotConnectionStatusDisconnected:
text = @"Disconnected";
break;
default:
text = @"";
break;
}
[settingsButton setTitle: text forState:UIControlStateNormal];
}The palmRejectorDelegate property on the JotStylusManager handles all stylus drawing notifications. In order for the JotTouchSDK to determine which of the touch events belong to a finger or stylus, the palmRejectorDelegate needs to intercept all of the UITouch events on your UIView. Even if your app will not be using our palm rejection, all events should still be passed through in order to allow proper interactions.
To register your view so that the JotTouchSDK and the palmRejectorDelegate can listen to these events, call the registerView: method on the JotStylusManager, as below:
[[JotStylusManager sharedInstance] registerView:yourDrawingView]That’s all that is needed for the JotTouchSDK to start sending stylus events to your delegates.
To unregister a view, perhaps when deallocating your view, or changing the active drawing view, you can call the related method:
[[JotStylusManager sharedInstance] unregisterView:yourDrawingView]NOTE: The palmRejectorDelegate property on the JotStylusManager handles all stylus drawing notifications.
The JotTouchSDK categorizes each UITouch on a registered view as either a palm, finger, or stylus. If palm rejection is turned on, then only touch events that match a Jot stylus will be forwarded to the delegate. If palm rejection is turned off in the SDK, then every event is considered a stylus event and will be forwarded to the palmRejectorDelegate.
Many applications may add additional gestures to their drawing UIView, such as a pinch-to-zoom gesture. If the user rests their palm on the screen, these gestures might be triggered accidentally. The JotTouchSDK also notifies the palmRejectorDelegate when any additional gestures should be disabled. This is based on when the user is actively drawing with the Jot stylus.
#pragma mark - PalmRejectionDelegate
-(void)jotStylusTouchBegan:(NSSet*)jotTouches{
// a Jot stylus has begun to draw on the screen
}
-(void)jotStylusTouchMoved:(NSSet*)jotTouches{
// a Jot stylus is moving on the screen
}
-(void)jotStylusTouchEnded:(NSSet*)jotTouches{
// a Jot stylus has ended normally on the screen
}
-(void)jotStylusTouchCancelled:(NSSet*)jotTouches{
// a stylus event has been cancelled on the screen
}
-(void)jotSuggestsToDisableGestures{
// the Jot Touch SDK has determined that the user’s palm is likely
// resting on the screen or the user is actively drawing with the
// Jot stylus, and we recommend to disable any other gestures
// that might be attached to that UIView, such as a pinch-to-zoom
// gesture
}
-(void)jotSuggestsToEnableGestures{
// The user’s palm has lifted and drawing has stopped, so it is
// safe to re-enable any other gestures on the UIView
}JotStylusManager has a property to help tune the palm rejection behavior. It allows you to tune the responsiveness of the suggestions to enable/disable gestures.
#pragma mark - JotStylusManager
/**
* The amount of time (in seconds) between the stylus being lifted from the screen
* and the notification that gestures should be enabled. Defaults to 1 second.
*/
@property (nonatomic) NSTimeInterval suggestionToEnableGesturesDelay;### Writing Style and Hand Preference
Jot palm rejection can also be optimized for left vs right handed and writing style orientation. The SDK will default to right handed users with a right-average style. A user's selected preference can be set with the JotWritingStyle property on the JotStylusManager. Setting the JotWritingStyle property will overwrite any preference set on JotPalmRejectionOrientation.
NOTE: JotPalmRejectionOrientation is marked for deprication in a later release.
typedef NS_ENUM(NSUInteger, JotWritingStyle) {
JotWritingStyleRightHorizontal = 2,
JotWritingStyleRightAverage = 1,
JotWritingStyleRightVertical = 0,
JotWritingStyleLeftHorizontal = 5,
JotWritingStyleLeftAverage = 4,
JotWritingStyleLeftVertical = 3,
};For each of the palm rejection delegate methods in the section above, an NSSet of JotTouch objects is passed in as the only parameter. Each of the JotTouch objects remember their own associated pressure value from the stylus, and can also calculate the location of the touch in a UIView.
The example code below shows how to fetch the pressure data from a JotTouch object, as well as how to find the location of the stylus in a UIView.
-(void)jotStylusTouchMoved:(NSSet*)jotTouches{
JotTouch* anyJotTouch = [jotTouches anyObject];
// pressure is between 0 and 2047 inclusive
uint pressureValue = anyJotTouch.pressure;
// the JotTouch object can calculate the position of the touch
// more accurately than a UITouch object, since this is calibrated
// to the exact location of the Jot stylus.
CGPoint locationInView = [anyJotTouch locationInView:self];
// You can also easily get UIKit's UITouch object associated with the JotTouch
UITouch* rawTouch = anyJotTouch.touch;
}Each JotTouch object remembers the pressure of the stylus at its own touch moment. So even if you save the JotTouch object and ask it about the pressure data seconds or minutes after the touch has occurred, it will still report the correct pressure data for that touch.
However, if you want to know the pressure value of the stylus right now, regardless of any touch events, then you can also ask the JotStylusManager directly. The JotStylusManager will return the value of the stylus pressure at the current moment, even if there is no associated touch object.
// Lastly, if you want the raw pressure data of the stylus
// at this moment, simply ask the JotStylusManager
uint rawPressure = [[JotStylusManager sharedInstance] getPressure];###Setting a Default Pressure When the SDK reports a stylus event, it will include the stylus tip pressure value between 0 and 2047. However, when a stylus is not connected to the SDK, you can decide what pressure value that the SDK should report.
[[JotStylusManager sharedInstance] setUnconnectedPressure:1024];This is particularly useful if you are using the pressure value to help determine the width of a pen stroke, for instance. You can set this unconnected pressure value to a reasonable default value for your algorithm. In this way, you can blindly use the pressure data reported by the SDK regardless of a Jot stylus being connected, and be confident that the value will be appropriate for your width algorithm.
The JotTouchSDK also optionally provides advanced palm rejection whenever a Jot stylus is connected and resting on the screen.
To enable palm rejection:
[[JotStylusManager sharedInstance] setRejectMode:YES];When palm rejection is enabled, only events that are known to be Jot stylus events will be reported by the SDK and sent to the palmRejectorDelegate of the JotStylusManager. When palm rejection is disabled, all touch events will be reported as stylus events, and will all share the same pressure value of the connected Jot Touch.
Note: Palm rejection relies on the orientation of the status bar with in your application, if your application does not support multiple orientations, palm rejection may not behave as expected.
To set up an action for the buttons, add the following code when your application initializes, usually in your root view controller:
[[JotStylusManager sharedInstance] addShortcutOptionButton1Default: [[JotShortcut alloc]
initWithDescriptiveText:@"Undo"
key:@"undo"
target:self
selector:@selector(undo)
repeatRate:0.1]];There is a parallel method for the 2nd button beginning with
addShortcutOptionButton2Default:These two methods will set the default button behaviors, and will call the target’s selector each time the button is pressed. The repeatRate determines how often the selector will be called if the user holds down the stylus button.
NSNotificationCenter notifications to the defaultCenter are available for button 1 and button 2 up and down events. These are named:
- JotStylusButton1Down
- JotStylusButton1Up
- JotStylusButton2Down
- JotStylusButton2Up
You can also configure additional options that the user can choose for the button behavior. To add user configurable options for the buttons, simply call the method
addShortcutOption:If the user changes the active shortcut, either through the provided Jot Settings View Controller or otherwise, You can always access the current shortcut through the button1Shortcut and button2Shortcut properties of the JotStylusManager. These properties are readwrite, so you can also set to any JotShortcut.
Included in the JotTouchSDK is a setting panel that you may use in your application. It includes the following settings and information.
- Jot Touch SDK on/off (optional)
- Connection Status
- Battery Level
- Support Links
- Shortcut Button Options
- Writing Style Options
- Palm Rejection on/off (optional)
###Creating a Jot Settings View Controller
The Jot Settings View Controller will display an appropriate look and feel depending on the device's current version.
To create an instance of the Jot Settings View Controller with both the SDK on/off switch and palm rejection views showing:
JotSettingsViewController* settings = [[JotSettingsViewController alloc] init];To create an instance of the Jot Settings View Controller without the SDK on/off switch:
JotSettingsViewController* settings = [[JotSettingsViewController alloc] initWithOnOffSwitch: NO];To create an instance of the Jot Settings View Controller without the SDK on/off switch AND without palm rejection showing:
JotSettingsViewController* settings = [[JotSettingsViewController alloc] initWithOnOffSwitch: NO andShowPalmRejection:NO];The Jot Settings View Controller will adapt to fit any size view, however we recommend placing it in a pop over such as:
JotSettingsViewController* settings = [[JotSettingsViewController alloc] initWithOnOffSwitch: YES];
if(popover){
[popover dismissPopoverAnimated:NO];
}
popover = [[UIPopoverController alloc] initWithContentViewController:settings];
[popover presentPopoverFromRect:sender.frame inView:self.view permittedArrowDirections:UIPopoverArrowDirectionUp animated:YES];
[popover setPopoverContentSize:CGSizeMake(300, 400) animated:NO];###Building your own Settings Panel
If you prefer not to to use the Settings View Controller the API provides all necessary Methods to create your own settings panel.
The SDK automatically persist the following settings.
- the preferred stylus type
- the preferred stylus name
- palm rejection on/off
- writing style
- palm rejection handedness from writing style (left/right)
- shortcut button selection