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

docs/CHANGES.txt

@@ -27,6 +27,14 @@ $Id$
     * Added "_modes()" function to Magic tool API, so Magic tool plugins
       can tell Tux Paint what modes it accepts, 'paint' or 'fullscreen'.
 
+    * "_click()" function is now given a 'mode' value, corresponding to the
+      mode the current tool is in.
+
+    * "_get_description()" function is now given a 'mode' value, and is
+      called once for each mode a particular tool claims to support.
+      (e.g., "which=0,mode=MODE_PAINT", then "which=1,mode=MODE_PAINT",
+      then "which=1,mode=MODE_FULLSCREEN")
+
     * "Paint" and "Fullscreen" control buttons added to Magic tool
       selector UI.  Can be disabled with "--nomagiccontrols".
 

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)
+           * char * get_description(magic_api * api, int which, int mode)
-             This should return a string containing the description of a
+             This should return a string containing the description of how to
-             magic tool. This will appear as a help tip, explained by Tux the
+             use a particular magic tool. This will appear as a help tip,
-             Penguin, within Tux Paint.
+             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
+             Note: For each Magic tool your plugin claims to contain
-             contain (by your "get_tool_count()").
+             (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>
+  int&nbsp;which, int&nbsp;mode)</b></code><br>
-  This should return a string containing the description of a magic tool.
+  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
+  <b>Note:</b> For each Magic tool your plugin claims to
-  contain (by your "<code>get_tool_count()</code>").<br>
+  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(
+  if (mode == MODE_PAINT)
-         gettext_noop("Click and move the mouse around to draw a negative.")));
+    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.")));
 }

src/tp_magic_api.h.in

@@ -50,7 +50,7 @@
 /* (as of API version 0x00000002) */
 #define MODE_PAINT      0x0001  /* User can paint the tool, freehand */
 #define MODE_FULLSCREEN 0x0002  /* User can apply effect to entire canvas at once */
-
+#define MAX_MODES 2
 
 typedef struct magic_api_t {
   /* A string containing the current version of Tux Paint (e.g., "0.9.18") */

src/tuxpaint.c

@@ -895,7 +895,7 @@ typedef struct magic_funcs_s {
   int (*get_tool_count)(magic_api *);
   char * (*get_name)(magic_api *, int);
   SDL_Surface * (*get_icon)(magic_api *, int);
-  char * (*get_description)(magic_api *, int);
+  char * (*get_description)(magic_api *, int, int);
   int (*requires_colors)(magic_api *, int);
   int (*modes)(magic_api *, int);
   void (*set_color)(magic_api *, Uint8, Uint8, Uint8);
@@ -918,7 +918,7 @@ typedef struct magic_s {
   int avail_modes;	// Available modes (paint &/or fullscreen)
   int colors;	// Whether magic tool accepts colors
   char * name;	// Name of magic tool
-  char * tip;	// Description of magic tool
+  char * tip[MAX_MODES];	// Description of magic tool, in each possible mode
   SDL_Surface * img_icon;
   SDL_Surface * img_name;
 } magic_t;
@@ -1558,6 +1558,7 @@ Uint8 magic_touched(int x, int y);
 
 void magic_switchin(SDL_Surface * last);
 void magic_switchout(SDL_Surface * last);
+int magic_modeint(int mode);
 
 #ifdef DEBUG
 static char *debug_gettext(const char *str);
@@ -3185,7 +3186,7 @@ static void mainloop(void)
 						color_hexes[cur_color][2]);
 	      }
 
-	      draw_tux_text(TUX_GREAT, magics[cur_magic].tip, 1);
+	      draw_tux_text(TUX_GREAT, magics[cur_magic].tip[magic_modeint(magics[cur_magic].mode)], 1);
 
 	      if (do_draw)
 		draw_magic();
@@ -3397,7 +3398,7 @@ static void mainloop(void)
 							   old_x, old_y,
 							   &update_rect);
 	    
-	    draw_tux_text(TUX_GREAT, magics[cur_magic].tip, 1);
+	    draw_tux_text(TUX_GREAT, magics[cur_magic].tip[magic_modeint(magics[cur_magic].mode)], 1);
 
   	    update_canvas(update_rect.x, update_rect.y,
 			  update_rect.x + update_rect.w,
@@ -3756,7 +3757,7 @@ static void mainloop(void)
 							   old_x, old_y,
 							   &update_rect);
 	    
-	    draw_tux_text(TUX_GREAT, magics[cur_magic].tip, 1);
+	    draw_tux_text(TUX_GREAT, magics[cur_magic].tip[magic_modeint(magics[cur_magic].mode)], 1);
 
   	    update_canvas(update_rect.x, update_rect.y,
 			  update_rect.x + update_rect.w,
@@ -17207,15 +17208,28 @@ void load_magic_plugins(void)
                 }
                 else
                 {
+                  int j, bit;
+
 		  for (i = 0; i < n; i++)
 		  {
 		    magics[num_magics].idx = i;
 		    magics[num_magics].place = plc;
 		    magics[num_magics].handle_idx = num_plugin_files;
 		    magics[num_magics].name = magic_funcs[num_plugin_files].get_name(magic_api_struct, i);
-		    magics[num_magics].tip = magic_funcs[num_plugin_files].get_description(magic_api_struct, i);
+
-		    magics[num_magics].colors = magic_funcs[num_plugin_files].requires_colors(magic_api_struct, i);
 		    magics[num_magics].avail_modes = magic_funcs[num_plugin_files].modes(magic_api_struct, i);
+
+                    bit = 1;
+                    for (j = 0; j < MAX_MODES; j++)
+		    {
+                      if (magics[num_magics].avail_modes & bit)
+		        magics[num_magics].tip[j] = magic_funcs[num_plugin_files].get_description(magic_api_struct, i, bit);
+                      else
+		        magics[num_magics].tip[j] = NULL;
+                      bit *= 2;
+		    }
+
+		    magics[num_magics].colors = magic_funcs[num_plugin_files].requires_colors(magic_api_struct, i);
 		    if (magics[num_magics].avail_modes & MODE_PAINT)
 		    	magics[num_magics].mode = MODE_PAINT;
 		    else
@@ -18961,3 +18975,12 @@ void magic_switchin(SDL_Surface * last)
 					               magics[cur_magic].idx,
 					               canvas, last);
 }
+
+int magic_modeint(int mode)
+{
+  if (mode == MODE_PAINT)
+    return 0;
+  else if (mode == MODE_FULLSCREEN)
+    return 1;
+}
+