doc/documentation/manual-pages/ja/man4/mouse.4

.\"
.\" Copyright (c) 1997
.\" Kazutaka YOKOTA <yokota@zodiac.mech.utsunomiya-u.ac.jp>
.\" All rights reserved.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\"    notice, this list of conditions and the following disclaimer as
.\"    the first lines of this file unmodified.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\"    notice, this list of conditions and the following disclaimer in the
.\"    documentation and/or other materials provided with the distribution.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
.\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
.\"
.\" %Id: mouse.4,v 1.2 1998/03/12 07:30:35 charnier Exp %
.\" $FreeBSD$
.\" WORD: track ball	トラックボール
.\" "
.Dd December 3, 1997
.Dt MOUSE 4 i386
.Os FreeBSD
.Sh 名称
.Nm mouse
.Nd マウス、ポインティングデバイス用ドライバ
.Sh 書式
.Fd #include <machine/mouse.h>
.Sh 解説
マウスドライバ
.Xr mse 4 ,
.Xr psm 4 ,
.Xr sysmouse 4
はユーザプログラムにマウスの動きやボタン状態の情報を提供します。
現在のところ、バスマウス用、InPort マウス用、PS/2 マウス用の
特有のデバイスドライバがあります。
シリアルマウスは、専用のドライバでは直接サポートされてはいませんが、
シリアルデバイスドライバを介して、あるいは
.Xr moused 8
や
.Xr sysmouse 4
を経由してアクセスできます。
.Pp
ユーザプログラムでは、単純に
.Xr open 2
呼び出しでマウスデバイスをオープンし、
.Xr read 2
でデバイスからマウスのデータを読み取ります。
動きとボタン状態は通常、固定長のデータパケットにエンコードされます。
マウスデバイスによっては、可変長のパケットでデータを送るかもしれません。
それぞれのドライバが実際に用いるプロトコル (データ形式) は大きく異なります。
.Pp
マウスドライバは ``非ブロッキング'' 属性を持つことができます。
その場合、マウスデータが取得できなければドライバはすぐに戻ります。
.Pp
マウスデバイスドライバは大抵いくつかのレベルの操作を提供します。
現在の操作レベルは
.Xr ioctl 2
コマンドで調査、変更することができます。
レベル 0 が最も低いレベルであり、
このときドライバはユーザプログラムに基本的なサービスを提供します。
このレベルでは、ほとんどのドライバがマウスの水平移動と垂直移動、
および 3 つまでのボタンの状態を提供します。
レベル 1 では、ドライバがサポートしている場合、
マウスデータは標準的な形式の
.Dv MOUSE_PROTO_SYSMOUSE
にエンコードされます。
その形式は次の通りです:
.Pp
.Bl -tag -width "バイト_1" -compact
.It バイト 1
.Bl -tag -width "ビット_7" -compact
.It ビット 7
常に 1 です。
.It ビット 6..3
常に 0 です。
.It ビット 2
左ボタンの状態: 押されていればクリアされ、そうでなければセットされます。
.It ビット 1
中ボタンの状態: 押されていればクリアされ、そうでなければセットされます。
デバイスが中ボタンを持たなければ、常に 1 です。
.It ビット 0
右ボタンの状態: 押されていればクリアされ、そうでなければセットされます。
.El
.It バイト 2
水平移動量の前半部分の、2 の補数表現です。
-128 から 127 の範囲になります。
.It バイト 3
垂直移動量の前半部分の、2 の補数表現です。
-128 から 127 の範囲になります。
.It バイト 4
水平移動量の後半部分の、2 の補数表現です。
-128 から 127 の範囲になります。
水平移動量全体を得るには、
バイト 2 とバイト 4 を足してください。
.It バイト 5
垂直移動量の後半部分の、2 の補数表現です。
-128 から 127 の範囲になります。
垂直移動量全体を得るには、
バイト 3 とバイト 5 を足してください。
.It バイト 6
ビット 7 は常に 0 です。
下位 7 ビットは Z 軸移動量の前半部分を
2 の補数表現でエンコードします。
-64 から 63 の範囲になります。
.It バイト 7
ビット 7 は常に 0 です。
下位 7 ビットは Z 軸移動量の後半部分を
2 の補数表現でエンコードします。
-64 から 63 の範囲になります。
全体の Z 軸移動量を得るには、
バイト 6 と バイト 7 を足してください。
.It バイト 8
ビット 7 は常に 0 です。
ビット 0 から 6 はボタン 4 から 10 の状態を表します。
ボタンが押されていれば対応するビットがクリアされ、
そうでなければセットされます。
.El
.Pp
この形式の最初の 5 バイトは MouseSystems 形式と互換になっています。
残りの 3 バイトは、最上位ビットが常に 0 にセットされています。
そのため、ユーザプログラムが MouseSystems データ形式を解釈できて、
ビットパターン 10000xxxb を検出することで
このデータ形式の 1 バイト目を見つけ出そうとしている場合、
追加分のバイトを棄てることによって、
x, y および 3 つのボタンの状態を正しくデコードできます。
.Pp
デバイスドライバが 2 以上の操作レベルを提供することもあります。
詳しくは個々のドライバのマニュアルページを参照してください。
.Sh IOCTL
次の
.Xr ioctl 2
コマンドがマウスドライバ用に定義されています。
サポートの状況はドライバによって変わります。
本セクションではコマンドの一般的な解説を記します。
特定のドライバの詳細については、個々のドライバのマニュアルページを
参照してください。
.Pp
.Bl -tag -width MOUSE -compact
.It Dv MOUSE_GETLEVEL Ar int *level
.It Dv MOUSE_SETLEVEL Ar int *level
これらのコマンドはマウスドライバの操作レベルを扱います。
.Pp
.It Dv MOUSE_GETHWINFO Ar mousehw_t *hw
接続されているデバイスのハードウェア情報を次の構造体に返します。
.Dv iftype
フィールド以外は、
デバイスドライバが必ずしも正しい値で構造体を埋めるとは限りません。
サポートの詳細は個々のドライバのマニュアルページを参照してください。
.Bd -literal
typedef struct mousehw {
    int buttons;    /* ボタン数 */
    int iftype;     /* I/F の型 */
    int type;       /* マウス/トラックボール/トラックパッド... */
    int model;      /* I/F 依存のモデル ID */
    int hwid;       /* I/F 依存のハードウェア ID */
} mousehw_t;
.Ed
.Pp
.Dv buttons
フィールドはドライバが検出したボタン数を保持します。
ドライバが正確な数を検出できなければ、
2 などの適当な値がこのフィールドに代入されることもあります。
.Pp
.Dv iftype
はインタフェースの型で、
.Dv MOUSE_IF_SERIAL ,
.Dv MOUSE_IF_BUS ,
.Dv MOUSE_IF_INPORT ,
.Dv MOUSE_IF_PS2 ,
.Dv MOUSE_IF_SYSMOUSE ,
.Dv MOUSE_IF_UNKNOWN
のいずれかです。
.Pp
.Dv type
はデバイスの型を示し、
.Dv MOUSE_MOUSE ,
.Dv MOUSE_TRACKBALL ,
.Dv MOUSE_STICK ,
.Dv MOUSE_PAD ,
.Dv MOUSE_UNKNOWN
のいずれかです。
.Pp
.Dv model
は
.Dv MOUSE_MODEL_GENERIC
か、あるいは定数
.Dv MOUSE_MODEL_XXX
のうちの 1 つです。
.Pp
.Dv hwid
はそのポインティングデバイスが返す ID 値です。
これはインタフェースの型に依ります。
取りうる値については特定のマウスドライバのマニュアルページを参照してください。
.Pp
.It Dv MOUSE_GETMODE Ar mousemode_t *mode
本コマンドはマウスドライバの現在の操作パラメータを報告します。
.Bd -literal
typedef struct mousemode {
    int protocol;    /* MOUSE_PROTO_XXX */
    int rate;        /* 報告頻度 (秒単位) */
    int resolution;  /* MOUSE_RES_XXX、不明なら -1 */
    int accelfactor; /* アクセラレーションの要素 */
    int level;       /* ドライバの操作レベル */
    int packetsize;  /* データパケットの長さ */
    unsigned char syncmask[2]; /* 同期ビット */
} mousemode_t;
.Ed
.Pp
.Dv protocol
フィールドは、ユーザプログラムがマウスデータを読み取る際に、
デバイスの状態が返される形式を示します。
これは定数
.Dv MOUSE_PROTO_XXX
のうちのひとつです。
.Pp
.Dv rate
フィールドは状態報告の頻度 (回/秒) であり、
デバイスはこの頻度でホストコンピュータに移動報告を送ります。
不明かまたは適用できなければ -1 です。
.Pp
.Dv resolution
フィールドはポインティングデバイスの解像度を示す値を保持します。
正の値か、定数
.Dv MOUSE_RES_XXX
のうちの 1 つです。
.Pp
.Dv accelfactor
フィールドは、アクセラレーション機能を制御するための値を保持します。
この値は 0 以上でなければなりません。
0 であればアクセラレーション機能は無効です。
.Pp
.Dv packetsize
フィールドは、固定サイズのデータパケットの長さ
または可変長パケットの固定部の長さを示します。
このサイズは、インタフェースの型、デバイスの型やモデル、
ドライバのプロトコルや操作レベルに依存します。
.Pp
配列
.Dv syncmask
は、データパケットの 1 バイト目を検出するための
ビットマスクとビットパターンを保持します。
.Dv syncmask[0]
はビットマスクで、データのバイトとの積 (AND) を取るためのものです。
その結果が
.Dv syncmask[1]
に等しければ、おそらくそのバイトはデータパケットの 1 バイト目でしょう。
但しこの 1 バイト目の検出法は 100% 信頼性があるとは言えません。
ですので、単に補助的な手段だととらえてください。
.Pp
.It Dv MOUSE_SETMODE Ar mousemode_t *mode
本コマンドは、マウスドライバの現在の操作パラメータを
.Ar mode
で指定される通りに変更します。
変更可能なのは、
.Dv rate ,
.Dv resolution ,
.Dv level ,
.Dv accelfactor
だけです。
他のフィールドに値を代入しても、エラーは発生しませんし、効果もありません。
.Pp
あるフィールドの現在の設定を変更したくないときは、
そのフィールドに -1 を入れてください。
また
.Dv resolution
と
.Dv rate
には 0 を入れることもできます。
そうすると、そのフィールドのデフォルト値が選択されます。
.\" .Pp
.\" .It Dv MOUSE_GETVARS Ar mousevar_t *vars
.\" Get internal variables of the mouse driver. 
.\" The variables which can be manipulated through these commands
.\" are specific to each driver. 
.\" This command may not be supported by all drivers.
.\" .Bd -literal
.\" typedef struct mousevar {
.\"     int var[16];    /* internal variables */
.\" } mousevar_t;
.\" .Ed
.\" .Pp
.\" If the commands are supported, the first element of the array is
.\" filled with a signature value. 
.\" Apart from the signature data, there is currently no standard concerning 
.\" the other elements of the buffer.
.\" .Pp
.\" .It Dv MOUSE_SETVARS Ar mousevar_t *vars
.\" Get internal variables of the mouse driver. 
.\" The first element of the array must be a signature value.
.\" This command may not be supported by all drivers.
.Pp
.It Dv MOUSE_READDATA Ar mousedata_t *data
本コマンドはデバイスから生のデータを読み取ります。
.Bd -literal
typedef struct mousedata {
    int len;        /* バッファ内のデータ数 */
    int buf[16];    /* データ用バッファ */
} mousedata_t;
.Ed
.Pp
呼び出し元プロセスは、
バッファに読み込まれるバイト数を
.Dv len
フィールドに入れておかなくてはなりません。
本コマンドはすべてのドライバがサポートしているとは限りません。
.Pp
.It Dv MOUSE_READSTATE Ar mousedata_t *state
本コマンドはデバイスから生の状態データを読み取ります。
上記と同じ構造体を使用します。
本コマンドはすべてのドライバがサポートしているとは限りません。
.Pp
.It Dv MOUSE_GETSTATE Ar mousestatus_t *status
本コマンドは、現在のボタン状態と移動量を次の構造体に返します。
.Bd -literal
typedef struct mousestatus {
    int flags;      /* 状態変更フラグ */
    int button;     /* ボタン状態 */
    int obutton;    /* 以前のボタン状態 */
    int dx;         /* x 方向の移動 */
    int dy;         /* y 方向の移動 */
    int dz;         /* z 方向の移動 */
} mousestatus_t;
.Ed
.Pp
.Dv button
フィールドと
.Dv obutton
フィールドは、マウスボタンの現在の状態と以前の状態を保持します。
ボタンが押されたとき、対応するビットがセットされます。
マウスドライバは 0 から 31 までのビットを使って
31 個までのボタンをサポートできます。
いくつかのボタンビットが
.Dv MOUSE_BUTTON1DOWN
から
.Dv MOUSE_BUTTON8DOWN
として定義されています。
最初の 3 つのボタンは、左ボタン、中ボタン、右ボタンに対応します。
.Pp
前回の
.Dv MOUSE_GETSTATE
呼び出しからボタンの状態が変わっていれば、
.Dv flags
フィールドの対応するビットがセットされます。
前回の呼び出しからマウスが移動していれば、
.Dv flags
フィールド中の
.Dv MOUSE_POSCHANGED
ビットもセットされます。
.Pp
その他のフィールドは、
前回の
.Dv MOUSE_GETSTATE
呼び出しからの移動量を保持します。
本コマンドが呼び出された後に、毎回内部カウンタがリセットされます。
.El
.Sh 関連ファイル
.Bl -tag -width /dev/sysmouseXX -compact
.It Pa /dev/cuaa%d
シリアルポート
.It Pa /dev/mse%d
バスマウス、InPort マウスデバイス
.It Pa /dev/psm%d
PS/2 マウスデバイス
.It Pa /dev/sysmouse
仮想マウスデバイス
.El
.Sh 関連項目
.Xr ioctl 2 ,
.Xr mse 4 ,
.Xr psm 4 ,
.Xr sysmouse 4 ,
.Xr moused 8
.\".Sh HISTORY
.Sh 作者
本マニュアルページは
.An Kazutaka Yokota Aq yokota@FreeBSD.org
が書きました。