get_description() gets mode, so tools can provide diff. instructions.

magic/docs/README.txt

@@ -218,16 +218,23 @@ Interfaces
              Note: Called once for each Magic tool your plugin claims to
              contain (by your "get_tool_count()").
 
-           * char * get_description(magic_api * api, int which)
-             This should return a string containing the description of a
-             magic tool. This will appear as a help tip, explained by Tux the
-             Penguin, within Tux Paint.
+           * char * get_description(magic_api * api, int which, int mode)
+             This should return a string containing the description of how to
+             use a particular magic tool. This will appear as a help tip,
+             explained by Tux the Penguin, within Tux Paint.
 
              Tux Paint will free() the string upon exit, so you should wrap
              it in a C strdup() call.
 
-             Note: Called once for each Magic tool your plugin claims to
-             contain (by your "get_tool_count()").
+             Note: For each Magic tool your plugin claims to contain
+             (reported by your "get_tool_count()" function), this function
+             will be called for each mode the tool claims to support
+             (reported by your "modes()" function).
+
+             In other words, if your plugin contains two tools, one which
+             works in paint mode only, and the other that works in both paint
+             mode and full-image mode, your plugin's "get_description()" will
+             be called three times.
 
            * int requires_colors(magic_api * api, int which)
              Return a '1' if the 'Magic' tool accepts colors (the 'Colors'

magic/docs/html/README.html

@@ -284,16 +284,24 @@ then the names of your functions must begin with "<code><b>zoom_</b></code>"
   <br>
 
 <li><code><b>char * get_description(magic_api&nbsp;*&nbsp;api,
-  int&nbsp;which)</b></code><br>
-  This should return a string containing the description of a magic tool.
+  int&nbsp;which, int&nbsp;mode)</b></code><br>
+  This should return a string containing the description of how to
+  use a particular magic tool.
   This will appear as a help tip, explained by Tux the Penguin, within
   Tux&nbsp;Paint.<br>
   <br>
   Tux Paint will <code>free()</code> the string upon exit, so you should
   wrap it in a C <code>strdup()</code> call.<br>
   <br>
