gimp/tools/pdbgen
Michael Natterer fb1660a4ea rename gimp_image_floating_sel() to gimp_image_get_floating_selection().
2008-11-14  Michael Natterer  <mitch@gimp.org>

	* app/core/gimpimage.[ch]: rename gimp_image_floating_sel() to
	gimp_image_get_floating_selection().

	* app/actions/channels-actions.c
	* app/actions/image-actions.c
	* app/actions/layers-actions.c
	* app/actions/layers-commands.c
	* app/actions/select-actions.c
	* app/core/gimpdrawable.c
	* app/core/gimpimage-duplicate.c
	* app/core/gimpimage-merge.c
	* app/core/gimpimage-quick-mask.c
	* app/core/gimplayer-floating-sel.c
	* app/core/gimpselection.c
	* app/display/gimpdisplayshell-layer-select.c
	* app/display/gimpdisplayshell.c
	* app/tools/gimpeditselectiontool.c
	* app/tools/gimpfreeselecttool.c
	* app/tools/gimpmovetool.c
	* app/tools/gimprectangleselecttool.c
	* app/tools/gimpregionselecttool.c
	* app/tools/gimpselectiontool.c
	* app/tools/gimptexttool.c
	* app/widgets/gimpdrawabletreeview.c
	* app/widgets/gimplayertreeview.c
	* app/xcf/xcf-save.c
	* tools/pdbgen/pdb/image.pdb: changed accordingly, replaced some
	instances of direct acces by the accessor.

	* app/pdb/image-cmds.c: regenerated.


svn path=/trunk/; revision=27649
2008-11-14 15:01:44 +00:00
..
pdb rename gimp_image_floating_sel() to gimp_image_get_floating_selection(). 2008-11-14 15:01:44 +00:00
Makefile.am tools/pdbgen/Makefile.am new text layer PDB API created by Marcus Heese 2008-04-02 20:53:51 +00:00
README add the new args to gimp-paintbrush PDB calls. 1999-04-20 23:03:31 +00:00
app.pl Add GEGL_CFLAGS and #includes as if gimpdrawable.h and gimpimage.h had a 2008-10-09 20:24:04 +00:00
enumcode.pl In all files, changed the standard copyright notice to say "GIMP - The GNU 2006-12-09 21:33:38 +00:00
enumgen.pl In all files, changed the standard copyright notice to say "GIMP - The GNU 2006-12-09 21:33:38 +00:00
enums.pl added new enum GimpTextHintStyle. 2008-10-27 07:59:32 +00:00
groups.pl tools/pdbgen/Makefile.am new text layer PDB API created by Marcus Heese 2008-04-02 20:53:51 +00:00
lib.pl HACKING tools/pdbgen/lib.pl fixed spelling of "auto-generated". 2007-01-09 10:52:47 +00:00
pdb.pl reindent the list of PDB types and remove the unused and deprecated types 2008-10-15 14:10:08 +00:00
pdbgen.pl In all files, changed the standard copyright notice to say "GIMP - The GNU 2006-12-09 21:33:38 +00:00
stddefs.pdb AUTHORS authors.xml Fix my name back to single name in most important 2008-04-26 23:51:51 +00:00
util.pl In all files, changed the standard copyright notice to say "GIMP - The GNU 2006-12-09 21:33:38 +00:00

README

Some mostly unfinished docs are here.

-Yosh

PDBGEN
------------------

What is this?
It's a tool to automate much of the drudge work of making PDB interfaces
to GIMP internals. Right now, it generates PDB description records,
argument marshallers (with sanity checking) for the app side, as well
as libgimp wrappers for C plugins. It's written so that extending it
to provide support for CORBA and other languages suited to static
autogeneration.

How to invoke pdbgen from the command line:
Change into the ./tools/pdbgen directory
  $ ./pdbgen.pl DIRNAME
where DIRNAME is either "lib" or "app", depending on which set of
files you want to generate.  The files are written to ./app or ./lib
in the ./tools/pdbgen directory.  Up to you to diff the file you
changed and when you're happy copy it into the actual ./app/ or ./lib/
directory where it gets built.

Anatomy of a PDB descriptor:
PDB descriptors are Perl code. You define a subroutine, which corresponds
to the PDB function you want to create. You then fill certain special
variables to fully describe all the information pdbgen needs to generate
code. Since it's perl, you can do practically whatever perl lets you
do to help you do this. However, at the simplest level, you don't need
to know perl at all to make PDB descriptors.

Annotated description:
For example, we will look at gimp_display_new, specified in gdisplay.pdb.

sub display_new { 

We start with the name of our PDB function (not including the "gimp_" prefix).

    $blurb = 'Create a new display for the specified image.';

This directly corresponds to the "blurb" field in the ProcRecord.

    $help = <<'HELP';
Creates a new display for the specified image. If the image already has a
display, another is added. Multiple displays are handled transparently by the
GIMP. The newly created display is returned and can be subsequently destroyed
with a call to 'gimp-display-delete'. This procedure only makes sense for use
with the GIMP UI.
HELP

This is the help field. Notice because it is a long string, we used HERE
document syntax to split it over multiple lines. Any extra whitespace
in $blurb or $help, including newlines, is automatically stripped, so you
don't have to worry about that.

    &std_pdb_misc;

This is the "author", "copyright", and "date" fields. Since S&P are quite
common, they get a special shortcut which fills these in for you. Stuff
like this is defined in stddefs.pdb.

    @inargs = ( &std_image_arg );

You specify arguments in a list. Again, your basic image is very common,
so it gets a shortcut.

    @outargs = (
        { name => 'display', type => 'display',
          desc => 'The new display', alias => 'gdisp', init => 1 }
    );

This is a real argument. It has a name, type, description at a minumum.
"alias" lets you use the alias name in your invoker code, but the real
name is still shown in the ProcRecord. This is useful not only as a
shorthand, but for grabbing variables defined somewhere else (or constants),
in conjunction with the "no_declare" flag. "init" simply says initialize
this variable to a dummy value (in this case to placate gcc warnings)

    %invoke = (
        headers => [ qw("gdisplay.h") ],

These are the headers needed for the functions you call.

        vars => [ 'guint scale = 0x101' ],

Extra variables can be put here for your invoker.

        code => <<'CODE'
{
  if (gimage->layers == NULL)
    success = FALSE;
  else
    success = ((gdisp = gdisplay_new (gimage, scale)) != NULL);
}
CODE

The actual invoker code. Since it's a multiline block, we put curly braces
in the beginning.