DDE Dock Plugin Development

石博文 edited this page Aug 23, 2016 · 4 revisions

此文档已经过时

安装依赖

  • $sudo apt-get install dde-dock(目前插件接口的头文件还未分开打包)

1.插件接口说明

dockplugininterface.h

  • 类名 DockPluginInterface

  • 枚举值(用于DockPluginProxyInterface的infoChangedEvent函数)

  • enum InfoType

InfoTypeItemSize,//插件实例的size已经改变

InfoTypeAppletSize,//插件实例提供的插件内容窗口中的内容size已经改变

InfoTypeTitle,//插件实例的Title已经改变

InfoTypeEnable,//插件实例的启用标志已经改变

InfoTypeConfigurable//插件实例是否可显示在插件设置窗口上的标志已经改变

  • 函数 请继承该类并实现以下纯虚函数
  • virtual QString getPluginName() = 0;
  • 返回值:

目前只用于记录log,可以只返回空值

  • 参数:

  • 说明

  • virtual void init(DockPluginProxyInterface *proxy) = 0;
  • 返回值

  • 参数

详见dockpluginproxyinterface.h说明

  • 说明

DDE Dock在检查插件提供的.so文件可以正常加载后会调用此函数,建议插件的数据初始化放在此函数执行

  • virtual void changeMode(Dock::DockMode newMode, Dock::DockMode oldMode) = 0;
  • 返回值

  • 参数:
  1. newMode 切换后的显示模式
  2. oldMode 切换前的显示模式
  • 说明

当DDE Dock的显示模式改变后此函数会被调用,三种显示模式的尺寸并不相同,请根据相应的模式做好模式切换处理

  • virtual QStringList ids() = 0;
  • 返回值

插件的实例对象的id列表

  • 参数:

  • 说明

一个插件可以提供多个实例对象(如:无线网络插件可以根据无线网卡数量提供等量的插件实例对象以管理对应的无线网卡),此处返回的id列表将提供给插件设置窗口,设置窗口根据对应的id可以启用或者停用id所对应的插件实例

  • virtual QString getName(QString id) = 0;
  • 返回值

对应id的插件实例的名称

  • 参数:

id 插件实例的id

  • 说明

用于设置窗口显示的名称等

  • virtual QString getTitle(QString id) = 0;
  • 返回值

对应id的插件实例的标题

  • 参数:

id 插件实例的id

  • 说明

用于鼠标悬停在插件实例上时显示的标题(如果getApplet返回的值有效,则此函数返回值无效,可以返回任意值)

  • virtual QString getCommand(QString id) = 0;
  • 返回值

鼠标单击id对应插件实例时将会执行的命令

  • 参数:

id 插件实例的id

  • 说明

如果插件实例重写了鼠标单击事件,则此返回值无效;QString类型的命令返回后将使用QProcess执行

  • virtual QPixmap getIcon(QString id) {Q_UNUSED(id); return QPixmap("");}
  • 返回值

插件设置窗口中对应id设置项的图标

  • 参数:

id 插件实例的id

  • 说明

  • virtual bool configurable(const QString &id) = 0;
  • 返回值

对应id的插件实例是否可以显示在设置窗口上

  • 参数:

id 插件实例的id

  • 说明

某些插件可能需要一直显示或者其他特殊操作,请根据需要返回对应的值;当插件实例主动更改了此值,请主动通知DDE Dock此值已经改变,详见dockpluginproxyinterface.h说明

  • virtual bool enabled(const QString &id) = 0;
  • 返回值

对应id的插件实例启用与否

  • 参数:

id 插件实例的id

  • 说明

当插件实例主动更改了此值,请主动通知DDE Dock此值已经改变,详见dockpluginproxyinterface.h说明

  • virtual void setEnabled(const QString &id, bool enabled) = 0;
  • 返回值

  • 参数:
  1. id 插件实例的id
  2. enabled 是否启用插件实例
  • 说明

此函数会在插件设置窗口点击启用或禁用按钮时调用,请在此函数中处理插件实例被禁用后的工作(如:销毁对象并从DDE Dock上删除对应显示的插件实例,此时也应该主动通知DDE Dock对应的插件实例需要被移除,详见dockpluginproxyinterface.h说明)

  • virtual QWidget * getItem(QString id) = 0;
  • 返回值

真正显示在DDE Dock插件区域的内容

  • 参数:

id 插件实例的id

  • 说明