-  <b>Note:</b> Called once for each Magic tool your plugin claims to
-  contain (by your "<code>get_tool_count()</code>").<br>
+  <b>Note:</b> For each Magic tool your plugin claims to
+  contain (reported by your "<code>get_tool_count()</code>" function),
+  this function will be called for each mode the tool claims to support
+  (reported by your "<code>modes()</code>" function).<br>
+  <br>
+  In other words, if your plugin contains two tools, one which works in
+  paint mode only, and the other that works in both paint mode and
+  full-image mode, your plugin's "<code>get_description()</code>" will be
+  called three times.<br>
   <br>
 
 <li><code><b>int requires_colors(magic_api&nbsp;*&nbsp;api,

magic/src/blackAndWhite.c

@@ -98,7 +98,7 @@ char * blackAndWhite_get_name(magic_api * api, int which){
 }
 
 // Return our descriptions, localized:
-char * blackAndWhite_get_description(magic_api * api, int which){
+char * blackAndWhite_get_description(magic_api * api, int which, int mode){
   return(strdup(gettext(bandw_descs[which])));
 }
 

magic/src/blocks_chalk_drip.c

@@ -55,7 +55,7 @@ Uint32 blocks_chalk_drip_api_version(void);
 int blocks_chalk_drip_get_tool_count(magic_api * api);
 SDL_Surface * blocks_chalk_drip_get_icon(magic_api * api, int which);
 char * blocks_chalk_drip_get_name(magic_api * api, int which);
-char * blocks_chalk_drip_get_description(magic_api * api, int which);
+char * blocks_chalk_drip_get_description(magic_api * api, int which, int mode);
 static void blocks_chalk_drip_linecb(void * ptr, int which,
 			      SDL_Surface * canvas, SDL_Surface * last,
 	                      int x, int y);
@@ -139,7 +139,7 @@ char * blocks_chalk_drip_get_name(magic_api * api ATTRIBUTE_UNUSED, int which)
 }
 
 // Return our descriptions, localized:
-char * blocks_chalk_drip_get_description(magic_api * api ATTRIBUTE_UNUSED, int which)
+char * blocks_chalk_drip_get_description(magic_api * api ATTRIBUTE_UNUSED, int which, int mode)
 {
   if (which == TOOL_BLOCKS)
     return(strdup(gettext_noop(

magic/src/blur.c

@@ -77,7 +77,7 @@ char * blur_get_name(magic_api * api, int which)
 }
 
 // Return our descriptions, localized:
-char * blur_get_description(magic_api * api, int which)
+char * blur_get_description(magic_api * api, int which, int mode)
 {
   return(strdup(gettext_noop(
 "Click and move the mouse around to blur the picture.")));

magic/src/blurAll.c

@@ -94,7 +94,7 @@ char * blurAll_get_name(magic_api * api, int which){
 }
 
 // Return our descriptions, localized:
-char * blurAll_get_description(magic_api * api, int which){
+char * blurAll_get_description(magic_api * api, int which, int mode){
   return(strdup(gettext(blurAll_descs[which])));
 }
 

magic/src/bricks.c

@@ -105,7 +105,7 @@ char * bricks_get_name(magic_api * api, int which)
 }
 
 // Return our descriptions, localized:
-char * bricks_get_description(magic_api * api, int which)
+char * bricks_get_description(magic_api * api, int which, int mode)
 {
   if (which == TOOL_LARGEBRICKS)
     return(strdup(gettext_noop("Click and move to draw large bricks.")));

magic/src/calligraphy.c

@@ -109,7 +109,7 @@ char * calligraphy_get_name(magic_api * api, int which)
 }
 
 // Return our description, localized:
-char * calligraphy_get_description(magic_api * api, int which)
+char * calligraphy_get_description(magic_api * api, int which, int mode)
 {
   return(strdup(
          gettext_noop("Click and move the mouse around to draw in calligraphy.")));

magic/src/cartoon.c

@@ -81,7 +81,7 @@ char * cartoon_get_name(magic_api * api, int which)
 }
 
 // Return our descriptions, localized:
-char * cartoon_get_description(magic_api * api, int which)
+char * cartoon_get_description(magic_api * api, int which, int mode)
 {
   return(strdup(gettext_noop(
 "Click and move the mouse around to turn the picture into a cartoon.")));

magic/src/distortion.c

@@ -124,7 +124,7 @@ char * distortion_get_name(magic_api * api, int which)
 
 // Report our "Magic" tool descriptions
 
-char * distortion_get_description(magic_api * api, int which)
+char * distortion_get_description(magic_api * api, int which, int mode)
 {
   return(strdup(gettext_noop("Click and drag the mouse to cause a distortion in your picture.")));
 }

magic/src/emboss.c

@@ -77,7 +77,7 @@ char * emboss_get_name(magic_api * api, int which)
 }
 
 // Return our descriptions, localized:
-char * emboss_get_description(magic_api * api, int which)
+char * emboss_get_description(magic_api * api, int which, int mode)
 {
   return(strdup(gettext_noop("Click and drag the mouse to emboss the picture.")));
 }

magic/src/fade_darken.c

@@ -49,7 +49,7 @@ Uint32 fade_darken_api_version(void);
 int fade_darken_get_tool_count(magic_api * api);
 SDL_Surface * fade_darken_get_icon(magic_api * api, int which);
 char * fade_darken_get_name(magic_api * api, int which);
-char * fade_darken_get_description(magic_api * api, int which);
+char * fade_darken_get_description(magic_api * api, int which, int mode);
 static void do_fade_darken(void * ptr, int which,
 	         SDL_Surface * canvas, SDL_Surface * last,
 	         int x, int y);
@@ -121,7 +121,7 @@ char * fade_darken_get_name(magic_api * api ATTRIBUTE_UNUSED, int which)
 }
 
 // Return our description, localized:
-char * fade_darken_get_description(magic_api * api ATTRIBUTE_UNUSED, int which)
+char * fade_darken_get_description(magic_api * api ATTRIBUTE_UNUSED, int which, int mode)
 {
   if (which == TOOL_FADE)
     return(strdup(

magic/src/fill.c

@@ -88,7 +88,7 @@ char * fill_get_name(magic_api * api, int which)
 }
 
 // Return our descriptions, localized:
-char * fill_get_description(magic_api * api, int which)
+char * fill_get_description(magic_api * api, int which, int mode)
 {
   return(strdup(gettext_noop(
 "Click in the picture to fill that area with color.")));

magic/src/flower.c

@@ -125,7 +125,7 @@ char * flower_get_name(magic_api * api, int which)
 }
 
 // Return our descriptions, localized:
-char * flower_get_description(magic_api * api, int which)
+char * flower_get_description(magic_api * api, int which, int mode)
 {
   return(strdup(gettext_noop("Click and drag to draw a flower stalk. Let go to finish the flower.")));
 }

magic/src/foam.c

@@ -105,7 +105,7 @@ char * foam_get_name(magic_api * api, int which)
 }
 
 // Return our descriptions, localized:
-char * foam_get_description(magic_api * api, int which)
+char * foam_get_description(magic_api * api, int which, int mode)
 {
   return(strdup(gettext_noop("Click and drag the mouse to cover an area with foamy bubbles.")));
 }

magic/src/glasstile.c

@@ -84,7 +84,7 @@ char * glasstile_get_name(magic_api * api, int which)
 }
 
 // Return our descriptions, localized:
-char * glasstile_get_description(magic_api * api, int which)
+char * glasstile_get_description(magic_api * api, int which, int mode)
 {
   return(strdup(gettext_noop("Click and drag the mouse to put glass tile over your picture.")));
 }

magic/src/grass.c

@@ -93,7 +93,7 @@ char * grass_get_name(magic_api * api, int which)
 }
 
 // Return our descriptions, localized:
-char * grass_get_description(magic_api * api, int which)
+char * grass_get_description(magic_api * api, int which, int mode)
 {
   return(strdup(gettext_noop("Click and move to draw grass. Don’t forget the dirt!")));
 }

magic/src/kalidescope.c

@@ -78,7 +78,7 @@ char * kalidescope_get_name(magic_api * api, int which)
 }
 
 // Return our descriptions, localized:
-char * kalidescope_get_description(magic_api * api, int which)
+char * kalidescope_get_description(magic_api * api, int which, int mode)
 {
   return(strdup(gettext_noop("Click and drag the mouse to draw with symmetric brushes (a kaleidoscope).")));
 }

magic/src/light.c

@@ -85,7 +85,7 @@ char * light_get_name(magic_api * api, int which)
 }
 
 // Return our descriptions, localized:
-char * light_get_description(magic_api * api, int which)
+char * light_get_description(magic_api * api, int which, int mode)
 {
   return(strdup(gettext_noop("Click and drag to draw a beam of light on your picture.")));
 }

magic/src/metalpaint.c

@@ -78,7 +78,7 @@ char * metalpaint_get_name(magic_api * api, int which)
 }
 
 // Return our descriptions, localized:
