← Back to branch summary

~ubuntu-branches/ubuntu/wily/geany/wily-proposed

« back to all changes in this revision

Viewing changes to doc/plugins.dox

  • Committer: Package Import Robot
  • Author(s): Evgeni Golov
  • Date: 2011-11-17 12:59:57 UTC
  • mfrom: (1.1.16)
  • Revision ID: package-import@ubuntu.com-20111117125957-nv48s8qkd2clcmr1
Tags: 0.21-1
* Imported Upstream version 0.21
* Refresh filetypes patch against 0.21
* Fix Description (thanks lintian!)
* Standards-Version: 3.9.2
* dpatch → 3.0 (quilt)
* Switch to new dh-style debian/rules
* Add a patch to search for plugins in both, multiarch and
  non-multiarch folders
* Add misc:Pre-Depends to Pre-Depends for multiarch
* Generate geany:Provides with GEANY_ABI_VERSION and GEANY_API_VERSION
* Split arch independent parts into geany-common
* Set maintainer to pkg-geany
* Set Vcs-* headers for pkg-geany
* Drop README.source, we're using standard 3.0 quilt now

Show diffs side-by-side

added added

removed removed

Lines of Context:
doc/plugins.dox
1
1
/*
2
2
 *      plugins.dox - this file is part of Geany, a fast and lightweight IDE
3
3
 *
4
 
 *      Copyright 2008-2010 Enrico Tröger <enrico(dot)troeger(at)uvena(dot)de>
5
 
 *      Copyright 2008-2010 Nick Treleaven <nick(dot)treleaven(at)btinternet(dot)com>
6
 
 *      Copyright 2009-2010 Frank Lanitz <frank(at)frank(dot)uvena(dot)de>
 
4
 *      Copyright 2008-2011 Enrico Tröger <enrico(dot)troeger(at)uvena(dot)de>
 
5
 *      Copyright 2008-2011 Nick Treleaven <nick(dot)treleaven(at)btinternet(dot)com>
 
6
 *      Copyright 2009-2011 Frank Lanitz <frank(at)frank(dot)uvena(dot)de>
7
7
 *
8
8
 *      This program is free software; you can redistribute it and/or modify
9
9
 *      it under the terms of the GNU General Public License as published by
20
20
 *      Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston,
21
21
 *      MA 02110-1301, USA.
22
22
 *
23
 
 * $Id: plugins.dox 5065 2010-06-25 16:50:27Z ntrel $
 
23
 * $Id: plugins.dox 5891 2011-08-19 06:55:34Z frlan $
24
24
 *
25
25
 * This file contains additional plugin documentation like the signal system and a small howto.
26
26
 * It is best viewed when filetype is set to C or C++.
32
32
 * @mainpage Geany Plugin API Documentation
33
33
 *
34
34
 * @author Enrico Tröger, Nick Treleaven, Frank Lanitz
35
 
 * $Date: 2010-06-25 17:50:27 +0100 (Fri, 25 Jun 2010) $
 
35
 * $Date: 2011-08-19 08:55:34 +0200 (ven. 19 août 2011) $
36
36
 *
37
37
 * @section Intro
38
38
 * This is the Geany API documentation. It should be considered work in progress.
194
194
 *  @a plugindata.h contains the biggest part of the plugin API and provides some basic macros.
195
195
 *  @a geanyfunctions.h provides some macros for convenient access to plugin API functions.
196
196
 *
197
 
 *  The you should define three basic variables which will give access to data fields and
 
197
 *  Then you should define three basic variables which will give access to data fields and
198
198
 *  functions provided by the plugin API.
199
199
 *  @code
200
200
GeanyPlugin                     *geany_plugin;
215
215
 *  For the next step, you will need to tell Geany some basic information about your plugin
216
216
 *  which will be shown in the plugin manager dialog.
217
217
 *
218
 
 *  For doing this, you should use PLUGIN_SET_INFO() which expects 4 values:
 
218
 *  To do this you should use the PLUGIN_SET_INFO() macro, which expects 4 parameters:
219
219
 *  - Plugin name
220
220
 *  - Short description
221
221
 *  - Version
231
231
 *  plugin is loaded. Part of that function could be adding and removing of an item to
232
232
 *  Geany's Tools menu, setting up keybindings or registering some callbacks. Also you will
233
233
 *  need to implement the function that is called when your plugin is unloaded.
234
 
 *  These functions are called plugin_init() and plugin_cleanup(). Let's see how it could look like:
 
234
 *  These functions are called plugin_init() and plugin_cleanup(). Let's see what this
 
235
 *  looks like:
235
236
 *  @code
236
 
PLUGIN_VERSION_CHECK(147)
 
237
PLUGIN_VERSION_CHECK(211)
237
238
 
238
239
PLUGIN_SET_INFO("HelloWorld", "Just another tool to say hello world",
239
240
                                "1.0", "Joe Doe <joe.doe@example.org>");
348
349
GeanyData               *geany_data;
349
350
GeanyFunctions  *geany_functions;
350
351
 
351
 
PLUGIN_VERSION_CHECK(147)
 
352
PLUGIN_VERSION_CHECK(211)
352
353
 
353
354
PLUGIN_SET_INFO("HelloWorld", "Just another tool to say hello world",
354
355
                                "1.0", "John Doe <john.doe@example.org>");
380
381
 *
381
382
 * Now you might like to look at Geany's source code for core plugins such as
382
383
 * @a plugins/demoplugin.c.
 
384
 *
 
385
 * @section furtherimprovements Furter Improvements and next steps
 
386
 * @subsection translatable_plugin_information Translatable plugin information
 
387
 *
 
388
 * After having written our first plugin, there is still room for improvement.
 
389
 *
 
390
 * By default, PLUGIN_SET_INFO() does not allow translation of the basic plugin
 
391
 * information for plugins which are not shipped with Geany's core distribution.
 
392
 * Since most plugins are not shipped with Geany's core, it makes sense to
 
393
 * enable translation when the plugin is loaded so that it gets translated
 
394
 * inside Geany's Plugin Manager.  As of Geany 0.19, the plugin API contains
 
395
 * the PLUGIN_SET_TRANSLATABLE_INFO() macro which enables translation of the
 
396
 * basic plugin details passed to PLUGIN_SET_INFO() when the plugin is loaded.
 
397
 *
 
398
 * PLUGIN_SET_TRANSLATABLE_INFO() takes two more parameters than PLUGIN_SET_INFO(),
 
399
 * for a total of six parameters.
 
400
 *
 
401
 *  - Localedir
 
402
 *  - Gettextpackage
 
403
 *  - Plugin name
 
404
 *  - Short description
 
405
 *  - Version
 
406
 *  - Author
 
407
 *
 
408
 * The @a Localdir and the @a Gettextpackage parameters are usually set inside
 
409
 * the build system.  If this has been done, the call for example HelloWorld
 
410
 * plugin could look like:
 
411
 *
 
412
 * @code
 
413
PLUGIN_SET_TRANSLATABLE_INFO(
 
414
        LOCALEDIR, GETTEXT_PACKAGE, _("Hello World"),
 
415
        _("Just another tool to say hello world"),
 
416
        "1.0", "John Doe <john.doe@example.org>");
 
417
 * @endcode
 
418
 *
 
419
 * When using this macro, you should use the gettext macro @a _() to mark
 
420
 * the strings like name and the short description as translatable as well. You
 
421
 * can see how this is done in the above example.
 
422
 *
 
423
 * As you can see the author's information is not marked as translatable in
 
424
 * this example.  The community has agreed that the best practice here is to
 
425
 * use, if possible, the latin version of the author's name followed by the
 
426
 * native spelling inside parenthesis, where applicable.
 
427
 *
 
428
 * @subsection plugin_i18n Using i18n/l10n inside Plugin
 
429
 *
 
430
 
 
431
 * You can (and should) also mark other strings beside the plugin's meta
 
432
 * information as translatable.  Strings used in menu entries, information
 
433
 * boxes or configuration dialogs should also be translatable as well.  Geany
 
434
 * offers a way to enable this in the plugin's code using the main_locale_init()
 
435
 * function provided by the plugin API. This function takes the same two
 
436
 * parameters discussed in the previous section; @a GETTEXT_PACKAGE and
 
437
 * @a LOCALEDIR.
 
438
 *
 
439
 * The main_locale_init() function is best called during initialization in the
 
440
 * plugin's plugin_init() function.  Adding this to the HelloWorld example could
 
441
 * look like:
 
442
 * @code
 
443
void plugin_init(GeanyData *data)
 
444
{
 
445
        main_locale_init(LOCALEDIR, GETTEXT_PACKAGE);
 
446
        main_menu_item = gtk_menu_item_new_with_mnemonic("Hello World");
 
447
        gtk_widget_show(main_menu_item);
 
448
        gtk_container_add(GTK_CONTAINER(geany->main_widgets->tools_menu),
 
449
                main_menu_item);
 
450
        g_signal_connect(main_menu_item, "activate",
 
451
                G_CALLBACK(item_activate_cb), NULL);
 
452
}
 
453
 * @endcode
 
454
 *
 
455
 * @note If you've previously called the PLUGIN_SET_TRANSLATABLE_INFO() you do not
 
456
 * need to call main_locale_init() yourself, as this has been already been
 
457
 * done for you.
383
458
 **/