= Joystick
* ((<Joystick機能概説>))
* ((<SDL::Joystick>))
* ジョイスティック関連メソッド
  * ((<SDL::Joystick.num>)) -- 利用可能なジョイスティックの数を数えます。
  * ((<SDL::Joystick.index_name>)) -- ジョイスティック名を取得します。
  * ((<SDL::Joystick.open>)) -- ジョイスティックを使うためオープンします。
  * ((<SDL::Joystick.open?>)) -- ジョイスティックがオープンされているかどうかを調べます。
  * ((<SDL::Joystick#index>)) -- ジョイスティックのインデックス番号を返します。
  * ((<SDL::Joystick#num_axes>)) -- ジョイスティックの軸の数を取得します。
  * ((<SDL::Joystick#num_balls>)) -- ジョイスティックのトラックボールの数を取得します。
  * ((<SDL::Joystick#num_hats>)) -- ジョイスティックのハットスイッチの数を取得します。
  * ((<SDL::Joystick#num_buttons>)) -- ジョイスティックのボタンの数を取得します。
  * ((<SDL::Joystick.poll=>)) -- ジョイスティックイベントのポーリングを有効/無効にします。
  * ((<SDL::Joystick.poll>)) -- ジョイスティックイベントのポーリングが有効かどうかを調べます。
  * ((<SDL::Joystick.update_all>)) -- すべてのジョイスティックの状態を更新します。
  * ((<SDL::Joystick#axis>)) -- 軸の現在の状態を取得します。
  * ((<SDL::Joystick#hat>)) -- ジョイスティックのハットスイッチの現在の状態を取得します。
  * ((<SDL::Joystick#button>)) -- 指定されたボタンの現在の情報を返します。
  * ((<SDL::Joystick#ball>)) -- トラックボールの相対的な動きを取得します。
  * ((<SDL::Joystick#close>)) -- オープンされているジョイスティックをクローズします。

== Joystick機能概説
ジョイスティック、またそれに近い他のデバイスは、
ゲームプレイにおける非常に強い役割を持っており、
SDL はそれらを広範囲にサポートしています。
軸、ボタン、POV ハットスイッチ、そしてトラックボールは
全てサポートされてます。

ジョイスティックのサポートは
((<SDL.init>)) に SDL::INIT_JOYSTICK フラグを渡すことで初期化されます。
いったん初期化されたジョイスティックは
((<SDL::Joystick.open>)) で
オープンされなければいけません。

ここに書かれているメソッドを使う時、
ジョイスティックにこちらからアクセスして読み込むのが
最良の方法のように思えますが、たいていの場合そうではありません。
理想的には、ジョイスティックは((<イベント|SDL::Event>))
システムを使って読み込むべきです。
これを可能にするために、((<SDL::Joystick.poll=>))
を使ってジョイスティックのイベント処理状態を設定しなければなりません。
もちろん、ジョイスティックを使う前に((<オープン|SDL::Joystick.open>))
しなければなりません。

* NOTES

  イベントキューを通してジョイスティックを扱っているので
  ((*なければ*))、 ((<SDL::Joystick.update_all>))
  を呼んでジョイスティックの更新を明示的に要求する必要があります。

  フォースフィードバックはまだサポートされていません。

== SDL::Joystick
個々のジョイステックから入力情報を得るためのクラスです。

* ((<SDL::Joystick.num>)) -- 利用可能なジョイスティックの数を数えます。
* ((<SDL::Joystick.index_name>)) -- ジョイスティック名を取得します。
* ((<SDL::Joystick.open>)) -- ジョイスティックを使うためオープンします。
* ((<SDL::Joystick.open?>)) -- ジョイスティックがオープンされているかどうかを調べます。
* ((<SDL::Joystick#index>)) -- ジョイスティックのインデックス番号を返します。
* ((<SDL::Joystick#num_axes>)) -- ジョイスティックの軸の数を取得します。
* ((<SDL::Joystick#num_balls>)) -- ジョイスティックのトラックボールの数を取得します。
* ((<SDL::Joystick#num_hats>)) -- ジョイスティックのハットスイッチの数を取得します。
* ((<SDL::Joystick#num_buttons>)) -- ジョイスティックのボタンの数を取得します。
* ((<SDL::Joystick.poll=>)) -- ジョイスティックイベントのポーリングを有効/無効にします。
* ((<SDL::Joystick.poll>)) -- ジョイスティックイベントのポーリングが有効かどうかを調べます。
* ((<SDL::Joystick.update_all>)) -- すべてのジョイスティックの状態を更新します。
* ((<SDL::Joystick#axis>)) -- 軸の現在の状態を取得します。
* ((<SDL::Joystick#hat>)) -- ジョイスティックのハットスイッチの現在の状態を取得します。
* ((<SDL::Joystick#button>)) -- 指定されたボタンの現在の情報を返します。
* ((<SDL::Joystick#ball>)) -- トラックボールの相対的な動きを取得します。
* ((<SDL::Joystick#close>)) -- オープンされているジョイスティックをクローズします。

== Methods

--- SDL::Joystick.num

    システムに接続されたジョイスティックの数を数えます。

    * See Also
      
      ((<SDL::Joystick.index_name>)), ((<SDL::Joystick.open>))

--- SDL::Joystick.index_name(index)
--- SDL::Joystick.indexName(index)

    実装に依存するジョイスティック名を文字列で取得します。
    ((|index|)) パラメータはシステム上のジョイスティック番号を指します。


    EXAMPLE
      # 接続された全てのジョイスティックの名前を表示
      num_joy = SDL::Joystick.num
      printf("%d 本のジョイスティックが見つかりました\n", num_joy)
      num_joy.times do |i|
        puts SDL::Joystick.index_name(i)
      end

    * See Also
      
      ((<SDL::Joystick.open>))

--- SDL::Joystick.open(index)

    SDL 内でジョイスティックを使うためオープンします。
    ((|index|)) はシステムにおけるジョイスティックの番号を指します。
    ジョイスティックはゲームで使用する前にオープンされる必要があります。
    
    ジョイスティック番号は 0 から SDL::Joystick.num - 1 までが有効です。

    ((<SDL::Joystick>))のインスタンスを返します。

    失敗したときには例外((<SDL::Error>))を発生させます。


    EXAMPLE
      # ジョイスティックがあるかチェック
      if SDL::Joystick.num > 0
        # ジョイスティックをオープンする
        joy = SDL::Joystick.open(0)
      
        printf("0番のジョイスティックを開きました\n");
        printf("名前: %s\n", SDL::Joystick.name(0))
        printf("軸の数: %d\n", joy.num_axes)
        printf("ボタンの数: %d\n", joy.num_buttons)
        printf("ボールの数: %d\n", joy.num_balls)
      end  

--- SDL::Joystick.open?(index)

    アプリケーションの中でジョイスティックがオープンされているかどうかを調べます。
    ((|index|)) はシステムにおけるジョイスティックの番号を指します。

    ジョイスティックが既にオープンされている場合は true を、
    そうでない場合は false を返します。

    * See Also
      
      ((<SDL::Joystick.open>))

--- SDL::Joystick#index

    ((|self|)) のインデックス番号を返します。

--- SDL::Joystick#num_axes
--- SDL::Joystick#numAxes

    利用可能な軸の数を返します。

    * NOTES

      縦軸と横軸を持つような入力装置(いわゆるアナログスティック)は軸が
      2つと数えられます。

    * See Also
      
      ((<SDL::Joystick#axis>))

--- SDL::Joystick#num_balls
--- SDL::Joystick#numBalls

    利用可能なトラックボールの数を返します。

    * See Also
      
      ((<SDL::Joystick#ball>))

--- SDL::Joystick#num_hats
--- SDL::Joystick#numHats

    利用可能なハットスイッチの数を返します。

    * See Also
      
      ((<SDL::Joystick#hat>))

--- SDL::Joystick#num_buttons
--- SDL::Joystick#numButtons

    利用可能なボタンの数を返します。

    * See Also
      
      ((<SDL::Joystick#button>))

--- SDL::Joystick.poll=(enable)

    ジョイスティックイベントの処理を有効または無効にするために使われます。
    ジョイスティックイベントの処理が無効の状態では、((<SDL::Joystick.update_all>))
    を使ってジョイスティックの状態を更新し、
    手動でジョイスティックの情報を読み込む必要があります。
    
    デフォルトでは有効になっています。
    
    NOTE
    これを無効にするのはおすすめしません。
    
    これを有効にしても、((<SDL::Joystick.open>))でデバイスをオープンしない
    限りそのジョイステックに関するイベントは発生しません。
    
    このメソッドを呼ぶとイベントキューの中身を勝手に捨てて
    しまう可能性があるので注意してください。

    * See Also
      
      ((<SDL::Joystick.update_all>)), ((<SDL::Joystick.poll>)), ((<SDL::Event::JoyAxis>)), ((<SDL::Event::JoyBall>)), ((<SDL::Event::JoyButtonDown>)), ((<SDL::Event::JoyButtonUp>)), ((<SDL::Event::JoyHat>))

--- SDL::Joystick.poll

    ジョイスティックイベントの処理が有効ならば true を、無効なら false を返し
    ます。詳しくは ((<SDL::Joystick.poll=>)) を見てください。

--- SDL::Joystick.update_all
--- SDL::Joystick.updateAll

    オープンされたすべてのジョイスティックの状態(位置・ボタンなど)を更新します。
    ((<SDL::Joystick.poll=>))
    によってジョイスティックイベントが有効になっている場合は、
    イベントループの中で自動的に呼ばれます。

--- SDL::Joystick#axis(axis_index)

    ((|self|)) の((|axis_index|)) で指定した軸の現在の状態を返します。
    
    最近のほとんどのジョイスティックでは、
    X 軸は通常 axis 0、
    Y 軸は axis 1 で表現されています。
    このメソッドによって返される値は、軸の現在の位置を表わす
    符号付き整数 (-32768 から 32768 まで) であり、
    ぶれを考慮するためこれらの値に適当な閾値を設定しておく必要があるでしょう。


    EXAMPLE
      joy = SDL::Joystick.open(0)
        .
        .
      x_move = joy.axis(0)
      y_move = joy.axis(1)

    * See Also
      
      ((<SDL::Joystick#num_axes>))

--- SDL::Joystick#hat(hat_index)

    ((|hat_index|)) で指定したハットスイッチの現在の状態を取得します。

    現在の状態は、
    以下に挙げる値の 1 つまたは複数の OR による組み合わせとして
    定義される符号無し整数の値として返されます。
    
    * SDL::Joystick::HAT_CENTERED
    * SDL::Joystick::HAT_UP
    * SDL::Joystick::HAT_RIGHT
    * SDL::Joystick::HAT_DOWN
    * SDL::Joystick::HAT_LEFT
    * SDL::Joystick::HAT_RIGHTUP
    * SDL::Joystick::HAT_RIGHTDOWN
    * SDL::Joystick::HAT_LEFTUP
    * SDL::Joystick::HAT_LEFTDOWN

    * See Also
      
      ((<SDL::Joystick#num_hats>))

--- SDL::Joystick#button(button_index)

    ((|button_index|)) で指定されたボタンの現在の情報を返します。
    ボタンが押下状態にある場合は true を、離されている場合は false を
    返します。

    * See Also
      
      ((<SDL::Joystick#num_buttons>))

--- SDL::Joystick#ball(ball_index)

    ((|ball_index|)) で指定したボールの相対的な変化を取得します。
    
    トラックボールは
    前回のこのメソッドの呼び出しからの
    相対的な動きだけを返すことができ、これらの動きの変化は
    [dx, dy] という形の整数2個の配列で得られます。

    失敗したときには例外((<SDL::Error>))を発生させます。


    EXAMPLE
      delta_x, delta_y = joy.ball(0)
      printf("トラックボールの相対移動値- X:%d, Y:%d\n", delta_x, delta_y)

--- SDL::Joystick#close

    ((<SDL::Joystick.open>)) でオープンされたジョイスティックデバイスを
    クローズします。

    * See Also
      
      ((<SDL::Joystick.open>)), ((<SDL::Joystick.open?>))

