メニュー

pygame.cursors

カーソル表示に使用されるpygameモジュール

Pygameではシステムのハードウェアカーソルを制御することができます。 Pygameは白黒のシステムカーソルの制御のみをサポートしています。 pygame.mouseモジュールの命令を使用することでカーソルの機能を制御することができます。

このカーソルモジュールには様々なカーソル形式を読み込んだり復号したりする機能があります。これらの機能を使用することで 設定したカーソルの情報を外部ファイルに保存したり、エンコードされたPythonの文字列として直接保存することが容易になります。

このモジュールには複数の標準カーソル情報が含まれています。pygame.mouse.set_cursor命令ではそれらのカーソル情報を引数を設定することができます。標準カーソル情報はタプル型の値として定義されており、下記のように使用します:

   >>> pygame.mouse.set_cursor(*pygame.cursors.arrow)

またこのモジュールには文字列形式で定義されているカーソル情報も少数存在します。それらのカーソルを使用する場合には、事前にpygame.cursors.compile命令を使用してバイナリの形式カーソル情報に変換する必要があります。変換方法は下記を参照してください。:

   >>> cursor = pygame.cursors.compile(pygame.cursors.textmarker_strings)
   >>> width=len(pygame.cursors.textmarker_strings[0])
   >>> height=len(pygame.cursors.textmarker_strings)
   >>> pygame.mouse.set_cursor((width,height),(0,0),cursor[0],cursor[1])

※原文にあるサンプルではエラーとなってしまうため、独自に動作確認した方法にて訳し直しています。

下記の定数がカーソルとして使用することができる形状の一覧です:

  • pygame.cursors.arrow
  • pygame.cursors.diamond
  • pygame.cursors.broken_x
  • pygame.cursors.tri_left
  • pygame.cursors.tri_right

下記の文字列は pygame.cursors.compile命令でカーソルの形状情報に変換することができます。 :

  • pygame.cursors.thickarrow_strings
  • pygame.cursors.sizer_x_strings
  • pygame.cursors.sizer_y_strings
  • pygame.cursors.sizer_xy_strings
pygame module for cursor resources

Pygame offers control over the system hardware cursor. Pygame only supports black and white cursors for the system. You control the cursor with functions inside pygame.mouse.

This cursors module contains functions for loading and unencoding various cursor formats. These allow you to easily store your cursors in external files or directly as encoded python strings.

The module includes several standard cursors. The pygame.mouse.set_cursor - set the image for the system mouse cursor function takes several arguments. All those arguments have been stored in a single tuple you can call like this:

   >>> pygame.mouse.set_cursor(*pygame.cursors.arrow)

This module also contains a few cursors as formatted strings. You'll need to pass these to pygame.cursors.compile - create binary cursor data from simple strings function before you can use them. The example call would look like this:

   >>> cursor = pygame.cursors.compile(pygame.cursors.textmarker_strings)
   >>> pygame.mouse.set_cursor(*cursor)

The following variables are cursor bitmaps that can be used as cursor:

  • pygame.cursors.arrow
  • pygame.cursors.diamond
  • pygame.cursors.broken_x
  • pygame.cursors.tri_left
  • pygame.cursors.tri_right

The following strings can be converted into cursor bitmaps with pygame.cursors.compile - create binary cursor data from simple strings :

  • pygame.cursors.thickarrow_strings
  • pygame.cursors.sizer_x_strings
  • pygame.cursors.sizer_y_strings
  • pygame.cursors.sizer_xy_strings

pygame.cursors.compile

文字列情報からバイナリ形式のカーソルデータを作成します。
pygame.cursor.compile(strings, black='X', white='.', xor='o'): return data, mask

文字列のリストを使用して、GUIシステムにて使用されるバイナリ形式のカーソルデータを作成することができます。戻り値として返される値はpygame.mouse.set_cursor命令で設定する引数と同じ形式のものです。