-char * metalpaint_get_description(magic_api * api, int which)
+char * metalpaint_get_description(magic_api * api, int which, int mode)
 {
   return(strdup(gettext_noop("Click and drag the mouse to paint with a metallic color.")));
 }

magic/src/mirror_flip.c

@@ -99,7 +99,7 @@ char * mirror_flip_get_name(magic_api * api, int which)
 }
 
 // Return our descriptions, localized:
-char * mirror_flip_get_description(magic_api * api, int which)
+char * mirror_flip_get_description(magic_api * api, int which, int mode)
 {
   if (which == TOOL_MIRROR)
     return(strdup(

magic/src/negative.c

@@ -73,10 +73,16 @@ char * negative_get_name(magic_api * api, int which)
 }
 
 // Return our description, localized:
-char * negative_get_description(magic_api * api, int which)
+char * negative_get_description(magic_api * api, int which, int mode)
 {
-  return(strdup(
-         gettext_noop("Click and move the mouse around to draw a negative.")));
+  if (mode == MODE_PAINT)
+    return(strdup(
+           gettext_noop("Click and move the mouse around to draw a negative."))); /* FIXME: This barely makes sense */
+  else if (mode == MODE_FULLSCREEN)
+    return(strdup(
+           gettext_noop("Click to turn the image into its negative.")));
+  else
+    return(NULL);
 }
 
 // Callback that does the negative color effect on a circle centered around x,y

magic/src/rainbow.c

@@ -108,7 +108,7 @@ char * rainbow_get_name(magic_api * api, int which)
 }
 
 // Return our descriptions, localized:
-char * rainbow_get_description(magic_api * api, int which)
+char * rainbow_get_description(magic_api * api, int which, int mode)
 {
   return(strdup(
 	   gettext_noop("You can draw in rainbow colors!")));

magic/src/ripples.c

@@ -82,7 +82,7 @@ char * ripples_get_name(magic_api * api, int which)
 }
 
 // Return our descriptions, localized:
-char * ripples_get_description(magic_api * api, int which)
+char * ripples_get_description(magic_api * api, int which, int mode)
 {
   return(strdup(gettext_noop("Click to make ripples appear over your picture.")));
 }

magic/src/sharpen.c

@@ -116,7 +116,7 @@ char * sharpen_get_name(magic_api * api, int which){
 }
 
 // Return our descriptions, localized:
-char * sharpen_get_description(magic_api * api, int which){
+char * sharpen_get_description(magic_api * api, int which, int mode){
   return(strdup(gettext(sharpen_descs[which])));
 }
 

magic/src/shift.c

@@ -51,7 +51,7 @@ int shift_init(magic_api * api);
 int shift_get_tool_count(magic_api * api);
 SDL_Surface * shift_get_icon(magic_api * api, int which);
 char * shift_get_name(magic_api * api, int which);
-char * shift_get_description(magic_api * api, int which);
+char * shift_get_description(magic_api * api, int which, int mode);
 void shift_drag(magic_api * api, int which, SDL_Surface * canvas,
 	          SDL_Surface * last, int ox, int oy, int x, int y,
 		  SDL_Rect * update_rect);
@@ -105,7 +105,7 @@ char * shift_get_name(magic_api * api ATTRIBUTE_UNUSED, int which ATTRIBUTE_UNUS
 }
 
 // Return our descriptions, localized:
-char * shift_get_description(magic_api * api ATTRIBUTE_UNUSED, int which ATTRIBUTE_UNUSED)
+char * shift_get_description(magic_api * api ATTRIBUTE_UNUSED, int which ATTRIBUTE_UNUSED, int mode)
 {
   return(strdup(gettext_noop("Click and drag to shift your picture around on the canvas.")));
 }

magic/src/smudge.c

@@ -78,7 +78,7 @@ char * smudge_get_name(magic_api * api, int which)
 }
 
 // Return our descriptions, localized:
-char * smudge_get_description(magic_api * api, int which)
+char * smudge_get_description(magic_api * api, int which, int mode)
 {
   return(strdup(gettext_noop(
 "Click and move the mouse around to smudge the picture.")));

magic/src/tint.c

@@ -78,7 +78,7 @@ char * tint_get_name(magic_api * api, int which)
 }
 
 // Return our descriptions, localized:
-char * tint_get_description(magic_api * api, int which)
+char * tint_get_description(magic_api * api, int which, int mode)
 {
   return(strdup(gettext_noop(
 "Click and move the mouse around to change the picture’s color.")));

magic/src/waves.c

@@ -79,7 +79,7 @@ char * waves_get_name(magic_api * api, int which)
 }
 
 // Return our descriptions, localized:
-char * waves_get_description(magic_api * api, int which)
+char * waves_get_description(magic_api * api, int which, int mode)
 {
   return(strdup(gettext_noop("Click to make the picture wavy. Click toward the top for shorter waves, the bottom for taller waves, the left for small waves, and the right for long waves.")));
 }