1"""
2All plugins need to import this module and inherit from the Plugin class.  A
3basic plugin could look something like this:
4
5	import geany
6	from geany.plugin import Plugin
7
8	class OpenNewDocumentPlugin(Plugin):
9
10		__plugin_name__ = "Open new document plugin"
11
12		_doc = None
13
14		def __init__(self):
15			Plugin.__init__(self)
16			print "About to open a new document"
17			self.open_document('/path/to/some/file')
18
19		def open_document(self, filename):
20			self._doc = geany.document.open(filename)
21
22		def close_document(self):
23			self._doc.close()
24			self._doc = None
25
26		def cleanup(self):
27			if self._doc is not None:
28				self._doc.close()
29
30The guts of the API are exposed to plugins through the `geany` package and
31its modules.
32
33Plugins should be placed in either the system plugin directory (something like
34/usr/local/lib/geany) or in the user plugin directory (something like
35~/.config/geany/plugins).  Only files with a `.py` extension will be loaded.
36"""
37
38
39from geany.logger import PluginLogger
40import keybindings
41
42class Plugin(object):
43	"""
44	Base class for all plugins.  All plugins must inherit from this in order
45	to be properly detected.
46	"""
47
48	# Child classes should implement these (at least __plugin__name__)
49	#__plugin_name__ = None
50	#__plugin_description__ = None
51	#__plugin_version__ = None
52	#__plugin_author__ = None
53
54	_events = {
55		"document-open": [],
56		# TODO: add more events here
57	}
58
59
60	def __init__(self):
61		"""
62		When the plugin is loaded its __init__() function will be called
63		so that's a good place to put plugin initialization code.
64		"""
65		self.logger = PluginLogger(self.name)
66
67
68	def cleanup(self):
69		"""
70		When the plugin is unloaded the cleanup() function will be called, so
71		it's a good place to put and clean-up/tear-down code.
72		"""
73		pass
74
75
76	@property
77	def __plugin_name__(self):
78		"""
79		Plugins must implement a __plugin_name__ attribute that returns the
80		string name of the plugin.
81		"""
82		raise NotImplementedError(
83			"Plugins must implement the __plugin_name__ attribute.")
84
85
86	@property
87	def name(self):
88		"""
89		Get plugin's name.
90		"""
91		return self.__plugin_name__
92
93
94	@property
95	def description(self):
96		"""
97		Get plugin's description.
98		"""
99		if hasattr(self, '__plugin_description__'):
100			return self.__plugin_description__
101		else:
102			return ""
103
104
105	@property
106	def version(self):
107		"""
108		Get plugin's version.
109		"""
110		if hasattr(self, '__plugin_version__'):
111			return self.__plugin_version__
112		else:
113			return ""
114
115
116	@property
117	def author(self):
118		"""
119		Get plugin's author.
120		"""
121		if hasattr(self, '__plugin_author__'):
122			return self.__plugin_author__
123		else:
124			return ""
125
126	def set_key_group(self, section_name, count, callback = None):
127		"""
128		Sets up a GeanyKeyGroup for this plugin. You can use that group to add keybindings
129		with group.add_key_item().
130		"""
131		return keybindings.set_key_group(self, section_name, count, callback)
132