Textual MouseScrollRight 事件詳解捕獲終端橫向滾輪滾動【免費下載鏈接】textualThe lean application framework for Python. Build sophisticated user interfaces with a simple Python API. Run your apps in the terminal and a web browser.項目地址: https://gitcode.com/gh_mirrors/te/textual導讀MouseScrollRight是 Textual 事件體系中的一員專門用于響應(yīng)鼠標滾輪或觸控板手勢在終端中向右滾動的事件。本文以 docs/events/mouse_scroll_right.md 為骨架深入 Textual 源碼與測試完整講解該事件的定義、觸發(fā)時機、屬性與方法、在 Widget 內(nèi)的默認行為橫向滾動以及如何編寫自定義處理器實現(xiàn)專屬交互邏輯。事件定義與繼承關(guān)系MouseScrollRight定義于 src/textual/events.pyrich.repr.auto class MouseScrollRight(MouseEvent, bubbleTrue, verboseTrue): Sent when the mouse wheel is scrolled *right*. - [X] Bubbles - [X] Verbose 從源碼可以看出該事件的兩個關(guān)鍵特征Bubbles冒泡事件會從產(chǎn)生它的控件向父控件逐級冒泡父級可以統(tǒng)一監(jiān)聽或攔截通過調(diào)用event.stop()Verbose冗長日志與Click等非 Verbose 事件不同滾動事件屬于高頻事件Textual 會將其記錄在冗長日志verbose log中方便調(diào)試滾動相關(guān)的交互問題但生產(chǎn)環(huán)境日志中不會默認輸出這些高頻噪聲。它與同族的 MouseScrollUp、MouseScrollDown、MouseScrollLeft 一樣都直接繼承自MouseEvent見 src/textual/events.py本身不新增任何字段全部屬性和方法均來自父類。注意原文檔明確指出——完整的屬性與方法列表見MouseEvent。因此理解MouseScrollRight的關(guān)鍵在于吃透MouseEvent提供的坐標系、修飾鍵與滾動增量等信息。MouseEvent 提供的屬性與坐標系MouseScrollRight繼承自MouseEvent定義于 src/textual/events.py事件攜帶以下核心信息坐標類屬性屬性類型含義x/yint鼠標所在的相對單元格坐標相對接收事件的控件pointer_x/pointer_yfloat鼠標所在的相對像素級浮點坐標screen_x/screen_yint鼠標所在的屏幕絕對坐標相對屏幕左上角pointer_screen_x/pointer_screen_yfloat屏幕絕對坐標的浮點版本offsetOffset(x, y)組合成的相對偏移量screen_offsetOffset(screen_x, screen_y)組合成的屏幕偏移量滾動增量類屬性屬性類型含義delta_xint自上次鼠標消息以來 x 方向的變化量delta_yint自上次鼠標消息以來 y 方向的變化量deltaOffset(delta_x, delta_y)組合成的增量偏移量修飾鍵與按鈕屬性類型含義shiftboolShift 鍵是否按下metaboolMeta 鍵是否按下ctrlboolCtrl 鍵是否按下buttonint被按下的按鍵索引styleStyle鼠標下方光標位置的 Rich Style實用方法get_content_offset(widget)返回鼠標在指定控件內(nèi)容區(qū)內(nèi)的偏移量若落在 padding 或 border 區(qū)域則返回Noneget_content_offset_capture(widget)即使鼠標不在內(nèi)容區(qū)內(nèi)也返回相對內(nèi)容區(qū)左上角的偏移量_apply_offset(x, y)在事件坐標基礎(chǔ)上平移生成新事件用于消息沿 DOM 樹向下轉(zhuǎn)發(fā)時校正坐標系。這些坐標均為單元格cell整數(shù)坐標因為終端渲染以字符單元為最小單位delta_x/delta_y由XTermParser依據(jù)上一次鼠標位置實時計算見下文觸發(fā)鏈路。事件的產(chǎn)生鏈路從 ANSI 序列到 MouseScrollRightMouseScrollRight并非憑空產(chǎn)生而是由終端的 SGR 鼠標協(xié)議\x1b[...M/m序列解析而來。核心解析邏輯位于 src/textual/_xterm_parser.pyif buttons 64: event_class [ events.MouseScrollUp, events.MouseScrollDown, events.MouseScrollLeft, events.MouseScrollRight, ][buttons 3] button 0這段代碼揭示了事件類型的分派規(guī)則SGR 序列中的按鈕碼與64做按位與若結(jié)果非零則說明這是滾動事件隨后用buttons 3取低 2 位作為索引映射到四個滾動方向其中索引3即對應(yīng)MouseScrollRight。解析器還會維護上一次的鼠標坐標last_x/last_y據(jù)此計算delta_x int(x) - int(self.last_x) delta_y int(y) - int(self.last_y)并提取修飾鍵狀態(tài)bool(buttons 4), # shift bool(buttons 8), # meta bool(buttons 16), # ctrl測試用例印證倉庫測試 tests/test_xterm_parser.py 對右側(cè)滾動事件的解析做了參數(shù)化驗證pytest.mark.parametrize( sequence, shift, meta, [ (\x1b[67;18;25M, False, False), (\x1b[71;18;25M, True, False), (\x1b[75;18;25M, False, True), ], ) def test_mouse_scroll_right(parser, sequence, shift, meta): events list(parser.feed(sequence)) assert len(events) 1 event events[0] assert isinstance(event, MouseScrollRight) assert event.x 17 assert event.y 24 assert event.shift is shift assert event.meta is meta可以看到序列\(zhòng)x1b[67;18;25M按鈕碼 67 64 3被正確解析為一個MouseScrollRight事件坐標為(17, 24)序列中坐標從 1 開始計數(shù)源碼中減 1 轉(zhuǎn)為 0 基坐標且不帶修飾鍵按鈕碼 71、75 則分別驗證了 Shift、Meta 鍵狀態(tài)位的解析。Widget 中的默認行為驅(qū)動橫向滾動Textual 的Widget基類為滾動事件提供了開箱即用的默認處理。在 src/textual/widget.py 中def _on_mouse_scroll_right(self, event: events.MouseScrollRight) - None: if self.allow_horizontal_scroll: if self._scroll_right_for_pointer(): event.stop() def _on_mouse_scroll_left(self, event: events.MouseScrollLeft) - None: if self.allow_horizontal_scroll: if self._scroll_left_for_pointer(): event.stop()這意味著當鼠標在支持水平滾動的控件allow_horizontal_scroll為真上向右滾動時Textual 會自動調(diào)用_scroll_right_for_pointer()執(zhí)行滾動滾動成功返回True后調(diào)用event.stop()停止冒泡避免父級重復處理因此如果你的控件本身具備水平滾動能力如設(shè)置了overflow-x: auto無需編寫任何代碼即可獲得橫向滾輪支持。如何監(jiān)聽與自定義處理由于事件具有冒泡特性你可以用兩種方式捕獲MouseScrollRight。方式一命名約定法按照 Textual 的命名約定為事件添加on_前綴、將類名轉(zhuǎn)為蛇形命名即可自動關(guān)聯(lián)處理器from textual.app import App, ComposeResult from textual.widgets import Static class ScrollWatcher(Static): def on_mouse_scroll_right(self, event: events.MouseScrollRight) - None: # 事件默認已由基類用于橫向滾動若想自定義可在此覆蓋 self.log(fScrolled right at ({event.screen_x}, {event.screen_y})) event.stop() # 停止冒泡方式二on裝飾器法Textual 的 [on][textual.on] 裝飾器用法見 docs/guide/events.md允許為事件綁定任意命名的方法且可配合 CSS 選擇器精確指定要監(jiān)聽的控件from textual import on from textual.events import MouseScrollRight class MyApp(App): on(MouseScrollRight, #content) def handle_scroll(self, event: MouseScrollRight) - None: self.notify(fRight scroll at x{event.delta_x})提示on裝飾器要求消息類具備control屬性MouseEvent的control屬性即返回鼠標下的控件見 src/textual/events.py因此可用于選擇器匹配。與 Shift/Ctrl 組合Textual 的默認行為中垂直滾輪配合shift/ctrl也會被轉(zhuǎn)換為橫向滾動見 src/textual/widget.py 中_on_mouse_scroll_down/_on_mouse_scroll_up的event.ctrl or event.shift分支。因此在實際終端中即使硬件沒有橫向滾輪也可以用「Shift 垂直滾輪」觸發(fā)等價的橫向滾動效果。調(diào)試與日志由于MouseScrollRight標記為verboseTrue當你在終端按CtrlE打開 Textual Devtools 的日志或?qū)⑷罩炯墑e調(diào)至 verbose 時滾動事件會以類似以下形式輸出來自__rich_repr__見 src/textual/events.pyMouseScrollRight(None, x17, y24, delta_x0, delta_y0, button0, shiftFalse, metaFalse, ctrlFalse)其中各字段只有在非默認值時才會展示便于快速定位坐標與修飾鍵狀態(tài)。與其他鼠標事件的協(xié)同MouseScrollRight通常與以下事件配合使用構(gòu)成完整的鼠標交互體系MouseScrollLeft向左滾動MouseScrollUp / MouseScrollDown垂直方向滾動Click、MouseDown、MouseUp點擊類交互MouseMove指針移動Enter / Leave鼠標進入/離開控件區(qū)域。設(shè)計自定義滾動控件如橫向走馬燈、圖表橫軸縮放、水平菜單切換時可在處理器中讀取event.delta_x作為步進量或讀取event.x/event.y判斷滾動位置實現(xiàn)精細的分步控制。小結(jié)MouseScrollRight繼承自MouseEvent具有冒泡與冗長日志特性本身不新增字段它的產(chǎn)生源于XTermParser對 SGR 鼠標協(xié)議序列的解析按鈕碼 64判定滾動、 3判定方向3為右Widget基類默認將其映射為水平右向滾動可零代碼使用自定義處理可使用命名約定或on裝飾器注意通過event.stop()控制冒泡。相關(guān)源碼與測試索引事件類定義src/textual/events.py父類MouseEventsrc/textual/events.pyANSI 序列解析src/textual/_xterm_parser.py默認滾動行為src/textual/widget.py解析測試tests/test_xterm_parser.py事件處理指南docs/guide/events.md【免費下載鏈接】textualThe lean application framework for Python. Build sophisticated user interfaces with a simple Python API. Run your apps in the terminal and a web browser.項目地址: https://gitcode.com/gh_mirrors/te/textual創(chuàng)作聲明：本文部分內(nèi)容由AI輔助生成（AIGC），僅供參考 Textual MouseScrollRight 事件詳解：捕獲終端橫向滾輪滾動
Textual MouseScrollRight 事件詳解捕獲終端橫向滾輪滾動【免費下載鏈接】textualThe lean application framework for Python. Build sophisticated user interfaces with a simple Python API. Run your apps in the terminal and a web browser.項目地址: https://gitcode.com/gh_mirrors/te/textual導讀MouseScrollRight是 Textual 事件體系中的一員專門用于響應(yīng)鼠標滾輪或觸控板手勢在終端中向右滾動的事件。本文以 docs/events/mouse_scroll_right.md 為骨架深入 Textual 源碼與測試完整講解該事件的定義、觸發(fā)時機、屬性與方法、在 Widget 內(nèi)的默認行為橫向滾動以及如何編寫自定義處理器實現(xiàn)專屬交互邏輯。事件定義與繼承關(guān)系MouseScrollRight定義于 src/textual/events.pyrich.repr.auto class MouseScrollRight(MouseEvent, bubbleTrue, verboseTrue): Sent when the mouse wheel is scrolled *right*. - [X] Bubbles - [X] Verbose 從源碼可以看出該事件的兩個關(guān)鍵特征Bubbles冒泡事件會從產(chǎn)生它的控件向父控件逐級冒泡父級可以統(tǒng)一監(jiān)聽或攔截通過調(diào)用event.stop()Verbose冗長日志與Click等非 Verbose 事件不同滾動事件屬于高頻事件Textual 會將其記錄在冗長日志verbose log中方便調(diào)試滾動相關(guān)的交互問題但生產(chǎn)環(huán)境日志中不會默認輸出這些高頻噪聲。它與同族的 MouseScrollUp、MouseScrollDown、MouseScrollLeft 一樣都直接繼承自MouseEvent見 src/textual/events.py本身不新增任何字段全部屬性和方法均來自父類。注意原文檔明確指出——完整的屬性與方法列表見MouseEvent。因此理解MouseScrollRight的關(guān)鍵在于吃透MouseEvent提供的坐標系、修飾鍵與滾動增量等信息。MouseEvent 提供的屬性與坐標系MouseScrollRight繼承自MouseEvent定義于 src/textual/events.py事件攜帶以下核心信息坐標類屬性屬性類型含義x/yint鼠標所在的相對單元格坐標相對接收事件的控件pointer_x/pointer_yfloat鼠標所在的相對像素級浮點坐標screen_x/screen_yint鼠標所在的屏幕絕對坐標相對屏幕左上角pointer_screen_x/pointer_screen_yfloat屏幕絕對坐標的浮點版本offsetOffset(x, y)組合成的相對偏移量screen_offsetOffset(screen_x, screen_y)組合成的屏幕偏移量滾動增量類屬性屬性類型含義delta_xint自上次鼠標消息以來 x 方向的變化量delta_yint自上次鼠標消息以來 y 方向的變化量deltaOffset(delta_x, delta_y)組合成的增量偏移量修飾鍵與按鈕屬性類型含義shiftboolShift 鍵是否按下metaboolMeta 鍵是否按下ctrlboolCtrl 鍵是否按下buttonint被按下的按鍵索引styleStyle鼠標下方光標位置的 Rich Style實用方法get_content_offset(widget)返回鼠標在指定控件內(nèi)容區(qū)內(nèi)的偏移量若落在 padding 或 border 區(qū)域則返回Noneget_content_offset_capture(widget)即使鼠標不在內(nèi)容區(qū)內(nèi)也返回相對內(nèi)容區(qū)左上角的偏移量_apply_offset(x, y)在事件坐標基礎(chǔ)上平移生成新事件用于消息沿 DOM 樹向下轉(zhuǎn)發(fā)時校正坐標系。這些坐標均為單元格cell整數(shù)坐標因為終端渲染以字符單元為最小單位delta_x/delta_y由XTermParser依據(jù)上一次鼠標位置實時計算見下文觸發(fā)鏈路。事件的產(chǎn)生鏈路從 ANSI 序列到 MouseScrollRightMouseScrollRight并非憑空產(chǎn)生而是由終端的 SGR 鼠標協(xié)議\x1b[...M/m序列解析而來。核心解析邏輯位于 src/textual/_xterm_parser.pyif buttons 64: event_class [ events.MouseScrollUp, events.MouseScrollDown, events.MouseScrollLeft, events.MouseScrollRight, ][buttons 3] button 0這段代碼揭示了事件類型的分派規(guī)則SGR 序列中的按鈕碼與64做按位與若結(jié)果非零則說明這是滾動事件隨后用buttons 3取低 2 位作為索引映射到四個滾動方向其中索引3即對應(yīng)MouseScrollRight。解析器還會維護上一次的鼠標坐標last_x/last_y據(jù)此計算delta_x int(x) - int(self.last_x) delta_y int(y) - int(self.last_y)并提取修飾鍵狀態(tài)bool(buttons 4), # shift bool(buttons 8), # meta bool(buttons 16), # ctrl測試用例印證倉庫測試 tests/test_xterm_parser.py 對右側(cè)滾動事件的解析做了參數(shù)化驗證pytest.mark.parametrize( sequence, shift, meta, [ (\x1b[67;18;25M, False, False), (\x1b[71;18;25M, True, False), (\x1b[75;18;25M, False, True), ], ) def test_mouse_scroll_right(parser, sequence, shift, meta): events list(parser.feed(sequence)) assert len(events) 1 event events[0] assert isinstance(event, MouseScrollRight) assert event.x 17 assert event.y 24 assert event.shift is shift assert event.meta is meta可以看到序列\(zhòng)x1b[67;18;25M按鈕碼 67 64 3被正確解析為一個MouseScrollRight事件坐標為(17, 24)序列中坐標從 1 開始計數(shù)源碼中減 1 轉(zhuǎn)為 0 基坐標且不帶修飾鍵按鈕碼 71、75 則分別驗證了 Shift、Meta 鍵狀態(tài)位的解析。Widget 中的默認行為驅(qū)動橫向滾動Textual 的Widget基類為滾動事件提供了開箱即用的默認處理。在 src/textual/widget.py 中def _on_mouse_scroll_right(self, event: events.MouseScrollRight) - None: if self.allow_horizontal_scroll: if self._scroll_right_for_pointer(): event.stop() def _on_mouse_scroll_left(self, event: events.MouseScrollLeft) - None: if self.allow_horizontal_scroll: if self._scroll_left_for_pointer(): event.stop()這意味著當鼠標在支持水平滾動的控件allow_horizontal_scroll為真上向右滾動時Textual 會自動調(diào)用_scroll_right_for_pointer()執(zhí)行滾動滾動成功返回True后調(diào)用event.stop()停止冒泡避免父級重復處理因此如果你的控件本身具備水平滾動能力如設(shè)置了overflow-x: auto無需編寫任何代碼即可獲得橫向滾輪支持。如何監(jiān)聽與自定義處理由于事件具有冒泡特性你可以用兩種方式捕獲MouseScrollRight。方式一命名約定法按照 Textual 的命名約定為事件添加on_前綴、將類名轉(zhuǎn)為蛇形命名即可自動關(guān)聯(lián)處理器from textual.app import App, ComposeResult from textual.widgets import Static class ScrollWatcher(Static): def on_mouse_scroll_right(self, event: events.MouseScrollRight) - None: # 事件默認已由基類用于橫向滾動若想自定義可在此覆蓋 self.log(fScrolled right at ({event.screen_x}, {event.screen_y})) event.stop() # 停止冒泡方式二on裝飾器法Textual 的 [on][textual.on] 裝飾器用法見 docs/guide/events.md允許為事件綁定任意命名的方法且可配合 CSS 選擇器精確指定要監(jiān)聽的控件from textual import on from textual.events import MouseScrollRight class MyApp(App): on(MouseScrollRight, #content) def handle_scroll(self, event: MouseScrollRight) - None: self.notify(fRight scroll at x{event.delta_x})提示on裝飾器要求消息類具備control屬性MouseEvent的control屬性即返回鼠標下的控件見 src/textual/events.py因此可用于選擇器匹配。與 Shift/Ctrl 組合Textual 的默認行為中垂直滾輪配合shift/ctrl也會被轉(zhuǎn)換為橫向滾動見 src/textual/widget.py 中_on_mouse_scroll_down/_on_mouse_scroll_up的event.ctrl or event.shift分支。因此在實際終端中即使硬件沒有橫向滾輪也可以用「Shift 垂直滾輪」觸發(fā)等價的橫向滾動效果。調(diào)試與日志由于MouseScrollRight標記為verboseTrue當你在終端按CtrlE打開 Textual Devtools 的日志或?qū)⑷罩炯墑e調(diào)至 verbose 時滾動事件會以類似以下形式輸出來自__rich_repr__見 src/textual/events.pyMouseScrollRight(None, x17, y24, delta_x0, delta_y0, button0, shiftFalse, metaFalse, ctrlFalse)其中各字段只有在非默認值時才會展示便于快速定位坐標與修飾鍵狀態(tài)。與其他鼠標事件的協(xié)同MouseScrollRight通常與以下事件配合使用構(gòu)成完整的鼠標交互體系MouseScrollLeft向左滾動MouseScrollUp / MouseScrollDown垂直方向滾動Click、MouseDown、MouseUp點擊類交互MouseMove指針移動Enter / Leave鼠標進入/離開控件區(qū)域。設(shè)計自定義滾動控件如橫向走馬燈、圖表橫軸縮放、水平菜單切換時可在處理器中讀取event.delta_x作為步進量或讀取event.x/event.y判斷滾動位置實現(xiàn)精細的分步控制。小結(jié)MouseScrollRight繼承自MouseEvent具有冒泡與冗長日志特性本身不新增字段它的產(chǎn)生源于XTermParser對 SGR 鼠標協(xié)議序列的解析按鈕碼 64判定滾動、 3判定方向3為右Widget基類默認將其映射為水平右向滾動可零代碼使用自定義處理可使用命名約定或on裝飾器注意通過event.stop()控制冒泡。相關(guān)源碼與測試索引事件類定義src/textual/events.py父類MouseEventsrc/textual/events.pyANSI 序列解析src/textual/_xterm_parser.py默認滾動行為src/textual/widget.py解析測試tests/test_xterm_parser.py事件處理指南docs/guide/events.md【免費下載鏈接】textualThe lean application framework for Python. Build sophisticated user interfaces with a simple Python API. Run your apps in the terminal and a web browser.項目地址: https://gitcode.com/gh_mirrors/te/textual創(chuàng)作聲明：本文部分內(nèi)容由AI輔助生成（AIGC），僅供參考