1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
|
This is going to be a mini-howto on writing plugins for go and gedit.
A plugin in this case is written almost exactly like any other
program. You just have to call client_init at the beginning and you
have a few functions extra. You also can't be called except as a
plugin. This will change in the future.
The first thing you have to do to write a plugin is include
"client.h". It's called client.h because this is a client of the
plugin API. gE_plugin_api.[ch] and go_plugin_api.[ch] are the
interface between plugins and the actual program. Sorry about the
confusion.
The rest of this document will be a list of functions and their
descriptions. It should be pretty clear what's going on.
int client_init( int *argc, char **argv[], client_info *info_struct);
This function initializes the plugin interface. It reads some of the
arguments (discarding them in the process). It does some initial
communication with the editor. It's meant to be called as
context = client_init( &argc, &argv, &info );
The info variable is meant to have been set up to specify some
information about the plugin. The type client_info is a typedefed
structure. An empty copy of client_info is stored in a global
variable empty_info. This is used to initialize your structure
thusly: client_info info = empty_info; The main reason for this
global variable is so that as fields get added to info, your copy of
it has the default values for those new fields.
The currently defined fields of the client_info structure are
menu_location and suggested_accelerator. These are discussed later.
The format of menu_location is going to have a few different
possibilities. The only menu_location that's supported right now is
"[Plugins]Menu label". "[Plugins]" must be exactly the same and Menu
label is how you want the menu item for your plugin to read. You can
also pass in "" and your plugin won't appear on any menus.
The format of suggested_accelerator may have different versions as
well. The format is currently exactly the same as the old
menu_factory format for accelerators. Some examples are "<control>P"
and "<alt>`" (Both from current plugins actually.) The accelerator is
ignored by gedit, but used by go.
These values are used only if your plugin is called in query mode. In
query mode client_init doesn't return.
The return value of client_init is a context identifier. Some later
functions require that you pass them the context identifier. If they
accept a paramerter gint context, you should pass them your context
identifier. Currently, you can only operate in one context, that is,
the one given to you by client_init. This may change in the future.
Finally, if the return value of client_init is 0, you're being called
from the command line by the --launch-plugin argument to the editor.
There are some functions that you can't call, but it's currently
dependant on which editor you're being called from.
gint client_document_current( gint context );
Each view of a document is identified by an int called docid. This
function returns the docid of the current document.
This function isn't valid if context == 0.
gchar *client_document_filename( gint docid );
This function returns the filename of the given document. It returns
memory allocated with g_malloc. You're responsible for freeing the
memory.
gint client_document_new( gint context, gchar *title );
This function creates a new document with the given title.
This function isn't valid under gedit if context == 0.
gint client_document_open( gint context, gchar *title );
This function opens the document with the given title.
This function isn't valid under gedit if context == 0.
void client_document_show( gint docid );
This function shows the document. This doesn't actually do anything
yet. Documents are shown when new or open is called. However, the
API requires that you call this function, or your document may not be displayed.
void client_text_append( gint docid, gchar *buff, gint length );
This functions appends the given text to the given document.
gchar *client_text_get( gint docid );
This function returns the full text of the given document. It returns
memory allocated with g_malloc. You're responsible for freeing the
memory.
gboolean client_program_quit();
This function causes the editor to quit. It returns a boolean that
tells you whether the editor actually quit. TRUE signifies that the
program actually quit. FALSE signifies that the program didn't quit.
This may happen because there were unsaved documents.
void client_finish( gint context );
This function tells the editor that your plugin is finished. You are
required to call this function, and after you have, none of the other
functions are valid. You cannot call client_init again after calling
client_finish.
// Gnome Additions
As the plugins now use the features of Gnome, it means they can also
access the Config settings of Gnome.
The standard prefix for plugins is /Editor_Plugins/<Plugin Name>/
If all the Plugins use this, we'll be able to keep everything neat and
tidy. (This feature, in a pratical use, can been seen in the Browse plugin)
The final thing that you have to do is to link with client.c (or
libclient.a in gedit) and put yourself in PLUGINDIR. Then you should
be done.
(If its a new plugin, please add it to the 'README.plugins' file in
the top gEdit directory, this way, people can see what plugins are
included with the package, and what they do)
Please submit any suggestions for new API functions to
clahey@umich.edu. I hope this document is helpful.
|
