编写 GNOME Shell 扩展的文档

我被要求自定义 GNOME 3桌面的布局。显然，这样做的方法是写一个“扩展”。

我已经设法做了一些我想做的事情，但我完全感觉到 饿死了的信息。我找不到任何有用的文档 任何地方。我已经浪费了我的整个 几天的生活疯狂谷歌每一个可以想象的搜索关键词，在一个绝望的尝试找到有用的信息。

GNOME 网站有 成百上千的扩展可供下载。这些不是简单的3行代码; 它们是复杂的代码片段。如果没有文档说明如何编写，任何人都可以编写这些内容，这是令人难以置信的。

拜托，谁能告诉我真正的文件在哪里？到目前为止，我所做的最好的工作就是分解现有的扩展，试图找到执行我感兴趣的特定部分的神奇命令。(这可不是件容易的事!)

命令名称，对象路径，示例程序，什么都行会很有帮助！

17549 次浏览
小开
最佳答案

我最近也深入研究过。文档通常是稀疏的或过时的。下面是一些帮助我开始(和通过开发)的资源:

由于文档几乎是不可用的(或者是最新的) ，所以您需要进行 很多的源代码阅读。我链接了上面提到的 gnome-shell 源代码(JavaScript 部分) ，这是一个很好的开始，可以深入研究那些没有包含在 In- 官方文档中的部分(这是您能找到的最完整的部分)。

特别有帮助的是检查 Extensions.gnome.org中的扩展，这些扩展执行与您想要创建的内容类似的操作，并查看它们的源代码(其中大部分是 GitHub 或 Bitbucket 上的开放源代码)。您也可以安装它们并在 ~/.local/share/gnome-shell/extensions/下找到源代码)。

在搜索要使用的内容或特定函数的更多文档时，还可以参考不同语言的绑定手册(考虑到参数和返回值可能不匹配)。

最后但并非最不重要的是，这里有一些 调试建议:

LookingGlass 并不是特别有用。它只显示异常的一行(描述) ，并且仅当异常在启动时发生(当您的扩展首次启动时)。

对于完整的 StackTraces 和运行时异常，请参考 ~/.xsession-errors文件。可能会很长很肿。我用这个 手稿来读:

# Grabs the last session-errors from the current X11 session.
# This includes full Stack-Trace of gnome-shell-extension errors.
# See https://live.gnome.org/GnomeShell/Extensions/StepByStepTutorial#lookingGlass
tail -n100 ~/.cache/gdm/session.log | less

注意: 从 Gnome 3.6开始，如果使用 gdm作为显示管理器，当前会话日志是文件 ~/.cache/gdm/session.log。

在一些使用 systemd 的新发行版上，您可以通过以下方式获取错误日志:

journalctl -f /usr/bin/gnome-session

对于您的扩展的 调试 prefs-part，您可以从终端使用 gnome-shell-extension-prefs工具启动首选项，以查看控制台上的任何异常输出(您也可以调用类似于 gnome-shell-extension-prefs [uuid]的工具，以直接显示您的扩展首选项)。

由于目前还没有实际的方法来调试断点(有，但是 这很棘手) ，您可以使用 print()-函数进行 登录控制台快速检查。您将看到上面提到的输出(在 session-error 文件中或启动 gnome-shell-extension-prefs-tool 时在终端上)。

虽然可能有点难以理解，但是扩展框架非常强大！

我写了一个 更详细的博客文章，可以在这里找到: 制作 Gnome-Shell 扩展

小开

在 Gnome 开发者-API 参考页面上可以找到大量的参考文献。

我使用下面的扩展名，但您的用法可能有所不同:

  • GTK + 3
    GTK + 是用于在 GNOME核心程式列表中构建用户界面的主要库。它提供用户界面控件和信号回调来控制用户界面。

  • GDK 3
    GDK 是一个中间层，它将 GTK + 从视窗系统的细节中分离出来

  • 杂物
    Clutter 是一个基于 GObject 的库，用于创建快速、可视化丰富的图形用户界面

  • GObject 自省
    GObject 内省致力于在(基于 GObject 的) C 库和语言绑定之间提供一个中间件层。

  • 壳牌
    外壳参考手册

  • 圣
    St-壳牌工具箱-是 GNOME Shell 定制的基于 Clutter 的工具包，它定义了有用的角色。其中一些参与者，例如 StBoxLayout和 StBin实现了各种布局选项。

  • 图标主题规格
    这个 Freedesktop.org规范描述了一种存储图标主题的常用方法

注意: 最后两个对于查找可视化元素参数非常有帮助！

  • PyGTK
    PyGTK 是 Python 的 GTK + 。此引用包含每个 Python PyGTK 模块(对应于底层 GTK + 库)的一章，其中包含类描述。

  • PyGObject
    PyGObject 是一个 Python 扩展模块，可以通过使用 GObject 内省对整个 GNOME 软件平台进行干净和一致的访问。具体来说，它是用于 GLib、 GObject、 GIO 和 GTK + 的 Python 绑定。
    这个引用包含每个 PyGObject 模块的一章，其中包含类描述。

小开

文件是关于:

Https://gjs.guide/extensions/

图书馆文献资料:

Https://gjs-docs.gnome.org/

更多有关 https://gjs.guide/extensions/overview/architecture.html的资料

其他你可能想检查的东西是

Https://gitlab.gnome.org/gnome/gnome-shell/blob/main/js/ui/popupmenu.js

Https://gitlab.gnome.org/gnome/gnome-shell/blob/main/js/ui/dialog.js

Https://gitlab.gnome.org/gnome/gnome-shell/blob/main/js/ui/modaldialog.js

Https://gitlab.gnome.org/gnome/gnome-shell/blob/main/js/ui/panelmenu.js

Https://gitlab.gnome.org/gnome/gnome-shell/tree/main/js

Https://gitlab.gnome.org/gnome/mutter

您可以在 js/下浏览更多要重用的代码。

您可能还需要检查 https://gi.readthedocs.io/en/latest/index.html

问题:

除了一些 CSS 和 Javascript 文档，我在 https://gjs-docs.gnome.org/下找不到任何东西！

回答:

你必须首先让文件使用它们，在这里，你将主要寻找:

  • 杂物
  • 超能力者
  • Shell
  • 斯特

创建如下文件:

echo '{"docs":"clutter9~9_api/clutterx118~8_api/gobject20~2.66p/meta9~9_api/shell01~0.1_api/st10~1.0_api","hideIntro":"1"}' > devdocs.json

将此文件导入到 https://gjs-docs.gnome.org/settings

现在你可以参观:

Https://gjs-docs.gnome.org/shell01~0.1_api-global/

Https://gjs-docs.gnome.org/shell01~0.1_api/

Https://gjs-docs.gnome.org/meta9~9_api/

Https://gjs-docs.gnome.org/st10~1.0_api/

Https://gjs-docs.gnome.org/clutter9~9_api/

Https://gjs-docs.gnome.org/clutter9~9_api-actor/

警告: devdocs.json文件上的版本是硬编码的。它很快就会过时，所以你可能需要检查一下版本。关键是，在启用文档之前，您无法访问它们。

我知道，这是一团糟，他们就是这样做的。


提交答案