此函数会被多次调用;可以重写QWidget的mousePressEvent等函数以覆盖默认行为(比如鼠标按下时把对象销毁而不是执行getCommand函数提供的命令);如果所返回的QWidget对象的size改变后,请主动通知DDE Dock,详见dockpluginproxyinterface.h说明

  • virtual QWidget * getApplet(QString id) = 0;
  • 返回值

当鼠标悬在id对应的插件实例上时所弹出的插件内容窗口中的内容

  • 参数:

id 插件实例的id

  • 说明

此函数会被多次调用;如果所返回的QWidget对象的size改变后,请主动通知DDE Dock,详见dockpluginproxyinterface.h说明

  • virtual QString getMenuContent(QString id) = 0;
  • 返回值

规定格式的JSON字符串,右键单击id对应的插件实例时显示

  • 参数:

id 插件实例的id

  • 说明

默认会提供"运行"和"移除"菜单选项,如果不想提供这两个选项,请返回空字符串,如果想显示其他菜单项,请按照规定格式的JSON字符串返回有效的字符串

  • virtual void invokeMenuItem(QString id, QString itemId, bool checked) = 0;
  • 返回值

  • 参数:
  1. id 插件实例的id
  2. 菜单项的id
  3. 菜单是否勾选
  • 说明

详细参数请参考规定格式的JSON字符串(注:此处给出的连接目前是tower上的连接,组织以外的人员无法查看,请把文档更新到github的wiki上后及时通知本文维护者进行修改)

dockpluginproxyinterface.h

  • 类名 DockPluginProxyInterface

  • 函数 以下函数只用于插件内调用,不需要继承此类,更不需要重写函数,此接口的实现在DDE Dock主程序处理。在DockPluginInterface的init函数会传递该类的一个对象,请在DockPluginInterface的init函数调用时保存该对象以在插件运行过程中调用

  • virtual Dock::DockMode dockMode() = 0;

返回值

DDE Dock当前的显示模式

参数

说明

  • virtual void itemAddedEvent(QString id) = 0;

返回值

参数

id 插件实例id

说明

当需要DDE Dock加载id对应的插件实例时,请调用此函数。DDE Dock在此函数调用时会调用DockPluginInterface的getItem方法获得一个有效的QWidget对象并将其插入DDE Dock的插件区域以显示

  • virtual void itemRemovedEvent(QString id) = 0;

返回值

参数

id 插件实例id

说明

当需要从DDE Dock的插件区域移除id对应的插件实例时,请调用此函数。请注意此函数与DockPluginInterface的configurable和enabled函数以及此类的infoChangedEvent结合使用,因为在插件实例移除的过程中有可能需要从设置窗口也移除相应的设置项,但是某些情况下即使id对应的插件实例已经被移除,但是依然需要保留设置项。

  • virtual void infoChangedEvent(DockPluginInterface::InfoType type, const QString &id) = 0;

返回值

参数

  1. type 改变的信息类型,请参考DockPluginInterface类的说明
  2. id 插件实例id

说明

每当插件某个实例的某些状态变化时都应该主动调用此函数通知DDE Dock,以便DDE Dock根据新的数据作出变化。比如在DDE Dock的模式改变时插件实例的size也应该会跟着改变,当某个插件实例的size改变之后,就应该调用此函数,这样DDE Dock就会根据新的大小给对应的插件实例分配相应的空间显示。

2.给QPluginLoader提供的JSON文件

插件开发时需要额外提供一个JSON文件,此文件的内容在DEE Dock加载插件时会读取并根据信息作进一步的加载处理,详见:QPluginLoader::metaData()

  1. 当前插件需要提供两个值,如下: { "api_version" : 1.0, "sys_plugin" : true } api_version:当前只有1.0版本,请填写1.0 sys_plugin:是否为系统级插件,一般情况请填写false
  2. 在.pro文件中包含此JSON文件: DISTFILES += dde-dock-my-plugin.json
  3. 在插件的类声明中加入(只需要把FILE改成你所提供的JSON文件的名字): Q_PLUGIN_METADATA(IID "org.deepin.Dock.PluginInterface" FILE "dde-dock-my-plugin.json")

3.开发示例

注:将来示例中的插件可能会被移动到其他项目,请更新示例链接

  1. 一个简单的例子
  2. 单插件实例的示例
  3. 多插件实例的示例
  4. 不可在插件设置窗口设置的示例
  5. 覆盖默认事件的示例
You can’t perform that action at this time.
You signed in with another tab or window. Reload to refresh your session. You signed out in another tab or window. Reload to refresh your session.
Press h to open a hovercard with more details.