如何取得和設定滑鼠指標（樣式）？Cursor 指標物件使用說明

Pygame 中的 Cursor 物件

Pygame 套件的Cursor物件可用於表示遊戲視窗中顯示的滑鼠指標，其建構子如下。

Cursor(constant)
Cursor(size, hotspot, xormasks, andmasks)
Cursor(hotspot, surface)
Cursor(cursor)
Cursor()

constant 參數

constant參數是一個表示系統滑鼠指標的整數，你可以從pygame模組中匯入以SYSTEM_CURSOR_開頭的變數，並將其作為該參數的值，這將建立表示系統滑鼠指標的Cursor物件。

size 參數

size參數是依次包含滑鼠指標寬度和高度的整數序列物件，無論如何寬度和高度應是8的倍數，比如(16,24)。

hotspot 參數

hotspot參數是依次包含滑鼠指標作用點 X 座標和 Y 座標的整數序列物件。

作用點是滑鼠指標與其他內容進行互動的點，他應在滑鼠指標大小範圍內。當你設定了不同的作用點時，滑鼠指標的顯示位置將發生變化，在滑鼠的實際位置保持不變的情況下。

xormasks，andmasks 參數

xormasks，andmasks參數是包含滑鼠指標互斥或運算遮罩的整數序列物件，以及滑鼠指標與運算遮罩的整數序列物件。序列物件所包含的遮罩的個數需要與size參數所指示大小相符。

以上兩個參數可通過cursors模組的compile函式建置，具體請參考從字串建置與滑鼠指標有關的遮罩一段。

surface 參數

surface參數是包含了影像資訊的Surface表面物件，其表示的影像將顯示為滑鼠指標。

cursor 參數

cursor參數是一個已有的Cursor物件，將根據該物件建立新的Cursor物件。你可以從cursors模組中匯入以下預先建立的型別為Cursor的變數，arrow，diamond，broken_x，tri_left，tri_right。

如果使用沒有任何參數的建構子，那麽其效果等同於Cursor(SYSTEM_CURSOR_ARROW)。

# 匯入 cursors 模組，Cursor 類別和其他相關內容
from pygame import cursors, Cursor, SYSTEM_CURSOR_WAIT


# 建立表示系統等候指標的 Cursor 物件
c1 = Cursor(SYSTEM_CURSOR_WAIT)
# 根據預先定義的 Cursor 物件建立 Cursor 物件
c2 = Cursor(cursors.ball)

取得滑鼠指標的資訊

Cursor物件的type變數是表示滑鼠指標型別的字串，根據建立時所傳遞給建構子的參數的不同，type的值可能是'system'，'bitmap'或'color'。其中，'system'對應采用Cursor(constant)或Cursor()建立的Cursor物件，'bitmap'對應采用Cursor(size,hotspot,xormasks,andmasks)建立的Cursor物件，'color'對應采用Cursor(hotspot,surface)建立的Cursor物件。

cursor.type

Cursor物件的data變數是一個元組，元組包含建立該Cursor物件所用到的資料。如果滑鼠指標的型別不同，那麽這些資料的含義可能也不同。

cursor.data

# …
# 顯示 Cursor 物件 c1，c2 的型別和資料
print(c1.type, c1.data)
print(c2.type, c2.data)

system (2,)
bitmap ((16, 16), (7, 7), (0, 0, 3, 192, 15, 240, 24, 248, 51, 252, 55, 252, 127, 254, 127, 254, 127, 254, 127, 254, 63, 252, 63, 252, 31, 248, 15, 240, 3, 192, 0, 0), (3, 192, 15, 240, 31, 248, 63, 252, 127, 254, 127, 254, 255, 255, 255, 255, 255, 255, 255, 255, 127, 254, 127, 254, 63, 252, 31, 248, 15, 240, 3, 192))

複製滑鼠指標

Cursor物件的copy方法，可用於複製滑鼠指標，其傳回值是一個與原有Cursor物件一致的新的Cursor物件。

cursor.copy()

傳回值

copy方法的傳回值為新的Cursor物件。

# …
# 複製之前建立的 Cursor 物件 c1
print(c1.copy())

<Cursor(type: system, constant: SYSTEM_CURSOR_WAIT)>

Pygame 中的 cursors 模組

Pygame 套件的cursors模組，包含一些用於幫助建立Cursor物件的函式。事實上，Cursor類別定義在該模組中，但開發人員也可以通過pygame模組來使用Cursor類別。

從字串建置與滑鼠指標有關的遮罩

