The OpenNET Project / Index page

[ новости /+++ | форум | теги | ]

Интерактивная система просмотра системных руководств (man-ов)

 ТемаНаборКатегория 
 
 [Cписок руководств | Печать]

Gimp (3)
  • >> Gimp (3) ( Solaris man: Библиотечные вызовы )
  • 
    
    

    NAME

         Gimp - Perl extension for writing Gimp Extensions/Plug-
         ins/Load & Save-Handlers
    
         This is mostly a reference manual. For a quick intro, look
         at the Gimp::Fu manpage. For more information, including
         tutorials, look at the Gimp-Perl pages at
         http://gimp.pages.de.
    
    
    

    RATIONALE

         Well, scheme (which is used by script-fu), is IMnsHO the
         crappiest language ever (well, the crappiest language that
         one actually can use, so it's not _that_ bad). Scheme has
         the worst of all languages, no data types, but still using
         variables. Look at haskell (http://www.haskell.org) to see
         how functional is done right.
    
         Since I was unable to write a haskell interface (and perl is
         the traditional scripting language), I wrote a Perl
         interface instead. Not too bad a decision I believe...
    
    
    

    SYNOPSIS

           use Gimp;
    
           Other modules of interest:
    
           use Gimp::Fu;         # easy scripting environment
           use Gimp::PDL;        # interface to the Perl Data Language
    
           these have their own manpage.
    
    
         IMPORT TAGS
    
         If you don't specify any import tags, Gimp assumes
         `qw/:consts main xlfd_size/' which is usually what you want.
    
         :auto
             Import useful constants, like RGB, RUN_NONINTERACTIVE...
             as well as all libgimp and pdb functions automagically
             into the caller's namespace. BEWARE!  This will
             overwrite your AUTOLOAD function, if you have one!
    
         :param
             Import PARAM_* constants (PDB_INT32, PDB_STRING etc.)
             only.
    
         :consts
             All constants from gimpenums.h (BG_IMAGE_FILL,
             RUN_NONINTERACTIVE, NORMAL_MODE, PDB_INT32 etc.).
    
    
         spawn_options=options
             Set default spawn options to options, see the Gimp::Net
             manpage.
    
         :DEFAULT
             The default set (see below).
    
         The default (unless '' is specified) is `'main',
         'xlfd_size', ':consts', '__''.  (`'__'' is used for i18n
         purposes).
    
    
    

    GETTING STARTED

         You should first read the Gimp::Fu manpage and then come
         back. This manpage is mainly intended for reference
         purposes.
    
         Also, Dov Grobgeld has written an excellent tutorial for
         Gimp-Perl. You can find it at
         http://imagic.weizmann.ac.il/~dov/gimp/perl-tut.html
    
    
    

    DESCRIPTION

         I think you already know what this is about: writing Gimp
         plug-ins/extensions/scripts/file-handlers/standalone-
         scripts, just about everything you can imagine in perl. If
         you are missing functionality (look into TODO first), please
         feel free contact the author...
    
         Some hilights:
    
    (i.e. to be started from within The Gimp) look almost the same
    (if you use the Gimp::Fu interface, there will be no visible
    differences at all), you can easily create hybrid (networked &
    libgimp) scripts as well.
         o Networked plug-ins and plug-
           ins using the libgimp interfaces
    
    oriented syntax, i.e. "gimp_image_new(600,300,RGB)" is the same
    as "new Image(600,300,RGB)"
         o Use either a plain pdb (scheme-
           like) interface or nice object-
    
    an existing gimp process.
         o Gimp::Fu will start The Gimp for you, if it cannot connect to
    
    versions using piddles (see the Gimp::PDL manpage)
         o You can optionally overwrite the pixel-data functions by
    
         noteworthy limitations (subject to be changed):
    
         o callback procedures do not poass return values to The Gimp.
    
    
    
    

    OUTLINE OF A GIMP PLUG-IN

         All plug-ins (and extensions etc.) _must_ contain a call to
         `Gimp::main'.  The return code should be immediately handed
         out to exit:
    
          exit main;             # Gimp::main is exported by default.
    
         Before the call to `Gimp::main', no other PDB function must
         be called.
    
         In a `Gimp::Fu'-script, you should call `Gimp::Fu::main'
         instead:
    
          exit main;             # Gimp::Fu::main is exported by default as well.
    
         This is similar to Gtk, Tk or similar modules, where you
         have to call the main eventloop. Attention: although you
         call `exit' with the result of `main', the main function
         might not actually return. This depends on both the version
         of Gimp and the version of the Gimp-Perl module that is in
         use.  Do not depend on `main' to return at all, but still
         call `exit' immediately.
    
         If you need to do cleanups before exiting you should use the
         `quit' callback (which is not yet available if you use
         Gimp::Fu).
    
    
    

    CALLBACKS

         THIS SECTION IS OUTDATED AND WILL BE REWORKED SOON. USE
         Gimp::Fu or READ THE SOURCE :(
    
         If you use the plain Gimp module (as opposed to Gimp::Fu),
         your program should only call one function: `main'.
         Everything else is going to be called from The Gimp at a
         later stage. For this to work, you should define certain
         call-backs in the same module you called `Gimp::main':
    
         init (), query (), quit ()
             the standard libgimp callback functions. `run'() is
             missing, because this module will directly call the
             function you registered with `gimp_install_procedure'.
             Some only make sense for extensions, some only for
             normal plug-ins.
    
         <installed_procedure>()
             The callback for a registered function
             (`gimp_install_procedure' and friends). The arguments
             from The Gimp are passed as normal arguments (with the
             exception of arrays being passed without a preceding
             count).
    
             The return values from <installed_procedure>() are
             checked against the specification, with the exception
             that a single `undef' is treated like no arguments. you
             can return less, but not more results than specified.
    
             If you `die' within the callback, the error will be
             reported to The Gimp (as soon as The Gimp implements
             such a functionality) as an execution error.
    
         net ()
             this is called when the plug-in is not started directly
             from within the Gimp, but instead from the Net-Server
             (the perl network server extension you hopefully have
             installed and started ;)
    
    
    

    CALLING GIMP FUNCTIONS

         There are two different flavours of gimp-functions.
         Functions from the PDB (the Procedural DataBase), and
         functions from libgimp (the C-language interface library).
    
         You can get a listing and description of every PDB function
         by starting the DB Browser extension in the Gimp-Xtns menu
         (but remember that DB Browser is buggy and displays "_"
         (underscores) as "-" (dashes), so you can't see the
         difference between gimp_quit and gimp-quit. As a rule of
         thumb, Script-Fu in gimp versions before 1.2 registers
         scripts with dashes, and everything else uses underscores).
    
         libgimp functions can't be traced (and won't be traceable in
         the foreseeable future).
    
         To call pdb functions (or equivalent libgimp functions),
         just treat them like normal perl (this requires the use of
         the `:auto' import tag, but see below for another
         possibility!):
    
          gimp_palette_set_foreground([20,5,7]);
          gimp_palette_set_background("cornsilk");
    
         If you don't use the `:auto' import tag, you can call all
         Gimp functions using OO-Syntax:
    
          Gimp->gimp_palette_set_foreground([20,5,7]);
          Gimp->palette_set_background("cornsilk");
          Palette->set_foreground('#1230f0');
    
         As you can see, you can also drop part of the name prefixes
         with this syntax, so its actually shorter to write.
    
         "But how do I call functions containing dashes?". Well, get
         your favourite perl book and learn perl! Anyway, newer perls
         understand a nice syntax (see also the description for
         `gimp_call_procedure'):
          "Gimp::plug-in-the-egg"->(RUN_INTERACTIVE,$image,$drawable);
    
         You can drop the `Gimp::' when using the `:auto'-import-tag.
         Very (very!) old perls may need:
    
          &{"Gimp::plug-in-the-egg"}("Gimp",RUN_INTERACTIVE,$image,$drawable);
    
         (unfortunately. the plug-in in this example is actually
         called "plug_in_the_egg" *sigh*)
    
    
    

    SPECIAL FUNCTIONS

         In this section, you can find descriptions of special
         functions, functions having different calling
         conventions/semantics than I would expect (I cannot speak
         for you), or just plain interesting functions. All of these
         functions must either be imported explicitly or called using
         a namespace override (`Gimp::'), not as Methods (`Gimp->').
    
         main(), Gimp::main()
             Should be called immediately when perl is initialized.
             Arguments are not yet supported. Initializations can
             later be done in the init function.
    
         xlfd_size(fontname)
             This auxillary functions parses the XLFD (usually
             obtained from a `PF_FONT' parameter) and returns its
             size and unit (e.g. `(20,POINTS)'). This can
             conviniently used in the gimp_text_..._fontname
             functions, which ignore the size (no joke ;). Example:
    
              $drawable->text_fontname (50, 50, "The quick", 5, 1, xlfd_size $font, $font;
    
    
         Gimp::gtk_init()
             Initialize Gtk in a similar way the Gimp itself did it.
             This automatically parses gimp's gtkrc and sets a
             variety of default settings (visual, colormap, gamma,
             shared memory...).
    
         Gimp::gtk_init_add { init statements ... };
             Add a callback function that should be called when gtk
             is being initialized (i.e. when Gimp::gtk_init is
             called, which should therefore be done even in Gnome
             applications).
    
             This is different to Gtk->init_add, which only gets
             called in Gtk->main, which is too late for registering
             types.
    
         Gimp::init([connection-argument]), Gimp::end()
             These is an alternative interface that replaces the call
             to Gimp::main and the net callback. At the moment it
             only works for the Net interface (the Gimp::Net
             manpage), and not as a native plug-in. Here's an
             example:
    
              use Gimp;
    
              Gimp::init;
              <do something with the gimp>
    
             The optional argument to init has the same format as the
             GIMP_HOST variable described in the Gimp::Net manpage.
             Calling `Gimp::end' is optional.
    
         Gimp::lock(), Gimp::unlock()
             These functions can be used to gain exclusive access to
             the Gimp. After calling lock, all accesses by other
             clients will be blocked and executed after the call to
             unlock. Calls to lock and unlock can be nested.
    
             Currently, these functions only lock the current Perl-
             Server instance against exclusive access, they are nops
             when used via the Gimp::Lib interface.
    
         Gimp::set_rgb_db(filespec)
             Use the given rgb database instead of the default one.
             The format is the same as the one used by the X11
             Consortiums rgb database (you might have a copy in
             /usr/lib/X11/rgb.txt). You can view the default database
             with `perldoc -m Gimp', at the end of the file (the
             default database is similar, but not identical to the
             X11 default rgb.txt)
    
         Gimp::initialized()
             this function returns true whenever it is safe to clal
             gimp functions. This is usually only the case after
             gimp_main or gimp_init have been called.
    
         Gimp::register_callback(gimp_function_name,perl_function)
             Using this fucntion you can overwrite the standard Gimp
             behaviour of calling a perl subroutine of the same name
             as the gimp function.
    
             The first argument is the name of a registered gimp
             function that you want to overwrite
             ('perl_fu_make_something'), and the second argument can
             be either a name of the corresponding perl sub
             ('Elsewhere::make_something') or a code reference
             (\&my_make).
    
    
    

    SPECIAL METHODS

         This chapter descibes methods that behave differently than
         you might expect, or methods uniquely implemented in perl
         (that is, not in the PDB). All of these must be invoked
         using the method syntax (`Gimp->' or `$object->').
    
    date, menu_path, image_types, type, [params], [return_vals])
         gimp_install_procedure(name, blurb, help, author, copyright,
             Mostly same as gimp_install_procedure. The parameters
             and return values for the functions are specified as an
             array ref containing either integers or array-refs with
             three elements, [PARAM_TYPE, \"NAME\", \"DESCRIPTION\"].
    
         gimp_progress_init(message,[])
             Initializes a progress bar. In networked modules this is
             a no-op.
    
         gimp_progress_update(percentage)
             Updates the progress bar. No-op in networked modules.
    
         gimp_tile_*, gimp_pixel_rgn_*, gimp_drawable_get
             With these functions you can access the raw pixel data
             of drawables. They are documented in the Gimp::Pixel
             manpage, to keep this manual page short.
    
         gimp_call_procedure(procname, arguments...)
             This function is actually used to implement the fancy
             stuff. Its your basic interface to the PDB. Every
             function call is eventually done through his function,
             i.e.:
    
              gimp_image_new(args...);
    
             is replaced by
    
              gimp_call_procedure "gimp_image_new",args...;
    
             at runtime.
    
         gimp_list_images, gimp_image_get_layers, gimp_image_get_channels
             These functions return what you would expect: an array
             of images, layers or channels. The reason why this is
             documented is that the usual way to return
             `PDB_INT32ARRAY''s would be to return a reference to an
             array of integers, rather than blessed objects.
    
         gimp_drawable_bounds drawable/gdrawable
             Returns an array (x,y,w,h) containing the upper left
             corner and the size of currently selected parts of the
             drawable, just as needed by PixelRgn->new and similar
             functions.
    
         server_eval(string)
             This evaluates the given string in array context and
             returns the results. It's similar to `eval', but with
             two important differences: the evaluating always takes
             place on the server side/server machine (which might be
             the same as the local one) and compilation/runtime
             errors are reported as runtime errors (i.e. throwing an
             exception).
    
    
    

    OBJECT ORIENTED SYNTAX

         In this manual, only the plain syntax (that lesser languages
         like C use) is described. Actually, the recommended way to
         write gimp scripts is to use the fancy OO-like syntax you
         are used to in perl (version 5 at least ;). As a fact, OO-
         syntax saves soooo much typing as well. See the Gimp::OO
         manpage for details.
    
    
    

    DEBUGGING AIDS

         No, I can't tell you how to cure immune deficiencies (which
         might well be uncurable, as AIDS virii might be able to
         survive in brain cells, among other unreachable (for
         medication) parts of your body), but I can tell you how Gimp
         can help you debugging your scripts:
    
         Gimp::set_trace (tracemask)
             Tracking down bugs in gimp scripts is difficult: no
             sensible error messages.  If anything goes wrong, you
             only get an execution failure. Switch on tracing to see
             which parameters are used to call pdb functions.
    
             This function is never exported, so you have to qualify
             it when calling.
    
             tracemask is any number of the following flags or'ed
             together.
    
             TRACE_NONE
                     nothing is printed.
    
             TRACE_CALL
                     all pdb calls (and only pdb calls!) are printed
                     with arguments and return values.
    
             TRACE_TYPE
                     the parameter types are printed additionally.
    
             TRACE_NAME
                     the parameter names are printed.
    
             TRACE_DESC
                     the parameter descriptions.
    
             TRACE_ALL
                     all of the above.
    
             `set_trace' returns the old tracemask.
    
         Gimp::set_trace(\$tracevar)
             write trace into $tracevar instead of printing it to
             STDERR. $tracevar only contains the last command traces,
             i.e. it's cleared on every PDB invocation invocation.
    
         Gimp::set_trace(*FILEHANDLE)
             write trace to FILEHANDLE instead of STDERR.
    
    
    

    SUPPORTED GIMP DATA TYPES

         Gimp supports different data types like colors, regions,
         strings. In perl, these are represented as:
    
         INT32, INT16, INT8, FLOAT, STRING
             normal perl scalars. Anything except STRING will be
             mapped to a perl-double.
    
         INT32ARRAY, INT16ARRAY, INT8ARRAY, FLOATARRAY, STRINGARRAY
             array refs containing scalars of the same type, i.e. [1,
             2, 3, 4]. Gimp implicitly swallows or generates a
             preceeding integer argument because the preceding
             argument usually (this is a de-facto standard) contains
             the number of elements.
    
         COLOR
             on input, either an array ref with 3 elements (i.e.
             [233,40,40]), a X11-like string ("#rrggbb") or a colour
             name ("papayawhip") (see set_rgb_db).
    
         DISPLAY, IMAGE, LAYER, CHANNEL, DRAWABLE, SELECTION
             these will be mapped to corresponding objects (IMAGE =>
             Gimp::Image). In trace output you will see small
             integers (the image/layer/etc..-ID)
    
         PARASITE
             represented as an array ref [name, flags, data], where
             name and data should be perl strings and flags is the
             numerical flag value.
    
         REGION, BOUNDARY, PATH, STATUS
             Not yet supported (and might never be).
    
    
    

    AUTHOR

         Marc Lehmann <[email protected]>
    
    
    

    SEE ALSO

         perl(1), gimp(1), the Gimp::OO manpage, the Gimp::Data
         manpage, the Gimp::Pixel manpage, the Gimp::PDL manpage, the
         Gimp::Util manpage, the Gimp::UI manpage, the Gimp::Feature
         manpage, the Gimp::Net manpage, the Gimp::Compat manpage,
         the Gimp::Config manpage, the Gimp::Lib manpage, the
         Gimp::Module manpage, the scm2perl manpage and the scm2scm
         manpage.
    
    
    
    


    Поиск по тексту MAN-ов: 




    Партнёры:
    PostgresPro
    Inferno Solutions
    Hosting by Hoster.ru
    Хостинг:

    Закладки на сайте
    Проследить за страницей
    Created 1996-2024 by Maxim Chirkov
    Добавить, Поддержать, Вебмастеру