Kobold2dのKKInput Touchesのドキュメントメモ

Kobold2dのKKInput Touchesについてのドキュメントを、メモ用にコピペします。
元記事はここ。
Kobold2dの「My-User-Input-Project」のソースを読んでいて、ドキュメントを読む必要を感じ、ついでにメモ的な日本語も少々付加いたしました。
（KKInput gestureに関してのメモは、こちら。）

KKInput Touches

• Enable Multi-Touch
• Simple Touch Began/Ended Tests
• Touches Available
• Did you just touch my Node???
• Location of Touches
• Accessing all Touches
• Removing a Touch

Enable Multi-Touch　（マルチタッチをEnabledに）

To enable multiple touches, either set the config.lua setting EnableMultiTouch = YES or set themultipleTouchEnabled property:　

[KKInput sharedInput].multipleTouchEnabled = YES;

Simple Touch Began/Ended Tests　（Touch開始、終了を簡単に取得。 anyTouchBeganThisFrame,anyTouchEndedThisFrame）

You can quickly test if any touch began or ended in the current frame with the following methods. This is a quick & easy way to, for example, create screens which the user can dismiss by touching the screen anywhere, or having the user "touch the screen to play again".

if ([KKInput sharedInput].anyTouchBeganThisFrame) { ... } if ([KKInput sharedInput].anyTouchEndedThisFrame) { ... }

Touches Available　（指がタッチ中か確認。touchesAvailable）

To test if touches are available, ie if any finger is touching the screen, use touchesAvailable:

if ([KKInput sharedInput].touchesAvailable) { ... }

Did you just touch my Node???　（あるNodeをタッチしたか確認。isAnyTouchOnNode: touchPhase:）

You can determine if a node is being touched (oh my) with the isAnyTouchOnNode:touchPhase:method. You pass in the node like a CCSprite, CCLabelTTF, or any other CCNode derived object to test if any touch with the given phase (began, ended, any, etc) was on that node.（beganやendedやanyなどのphaseも指定できて、あるNodeのタッチを確認。）

The isAnyTouchOnNode method correctly performs the test even if the node is rotated, scaled or both.（nodeが回転したり、拡大縮小していても、isAnyTouchOnNodeは正しく動作します。）

KKInput* input = [KKInput sharedInput]; if ([input isAnyTouchOnNode:someNode touchPhase:KKTouchPhaseBegan]) {...} if ([input isAnyTouchOnNode:someNode touchPhase:KKTouchPhaseAny]) {...}

Instances of CCNode by definition have a zero contentSize, so you can not use this method to test for touches on CCNode, unless you have modified the contentSize property of the CCNode object.(CCNodeのインスタンスは、contentSizeはゼロに定義されている。だから、contentSizeプロパティを修正しないと、このメソッドはつかえない。isAnyTouchOnNode。isAnyTouchOnNode: touchPhase:) CCScene or CCLayer by definition have a contentSize that equals that of the screen/window size. You can test if a touch was on a CCScene or CCLayer object, but it makes little sense because if there is a touch on the screen, it will naturally be on the CCScene or CCLayer object — unless you have modified the contentSize property.

Location of Touches　（タッチの位置取得。locationOfAnyTouchInPhase:メソッド。）

You can get the location of any touch with locationOfAnyTouchInPhase:. You can use one of the standard phases (began, moved, stationary, ended, cancelled) or use the special Kobold2D phaseKKTouchPhaseAny to test for the location of any touch in any phase.（phaseKKTouchPhaseAnyは、Kobold2dの特別なもので、どんなphaseのどんなtouchでも位置を取得できるとのこと。）

When is this useful? Whenever you don't care which finger is at that location, or if multiple touches are disabled you can get the location of the one (any) finger on the screen.

KKInput* input = [KKInput sharedInput]; CGPoint pos = [input locationOfAnyTouchInPhase:KKTouchPhaseAny];

If no finger is currently touching the screen that is in the given phase, then CGPointZero is returned.（指がタッチしてなかったら、CGPointZeroが返される、と。）

Accessing all Touches　（全てのtouchesにアクセス。）

The most powerful way to work with touches is to obtain the list of currently available touches via thetouches property, which is a CCArray* containing zero to five KKTouch* objects.（ゼロから５つのKKTouch*オブジェクトを格納したCCArray* touchesを使えるとのこと。）

KKTouch is a wrapper for UITouch that allows you to work with touches already converted to the Cocos2D view space(KKTouchはUITouchのラッパーで、Cocos2dのview spaceに既に転換されたタッチを使えるようにしたものです), and without having to use #ifdef if you also build for Mac（Mac用にビルドする際にも、#ifdefを使う必要がありません。）. You can get the KKTouch* array and iterate over it like this:（KKTouch*配列を、以下のように取得して、繰り返すことが出来ます。）

CCArray* touches = [KKInput sharedInput].touches;//[KKInput sharedInput].touchesで取得し、CCArray *touchesに格納、と。 KKTouch* touch; CCARRAY_FOREACH(touches, touch)//CCARRAY_FOREACHというメソッドがあるのですね。便利だ。 {     // do something with touch here     mySprite.position = touch.location; }

The KKTouch location and previousLocation properties are already converted to Cocos2D view coordinates. You do not need to (and shouldn't) call CCDirector's convertGL method.　 （KKTouchのlocationとpreviousLocationプロパティは、すでにCocos2dのview座標に転換されているので、CCDirectorのconvertGLメソッドを使う必要がなく、使ってはいけません。）

Each KKTouch object corresponds to a particular finger on the screen. The same KKTouch object is used for the same finger starting when the touch "began" until the touch either "ended" or got "cancelled". ("ended"か"cancelled”になるまで、"began"によって開始されたtouchは、同じ指がタッチしている限り、KKTouchオブジェクトは維持されている、と。）

You can not rely on the array index for accessing a particular finger's KKTouch as other touches may end and get started（他のタッチが終わったり始まったりした場合は、配列中のインデックスで、特定のKKTouchにアクセスするのは信頼できません。）. You can either store and later compare the touchID property to make sure you're using the same KKTouch as before, or simply keep a weak reference to the KKTouch object. In that case you have to check that it's phase property isn't KKTouchPhaseLifted, which indicates that the KKTouch object is no longer associated with a finger on the screen.（KKTouchPhaseLiftedは、すでに指が画面から離されていて、KKTouchオブジェクトが関連づけられていないというphase） You will also want to nil your reference when the touch phase is either KKTouchPhaseEnded or KKTouchPhaseLifted.

If you ever need access to the underlying UITouch* object, you can simply cast the touchID property:

// access the underlying UITouch object if needed UITouch* uiTouch = (UITouch*)touch.touchID;

Do not retain or otherwise hold on to UITouch* objects, they may contain invalid data in the next frame. Access them only through the touches property on a "as needed" basis.

Removing a Touch　（タッチを削除も出来る、と。）

As of Kobold2D v1.0.2 you can remove a touch to prevent other classes from handling the same touch. The finger associated with that KKTouch object will be ignored from then on.

CCArray* touches = [KKInput sharedInput].touches; KKTouch* touch; CCARRAY_FOREACH(touches, touch) {     // remove touch     [[KKInput sharedInput] removeTouch:touch]; }

It is legal to remove touches while iterating over the touches array. The touch is first invalidated (KKTouchPhase is set to KKTouchPhaseLifted among other things) and later removed.