Mouse
================================

.. code-block:: python

    class psychopy.event.Mouse(visible=True, newPos=None, win=None)

マウスの状態を取得するクラスである。これはクラスである必要はないが、ジョイスティックはクラスとした方が良いので統一するためにクラスとした。

Mouseオブジェクトを作成する前にWindowオブジェクトを作成しておくこと。

.. class psychopy.event.Mouse(visible=True, newPos=None, win=None)

.. Easy way to track what your mouse is doing.

.. It needn’t be a class, but since Joystick works better as a class this may as well be one too for consistency

.. Create your visual.Window before creating a Mouse.

================ =============================================================================================
パラメータ       解説
================ =============================================================================================
visible          TrueかFalse。マウスカーソルを表示するか否かを指定する。
newPos           NoneまたはX座標,Y座標を並べたシーケンス。初期化時のマウスカーソル位置を指定する。
                 (訳注：原文ではpygameバックエンドのみと書かれているがpygletに対応済みである)
win              マウスを割り当てるWindowオブジェクトを指定する。Noneならば最初に見つかったPsychoPy Window
                 に割り当てる。
================ =============================================================================================

.. Parameters:	

.. visible: True or False
..    makes the mouse invisible if necessary
.. newPos : None or [x,y]
..    gives the mouse a particular starting position (pygame Window only)
.. win: None or Window
    the window to which this mouse is attached (the first found if None provided)


clickReset(buttons=(0, 1, 2))
-----------------------------------

各ボタンに割り当てられたストップウォッチをリセットする。

引数として、リセットするボタンを表すインデックス(0, 1, 2)を並べたシーケンスを渡すことが出来る。省略すると全てリセットされる。

.. Reset a 3-item list of core.Clocks use in timing button clicks.

.. The pyglet mouse-button-pressed handler uses their clock.getLastResetTime() when a button is pressed so the user can reset them at stimulus onset or offset to measure RT. The default is to reset all, but they can be reset individually as specified in buttons list

getPos()
-------------------

現在のマウスカーソルの座標を返す。単位はWindowオブジェクトに設定されたものに従う。(0, 0)がウィンドウの中心である。

.. Returns the current position of the mouse, in the same units as the Window (0,0) is at centre

getPressed(getTime=False)
-------------------------------------

ボタン0, 1, 2が押されているか否かを要素数3のリストとして返す。

引数getTime=Trueが渡された場合、ボタン押しの状態を表すリストに加えて、clickResetを実行した時点を0.0秒として各ボタンが最後に押されたタイムスタンプを並べたリストを返す。

.. code-block:: python

    buttons = mouse.getPressed()
    buttons, times = mouse.getPressed(getTime=True)

刺激のオンセット時にclickReset()を実行しておくと、この刺激に対するボタン押し反応がおこなわれた時、この戻り値から反応時間を得ることが出来る。この値はいつgetPressed()を実行するかに関わらず、実際の反応時間を表している。

(訳注：この部分はかなり「意訳」している。ここで述べられているのは、引数getTime=Trueを指定したときに得られるタイムスタンプが「リセットしてからgetPressed()を実行するまでの時間」ではなく、実際に「リセットしてからボタンが押されるまでの時間」だということである。この値はMouseオブジェクトの内部で保持されていて、getPressedは保持されている値を得るだけである。したがって、getPressedの実行が実際にボタンが押された時刻よりかなり後であったとしても、正しい反応時間が得られる。自前でpsychopy.core.Clockオブジェクトを作成して、getPressedでボタン押しを検出した直後にClockオブジェクトのgetTimeを実行して反応時間を測ろうとするコードと比べてみると良い。)

.. Returns a 3-item list indicating whether or not buttons 0,1,2 are currently pressed.

.. If getTime=True (False by default) then getPressed will return all buttons that have been pressed since the last call to mouse.clickReset as well as their time stamps:

..    buttons = mouse.getPressed()
..    buttons, times = mouse.getPressed(getTime=True)

.. Typically you want to call mouse.clickReset() at stimulus onset, then after the button is pressed in reaction to it, the total time elapsed from the last reset to click is in mouseTimes. This is the actual RT, regardless of when the call to getPressed() was made.

getRel()
----------------

最後にgetRel()またはgetPos()を実行した時点からの相対的なマウスカーソルの位置を返す。単位はWindowオブジェクトに設定されたものに従う。

.. Returns the new position of the mouse relative to the last call to getRel or getPos, in the same units as the Window.

getVisible()
-----------------

マウスカーソルを表示するように設定されているか否かを返す。表示なら1、非表示なら0である。

.. Gets the visibility of the mouse (1 or 0)

getWheelRel()
--------------------

最後にgetWheelRel()が実行された時点からの相対的なホイールの回転量を返す。戻り値は要素数2のNumPyのarrayオブジェクトだが、2軸の回転を取得できるのはその機能を持つマウスのみに限る。

.. Returns the travel of the mouse scroll wheel since last call. Returns a numpy.array(x,y) but for most wheels y is the only value that will change (except Mac mighty mice?)

isPressedIn(shape, buttons=(0, 1, 2))
---------------------------------------------

引数shapeに指定した視覚刺激オブジェクトにマウスカーソルが重なった状態でボタンが押されていればTrue、いなければFalseを返す。デフォルトでは3ボタンのいずれかが押されていればTrueとなる。ボタンを制限する場合は引数buttonsを用いて指定する。

