Mac Easy 2010 May

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-first-script.html < prev next >

Wrap

Extensible Markup Language | 2008-05-03 | 30.0 KB | 809 lines

<?xml version="1.0" encoding="UTF-8" standalone="no"?> <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> <html xmlns="http://www.w3.org/1999/xhtml"> <head> <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /> <title>3.4.¬† Your First Script-Fu Script</title> <link rel="stylesheet" href="gimp-help-plain.css" type="text/css" /> <link rel="stylesheet" href="gimp-help-screen.css" type="text/css" /> <link rel="stylesheet" href="gimp-help-custom.css" type="text/css" /> <link rel="alternate stylesheet" href="gimp22.css" type="text/css" title="gimp22" /> <meta name="generator" content="DocBook XSL Stylesheets V1.73.2" /> <link rel="start" href="index.html" title="GNU Image Manipulation Program" /> <link rel="up" href="gimp-using-script-fu-tutorial.html" title="3.¬† A Script-Fu Tutorial" /> <link rel="prev" href="gimp-using-script-fu-tutorial-lists.html" title="3.3.¬† Lists, Lists And More Lists" /> <link rel="next" href="gimp-using-script-fu-tutorial-script.html" title="3.5.¬† Giving Our Script Some Guts" /> </head> <body> <div class="navheader"> <table width="100%" summary="Navigation header"> <tr> <th colspan="3" align="center">3.4.¬† <span lang="en" xml:lang="en">Your First Script-Fu Script</span> </th> </tr> <tr> <td width="20%" align="left"><a accesskey="p" href="gimp-using-script-fu-tutorial-lists.html"><img src="../images/prev.png" alt="Prev" /></a>¬†</td> <th width="60%" align="center">3.¬† <span lang="en" xml:lang="en">A Script-Fu Tutorial</span> </th> <td width="20%" align="right">¬†<a accesskey="n" href="gimp-using-script-fu-tutorial-script.html"><img src="../images/next.png" alt="Next" /></a></td> </tr> </table> <hr /> </div> <div class="sect2" lang="en" xml:lang="en"> <div class="titlepage"> <div> <div> <h3 class="title"><a id="gimp-using-script-fu-tutorial-first-script"></a>3.4.¬† <span lang="en" xml:lang="en">Your First Script-Fu Script</span> </h3> </div> </div> </div> <p> Do you not need to stop and catch your breath? No? Well then, let's proceed with your fourth lesson -- your first Script-Fu Script. </p> <div class="sect3" lang="en" xml:lang="en"> <div class="titlepage"> <div> <div> <h4 class="title"><a id="id2617958"></a>3.4.1.¬† <span lang="en" xml:lang="en">Creating A Text Box Script</span> </h4> </div> </div> </div> <p> One of the most common operations I perform in GIMP is creating a box with some text in it for a web page, a logo or whatever. However, you never quite know how big to make the initial image when you start out. You don't know how much space the text will fill with the font and font size you want. </p> <p> The Script-Fu Master (and student) will quickly realize that this problem can easily be solved and automated with Script-Fu. </p> <p> We will, therefore, create a script, called Text Box, which creates an image correctly sized to fit snugly around a line of text the user inputs. We'll also let the user choose the font, font size and text color. </p> </div> <div class="sect3" lang="en" xml:lang="en"> <div class="titlepage"> <div> <div> <h4 class="title"><a id="id2617999"></a>3.4.2.¬† <span lang="en" xml:lang="en">Editing And Storing Your Scripts</span> </h4> </div> </div> </div> <p> Up until now, we've been working in the Script-Fu Console. Now, however, we're going to switch to editing script text files. </p> <p> Where you place your scripts is a matter of preference -- if you have access to GIMP's default script directory, you can place your scripts there. However, I prefer keeping my personal scripts in my own script directory, to keep them separate from the factory-installed scripts. </p> <p> In the <code class="filename">.gimp-2.4</code> directory that GIMP made off of your home directory, you should find a directory called <code class="filename">scripts</code>. GIMP will automatically look in your <code class="filename">.gimp-2.4</code> directory for a scripts directory, and add the scripts in this directory to the Script-Fu database. You should place your personal scripts here. </p> </div> <div class="sect3" lang="en" xml:lang="en"> <div class="titlepage"> <div> <div> <h4 class="title"><a id="id2618058"></a>3.4.3.¬† <span lang="en" xml:lang="en">The Bare Essentials</span> </h4> </div> </div> </div> <p> Every Script-Fu script defines at least one function, which is the script's main function. This is where you do the work. </p> <p> Every script must also register with the procedural database, so you can access it within GIMP. </p> <p>We'll define the main function first:</p> <pre class="programlisting"> (define (script-fu-text-box inText inFont inFontSize inTextColor)) </pre> <p> Here, we've defined a new function called script-fu-text-box that takes four parameters, which will later correspond to some text, a font, the font size, and the text's color. The function is currently empty and thus does nothing. So far, so good -- nothing new, nothing fancy. </p> </div> <div class="sect3" lang="en" xml:lang="en"> <div class="titlepage"> <div> <div> <h4 class="title"><a id="id2618108"></a>3.4.4.¬† <span lang="en" xml:lang="en">Naming Conventions</span> </h4> </div> </div> </div> <p> Scheme's naming conventions seem to prefer lowercase letters with hyphens, which I've followed in the naming of the function. However, I've departed from the convention with the parameters. I like more descriptive names for my parameters and variables, and thus add the "in" prefix to the parameters so I can quickly see that they're values passed into the script, rather than created within it. I use the prefix "the" for variables defined within the script. </p> <p> It's GIMP convention to name your script functions script-fu-abc, because then when they're listed in the procedural database, they'll all show up under script-fu when you're listing the functions. This also helps distinguish them from plug-ins. </p> </div> <div class="sect3" lang="en" xml:lang="en"> <div class="titlepage"> <div> <div> <h4 class="title"><a id="id2618144"></a>3.4.5.¬† <span lang="en" xml:lang="en">Registering The Function</span> </h4> </div> </div> </div> <p> Now, let's register the function with GIMP. This is done by calling the function <code class="code">script-fu-register</code>. When GIMP reads in a script, it will execute this function, which registers the script with the procedural database. You can place this function call wherever you wish in your script, but I usually place it at the end, after all my other code. </p> <p> Here's the listing for registering this function (I will explain all its parameters in a minute): </p> <pre class="programlisting"> (script-fu-register "script-fu-text-box" ;func name "Text Box" ;menu label "Creates a simple text box, sized to fit\ around the user's choice of text,\ font, font size, and color." ;description "Michael Terry" ;author "copyright 1997, Michael Terry" ;copyright notice "October 27, 1997" ;date created "" ;image type that the script works on SF-STRING "Text:" "Text Box" ;a string variable SF-FONT "Font:" "Charter" ;a font variable SF-ADJUSTMENT "Font size" '(50 1 1000 1 10 0 1) ;a spin-button SF-COLOR "Color:" '(0 0 0) ;color variable ) (script-fu-menu-register "script-fu-text-box" "<Toolbox>/Xtns/Script-Fu/Text") </pre> <p> If you save these functions in a text file with a <code class="filename">.scm</code> suffix in your script directory, then choose <span class="guimenu">Xtns</span> ‚Üí <span class="guisubmenu">Script-Fu</span> ‚Üí <span class="guimenuitem">Refresh Scripts</span>, this new script will appear as <span class="guimenu"> Xtns</span> ‚Üí <span class="guisubmenu">Script-Fu</span> ‚Üí <span class="guisubmenu">Text</span> ‚Üí <span class="guimenuitem">Text Box</span>. </p> <p> If you invoke this new script, it won't do anything, of course, but you can view the prompts you created when registering the script (more information about what we did is covered next). </p> <p> Finally, if you invoke the Procedure Browser ( <span class="guimenu"> Xtns</span> ‚Üí <span class="guimenuitem">Procedure Browser</span>), you'll notice that our script now appears in the database. </p> </div> <div class="sect3" lang="en" xml:lang="en"> <div class="titlepage"> <div> <div> <h4 class="title"><a id="id2618319"></a>3.4.6.¬† <span lang="en" xml:lang="en">Steps For Registering The Script</span> </h4> </div> </div> </div> <p> To register our script with GIMP, we call the function script-fu-register, fill in the seven required parameters and add our script's own parameters, along with a description and default value for each parameter. </p> <div class="itemizedlist"> <p class="title"> <b> <span lang="en" xml:lang="en">The Required Parameters</span> </b> </p> <ul type="disc"> <li> <p> The <span class="emphasis"><em>name</em></span> of the function we defined. This is the function called when our script is invoked (the entry-point into our script). This is necessary because we may define additional functions within the same file, and GIMP needs to know which of these functions to call. In our example, we only defined one function, text-box, which we registered. </p> </li> <li> <p> The <span class="emphasis"><em>location</em></span> in the menu where the script will be inserted. The exact location of the script is specified like a path in Unix, with the root of the path being either toolbox or right-click. </p> <p> If your script does not operate on an existing image (and thus creates a new image, like our Text Box script will), you'll want to insert it in the toolbox menu -- this is the menu in GIMP's main window (where all the tools are located: the selection tools, magnifying glass, etc.). </p> <p> If your script is intended to work on an image being edited, you'll want to insert it in the menu that appears when you right-click on an open image. The rest of the path points to the menu lists, menus and sub-menus. Thus, we registered our Text Box script in the Text menu of the Script-Fu menu of the Xtns menu of the toolbox ( <span class="guimenu"> Xtns</span> ‚Üí <span class="guisubmenu">Script-Fu</span> ‚Üí <span class="guisubmenu">Text</span> ‚Üí <span class="guimenuitem">Text Box</span> ). </p> <p> If you notice, the Text sub-menu in the Script-Fu menu wasn't there when we began -- GIMP automatically creates any menus not already existing. </p> </li> <li> <p> A <span class="emphasis"><em>description</em></span> of your script, to be displayed in the Procedure Browser. </p> </li> <li> <p> <span class="emphasis"><em>Your name</em></span> (the author of the script). </p> </li> <li> <p> <span class="emphasis"><em>Copyright</em></span> information. </p> </li> <li> <p> The <span class="emphasis"><em>date</em></span> the script was made, or the last revision of the script. </p> </li> <li> <p> The <span class="emphasis"><em>types</em></span> of images the script works on. This may be any of the following: RGB, RGBA, GRAY, GRAYA, INDEXED, INDEXEDA. Or it may be none at all -- in our case, we're creating an image, and thus don't need to define the type of image on which we work. </p> </li> </ul> </div> <div class="figure"> <a id="id2618524"></a> <p class="title"> <b>Figure¬†12.4.¬† <span lang="en" xml:lang="en">The menu of our script.</span> </b> </p> <div class="figure-contents"> <div class="mediaobject"> <img src="../images/using/script-fu-menu.png" alt="The menu of our script." /> </div> </div> </div> <br class="figure-break" /> </div> <div class="sect3" lang="en" xml:lang="en"> <div class="titlepage"> <div> <div> <h4 class="title"><a id="id2618557"></a>3.4.7.¬† <span lang="en" xml:lang="en">Registering The Script's Parameters</span> </h4> </div> </div> </div> <p> Once we have listed the required parameters, we then need to list the parameters that correspond to the parameters our script needs. When we list these params, we give hints as to what their types are. This is for the dialog which pops up when the user selects our script. We also provide a default value. </p> <p> This section of the registration process has the following format: </p> <div class="informaltable"> <table border="1"> <colgroup> <col /> <col /> <col /> </colgroup> <thead> <tr> <th> <p>Param Type</p> </th> <th> <p>Description</p> </th> <th> <p>Example</p> </th> </tr> </thead> <tbody> <tr> <td> <p>SF-IMAGE</p> </td> <td> <p> If your script operates on an open image, this should be the first parameter after the required parameters. GIMP will pass in a reference to the image in this parameter. </p> </td> <td> <p>3</p> </td> </tr> <tr> <td> <p>SF-DRAWABLE</p> </td> <td> <p> If your script operates on an open image, this should be the second parameter after the SF-IMAGE param. It refers to the active layer. GIMP will pass in a reference to the active layer in this parameter. </p> </td> <td> <p>17</p> </td> </tr> <tr> <td> <p>SF-VALUE</p> </td> <td> <p> Accepts numbers and strings. Note that quotes must be escaped for default text, so better use SF-STRING. </p> </td> <td> <p>42</p> </td> </tr> <tr> <td> <p>SF-STRING</p> </td> <td> <p>Accepts strings.</p> </td> <td> <p>"Some text"</p> </td> </tr> <tr> <td> <p>SF-COLOR</p> </td> <td> <p> Indicates that a color is requested in this parameter. </p> </td> <td> <p>'(0 102 255)</p> </td> </tr> <tr> <td> <p>SF-TOGGLE</p> </td> <td> <p> A checkbox is displayed, to get a Boolean value. </p> </td> <td> <p>TRUE or FALSE</p> </td> </tr> </tbody> </table> </div> </div> <div class="sect3" lang="en" xml:lang="en"> <div class="titlepage"> <div> <div> <h4 class="title"><a id="gimp-using-script-fu-api"></a>3.4.8.¬† <span lang="en" xml:lang="en"> The Script-Fu parameter API<sup>[<a id="id2618815" href="#ftn.id2618815" class="footnote">3</a>]</sup> </span> </h4> </div> </div> </div> <div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"> <table border="0" summary="Note"> <tr> <td rowspan="2" align="center" valign="top" width="25"> <img alt="[Note]" src="../images/note.png" /> </td> <th align="left">Note</th> </tr> <tr> <td align="left" valign="top"> <p> Beside the above parameter types there are more types for the interactive mode, each of them will create a widget in the control dialog. You will find the description of these parameters and examples in the test script <code class="filename">plug-ins/script-fu/scripts/test-sphere.scm</code> shipped with the <acronym class="acronym">GIMP</acronym> source code. </p> </td> </tr> </table> </div> <div class="informaltable"> <table border="1"> <colgroup> <col /> <col /> </colgroup> <thead> <tr> <th> <p>Param Type</p> </th> <th> <p>Description</p> </th> </tr> </thead> <tbody> <tr> <td> <p>SF-ADJUSTMENT</p> </td> <td> <p> In interactive mode it creates an adjustment widget in the dialog. </p> <p> SF-ADJUSTMENT "label" '(value lower upper step_inc page_inc digits type) </p> <p>"label" : Text printed before the widget.</p> <p>value : Value print at the start.</p> <p> lower / upper : the lower / upper values (range of choice). </p> <p>step_inc : increment/decrement value.</p> <p> page_inc : increment/decrement value using page key. </p> <p> digits : digits after the point (decimal part). </p> <p> type : is one of: SF-SLIDER or 0, SF-SPINNER or 1 </p> </td> </tr> <tr> <td> <p>SF-COLOR</p> </td> <td> <p>Creates a color button in the dialog.</p> <p>SF-COLOR "label" '(red green blue)</p> <p>or</p> <p>SF-COLOR "label" "color"</p> <p>"label" : Text printed before the widget.</p> <p> '(red green blue) : list of three values for the red, green and blue components. </p> <p>"color" : a color name in CSS notatation.</p> </td> </tr> <tr> <td> <p>SF-FONT</p> </td> <td> <p> Creates a font-selection widget in the dialog. It returns a fontname as a string. There are two new gimp-text procedures to ease the use of this return parameter: </p> <p> (gimp-text-fontname image drawable x-pos y-pos text border antialias size unit font) </p> <p> (gimp-text-get-extents-fontname text size unit font) </p> <p> where font is the fontname you get. The size specified in the fontname is silently ignored. It is only used in the font-selector. So you are asked to set it to a useful value (24 pixels is a good choice). </p> <p>SF-FONT "label" "fontname"</p> <p>"label" : Text printed before the widget.</p> <p>"fontname" : name of the d√©fault font.</p> </td> </tr> <tr> <td> <p>SF-BRUSH</p> </td> <td> <p> It will create a widget in the control dialog. The widget consists of a preview area (which when pressed will produce a popup preview ) and a button with the "..." label. The button will popup a dialog where brushes can be selected and each of the characteristics of the brush can be modified. </p> <p>SF-BRUSH "Brush" '("Circle (03)" 100 44 0)</p> <p> Here the brush dialog will be popped up with a default brush of Circle (03) opacity 100 spacing 44 and paint mode of Normal (value 0). </p> <p> If this selection was unchanged the value passed to the function as a parameter would be '("Circle (03)" 100 44 0). </p> </td> </tr> <tr> <td> <p>SF-PATTERN</p> </td> <td> <p> It will create a widget in the control dialog. The widget consists of a preview area (which when pressed will produce a popup preview ) and a button with the "..." label. The button will popup a dialog where patterns can be selected. </p> <p>SF-PATTERN "Pattern" "Maple Leaves"</p> <p> The value returned when the script is invoked is a string containing the pattern name. If the above selection was not altered the string would contain "Maple Leaves". </p> </td> </tr> <tr> <td> <p>SF-GRADIENT</p> </td> <td> <p> It will create a widget in the control dialog. The widget consists of a button containing a preview of the selected gradient. </p> <p> If the button is pressed a gradient selection dialog will popup. </p> <p>SF-GRADIENT "Gradient" "Deep Sea"</p> <p> The value returned when the script is invoked is a string containing the gradient name. If the above selection was not altered the string would contain "Deep Sea". </p> <p> Cliquer sur celui-ci fait appara√Ætre la boite de dialogue des d√©grad√©s. </p> </td> </tr> <tr> <td> <p>SF-PALETTE</p> </td> <td> <p> It will create a widget in the control dialog. The widget consists of a button containing the name of the selected palette. </p> <p> If the button is pressed a palette selection dialog will popup. </p> <p>SF-PALETTE "Palette" "Named Colors"</p> <p> The value returned when the script is invoked is a string containing the palette name. If the above selection was not altered the string would contain "Named Colors". </p> <p> Cliquer sur celui-ci fait appara√Ætre la boite de dialogue des palettes. </p> </td> </tr> <tr> <td> <p>SF-FILENAME</p> </td> <td> <p> It will create a widget in the control dialog. The widget consists of a button containing the name of a file. </p> <p> If the button is pressed a file selection dialog will popup. </p> <p> SF-FILENAME "Environment Map" (string-append "" gimp-data-directory "/scripts/beavis.jpg") </p> <p> The value returned when the script is invoked is a string containing the filename. </p> </td> </tr> <tr> <td> <p>SF-DIRNAME</p> </td> <td> <p> Only useful in interactive mode. Very similar to SF-FILENAME, but the created widget allows to choose a directory instead of a file. </p> <p> SF-DIRNAME "Image Directory" "/var/tmp/images" </p> <p> The value returned when the script is invoked is a string containing the dirname. </p> </td> </tr> <tr> <td> <p>SF-OPTION</p> </td> <td> <p> It will create a widget in the control dialog. The widget is a combo-box showing the options that are passed as a list. </p> <p>The first option is the default choice.</p> <p> SF-OPTION "Orientation" '("Horizontal" "Vertical") </p> <p> The value returned when the script is invoked is the number of the chosen option, where the option first is counted as 0. </p> </td> </tr> <tr> <td> <p>SF-ENUM</p> </td> <td> <p> It will create a widget in the control dialog. The widget is a combo-box showing all enum values for the given enum type. This has to be the name of a registered enum, without the "Gimp" prefix. The second parameter speficies the default value, using the enum value's nick. </p> <p> SF-ENUM "Interpolation" '("InterpolationType" "linear") </p> <p> The value returned when the script is invoked corresponds to chosen enum value. </p> </td> </tr> </tbody> </table> </div> </div> <div class="footnotes"> <br /> <hr width="100" align="left" /> <div class="footnote"> <p><sup>[<a id="ftn.id2618815" href="#id2618815" class="para">3</a>] </sup> This section is not part of the original tutorial. </p> </div> </div> </div> <div class="navfooter"> <hr /> <table width="100%" summary="Navigation footer"> <tr> <td width="40%" align="left"><a accesskey="p" href="gimp-using-script-fu-tutorial-lists.html"><img src="../images/prev.png" alt="Prev" /></a>¬†</td> <td width="20%" align="center"> <a accesskey="u" href="gimp-using-script-fu-tutorial.html"> <img src="../images/up.png" alt="Up" /> </a> </td> <td width="40%" align="right">¬†<a accesskey="n" href="gimp-using-script-fu-tutorial-script.html"><img src="../images/next.png" alt="Next" /></a></td> </tr> <tr> <td width="40%" align="left" valign="top"><a accesskey="p" href="gimp-using-script-fu-tutorial-lists.html">3.3.¬† <span lang="en" xml:lang="en">Lists, Lists And More Lists</span> </a>¬†</td> <td width="20%" align="center"> <a accesskey="h" href="index.html"> <img src="../images/home.png" alt="Home" /> </a> </td> <td width="40%" align="right" valign="top">¬†<a accesskey="n" href="gimp-using-script-fu-tutorial-script.html">3.5.¬† <span lang="en" xml:lang="en">Giving Our Script Some Guts</span> </a></td> </tr> </table> </div> </body> </html>