Commit 134abddb authored by Christian Hergert's avatar Christian Hergert
Browse files

doc: progress on workbench documentation

parent 8fd5d26d
########################
Extending the Header Bar
########################
......@@ -2,13 +2,16 @@
Creating Plugins
################
The following provides examples of various ways you can extend Builder.
All examples are provided in the Python 3 language for succinctness.
You can also implement plugins in C or Vala.
.. toctree::
:maxdepth: 3
:titlesonly:
creating
workbench
headerbar
workbench/index
greeter
editor/index
symbols/index
......
Registering Workbench Actions
=============================
Using ``Gio.Action`` is a convenient way to attach actions to the workbench that contain state.
For example, maybe for use by a button that should be insensitive when it cannot be used.
Additionally, actions registered on the workbench can be activated using the command bar plugin.
.. code-block:: python3
:caption: Registering an action on the workbench
import gi
from gi.repository import GObject
from gi.repository import Gio
from gi.repository import Ide
class MyWorkbenchAddin(GObject.Object, Ide.WorkbenchAddin):
def do_load(self, workbench):
action = Gio.SimpleAction.new('hello', None)
action.connect('activate', self.hello_activate)
workbench.add_action(action)
def do_unload(self, workbench):
workbench.remove_action('hello')
def hello_activate(self, action, param):
print('Hello activated!')
This adds a new action named ``hello`` to the workbench.
It can be connected to widgets by using the ``win.hello`` action-name.
Additionally, you can call the action with ``hello`` from the command bar.
To toggle whether or not the action can be activated. set the ``Gio.SimpleAction:enabled`` property.
The Basics
==========
The basic mechanics of extending the workbench requires first creating an ``Ide.WorkbenchAddin``.
Your subclass will created for each instance of the ``Ide.Workbench``.
This conveniently allows you to track the state needed for your plugin for each workbench.
.. code-block:: python3
:caption: A Basic WorkbenchAddin to demonstrate scaffolding
:name: basic-workbench-addin-py
import gi
from gi.repository import GObject
from gi.repository import Ide
class BasicWorkbenchAddin(GObject.Object, Ide.WorkbenchAddin):
def do_load(self, workbench: Ide.Workbench):
pass
def do_unload(self, workbench: Ide.Workbench):
pass
You will notice that at the top we import the packages we'll be using.
Here we use the ``GObject`` and ``Ide`` packages from GObject Introspection.
We then create a class which inherits from ``GObject.Object`` and implements the ``Ide.WorkbenchAddin`` interface.
The ``Ide.WorkbenchAddin`` interface has two virtual methods to override, ``Ide.WorkbenchAddin.load()`` and ``Ide.WorkbenchAddin.unload()``.
.. note:: PyGObject uses ``do_`` prefix to indicate we are overriding a virtual method.
The ``load`` virtual method is called to allow the plugin to initialize itself.
This method is called when the workbench is setup or your plugin is loaded.
When the ``unload`` virtual method is called the plugin should clean up after itself to leave Builder and the workbench in a consistent state.
This method is called when the workbench is destroyed or your plugin is unloaded.
Adding Widgets to the Header Bar
================================
You might want to add a button to the workbench header bar.
To do this, use an ``Ide.WorkbenchAddin`` and fetch the header bar using ``Ide.Workbench.get_headerbar()``.
You can attach your widget to either the left or the right side of the ``Ide.OmniBar`` in the center of the header bar.
Additionally, by specifying a ``Gtk.PackType``, you can align the button within the left or right of the header bar.
We suggest using ``Gio.SimpleAction`` to attach an action to the workbench and then activating the action using the ``Gtk.Button:action-name`` property.
.. code-block:: python3
:caption: Adding a button to the workbench header bar
import gi
from gi.repository import GObject
from gi.repository import Ide
class MyWorkbenchAddin(GObject.Object, Ide.WorkbenchAddin):
def do_load(self, workbench):
headerbar = workbench.get_headerbar()
# Add button to top-center-left
self.button = Gtk.Button(label='Click', action_name='win.hello', visible=True)
headerbar.insert_left(self.button, Gtk.PackType.PACK_END, 0)
def do_unload(self, workbench):
# remove the button we added
self.button.destroy()
self.button = None
#######################
Extending the Workbench
#######################
.. toctree::
:maxdepth: 3
:titlesonly:
basics
actions
headerbar
widgets
perspectives
panels
Registering Panels
==================
.. code-block:: python3
# my_plugin.py
import gi
from gi.repository import GObject
from gi.repository import Ide
class MyWorkbenchAddin(GObject.Object, Ide.WorkbenchAddin):
def do_load(self, workbench):
pass
def do_unload(self, workbench):
pass
Registering Perspectives
========================
.. code-block:: python3
# my_plugin.py
import gi
from gi.repository import GObject
from gi.repository import Ide
class MyWorkbenchAddin(GObject.Object, Ide.WorkbenchAddin):
def do_load(self, workbench):
pass
def do_unload(self, workbench):
pass
Adding Widgets to the Workbench
===============================
.. code-block:: python3
# my_plugin.py
import gi
from gi.repository import GObject
from gi.repository import Ide
class MyWorkbenchAddin(GObject.Object, Ide.WorkbenchAddin):
def do_load(self, workbench):
pass
def do_unload(self, workbench):
pass
Supports Markdown
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment