Qtile 窗口命令 API 全指南：在命令图中控制浮动、全屏、透明度与 Z 轴图层

桌面应用操作系统【免费下载链接】qtile:cookie: A full-featured, hackable tiling window manager written and configured in Python (X11 Wayland)项目地址https://gitcode.com/gh_mirrors/qt/qtile点击查看免费下载导读在 Qtile 中窗口的尺寸与位置通常由当前布局layout决定但窗口自身仍可通过一组丰富的命令改变外观与行为切换浮动状态、进入全屏、调节透明度、调整 Z 轴图层次序、跨组/跨屏移动等。本文以 docs/manual/commands/api/windows.rst 为骨架结合 libqtile/backend/base/window.py、X11/Wayland 双后端实现与对应测试系统梳理窗口对象暴露的全部命令及其底层原理。读完本文你将能够在键位绑定、鼠标回调、qtile shell、qtile cmd-obj 以及 Python 脚本CommandClient / InteractiveCommandClient中熟练调用这些窗口命令并理解 X11 与 Wayland 后端在实现上的差异。窗口对象与命令图Qtile 将窗口管理器拆解为八类基本对象构成一棵命令图command graphlayouts、windows、groups、bars、widgets、screens、core以及一个特殊的root节点。图形结构见 docs/manual/commands/command_graph.rst每一条边都表示持有对某对象的引用。窗口节点正是这八类节点之一。如 windows.rst 所述窗口的尺寸与位置由当前布局决定但窗口仍可以多种方式改变自身外观例如切换浮动状态、全屏、调节透明度窗口还可以访问与其显示相关的对象即它所在的屏幕screen、所属的工作组group和当前布局layout。这种连通性使得在某个对象上触发的回调中可以轻易顺藤摸瓜地访问到相关对象。文档自动生成机制windows.rst 本身是一份由 Sphinx 指令生成的 API 页面它通过qtile_commands指令以libqtile.backend.base.Window为基类将代码中所有用expose_command()装饰的方法自动展开为命令文档。对应的指令实现位于 docs/qtile_docs/commands.py它反射类成员检查_cmd标记收集全部公开命令并同时生成lazy.window.command()与qtile cmd-obj -o window -f command两种调用语法的示例。因此只要源码中新增了expose_command()方法本页 API 文档就会自动同步更新这保证了文档与实现始终一致。访问窗口命令的多种接口命令图中的命令可通过五种接口调用详见 docs/manual/commands/interfaces.rst。以窗口命令为例同一操作在五种接口中的写法分别为# 1. lazy 接口用于配置脚本中的键位与鼠标回调 lazy.window.toggle_floating() # 2. qtile shell将命令图映射为虚拟文件系统 cd window window toggle_floating() # 3. qtile cmd-obj适合 shell 脚本 qtile cmd-obj -o window -f toggle_floating # 4. CommandClient低级 Python 接口 from libqtile.command.client import CommandClient c CommandClient() c.navigate(window, None).call(toggle_floating) # 5. InteractiveCommandClient高级 Python 接口语法模仿 lazy from libqtile.command.client import InteractiveCommandClient c InteractiveCommandClient() c.window.toggle_floating()需要注意从根节点出发时当前window、group、layout、screen都可以省略选择器而直接访问当前对象而widget与bar节点必须携带选择器。若某条路径解析不到对象例如访问一个未显示在屏幕上的组所关联的 screen会抛出CommandError: No object screen in path ...异常。窗口对象的类层次Window / Internal / Static在 libqtile/backend/base/window.py 中窗口对象被划分为三个抽象子类均继承自_WindowCommandObject的子类由各后端分别实现Window普通客户端窗口由布局管理。它持有qtile引用、float_x/float_y浮动偏移、bordercolor边框颜色与_float_state浮动状态等关键属性。repr形如Window(name..., wid...)。InternalQtile 自身拥有的内部窗口典型如 bar。它需要实现create_drawer()来绘制内容并处理按键、指针进入/离开/移动、按钮点击等事件。Static绑定到屏幕而非工作组的窗口info()命令返回name、wm_class、x、y、width、height、id、opacity等字段。此外窗口还有若干只读属性供命令与布局使用例如has_fixed_ratio()客户端要求固定宽高比对应 X11 的PAspect提示、has_fixed_size()固定尺寸与urgent紧急请求焦点X11 下对应_NET_WM_STATE_DEMANDS_ATTENTION。布局定尺寸窗口定状态浮动 / 全屏 / 最大化 / 最小化窗口的几何行为由浮动状态机统一管理。状态定义见 libqtile/backend/base/float_states.pyclass FloatStates(enum.Enum): NOT_FLOATING 1 # 平铺 FLOATING 2 # 浮动 MAXIMIZED 3 # 最大化 FULLSCREEN 4 # 全屏 TOP 5 # 置顶 MINIMIZED 6 # 最小化基类的Window.maximized、fullscreen、minimized属性均直接以_float_state为准。进入/退出全屏的核心逻辑在_set_fullscreen()window.py#L305-L323进入全屏时先调用save_float_state()记录当前几何与状态然后按屏幕全尺寸扣除fullscreen_border_width重排浮动几何退出时调用restore_float_state()恢复。最大化maximizedsetter与之对称使用max_border_width作为边框扣除。save_float_state()与restore_float_state()window.py#L340-L361把base_x/base_y/base_width/base_height作为退出全屏/最大化后恢复的锚点。状态切换命令基类Window声明了一组成对的抽象命令均由具体后端实现命令作用toggle_floating()/enable_floating()/disable_floating()切换/强制进入/强制退出浮动toggle_maximize()/toggle_minimize()切换最大化 / 最小化toggle_fullscreen()/enable_fullscreen()/disable_fullscreen()切换/进入/退出全屏在 Wayland 后端libqtile/backend/wayland/window.py#L864-L893中这些命令实现得非常直接toggle_floating()即self.floating not self.floatingtoggle_fullscreen()即self.fullscreen not self.fullscreenfullscreen与maximized的 setter 进一步触发_update_fullscreen()/_update_maximized()向合成器同步状态。进入浮动时若配置了floats_kept_aboveTrue窗口会被自动放入 keep-above 图层见get_new_layer()wayland/window.py#L634-L641。X11 后端在info()中x11/window.py#L668-L694额外返回float_info浮动时的 x/y/width/height与floating/maximized/minimized/fullscreen布尔字段。测试 test/backend/x11/test_window.py#L195-L203 验证了窗口从浮动10×10切换为平铺398×578再切换为全屏800×600的几何变化。透明度控制基类Window提供三组透明度命令window.py#L533-L551set_opacity(opacity)设置透明度取值范围0.11.0小于 0.1 被钳制到 0.1大于 1 被钳制到 1up_opacity()/down_opacity()以 0.1 为步长递增/递减只读属性opacity0 表示全透明1 表示不透明。在 X11 后端透明度读写映射到 EWMH 的_NET_WM_WINDOW_OPACITY属性x11/window.py#L705-L722写入时将 0.0~1.0 的浮点值按0xFFFFFFFF缩放为整数读取时再换算回两位小数。测试 test/backend/wayland/test_window.py#L122-L159 完整覆盖了边界行为set_opacity(5.0)被钳到 1.0、set_opacity(-1.0)被钳到 0.1、连按down_opacity()十次后停在 0.1、连按up_opacity()十五次后停在 1.0——这也验证了基类的 IPC 命令在 0.1 处钳制而非 0.0这一细节。Z 轴图层置顶、置底与堆叠次序窗口堆叠遵循 EWMH 的分层规则desktop 层 → below 层 → 普通层 → above/dock 层 → 聚焦的全屏层Qtile 还额外增加了一个scratchpad 永远在最上的图层。基类定义了五组图层命令window.py#L153-L215命令语义keep_above(enableNone)保持窗口在其它窗口之上不传参时翻转当前状态keep_below(enableNone)保持窗口在其它窗口之下不传参时翻转当前状态move_up(forceFalse)沿 Z 轴向上移动一个位置普通窗口不会被提升到 keep_above 窗口之上move_down(forceFalse)沿 Z 轴向下移动一个位置普通窗口不会被压到 keep_below 窗口之下move_to_top()移动到当前图层的顶部例如三个 keep_above 窗口中调用者排第一move_to_bottom()移动到当前图层的底部bring_to_front()无视所有分层规则直接置顶窗口失去焦点后按规则重新入栈forceTrue的语义move_up(forceTrue)允许把 keep_below 的窗口提升上去同时清除其 keep_below 状态move_down(forceTrue)同理允许压过 keep_above 窗口。keep_above/keep_below在 X11 后端通过读写_NET_WM_STATE中的_NET_WM_STATE_ABOVE/_NET_WM_STATE_BELOW原子实现x11/window.py#L1394-L1484随后调用change_layer()依据get_layering_information()x11/window.py#L910-L971重排堆叠。Wayland 后端则直接映射到 wlr 合成器的图层keep_above将视图 reparent 到LAYER_KEEPABOVEkeep_below到LAYER_KEEPBELOWbring_to_front到LAYER_BRINGTOFRONT并调用qw_view_raise_to_topwayland/window.py#L80-L121。对应测试 test/backend/wayland/test_window.py#L88-L98 验证了bring_to_front()会把窗口从LAYER_LAYOUT移到LAYER_BRINGTOFRONT。位置与尺寸浮动几何的精细控制基类抽象定义了以下几何命令全部由后端实现命令作用place(x, y, width, height, borderwidth, bordercolor, aboveFalse, marginNone, respect_hintsFalse)把窗口放到指定位置并设置尺寸布局调度的底层通道get_position()返回(x, y)get_size()返回(width, height)move_floating(dx, dy)浮动窗口相对位移resize_floating(dw, dh)浮动窗口增减尺寸set_position_floating(x, y)浮动窗口移动到绝对坐标set_size_floating(w, h)浮动窗口设置为指定尺寸set_position(x, y)浮动窗口移动平铺窗口则与指针下的窗口交换位置center()将浮动窗口在屏幕上居中place()是布局调度窗口的底层通道。X11 实现x11/window.py#L804-L908展示了它的完整细节margin接受单个 int四边等距或[N, E, S, W]列表并据此收缩目标几何respect_hintsTrue时会尊重客户端的 WM_SIZE_HINTS受PMinSize/PMaxSize钳制、按PAspect校正宽高比、按base_width/width_inc与base_height/height_inc对齐增量会保存float_x/float_y屏幕相对偏移调用configure()下发 X 协议随后paint_borders()绘制边框并发送合成ConfigureNotify。Wayland 的place()wayland/window.py#L178-L258同样处理 margin并把边框颜色列表转换为 C 层的qw_border数组后调用合成器接口其set_position()在窗口为平铺状态时会遍历同组窗口与指针所在窗口调用group.layout.swap()交换wayland/window.py#L840-L857。center()命令是基类默认实现window.py#L569-L592仅对浮动窗口生效且要求窗口已属于某个显示中的屏幕然后按(screen.width - self.width) // 2计算居中坐标并调用place(..., aboveTrue, respect_hintsTrue)。在鼠标回调中的典型用法窗口几何命令最常见的实战场景是鼠标拖拽与调整大小参考 docs/manual/config/mouse.rstfrom libqtile.config import Click, Drag mouse [ # 用 mod左键拖动浮动窗口 Drag([mod], Button1, lazy.window.set_position_floating(), startlazy.window.get_position()), # 用 mod右键调整浮动窗口大小 Drag([mod], Button3, lazy.window.set_size_floating(), startlazy.window.get_size()), # 用 mod中键置顶窗口 Click([mod], Button2, lazy.window.bring_to_front()) ]其中start提供了拖拽的起始几何快照Drag会在指针移动时把增量传入绑定命令。跨组与跨屏移动togroup 与 toscreentogroup(group_nameNone, switch_groupFalse, toggleFalse)基类文档位于 window.py#L480-L505把窗口移动到指定工作组# 移动到当前组无实际效果 togroup() # 移动到名为 a 的组 togroup(a) # 移动到组 a并切换到该组 togroup(a, switch_groupTrue) # 若组 a 已在屏幕显示则改用上一个使用过的组 togroup(a, toggleTrue)toscreen(indexNone)则把窗口移动到指定屏幕——本质上是把窗口移交到该屏幕当前显示的组window.py#L507-L531# 移动到当前屏幕 toscreen() # 移动到屏幕 0 toscreen(0)索引越界会抛出CommandError: No such screen: ...。Wayland 的togroup()实现wayland/window.py#L526-L559还会先hide()再移交并在组未配置persistTrue时清理空组。静态窗口从布局中解放static(screenNone, xNone, yNone, widthNone, heightNone)把普通窗口转换为静态窗口——它不再属于任何工作组而是直接绑定屏幕几何由用户指定其余未指定的值沿用窗口当前状态。转换时窗口对象的defunct标记被置为 True表示不再作为普通窗口被管理并触发client_managedhookWayland 实现见 wayland/window.py#L469-L523。测试 test/backend/wayland/test_window.py#L40-L58 验证了 XDG shell 窗口调用static()后仍可从info()[shell]读到XDG而 layer shell 窗口的 shell 字段为layer。关闭、聚焦与信息查询killkill()关闭窗口。X11 实现遵循 ICCCM若窗口声明了WM_DELETE_WINDOW协议则发送ClientMessage礼貌请求关闭否则直接KillClientx11/window.py#L724-L747。Wayland 实现直接调用合成器视图的kill()wayland/window.py#L167-L168。典型键位绑定Key([mod1], F4, lazy.window.kill())。focus 与焦点机制focus(warpTrue)聚焦窗口并可选地将指针移动到窗口中心。X11 实现x11/window.py#L1289-L1333展示了一套完整的 ICCCM 聚焦协商流程若WM_HINTS的InputHint为真直接SetInputFocus否则若窗口声明了WM_TAKE_FOCUS协议发送携带合法时间戳的ClientMessage时间戳不能是CurrentTime聚焦成功后同步_NET_WM_STATE_FOCUSED状态、清除 urgent 标记、更新_NET_ACTIVE_WINDOW、重抓/解除旧窗口的按钮事件并触发client_focushook。此外还有两个与焦点相关的辅助属性can_steal_focus决定窗口是否可以抢走焦点X11 下类型为notification的窗口默认不允许activate_by_config()则依据配置项focus_on_window_activation取值focus/smart/urgent/never也可为可调用对象决定窗口请求激活时的行为——smart模式下若窗口在别的屏幕会置为 urgent 并触发client_urgent_hint_changedhookwindow.py#L611-L632。info 与 inspectinfo()返回窗口的元信息。基类文档要求至少包含name、x、y、width、height、group、id、wm_classwindow.py#L136-L151X11 与 Wayland 实现在此基础上追加floating、maximized、minimized、fullscreen、float_info等字段Wayland 还额外提供shell与opacitywayland/window.py#L657-L684。get_hints()仅 X11返回 WM_HINTS / WM_SIZE_HINTS 解析结果。inspect()仅 X11返回关于窗口的一切X 属性backing_store、map_state、事件掩码等、属性列表、协议、normal hints、state 与 float_infox11/window.py#L1340-L1392对应测试 test/backend/x11/test_window.py#L759 的test_inspect_window。空闲抑制add_idle_inhibitor 与 remove_idle_inhibitor为了在播放视频、全屏展示等场景下阻止系统进入空闲/睡眠基类暴露了空闲抑制命令window.py#L639-L652add_idle_inhibitor(inhibitor_typeopen)为窗口创建抑制规则inhibitor_type可选open、focus、fullscreen、visible默认openremove_idle_inhibitor()移除该窗口的抑制规则。两者最终都交由qtile.core.idle_inhibitor_manager统一管理对应 X11 的_NET_WM_IDLE_INHIBIT与 Wayland 的 idle inhibit 协议见 libqtile/backend/x11/idle_notify.py 与 libqtile/backend/wayland/idle_inhibit.py。配置中还可以通过idle_inhibitors规则批量声明哪些窗口、在什么条件下自动添加抑制window.py#L634-L637。在键位配置中的综合实战把上述命令组装成一套常见的窗口快捷键配置参考 docs/manual/config/keys.rstfrom libqtile.config import Key, Match from libqtile.lazy import lazy keys [ # 关闭窗口 Key([mod], c, lazy.window.kill()), # 切换浮动 Key([mod], space, lazy.window.toggle_floating()), # 切换全屏可配合 .when() 限定条件例如仅在窗口浮动时生效 Key([mod], f, lazy.window.toggle_fullscreen().when(when_floatingTrue)), # 仅对特定 wm_class 生效 Key([mod], x, lazy.window.toggle_fullscreen().when(focusedMatch(wm_classyourclasshere))), # Z 轴调整 Key([mod], k, lazy.window.move_up()), Key([mod], j, lazy.window.move_down()), Key([mod, shift], k, lazy.window.keep_above()), Key([mod, shift], j, lazy.window.keep_below()), Key([mod, control], k, lazy.window.bring_to_front()), # 跨组移动把窗口移到组 2 并切换过去 Key([mod, shift], 2, lazy.window.togroup(2, switch_groupTrue)), # 透明度微调 Key([mod], equal, lazy.window.up_opacity()), Key([mod], minus, lazy.window.down_opacity()), ]其中lazy.window.command()创建的是对命令的引用而非立即调用——这正是它能与键位/鼠标回调绑定的前提详见 docs/manual/config/lazy.rst 中的 Window functions 一节与 docs/manual/commands/interfaces.rst 的说明。togroup的可选参数switch_group、toggle也都在 lazy.rst 中有对应描述。后端差异小结与测试佐证能力X11 后端实现Wayland 后端实现置顶/置底EWMH_NET_WM_STATE原子 ConfigureWindow堆叠wlr layer-shell 图层 reparent透明度_NET_WM_WINDOW_OPACITY属性合成器直接支持焦点ICCCMWM_TAKE_FOCUS/ InputHint 协商qw_server_active_viewfocus_window()几何提示完整尊重WM_SIZE_HINTSrespect_hints暂标注为 TODOwayland/window.py#L214专属命令get_hints()、inspect()is_visible()直接查询合成器可见性所有窗口命令均被 test/backend/x11/test_window.py 与 test/backend/wayland/test_window.py 覆盖验证例如 X11 侧的浮动/全屏几何切换test_window.py#L195-L203、大小/宽高比提示test_min_size_hint等、多色边框test_multiple_borders以及 Wayland 侧的透明度边界、图层切换与info()的 shell 字段。结语窗口命令 API 是 Qtile可破解hackable特性的重要一环布局决定几何而窗口自身的浮动、全屏、透明度与图层状态完全交给用户通过命令图控制。无论是编写键位配置、实现鼠标手势还是通过 IPC 编写外部脚本掌握 windows.rst 中列出的这组命令就等于掌握了 Qtile 窗口层全部的用户可编程能力。想进一步了解其余对象的命令可继续阅读 docs/manual/commands/api/index.rst 中的 root、layouts、groups、bars、widgets、screens 与 backend 各页。赞分享桌面应用操作系统【免费下载链接】qtile:cookie: A full-featured, hackable tiling window manager written and configured in Python (X11 Wayland)项目地址https://gitcode.com/gh_mirrors/qt/qtile点击查看免费下载相关推荐Qtile 命令图接口Interfaces全解析lazy、qtile shell、cmd-obj 与 Python 命令客户端Qtile 命令图接口Interfaces全解析lazy、qtile shell、cmd obj 与 Python 命令客户端 导读 Qtile 是一款用桌面应用操作系统OpenSAGE与原版SAGE引擎对比兼容性测试与功能差异深度分析OpenSAGE与原版SAGE引擎对比兼容性测试与功能差异深度分析 OpenSAGE 是一款免费开源的 SAGE 引擎重实现项目旨在重现 EA PacifiQtile Shell 实战指南用命令行交互式驾驭 Qtile 命令图Qtile Shell 实战指南用命令行交互式驾驭 Qtile 命令图 Qtile shell qtile shell 是 Qtile 提供的一个命令行式桌面应用操作系统上一篇minimal-mistakes 文本对齐实战用 Kramdown 属性列表控制段落排版下一篇Apache Pulsar C 客户端源码构建全指南多平台编译、测试与配置详解创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考