采用形式為Cursor(size,hotspot,xormasks,andmasks)的建構子，Pygame 將建立僅支援黑白兩種色彩的點陣圖形式的滑鼠指標（當然這似乎是一種非常過時的方法），其包含遮罩的參數xormasks和andmasks可通過cursors模組的compile函式來產生。

compile(strings, black='X', white='.', xor='o')

strings 參數

strings參數是一個包含字串的序列物件，這些字串將指示滑鼠指標中的像素的色彩，序列中的第一個字串對應第一行像素，序列中每個字串的第一個字元對應第一列像素，以此類推。你可以從cursors模組中匯入以下預先建立的型別為Cursor的變數，arrow，diamond，broken_x，tri_left，tri_right。

無論如何，應確保每個字串的長度，以及字串的個數，與滑鼠指標的大小一致，否則可能會引發例外狀況。

black 參數

black參數用於指示表示黑色的字元，如果strings參數包含的某個字串中含有表示黑色的字元（空格表示沒有色彩），那麽滑鼠指標中對應位置的像素將為黑色。

white 參數

white參數用於指示表示白色的字元，如果strings參數包含的某個字串中含有表示白色的字元（空格表示沒有色彩），那麽滑鼠指標中對應位置的像素將為白色。

xor 參數

xor參數用於指示采用反轉色彩的字元，如果strings參數包含的某個字串中含有表示反轉色彩的字元（空格表示沒有色彩），那麽滑鼠指標中對應位置的像素的色彩，將與系統色彩相反。如果反轉色彩不被支援，那麽對應的像素將為黑色。

傳回值

compile函式的傳回值是一個元組，其第一個元素是可用於建立Cursor物件的，包含互斥或運算遮罩的元組，其第二個元素是可用於建立Cursor物件的，包含與運算遮罩的元組。

# 匯入 cursors 模組，Cursor 類別
from pygame import cursors, Cursor


# 表示十字的字串元組
cross_strings = (
	"   ++   ",
	"   --   ",
	"   --   ",
	"+--++--+",
	"+--++--+",
	"   --   ",
	"   --   ",
	"   ++   ",
)
# 使用 compile 建置對應的遮罩
(xormarks, andmarks) = cursors.compile(cross_strings, '+', '-')


# 建立表示十字的 Cursor 物件，大小 8x8，作用點在 4 4
Cursor((8, 8), (4, 4), xormarks, andmarks)

從 xbm 檔案建置與滑鼠指標有關的資訊

cursors模組的load_xbm函式，可從xbm檔案建置與滑鼠指標相關的資訊（當然這似乎是一種非常過時的方法），這些資訊可用於形式為Cursor(size,hotspot,xormasks,andmasks)的建構子。

load_xbm(curs, mask)

curs 參數

curs參數是表示xbm檔案路徑的字串，或包含xbm檔案路徑的類路徑（path-like）物件，或包含xbm檔案資料的IO物件。

mask 參數

mask參數與curs參數類似，只不過，其對應的xbm檔案包含遮罩資訊。

傳回值

load_xbm函式的傳回值是一個元組，元組中元素的含義和順序，與形式為Cursor(size,hotspot,xormasks,andmasks)的建構子的參數一致。

取得和設定滑鼠指標（樣式）

Pygame 自訂滑鼠指標（通過載入影像檔案等方式）

影片示範 YouTube

Pygame 的cursors模組並未包含取得或設定滑鼠指標（樣式）的函式，要完成該目標，你需要使用mouse模組的get_cursor和set_cursor函式。其中set_cursor函式的參數與Cursor物件的建構子參數含義相同，因此，可參考Cursor 物件一段。

get_cursor()

傳回值

get_cursor函式傳回目前滑鼠物件所對應的Cursor物件。

set_cursor(constant)
set_cursor(size, hotspot, xormasks, andmasks)
set_cursor(hotspot, surface)
set_cursor(cursor)

# 在執行腳本前，請將命令列跳躍至 set_get.py 所在的目錄


# 匯入 mouse 模組和其他相關內容，並建立遊戲視窗
from pygame import mouse, image, display, event, QUIT
display.set_mode((400, 300))


# 載入大小為 32x32 的影像
candy = image.load('candy.png')
# 將影像設定為滑鼠指標，作用點在影像的中心
mouse.set_cursor((16, 16), candy)
print(mouse.get_cursor())


# 處理遊戲中的事件
running = True
while running:
	for e in event.get():
		if e.type == QUIT:
			running = False

<Cursor(type: color, hotspot: (16, 16), surf: <Surface(32x32x32 SW)>)>

原始碼

src/zh-hant/mouse/cursors·codebeatme/pygame·GitHub

講解影片

Pygame 自訂滑鼠指標（通過載入影像檔案等方式）·YouTube