1
# -*- coding: utf-8 -*-
2
# vim:set shiftwidth=4 tabstop=4 expandtab textwidth=79:
3
# $Id: plugin.py 431 2005-07-21 21:42:14Z aafshar $
4
#Copyright (c) 2005 Ali Afshar aafshar@gmail.com
6
#Permission is hereby granted, free of charge, to any person obtaining a copy
7
#of this software and associated documentation files (the "Software"), to deal
8
#in the Software without restriction, including without limitation the rights
9
#to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
10
#copies of the Software, and to permit persons to whom the Software is
11
#furnished to do so, subject to the following conditions:
13
#The above copyright notice and this permission notice shall be included in
14
#all copies or substantial portions of the Software.
16
#THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
17
#IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
18
#FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
19
#AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
20
#LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
21
#OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
24
"""This module provides the base plugin superclass"""
32
class Plugin(base.pidaobject):
33
""" The base plugin class.
35
This class is to be overriden for any object that wishes to have a
36
reference to the main Application object, or wishes to receive events
37
generated by the main Application object.
39
# Class attributes for overriding.
40
# The name of the plugin.
42
# The icon in the top left
44
# The alternative icon for tabs and tooltip
45
DICON = 'fullscreen', 'Detach window.'
46
# Whether the plugin is detachable.
50
#def __init__(self, cb):
54
# @param cb: An instance of the main application class.
55
# @type cb: C{pida.main.Application}
57
# @note: It is recommended that to add additional widgets to the plugin,
58
# that the populate_widgets method is overriden instead of this
61
# Instance of the Application class.
65
self.detach_window = None
68
def configure(self, reg):
71
def __populate__(self):
77
self.win.pack_start(self.bar, expand=False)
80
self.ctlbar = gtk.HBox()
81
self.bar.pack_start(self.ctlbar)
85
self.dtbut = gtk.ToggleToolButton(stock_id=None)
87
self.ctlbar.pack_start(eb, expand=False)
88
ic = self.do_get_image(self.DICON[0])
89
self.dtbut.set_icon_widget(ic)
90
self.dtbut.connect('toggled', self.cb_toggledetatch)
91
self.do_set_tooltip(eb, self.DICON[1])
92
# The main title label.
93
self.label = gtk.Label(self.NAME)
94
self.ctlbar.pack_start(self.label, expand=False)
95
# The horizontal expander.
96
self.sepbar = gtkextra.Sepbar()
97
self.sepbar.connect(self.cb_sep_rclick, self.cb_sep_dclick)
98
self.ctlbar.pack_start(self.sepbar.win, padding=6)
100
self.shortbar = gtk.HBox()
101
self.bar.pack_start(self.shortbar, expand=False)
102
# The custom tool bar.
103
self.cusbar = gtkextra.Toolbar()
104
self.bar.pack_start(self.cusbar.win, expand=False)
105
# The holder for transient windows.
106
self.transwin = gtk.VBox()
107
# self.transwin.show()
108
self.win.pack_start(self.transwin, expand=False)
110
self.msgbox = gtkextra.Messagebox()
111
self.transwin.pack_start(self.msgbox.win, expand=False)
113
self.qstbox = gtkextra.Questionbox()
114
self.transwin.pack_start(self.qstbox.win, expand=False)
116
self.frame = gtk.VBox()
117
self.win.pack_start(self.frame)
118
# The toolbar popup menu.
119
self.toolbar_popup = gtkextra.Popup()
120
#self.populate_widgets()
121
#self.connect_widgets()
122
#self.frame.show_all()
126
def populate_widgets(self):
128
Called after the constructor to populate the plugin.
130
Override this method and add the desired widgets to the plugin.
134
def connect_widgets(self):
136
Called after widget population to connect signals.
140
def add(self, widget, *args, **kwargs):
142
Add a widget to the plugin.
144
@param widget: The widget to add.
145
@type widget: L{gtk.Widget}
147
@param *args: Additional arguments to pass the pack_start method.
148
@param **kwargs: Additional kwargs to pass the pack_start method.
150
@note: use C{expand=False} in kwargs, to prevent widget expanding.
152
self.frame.pack_start(widget, *args, **kwargs)
154
def add_button(self, stock, callback, tooltip='None Set!', cbargs=[]):
156
Add a button to the plugin toolbar and toolbar menu.
158
@param stock: The icon name.
161
@param callback: The function to call back on button activation
162
@type callback: function
164
@param tooltip: The tooltip to display for the button.
165
@type: tooltip: string
167
@param cbargs: A list of arguments to pass the callback function.
170
@return: The newly created button.
171
@rtype: L{gtk.ToolButton}
173
self.toolbar_popup.add_item(stock, tooltip, callback, cbargs)
174
return self.cusbar.add_button(stock, callback, tooltip, cbargs)
176
def add_separator(self):
178
Add a separator to the toolbar and toolbar menu.
180
self.toolbar_popup.add_separator()
181
self.cusbar.add_separator()
183
def message(self, message):
185
Give the user a message in a transient window.
187
@param message: The text of the message to give the user.
188
@type message: C{str}
190
self.msgbox.message(message)
192
def question(self, message, callback):
194
Ask the user a question in a transient window.
196
The question is popped up to the user inside the plugin, and the
197
callback method is called on successful submission with the answer as
200
@param message: The prompt to display.
201
@type message: string
203
@param callback: The function to callback on submission.
204
@type callback: function
206
@note: the signature of the callback function will be:
208
C{def callback_function(answer):} for functions, and
210
C{def callback_function(self, answer):} for class methods.
212
self.qstbox.question(message, callback)
214
def attach(self, *a):
216
Reparent the plugin in the original parent.
218
self.win.reparent(self.oldparent)
219
self.detach_window.destroy()
220
self.detach_window = None
224
Reparent the plugin in a top-level window.
226
self.oldparent = self.win.get_parent()
227
self.detach_window = gtkextra.Winparent(self)
229
def log(self, message, level):
233
@param message: The message to be logged.
234
@type message: string
236
@param level: The log level.
239
# Add plugin name to message.
240
text = '%s: %s' % (self.NAME, message)
241
# Call the main log event.
242
self.cb.action('log', self.NAME, message, level)
244
def debug(self, message):
248
@param message: The message to be logged.
249
@type message: string
254
def info(self, message):
258
@param message: The message to be logged.
259
@type message: string
263
def warn(self, message):
267
@param message: The message to be logged.
268
@type message: string
272
def error(self, message):
276
@param message: The message to be logged.
277
@type message: string
281
def cb_sep_rclick(self, event):
283
Called when the toolbar separator is right clicked.
285
Default behaviour pops up the toolbar menu. Override this method to
286
change this behaviour.
288
@param event: The gdk event firing the callback.
289
@type event: gtk.gdk.Event
291
self.toolbar_popup.popup(event.time)
293
def cb_sep_dclick(self, event):
295
Called when the horizontal separator bar is double clicked.
297
Override this method to add desired bahaviour
299
@param event: The gdk event firing the callback.
300
@type event: gtk.gdk.Event
304
def cb_alternative(self):
306
The alternative function called for non detachable plugins.
310
def cb_toggledetatch(self, *a):
312
Called back when the detach button is clicked.
314
Detach the plugin for a detachable plugin, or call the alternative
315
callback for undetachable plugins.
317
# Check whether the detach button is active or not.
318
if self.dtbut.get_active():
319
# Detach detachable plugins, or call the alternative callback.
323
self.cb_alternative()
324
# Ensure the toggle button behaves normally.
325
self.dtbut.set_active(False)
327
# Reattach detached plugins.
333
# Event: called on initializing the plugin.
337
def evt_populate(self):
339
self.populate_widgets()
340
self.connect_widgets()
341
self.frame.show_all()
348
def get_window(self):
351
def get_main_toolbar(self):
354
def get_extra_toolbar(self):
357
class CommonEvents(object):
358
""" Just for reference """
359
def evt_started(self, serverlist):
361
Event: called on starting.
363
@param serverlist: A list of servers registered with the X root
365
@type serverlist: C{list} of C{(name, X-window ID)} pairs
371
Event: Called before shut-down.
377
Event: called when main configuration has been changed.
381
def evt_shortcuts(self):
383
Event: called for shortcuts window to be shown.
387
def evt_shortcutschanged(self):
389
Event: Called when shortcuts have been changed.
393
def evt_newterm(self, command, args, **kwargs):
395
Event: called to open a command in a new terminal.
397
@param command: The path to the command to be executed.
398
@type command: string
400
@param args: The argument list to pass the command (this usually
401
starts with the command name as the first argument)
404
@param kwargs: a list of additional keyword args to pass the terminal.
405
See the VTE reference manual for details.
409
def evt_log(self, title, message, level=0):
411
Event: called to log a mesage.
413
@param title: The title of the message.
416
@param message: The message.
417
@type message: string
419
@param level: The level to be logged.
424
def evt_connectserver(self, servername):
426
Event: called to connect to a server.
428
@param servername: The server to connect to.
429
@type servername: string
433
def evt_serverchange(self, servername):
435
Event: called when the server is changed
437
@param servername: The server connected to.
438
@type servername: string
442
def evt_badserver(self, servername):
444
Event: called after attempting to connect to a bad server.
446
@param servername: The bad server name.
447
@type servername: string
451
def evt_bufferlist(self, bufferlist):
453
Event: called when a new buffer list is received.
455
@param bufferlist: A list of loaded buffers.
456
@type bufferlist a C{list} of C{(number, name)} pairs
460
def evt_bufferchange(self, buffernumber, buffername):
462
Event: called when the buffer number has changed.
464
@param buffernumber: The number of the buffer changed to.
465
@type buffernumber: string
467
@param buffername: The path of the buffer changed to on disk.
468
@type buffername: string
472
def evt_bufferunload(self, *a):
474
Event: called when a buffer is unloaded.
478
def evt_filetype (self, buffernumber, filetype):
480
Event: called when the filetype is detected
482
@param buffernumber: The number of the buffer
483
@type buffernumber: string
485
@param filetype: The fieltype of file
486
@type filetype: string
490
def evt_bufferexecute(self):
492
Called to execute the contents of a buffer.
496
def evt_breakpointset(self, line, filename=None):
498
Called to set a breakpoint.
500
If no filename is passed, it is assumed that the current filename is
503
@param line: The line number to place the brakpoint.
504
@type line: int or string
506
@param filename: The filename to place the breakpoint.
507
@type filename: string
511
def evt_breakpointclear(self, line, filename=None):
513
Event: called to clear a breakpoint.
515
If no filename is passed, it is assumed that the current filename is
518
@param line: The line number to clear the brakpoint.
519
@type line: int or string
521
@param filename: The filename to clear the breakpoint.
522
@type filename: string
526
def evt_projectexecute(self, *a):
528
Event: called to execute the project.
532
def evt_doc(self, text):
534
Called to perform a doc lookup.
536
@param text: The text to lookup in doc.