Getting Started Guide
This guide is a work in progress. Let us know your your thoughts by submitting an issue with the label "getting started guide" to the project.
- Team Adonit.
- Importing the JotTouchSDK
- Compiling the project with the JotTouchSDK
- Listening for Stylus Connection Events
- Enabling Palm Rejection
- Listening for Pressure Data
- Configuring the shortcut buttons
- Adding the Jot Settings Panel
###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 [email protected]: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.
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: AudioToolbox 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" and "-all_load" to the linker flags as shown below:
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/JotStylusManager.h>###Enable the JotTouchSDK Before you can connect to a Jot Touch 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] setEnabled:YES];To re-disable the SDK after enabling, simply:
[[JotStylusManager sharedInstance] setEnabled:NO];When the JotSDK 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 making reconnecting extremely quick / reliable for the use, however it requires the 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.
###Register Your Drawing UIView In order for the JotTouchSDK to determine which of the touch events belong to a finger or stylus, it needs to intercept the UITouch events on your UIView. To register your view so that the JotTouchSDK 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.
For the best experience, we recommend showing the connection status in your application's UI at all times.
Whenever a Jot Touch stylus connects or disconnects from the SDK, events are sent to the JotStylusManager’s connectionDelegate. To setup a connection delegate, simply set the property on the manager itself:
[[JotStylusManager sharedInstance] setConnectionDelegate:myDelegate];The delegate must conform to the StylusConnectionDelegate protocol:
#pragma mark - StylusConnectionDelegate
-(void)jotStylusConnected: (id <StylusConnection>)conn{
// a Jot Touch stylus has connected to the SDK
}
-(void)jotStylusDisconnected: (id <StylusConnection>)conn{
// a Jot Touch stylus has explicitly disconnected
}
-(void)jotStylusBatteryUpdate:(uint)batteryLevel{
// the Jot battery level has been updated
// values are between 0 and 100. Anything 10 or less means
// the user should recharge the Jot
}The JotTouchSDK also optionally provides advanced palm rejection whenever a Jot Touch stylus is connected. To enable palm rejection:
[[JotStylusManager sharedInstance] setRejectMode:YES];When palm rejection is enabled, only events that are known to be Jot Touch 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.
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 Touch 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 both when the palm is detected as well as 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
}Jot palm rejection can also be optimized for left vs right handed users. The SDK will default to right handed users, but can be set with the palmRejectionOrientation property on the JotStylusManager.
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 Touch stylus being connected, and be confident that the value will be appropriate for your width algorithm.
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]
initWithShortDescription:@"Undo"
key:@"undo"
target:self selector:@selector(undo)
repeatRate:100]];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.
If using the Jot Touch UI elements, 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 JotSettingsController or otherwise, you can always access the current short.cut 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 (Bluetooth 4.0 styli only)
- Support Links
- Shortcut Button Options
- Palm Rejection Options (Bluetooth 4.0 styli only)
###Creating a Settings View Controller
To creating an instance of the Jot Settings View Controller.
SettingsViewController* settings = [[SettingsViewController alloc] initWithSwitch: YES];Optionally, to create an instance of the Jot Settings View Controller without the SDK on/off switch.
SettingsViewController* settings = [[SettingsViewController alloc] initWithSwitch: NO];The Jot Settings View Controller will adapt to fit any size view, however we recommend placing it in a pop over such as:
SettingsViewController* settings = [[SettingsViewController alloc] initWithSwitch: YES];
if(popoverController){
[popoverController 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 this UI the API provides all necessary Methods to create your own.