Professional Documents
Culture Documents
Gedit Plugins Howto PDF
Gedit Plugins Howto PDF
Contents Files needed gedit plugin infrastructure Writing the plugin Minimal plugin Minimal plugin Implementing the window controller Implementing the window controller Making use of side/bottom panels Events Adding a configure dialog for your plugin Writing plugins without wrappers Template Template generator Most important API gedit gedit.App gedit.Window gedit.Panel gedit.Tab gedit.gedit.View gedit.Document gedit.Encoding
Files needed
Every python plugin needs at least two files. One file (pluginname.gedit-plugin) is to tell gedit where the plugin can be found, what it's called, a short description, who's the author, etc. This file is in the .desktop format (see example). The second file is the actual python code. Both of these files need to be placed in either the system-wide plugins directory /usr/lib/gedit-2/plugins/, or in the user plugins directory ~/.gnome2/gedit/plugins/.
examplepy.gedit-plugin
[Gedit Plugin] Loader=python Module=examplepy IAge=2 Name=Example py Description=A python plugin example Authors=Jesse van den Kieboom <jesse@icecrew.nl> Copyright=Copyright 2006 Jesse van den Kieboom <jesse@icecrew.nl> Website=http://www.gedit.org To explain the specified fields:
Loader: which loaded gedit needs to use, for python plugins this is python Module: the file in which your plugin is located (leaving out the extension .py). You can also specify a directory here. As with normal python applications you need to put a __init__.py in that directory) IAge: the plugin version, this is always 2 Name: the name of the plugin. This will show up in the plugins list in the preference dialog Description: a short description of the plugin. This will show up in the plugins list in the preference dialog Authors: a list of people who wrote the plugin. This will show up in the about dialog of the plugin (plugins list in the preference dialog) Copyright: the plugins copyright. This will show up in the about dialog of the plugin (plugins list in the preference dialog) Website: optionally, the plugins website
Now we need to create the plugin itself. The plugin is called examplepy, so we create examplepy.py. At the most minimal level, it just defines one class derived from gedit.Plugin defining activate, deactivate and update_ui:
Minimal plugin
import gedit class ExamplePyPlugin(gedit.Plugin): def activate(self, window): pass
Events
This is a very, very incomplete description of signals. A proper discussion of signals can be found in the `pyGTK tutorial`_. You *will* need to consult this. Your plugin can react to certain events (such as the opening of a tab or the saving of a file). This is accomplished by listening to signals from various gedit objects (gedit.Window and so on). A full specification of the signals emitted by each object can be found in the C API. To listen for a certain signal, use the connect() function of the object. The syntax is as follows: object.connect("signal", handler, other_arg1, ...) The signal that you are listening for is the first argument, in quotes. The second argument is the name of a function that will handle the signal event. The arguments to this function will vary by signal; consult the reference for your particular
Adding a configure dialog for your plugin Writing plugins without wrappers
If you want to write a plugin using Python, but the appropriate wrappers for a specific library are unavailable, you can use the 'dl' module to access the library's functions. For example, if you want to access the Enchant spell checking library you could use the following code: import dl class Enchant(object): def __init__(self, lang='en_US'): try: self.library = dl.open('libenchant.so') broker = self.library.call('enchant_broker_init') self.dict = self.library.call( 'enchant_broker_request_dict', broker, lang) except dl.error: self.incorrect_spelling = lambda x: False def incorrect_spelling(self, word): return bool(self.library.call('enchant_dict_check', self.dict, word, len(word)))
Template generator
A python plugin template can be easily generated using the little script attached to this page: gedit-py-plugin.py (mind that this is just a very simple little script, there is a much better one in the tools/ directory in gedit CVS)
gedit
The gedit module defines two functions to get the default gedit.App and to get a gedit.Tab from a gedit.Document.
app_get_default() : gets the default gedit.App instance tab_get_from_document(gedit.Document) : gets the gedit.Tab belonging to a gedit.Document
gedit.App
The gedit application provides functions to get all the gedit.Windows, create new windows, get all the documents, etc.
create_window([gdk.Screen]) : creates a new gedit.Window on a gdk.Screen. If gdk.Screen is omitted then the default screen will be used get_windows() : get a list of gedit.Window get_active_window() : get the currently active window get_documents() : get all the gedit.Document in all the windows get_views() : get all the gedit.View in all the windows
gedit.Window
The gedit window based on gtk.Window.
create_tab(jump_to) : create a new empty document. jump_to (boolean) specifies whether to select the new document when it's created create_tab_from_uri(uri, encoding, line_pos, create, jump_to) : open a file. uri (string) specifies the file to open. encoding (gedit.Encoding) specifies the encoding to use (None for default), line_pos (int) specifies to which line to jump when the file is opened. create (boolean) specifies whether to create a new file if it doesn't exist yet. jump_to (boolean) specifies whether to select the new document when it's created close_tab(tab) : close a tab (gedit.Tab) close_all_tabs() : closes all the tabs in the window get_active_tab() : gets the currently active tab (gedit.Tab) set_active_tab(tab) : sets the currently active tab (gedit.Tab) get_active_view() : gets the currently active view (gedit.View) get_active_document() : gets the currently active document (gedit.Document) get_documents() : gets a list of the documents (gedit.Document) in the window get_unsaved_documents() : gets a list of unsaved documents (gedit.Document) get_views() : get a list of the views (gedit.View) in the window get_group() : gets the gtk.`WindowGroup`_ the window belongs to get_side_panel() : gets the sidepanel (gedit.Panel) get_bottom_panel() : gets the bottompanel (gedit.Panel) get_statusbar() : gets the statusbar (gtk.Statusbar) get_ui_manager() : gets the ui manager (gtk.UIManager) get_state() : gets the state of the window (cumulative state of the different documents)
gedit.Panel
add_item(item, "name", image) : Adds an item (a gtkWidget) to the panel. image is the icon (usually a gtk.Image).
gedit.Tab
The tab is based on a gtk.VBox and is the controller of gedit.View and gedit.Document.
get_view() : get the view (gedit.View) get_document() : get the document (gedit.Document) get_state() : get the state set_auto_save_enabled(enabled) : sets whether autosave is enabled get_auto_save_enabled() : gets whether autosave is enabled set_auto_save_interal(interval) : sets the interval on which to perform autosave get_auto_save_interval() : gets the interval on which to perform autosave
gedit.View
The view is based on a gtksourceview and is the view for gedit.Document.
cut_clipboard() : cut selection to clipboard copy_clipboard() : copy selection to clipboard paste_clipboard() : paste clipboard at cursor position delete_selection() : deletes the selected text select_all() : select all text scroll_to_cursor() : scroll to the cursor position set_colors(def, background, text, selection, sel_text) sets the different colors to use. def (boolean) specifies whether to use the default colors. background, text, selection and sel_text are gdk.Color objects which specify the corresponding colors set_font(def, font_name) : sets the font to use. def (boolean) specifies whether to use the default font. font_name (string) specifies the font to use
gedit.Document
The document is based on a gtksourcebuffer and is the document for gedit.View.
get_uri() : gets the documents uri (or None if the document is unsaved) get_uri_for_display() : gets the documents uri for display (or None if the document is unsaved) get_short_name_for_dispaly() : gets the documents short name for display get_mime_type() : gets the documents mime type get_readonly() : gets whether the document is read only load(uri, encoding, line_pos, create) : loads a file. uri (string) specifies the file. encoding (gedit.Encoding) specifies the encoding (None for the defaultencoding). line_pos (int) : specifies the line to scroll to after loading. create (boolean) specifies whether to create the file if it doesn't exist yet. insert_file(iter, uri, encoding) : inserts the contents of a file. iter (gtk.`TextIter`_) specifies where to insert the file. uri specifies the file to insert. encoding (gedit.Encoding) specifies the encoding (None for the default encoding) load_cancel() : cancels the loading of a file is_untouched() : gets whether the document has been changed since the last time it was saved is_untitled() : gets whether the document has a title get_deleted() : gets whether the document has been deleted goto_line(line) : scroll to a line number. line (int) specifies the line number to scroll to set_search_text(text, flags) : set text to search for get_search_text() : gets the text to search for get_can_search_again() : gets whether the end of the document has not yet been reached search_forward : replace_all : search_backward : set_language(lang) : sets the source language of the document to lang (gtk.`SourceLanguage`_) get_language() : gets the source language of the document (gtk.`SourceLanguage`_)
gedit.Encoding
copy() : free() : get_charset() : gets the actual character set like 'UTF-8' get_name() : gets the name of the encoding like 'Unicode' to_string() : gets its string representation like 'Unicode (UTF-8)'