====== SHThumbstick ======
---- dataentry extension ----
type                   : extension
author_mail            : shilo86@gmail.com Shilo White
description            : A robust thumbstick.
lastupdate_dt          : 2011-09-09
compatible             : v2.X
depends                : 
tags                   : thumbstick, joystick, joypad, dpad, controller
homepage_url           : https://gist.github.com/878049
download_url           : https://gist.github.com/gists/878049/download
demo (old)_url         : http://shilo.coarsemode.com/sparrow/extensions/shthumbstick/ThumbstickSample.zip
basic sample (old)_url : http://cl.ly/1Z0V321y2C1D3j2c3I0C
----


===== Description =====
SHThumbstick class will allow you to create multiple thumbsticks to a game with ease. You can choose to use images or go without images. You can change the thumbstick type to static, relative, absolute, float. More details about these types are in the sample project. There's many other properties to customize the thumbstick, but can also be as simple as you like.

===== Sample =====
[[http://shilo.coarsemode.com/sparrow/extensions/shthumbstick/ThumbstickSample.zip|{{http://shilo.coarsemode.com/sparrow/extensions/shthumbstick/ThumbstickScreenshot.png}}]]
  * Project: [[http://shilo.coarsemode.com/sparrow/extensions/shthumbstick/ThumbstickSample.zip|Thumbstick Showcase (OLD)]]
  * Screenshot: [[http://shilo.coarsemode.com/sparrow/extensions/shthumbstick/ThumbstickScreenshot.png|ThumbstickScreenshot.png]]
  * Recording: [[http://shilo.coarsemode.com/sparrow/extensions/shthumbstick/ThumbstickRecording.mov|ThumbstickRecording.mov]]

===== Examples =====
==== Initialization Example =====
<code objc>
//initialize a thumbstick
SHThumbstick *absoluteThumbstick = [SHThumbstick thumbstick];
 
//set the inner image
absoluteThumbstick.innerImage = [SPImage imageWithContentsOfFile:@"innerThumbstick.png"];
 
//set the outer image
absoluteThumbstick.outerImage = [SPImage imageWithContentsOfFile:@"outerThumbstick.png"];
 
//change the thumbstick type to absolute, which will only appear on touch
absoluteThumbstick.type = SHThumbstickAbsolute;
 
//set the bounds for landscape
absoluteThumbstick.bounds = [SPRectangle rectangleWithX:0 y:0 width:480 height:320];
 
//change the inner radius to 0
absoluteThumbstick.innerRadius = 0;
 
//change the outer radius to 40
absoluteThumbstick.outerRadius = 40;
 
//draw the values of innerRadius, outerRadius, and bounds to screen
absoluteThumbstick.debugDraw = YES;
 
//add an event listener to get the event.distance and event.direction
[self addEventListener:@selector(onThumstickChanged:) atObject:self forType:SH_THUMBSTICK_EVENT_CHANGED];
 
//add the thumbstick to the stage
[self addChild:absoluteThumbstick];
</code>

==== Event Example ====
<code objc>
- (id)initWithWidth:(float)width height:(float)height {
	if (self = [super initWithWidth:width height:height]) {
		SHThumbstick *thumbstick = [SHThumbstick thumbstick];
		thumbstick.innerImage = [SPImage imageWithContentsOfFile:@"innerThumbstick.png"];
		thumbstick.outerImage = [SPImage imageWithContentsOfFile:@"outerThumbstick.png"];
		thumbstick.debugDraw = YES;
		[self addChild:thumbstick];
 
		[thumbstick addEventListener:@selector(onThumbstickTouch:) atObject:self forType:SH_THUMBSTICK_EVENT_TOUCH];
		[thumbstick addEventListener:@selector(onThumbstickMove:) atObject:self forType:SH_THUMBSTICK_EVENT_MOVE];
		[thumbstick addEventListener:@selector(onThumbstickTouchUp:) atObject:self forType:SH_THUMBSTICK_EVENT_TOUCHUP];
		[thumbstick addEventListener:@selector(onThumbstickChanged:) atObject:self forType:SH_THUMBSTICK_EVENT_CHANGED];
    }
    return self;
}
 
- (void)onThumbstickTouch:(SHThumbstickEvent *)event {
	NSLog(@"onThumbstickTouch distance:%f direction:%f", event.distance, event.direction);
}
 
- (void)onThumbstickMove:(SHThumbstickEvent *)event {
	NSLog(@"onThumbstickMove distance:%f direction:%f", event.distance, event.direction);
}
 
- (void)onThumbstickTouchUp:(SHThumbstickEvent *)event {
	NSLog(@"onThumbstickTouchUp distance:%f direction:%f", event.distance, event.direction);
}
 
- (void)onThumbstickChanged:(SHThumbstickEvent *)event {
	NSLog(@"onThumbstickChanged distance:%f direction:%f", event.distance, event.direction);
}
</code>

===== Instructions =====
==== To add into your Sparrow project ====
  - Download the source files here: [[https://gist.github.com/gists/878049/download]]
  - Open your desired Sparrow project
  - Drag and drop the files into the "Groups & Files" pane
  - Open "Game.h"
  - Include the extension: <code objc>#include "SHThumbstick.h"</code>
  - Save "Game.h"

==== To add directly into Sparrow source ====
  - Download the source files here: [[https://gist.github.com/gists/878049/download]]
  - Save the files into Sparrow's "/Classes/" directory
    * Example: "/sparrow/src/Classes/"
  - Navigate back one directory and open "Sparrow.xcodeproj"
    * Example: "/sparrow/src/Sparrow.xcodeproj"
  - Inside the "Groups & Files" pane, locate the "Utils" group folder
    * Example: "Sparrow -> Classes -> Utils"
  - Right click the "Display" group folder and click "Add -> Existing Files.."
  - Navigate into the "/Classes/" directory and select "SHThumbstick.h" and "SHThumbstick.m", then click "add"
  - On the next window, leave all options as default and click "add"
  - In the "Groups & Files" pane, Open "Sparrow.h"
    * Example "Sparrow -> Classes -> Sparrow.h"
  - At the bottom of the file, add: <code objc>#import "SHThumbstick.h"</code>
  - Save "Sparrow.h"
  - Close "Sparrow.xcodeproj"

===== Source Code =====
%gist(878049)%

===== Changelog =====
  * //2011-02-12:// First version

===== Todo =====
  * (EMPTY)