.. code-block:: python

    if mouse.isPressedIn(shape):
    if mouse.isPressedIn(shape, buttons=[0]):  # 左ボタンのみ確認

視覚刺激オブジェクトはcontains()メソッドも持つものであればよい。

(訳注：原文では内容が古くてImageStimでテストされていないなどと書かれているが、現在のバージョンはcontains()を持つ視覚刺激オブジェクトすべてで問題なく動作するはずである)

.. Returns True if the mouse is currently inside the shape and one of the mouse buttons is pressed. The default is that any of the 3 buttons can indicate a click; for only a left-click, specifiy buttons=[0]:

..    if mouse.isPressedIn(shape):
..    if mouse.isPressedIn(shape, buttons=[0]):  # left-clicks only

.. Ideally, shape can be anything that has a .contains() method, like ShapeStim or Polygon. Not tested with ImageStim.

mouseMoveTime()
-----------------------

(訳注：原文ではこの項目は空欄である。mouseMoved()参照。)

mouseMoved(distance=None, reset=False)
--------------------------------------------

マウスカーソルが動いたか、どれだけ大きく動いたかを判定する。

引数が省略された場合、最後にgetPos()が実行されてからマウスカーソルが動いていればTrueを返す。
引数distanceに整数または浮動小数点数が指定された場合、最後にgetPos()を実行した位置から指定した距離だけマウスカーソルが離れていればTrueを返す(訳注：X, Y方向の距離を別々に指定することも可能だが、符号の扱いに疑問があるので興味がある方はソースコードを読んでいただきたい。ここでは原文のこの指定法に関する訳は省略する)。

最後の動きの時間はself.mouseClock.getTime()から得られる(訳注：恐らく間違いと思われる。mouseMoveTime()がここで述べられている動作に近いと訳者は思うが、mouseMoveTime()で正しいかは確証がない)。

resetは'here'または座標(X,Y)のいずれかで、その位置から移動したかどうかを計測することが出来る。引数resetに座標(X,Y)を指定して引数distanceを指定した場合、(X,Y)の位置を動き判定の基準点として登録した後に、現在のマウスカーソル位置との距離が判定される(訳注：原文のこの段落の後半はMouseオブジェクトの内部変数に言及するなど、ユーザー向けというよりは開発者向けのメモと言うべき内容と思われる。なお、ソースコードを読むとresetにTrueを指定することも可能で、この場合はmouseMoveTime()で得られる時刻を0.0にリセットする)。

.. Determine whether/how far the mouse has moved.

.. With no args returns true if mouse has moved at all since last getPos() call, or distance (x,y) can be set to pos or neg distances from x and y to see if moved either x or y that far from lastPos, or distance can be an int/float to test if new coordinates are more than that far in a straight line from old coords.

.. Retrieve time of last movement from self.mouseClock.getTime().

.. Reset can be to ‘here’ or to screen coords (x,y) which allows measuring distance from there to mouse when moved. If reset is (x,y) and distance is set, then prevPos is set to (x,y) and distance from (x,y) to here is checked, mouse.lastPos is set as current (x,y) by getPos(), mouse.prevPos holds lastPos from last time mouseMoved was called.

setExclusive(exclusivity)
---------------------------------------

マウスカーソルの移動範囲を割り当てられたウィンドウに制限する。Pygletバックエンドでのみ有効である。

マルチモニター環境や、（フルスクリーンウィンドウではない）通常のウィンドウでは、マウスカーソルはウィンドウ外へ移動可能である。ウィンドウ外にカーソルがあると、PsychoPyのウィンドウはイベントを受け取れなくなる。setExclusive(True)とするとこれらの状況でマウスカーソルがウィンドウ外へ出ないようにすることが出来る。

マウスカーソル移動範囲をウィンドウ内に制限することによってカーソルが消失し、絶対位置は意味を成さなくなる点に注意。この場合、getPos()は[0,0]を返す。

.. Binds the mouse to the experiment window. Only works in Pyglet.

.. In multi-monitor settings, or with a window that is not fullscreen, the mouse pointer can drift, and thereby PsychoPy might not get the events from that window. setExclusive(True) works with Pyglet to bind the mouse to the experiment window.

.. Note that binding the mouse pointer to a window will cause the pointer to vanish, and absolute positions will no longer be meaningful getPos() returns [0, 0] in this case.

setPos(newPos=(0, 0))
-------------------------------

マウスカーソルの位置を指定する。単位はWindowオブジェクトのものに従う。(0, 0)が中心である。

.. Sets the current position of the mouse, in the same units as the Window. (0,0) is the center.
..    Parameters:	

..    newPos
..    : (x,y) or [x,y]

..        the new position on the screen

setVisible(visible)
-----------------------------

マウスカーソルを表示するか否かを指定する。表示するならvisible=1、しないなら0である。

マウスカーソルが非表示のときは、マウスカーソルが画面外へ移動して見失われてしまわないように絶対位置は(0, 0)に保たれる。このような場合でもgetRel()は有効である。

.. Sets the visibility of the mouse to 1 or 0

.. NB when the mouse is not visible its absolute position is held at (0, 0) to prevent it from going off the screen and getting lost! You can still use getRel() in that case.

units
-----------------

Mouseオブジェクトが使用する単位である。割り当てられたWindowオブジェクトの単位と一致する。

.. The units for this mouse (will match the current units for the Window it lives in)