home *** CD-ROM | disk | FTP | other *** search
/ Mac Easy 2010 May / Mac Life Ubuntu.iso / casper / filesystem.squashfs / usr / share / gimp / 2.0 / help / en / gimp-using-script-fu-tutorial-script.html < prev    next >
Encoding:
Extensible Markup Language  |  2008-05-03  |  13.5 KB  |  328 lines
  1. <?xml version="1.0" encoding="UTF-8" standalone="no"?>
  2. <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
  3. <html xmlns="http://www.w3.org/1999/xhtml">
  4.   <head>
  5.     <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
  6.     <title>3.5.¬† Giving Our Script Some Guts</title>
  7.     <link rel="stylesheet" href="gimp-help-plain.css" type="text/css" />
  8.     <link rel="stylesheet" href="gimp-help-screen.css" type="text/css" />
  9.     <link rel="stylesheet" href="gimp-help-custom.css" type="text/css" />
  10.     <link rel="alternate stylesheet" href="gimp22.css" type="text/css" title="gimp22" />
  11.     <meta name="generator" content="DocBook XSL Stylesheets V1.73.2" />
  12.     <link rel="start" href="index.html" title="GNU Image Manipulation Program" />
  13.     <link rel="up" href="gimp-using-script-fu-tutorial.html" title="3.¬† A Script-Fu Tutorial" />
  14.     <link rel="prev" href="gimp-using-script-fu-tutorial-first-script.html" title="3.4.¬† Your First Script-Fu Script" />
  15.     <link rel="next" href="gimp-using-script-fu-tutorial-extending-text-box.html" title="3.6.¬† Extending The Text Box Script" />
  16.   </head>
  17.   <body>
  18.     <div class="navheader">
  19.       <table width="100%" summary="Navigation header">
  20.         <tr>
  21.           <th colspan="3" align="center">3.5.¬†
  22.       <span lang="en" xml:lang="en">Giving Our Script Some Guts</span>
  23.     </th>
  24.         </tr>
  25.         <tr>
  26.           <td width="20%" align="left"><a accesskey="p" href="gimp-using-script-fu-tutorial-first-script.html"><img src="../images/prev.png" alt="Prev" /></a>¬†</td>
  27.           <th width="60%" align="center">3.¬†
  28.     <span lang="en" xml:lang="en">A Script-Fu Tutorial</span>
  29.   </th>
  30.           <td width="20%" align="right">¬†<a accesskey="n" href="gimp-using-script-fu-tutorial-extending-text-box.html"><img src="../images/next.png" alt="Next" /></a></td>
  31.         </tr>
  32.       </table>
  33.       <hr />
  34.     </div>
  35.     <div class="sect2" lang="en" xml:lang="en">
  36.       <div class="titlepage">
  37.         <div>
  38.           <div>
  39.             <h3 class="title"><a id="gimp-using-script-fu-tutorial-script"></a>3.5.¬†
  40.       <span lang="en" xml:lang="en">Giving Our Script Some Guts</span>
  41.     </h3>
  42.           </div>
  43.         </div>
  44.       </div>
  45.       <p>
  46.       Let us continue with our training and add some functionality to our
  47.       script.
  48.     </p>
  49.       <div class="sect3" lang="en" xml:lang="en">
  50.         <div class="titlepage">
  51.           <div>
  52.             <div>
  53.               <h4 class="title"><a id="id2619449"></a>3.5.1.¬†
  54.         <span lang="en" xml:lang="en">Creating A New Image</span>
  55.       </h4>
  56.             </div>
  57.           </div>
  58.         </div>
  59.         <p>
  60.         In the previous lesson, we created an empty function and registered it
  61.         with GIMP. In this lesson, we want to provide functionality to our
  62.         script -- we want to create a new image, add the user's text to it and
  63.         resize the image to fit the text exactly.
  64.       </p>
  65.         <p>
  66.         Once you know how to set variables, define functions and access list
  67.         members, the rest is all downhill -- all you need to do is familiarize
  68.         yourself with the functions available in GIMP's procedural database
  69.         and call those functions directly. So fire up the DB Browser and let's
  70.         get cookin'!
  71.       </p>
  72.         <p>
  73.         Let's begin by making a new image. We'll create a new variable,
  74.         <code class="varname">theImage</code>, set to the result of calling GIMP's
  75.         built-in function <code class="code">gimp-image-new</code>.
  76.       </p>
  77.         <p>
  78.         As you can see from the DB Browser, the function
  79.         <code class="code">gimp-image-new</code> takes three parameters -- the
  80.         image's width, height and the type of image. Because we'll
  81.         later resize the image to fit the text, we'll make a 10x10 RGB
  82.         image. We'll store the image's width and sizes in some
  83.         variables, too, as we'll refer to and manipulate them later in
  84.         the script.
  85.       </p>
  86.         <pre class="programlisting">
  87.         (define (script-fu-text-box inText inFont inFontSize inTextColor)
  88.         (let*
  89.               (
  90.                  ; define our local variables
  91.                  ; create a new image:
  92.                  (theImageWidth  10)
  93.                  (theImageHeight 10)
  94.                  (theImage (car
  95.                                 (gimp-image-new
  96.                                  theImageWidth
  97.                                  theImageHeight
  98.                                  RGB
  99.                                 )
  100.                            )
  101.                  )
  102.                  (theText)     ;a declaration for the text
  103.                                ;we create later
  104.       </pre>
  105.         <p>
  106.         Note: We used the value RGB to specify that the image is an RGB image.
  107.         We could have also used 0, but RGB is more descriptive when we glance
  108.         at the code.
  109.       </p>
  110.         <p>
  111.         You should also notice that we took the head of the result of the
  112.         function call. This may seem strange, because the database explicitly
  113.         tells us that it returns only one value -- the ID of the newly created
  114.         image. However, all GIMP functions return a list, even if there is
  115.         only one element in the list, so we need to get the head of the list.
  116.       </p>
  117.       </div>
  118.       <div class="sect3" lang="en" xml:lang="en">
  119.         <div class="titlepage">
  120.           <div>
  121.             <div>
  122.               <h4 class="title"><a id="id2619561"></a>3.5.2.¬†
  123.         <span lang="en" xml:lang="en">Adding A New Layer To The Image</span>
  124.       </h4>
  125.             </div>
  126.           </div>
  127.         </div>
  128.         <p>
  129.         Now that we have an image, we need to add a layer to it. We'll
  130.         call the <code class="code">gimp-layer-new</code> function to create the
  131.         layer, passing
  132.         in the ID of the image we just created. (From now on, instead
  133.         of listing the complete function, we'll only list the lines
  134.         we're adding to it. You can see the complete script 
  135.         <a class="link" href="gimp-using-script-fu-tutorial-result.html" title="3.7.¬† Your script and its working">here</a>.)
  136.         Because we've declared all of the local variables we'll use,
  137.         we'll also close the parentheses marking the end of our
  138.         variable declarations:
  139.       </p>
  140.         <pre class="programlisting">
  141.         ;create a new layer for the image:
  142.            (theLayer
  143.                      (car
  144.                           (gimp-layer-new
  145.                            theImage
  146.                            theImageWidth
  147.                            theImageHeight
  148.                            RGB-IMAGE
  149.                            "layer 1"
  150.                            100
  151.                            NORMAL
  152.                           )
  153.                       )
  154.             )
  155.          ) ;end of our local variables
  156.       </pre>
  157.         <p>
  158.         Once we have the new layer, we need to add it to the image:
  159.       </p>
  160.         <pre class="programlisting">
  161.         (gimp-image-add-layer theImage theLayer 0)
  162.       </pre>
  163.         <p>
  164.         Now, just for fun, let's see the fruits of our labors up until this
  165.         point, and add this line to show the new, empty image:
  166.       </p>
  167.         <pre class="programlisting">
  168.         (gimp-display-new theImage)
  169.       </pre>
  170.         <p>
  171.         Save your work, select
  172.         <span class="guimenu">Xtns</span> ‚Üí <span class="guisubmenu">Script-Fu</span> ‚Üí <span class="guimenuitem">Refresh Scripts</span>,
  173.         run the script and a new image should pop up. It will probably
  174.         contain garbage (random colors), because we haven't erased
  175.         it. We'll get to that in a second.
  176.       </p>
  177.       </div>
  178.       <div class="sect3" lang="en" xml:lang="en">
  179.         <div class="titlepage">
  180.           <div>
  181.             <div>
  182.               <h4 class="title"><a id="id2619673"></a>3.5.3.¬†
  183.         <span lang="en" xml:lang="en">Adding The Text</span>
  184.       </h4>
  185.             </div>
  186.           </div>
  187.         </div>
  188.         <p>
  189.         Go ahead and remove the line to display the image (or comment
  190.         it out with a ; as the first character of the line).
  191.       </p>
  192.         <p>
  193.         Before we add text to the image, we need to set the background
  194.         and foreground colors so that the text appears in the color
  195.         the user specified. We'll use the
  196.         gimp-context-set-back/foreground functions:
  197.       </p>
  198.         <pre class="programlisting">
  199.         (gimp-context-set-background '(255 255 255) )
  200.         (gimp-context-set-foreground inTextColor)
  201.       </pre>
  202.         <p>
  203.         With the colors properly set, let's now clean out the garbage
  204.         currently in the image by filling the drawable with the background
  205.         color:
  206.       </p>
  207.         <pre class="programlisting">
  208.         (gimp-drawable-fill theLayer BACKGROUND-FILL)
  209.       </pre>
  210.         <p>
  211.         With the image cleared, we're ready to add some text:
  212.       </p>
  213.         <pre class="programlisting">
  214.         (set! theText
  215.                       (car
  216.                            (gimp-text-fontname
  217.                             theImage theLayer
  218.                             0 0
  219.                             inText
  220.                             0
  221.                             TRUE
  222.                             inFontSize PIXELS
  223.                             "Sans")
  224.                        )
  225.         )
  226.       </pre>
  227.         <p>
  228.         Although a long function call, it's fairly straightforward if
  229.         you go over the parameters while looking at the function's
  230.         entry in the DB Browser. Basically, we're creating a new text
  231.         layer and assigning it to the variable
  232.         <code class="varname">theText</code>.
  233.       </p>
  234.         <p>
  235.         Now that we have the text, we can grab its width and height and resize
  236.         the image and the image's layer to the text's size:
  237.       </p>
  238.         <pre class="programlisting">
  239.         (set! theImageWidth   (car (gimp-drawable-width  theText) ) )
  240.         (set! theImageHeight  (car (gimp-drawable-height theText) ) )
  241.         (gimp-image-resize theImage theImageWidth theImageHeight 0 0)
  242.         (gimp-layer-resize theLayer theImageWidth theImageHeight 0 0)
  243.       </pre>
  244.         <p>
  245.         If you're like me, you're probably wondering what a drawable is when
  246.         compared to a layer. The difference between the two is that a drawable
  247.         is anything that can be drawn into, including layers but also
  248.         channels, layer masks, the selection, etc; a layer is a more specific
  249.         version of a drawable. In most cases, the distinction is not
  250.         important.
  251.       </p>
  252.         <p>
  253.         With the image ready to go, we can now re-add our display line:
  254.       </p>
  255.         <pre class="programlisting">
  256.         (gimp-display-new theImage)
  257.       </pre>
  258.         <p>
  259.         Save your work, refresh the database and give your first script a run!
  260.       </p>
  261.       </div>
  262.       <div class="sect3" lang="en" xml:lang="en">
  263.         <div class="titlepage">
  264.           <div>
  265.             <div>
  266.               <h4 class="title"><a id="id2619807"></a>3.5.4.¬†
  267.         <span lang="en" xml:lang="en">Clearing The Dirty Flag</span>
  268.       </h4>
  269.             </div>
  270.           </div>
  271.         </div>
  272.         <p>
  273.         If you try to close the image created without first saving the file,
  274.         GIMP will ask you if you want to save your work before you close the
  275.         image. It asks this because the image is marked as dirty, or unsaved.
  276.         In the case of our script, this is a nuisance for the times when we
  277.         simply give it a test run and don't add or change anything in the
  278.         resulting image -- that is, our work is easily reproducible in such a
  279.         simple script, so it makes sense to get rid of this dirty flag.
  280.       </p>
  281.         <p>
  282.         To do this, we can clear the dirty flag after displaying the image:
  283.       </p>
  284.         <pre class="programlisting">
  285.         (gimp-image-clean-all theImage)
  286.       </pre>
  287.         <p>
  288.         This will set dirty count to 0, making it appear to be a "clean"
  289.         image.
  290.       </p>
  291.         <p>
  292.         Whether to add this line or not is a matter of personal taste. I use
  293.         it in scripts that produce new images, where the results are trivial,
  294.         as in this case. If your script is very complicated, or if it works on
  295.         an existing image, you will probably not want to use this function.
  296.       </p>
  297.       </div>
  298.     </div>
  299.     <div class="navfooter">
  300.       <hr />
  301.       <table width="100%" summary="Navigation footer">
  302.         <tr>
  303.           <td width="40%" align="left"><a accesskey="p" href="gimp-using-script-fu-tutorial-first-script.html"><img src="../images/prev.png" alt="Prev" /></a>¬†</td>
  304.           <td width="20%" align="center">
  305.             <a accesskey="u" href="gimp-using-script-fu-tutorial.html">
  306.               <img src="../images/up.png" alt="Up" />
  307.             </a>
  308.           </td>
  309.           <td width="40%" align="right">¬†<a accesskey="n" href="gimp-using-script-fu-tutorial-extending-text-box.html"><img src="../images/next.png" alt="Next" /></a></td>
  310.         </tr>
  311.         <tr>
  312.           <td width="40%" align="left" valign="top"><a accesskey="p" href="gimp-using-script-fu-tutorial-first-script.html">3.4.¬†
  313.       <span lang="en" xml:lang="en">Your First Script-Fu Script</span>
  314.     </a>¬†</td>
  315.           <td width="20%" align="center">
  316.             <a accesskey="h" href="index.html">
  317.               <img src="../images/home.png" alt="Home" />
  318.             </a>
  319.           </td>
  320.           <td width="40%" align="right" valign="top">¬†<a accesskey="n" href="gimp-using-script-fu-tutorial-extending-text-box.html">3.6.¬†
  321.       <span lang="en" xml:lang="en">Extending The Text Box Script</span>
  322.     </a></td>
  323.         </tr>
  324.       </table>
  325.     </div>
  326.   </body>
  327. </html>
  328.