编写GNOME Shell扩展的文档

Question

我被要求自定义GNOME 3桌面的布局.显然,这样做的方法是写一个"扩展".

我已经成功完成了一些我想做的事情,但我完全缺乏信息.我无法找到任何有用的文档的任何地方.我浪费了生命中的一整天疯狂地搜索每一个可以想象的搜索词,以寻求有用的信息.

GNOME网站有数百个下载扩展.这些不是简单的3线; 它们是复杂的代码片段.它无法相信任何人都可以在没有文件解释如何做的情况下编写这些内容.

请问,有人能告诉我实际文件在哪里吗？到目前为止,我设法做的最好的事情是拆开现有的扩展程序,试图找到执行我感兴趣的特定位的魔术命令.(这不是一件容易的事!)

命令名称,对象路径,示例程序,任何东西都会有所帮助!

Answer 1

我最近自己挖了它.文档通常稀疏或过时.以下是一些帮助我开始(并通过开发)的资源:

• 基本的东西
• 关于开发的基本知识
• 分步教程
• 许多库的JavaScript绑定的非官方文档
• gnome-shell的JavaScript绑定的来源
• St(Shell Toolkit)Ui-Toolkit组件的说明.
• 一些非官方的指导方针,可以在extensions.gnome.org上获得您的扩展

由于文档几乎不可用(或最新),您需要进行大量的源读取.我链接了上面的gnome-shell源代码(JavaScript部分),这是潜入官方文档未涵盖的部分(这是你会发现的最完整的部分)的良好开端.

还有一点特别有用的是检查extensions.gnome.org是否有与你想要创建类似的东西的扩展,并查看它们的来源(大多数是GitHub或Bitbucket上的开源.你也可以安装它们并找到它们来源~/.local/share/gnome-shell/extensions/).

在搜索要使用的内容或有关特定函数的更多文档时,您还可以查阅手册以获取不同语言的绑定(认为参数和返回值可能不匹配).

最后但同样重要的是,这里有一些调试建议:

LookingGlass并不是特别有用.它只显示一行异常(描述),并且只有在启动时(首次启动扩展时)才会出现.

有关完整的StackTraces和运行时异常,请参阅~/.xsession-errors-file.它可能很长很臃肿.我用这个方便的脚本来阅读它:

# 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终端中的-tool 启动首选项,以查看控制台上的任何异常输出(您也可以调用工具gnome-shell-extension-prefs [uuid],直接显示扩展首选项).

由于目前没有真正的断点调试方法(有,但它很棘手),您可以登录控制台进行快速检查,使用print()-function.您将看到上面提到的输出(在sessions-error文件中或在启动gnome-shell-extension-prefs-tool 时在终端上).

尽管进入它可能有点困难,但扩展框架非常强大.有乐趣!

我写了一篇更详细的Blog-Post,可以在这里找到:制作Gnome-Shell Extensions

Answer 2

可以在Gnome Developer - API Reference页面上找到大量参考文献.

我使用以下内容进行扩展,但您的使用可能会有所不同:

• GTK + 3
  GTK +是用于在GNOME应用程序中构建用户界面的主库.它提供用户界面控件和信号回调来控制用户界面.

• GDK 3
  GDK是一个中间层,它将GTK +与窗口系统的细节隔离开来.

• Clutter
  Clutter是一个基于GObject的库,用于创建快速,视觉丰富的图形用户界面.

• GObject Introspection
  GObject Introspection正在努力在(基于GObject的)C库和语言绑定之间提供中间件层.

• Shell
  Shell参考手册

• St
  St - Shell Toolkit - 是GNOME Shell定制的基于Clutter的工具包,它定义了有用的actor.其中一些演员,例如StBoxLayout并StBin实现各种布局选项.

• 图标主题规范
  此 freedesktop.org规范描述了存储图标主题的常用方法.

注意:最后两个在查找视觉元素参数时非常有用!

• PyGTK
  PyGTK是Python的GTK +.该引用包含每个包含类描述的Python PyGTK模块(对应于底层GTK +库)的章节.

• PyGObject
  PyGObject是一个Python扩展模块,通过使用GObject Introspection提供对整个GNOME软件平台的干净和一致的访问.具体来说,它是GLib,GObject,GIO和GTK +的Python绑定.
  该引用包含每个包含类描述的PyGObject模块的章节.