もし独自の形状のカーソルを作成するのであれば、黒と白のピクセル情報を表わす値を組み合わせることで任意の形状を作成できます。使用環境によってはカーソルの色を別の色に切り替えて表示することができます。これはxorカラーと呼ばれるものです。使用環境がxorカーソルをサーポートしていない場合、カーソルの色はシンプルな白黒となります。

各文字列の幅は全て等しい値とし、また8の倍数でなければなりません。文字列形式カーソル情報は下記のようになります。

    thickarrow_strings = (               #sized 24x24
      "XX                      ",
      "XXX                     ",
      "XXXX                    ",
      "XX.XX                   ",
      "XX..XX                  ",
      "XX...XX                 ",
      "XX....XX                ",
      "XX.....XX               ",
      "XX......XX              ",
      "XX.......XX             ",
      "XX........XX            ",
      "XX........XXX           ",
      "XX......XXXXX           ",
      "XX.XXX..XX              ",
      "XXXX XX..XX             ",
      "XX   XX..XX             ",
      "     XX..XX             ",
      "      XX..XX            ",
      "      XX..XX            ",
      "       XXXX             ",
      "       XX               ",
      "                        ",
      "                        ",
      "                        ")
create binary cursor data from simple strings
pygame.cursor.compile(strings, black='X', white='.', xor='o'): return data, mask

A sequence of strings can be used to create binary cursor data for the system cursor. The return values are the same format needed by pygame.mouse.set_cursor - set the image for the system mouse cursor.

If you are creating your own cursor strings, you can use any value represent the black and white pixels. Some system allow you to set a special toggle color for the system color, this is also called the xor color. If the system does not support xor cursors, that color will simply be black.

The width of the strings must all be equal and be divisible by 8. An example set of cursor strings looks like this

    thickarrow_strings = (               #sized 24x24
      "XX                      ",
      "XXX                     ",
      "XXXX                    ",
      "XX.XX                   ",
      "XX..XX                  ",
      "XX...XX                 ",
      "XX....XX                ",
      "XX.....XX               ",
      "XX......XX              ",
      "XX.......XX             ",
      "XX........XX            ",
      "XX........XXX           ",
      "XX......XXXXX           ",
      "XX.XXX..XX              ",
      "XXXX XX..XX             ",
      "XX   XX..XX             ",
      "     XX..XX             ",
      "      XX..XX            ",
      "      XX..XX            ",
      "       XXXX             ",
      "       XX               ",
      "                        ",
      "                        ",
      "                        ")

pygame.cursors.load_xbm

xbm形式のファイルからカーソルのデータを読み込みます。
pygame.cursors.load_xbm(cursorfile): return cursor_argspygame.cursors.load_xbm(cursorfile, maskfile): return cursor_args

この命令は複数のXBMファイルからカーソル情報を読み込みます。XBMファイルとは元々UNIXシステム上でカーソル情報を保存するために使用されていたもので、単純な画像を表示するために使われるASCII形式のファイルです。

カーソルの黒い部分を表わす色の値と白い部分を表わす色の値が二つのXBMファイルに分けられて保存される場合もあります。二つ目の引数maskfileを設定することで、二つの画像を読み込んみそれらを合わせてカーソル作成できます。

cursorfile引数とmaskfile引数にはどちらも、ファイル名かreadlines命令で読み込みができるファイルと互換性のあるオブジェクト名を設定します。

戻り値cursor_argsはpygame.mouse.set_cursor命令の引数として直接設定することができます。

load cursor data from an xbm file
pygame.cursors.load_xbm(cursorfile): return cursor_argspygame.cursors.load_xbm(cursorfile, maskfile): return cursor_args

This loads cursors for a simple subset of XBM files. XBM files are traditionally used to store cursors on unix systems, they are an ascii format used to represent simple images.

Sometimes the black and white color values will be split into two separate XBM files. You can pass a second maskfile argument to load the two images into a single cursor.

The cursorfile and maskfile arguments can either be filenames or filelike object with the readlines method.

The return value cursor_args can be passed directly to the pygame.mouse.set_cursor - set the image for the system mouse cursor function.