notgne2/tuxpaint-pencil-sharpener
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Sync tp_magic_example.c from tuxpaint-docs

Browse source
This commit is contained in:
Bill Kendrick 2022-10-19 01:42:23 -07:00
parent 2083b66564
commit 1a0a07ea32
10 changed files with 2370 additions and 1950 deletions
Download patch file Download diff file Expand all files Collapse all files

432
docs/en/html/tp_magic_example.c
View file

@ -1,7 +1,7 @@
/* tp_magic_example.c /* tp_magic_example.c
An example of a "Magic" tool plugin for Tux Paint An example of a "Magic" tool plugin for Tux Paint
October 18, 2022 October 19, 2022
*/ */
@ -26,12 +26,12 @@
enum enum
{ {
TOOL_ONE, // Becomes '0' TOOL_ONE, // Becomes '0'
TOOL_ONE, // Becomes '1' TOOL_TWO, // Becomes '1'
NUM_TOOLS // Becomes '2' NUM_TOOLS // Becomes '2'
}; };
/* A list of filenames for sounds and icons to load at startup: */ /* Lists of filenames for sounds and icons to load at startup: */
const char *sound_filenames[NUM_TOOLS] = { const char *sound_filenames[NUM_TOOLS] = {
"tool_one.wav", "tool_one.wav",
@ -61,7 +61,7 @@ const char *tool_names[NUM_TOOLS] = {
/* How to group the tools with other similar tools, within the 'Magic' selector: */ /* How to group the tools with other similar tools, within the 'Magic' selector: */
const int tool_groups[$NUM_TOOLS] = { const int tool_groups[NUM_TOOLS] = {
MAGIC_TYPE_PAINTING, MAGIC_TYPE_PAINTING,
MAGIC_TYPE_DISTORTS MAGIC_TYPE_DISTORTS
}; };
@ -83,7 +83,7 @@ const char *tool_descriptions[NUM_TOOLS] = {
Mix_Chunk *sound_effects[NUM_TOOLS]; Mix_Chunk *sound_effects[NUM_TOOLS];
/* The current color (an "RGB" -- red, green, blue -- value) the user has selected in Tux Paint: */ /* The current color (an "RGB" -- red, green, blue -- value) the user has selected in Tux Paint: */
Uint8 example_r, $example_g, $example_b; Uint8 example_r, example_g, example_b;
/* Our local function prototypes: */ /* Our local function prototypes: */
@ -97,11 +97,11 @@ _before_ them.
*/ */
void example_drag(magic_api * api, int which, SDL_Surface * canvas, void example_drag(magic_api * api, int which, SDL_Surface * canvas,
SDL_Surface * snapshot, int ox, int oy, int x, int y, SDL_Surface * snapshot, int old_x, int old_y, int x, int y,
SDL_Rect * update_rect); SDL_Rect * update_rect);
void example_line_callback(void *pointer, int which, SDL_Surface * canvas, void example_line_callback(void *pointer, int which, SDL_Surface * canvas,
SDL_Surface * snapshot, int x, int y); SDL_Surface * snapshot, int x, int y);
/* Setup Functions: */ /* Setup Functions: */
@ -154,13 +154,14 @@ int example_init(magic_api * api)
Use "api->data_directory" to figure out where our sounds should be. (The Use "api->data_directory" to figure out where our sounds should be. (The
"tp-magic-config --dataprefix" command would have told us when we installed "tp-magic-config --dataprefix" command would have told us when we installed
our plugin and its data.) our plugin and its data.)
*/
snprintf(filename, sizeof(filename), "%s/sounds/magic/%s", api->data_directory, snprintf(filename, sizeof(filename), "%s/sounds/magic/%s", api->data_directory,
sound_filenames[i]); sound_filenames[i]);
printf("Trying to load %s sound file\n", filename); printf("Trying to load %s sound file\n", filename);
// Try to load the file! /* Try to load the file! */
sound_effects[i] = Mix_LoadWAV(filename); sound_effects[i] = Mix_LoadWAV(filename);
} }
@ -168,80 +169,86 @@ int example_init(magic_api * api)
} }
// Report our tool count /*
// Report our tool count
// Tux Paint needs to know how many "Magic" tools we'll be providing.
// Return that number here. (We simply grab the value of "NUM_TOOLS"
// from our 'enum' above!)
//
// When Tux Paint is starting up and loading plugins, it will call
// some of the following setup functions once for each tool we report.
Tux Paint needs to know how many 'Magic' tools we'll be providing. Return
that number here. (We simply grab the value of 'NUM_TOOLS' from our 'enum'
above!)
When Tux Paint is starting up and loading plugins, it will call some of the
following setup functions once for each tool we report.
*/
int example_get_tool_count(magic_api * api) int example_get_tool_count(magic_api * api)
{ {
return (NUM_TOOLS); return (NUM_TOOLS);
} }
// Load icons /*
// Load our icons
// When Tux Paint is starting up and loading plugins, it asks us to
// provide icons for the "Magic" tool buttons.
When Tux Paint is starting up and loading plugins, it asks us to provide icons for the 'Magic' tool buttons.
*/
SDL_Surface *example_get_icon(magic_api * api, int which) SDL_Surface *example_get_icon(magic_api * api, int which)
{ {
char fname[1024]; char filename[1024];
// Assemble the filename from the "icon_filenames[]" array into /*
// a full path to a real file. Assemble the filename from the "icon_filenames[]" array into a full path to
// a real file.
// Use "api->data_directory" to figure out where our sounds should be.
// (The "tp-magic-config --dataprefix" command would have told us when
// we installed our plugin and its data.)
//
// We use 'which' (which of our tools Tux Paint is asking about)
// as an index into the array.
snprintf(fname, sizeof(fname), "%s/images/magic/%s.png", Use "api->data_directory" to figure out where our sounds should be. (The
"tp-magic-config --dataprefix" command would have told us when we installed
our plugin and its data.)
We use "which" (which of our tools Tux Paint is asking about) as an index
into the array.
*/
snprintf(filename, sizeof(filename), "%s/images/magic/%s",
api->data_directory, icon_filenames[which]); api->data_directory, icon_filenames[which]);
printf("Trying to load %s icon\n", filename);
// Try to load the image, and return the results to Tux Paint: /* Try to load the image, and return the results to Tux Paint: */
return (IMG_Load(fname)); return (IMG_Load(filename));
} }
// Report our "Magic" tool names /*
// Report our 'Magic' tool names
// When Tux Paint is starting up and loading plugins, it asks us to
// provide names (labels) for the "Magic" tool buttons.
When Tux Paint is starting up and loading plugins, it asks us to provide
names (labels) for the 'Magic' tool buttons.
*/
char *example_get_name(magic_api * api, int which) char *example_get_name(magic_api * api, int which)
{ {
const char *our_name_english; const char *our_name_english;
const char *our_name_localized; const char *our_name_localized;
// Get our name from the "names[]" array. /*
// Get our name from the "tool_names[]" array.
// We use 'which' (which of our tools Tux Paint is asking about)
// as an index into the array.
our_name_english = names[which]; We use 'which' (which of our tools Tux Paint is asking about) as an index
into the array.
*/
our_name_english = tool_names[which];
// Return a localized (aka translated) version of our name, /*
// if possible. Return a localized (aka translated) version of our name, if possible.
//
// We send "gettext()" the English version of the name from our array.
We send "gettext()" the English version of the name from our array.
*/
our_name_localized = gettext(our_name_english); our_name_localized = gettext(our_name_english);
// Finally, duplicate the string into a new section of memory, and /*
// send it to Tux Paint. (Tux Paint keeps track of the string and Finally, duplicate the string into a new section of memory, and send it to
// will free it for us, so we have one less thing to keep track of.) Tux Paint. (Tux Paint keeps track of the string and will free it for us,
so we have one less thing to keep track of.)
*/
return (strdup(our_name_localized)); return (strdup(our_name_localized));
} }
@ -306,9 +313,10 @@ char *example_get_description(magic_api * api, int which, int mode)
int example_requires_colors(magic_api * api, int which) int example_requires_colors(magic_api * api, int which)
{ {
// Both of our tools accept colors, so we're always returning '1' (for 'true') if (which == TOOL_ONE)
return 1;
return 1; else
return 0;
} }
@ -316,8 +324,10 @@ int example_requires_colors(magic_api * api, int which)
int example_modes(magic_api * api, int which) int example_modes(magic_api * api, int which)
{ {
// Both of our tools are painted (neither affect the full-screen), so we're /*
always returning 'MODE_PAINT' Both of our tools are painted (neither affect the full-screen), so we're
always returning 'MODE_PAINT'
*/
return MODE_PAINT; return MODE_PAINT;
} }
@ -347,114 +357,130 @@ void example_shutdown(magic_api * api)
/* Functions that respond to events in Tux Paint: */ /* Functions that respond to events in Tux Paint: */
/* ---------------------------------------------------------------------- */ /* ---------------------------------------------------------------------- */
// Affect the canvas on click: /* Affect the canvas on click: */
void void
example_click(magic_api * api, int which, int mode, example_click(magic_api * api, int which, int mode,
SDL_Surface * canvas, SDL_Surface * snapshot, int x, int y, SDL_Surface * canvas, SDL_Surface * snapshot, int x, int y,
SDL_Rect * update_rect) SDL_Rect * update_rect)
{ {
// In our case, a single click (which is also the start of a drag!) /*
// is identical to what dragging does, but just at one point, rather In our case, a single click (which is also the start of a drag!) is
// than across a line. identical to what dragging does, but just at one point, rather than across
// a line.
// So we 'cheat' here, by calling our draw() function with
// (x,y) for both the beginning and end points of a line. So we 'cheat' here, by calling our "example_draw()" function with (x,y) for
both the beginning and end points of a line.
*/
example_drag(api, which, canvas, snapshot, x, y, x, y, update_rect); example_drag(api, which, canvas, snapshot, x, y, x, y, update_rect);
} }
// Affect the canvas on drag: /* Affect the canvas on drag: */
void void
example_drag(magic_api * api, int which, SDL_Surface * canvas, example_drag(magic_api * api, int which,
SDL_Surface * snapshot, int ox, int oy, int x, int y, SDL_Surface * canvas, SDL_Surface * snapshot,
int old_x, int old_y, int x, int y,
SDL_Rect * update_rect) SDL_Rect * update_rect)
{ {
// Call Tux Paint's "line()" function. /*
// Call Tux Paint's "line()" (line-traversing) function.
// It will calculate a straight line between (ox,ox) and (x,y).
// Every N steps along that line (in this case, N is '1'), it
// will call _our_ function, "example_line_callback()", and send
// the current X,Y coordinates along the line, as well as other
// useful things (which of our "Magic" tools is being used and
// the current and snapshot canvases).
api->line((void *) api, which, canvas, snapshot, ox, oy, x, y, 1, It will calculate a straight line between (old_x,old_y) and (x,y). Every
N steps along that line (in this case, N is '1'), it will call _our_
function, "example_line_callback()", and send the current X,Y
coordinates along the line, as well as other useful things (which of our
'Magic' tools is being used and the current and snapshot canvases).
*/
api->line((void *) api, which, canvas, snapshot,
old_x, old_y, x, y, 1,
example_line_callback); example_line_callback);
/*
If we need to, swap the X and/or Y values, so that the coordinates
(old_x,old_y) is always the top left, and the coordinates (x,y) is
always the bottom right, so the values we put inside "update_rect" make
sense:
*/
// If we need to, swap the X and/or Y values, so that if (old_x > x)
// (ox,oy) is always the top left, and (x,y) is always the bottom right,
// so the values we put inside "update_rect" make sense:
if (ox > x)
{ {
int tmp = ox; int temp = old_x;
ox = x; old_x = x;
x = tmp; x = temp;
} }
if (oy > y) if (old_y > y)
{ {
int tmp = oy; int temp = old_y;
oy = y; old_y = y;
y = tmp; y = temp;
} }
// Fill in the elements of the "update_rect" SDL_Rect structure /*
// that Tux Paint is sharing with us. Fill in the elements of the "update_rect" SDL_Rect structure that Tux
Paint is sharing with us, therefore telling Tux Paint which part of the
canvas has been modified and should be updated.
*/
update_rect->x = ox - 4; update_rect->x = old_x - 4;
update_rect->y = oy - 4; update_rect->y = old_y - 4;
update_rect->w = (x + 4) - update_rect->x; update_rect->w = (x + 4) - update_rect->x;
update_rect->h = (y + 4) - update_rect->h; update_rect->h = (y + 4) - update_rect->y;
/*
Play the appropriate sound effect
// Play the appropriate sound effect We're calculating a value between 0-255 for where the mouse is
// horizontally across the canvas (0 is the left, ~128 is the center, 255
// We're calculating a value between 0-255 for where the mouse is is the right).
// across the canvas (0 is the left, ~128 is the center, 255 is the right).
//
// These are the exact values Tux Paint's "playsound()" wants,
// to determine what speaker to play the sound in.
// (So the sound will pan from speaker to speaker as you drag the
// mouse around the canvas!)
api->playsound(snd_effect[which], (x * 255) / canvas->w, // pan These are the exact values Tux Paint's "playsound()" wants, to determine
255); // distance what speaker to play the sound in. (So the sound will pan from speaker
to speaker as you drag the mouse around the canvas!)
*/
api->playsound(sound_effects[which],
(x * 255) / canvas->w, /* Left/right pan */
255 /* Near/far distance (loudness) */);
} }
// Affect the canvas on release: /* Affect the canvas on release: */
void void
example_release(magic_api * api, int which, example_release(magic_api * api, int which,
SDL_Surface * canvas, SDL_Surface * snapshot, int x, int y, SDL_Surface * canvas, SDL_Surface * snapshot, int x, int y,
SDL_Rect * update_rect) SDL_Rect * update_rect)
{ {
// Neither of our effects do anything special when the mouse is released /*
// from a click or click-and-drag, so there's no code here... Neither of our effects do anything special when the mouse is released
from a click or click-and-drag, so there's no code here...
*/
} }
// Accept colors /*
// Accept colors
// When any of our "Magic" tools are activated by the user,
// if that tool accepts colors, the current color selection is sent to us.
//
// Additionally, if one of our color-accepting tools is active when the
// user changes colors, we'll be informed of that, as well.
//
// The color comes in as RGB values.
When any of our 'Magig' tools are activated by the user, if that tool
accepts colors, the current color selection is sent to us.
Additionally, if one of our color-accepting tools is active when the user
changes their chosen, we'll be informed of that as well.
The color comes in as RGB (red, green, and blue) values from 0 (darkest) to
255 (brightest).
*/
void example_set_color(magic_api * api, Uint8 r, Uint8 g, Uint8 b) void example_set_color(magic_api * api, Uint8 r, Uint8 g, Uint8 b)
{ {
// We simply store the RGB values in the global variables we /*
// declared at the top of this file. We simply store the RGB values in the global variables we declared at
the top of this file.
*/
example_r = r; example_r = r;
example_g = g; example_g = g;
@ -465,114 +491,130 @@ void example_set_color(magic_api * api, Uint8 r, Uint8 g, Uint8 b)
/* The Magic Effect Routines! */ /* The Magic Effect Routines! */
/* ---------------------------------------------------------------------- */ /* ---------------------------------------------------------------------- */
// Our "callback" function /*
// Our 'callback' function
// We do the 'work' in this callback. Our plugin file has just one.
// Some "Magic" tool plugins may have more, depending on the tools they're
// providing. Some have none (since they're not click-and-drag
// painting-style tools).
//
// Our callback function gets called once for every point along a line between
// the mouse's previous and current position, as it's being dragged.
//
// It pays attention to 'which' to determine which of our plugin's tools
// is currently selected.
void example_line_callback(void *ptr, int which, SDL_Surface * canvas, We do the 'work' in this callback. Our plugin file has just one. Some
SDL_Surface * snapshot, int x, int y) 'Magic' tool plugins may have more, depending on the tools they're
providing. Some have none (since they're not click-and-drag painting-style
tools).
Our callback function gets called once for every point along a line between
the mouse's previous and current position, as it's being dragged.
Our callback pays attention to 'which' to determine which of our plugin's
tools is currently selected.
*/
void example_line_callback(void *pointer, int which, SDL_Surface * canvas,
SDL_Surface * snapshot, int x, int y)
{ {
// For technical reasons, we can't accept a pointer to the "magic_api" /*
// struct, like the other functions do. For technical reasons, we can't accept a pointer to the Tux Paint API's
// "magic_api" struct, like the other functions do.
// Instead, we receive a 'generic' pointer (a "void *").
// The line below declares a local "magic_api" pointer variable called "api", Instead, we receive a 'generic' pointer (a "void *"). The line below
// and then assigns it to the value of the 'generic' pointer we received. declares a local "magic_api" pointer variable called "api", and then
// assigns it to the value of the 'generic' pointer we received.
// (The "(magic_api *)" casts the generic pointer into the 'type' of
// pointer we want, a pointer to a "magic_api".) The "(magic_api *)" seen below casts the generic "void *" pointer into
magic_api *api = (magic_api *) ptr; the 'type' of pointer we want, a pointer to a "magic_api" struct.)
*/
magic_api *api = (magic_api *) pointer;
int xx, yy; int xx, yy;
/*
// This function handles both of our tools, so we need to check which This function handles both of our tools, so we need to check which is
// is being used right now. We compare the 'which' argument that being used right now. We compare the 'which' argument that Tux Paint
// Tux Paint sends to us with the values we enumerated above. sends to us with the values we enumerated above.
*/
if (which == TOOL_ONE) if (which == TOOL_ONE)
{ {
// Tool number 1 simply draws a single pixel at the (x,y) location. /*
// It's a 1x1 pixel brush Tool number 1 simply draws a single pixel at the (x,y) location. It acts
as a 1x1 pixel brush.
*/
api->putpixel(canvas, x, y, api->putpixel(canvas, x, y,
SDL_MapRGB(canvas->format, example_r, example_g, SDL_MapRGB(canvas->format,
example_b)); example_r, example_g, example_b));
// We use "SDL_MapRGB()" to convert the RGB value we receive from Tux Paint /*
// for the user's current color selection to a 'Uint32' pixel value We use "SDL_MapRGB()" to convert the RGB value we receive from Tux Paint
// we can send to Tux Paint's "putpixel()" function. for the user's current color selection to a 'Uint32' pixel value we can
send to Tux Paint's "putpixel()" function.
*/
} }
else if (which == TOOL_TWO) else if (which == TOOL_TWO)
{ {
// Tool number 2 copies an 8x8 square of pixels from the opposite side /*
// of the canvas and puts it under the cursor Tool number 2 copies an 8x8 square of pixels from the opposite side of
the canvas and puts it under the cursor.
*/
for (yy = -4; yy < 4; yy++) for (yy = -4; yy < 4; yy++)
{ {
for (xx = -4; xx < 4; xx++) for (xx = -4; xx < 4; xx++)
{ {
api->putpixel(canvas, x + xx, y + yy, api->putpixel(canvas, x + xx, y + yy,
api->getpixel(snapshot, canvas->w - x - xx, api->getpixel(snapshot,
canvas->h - y - yy)); snapshot->w - x - xx,
snapshot->h - y - yy));
// We simply use Tux Paint's "getpixel()" routine to pull pixel /*
// values from the 'snapshot', and then "putpixel()" to draw them Here we have simply use Tux Paint's "getpixel()" routine to pull pixel
// right into the 'canvas'. values from the 'snapshot', and then "putpixel()" to draw them right
into the 'snapshot'.
// Note: putpixel() and getpixel() are safe to use, even if your Note: putpixel() and getpixel() are safe to use, even if your X,Y values
// X,Y values are outside of the SDL surface (e.g., negative, or are outside of the SDL surface (e.g., negative, or greater than the
// greater than the surface's width or height). surface's width and/or height).
*/
} }
} }
} }
} }
// Switch-In event /*
// Switch-In event
// This happens whenever a Magic tool is enabled, either because the
// user just selected it, or they just came back to "Magic" after using
// another tool (e.g., Brush or Text), and this was the most-recently
// selected Magic tool.
//
// (This also applies to momentary tools, like
// Undo and Redo, and image-changing tools such as New and Open.)
//
// It also happens when a Magic tool's mode changes (it first
// receives a 'switchout()', below, for the old mode).
//
// Our example doesn't do anything when we switch to, or away from, our
// Magic tools, so we just do nothing here.
This happens whenever a Magic tool is enabled, either because the user just
selected it, or they just came back to 'Magic' after using another tool
(e.g., Brush or Text), and this was the most-recently selected Magic tool.
(This also applies to momentary tools, like Undo and Redo, and
image-changing tools such as New and Open.)
It also happens when a Magic tool's mode changes (we will first receive a
call to 'example_switchout()', below, for the old mode).
Our example doesn't do anything when we switch to, or away from, our Magic
tools, so we just do nothing here.
*/
void example_switchin(magic_api * api, int which, int mode, void example_switchin(magic_api * api, int which, int mode,
SDL_Surface * canvas) SDL_Surface * canvas)
{ {
} }
// Switch-Out event /*
// Switch-Out event
// This happens whenever a Magic tool is disabled, either because the
// user selected a different Magic tool, or they selected a completely
// different tool (e.g., Brush or Text).
//
// (This also applies to momentary tools, like Undo and Redo, and
// image-changing tools such as New and Open, in which case the
// switchin() function will be called moments later.)
//
// It also happens when a Magic tool's mode changes (it then
// receives a 'switchin()', above, for the new mode).
//
// Our example doesn't do anything when we switch to, or away from, our
// Magic tools, so we just do nothing here.
This happens whenever a Magic tool is disabled, either because the user
selected a different Magic tool, or they selected a completely different
tool (e.g., Brush or Text).
(This also applies to momentary tools, like Undo and Redo, and
image-changing tools such as New and Open.)
(And in that case, our example_switchin() function will be called moments
later.
It also happens when a Magic tool's mode changes (we will then receive a
call to 'example_switchin()', above, for the new mode).
Our example doesn't do anything when we switch to, or away from, our Magic
tools, so we just do nothing here.
*/
void example_switchout(magic_api * api, int which, int mode, void example_switchout(magic_api * api, int which, int mode,
SDL_Surface * canvas) SDL_Surface * canvas)
{ {

432
docs/en/tp_magic_example.c
View file

@ -1,7 +1,7 @@
/* tp_magic_example.c /* tp_magic_example.c
An example of a "Magic" tool plugin for Tux Paint An example of a "Magic" tool plugin for Tux Paint
October 18, 2022 October 19, 2022
*/ */
@ -26,12 +26,12 @@
enum enum
{ {
TOOL_ONE, // Becomes '0' TOOL_ONE, // Becomes '0'
TOOL_ONE, // Becomes '1' TOOL_TWO, // Becomes '1'
NUM_TOOLS // Becomes '2' NUM_TOOLS // Becomes '2'
}; };
/* A list of filenames for sounds and icons to load at startup: */ /* Lists of filenames for sounds and icons to load at startup: */
const char *sound_filenames[NUM_TOOLS] = { const char *sound_filenames[NUM_TOOLS] = {
"tool_one.wav", "tool_one.wav",
@ -61,7 +61,7 @@ const char *tool_names[NUM_TOOLS] = {
/* How to group the tools with other similar tools, within the 'Magic' selector: */ /* How to group the tools with other similar tools, within the 'Magic' selector: */
const int tool_groups[$NUM_TOOLS] = { const int tool_groups[NUM_TOOLS] = {
MAGIC_TYPE_PAINTING, MAGIC_TYPE_PAINTING,
MAGIC_TYPE_DISTORTS MAGIC_TYPE_DISTORTS
}; };
@ -83,7 +83,7 @@ const char *tool_descriptions[NUM_TOOLS] = {
Mix_Chunk *sound_effects[NUM_TOOLS]; Mix_Chunk *sound_effects[NUM_TOOLS];
/* The current color (an "RGB" -- red, green, blue -- value) the user has selected in Tux Paint: */ /* The current color (an "RGB" -- red, green, blue -- value) the user has selected in Tux Paint: */
Uint8 example_r, $example_g, $example_b; Uint8 example_r, example_g, example_b;
/* Our local function prototypes: */ /* Our local function prototypes: */
@ -97,11 +97,11 @@ _before_ them.
*/ */
void example_drag(magic_api * api, int which, SDL_Surface * canvas, void example_drag(magic_api * api, int which, SDL_Surface * canvas,
SDL_Surface * snapshot, int ox, int oy, int x, int y, SDL_Surface * snapshot, int old_x, int old_y, int x, int y,
SDL_Rect * update_rect); SDL_Rect * update_rect);
void example_line_callback(void *pointer, int which, SDL_Surface * canvas, void example_line_callback(void *pointer, int which, SDL_Surface * canvas,
SDL_Surface * snapshot, int x, int y); SDL_Surface * snapshot, int x, int y);
/* Setup Functions: */ /* Setup Functions: */
@ -154,13 +154,14 @@ int example_init(magic_api * api)
Use "api->data_directory" to figure out where our sounds should be. (The Use "api->data_directory" to figure out where our sounds should be. (The
"tp-magic-config --dataprefix" command would have told us when we installed "tp-magic-config --dataprefix" command would have told us when we installed
our plugin and its data.) our plugin and its data.)
*/
snprintf(filename, sizeof(filename), "%s/sounds/magic/%s", api->data_directory, snprintf(filename, sizeof(filename), "%s/sounds/magic/%s", api->data_directory,
sound_filenames[i]); sound_filenames[i]);
printf("Trying to load %s sound file\n", filename); printf("Trying to load %s sound file\n", filename);
// Try to load the file! /* Try to load the file! */
sound_effects[i] = Mix_LoadWAV(filename); sound_effects[i] = Mix_LoadWAV(filename);
} }
@ -168,80 +169,86 @@ int example_init(magic_api * api)
} }
// Report our tool count /*
// Report our tool count
// Tux Paint needs to know how many "Magic" tools we'll be providing.
// Return that number here. (We simply grab the value of "NUM_TOOLS"
// from our 'enum' above!)
//
// When Tux Paint is starting up and loading plugins, it will call
// some of the following setup functions once for each tool we report.
Tux Paint needs to know how many 'Magic' tools we'll be providing. Return
that number here. (We simply grab the value of 'NUM_TOOLS' from our 'enum'
above!)
When Tux Paint is starting up and loading plugins, it will call some of the
following setup functions once for each tool we report.
*/
int example_get_tool_count(magic_api * api) int example_get_tool_count(magic_api * api)
{ {
return (NUM_TOOLS); return (NUM_TOOLS);
} }
// Load icons /*
// Load our icons
// When Tux Paint is starting up and loading plugins, it asks us to
// provide icons for the "Magic" tool buttons.
When Tux Paint is starting up and loading plugins, it asks us to provide icons for the 'Magic' tool buttons.
*/
SDL_Surface *example_get_icon(magic_api * api, int which) SDL_Surface *example_get_icon(magic_api * api, int which)
{ {
char fname[1024]; char filename[1024];
// Assemble the filename from the "icon_filenames[]" array into /*
// a full path to a real file. Assemble the filename from the "icon_filenames[]" array into a full path to
// a real file.
// Use "api->data_directory" to figure out where our sounds should be.
// (The "tp-magic-config --dataprefix" command would have told us when
// we installed our plugin and its data.)
//
// We use 'which' (which of our tools Tux Paint is asking about)
// as an index into the array.
snprintf(fname, sizeof(fname), "%s/images/magic/%s.png", Use "api->data_directory" to figure out where our sounds should be. (The
"tp-magic-config --dataprefix" command would have told us when we installed
our plugin and its data.)
We use "which" (which of our tools Tux Paint is asking about) as an index
into the array.
*/
snprintf(filename, sizeof(filename), "%s/images/magic/%s",
api->data_directory, icon_filenames[which]); api->data_directory, icon_filenames[which]);
printf("Trying to load %s icon\n", filename);
// Try to load the image, and return the results to Tux Paint: /* Try to load the image, and return the results to Tux Paint: */
return (IMG_Load(fname)); return (IMG_Load(filename));
} }
// Report our "Magic" tool names /*
// Report our 'Magic' tool names
// When Tux Paint is starting up and loading plugins, it asks us to
// provide names (labels) for the "Magic" tool buttons.
When Tux Paint is starting up and loading plugins, it asks us to provide
names (labels) for the 'Magic' tool buttons.
*/
char *example_get_name(magic_api * api, int which) char *example_get_name(magic_api * api, int which)
{ {
const char *our_name_english; const char *our_name_english;
const char *our_name_localized; const char *our_name_localized;
// Get our name from the "names[]" array. /*
// Get our name from the "tool_names[]" array.
// We use 'which' (which of our tools Tux Paint is asking about)
// as an index into the array.
our_name_english = names[which]; We use 'which' (which of our tools Tux Paint is asking about) as an index
into the array.
*/
our_name_english = tool_names[which];
// Return a localized (aka translated) version of our name, /*
// if possible. Return a localized (aka translated) version of our name, if possible.
//
// We send "gettext()" the English version of the name from our array.
We send "gettext()" the English version of the name from our array.
*/
our_name_localized = gettext(our_name_english); our_name_localized = gettext(our_name_english);
// Finally, duplicate the string into a new section of memory, and /*
// send it to Tux Paint. (Tux Paint keeps track of the string and Finally, duplicate the string into a new section of memory, and send it to
// will free it for us, so we have one less thing to keep track of.) Tux Paint. (Tux Paint keeps track of the string and will free it for us,
so we have one less thing to keep track of.)
*/
return (strdup(our_name_localized)); return (strdup(our_name_localized));
} }
@ -306,9 +313,10 @@ char *example_get_description(magic_api * api, int which, int mode)
int example_requires_colors(magic_api * api, int which) int example_requires_colors(magic_api * api, int which)
{ {
// Both of our tools accept colors, so we're always returning '1' (for 'true') if (which == TOOL_ONE)
return 1;
return 1; else
return 0;
} }
@ -316,8 +324,10 @@ int example_requires_colors(magic_api * api, int which)
int example_modes(magic_api * api, int which) int example_modes(magic_api * api, int which)
{ {
// Both of our tools are painted (neither affect the full-screen), so we're /*
always returning 'MODE_PAINT' Both of our tools are painted (neither affect the full-screen), so we're
always returning 'MODE_PAINT'
*/
return MODE_PAINT; return MODE_PAINT;
} }
@ -347,114 +357,130 @@ void example_shutdown(magic_api * api)
/* Functions that respond to events in Tux Paint: */ /* Functions that respond to events in Tux Paint: */
/* ---------------------------------------------------------------------- */ /* ---------------------------------------------------------------------- */
// Affect the canvas on click: /* Affect the canvas on click: */
void void
example_click(magic_api * api, int which, int mode, example_click(magic_api * api, int which, int mode,
SDL_Surface * canvas, SDL_Surface * snapshot, int x, int y, SDL_Surface * canvas, SDL_Surface * snapshot, int x, int y,
SDL_Rect * update_rect) SDL_Rect * update_rect)
{ {
// In our case, a single click (which is also the start of a drag!) /*
// is identical to what dragging does, but just at one point, rather In our case, a single click (which is also the start of a drag!) is
// than across a line. identical to what dragging does, but just at one point, rather than across
// a line.
// So we 'cheat' here, by calling our draw() function with
// (x,y) for both the beginning and end points of a line. So we 'cheat' here, by calling our "example_draw()" function with (x,y) for
both the beginning and end points of a line.
*/
example_drag(api, which, canvas, snapshot, x, y, x, y, update_rect); example_drag(api, which, canvas, snapshot, x, y, x, y, update_rect);
} }
// Affect the canvas on drag: /* Affect the canvas on drag: */
void void
example_drag(magic_api * api, int which, SDL_Surface * canvas, example_drag(magic_api * api, int which,
SDL_Surface * snapshot, int ox, int oy, int x, int y, SDL_Surface * canvas, SDL_Surface * snapshot,
int old_x, int old_y, int x, int y,
SDL_Rect * update_rect) SDL_Rect * update_rect)
{ {
// Call Tux Paint's "line()" function. /*
// Call Tux Paint's "line()" (line-traversing) function.
// It will calculate a straight line between (ox,ox) and (x,y).
// Every N steps along that line (in this case, N is '1'), it
// will call _our_ function, "example_line_callback()", and send
// the current X,Y coordinates along the line, as well as other
// useful things (which of our "Magic" tools is being used and
// the current and snapshot canvases).
api->line((void *) api, which, canvas, snapshot, ox, oy, x, y, 1, It will calculate a straight line between (old_x,old_y) and (x,y). Every
N steps along that line (in this case, N is '1'), it will call _our_
function, "example_line_callback()", and send the current X,Y
coordinates along the line, as well as other useful things (which of our
'Magic' tools is being used and the current and snapshot canvases).
*/
api->line((void *) api, which, canvas, snapshot,
old_x, old_y, x, y, 1,
example_line_callback); example_line_callback);
/*
If we need to, swap the X and/or Y values, so that the coordinates
(old_x,old_y) is always the top left, and the coordinates (x,y) is
always the bottom right, so the values we put inside "update_rect" make
sense:
*/
// If we need to, swap the X and/or Y values, so that if (old_x > x)
// (ox,oy) is always the top left, and (x,y) is always the bottom right,
// so the values we put inside "update_rect" make sense:
if (ox > x)
{ {
int tmp = ox; int temp = old_x;
ox = x; old_x = x;
x = tmp; x = temp;
} }
if (oy > y) if (old_y > y)
{ {
int tmp = oy; int temp = old_y;
oy = y; old_y = y;
y = tmp; y = temp;
} }
// Fill in the elements of the "update_rect" SDL_Rect structure /*
// that Tux Paint is sharing with us. Fill in the elements of the "update_rect" SDL_Rect structure that Tux
Paint is sharing with us, therefore telling Tux Paint which part of the
canvas has been modified and should be updated.
*/
update_rect->x = ox - 4; update_rect->x = old_x - 4;
update_rect->y = oy - 4; update_rect->y = old_y - 4;
update_rect->w = (x + 4) - update_rect->x; update_rect->w = (x + 4) - update_rect->x;
update_rect->h = (y + 4) - update_rect->h; update_rect->h = (y + 4) - update_rect->y;
/*
Play the appropriate sound effect
// Play the appropriate sound effect We're calculating a value between 0-255 for where the mouse is
// horizontally across the canvas (0 is the left, ~128 is the center, 255
// We're calculating a value between 0-255 for where the mouse is is the right).
// across the canvas (0 is the left, ~128 is the center, 255 is the right).
//
// These are the exact values Tux Paint's "playsound()" wants,
// to determine what speaker to play the sound in.
// (So the sound will pan from speaker to speaker as you drag the
// mouse around the canvas!)
api->playsound(snd_effect[which], (x * 255) / canvas->w, // pan These are the exact values Tux Paint's "playsound()" wants, to determine
255); // distance what speaker to play the sound in. (So the sound will pan from speaker
to speaker as you drag the mouse around the canvas!)
*/
api->playsound(sound_effects[which],
(x * 255) / canvas->w, /* Left/right pan */
255 /* Near/far distance (loudness) */);
} }
// Affect the canvas on release: /* Affect the canvas on release: */
void void
example_release(magic_api * api, int which, example_release(magic_api * api, int which,
SDL_Surface * canvas, SDL_Surface * snapshot, int x, int y, SDL_Surface * canvas, SDL_Surface * snapshot, int x, int y,
SDL_Rect * update_rect) SDL_Rect * update_rect)
{ {
// Neither of our effects do anything special when the mouse is released /*
// from a click or click-and-drag, so there's no code here... Neither of our effects do anything special when the mouse is released
from a click or click-and-drag, so there's no code here...
*/
} }
// Accept colors /*
// Accept colors
// When any of our "Magic" tools are activated by the user,
// if that tool accepts colors, the current color selection is sent to us.
//
// Additionally, if one of our color-accepting tools is active when the
// user changes colors, we'll be informed of that, as well.
//
// The color comes in as RGB values.
When any of our 'Magig' tools are activated by the user, if that tool
accepts colors, the current color selection is sent to us.
Additionally, if one of our color-accepting tools is active when the user
changes their chosen, we'll be informed of that as well.
The color comes in as RGB (red, green, and blue) values from 0 (darkest) to
255 (brightest).
*/
void example_set_color(magic_api * api, Uint8 r, Uint8 g, Uint8 b) void example_set_color(magic_api * api, Uint8 r, Uint8 g, Uint8 b)
{ {
// We simply store the RGB values in the global variables we /*
// declared at the top of this file. We simply store the RGB values in the global variables we declared at
the top of this file.
*/
example_r = r; example_r = r;
example_g = g; example_g = g;
@ -465,114 +491,130 @@ void example_set_color(magic_api * api, Uint8 r, Uint8 g, Uint8 b)
/* The Magic Effect Routines! */ /* The Magic Effect Routines! */
/* ---------------------------------------------------------------------- */ /* ---------------------------------------------------------------------- */
// Our "callback" function /*
// Our 'callback' function
// We do the 'work' in this callback. Our plugin file has just one.
// Some "Magic" tool plugins may have more, depending on the tools they're
// providing. Some have none (since they're not click-and-drag
// painting-style tools).
//
// Our callback function gets called once for every point along a line between
// the mouse's previous and current position, as it's being dragged.
//
// It pays attention to 'which' to determine which of our plugin's tools
// is currently selected.
void example_line_callback(void *ptr, int which, SDL_Surface * canvas, We do the 'work' in this callback. Our plugin file has just one. Some
SDL_Surface * snapshot, int x, int y) 'Magic' tool plugins may have more, depending on the tools they're
providing. Some have none (since they're not click-and-drag painting-style
tools).
Our callback function gets called once for every point along a line between
the mouse's previous and current position, as it's being dragged.
Our callback pays attention to 'which' to determine which of our plugin's
tools is currently selected.
*/
void example_line_callback(void *pointer, int which, SDL_Surface * canvas,
SDL_Surface * snapshot, int x, int y)
{ {
// For technical reasons, we can't accept a pointer to the "magic_api" /*
// struct, like the other functions do. For technical reasons, we can't accept a pointer to the Tux Paint API's
// "magic_api" struct, like the other functions do.
// Instead, we receive a 'generic' pointer (a "void *").
// The line below declares a local "magic_api" pointer variable called "api", Instead, we receive a 'generic' pointer (a "void *"). The line below
// and then assigns it to the value of the 'generic' pointer we received. declares a local "magic_api" pointer variable called "api", and then
// assigns it to the value of the 'generic' pointer we received.
// (The "(magic_api *)" casts the generic pointer into the 'type' of
// pointer we want, a pointer to a "magic_api".) The "(magic_api *)" seen below casts the generic "void *" pointer into
magic_api *api = (magic_api *) ptr; the 'type' of pointer we want, a pointer to a "magic_api" struct.)
*/
magic_api *api = (magic_api *) pointer;
int xx, yy; int xx, yy;
/*
// This function handles both of our tools, so we need to check which This function handles both of our tools, so we need to check which is
// is being used right now. We compare the 'which' argument that being used right now. We compare the 'which' argument that Tux Paint
// Tux Paint sends to us with the values we enumerated above. sends to us with the values we enumerated above.
*/
if (which == TOOL_ONE) if (which == TOOL_ONE)
{ {
// Tool number 1 simply draws a single pixel at the (x,y) location. /*
// It's a 1x1 pixel brush Tool number 1 simply draws a single pixel at the (x,y) location. It acts
as a 1x1 pixel brush.
*/
api->putpixel(canvas, x, y, api->putpixel(canvas, x, y,
SDL_MapRGB(canvas->format, example_r, example_g, SDL_MapRGB(canvas->format,
example_b)); example_r, example_g, example_b));
// We use "SDL_MapRGB()" to convert the RGB value we receive from Tux Paint /*
// for the user's current color selection to a 'Uint32' pixel value We use "SDL_MapRGB()" to convert the RGB value we receive from Tux Paint
// we can send to Tux Paint's "putpixel()" function. for the user's current color selection to a 'Uint32' pixel value we can
send to Tux Paint's "putpixel()" function.
*/
} }
else if (which == TOOL_TWO) else if (which == TOOL_TWO)
{ {
// Tool number 2 copies an 8x8 square of pixels from the opposite side /*
// of the canvas and puts it under the cursor Tool number 2 copies an 8x8 square of pixels from the opposite side of
the canvas and puts it under the cursor.
*/
for (yy = -4; yy < 4; yy++) for (yy = -4; yy < 4; yy++)
{ {
for (xx = -4; xx < 4; xx++) for (xx = -4; xx < 4; xx++)
{ {
api->putpixel(canvas, x + xx, y + yy, api->putpixel(canvas, x + xx, y + yy,
api->getpixel(snapshot, canvas->w - x - xx, api->getpixel(snapshot,
canvas->h - y - yy)); snapshot->w - x - xx,
snapshot->h - y - yy));
// We simply use Tux Paint's "getpixel()" routine to pull pixel /*
// values from the 'snapshot', and then "putpixel()" to draw them Here we have simply use Tux Paint's "getpixel()" routine to pull pixel
// right into the 'canvas'. values from the 'snapshot', and then "putpixel()" to draw them right
into the 'snapshot'.
// Note: putpixel() and getpixel() are safe to use, even if your Note: putpixel() and getpixel() are safe to use, even if your X,Y values
// X,Y values are outside of the SDL surface (e.g., negative, or are outside of the SDL surface (e.g., negative, or greater than the
// greater than the surface's width or height). surface's width and/or height).
*/
} }
} }
} }
} }
// Switch-In event /*
// Switch-In event
// This happens whenever a Magic tool is enabled, either because the
// user just selected it, or they just came back to "Magic" after using
// another tool (e.g., Brush or Text), and this was the most-recently
// selected Magic tool.
//
// (This also applies to momentary tools, like
// Undo and Redo, and image-changing tools such as New and Open.)
//
// It also happens when a Magic tool's mode changes (it first
// receives a 'switchout()', below, for the old mode).
//
// Our example doesn't do anything when we switch to, or away from, our
// Magic tools, so we just do nothing here.
This happens whenever a Magic tool is enabled, either because the user just
selected it, or they just came back to 'Magic' after using another tool
(e.g., Brush or Text), and this was the most-recently selected Magic tool.
(This also applies to momentary tools, like Undo and Redo, and
image-changing tools such as New and Open.)
It also happens when a Magic tool's mode changes (we will first receive a
call to 'example_switchout()', below, for the old mode).
Our example doesn't do anything when we switch to, or away from, our Magic
tools, so we just do nothing here.
*/
void example_switchin(magic_api * api, int which, int mode, void example_switchin(magic_api * api, int which, int mode,
SDL_Surface * canvas) SDL_Surface * canvas)
{ {
} }
// Switch-Out event /*
// Switch-Out event
// This happens whenever a Magic tool is disabled, either because the
// user selected a different Magic tool, or they selected a completely
// different tool (e.g., Brush or Text).
//
// (This also applies to momentary tools, like Undo and Redo, and
// image-changing tools such as New and Open, in which case the
// switchin() function will be called moments later.)
//
// It also happens when a Magic tool's mode changes (it then
// receives a 'switchin()', above, for the new mode).
//
// Our example doesn't do anything when we switch to, or away from, our
// Magic tools, so we just do nothing here.
This happens whenever a Magic tool is disabled, either because the user
selected a different Magic tool, or they selected a completely different
tool (e.g., Brush or Text).
(This also applies to momentary tools, like Undo and Redo, and
image-changing tools such as New and Open.)
(And in that case, our example_switchin() function will be called moments
later.
It also happens when a Magic tool's mode changes (we will then receive a
call to 'example_switchin()', above, for the new mode).
Our example doesn't do anything when we switch to, or away from, our Magic
tools, so we just do nothing here.
*/
void example_switchout(magic_api * api, int which, int mode, void example_switchout(magic_api * api, int which, int mode,
SDL_Surface * canvas) SDL_Surface * canvas)
{ {

432
docs/es_ES.UTF-8/html/tp_magic_example.c
View file

@ -1,7 +1,7 @@
/* tp_magic_example.c /* tp_magic_example.c
An example of a "Magic" tool plugin for Tux Paint An example of a "Magic" tool plugin for Tux Paint
octubre 18, 2022 octubre 19, 2022
*/ */
@ -26,12 +26,12 @@
enum enum
{ {
TOOL_ONE, // Becomes '0' TOOL_ONE, // Becomes '0'
TOOL_ONE, // Becomes '1' TOOL_TWO, // Becomes '1'
NUM_TOOLS // Becomes '2' NUM_TOOLS // Becomes '2'
}; };
/* A list of filenames for sounds and icons to load at startup: */ /* Lists of filenames for sounds and icons to load at startup: */
const char *sound_filenames[NUM_TOOLS] = { const char *sound_filenames[NUM_TOOLS] = {
"tool_one.wav", "tool_one.wav",
@ -61,7 +61,7 @@ const char *tool_names[NUM_TOOLS] = {
/* How to group the tools with other similar tools, within the 'Magic' selector: */ /* How to group the tools with other similar tools, within the 'Magic' selector: */
const int tool_groups[$NUM_TOOLS] = { const int tool_groups[NUM_TOOLS] = {
MAGIC_TYPE_PAINTING, MAGIC_TYPE_PAINTING,
MAGIC_TYPE_DISTORTS MAGIC_TYPE_DISTORTS
}; };
@ -83,7 +83,7 @@ const char *tool_descriptions[NUM_TOOLS] = {
Mix_Chunk *sound_effects[NUM_TOOLS]; Mix_Chunk *sound_effects[NUM_TOOLS];
/* The current color (an "RGB" -- red, green, blue -- value) the user has selected in Tux Paint: */ /* The current color (an "RGB" -- red, green, blue -- value) the user has selected in Tux Paint: */
Uint8 example_r, $example_g, $example_b; Uint8 example_r, example_g, example_b;
/* Our local function prototypes: */ /* Our local function prototypes: */
@ -97,11 +97,11 @@ _before_ them.
*/ */
void example_drag(magic_api * api, int which, SDL_Surface * canvas, void example_drag(magic_api * api, int which, SDL_Surface * canvas,
SDL_Surface * snapshot, int ox, int oy, int x, int y, SDL_Surface * snapshot, int old_x, int old_y, int x, int y,
SDL_Rect * update_rect); SDL_Rect * update_rect);
void example_line_callback(void *pointer, int which, SDL_Surface * canvas, void example_line_callback(void *pointer, int which, SDL_Surface * canvas,
SDL_Surface * snapshot, int x, int y); SDL_Surface * snapshot, int x, int y);
/* Setup Functions: */ /* Setup Functions: */
@ -154,13 +154,14 @@ int example_init(magic_api * api)
Use "api->data_directory" to figure out where our sounds should be. (The Use "api->data_directory" to figure out where our sounds should be. (The
"tp-magic-config --dataprefix" command would have told us when we installed "tp-magic-config --dataprefix" command would have told us when we installed
our plugin and its data.) our plugin and its data.)
*/
snprintf(filename, sizeof(filename), "%s/sounds/magic/%s", api->data_directory, snprintf(filename, sizeof(filename), "%s/sounds/magic/%s", api->data_directory,
sound_filenames[i]); sound_filenames[i]);
printf("Trying to load %s sound file\n", filename); printf("Trying to load %s sound file\n", filename);
// Try to load the file! /* Try to load the file! */
sound_effects[i] = Mix_LoadWAV(filename); sound_effects[i] = Mix_LoadWAV(filename);
} }
@ -168,80 +169,86 @@ int example_init(magic_api * api)
} }
// Report our tool count /*
// Report our tool count
// Tux Paint needs to know how many "Magic" tools we'll be providing.
// Return that number here. (We simply grab the value of "NUM_TOOLS"
// from our 'enum' above!)
//
// When Tux Paint is starting up and loading plugins, it will call
// some of the following setup functions once for each tool we report.
Tux Paint needs to know how many 'Magic' tools we'll be providing. Return
that number here. (We simply grab the value of 'NUM_TOOLS' from our 'enum'
above!)
When Tux Paint is starting up and loading plugins, it will call some of the
following setup functions once for each tool we report.
*/
int example_get_tool_count(magic_api * api) int example_get_tool_count(magic_api * api)
{ {
return (NUM_TOOLS); return (NUM_TOOLS);
} }
// Load icons /*
// Load our icons
// When Tux Paint is starting up and loading plugins, it asks us to
// provide icons for the "Magic" tool buttons.
When Tux Paint is starting up and loading plugins, it asks us to provide icons for the 'Magic' tool buttons.
*/
SDL_Surface *example_get_icon(magic_api * api, int which) SDL_Surface *example_get_icon(magic_api * api, int which)
{ {
char fname[1024]; char filename[1024];
// Assemble the filename from the "icon_filenames[]" array into /*
// a full path to a real file. Assemble the filename from the "icon_filenames[]" array into a full path to
// a real file.
// Use "api->data_directory" to figure out where our sounds should be.
// (The "tp-magic-config --dataprefix" command would have told us when
// we installed our plugin and its data.)
//
// We use 'which' (which of our tools Tux Paint is asking about)
// as an index into the array.
snprintf(fname, sizeof(fname), "%s/images/magic/%s.png", Use "api->data_directory" to figure out where our sounds should be. (The
"tp-magic-config --dataprefix" command would have told us when we installed
our plugin and its data.)
We use "which" (which of our tools Tux Paint is asking about) as an index
into the array.
*/
snprintf(filename, sizeof(filename), "%s/images/magic/%s",
api->data_directory, icon_filenames[which]); api->data_directory, icon_filenames[which]);
printf("Trying to load %s icon\n", filename);
// Try to load the image, and return the results to Tux Paint: /* Try to load the image, and return the results to Tux Paint: */
return (IMG_Load(fname)); return (IMG_Load(filename));
} }
// Report our "Magic" tool names /*
// Report our 'Magic' tool names
// When Tux Paint is starting up and loading plugins, it asks us to
// provide names (labels) for the "Magic" tool buttons.
When Tux Paint is starting up and loading plugins, it asks us to provide
names (labels) for the 'Magic' tool buttons.
*/
char *example_get_name(magic_api * api, int which) char *example_get_name(magic_api * api, int which)
{ {
const char *our_name_english; const char *our_name_english;
const char *our_name_localized; const char *our_name_localized;
// Get our name from the "names[]" array. /*
// Get our name from the "tool_names[]" array.
// We use 'which' (which of our tools Tux Paint is asking about)
// as an index into the array.
our_name_english = names[which]; We use 'which' (which of our tools Tux Paint is asking about) as an index
into the array.
*/
our_name_english = tool_names[which];
// Return a localized (aka translated) version of our name, /*
// if possible. Return a localized (aka translated) version of our name, if possible.
//
// We send "gettext()" the English version of the name from our array.
We send "gettext()" the English version of the name from our array.
*/
our_name_localized = gettext(our_name_english); our_name_localized = gettext(our_name_english);
// Finally, duplicate the string into a new section of memory, and /*
// send it to Tux Paint. (Tux Paint keeps track of the string and Finally, duplicate the string into a new section of memory, and send it to
// will free it for us, so we have one less thing to keep track of.) Tux Paint. (Tux Paint keeps track of the string and will free it for us,
so we have one less thing to keep track of.)
*/
return (strdup(our_name_localized)); return (strdup(our_name_localized));
} }
@ -306,9 +313,10 @@ char *example_get_description(magic_api * api, int which, int mode)
int example_requires_colors(magic_api * api, int which) int example_requires_colors(magic_api * api, int which)
{ {
// Both of our tools accept colors, so we're always returning '1' (for 'true') if (which == TOOL_ONE)
return 1;
return 1; else
return 0;
} }
@ -316,8 +324,10 @@ int example_requires_colors(magic_api * api, int which)
int example_modes(magic_api * api, int which) int example_modes(magic_api * api, int which)
{ {
// Both of our tools are painted (neither affect the full-screen), so we're /*
always returning 'MODE_PAINT' Both of our tools are painted (neither affect the full-screen), so we're
always returning 'MODE_PAINT'
*/
return MODE_PAINT; return MODE_PAINT;
} }
@ -347,114 +357,130 @@ void example_shutdown(magic_api * api)
/* Functions that respond to events in Tux Paint: */ /* Functions that respond to events in Tux Paint: */
/* ---------------------------------------------------------------------- */ /* ---------------------------------------------------------------------- */
// Affect the canvas on click: /* Affect the canvas on click: */
void void
example_click(magic_api * api, int which, int mode, example_click(magic_api * api, int which, int mode,
SDL_Surface * canvas, SDL_Surface * snapshot, int x, int y, SDL_Surface * canvas, SDL_Surface * snapshot, int x, int y,
SDL_Rect * update_rect) SDL_Rect * update_rect)
{ {
// In our case, a single click (which is also the start of a drag!) /*
// is identical to what dragging does, but just at one point, rather In our case, a single click (which is also the start of a drag!) is
// than across a line. identical to what dragging does, but just at one point, rather than across
// a line.
// So we 'cheat' here, by calling our draw() function with
// (x,y) for both the beginning and end points of a line. So we 'cheat' here, by calling our "example_draw()" function with (x,y) for
both the beginning and end points of a line.
*/
example_drag(api, which, canvas, snapshot, x, y, x, y, update_rect); example_drag(api, which, canvas, snapshot, x, y, x, y, update_rect);
} }
// Affect the canvas on drag: /* Affect the canvas on drag: */
void void
example_drag(magic_api * api, int which, SDL_Surface * canvas, example_drag(magic_api * api, int which,
SDL_Surface * snapshot, int ox, int oy, int x, int y, SDL_Surface * canvas, SDL_Surface * snapshot,
int old_x, int old_y, int x, int y,
SDL_Rect * update_rect) SDL_Rect * update_rect)
{ {
// Call Tux Paint's "line()" function. /*
// Call Tux Paint's "line()" (line-traversing) function.
// It will calculate a straight line between (ox,ox) and (x,y).
// Every N steps along that line (in this case, N is '1'), it
// will call _our_ function, "example_line_callback()", and send
// the current X,Y coordinates along the line, as well as other
// useful things (which of our "Magic" tools is being used and
// the current and snapshot canvases).
api->line((void *) api, which, canvas, snapshot, ox, oy, x, y, 1, It will calculate a straight line between (old_x,old_y) and (x,y). Every
N steps along that line (in this case, N is '1'), it will call _our_
function, "example_line_callback()", and send the current X,Y
coordinates along the line, as well as other useful things (which of our
'Magic' tools is being used and the current and snapshot canvases).
*/
api->line((void *) api, which, canvas, snapshot,
old_x, old_y, x, y, 1,
example_line_callback); example_line_callback);
/*
If we need to, swap the X and/or Y values, so that the coordinates
(old_x,old_y) is always the top left, and the coordinates (x,y) is
always the bottom right, so the values we put inside "update_rect" make
sense:
*/
// If we need to, swap the X and/or Y values, so that if (old_x > x)
// (ox,oy) is always the top left, and (x,y) is always the bottom right,
// so the values we put inside "update_rect" make sense:
if (ox > x)
{ {
int tmp = ox; int temp = old_x;
ox = x; old_x = x;
x = tmp; x = temp;
} }
if (oy > y) if (old_y > y)
{ {
int tmp = oy; int temp = old_y;
oy = y; old_y = y;
y = tmp; y = temp;
} }
// Fill in the elements of the "update_rect" SDL_Rect structure /*
// that Tux Paint is sharing with us. Fill in the elements of the "update_rect" SDL_Rect structure that Tux
Paint is sharing with us, therefore telling Tux Paint which part of the
canvas has been modified and should be updated.
*/
update_rect->x = ox - 4; update_rect->x = old_x - 4;
update_rect->y = oy - 4; update_rect->y = old_y - 4;
update_rect->w = (x + 4) - update_rect->x; update_rect->w = (x + 4) - update_rect->x;
update_rect->h = (y + 4) - update_rect->h; update_rect->h = (y + 4) - update_rect->y;
/*
Play the appropriate sound effect
// Play the appropriate sound effect We're calculating a value between 0-255 for where the mouse is
// horizontally across the canvas (0 is the left, ~128 is the center, 255
// We're calculating a value between 0-255 for where the mouse is is the right).
// across the canvas (0 is the left, ~128 is the center, 255 is the right).
//
// These are the exact values Tux Paint's "playsound()" wants,
// to determine what speaker to play the sound in.
// (So the sound will pan from speaker to speaker as you drag the
// mouse around the canvas!)
api->playsound(snd_effect[which], (x * 255) / canvas->w, // pan These are the exact values Tux Paint's "playsound()" wants, to determine
255); // distance what speaker to play the sound in. (So the sound will pan from speaker
to speaker as you drag the mouse around the canvas!)
*/
api->playsound(sound_effects[which],
(x * 255) / canvas->w, /* Left/right pan */
255 /* Near/far distance (loudness) */);
} }
// Affect the canvas on release: /* Affect the canvas on release: */
void void
example_release(magic_api * api, int which, example_release(magic_api * api, int which,
SDL_Surface * canvas, SDL_Surface * snapshot, int x, int y, SDL_Surface * canvas, SDL_Surface * snapshot, int x, int y,
SDL_Rect * update_rect) SDL_Rect * update_rect)
{ {
// Neither of our effects do anything special when the mouse is released /*
// from a click or click-and-drag, so there's no code here... Neither of our effects do anything special when the mouse is released
from a click or click-and-drag, so there's no code here...
*/
} }
// Accept colors /*
// Accept colors
// When any of our "Magic" tools are activated by the user,
// if that tool accepts colors, the current color selection is sent to us.
//
// Additionally, if one of our color-accepting tools is active when the
// user changes colors, we'll be informed of that, as well.
//
// The color comes in as RGB values.
When any of our 'Magig' tools are activated by the user, if that tool
accepts colors, the current color selection is sent to us.
Additionally, if one of our color-accepting tools is active when the user
changes their chosen, we'll be informed of that as well.
The color comes in as RGB (red, green, and blue) values from 0 (darkest) to
255 (brightest).
*/
void example_set_color(magic_api * api, Uint8 r, Uint8 g, Uint8 b) void example_set_color(magic_api * api, Uint8 r, Uint8 g, Uint8 b)
{ {
// We simply store the RGB values in the global variables we /*
// declared at the top of this file. We simply store the RGB values in the global variables we declared at
the top of this file.
*/
example_r = r; example_r = r;
example_g = g; example_g = g;
@ -465,114 +491,130 @@ void example_set_color(magic_api * api, Uint8 r, Uint8 g, Uint8 b)
/* The Magic Effect Routines! */ /* The Magic Effect Routines! */
/* ---------------------------------------------------------------------- */ /* ---------------------------------------------------------------------- */
// Our "callback" function /*
// Our 'callback' function
// We do the 'work' in this callback. Our plugin file has just one.
// Some "Magic" tool plugins may have more, depending on the tools they're
// providing. Some have none (since they're not click-and-drag
// painting-style tools).
//
// Our callback function gets called once for every point along a line between
// the mouse's previous and current position, as it's being dragged.
//
// It pays attention to 'which' to determine which of our plugin's tools
// is currently selected.
void example_line_callback(void *ptr, int which, SDL_Surface * canvas, We do the 'work' in this callback. Our plugin file has just one. Some
SDL_Surface * snapshot, int x, int y) 'Magic' tool plugins may have more, depending on the tools they're
providing. Some have none (since they're not click-and-drag painting-style
tools).
Our callback function gets called once for every point along a line between
the mouse's previous and current position, as it's being dragged.
Our callback pays attention to 'which' to determine which of our plugin's
tools is currently selected.
*/
void example_line_callback(void *pointer, int which, SDL_Surface * canvas,
SDL_Surface * snapshot, int x, int y)
{ {
// For technical reasons, we can't accept a pointer to the "magic_api" /*
// struct, like the other functions do. For technical reasons, we can't accept a pointer to the Tux Paint API's
// "magic_api" struct, like the other functions do.
// Instead, we receive a 'generic' pointer (a "void *").
// The line below declares a local "magic_api" pointer variable called "api", Instead, we receive a 'generic' pointer (a "void *"). The line below
// and then assigns it to the value of the 'generic' pointer we received. declares a local "magic_api" pointer variable called "api", and then
// assigns it to the value of the 'generic' pointer we received.
// (The "(magic_api *)" casts the generic pointer into the 'type' of
// pointer we want, a pointer to a "magic_api".) The "(magic_api *)" seen below casts the generic "void *" pointer into
magic_api *api = (magic_api *) ptr; the 'type' of pointer we want, a pointer to a "magic_api" struct.)
*/
magic_api *api = (magic_api *) pointer;
int xx, yy; int xx, yy;
/*
// This function handles both of our tools, so we need to check which This function handles both of our tools, so we need to check which is
// is being used right now. We compare the 'which' argument that being used right now. We compare the 'which' argument that Tux Paint
// Tux Paint sends to us with the values we enumerated above. sends to us with the values we enumerated above.
*/
if (which == TOOL_ONE) if (which == TOOL_ONE)
{ {
// Tool number 1 simply draws a single pixel at the (x,y) location. /*
// It's a 1x1 pixel brush Tool number 1 simply draws a single pixel at the (x,y) location. It acts
as a 1x1 pixel brush.
*/
api->putpixel(canvas, x, y, api->putpixel(canvas, x, y,
SDL_MapRGB(canvas->format, example_r, example_g, SDL_MapRGB(canvas->format,
example_b)); example_r, example_g, example_b));
// We use "SDL_MapRGB()" to convert the RGB value we receive from Tux Paint /*
// for the user's current color selection to a 'Uint32' pixel value We use "SDL_MapRGB()" to convert the RGB value we receive from Tux Paint
// we can send to Tux Paint's "putpixel()" function. for the user's current color selection to a 'Uint32' pixel value we can
send to Tux Paint's "putpixel()" function.
*/
} }
else if (which == TOOL_TWO) else if (which == TOOL_TWO)
{ {
// Tool number 2 copies an 8x8 square of pixels from the opposite side /*
// of the canvas and puts it under the cursor Tool number 2 copies an 8x8 square of pixels from the opposite side of
the canvas and puts it under the cursor.
*/
for (yy = -4; yy < 4; yy++) for (yy = -4; yy < 4; yy++)
{ {
for (xx = -4; xx < 4; xx++) for (xx = -4; xx < 4; xx++)
{ {
api->putpixel(canvas, x + xx, y + yy, api->putpixel(canvas, x + xx, y + yy,
api->getpixel(snapshot, canvas->w - x - xx, api->getpixel(snapshot,
canvas->h - y - yy)); snapshot->w - x - xx,
snapshot->h - y - yy));
// We simply use Tux Paint's "getpixel()" routine to pull pixel /*
// values from the 'snapshot', and then "putpixel()" to draw them Here we have simply use Tux Paint's "getpixel()" routine to pull pixel
// right into the 'canvas'. values from the 'snapshot', and then "putpixel()" to draw them right
into the 'snapshot'.
// Note: putpixel() and getpixel() are safe to use, even if your Note: putpixel() and getpixel() are safe to use, even if your X,Y values
// X,Y values are outside of the SDL surface (e.g., negative, or are outside of the SDL surface (e.g., negative, or greater than the
// greater than the surface's width or height). surface's width and/or height).
*/
} }
} }
} }
} }
// Switch-In event /*
// Switch-In event
// This happens whenever a Magic tool is enabled, either because the
// user just selected it, or they just came back to "Magic" after using
// another tool (e.g., Brush or Text), and this was the most-recently
// selected Magic tool.
//
// (This also applies to momentary tools, like
// Undo and Redo, and image-changing tools such as New and Open.)
//
// It also happens when a Magic tool's mode changes (it first
// receives a 'switchout()', below, for the old mode).
//
// Our example doesn't do anything when we switch to, or away from, our
// Magic tools, so we just do nothing here.
This happens whenever a Magic tool is enabled, either because the user just
selected it, or they just came back to 'Magic' after using another tool
(e.g., Brush or Text), and this was the most-recently selected Magic tool.
(This also applies to momentary tools, like Undo and Redo, and
image-changing tools such as New and Open.)
It also happens when a Magic tool's mode changes (we will first receive a
call to 'example_switchout()', below, for the old mode).
Our example doesn't do anything when we switch to, or away from, our Magic
tools, so we just do nothing here.
*/
void example_switchin(magic_api * api, int which, int mode, void example_switchin(magic_api * api, int which, int mode,
SDL_Surface * canvas) SDL_Surface * canvas)
{ {
} }
// Switch-Out event /*
// Switch-Out event
// This happens whenever a Magic tool is disabled, either because the
// user selected a different Magic tool, or they selected a completely
// different tool (e.g., Brush or Text).
//
// (This also applies to momentary tools, like Undo and Redo, and
// image-changing tools such as New and Open, in which case the
// switchin() function will be called moments later.)
//
// It also happens when a Magic tool's mode changes (it then
// receives a 'switchin()', above, for the new mode).
//
// Our example doesn't do anything when we switch to, or away from, our
// Magic tools, so we just do nothing here.
This happens whenever a Magic tool is disabled, either because the user
selected a different Magic tool, or they selected a completely different
tool (e.g., Brush or Text).
(This also applies to momentary tools, like Undo and Redo, and
image-changing tools such as New and Open.)
(And in that case, our example_switchin() function will be called moments
later.
It also happens when a Magic tool's mode changes (we will then receive a
call to 'example_switchin()', above, for the new mode).
Our example doesn't do anything when we switch to, or away from, our Magic
tools, so we just do nothing here.
*/
void example_switchout(magic_api * api, int which, int mode, void example_switchout(magic_api * api, int which, int mode,
SDL_Surface * canvas) SDL_Surface * canvas)
{ {

432
docs/es_ES.UTF-8/tp_magic_example.c
View file

@ -1,7 +1,7 @@
/* tp_magic_example.c /* tp_magic_example.c
An example of a "Magic" tool plugin for Tux Paint An example of a "Magic" tool plugin for Tux Paint
octubre 18, 2022 octubre 19, 2022
*/ */
@ -26,12 +26,12 @@
enum enum
{ {
TOOL_ONE, // Becomes '0' TOOL_ONE, // Becomes '0'
TOOL_ONE, // Becomes '1' TOOL_TWO, // Becomes '1'
NUM_TOOLS // Becomes '2' NUM_TOOLS // Becomes '2'
}; };
/* A list of filenames for sounds and icons to load at startup: */ /* Lists of filenames for sounds and icons to load at startup: */
const char *sound_filenames[NUM_TOOLS] = { const char *sound_filenames[NUM_TOOLS] = {
"tool_one.wav", "tool_one.wav",
@ -61,7 +61,7 @@ const char *tool_names[NUM_TOOLS] = {
/* How to group the tools with other similar tools, within the 'Magic' selector: */ /* How to group the tools with other similar tools, within the 'Magic' selector: */
const int tool_groups[$NUM_TOOLS] = { const int tool_groups[NUM_TOOLS] = {
MAGIC_TYPE_PAINTING, MAGIC_TYPE_PAINTING,
MAGIC_TYPE_DISTORTS MAGIC_TYPE_DISTORTS
}; };
@ -83,7 +83,7 @@ const char *tool_descriptions[NUM_TOOLS] = {
Mix_Chunk *sound_effects[NUM_TOOLS]; Mix_Chunk *sound_effects[NUM_TOOLS];
/* The current color (an "RGB" -- red, green, blue -- value) the user has selected in Tux Paint: */ /* The current color (an "RGB" -- red, green, blue -- value) the user has selected in Tux Paint: */
Uint8 example_r, $example_g, $example_b; Uint8 example_r, example_g, example_b;
/* Our local function prototypes: */ /* Our local function prototypes: */
@ -97,11 +97,11 @@ _before_ them.
*/ */
void example_drag(magic_api * api, int which, SDL_Surface * canvas, void example_drag(magic_api * api, int which, SDL_Surface * canvas,
SDL_Surface * snapshot, int ox, int oy, int x, int y, SDL_Surface * snapshot, int old_x, int old_y, int x, int y,
SDL_Rect * update_rect); SDL_Rect * update_rect);
void example_line_callback(void *pointer, int which, SDL_Surface * canvas, void example_line_callback(void *pointer, int which, SDL_Surface * canvas,
SDL_Surface * snapshot, int x, int y); SDL_Surface * snapshot, int x, int y);
/* Setup Functions: */ /* Setup Functions: */
@ -154,13 +154,14 @@ int example_init(magic_api * api)
Use "api->data_directory" to figure out where our sounds should be. (The Use "api->data_directory" to figure out where our sounds should be. (The
"tp-magic-config --dataprefix" command would have told us when we installed "tp-magic-config --dataprefix" command would have told us when we installed
our plugin and its data.) our plugin and its data.)
*/
snprintf(filename, sizeof(filename), "%s/sounds/magic/%s", api->data_directory, snprintf(filename, sizeof(filename), "%s/sounds/magic/%s", api->data_directory,
sound_filenames[i]); sound_filenames[i]);
printf("Trying to load %s sound file\n", filename); printf("Trying to load %s sound file\n", filename);
// Try to load the file! /* Try to load the file! */
sound_effects[i] = Mix_LoadWAV(filename); sound_effects[i] = Mix_LoadWAV(filename);
} }
@ -168,80 +169,86 @@ int example_init(magic_api * api)
} }
// Report our tool count /*
// Report our tool count
// Tux Paint needs to know how many "Magic" tools we'll be providing.
// Return that number here. (We simply grab the value of "NUM_TOOLS"
// from our 'enum' above!)
//
// When Tux Paint is starting up and loading plugins, it will call
// some of the following setup functions once for each tool we report.
Tux Paint needs to know how many 'Magic' tools we'll be providing. Return
that number here. (We simply grab the value of 'NUM_TOOLS' from our 'enum'
above!)
When Tux Paint is starting up and loading plugins, it will call some of the
following setup functions once for each tool we report.
*/
int example_get_tool_count(magic_api * api) int example_get_tool_count(magic_api * api)
{ {
return (NUM_TOOLS); return (NUM_TOOLS);
} }
// Load icons /*
// Load our icons
// When Tux Paint is starting up and loading plugins, it asks us to
// provide icons for the "Magic" tool buttons.
When Tux Paint is starting up and loading plugins, it asks us to provide icons for the 'Magic' tool buttons.
*/
SDL_Surface *example_get_icon(magic_api * api, int which) SDL_Surface *example_get_icon(magic_api * api, int which)
{ {
char fname[1024]; char filename[1024];
// Assemble the filename from the "icon_filenames[]" array into /*
// a full path to a real file. Assemble the filename from the "icon_filenames[]" array into a full path to
// a real file.
// Use "api->data_directory" to figure out where our sounds should be.
// (The "tp-magic-config --dataprefix" command would have told us when
// we installed our plugin and its data.)
//
// We use 'which' (which of our tools Tux Paint is asking about)
// as an index into the array.
snprintf(fname, sizeof(fname), "%s/images/magic/%s.png", Use "api->data_directory" to figure out where our sounds should be. (The
"tp-magic-config --dataprefix" command would have told us when we installed
our plugin and its data.)
We use "which" (which of our tools Tux Paint is asking about) as an index
into the array.
*/
snprintf(filename, sizeof(filename), "%s/images/magic/%s",
api->data_directory, icon_filenames[which]); api->data_directory, icon_filenames[which]);
printf("Trying to load %s icon\n", filename);
// Try to load the image, and return the results to Tux Paint: /* Try to load the image, and return the results to Tux Paint: */
return (IMG_Load(fname)); return (IMG_Load(filename));
} }
// Report our "Magic" tool names /*
// Report our 'Magic' tool names
// When Tux Paint is starting up and loading plugins, it asks us to
// provide names (labels) for the "Magic" tool buttons.
When Tux Paint is starting up and loading plugins, it asks us to provide
names (labels) for the 'Magic' tool buttons.
*/
char *example_get_name(magic_api * api, int which) char *example_get_name(magic_api * api, int which)
{ {
const char *our_name_english; const char *our_name_english;
const char *our_name_localized; const char *our_name_localized;
// Get our name from the "names[]" array. /*
// Get our name from the "tool_names[]" array.
// We use 'which' (which of our tools Tux Paint is asking about)
// as an index into the array.
our_name_english = names[which]; We use 'which' (which of our tools Tux Paint is asking about) as an index
into the array.
*/
our_name_english = tool_names[which];
// Return a localized (aka translated) version of our name, /*
// if possible. Return a localized (aka translated) version of our name, if possible.
//
// We send "gettext()" the English version of the name from our array.
We send "gettext()" the English version of the name from our array.
*/
our_name_localized = gettext(our_name_english); our_name_localized = gettext(our_name_english);
// Finally, duplicate the string into a new section of memory, and /*
// send it to Tux Paint. (Tux Paint keeps track of the string and Finally, duplicate the string into a new section of memory, and send it to
// will free it for us, so we have one less thing to keep track of.) Tux Paint. (Tux Paint keeps track of the string and will free it for us,
so we have one less thing to keep track of.)
*/
return (strdup(our_name_localized)); return (strdup(our_name_localized));
} }
@ -306,9 +313,10 @@ char *example_get_description(magic_api * api, int which, int mode)
int example_requires_colors(magic_api * api, int which) int example_requires_colors(magic_api * api, int which)
{ {
// Both of our tools accept colors, so we're always returning '1' (for 'true') if (which == TOOL_ONE)
return 1;
return 1; else
return 0;
} }
@ -316,8 +324,10 @@ int example_requires_colors(magic_api * api, int which)
int example_modes(magic_api * api, int which) int example_modes(magic_api * api, int which)
{ {
// Both of our tools are painted (neither affect the full-screen), so we're /*
always returning 'MODE_PAINT' Both of our tools are painted (neither affect the full-screen), so we're
always returning 'MODE_PAINT'
*/
return MODE_PAINT; return MODE_PAINT;
} }
@ -347,114 +357,130 @@ void example_shutdown(magic_api * api)
/* Functions that respond to events in Tux Paint: */ /* Functions that respond to events in Tux Paint: */
/* ---------------------------------------------------------------------- */ /* ---------------------------------------------------------------------- */
// Affect the canvas on click: /* Affect the canvas on click: */
void void
example_click(magic_api * api, int which, int mode, example_click(magic_api * api, int which, int mode,
SDL_Surface * canvas, SDL_Surface * snapshot, int x, int y, SDL_Surface * canvas, SDL_Surface * snapshot, int x, int y,
SDL_Rect * update_rect) SDL_Rect * update_rect)
{ {
// In our case, a single click (which is also the start of a drag!) /*
// is identical to what dragging does, but just at one point, rather In our case, a single click (which is also the start of a drag!) is
// than across a line. identical to what dragging does, but just at one point, rather than across
// a line.
// So we 'cheat' here, by calling our draw() function with
// (x,y) for both the beginning and end points of a line. So we 'cheat' here, by calling our "example_draw()" function with (x,y) for
both the beginning and end points of a line.
*/
example_drag(api, which, canvas, snapshot, x, y, x, y, update_rect); example_drag(api, which, canvas, snapshot, x, y, x, y, update_rect);
} }
// Affect the canvas on drag: /* Affect the canvas on drag: */
void void
example_drag(magic_api * api, int which, SDL_Surface * canvas, example_drag(magic_api * api, int which,
SDL_Surface * snapshot, int ox, int oy, int x, int y, SDL_Surface * canvas, SDL_Surface * snapshot,
int old_x, int old_y, int x, int y,
SDL_Rect * update_rect) SDL_Rect * update_rect)
{ {
// Call Tux Paint's "line()" function. /*
// Call Tux Paint's "line()" (line-traversing) function.
// It will calculate a straight line between (ox,ox) and (x,y).
// Every N steps along that line (in this case, N is '1'), it
// will call _our_ function, "example_line_callback()", and send
// the current X,Y coordinates along the line, as well as other
// useful things (which of our "Magic" tools is being used and
// the current and snapshot canvases).
api->line((void *) api, which, canvas, snapshot, ox, oy, x, y, 1, It will calculate a straight line between (old_x,old_y) and (x,y). Every
N steps along that line (in this case, N is '1'), it will call _our_
function, "example_line_callback()", and send the current X,Y
coordinates along the line, as well as other useful things (which of our
'Magic' tools is being used and the current and snapshot canvases).
*/
api->line((void *) api, which, canvas, snapshot,
old_x, old_y, x, y, 1,
example_line_callback); example_line_callback);
/*
If we need to, swap the X and/or Y values, so that the coordinates
(old_x,old_y) is always the top left, and the coordinates (x,y) is
always the bottom right, so the values we put inside "update_rect" make
sense:
*/
// If we need to, swap the X and/or Y values, so that if (old_x > x)
// (ox,oy) is always the top left, and (x,y) is always the bottom right,
// so the values we put inside "update_rect" make sense:
if (ox > x)
{ {
int tmp = ox; int temp = old_x;
ox = x; old_x = x;
x = tmp; x = temp;
} }
if (oy > y) if (old_y > y)
{ {
int tmp = oy; int temp = old_y;
oy = y; old_y = y;
y = tmp; y = temp;
} }
// Fill in the elements of the "update_rect" SDL_Rect structure /*
// that Tux Paint is sharing with us. Fill in the elements of the "update_rect" SDL_Rect structure that Tux
Paint is sharing with us, therefore telling Tux Paint which part of the
canvas has been modified and should be updated.
*/
update_rect->x = ox - 4; update_rect->x = old_x - 4;
update_rect->y = oy - 4; update_rect->y = old_y - 4;
update_rect->w = (x + 4) - update_rect->x; update_rect->w = (x + 4) - update_rect->x;
update_rect->h = (y + 4) - update_rect->h; update_rect->h = (y + 4) - update_rect->y;
/*
Play the appropriate sound effect
// Play the appropriate sound effect We're calculating a value between 0-255 for where the mouse is
// horizontally across the canvas (0 is the left, ~128 is the center, 255
// We're calculating a value between 0-255 for where the mouse is is the right).
// across the canvas (0 is the left, ~128 is the center, 255 is the right).
//
// These are the exact values Tux Paint's "playsound()" wants,
// to determine what speaker to play the sound in.
// (So the sound will pan from speaker to speaker as you drag the
// mouse around the canvas!)
api->playsound(snd_effect[which], (x * 255) / canvas->w, // pan These are the exact values Tux Paint's "playsound()" wants, to determine
255); // distance what speaker to play the sound in. (So the sound will pan from speaker
to speaker as you drag the mouse around the canvas!)
*/
api->playsound(sound_effects[which],
(x * 255) / canvas->w, /* Left/right pan */
255 /* Near/far distance (loudness) */);
} }
// Affect the canvas on release: /* Affect the canvas on release: */
void void
example_release(magic_api * api, int which, example_release(magic_api * api, int which,
SDL_Surface * canvas, SDL_Surface * snapshot, int x, int y, SDL_Surface * canvas, SDL_Surface * snapshot, int x, int y,
SDL_Rect * update_rect) SDL_Rect * update_rect)
{ {
// Neither of our effects do anything special when the mouse is released /*
// from a click or click-and-drag, so there's no code here... Neither of our effects do anything special when the mouse is released
from a click or click-and-drag, so there's no code here...
*/
} }
// Accept colors /*
// Accept colors
// When any of our "Magic" tools are activated by the user,
// if that tool accepts colors, the current color selection is sent to us.
//
// Additionally, if one of our color-accepting tools is active when the
// user changes colors, we'll be informed of that, as well.
//
// The color comes in as RGB values.
When any of our 'Magig' tools are activated by the user, if that tool
accepts colors, the current color selection is sent to us.
Additionally, if one of our color-accepting tools is active when the user
changes their chosen, we'll be informed of that as well.
The color comes in as RGB (red, green, and blue) values from 0 (darkest) to
255 (brightest).
*/
void example_set_color(magic_api * api, Uint8 r, Uint8 g, Uint8 b) void example_set_color(magic_api * api, Uint8 r, Uint8 g, Uint8 b)
{ {
// We simply store the RGB values in the global variables we /*
// declared at the top of this file. We simply store the RGB values in the global variables we declared at
the top of this file.
*/
example_r = r; example_r = r;
example_g = g; example_g = g;
@ -465,114 +491,130 @@ void example_set_color(magic_api * api, Uint8 r, Uint8 g, Uint8 b)
/* The Magic Effect Routines! */ /* The Magic Effect Routines! */
/* ---------------------------------------------------------------------- */ /* ---------------------------------------------------------------------- */
// Our "callback" function /*
// Our 'callback' function
// We do the 'work' in this callback. Our plugin file has just one.
// Some "Magic" tool plugins may have more, depending on the tools they're
// providing. Some have none (since they're not click-and-drag
// painting-style tools).
//
// Our callback function gets called once for every point along a line between
// the mouse's previous and current position, as it's being dragged.
//
// It pays attention to 'which' to determine which of our plugin's tools
// is currently selected.
void example_line_callback(void *ptr, int which, SDL_Surface * canvas, We do the 'work' in this callback. Our plugin file has just one. Some
SDL_Surface * snapshot, int x, int y) 'Magic' tool plugins may have more, depending on the tools they're
providing. Some have none (since they're not click-and-drag painting-style
tools).
Our callback function gets called once for every point along a line between
the mouse's previous and current position, as it's being dragged.
Our callback pays attention to 'which' to determine which of our plugin's
tools is currently selected.
*/
void example_line_callback(void *pointer, int which, SDL_Surface * canvas,
SDL_Surface * snapshot, int x, int y)
{ {
// For technical reasons, we can't accept a pointer to the "magic_api" /*
// struct, like the other functions do. For technical reasons, we can't accept a pointer to the Tux Paint API's
// "magic_api" struct, like the other functions do.
// Instead, we receive a 'generic' pointer (a "void *").
// The line below declares a local "magic_api" pointer variable called "api", Instead, we receive a 'generic' pointer (a "void *"). The line below
// and then assigns it to the value of the 'generic' pointer we received. declares a local "magic_api" pointer variable called "api", and then
// assigns it to the value of the 'generic' pointer we received.
// (The "(magic_api *)" casts the generic pointer into the 'type' of
// pointer we want, a pointer to a "magic_api".) The "(magic_api *)" seen below casts the generic "void *" pointer into
magic_api *api = (magic_api *) ptr; the 'type' of pointer we want, a pointer to a "magic_api" struct.)
*/
magic_api *api = (magic_api *) pointer;
int xx, yy; int xx, yy;
/*
// This function handles both of our tools, so we need to check which This function handles both of our tools, so we need to check which is
// is being used right now. We compare the 'which' argument that being used right now. We compare the 'which' argument that Tux Paint
// Tux Paint sends to us with the values we enumerated above. sends to us with the values we enumerated above.
*/
if (which == TOOL_ONE) if (which == TOOL_ONE)
{ {
// Tool number 1 simply draws a single pixel at the (x,y) location. /*
// It's a 1x1 pixel brush Tool number 1 simply draws a single pixel at the (x,y) location. It acts
as a 1x1 pixel brush.
*/
api->putpixel(canvas, x, y, api->putpixel(canvas, x, y,
SDL_MapRGB(canvas->format, example_r, example_g, SDL_MapRGB(canvas->format,
example_b)); example_r, example_g, example_b));
// We use "SDL_MapRGB()" to convert the RGB value we receive from Tux Paint /*
// for the user's current color selection to a 'Uint32' pixel value We use "SDL_MapRGB()" to convert the RGB value we receive from Tux Paint
// we can send to Tux Paint's "putpixel()" function. for the user's current color selection to a 'Uint32' pixel value we can
send to Tux Paint's "putpixel()" function.
*/
} }
else if (which == TOOL_TWO) else if (which == TOOL_TWO)
{ {
// Tool number 2 copies an 8x8 square of pixels from the opposite side /*
// of the canvas and puts it under the cursor Tool number 2 copies an 8x8 square of pixels from the opposite side of
the canvas and puts it under the cursor.
*/
for (yy = -4; yy < 4; yy++) for (yy = -4; yy < 4; yy++)
{ {
for (xx = -4; xx < 4; xx++) for (xx = -4; xx < 4; xx++)
{ {
api->putpixel(canvas, x + xx, y + yy, api->putpixel(canvas, x + xx, y + yy,
api->getpixel(snapshot, canvas->w - x - xx, api->getpixel(snapshot,
canvas->h - y - yy)); snapshot->w - x - xx,
snapshot->h - y - yy));
// We simply use Tux Paint's "getpixel()" routine to pull pixel /*
// values from the 'snapshot', and then "putpixel()" to draw them Here we have simply use Tux Paint's "getpixel()" routine to pull pixel
// right into the 'canvas'. values from the 'snapshot', and then "putpixel()" to draw them right
into the 'snapshot'.
// Note: putpixel() and getpixel() are safe to use, even if your Note: putpixel() and getpixel() are safe to use, even if your X,Y values
// X,Y values are outside of the SDL surface (e.g., negative, or are outside of the SDL surface (e.g., negative, or greater than the
// greater than the surface's width or height). surface's width and/or height).
*/
} }
} }
} }
} }
// Switch-In event /*
// Switch-In event
// This happens whenever a Magic tool is enabled, either because the
// user just selected it, or they just came back to "Magic" after using
// another tool (e.g., Brush or Text), and this was the most-recently
// selected Magic tool.
//
// (This also applies to momentary tools, like
// Undo and Redo, and image-changing tools such as New and Open.)
//
// It also happens when a Magic tool's mode changes (it first
// receives a 'switchout()', below, for the old mode).
//
// Our example doesn't do anything when we switch to, or away from, our
// Magic tools, so we just do nothing here.
This happens whenever a Magic tool is enabled, either because the user just
selected it, or they just came back to 'Magic' after using another tool
(e.g., Brush or Text), and this was the most-recently selected Magic tool.
(This also applies to momentary tools, like Undo and Redo, and
image-changing tools such as New and Open.)
It also happens when a Magic tool's mode changes (we will first receive a
call to 'example_switchout()', below, for the old mode).
Our example doesn't do anything when we switch to, or away from, our Magic
tools, so we just do nothing here.
*/
void example_switchin(magic_api * api, int which, int mode, void example_switchin(magic_api * api, int which, int mode,
SDL_Surface * canvas) SDL_Surface * canvas)
{ {
} }
// Switch-Out event /*
// Switch-Out event
// This happens whenever a Magic tool is disabled, either because the
// user selected a different Magic tool, or they selected a completely
// different tool (e.g., Brush or Text).
//
// (This also applies to momentary tools, like Undo and Redo, and
// image-changing tools such as New and Open, in which case the
// switchin() function will be called moments later.)
//
// It also happens when a Magic tool's mode changes (it then
// receives a 'switchin()', above, for the new mode).
//
// Our example doesn't do anything when we switch to, or away from, our
// Magic tools, so we just do nothing here.
This happens whenever a Magic tool is disabled, either because the user
selected a different Magic tool, or they selected a completely different
tool (e.g., Brush or Text).
(This also applies to momentary tools, like Undo and Redo, and
image-changing tools such as New and Open.)
(And in that case, our example_switchin() function will be called moments
later.
It also happens when a Magic tool's mode changes (we will then receive a
call to 'example_switchin()', above, for the new mode).
Our example doesn't do anything when we switch to, or away from, our Magic
tools, so we just do nothing here.
*/
void example_switchout(magic_api * api, int which, int mode, void example_switchout(magic_api * api, int which, int mode,
SDL_Surface * canvas) SDL_Surface * canvas)
{ {

432
docs/fr_FR.UTF-8/html/tp_magic_example.c
View file

@ -1,7 +1,7 @@
/* tp_magic_example.c /* tp_magic_example.c
An example of a "Magic" tool plugin for Tux Paint An example of a "Magic" tool plugin for Tux Paint
octobre 18, 2022 octobre 19, 2022
*/ */
@ -26,12 +26,12 @@
enum enum
{ {
TOOL_ONE, // Becomes '0' TOOL_ONE, // Becomes '0'
TOOL_ONE, // Becomes '1' TOOL_TWO, // Becomes '1'
NUM_TOOLS // Becomes '2' NUM_TOOLS // Becomes '2'
}; };
/* A list of filenames for sounds and icons to load at startup: */ /* Lists of filenames for sounds and icons to load at startup: */
const char *sound_filenames[NUM_TOOLS] = { const char *sound_filenames[NUM_TOOLS] = {
"tool_one.wav", "tool_one.wav",
@ -61,7 +61,7 @@ const char *tool_names[NUM_TOOLS] = {
/* How to group the tools with other similar tools, within the 'Magic' selector: */ /* How to group the tools with other similar tools, within the 'Magic' selector: */
const int tool_groups[$NUM_TOOLS] = { const int tool_groups[NUM_TOOLS] = {
MAGIC_TYPE_PAINTING, MAGIC_TYPE_PAINTING,
MAGIC_TYPE_DISTORTS MAGIC_TYPE_DISTORTS
}; };
@ -83,7 +83,7 @@ const char *tool_descriptions[NUM_TOOLS] = {
Mix_Chunk *sound_effects[NUM_TOOLS]; Mix_Chunk *sound_effects[NUM_TOOLS];
/* The current color (an "RGB" -- red, green, blue -- value) the user has selected in Tux Paint: */ /* The current color (an "RGB" -- red, green, blue -- value) the user has selected in Tux Paint: */
Uint8 example_r, $example_g, $example_b; Uint8 example_r, example_g, example_b;
/* Our local function prototypes: */ /* Our local function prototypes: */
@ -97,11 +97,11 @@ _before_ them.
*/ */
void example_drag(magic_api * api, int which, SDL_Surface * canvas, void example_drag(magic_api * api, int which, SDL_Surface * canvas,
SDL_Surface * snapshot, int ox, int oy, int x, int y, SDL_Surface * snapshot, int old_x, int old_y, int x, int y,
SDL_Rect * update_rect); SDL_Rect * update_rect);
void example_line_callback(void *pointer, int which, SDL_Surface * canvas, void example_line_callback(void *pointer, int which, SDL_Surface * canvas,
SDL_Surface * snapshot, int x, int y); SDL_Surface * snapshot, int x, int y);
/* Setup Functions: */ /* Setup Functions: */
@ -154,13 +154,14 @@ int example_init(magic_api * api)
Use "api->data_directory" to figure out where our sounds should be. (The Use "api->data_directory" to figure out where our sounds should be. (The
"tp-magic-config --dataprefix" command would have told us when we installed "tp-magic-config --dataprefix" command would have told us when we installed
our plugin and its data.) our plugin and its data.)
*/
snprintf(filename, sizeof(filename), "%s/sounds/magic/%s", api->data_directory, snprintf(filename, sizeof(filename), "%s/sounds/magic/%s", api->data_directory,
sound_filenames[i]); sound_filenames[i]);
printf("Trying to load %s sound file\n", filename); printf("Trying to load %s sound file\n", filename);
// Try to load the file! /* Try to load the file! */
sound_effects[i] = Mix_LoadWAV(filename); sound_effects[i] = Mix_LoadWAV(filename);
} }
@ -168,80 +169,86 @@ int example_init(magic_api * api)
} }
// Report our tool count /*
// Report our tool count
// Tux Paint needs to know how many "Magic" tools we'll be providing.
// Return that number here. (We simply grab the value of "NUM_TOOLS"
// from our 'enum' above!)
//
// When Tux Paint is starting up and loading plugins, it will call
// some of the following setup functions once for each tool we report.
Tux Paint needs to know how many 'Magic' tools we'll be providing. Return
that number here. (We simply grab the value of 'NUM_TOOLS' from our 'enum'
above!)
When Tux Paint is starting up and loading plugins, it will call some of the
following setup functions once for each tool we report.
*/
int example_get_tool_count(magic_api * api) int example_get_tool_count(magic_api * api)
{ {
return (NUM_TOOLS); return (NUM_TOOLS);
} }
// Load icons /*
// Load our icons
// When Tux Paint is starting up and loading plugins, it asks us to
// provide icons for the "Magic" tool buttons.
When Tux Paint is starting up and loading plugins, it asks us to provide icons for the 'Magic' tool buttons.
*/
SDL_Surface *example_get_icon(magic_api * api, int which) SDL_Surface *example_get_icon(magic_api * api, int which)
{ {
char fname[1024]; char filename[1024];
// Assemble the filename from the "icon_filenames[]" array into /*
// a full path to a real file. Assemble the filename from the "icon_filenames[]" array into a full path to
// a real file.
// Use "api->data_directory" to figure out where our sounds should be.
// (The "tp-magic-config --dataprefix" command would have told us when
// we installed our plugin and its data.)
//
// We use 'which' (which of our tools Tux Paint is asking about)
// as an index into the array.
snprintf(fname, sizeof(fname), "%s/images/magic/%s.png", Use "api->data_directory" to figure out where our sounds should be. (The
"tp-magic-config --dataprefix" command would have told us when we installed
our plugin and its data.)
We use "which" (which of our tools Tux Paint is asking about) as an index
into the array.
*/
snprintf(filename, sizeof(filename), "%s/images/magic/%s",
api->data_directory, icon_filenames[which]); api->data_directory, icon_filenames[which]);
printf("Trying to load %s icon\n", filename);
// Try to load the image, and return the results to Tux Paint: /* Try to load the image, and return the results to Tux Paint: */
return (IMG_Load(fname)); return (IMG_Load(filename));
} }
// Report our "Magic" tool names /*
// Report our 'Magic' tool names
// When Tux Paint is starting up and loading plugins, it asks us to
// provide names (labels) for the "Magic" tool buttons.
When Tux Paint is starting up and loading plugins, it asks us to provide
names (labels) for the 'Magic' tool buttons.
*/
char *example_get_name(magic_api * api, int which) char *example_get_name(magic_api * api, int which)
{ {
const char *our_name_english; const char *our_name_english;
const char *our_name_localized; const char *our_name_localized;
// Get our name from the "names[]" array. /*
// Get our name from the "tool_names[]" array.
// We use 'which' (which of our tools Tux Paint is asking about)
// as an index into the array.
our_name_english = names[which]; We use 'which' (which of our tools Tux Paint is asking about) as an index
into the array.
*/
our_name_english = tool_names[which];
// Return a localized (aka translated) version of our name, /*
// if possible. Return a localized (aka translated) version of our name, if possible.
//
// We send "gettext()" the English version of the name from our array.
We send "gettext()" the English version of the name from our array.
*/
our_name_localized = gettext(our_name_english); our_name_localized = gettext(our_name_english);
// Finally, duplicate the string into a new section of memory, and /*
// send it to Tux Paint. (Tux Paint keeps track of the string and Finally, duplicate the string into a new section of memory, and send it to
// will free it for us, so we have one less thing to keep track of.) Tux Paint. (Tux Paint keeps track of the string and will free it for us,
so we have one less thing to keep track of.)
*/
return (strdup(our_name_localized)); return (strdup(our_name_localized));
} }
@ -306,9 +313,10 @@ char *example_get_description(magic_api * api, int which, int mode)
int example_requires_colors(magic_api * api, int which) int example_requires_colors(magic_api * api, int which)
{ {
// Both of our tools accept colors, so we're always returning '1' (for 'true') if (which == TOOL_ONE)
return 1;
return 1; else
return 0;
} }
@ -316,8 +324,10 @@ int example_requires_colors(magic_api * api, int which)
int example_modes(magic_api * api, int which) int example_modes(magic_api * api, int which)
{ {
// Both of our tools are painted (neither affect the full-screen), so we're /*
always returning 'MODE_PAINT' Both of our tools are painted (neither affect the full-screen), so we're
always returning 'MODE_PAINT'
*/
return MODE_PAINT; return MODE_PAINT;
} }
@ -347,114 +357,130 @@ void example_shutdown(magic_api * api)
/* Functions that respond to events in Tux Paint: */ /* Functions that respond to events in Tux Paint: */
/* ---------------------------------------------------------------------- */ /* ---------------------------------------------------------------------- */
// Affect the canvas on click: /* Affect the canvas on click: */
void void
example_click(magic_api * api, int which, int mode, example_click(magic_api * api, int which, int mode,
SDL_Surface * canvas, SDL_Surface * snapshot, int x, int y, SDL_Surface * canvas, SDL_Surface * snapshot, int x, int y,
SDL_Rect * update_rect) SDL_Rect * update_rect)
{ {
// In our case, a single click (which is also the start of a drag!) /*
// is identical to what dragging does, but just at one point, rather In our case, a single click (which is also the start of a drag!) is
// than across a line. identical to what dragging does, but just at one point, rather than across
// a line.
// So we 'cheat' here, by calling our draw() function with
// (x,y) for both the beginning and end points of a line. So we 'cheat' here, by calling our "example_draw()" function with (x,y) for
both the beginning and end points of a line.
*/
example_drag(api, which, canvas, snapshot, x, y, x, y, update_rect); example_drag(api, which, canvas, snapshot, x, y, x, y, update_rect);
} }
// Affect the canvas on drag: /* Affect the canvas on drag: */
void void
example_drag(magic_api * api, int which, SDL_Surface * canvas, example_drag(magic_api * api, int which,
SDL_Surface * snapshot, int ox, int oy, int x, int y, SDL_Surface * canvas, SDL_Surface * snapshot,
int old_x, int old_y, int x, int y,
SDL_Rect * update_rect) SDL_Rect * update_rect)
{ {
// Call Tux Paint's "line()" function. /*
// Call Tux Paint's "line()" (line-traversing) function.
// It will calculate a straight line between (ox,ox) and (x,y).
// Every N steps along that line (in this case, N is '1'), it
// will call _our_ function, "example_line_callback()", and send
// the current X,Y coordinates along the line, as well as other
// useful things (which of our "Magic" tools is being used and
// the current and snapshot canvases).
api->line((void *) api, which, canvas, snapshot, ox, oy, x, y, 1, It will calculate a straight line between (old_x,old_y) and (x,y). Every
N steps along that line (in this case, N is '1'), it will call _our_
function, "example_line_callback()", and send the current X,Y
coordinates along the line, as well as other useful things (which of our
'Magic' tools is being used and the current and snapshot canvases).
*/
api->line((void *) api, which, canvas, snapshot,
old_x, old_y, x, y, 1,
example_line_callback); example_line_callback);
/*
If we need to, swap the X and/or Y values, so that the coordinates
(old_x,old_y) is always the top left, and the coordinates (x,y) is
always the bottom right, so the values we put inside "update_rect" make
sense:
*/
// If we need to, swap the X and/or Y values, so that if (old_x > x)
// (ox,oy) is always the top left, and (x,y) is always the bottom right,
// so the values we put inside "update_rect" make sense:
if (ox > x)
{ {
int tmp = ox; int temp = old_x;
ox = x; old_x = x;
x = tmp; x = temp;
} }
if (oy > y) if (old_y > y)
{ {
int tmp = oy; int temp = old_y;
oy = y; old_y = y;
y = tmp; y = temp;
} }
// Fill in the elements of the "update_rect" SDL_Rect structure /*
// that Tux Paint is sharing with us. Fill in the elements of the "update_rect" SDL_Rect structure that Tux
Paint is sharing with us, therefore telling Tux Paint which part of the
canvas has been modified and should be updated.
*/
update_rect->x = ox - 4; update_rect->x = old_x - 4;
update_rect->y = oy - 4; update_rect->y = old_y - 4;
update_rect->w = (x + 4) - update_rect->x; update_rect->w = (x + 4) - update_rect->x;
update_rect->h = (y + 4) - update_rect->h; update_rect->h = (y + 4) - update_rect->y;
/*
Play the appropriate sound effect
// Play the appropriate sound effect We're calculating a value between 0-255 for where the mouse is
// horizontally across the canvas (0 is the left, ~128 is the center, 255
// We're calculating a value between 0-255 for where the mouse is is the right).
// across the canvas (0 is the left, ~128 is the center, 255 is the right).
//
// These are the exact values Tux Paint's "playsound()" wants,
// to determine what speaker to play the sound in.
// (So the sound will pan from speaker to speaker as you drag the
// mouse around the canvas!)
api->playsound(snd_effect[which], (x * 255) / canvas->w, // pan These are the exact values Tux Paint's "playsound()" wants, to determine
255); // distance what speaker to play the sound in. (So the sound will pan from speaker
to speaker as you drag the mouse around the canvas!)
*/
api->playsound(sound_effects[which],
(x * 255) / canvas->w, /* Left/right pan */
255 /* Near/far distance (loudness) */);
} }
// Affect the canvas on release: /* Affect the canvas on release: */
void void
example_release(magic_api * api, int which, example_release(magic_api * api, int which,
SDL_Surface * canvas, SDL_Surface * snapshot, int x, int y, SDL_Surface * canvas, SDL_Surface * snapshot, int x, int y,
SDL_Rect * update_rect) SDL_Rect * update_rect)
{ {
// Neither of our effects do anything special when the mouse is released /*
// from a click or click-and-drag, so there's no code here... Neither of our effects do anything special when the mouse is released
from a click or click-and-drag, so there's no code here...
*/
} }
// Accept colors /*
// Accept colors
// When any of our "Magic" tools are activated by the user,
// if that tool accepts colors, the current color selection is sent to us.
//
// Additionally, if one of our color-accepting tools is active when the
// user changes colors, we'll be informed of that, as well.
//
// The color comes in as RGB values.
When any of our 'Magig' tools are activated by the user, if that tool
accepts colors, the current color selection is sent to us.
Additionally, if one of our color-accepting tools is active when the user
changes their chosen, we'll be informed of that as well.
The color comes in as RGB (red, green, and blue) values from 0 (darkest) to
255 (brightest).
*/
void example_set_color(magic_api * api, Uint8 r, Uint8 g, Uint8 b) void example_set_color(magic_api * api, Uint8 r, Uint8 g, Uint8 b)
{ {
// We simply store the RGB values in the global variables we /*
// declared at the top of this file. We simply store the RGB values in the global variables we declared at
the top of this file.
*/
example_r = r; example_r = r;
example_g = g; example_g = g;
@ -465,114 +491,130 @@ void example_set_color(magic_api * api, Uint8 r, Uint8 g, Uint8 b)
/* The Magic Effect Routines! */ /* The Magic Effect Routines! */
/* ---------------------------------------------------------------------- */ /* ---------------------------------------------------------------------- */
// Our "callback" function /*
// Our 'callback' function
// We do the 'work' in this callback. Our plugin file has just one.
// Some "Magic" tool plugins may have more, depending on the tools they're
// providing. Some have none (since they're not click-and-drag
// painting-style tools).
//
// Our callback function gets called once for every point along a line between
// the mouse's previous and current position, as it's being dragged.
//
// It pays attention to 'which' to determine which of our plugin's tools
// is currently selected.
void example_line_callback(void *ptr, int which, SDL_Surface * canvas, We do the 'work' in this callback. Our plugin file has just one. Some
SDL_Surface * snapshot, int x, int y) 'Magic' tool plugins may have more, depending on the tools they're
providing. Some have none (since they're not click-and-drag painting-style
tools).
Our callback function gets called once for every point along a line between
the mouse's previous and current position, as it's being dragged.
Our callback pays attention to 'which' to determine which of our plugin's
tools is currently selected.
*/
void example_line_callback(void *pointer, int which, SDL_Surface * canvas,
SDL_Surface * snapshot, int x, int y)
{ {
// For technical reasons, we can't accept a pointer to the "magic_api" /*
// struct, like the other functions do. For technical reasons, we can't accept a pointer to the Tux Paint API's
// "magic_api" struct, like the other functions do.
// Instead, we receive a 'generic' pointer (a "void *").
// The line below declares a local "magic_api" pointer variable called "api", Instead, we receive a 'generic' pointer (a "void *"). The line below
// and then assigns it to the value of the 'generic' pointer we received. declares a local "magic_api" pointer variable called "api", and then
// assigns it to the value of the 'generic' pointer we received.
// (The "(magic_api *)" casts the generic pointer into the 'type' of
// pointer we want, a pointer to a "magic_api".) The "(magic_api *)" seen below casts the generic "void *" pointer into
magic_api *api = (magic_api *) ptr; the 'type' of pointer we want, a pointer to a "magic_api" struct.)
*/
magic_api *api = (magic_api *) pointer;
int xx, yy; int xx, yy;
/*
// This function handles both of our tools, so we need to check which This function handles both of our tools, so we need to check which is
// is being used right now. We compare the 'which' argument that being used right now. We compare the 'which' argument that Tux Paint
// Tux Paint sends to us with the values we enumerated above. sends to us with the values we enumerated above.
*/
if (which == TOOL_ONE) if (which == TOOL_ONE)
{ {
// Tool number 1 simply draws a single pixel at the (x,y) location. /*
// It's a 1x1 pixel brush Tool number 1 simply draws a single pixel at the (x,y) location. It acts
as a 1x1 pixel brush.
*/
api->putpixel(canvas, x, y, api->putpixel(canvas, x, y,
SDL_MapRGB(canvas->format, example_r, example_g, SDL_MapRGB(canvas->format,
example_b)); example_r, example_g, example_b));
// We use "SDL_MapRGB()" to convert the RGB value we receive from Tux Paint /*
// for the user's current color selection to a 'Uint32' pixel value We use "SDL_MapRGB()" to convert the RGB value we receive from Tux Paint
// we can send to Tux Paint's "putpixel()" function. for the user's current color selection to a 'Uint32' pixel value we can
send to Tux Paint's "putpixel()" function.
*/
} }
else if (which == TOOL_TWO) else if (which == TOOL_TWO)
{ {
// Tool number 2 copies an 8x8 square of pixels from the opposite side /*
// of the canvas and puts it under the cursor Tool number 2 copies an 8x8 square of pixels from the opposite side of
the canvas and puts it under the cursor.
*/
for (yy = -4; yy < 4; yy++) for (yy = -4; yy < 4; yy++)
{ {
for (xx = -4; xx < 4; xx++) for (xx = -4; xx < 4; xx++)
{ {
api->putpixel(canvas, x + xx, y + yy, api->putpixel(canvas, x + xx, y + yy,
api->getpixel(snapshot, canvas->w - x - xx, api->getpixel(snapshot,
canvas->h - y - yy)); snapshot->w - x - xx,
snapshot->h - y - yy));
// We simply use Tux Paint's "getpixel()" routine to pull pixel /*
// values from the 'snapshot', and then "putpixel()" to draw them Here we have simply use Tux Paint's "getpixel()" routine to pull pixel
// right into the 'canvas'. values from the 'snapshot', and then "putpixel()" to draw them right
into the 'snapshot'.
// Note: putpixel() and getpixel() are safe to use, even if your Note: putpixel() and getpixel() are safe to use, even if your X,Y values
// X,Y values are outside of the SDL surface (e.g., negative, or are outside of the SDL surface (e.g., negative, or greater than the
// greater than the surface's width or height). surface's width and/or height).
*/
} }
} }
} }
} }
// Switch-In event /*
// Switch-In event
// This happens whenever a Magic tool is enabled, either because the
// user just selected it, or they just came back to "Magic" after using
// another tool (e.g., Brush or Text), and this was the most-recently
// selected Magic tool.
//
// (This also applies to momentary tools, like
// Undo and Redo, and image-changing tools such as New and Open.)
//
// It also happens when a Magic tool's mode changes (it first
// receives a 'switchout()', below, for the old mode).
//
// Our example doesn't do anything when we switch to, or away from, our
// Magic tools, so we just do nothing here.
This happens whenever a Magic tool is enabled, either because the user just
selected it, or they just came back to 'Magic' after using another tool
(e.g., Brush or Text), and this was the most-recently selected Magic tool.
(This also applies to momentary tools, like Undo and Redo, and
image-changing tools such as New and Open.)
It also happens when a Magic tool's mode changes (we will first receive a
call to 'example_switchout()', below, for the old mode).
Our example doesn't do anything when we switch to, or away from, our Magic
tools, so we just do nothing here.
*/
void example_switchin(magic_api * api, int which, int mode, void example_switchin(magic_api * api, int which, int mode,
SDL_Surface * canvas) SDL_Surface * canvas)
{ {
} }
// Switch-Out event /*
// Switch-Out event
// This happens whenever a Magic tool is disabled, either because the
// user selected a different Magic tool, or they selected a completely
// different tool (e.g., Brush or Text).
//
// (This also applies to momentary tools, like Undo and Redo, and
// image-changing tools such as New and Open, in which case the
// switchin() function will be called moments later.)
//
// It also happens when a Magic tool's mode changes (it then
// receives a 'switchin()', above, for the new mode).
//
// Our example doesn't do anything when we switch to, or away from, our
// Magic tools, so we just do nothing here.
This happens whenever a Magic tool is disabled, either because the user
selected a different Magic tool, or they selected a completely different
tool (e.g., Brush or Text).
(This also applies to momentary tools, like Undo and Redo, and
image-changing tools such as New and Open.)
(And in that case, our example_switchin() function will be called moments
later.
It also happens when a Magic tool's mode changes (we will then receive a
call to 'example_switchin()', above, for the new mode).
Our example doesn't do anything when we switch to, or away from, our Magic
tools, so we just do nothing here.
*/
void example_switchout(magic_api * api, int which, int mode, void example_switchout(magic_api * api, int which, int mode,
SDL_Surface * canvas) SDL_Surface * canvas)
{ {

432
docs/fr_FR.UTF-8/tp_magic_example.c
View file

@ -1,7 +1,7 @@
/* tp_magic_example.c /* tp_magic_example.c
An example of a "Magic" tool plugin for Tux Paint An example of a "Magic" tool plugin for Tux Paint
octobre 18, 2022 octobre 19, 2022
*/ */
@ -26,12 +26,12 @@
enum enum
{ {
TOOL_ONE, // Becomes '0' TOOL_ONE, // Becomes '0'
TOOL_ONE, // Becomes '1' TOOL_TWO, // Becomes '1'
NUM_TOOLS // Becomes '2' NUM_TOOLS // Becomes '2'
}; };
/* A list of filenames for sounds and icons to load at startup: */ /* Lists of filenames for sounds and icons to load at startup: */
const char *sound_filenames[NUM_TOOLS] = { const char *sound_filenames[NUM_TOOLS] = {
"tool_one.wav", "tool_one.wav",
@ -61,7 +61,7 @@ const char *tool_names[NUM_TOOLS] = {
/* How to group the tools with other similar tools, within the 'Magic' selector: */ /* How to group the tools with other similar tools, within the 'Magic' selector: */
const int tool_groups[$NUM_TOOLS] = { const int tool_groups[NUM_TOOLS] = {
MAGIC_TYPE_PAINTING, MAGIC_TYPE_PAINTING,
MAGIC_TYPE_DISTORTS MAGIC_TYPE_DISTORTS
}; };
@ -83,7 +83,7 @@ const char *tool_descriptions[NUM_TOOLS] = {
Mix_Chunk *sound_effects[NUM_TOOLS]; Mix_Chunk *sound_effects[NUM_TOOLS];
/* The current color (an "RGB" -- red, green, blue -- value) the user has selected in Tux Paint: */ /* The current color (an "RGB" -- red, green, blue -- value) the user has selected in Tux Paint: */
Uint8 example_r, $example_g, $example_b; Uint8 example_r, example_g, example_b;
/* Our local function prototypes: */ /* Our local function prototypes: */
@ -97,11 +97,11 @@ _before_ them.
*/ */
void example_drag(magic_api * api, int which, SDL_Surface * canvas, void example_drag(magic_api * api, int which, SDL_Surface * canvas,
SDL_Surface * snapshot, int ox, int oy, int x, int y, SDL_Surface * snapshot, int old_x, int old_y, int x, int y,
SDL_Rect * update_rect); SDL_Rect * update_rect);
void example_line_callback(void *pointer, int which, SDL_Surface * canvas, void example_line_callback(void *pointer, int which, SDL_Surface * canvas,
SDL_Surface * snapshot, int x, int y); SDL_Surface * snapshot, int x, int y);
/* Setup Functions: */ /* Setup Functions: */
@ -154,13 +154,14 @@ int example_init(magic_api * api)
Use "api->data_directory" to figure out where our sounds should be. (The Use "api->data_directory" to figure out where our sounds should be. (The
"tp-magic-config --dataprefix" command would have told us when we installed "tp-magic-config --dataprefix" command would have told us when we installed
our plugin and its data.) our plugin and its data.)
*/
snprintf(filename, sizeof(filename), "%s/sounds/magic/%s", api->data_directory, snprintf(filename, sizeof(filename), "%s/sounds/magic/%s", api->data_directory,
sound_filenames[i]); sound_filenames[i]);
printf("Trying to load %s sound file\n", filename); printf("Trying to load %s sound file\n", filename);
// Try to load the file! /* Try to load the file! */
sound_effects[i] = Mix_LoadWAV(filename); sound_effects[i] = Mix_LoadWAV(filename);
} }
@ -168,80 +169,86 @@ int example_init(magic_api * api)
} }
// Report our tool count /*
// Report our tool count
// Tux Paint needs to know how many "Magic" tools we'll be providing.
// Return that number here. (We simply grab the value of "NUM_TOOLS"
// from our 'enum' above!)
//
// When Tux Paint is starting up and loading plugins, it will call
// some of the following setup functions once for each tool we report.
Tux Paint needs to know how many 'Magic' tools we'll be providing. Return
that number here. (We simply grab the value of 'NUM_TOOLS' from our 'enum'
above!)
When Tux Paint is starting up and loading plugins, it will call some of the
following setup functions once for each tool we report.
*/
int example_get_tool_count(magic_api * api) int example_get_tool_count(magic_api * api)
{ {
return (NUM_TOOLS); return (NUM_TOOLS);
} }
// Load icons /*
// Load our icons
// When Tux Paint is starting up and loading plugins, it asks us to
// provide icons for the "Magic" tool buttons.
When Tux Paint is starting up and loading plugins, it asks us to provide icons for the 'Magic' tool buttons.
*/
SDL_Surface *example_get_icon(magic_api * api, int which) SDL_Surface *example_get_icon(magic_api * api, int which)
{ {
char fname[1024]; char filename[1024];
// Assemble the filename from the "icon_filenames[]" array into /*
// a full path to a real file. Assemble the filename from the "icon_filenames[]" array into a full path to
// a real file.
// Use "api->data_directory" to figure out where our sounds should be.
// (The "tp-magic-config --dataprefix" command would have told us when
// we installed our plugin and its data.)
//
// We use 'which' (which of our tools Tux Paint is asking about)
// as an index into the array.
snprintf(fname, sizeof(fname), "%s/images/magic/%s.png", Use "api->data_directory" to figure out where our sounds should be. (The
"tp-magic-config --dataprefix" command would have told us when we installed
our plugin and its data.)
We use "which" (which of our tools Tux Paint is asking about) as an index
into the array.
*/
snprintf(filename, sizeof(filename), "%s/images/magic/%s",
api->data_directory, icon_filenames[which]); api->data_directory, icon_filenames[which]);
printf("Trying to load %s icon\n", filename);
// Try to load the image, and return the results to Tux Paint: /* Try to load the image, and return the results to Tux Paint: */
return (IMG_Load(fname)); return (IMG_Load(filename));
} }
// Report our "Magic" tool names /*
// Report our 'Magic' tool names
// When Tux Paint is starting up and loading plugins, it asks us to
// provide names (labels) for the "Magic" tool buttons.
When Tux Paint is starting up and loading plugins, it asks us to provide
names (labels) for the 'Magic' tool buttons.
*/
char *example_get_name(magic_api * api, int which) char *example_get_name(magic_api * api, int which)
{ {
const char *our_name_english; const char *our_name_english;
const char *our_name_localized; const char *our_name_localized;
// Get our name from the "names[]" array. /*
// Get our name from the "tool_names[]" array.
// We use 'which' (which of our tools Tux Paint is asking about)
// as an index into the array.
our_name_english = names[which]; We use 'which' (which of our tools Tux Paint is asking about) as an index
into the array.
*/
our_name_english = tool_names[which];
// Return a localized (aka translated) version of our name, /*
// if possible. Return a localized (aka translated) version of our name, if possible.
//
// We send "gettext()" the English version of the name from our array.
We send "gettext()" the English version of the name from our array.
*/
our_name_localized = gettext(our_name_english); our_name_localized = gettext(our_name_english);
// Finally, duplicate the string into a new section of memory, and /*
// send it to Tux Paint. (Tux Paint keeps track of the string and Finally, duplicate the string into a new section of memory, and send it to
// will free it for us, so we have one less thing to keep track of.) Tux Paint. (Tux Paint keeps track of the string and will free it for us,
so we have one less thing to keep track of.)
*/
return (strdup(our_name_localized)); return (strdup(our_name_localized));
} }
@ -306,9 +313,10 @@ char *example_get_description(magic_api * api, int which, int mode)
int example_requires_colors(magic_api * api, int which) int example_requires_colors(magic_api * api, int which)
{ {
// Both of our tools accept colors, so we're always returning '1' (for 'true') if (which == TOOL_ONE)
return 1;
return 1; else
return 0;
} }
@ -316,8 +324,10 @@ int example_requires_colors(magic_api * api, int which)
int example_modes(magic_api * api, int which) int example_modes(magic_api * api, int which)
{ {
// Both of our tools are painted (neither affect the full-screen), so we're /*
always returning 'MODE_PAINT' Both of our tools are painted (neither affect the full-screen), so we're
always returning 'MODE_PAINT'
*/
return MODE_PAINT; return MODE_PAINT;
} }
@ -347,114 +357,130 @@ void example_shutdown(magic_api * api)
/* Functions that respond to events in Tux Paint: */ /* Functions that respond to events in Tux Paint: */
/* ---------------------------------------------------------------------- */ /* ---------------------------------------------------------------------- */
// Affect the canvas on click: /* Affect the canvas on click: */
void void
example_click(magic_api * api, int which, int mode, example_click(magic_api * api, int which, int mode,
SDL_Surface * canvas, SDL_Surface * snapshot, int x, int y, SDL_Surface * canvas, SDL_Surface * snapshot, int x, int y,
SDL_Rect * update_rect) SDL_Rect * update_rect)
{ {
// In our case, a single click (which is also the start of a drag!) /*
// is identical to what dragging does, but just at one point, rather In our case, a single click (which is also the start of a drag!) is
// than across a line. identical to what dragging does, but just at one point, rather than across
// a line.
// So we 'cheat' here, by calling our draw() function with
// (x,y) for both the beginning and end points of a line. So we 'cheat' here, by calling our "example_draw()" function with (x,y) for
both the beginning and end points of a line.
*/
example_drag(api, which, canvas, snapshot, x, y, x, y, update_rect); example_drag(api, which, canvas, snapshot, x, y, x, y, update_rect);
} }
// Affect the canvas on drag: /* Affect the canvas on drag: */
void void
example_drag(magic_api * api, int which, SDL_Surface * canvas, example_drag(magic_api * api, int which,
SDL_Surface * snapshot, int ox, int oy, int x, int y, SDL_Surface * canvas, SDL_Surface * snapshot,
int old_x, int old_y, int x, int y,
SDL_Rect * update_rect) SDL_Rect * update_rect)
{ {
// Call Tux Paint's "line()" function. /*
// Call Tux Paint's "line()" (line-traversing) function.
// It will calculate a straight line between (ox,ox) and (x,y).
// Every N steps along that line (in this case, N is '1'), it
// will call _our_ function, "example_line_callback()", and send
// the current X,Y coordinates along the line, as well as other
// useful things (which of our "Magic" tools is being used and
// the current and snapshot canvases).
api->line((void *) api, which, canvas, snapshot, ox, oy, x, y, 1, It will calculate a straight line between (old_x,old_y) and (x,y). Every
N steps along that line (in this case, N is '1'), it will call _our_
function, "example_line_callback()", and send the current X,Y
coordinates along the line, as well as other useful things (which of our
'Magic' tools is being used and the current and snapshot canvases).
*/
api->line((void *) api, which, canvas, snapshot,
old_x, old_y, x, y, 1,
example_line_callback); example_line_callback);
/*
If we need to, swap the X and/or Y values, so that the coordinates
(old_x,old_y) is always the top left, and the coordinates (x,y) is
always the bottom right, so the values we put inside "update_rect" make
sense:
*/
// If we need to, swap the X and/or Y values, so that if (old_x > x)
// (ox,oy) is always the top left, and (x,y) is always the bottom right,
// so the values we put inside "update_rect" make sense:
if (ox > x)
{ {
int tmp = ox; int temp = old_x;
ox = x; old_x = x;
x = tmp; x = temp;
} }
if (oy > y) if (old_y > y)
{ {
int tmp = oy; int temp = old_y;
oy = y; old_y = y;
y = tmp; y = temp;
} }
// Fill in the elements of the "update_rect" SDL_Rect structure /*
// that Tux Paint is sharing with us. Fill in the elements of the "update_rect" SDL_Rect structure that Tux
Paint is sharing with us, therefore telling Tux Paint which part of the
canvas has been modified and should be updated.
*/
update_rect->x = ox - 4; update_rect->x = old_x - 4;
update_rect->y = oy - 4; update_rect->y = old_y - 4;
update_rect->w = (x + 4) - update_rect->x; update_rect->w = (x + 4) - update_rect->x;
update_rect->h = (y + 4) - update_rect->h; update_rect->h = (y + 4) - update_rect->y;
/*
Play the appropriate sound effect
// Play the appropriate sound effect We're calculating a value between 0-255 for where the mouse is
// horizontally across the canvas (0 is the left, ~128 is the center, 255
// We're calculating a value between 0-255 for where the mouse is is the right).
// across the canvas (0 is the left, ~128 is the center, 255 is the right).
//
// These are the exact values Tux Paint's "playsound()" wants,
// to determine what speaker to play the sound in.
// (So the sound will pan from speaker to speaker as you drag the
// mouse around the canvas!)
api->playsound(snd_effect[which], (x * 255) / canvas->w, // pan These are the exact values Tux Paint's "playsound()" wants, to determine
255); // distance what speaker to play the sound in. (So the sound will pan from speaker
to speaker as you drag the mouse around the canvas!)
*/
api->playsound(sound_effects[which],
(x * 255) / canvas->w, /* Left/right pan */
255 /* Near/far distance (loudness) */);
} }
// Affect the canvas on release: /* Affect the canvas on release: */
void void
example_release(magic_api * api, int which, example_release(magic_api * api, int which,
SDL_Surface * canvas, SDL_Surface * snapshot, int x, int y, SDL_Surface * canvas, SDL_Surface * snapshot, int x, int y,
SDL_Rect * update_rect) SDL_Rect * update_rect)
{ {
// Neither of our effects do anything special when the mouse is released /*
// from a click or click-and-drag, so there's no code here... Neither of our effects do anything special when the mouse is released
from a click or click-and-drag, so there's no code here...
*/
} }
// Accept colors /*
// Accept colors
// When any of our "Magic" tools are activated by the user,
// if that tool accepts colors, the current color selection is sent to us.
//
// Additionally, if one of our color-accepting tools is active when the
// user changes colors, we'll be informed of that, as well.
//
// The color comes in as RGB values.
When any of our 'Magig' tools are activated by the user, if that tool
accepts colors, the current color selection is sent to us.
Additionally, if one of our color-accepting tools is active when the user
changes their chosen, we'll be informed of that as well.
The color comes in as RGB (red, green, and blue) values from 0 (darkest) to
255 (brightest).
*/
void example_set_color(magic_api * api, Uint8 r, Uint8 g, Uint8 b) void example_set_color(magic_api * api, Uint8 r, Uint8 g, Uint8 b)
{ {
// We simply store the RGB values in the global variables we /*
// declared at the top of this file. We simply store the RGB values in the global variables we declared at
the top of this file.
*/
example_r = r; example_r = r;
example_g = g; example_g = g;
@ -465,114 +491,130 @@ void example_set_color(magic_api * api, Uint8 r, Uint8 g, Uint8 b)
/* The Magic Effect Routines! */ /* The Magic Effect Routines! */
/* ---------------------------------------------------------------------- */ /* ---------------------------------------------------------------------- */
// Our "callback" function /*
// Our 'callback' function
// We do the 'work' in this callback. Our plugin file has just one.
// Some "Magic" tool plugins may have more, depending on the tools they're
// providing. Some have none (since they're not click-and-drag
// painting-style tools).
//
// Our callback function gets called once for every point along a line between
// the mouse's previous and current position, as it's being dragged.
//
// It pays attention to 'which' to determine which of our plugin's tools
// is currently selected.
void example_line_callback(void *ptr, int which, SDL_Surface * canvas, We do the 'work' in this callback. Our plugin file has just one. Some
SDL_Surface * snapshot, int x, int y) 'Magic' tool plugins may have more, depending on the tools they're
providing. Some have none (since they're not click-and-drag painting-style
tools).
Our callback function gets called once for every point along a line between
the mouse's previous and current position, as it's being dragged.
Our callback pays attention to 'which' to determine which of our plugin's
tools is currently selected.
*/
void example_line_callback(void *pointer, int which, SDL_Surface * canvas,
SDL_Surface * snapshot, int x, int y)
{ {
// For technical reasons, we can't accept a pointer to the "magic_api" /*
// struct, like the other functions do. For technical reasons, we can't accept a pointer to the Tux Paint API's
// "magic_api" struct, like the other functions do.
// Instead, we receive a 'generic' pointer (a "void *").
// The line below declares a local "magic_api" pointer variable called "api", Instead, we receive a 'generic' pointer (a "void *"). The line below
// and then assigns it to the value of the 'generic' pointer we received. declares a local "magic_api" pointer variable called "api", and then
// assigns it to the value of the 'generic' pointer we received.
// (The "(magic_api *)" casts the generic pointer into the 'type' of
// pointer we want, a pointer to a "magic_api".) The "(magic_api *)" seen below casts the generic "void *" pointer into
magic_api *api = (magic_api *) ptr; the 'type' of pointer we want, a pointer to a "magic_api" struct.)
*/
magic_api *api = (magic_api *) pointer;
int xx, yy; int xx, yy;
/*
// This function handles both of our tools, so we need to check which This function handles both of our tools, so we need to check which is
// is being used right now. We compare the 'which' argument that being used right now. We compare the 'which' argument that Tux Paint
// Tux Paint sends to us with the values we enumerated above. sends to us with the values we enumerated above.
*/
if (which == TOOL_ONE) if (which == TOOL_ONE)
{ {
// Tool number 1 simply draws a single pixel at the (x,y) location. /*
// It's a 1x1 pixel brush Tool number 1 simply draws a single pixel at the (x,y) location. It acts
as a 1x1 pixel brush.
*/
api->putpixel(canvas, x, y, api->putpixel(canvas, x, y,
SDL_MapRGB(canvas->format, example_r, example_g, SDL_MapRGB(canvas->format,
example_b)); example_r, example_g, example_b));
// We use "SDL_MapRGB()" to convert the RGB value we receive from Tux Paint /*
// for the user's current color selection to a 'Uint32' pixel value We use "SDL_MapRGB()" to convert the RGB value we receive from Tux Paint
// we can send to Tux Paint's "putpixel()" function. for the user's current color selection to a 'Uint32' pixel value we can
send to Tux Paint's "putpixel()" function.
*/
} }
else if (which == TOOL_TWO) else if (which == TOOL_TWO)
{ {
// Tool number 2 copies an 8x8 square of pixels from the opposite side /*
// of the canvas and puts it under the cursor Tool number 2 copies an 8x8 square of pixels from the opposite side of
the canvas and puts it under the cursor.
*/
for (yy = -4; yy < 4; yy++) for (yy = -4; yy < 4; yy++)
{ {
for (xx = -4; xx < 4; xx++) for (xx = -4; xx < 4; xx++)
{ {
api->putpixel(canvas, x + xx, y + yy, api->putpixel(canvas, x + xx, y + yy,
api->getpixel(snapshot, canvas->w - x - xx, api->getpixel(snapshot,
canvas->h - y - yy)); snapshot->w - x - xx,
snapshot->h - y - yy));
// We simply use Tux Paint's "getpixel()" routine to pull pixel /*
// values from the 'snapshot', and then "putpixel()" to draw them Here we have simply use Tux Paint's "getpixel()" routine to pull pixel
// right into the 'canvas'. values from the 'snapshot', and then "putpixel()" to draw them right
into the 'snapshot'.
// Note: putpixel() and getpixel() are safe to use, even if your Note: putpixel() and getpixel() are safe to use, even if your X,Y values
// X,Y values are outside of the SDL surface (e.g., negative, or are outside of the SDL surface (e.g., negative, or greater than the
// greater than the surface's width or height). surface's width and/or height).
*/
} }
} }
} }
} }
// Switch-In event /*
// Switch-In event
// This happens whenever a Magic tool is enabled, either because the
// user just selected it, or they just came back to "Magic" after using
// another tool (e.g., Brush or Text), and this was the most-recently
// selected Magic tool.
//
// (This also applies to momentary tools, like
// Undo and Redo, and image-changing tools such as New and Open.)
//
// It also happens when a Magic tool's mode changes (it first
// receives a 'switchout()', below, for the old mode).
//
// Our example doesn't do anything when we switch to, or away from, our
// Magic tools, so we just do nothing here.
This happens whenever a Magic tool is enabled, either because the user just
selected it, or they just came back to 'Magic' after using another tool
(e.g., Brush or Text), and this was the most-recently selected Magic tool.
(This also applies to momentary tools, like Undo and Redo, and
image-changing tools such as New and Open.)
It also happens when a Magic tool's mode changes (we will first receive a
call to 'example_switchout()', below, for the old mode).
Our example doesn't do anything when we switch to, or away from, our Magic
tools, so we just do nothing here.
*/
void example_switchin(magic_api * api, int which, int mode, void example_switchin(magic_api * api, int which, int mode,
SDL_Surface * canvas) SDL_Surface * canvas)
{ {
} }
// Switch-Out event /*
// Switch-Out event
// This happens whenever a Magic tool is disabled, either because the
// user selected a different Magic tool, or they selected a completely
// different tool (e.g., Brush or Text).
//
// (This also applies to momentary tools, like Undo and Redo, and
// image-changing tools such as New and Open, in which case the
// switchin() function will be called moments later.)
//
// It also happens when a Magic tool's mode changes (it then
// receives a 'switchin()', above, for the new mode).
//
// Our example doesn't do anything when we switch to, or away from, our
// Magic tools, so we just do nothing here.
This happens whenever a Magic tool is disabled, either because the user
selected a different Magic tool, or they selected a completely different
tool (e.g., Brush or Text).
(This also applies to momentary tools, like Undo and Redo, and
image-changing tools such as New and Open.)
(And in that case, our example_switchin() function will be called moments
later.
It also happens when a Magic tool's mode changes (we will then receive a
call to 'example_switchin()', above, for the new mode).
Our example doesn't do anything when we switch to, or away from, our Magic
tools, so we just do nothing here.
*/
void example_switchout(magic_api * api, int which, int mode, void example_switchout(magic_api * api, int which, int mode,
SDL_Surface * canvas) SDL_Surface * canvas)
{ {

432
docs/gl_ES.UTF-8/html/tp_magic_example.c
View file

@ -1,7 +1,7 @@
/* tp_magic_example.c /* tp_magic_example.c
An example of a "Magic" tool plugin for Tux Paint An example of a "Magic" tool plugin for Tux Paint
18 de Outubro de 2022 19 de Outubro de 2022
*/ */
@ -26,12 +26,12 @@
enum enum
{ {
TOOL_ONE, // Becomes '0' TOOL_ONE, // Becomes '0'
TOOL_ONE, // Becomes '1' TOOL_TWO, // Becomes '1'
NUM_TOOLS // Becomes '2' NUM_TOOLS // Becomes '2'
}; };
/* A list of filenames for sounds and icons to load at startup: */ /* Lists of filenames for sounds and icons to load at startup: */
const char *sound_filenames[NUM_TOOLS] = { const char *sound_filenames[NUM_TOOLS] = {
"tool_one.wav", "tool_one.wav",
@ -61,7 +61,7 @@ const char *tool_names[NUM_TOOLS] = {
/* How to group the tools with other similar tools, within the 'Magic' selector: */ /* How to group the tools with other similar tools, within the 'Magic' selector: */
const int tool_groups[$NUM_TOOLS] = { const int tool_groups[NUM_TOOLS] = {
MAGIC_TYPE_PAINTING, MAGIC_TYPE_PAINTING,
MAGIC_TYPE_DISTORTS MAGIC_TYPE_DISTORTS
}; };
@ -83,7 +83,7 @@ const char *tool_descriptions[NUM_TOOLS] = {
Mix_Chunk *sound_effects[NUM_TOOLS]; Mix_Chunk *sound_effects[NUM_TOOLS];
/* The current color (an "RGB" -- red, green, blue -- value) the user has selected in Tux Paint: */ /* The current color (an "RGB" -- red, green, blue -- value) the user has selected in Tux Paint: */
Uint8 example_r, $example_g, $example_b; Uint8 example_r, example_g, example_b;
/* Our local function prototypes: */ /* Our local function prototypes: */
@ -97,11 +97,11 @@ _before_ them.
*/ */
void example_drag(magic_api * api, int which, SDL_Surface * canvas, void example_drag(magic_api * api, int which, SDL_Surface * canvas,
SDL_Surface * snapshot, int ox, int oy, int x, int y, SDL_Surface * snapshot, int old_x, int old_y, int x, int y,
SDL_Rect * update_rect); SDL_Rect * update_rect);
void example_line_callback(void *pointer, int which, SDL_Surface * canvas, void example_line_callback(void *pointer, int which, SDL_Surface * canvas,
SDL_Surface * snapshot, int x, int y); SDL_Surface * snapshot, int x, int y);
/* Setup Functions: */ /* Setup Functions: */
@ -154,13 +154,14 @@ int example_init(magic_api * api)
Use "api->data_directory" to figure out where our sounds should be. (The Use "api->data_directory" to figure out where our sounds should be. (The
"tp-magic-config --dataprefix" command would have told us when we installed "tp-magic-config --dataprefix" command would have told us when we installed
our plugin and its data.) our plugin and its data.)
*/
snprintf(filename, sizeof(filename), "%s/sounds/magic/%s", api->data_directory, snprintf(filename, sizeof(filename), "%s/sounds/magic/%s", api->data_directory,
sound_filenames[i]); sound_filenames[i]);
printf("Trying to load %s sound file\n", filename); printf("Trying to load %s sound file\n", filename);
// Try to load the file! /* Try to load the file! */
sound_effects[i] = Mix_LoadWAV(filename); sound_effects[i] = Mix_LoadWAV(filename);
} }
@ -168,80 +169,86 @@ int example_init(magic_api * api)
} }
// Report our tool count /*
// Report our tool count
// Tux Paint needs to know how many "Magic" tools we'll be providing.
// Return that number here. (We simply grab the value of "NUM_TOOLS"
// from our 'enum' above!)
//
// When Tux Paint is starting up and loading plugins, it will call
// some of the following setup functions once for each tool we report.
Tux Paint needs to know how many 'Magic' tools we'll be providing. Return
that number here. (We simply grab the value of 'NUM_TOOLS' from our 'enum'
above!)
When Tux Paint is starting up and loading plugins, it will call some of the
following setup functions once for each tool we report.
*/
int example_get_tool_count(magic_api * api) int example_get_tool_count(magic_api * api)
{ {
return (NUM_TOOLS); return (NUM_TOOLS);
} }
// Load icons /*
// Load our icons
// When Tux Paint is starting up and loading plugins, it asks us to
// provide icons for the "Magic" tool buttons.
When Tux Paint is starting up and loading plugins, it asks us to provide icons for the 'Magic' tool buttons.
*/
SDL_Surface *example_get_icon(magic_api * api, int which) SDL_Surface *example_get_icon(magic_api * api, int which)
{ {
char fname[1024]; char filename[1024];
// Assemble the filename from the "icon_filenames[]" array into /*
// a full path to a real file. Assemble the filename from the "icon_filenames[]" array into a full path to
// a real file.
// Use "api->data_directory" to figure out where our sounds should be.
// (The "tp-magic-config --dataprefix" command would have told us when
// we installed our plugin and its data.)
//
// We use 'which' (which of our tools Tux Paint is asking about)
// as an index into the array.
snprintf(fname, sizeof(fname), "%s/images/magic/%s.png", Use "api->data_directory" to figure out where our sounds should be. (The
"tp-magic-config --dataprefix" command would have told us when we installed
our plugin and its data.)
We use "which" (which of our tools Tux Paint is asking about) as an index
into the array.
*/
snprintf(filename, sizeof(filename), "%s/images/magic/%s",
api->data_directory, icon_filenames[which]); api->data_directory, icon_filenames[which]);
printf("Trying to load %s icon\n", filename);
// Try to load the image, and return the results to Tux Paint: /* Try to load the image, and return the results to Tux Paint: */
return (IMG_Load(fname)); return (IMG_Load(filename));
} }
// Report our "Magic" tool names /*
// Report our 'Magic' tool names
// When Tux Paint is starting up and loading plugins, it asks us to
// provide names (labels) for the "Magic" tool buttons.
When Tux Paint is starting up and loading plugins, it asks us to provide
names (labels) for the 'Magic' tool buttons.
*/
char *example_get_name(magic_api * api, int which) char *example_get_name(magic_api * api, int which)
{ {
const char *our_name_english; const char *our_name_english;
const char *our_name_localized; const char *our_name_localized;
// Get our name from the "names[]" array. /*
// Get our name from the "tool_names[]" array.
// We use 'which' (which of our tools Tux Paint is asking about)
// as an index into the array.
our_name_english = names[which]; We use 'which' (which of our tools Tux Paint is asking about) as an index
into the array.
*/
our_name_english = tool_names[which];
// Return a localized (aka translated) version of our name, /*
// if possible. Return a localized (aka translated) version of our name, if possible.
//
// We send "gettext()" the English version of the name from our array.
We send "gettext()" the English version of the name from our array.
*/
our_name_localized = gettext(our_name_english); our_name_localized = gettext(our_name_english);
// Finally, duplicate the string into a new section of memory, and /*
// send it to Tux Paint. (Tux Paint keeps track of the string and Finally, duplicate the string into a new section of memory, and send it to
// will free it for us, so we have one less thing to keep track of.) Tux Paint. (Tux Paint keeps track of the string and will free it for us,
so we have one less thing to keep track of.)
*/
return (strdup(our_name_localized)); return (strdup(our_name_localized));
} }
@ -306,9 +313,10 @@ char *example_get_description(magic_api * api, int which, int mode)
int example_requires_colors(magic_api * api, int which) int example_requires_colors(magic_api * api, int which)
{ {
// Both of our tools accept colors, so we're always returning '1' (for 'true') if (which == TOOL_ONE)
return 1;
return 1; else
return 0;
} }
@ -316,8 +324,10 @@ int example_requires_colors(magic_api * api, int which)
int example_modes(magic_api * api, int which) int example_modes(magic_api * api, int which)
{ {
// Both of our tools are painted (neither affect the full-screen), so we're /*
always returning 'MODE_PAINT' Both of our tools are painted (neither affect the full-screen), so we're
always returning 'MODE_PAINT'
*/
return MODE_PAINT; return MODE_PAINT;
} }
@ -347,114 +357,130 @@ void example_shutdown(magic_api * api)
/* Functions that respond to events in Tux Paint: */ /* Functions that respond to events in Tux Paint: */
/* ---------------------------------------------------------------------- */ /* ---------------------------------------------------------------------- */
// Affect the canvas on click: /* Affect the canvas on click: */
void void
example_click(magic_api * api, int which, int mode, example_click(magic_api * api, int which, int mode,
SDL_Surface * canvas, SDL_Surface * snapshot, int x, int y, SDL_Surface * canvas, SDL_Surface * snapshot, int x, int y,
SDL_Rect * update_rect) SDL_Rect * update_rect)
{ {
// In our case, a single click (which is also the start of a drag!) /*
// is identical to what dragging does, but just at one point, rather In our case, a single click (which is also the start of a drag!) is
// than across a line. identical to what dragging does, but just at one point, rather than across
// a line.
// So we 'cheat' here, by calling our draw() function with
// (x,y) for both the beginning and end points of a line. So we 'cheat' here, by calling our "example_draw()" function with (x,y) for
both the beginning and end points of a line.
*/
example_drag(api, which, canvas, snapshot, x, y, x, y, update_rect); example_drag(api, which, canvas, snapshot, x, y, x, y, update_rect);
} }
// Affect the canvas on drag: /* Affect the canvas on drag: */
void void
example_drag(magic_api * api, int which, SDL_Surface * canvas, example_drag(magic_api * api, int which,
SDL_Surface * snapshot, int ox, int oy, int x, int y, SDL_Surface * canvas, SDL_Surface * snapshot,
int old_x, int old_y, int x, int y,
SDL_Rect * update_rect) SDL_Rect * update_rect)
{ {
// Call Tux Paint's "line()" function. /*
// Call Tux Paint's "line()" (line-traversing) function.
// It will calculate a straight line between (ox,ox) and (x,y).
// Every N steps along that line (in this case, N is '1'), it
// will call _our_ function, "example_line_callback()", and send
// the current X,Y coordinates along the line, as well as other
// useful things (which of our "Magic" tools is being used and
// the current and snapshot canvases).
api->line((void *) api, which, canvas, snapshot, ox, oy, x, y, 1, It will calculate a straight line between (old_x,old_y) and (x,y). Every
N steps along that line (in this case, N is '1'), it will call _our_
function, "example_line_callback()", and send the current X,Y
coordinates along the line, as well as other useful things (which of our
'Magic' tools is being used and the current and snapshot canvases).
*/
api->line((void *) api, which, canvas, snapshot,
old_x, old_y, x, y, 1,
example_line_callback); example_line_callback);
/*
If we need to, swap the X and/or Y values, so that the coordinates
(old_x,old_y) is always the top left, and the coordinates (x,y) is
always the bottom right, so the values we put inside "update_rect" make
sense:
*/
// If we need to, swap the X and/or Y values, so that if (old_x > x)
// (ox,oy) is always the top left, and (x,y) is always the bottom right,
// so the values we put inside "update_rect" make sense:
if (ox > x)
{ {
int tmp = ox; int temp = old_x;
ox = x; old_x = x;
x = tmp; x = temp;
} }
if (oy > y) if (old_y > y)
{ {
int tmp = oy; int temp = old_y;
oy = y; old_y = y;
y = tmp; y = temp;
} }
// Fill in the elements of the "update_rect" SDL_Rect structure /*
// that Tux Paint is sharing with us. Fill in the elements of the "update_rect" SDL_Rect structure that Tux
Paint is sharing with us, therefore telling Tux Paint which part of the
canvas has been modified and should be updated.
*/
update_rect->x = ox - 4; update_rect->x = old_x - 4;
update_rect->y = oy - 4; update_rect->y = old_y - 4;
update_rect->w = (x + 4) - update_rect->x; update_rect->w = (x + 4) - update_rect->x;
update_rect->h = (y + 4) - update_rect->h; update_rect->h = (y + 4) - update_rect->y;
/*
Play the appropriate sound effect
// Play the appropriate sound effect We're calculating a value between 0-255 for where the mouse is
// horizontally across the canvas (0 is the left, ~128 is the center, 255
// We're calculating a value between 0-255 for where the mouse is is the right).
// across the canvas (0 is the left, ~128 is the center, 255 is the right).
//
// These are the exact values Tux Paint's "playsound()" wants,
// to determine what speaker to play the sound in.
// (So the sound will pan from speaker to speaker as you drag the
// mouse around the canvas!)
api->playsound(snd_effect[which], (x * 255) / canvas->w, // pan These are the exact values Tux Paint's "playsound()" wants, to determine
255); // distance what speaker to play the sound in. (So the sound will pan from speaker
to speaker as you drag the mouse around the canvas!)
*/
api->playsound(sound_effects[which],
(x * 255) / canvas->w, /* Left/right pan */
255 /* Near/far distance (loudness) */);
} }
// Affect the canvas on release: /* Affect the canvas on release: */
void void
example_release(magic_api * api, int which, example_release(magic_api * api, int which,
SDL_Surface * canvas, SDL_Surface * snapshot, int x, int y, SDL_Surface * canvas, SDL_Surface * snapshot, int x, int y,
SDL_Rect * update_rect) SDL_Rect * update_rect)
{ {
// Neither of our effects do anything special when the mouse is released /*
// from a click or click-and-drag, so there's no code here... Neither of our effects do anything special when the mouse is released
from a click or click-and-drag, so there's no code here...
*/
} }
// Accept colors /*
// Accept colors
// When any of our "Magic" tools are activated by the user,
// if that tool accepts colors, the current color selection is sent to us.
//
// Additionally, if one of our color-accepting tools is active when the
// user changes colors, we'll be informed of that, as well.
//
// The color comes in as RGB values.
When any of our 'Magig' tools are activated by the user, if that tool
accepts colors, the current color selection is sent to us.
Additionally, if one of our color-accepting tools is active when the user
changes their chosen, we'll be informed of that as well.
The color comes in as RGB (red, green, and blue) values from 0 (darkest) to
255 (brightest).
*/
void example_set_color(magic_api * api, Uint8 r, Uint8 g, Uint8 b) void example_set_color(magic_api * api, Uint8 r, Uint8 g, Uint8 b)
{ {
// We simply store the RGB values in the global variables we /*
// declared at the top of this file. We simply store the RGB values in the global variables we declared at
the top of this file.
*/
example_r = r; example_r = r;
example_g = g; example_g = g;
@ -465,114 +491,130 @@ void example_set_color(magic_api * api, Uint8 r, Uint8 g, Uint8 b)
/* The Magic Effect Routines! */ /* The Magic Effect Routines! */
/* ---------------------------------------------------------------------- */ /* ---------------------------------------------------------------------- */
// Our "callback" function /*
// Our 'callback' function
// We do the 'work' in this callback. Our plugin file has just one.
// Some "Magic" tool plugins may have more, depending on the tools they're
// providing. Some have none (since they're not click-and-drag
// painting-style tools).
//
// Our callback function gets called once for every point along a line between
// the mouse's previous and current position, as it's being dragged.
//
// It pays attention to 'which' to determine which of our plugin's tools
// is currently selected.
void example_line_callback(void *ptr, int which, SDL_Surface * canvas, We do the 'work' in this callback. Our plugin file has just one. Some
SDL_Surface * snapshot, int x, int y) 'Magic' tool plugins may have more, depending on the tools they're
providing. Some have none (since they're not click-and-drag painting-style
tools).
Our callback function gets called once for every point along a line between
the mouse's previous and current position, as it's being dragged.
Our callback pays attention to 'which' to determine which of our plugin's
tools is currently selected.
*/
void example_line_callback(void *pointer, int which, SDL_Surface * canvas,
SDL_Surface * snapshot, int x, int y)
{ {
// For technical reasons, we can't accept a pointer to the "magic_api" /*
// struct, like the other functions do. For technical reasons, we can't accept a pointer to the Tux Paint API's
// "magic_api" struct, like the other functions do.
// Instead, we receive a 'generic' pointer (a "void *").
// The line below declares a local "magic_api" pointer variable called "api", Instead, we receive a 'generic' pointer (a "void *"). The line below
// and then assigns it to the value of the 'generic' pointer we received. declares a local "magic_api" pointer variable called "api", and then
// assigns it to the value of the 'generic' pointer we received.
// (The "(magic_api *)" casts the generic pointer into the 'type' of
// pointer we want, a pointer to a "magic_api".) The "(magic_api *)" seen below casts the generic "void *" pointer into
magic_api *api = (magic_api *) ptr; the 'type' of pointer we want, a pointer to a "magic_api" struct.)
*/
magic_api *api = (magic_api *) pointer;
int xx, yy; int xx, yy;
/*
// This function handles both of our tools, so we need to check which This function handles both of our tools, so we need to check which is
// is being used right now. We compare the 'which' argument that being used right now. We compare the 'which' argument that Tux Paint
// Tux Paint sends to us with the values we enumerated above. sends to us with the values we enumerated above.
*/
if (which == TOOL_ONE) if (which == TOOL_ONE)
{ {
// Tool number 1 simply draws a single pixel at the (x,y) location. /*
// It's a 1x1 pixel brush Tool number 1 simply draws a single pixel at the (x,y) location. It acts
as a 1x1 pixel brush.
*/
api->putpixel(canvas, x, y, api->putpixel(canvas, x, y,
SDL_MapRGB(canvas->format, example_r, example_g, SDL_MapRGB(canvas->format,
example_b)); example_r, example_g, example_b));
// We use "SDL_MapRGB()" to convert the RGB value we receive from Tux Paint /*
// for the user's current color selection to a 'Uint32' pixel value We use "SDL_MapRGB()" to convert the RGB value we receive from Tux Paint
// we can send to Tux Paint's "putpixel()" function. for the user's current color selection to a 'Uint32' pixel value we can
send to Tux Paint's "putpixel()" function.
*/
} }
else if (which == TOOL_TWO) else if (which == TOOL_TWO)
{ {
// Tool number 2 copies an 8x8 square of pixels from the opposite side /*
// of the canvas and puts it under the cursor Tool number 2 copies an 8x8 square of pixels from the opposite side of
the canvas and puts it under the cursor.
*/
for (yy = -4; yy < 4; yy++) for (yy = -4; yy < 4; yy++)
{ {
for (xx = -4; xx < 4; xx++) for (xx = -4; xx < 4; xx++)
{ {
api->putpixel(canvas, x + xx, y + yy, api->putpixel(canvas, x + xx, y + yy,
api->getpixel(snapshot, canvas->w - x - xx, api->getpixel(snapshot,
canvas->h - y - yy)); snapshot->w - x - xx,
snapshot->h - y - yy));
// We simply use Tux Paint's "getpixel()" routine to pull pixel /*
// values from the 'snapshot', and then "putpixel()" to draw them Here we have simply use Tux Paint's "getpixel()" routine to pull pixel
// right into the 'canvas'. values from the 'snapshot', and then "putpixel()" to draw them right
into the 'snapshot'.
// Note: putpixel() and getpixel() are safe to use, even if your Note: putpixel() and getpixel() are safe to use, even if your X,Y values
// X,Y values are outside of the SDL surface (e.g., negative, or are outside of the SDL surface (e.g., negative, or greater than the
// greater than the surface's width or height). surface's width and/or height).
*/
} }
} }
} }
} }
// Switch-In event /*
// Switch-In event
// This happens whenever a Magic tool is enabled, either because the
// user just selected it, or they just came back to "Magic" after using
// another tool (e.g., Brush or Text), and this was the most-recently
// selected Magic tool.
//
// (This also applies to momentary tools, like
// Undo and Redo, and image-changing tools such as New and Open.)
//
// It also happens when a Magic tool's mode changes (it first
// receives a 'switchout()', below, for the old mode).
//
// Our example doesn't do anything when we switch to, or away from, our
// Magic tools, so we just do nothing here.
This happens whenever a Magic tool is enabled, either because the user just
selected it, or they just came back to 'Magic' after using another tool
(e.g., Brush or Text), and this was the most-recently selected Magic tool.
(This also applies to momentary tools, like Undo and Redo, and
image-changing tools such as New and Open.)
It also happens when a Magic tool's mode changes (we will first receive a
call to 'example_switchout()', below, for the old mode).
Our example doesn't do anything when we switch to, or away from, our Magic
tools, so we just do nothing here.
*/
void example_switchin(magic_api * api, int which, int mode, void example_switchin(magic_api * api, int which, int mode,
SDL_Surface * canvas) SDL_Surface * canvas)
{ {
} }
// Switch-Out event /*
// Switch-Out event
// This happens whenever a Magic tool is disabled, either because the
// user selected a different Magic tool, or they selected a completely
// different tool (e.g., Brush or Text).
//
// (This also applies to momentary tools, like Undo and Redo, and
// image-changing tools such as New and Open, in which case the
// switchin() function will be called moments later.)
//
// It also happens when a Magic tool's mode changes (it then
// receives a 'switchin()', above, for the new mode).
//
// Our example doesn't do anything when we switch to, or away from, our
// Magic tools, so we just do nothing here.
This happens whenever a Magic tool is disabled, either because the user
selected a different Magic tool, or they selected a completely different
tool (e.g., Brush or Text).
(This also applies to momentary tools, like Undo and Redo, and
image-changing tools such as New and Open.)
(And in that case, our example_switchin() function will be called moments
later.
It also happens when a Magic tool's mode changes (we will then receive a
call to 'example_switchin()', above, for the new mode).
Our example doesn't do anything when we switch to, or away from, our Magic
tools, so we just do nothing here.
*/
void example_switchout(magic_api * api, int which, int mode, void example_switchout(magic_api * api, int which, int mode,
SDL_Surface * canvas) SDL_Surface * canvas)
{ {

432
docs/gl_ES.UTF-8/tp_magic_example.c
View file

@ -1,7 +1,7 @@
/* tp_magic_example.c /* tp_magic_example.c
An example of a "Magic" tool plugin for Tux Paint An example of a "Magic" tool plugin for Tux Paint
18 de Outubro de 2022 19 de Outubro de 2022
*/ */
@ -26,12 +26,12 @@
enum enum
{ {
TOOL_ONE, // Becomes '0' TOOL_ONE, // Becomes '0'
TOOL_ONE, // Becomes '1' TOOL_TWO, // Becomes '1'
NUM_TOOLS // Becomes '2' NUM_TOOLS // Becomes '2'
}; };
/* A list of filenames for sounds and icons to load at startup: */ /* Lists of filenames for sounds and icons to load at startup: */
const char *sound_filenames[NUM_TOOLS] = { const char *sound_filenames[NUM_TOOLS] = {
"tool_one.wav", "tool_one.wav",
@ -61,7 +61,7 @@ const char *tool_names[NUM_TOOLS] = {
/* How to group the tools with other similar tools, within the 'Magic' selector: */ /* How to group the tools with other similar tools, within the 'Magic' selector: */
const int tool_groups[$NUM_TOOLS] = { const int tool_groups[NUM_TOOLS] = {
MAGIC_TYPE_PAINTING, MAGIC_TYPE_PAINTING,
MAGIC_TYPE_DISTORTS MAGIC_TYPE_DISTORTS
}; };
@ -83,7 +83,7 @@ const char *tool_descriptions[NUM_TOOLS] = {
Mix_Chunk *sound_effects[NUM_TOOLS]; Mix_Chunk *sound_effects[NUM_TOOLS];
/* The current color (an "RGB" -- red, green, blue -- value) the user has selected in Tux Paint: */ /* The current color (an "RGB" -- red, green, blue -- value) the user has selected in Tux Paint: */
Uint8 example_r, $example_g, $example_b; Uint8 example_r, example_g, example_b;
/* Our local function prototypes: */ /* Our local function prototypes: */
@ -97,11 +97,11 @@ _before_ them.
*/ */
void example_drag(magic_api * api, int which, SDL_Surface * canvas, void example_drag(magic_api * api, int which, SDL_Surface * canvas,
SDL_Surface * snapshot, int ox, int oy, int x, int y, SDL_Surface * snapshot, int old_x, int old_y, int x, int y,
SDL_Rect * update_rect); SDL_Rect * update_rect);
void example_line_callback(void *pointer, int which, SDL_Surface * canvas, void example_line_callback(void *pointer, int which, SDL_Surface * canvas,
SDL_Surface * snapshot, int x, int y); SDL_Surface * snapshot, int x, int y);
/* Setup Functions: */ /* Setup Functions: */
@ -154,13 +154,14 @@ int example_init(magic_api * api)
Use "api->data_directory" to figure out where our sounds should be. (The Use "api->data_directory" to figure out where our sounds should be. (The
"tp-magic-config --dataprefix" command would have told us when we installed "tp-magic-config --dataprefix" command would have told us when we installed
our plugin and its data.) our plugin and its data.)
*/
snprintf(filename, sizeof(filename), "%s/sounds/magic/%s", api->data_directory, snprintf(filename, sizeof(filename), "%s/sounds/magic/%s", api->data_directory,
sound_filenames[i]); sound_filenames[i]);
printf("Trying to load %s sound file\n", filename); printf("Trying to load %s sound file\n", filename);
// Try to load the file! /* Try to load the file! */
sound_effects[i] = Mix_LoadWAV(filename); sound_effects[i] = Mix_LoadWAV(filename);
} }
@ -168,80 +169,86 @@ int example_init(magic_api * api)
} }
// Report our tool count /*
// Report our tool count
// Tux Paint needs to know how many "Magic" tools we'll be providing.
// Return that number here. (We simply grab the value of "NUM_TOOLS"
// from our 'enum' above!)
//
// When Tux Paint is starting up and loading plugins, it will call
// some of the following setup functions once for each tool we report.
Tux Paint needs to know how many 'Magic' tools we'll be providing. Return
that number here. (We simply grab the value of 'NUM_TOOLS' from our 'enum'
above!)
When Tux Paint is starting up and loading plugins, it will call some of the
following setup functions once for each tool we report.
*/
int example_get_tool_count(magic_api * api) int example_get_tool_count(magic_api * api)
{ {
return (NUM_TOOLS); return (NUM_TOOLS);
} }
// Load icons /*
// Load our icons
// When Tux Paint is starting up and loading plugins, it asks us to
// provide icons for the "Magic" tool buttons.
When Tux Paint is starting up and loading plugins, it asks us to provide icons for the 'Magic' tool buttons.
*/
SDL_Surface *example_get_icon(magic_api * api, int which) SDL_Surface *example_get_icon(magic_api * api, int which)
{ {
char fname[1024]; char filename[1024];
// Assemble the filename from the "icon_filenames[]" array into /*
// a full path to a real file. Assemble the filename from the "icon_filenames[]" array into a full path to
// a real file.
// Use "api->data_directory" to figure out where our sounds should be.
// (The "tp-magic-config --dataprefix" command would have told us when
// we installed our plugin and its data.)
//
// We use 'which' (which of our tools Tux Paint is asking about)
// as an index into the array.
snprintf(fname, sizeof(fname), "%s/images/magic/%s.png", Use "api->data_directory" to figure out where our sounds should be. (The
"tp-magic-config --dataprefix" command would have told us when we installed
our plugin and its data.)
We use "which" (which of our tools Tux Paint is asking about) as an index
into the array.
*/
snprintf(filename, sizeof(filename), "%s/images/magic/%s",
api->data_directory, icon_filenames[which]); api->data_directory, icon_filenames[which]);
printf("Trying to load %s icon\n", filename);
// Try to load the image, and return the results to Tux Paint: /* Try to load the image, and return the results to Tux Paint: */
return (IMG_Load(fname)); return (IMG_Load(filename));
} }
// Report our "Magic" tool names /*
// Report our 'Magic' tool names
// When Tux Paint is starting up and loading plugins, it asks us to
// provide names (labels) for the "Magic" tool buttons.
When Tux Paint is starting up and loading plugins, it asks us to provide
names (labels) for the 'Magic' tool buttons.
*/
char *example_get_name(magic_api * api, int which) char *example_get_name(magic_api * api, int which)
{ {
const char *our_name_english; const char *our_name_english;
const char *our_name_localized; const char *our_name_localized;
// Get our name from the "names[]" array. /*
// Get our name from the "tool_names[]" array.
// We use 'which' (which of our tools Tux Paint is asking about)
// as an index into the array.
our_name_english = names[which]; We use 'which' (which of our tools Tux Paint is asking about) as an index
into the array.
*/
our_name_english = tool_names[which];
// Return a localized (aka translated) version of our name, /*
// if possible. Return a localized (aka translated) version of our name, if possible.
//
// We send "gettext()" the English version of the name from our array.
We send "gettext()" the English version of the name from our array.
*/
our_name_localized = gettext(our_name_english); our_name_localized = gettext(our_name_english);
// Finally, duplicate the string into a new section of memory, and /*
// send it to Tux Paint. (Tux Paint keeps track of the string and Finally, duplicate the string into a new section of memory, and send it to
// will free it for us, so we have one less thing to keep track of.) Tux Paint. (Tux Paint keeps track of the string and will free it for us,
so we have one less thing to keep track of.)
*/
return (strdup(our_name_localized)); return (strdup(our_name_localized));
} }
@ -306,9 +313,10 @@ char *example_get_description(magic_api * api, int which, int mode)
int example_requires_colors(magic_api * api, int which) int example_requires_colors(magic_api * api, int which)
{ {
// Both of our tools accept colors, so we're always returning '1' (for 'true') if (which == TOOL_ONE)
return 1;
return 1; else
return 0;
} }
@ -316,8 +324,10 @@ int example_requires_colors(magic_api * api, int which)
int example_modes(magic_api * api, int which) int example_modes(magic_api * api, int which)
{ {
// Both of our tools are painted (neither affect the full-screen), so we're /*
always returning 'MODE_PAINT' Both of our tools are painted (neither affect the full-screen), so we're
always returning 'MODE_PAINT'
*/
return MODE_PAINT; return MODE_PAINT;
} }
@ -347,114 +357,130 @@ void example_shutdown(magic_api * api)
/* Functions that respond to events in Tux Paint: */ /* Functions that respond to events in Tux Paint: */
/* ---------------------------------------------------------------------- */ /* ---------------------------------------------------------------------- */
// Affect the canvas on click: /* Affect the canvas on click: */
void void
example_click(magic_api * api, int which, int mode, example_click(magic_api * api, int which, int mode,
SDL_Surface * canvas, SDL_Surface * snapshot, int x, int y, SDL_Surface * canvas, SDL_Surface * snapshot, int x, int y,
SDL_Rect * update_rect) SDL_Rect * update_rect)
{ {
// In our case, a single click (which is also the start of a drag!) /*
// is identical to what dragging does, but just at one point, rather In our case, a single click (which is also the start of a drag!) is
// than across a line. identical to what dragging does, but just at one point, rather than across
// a line.
// So we 'cheat' here, by calling our draw() function with
// (x,y) for both the beginning and end points of a line. So we 'cheat' here, by calling our "example_draw()" function with (x,y) for
both the beginning and end points of a line.
*/
example_drag(api, which, canvas, snapshot, x, y, x, y, update_rect); example_drag(api, which, canvas, snapshot, x, y, x, y, update_rect);
} }
// Affect the canvas on drag: /* Affect the canvas on drag: */
void void
example_drag(magic_api * api, int which, SDL_Surface * canvas, example_drag(magic_api * api, int which,
SDL_Surface * snapshot, int ox, int oy, int x, int y, SDL_Surface * canvas, SDL_Surface * snapshot,
int old_x, int old_y, int x, int y,
SDL_Rect * update_rect) SDL_Rect * update_rect)
{ {
// Call Tux Paint's "line()" function. /*
// Call Tux Paint's "line()" (line-traversing) function.
// It will calculate a straight line between (ox,ox) and (x,y).
// Every N steps along that line (in this case, N is '1'), it
// will call _our_ function, "example_line_callback()", and send
// the current X,Y coordinates along the line, as well as other
// useful things (which of our "Magic" tools is being used and
// the current and snapshot canvases).
api->line((void *) api, which, canvas, snapshot, ox, oy, x, y, 1, It will calculate a straight line between (old_x,old_y) and (x,y). Every
N steps along that line (in this case, N is '1'), it will call _our_
function, "example_line_callback()", and send the current X,Y
coordinates along the line, as well as other useful things (which of our
'Magic' tools is being used and the current and snapshot canvases).
*/
api->line((void *) api, which, canvas, snapshot,
old_x, old_y, x, y, 1,
example_line_callback); example_line_callback);
/*
If we need to, swap the X and/or Y values, so that the coordinates
(old_x,old_y) is always the top left, and the coordinates (x,y) is
always the bottom right, so the values we put inside "update_rect" make
sense:
*/
// If we need to, swap the X and/or Y values, so that if (old_x > x)
// (ox,oy) is always the top left, and (x,y) is always the bottom right,
// so the values we put inside "update_rect" make sense:
if (ox > x)
{ {
int tmp = ox; int temp = old_x;
ox = x; old_x = x;
x = tmp; x = temp;
} }
if (oy > y) if (old_y > y)
{ {
int tmp = oy; int temp = old_y;
oy = y; old_y = y;
y = tmp; y = temp;
} }
// Fill in the elements of the "update_rect" SDL_Rect structure /*
// that Tux Paint is sharing with us. Fill in the elements of the "update_rect" SDL_Rect structure that Tux
Paint is sharing with us, therefore telling Tux Paint which part of the
canvas has been modified and should be updated.
*/
update_rect->x = ox - 4; update_rect->x = old_x - 4;
update_rect->y = oy - 4; update_rect->y = old_y - 4;
update_rect->w = (x + 4) - update_rect->x; update_rect->w = (x + 4) - update_rect->x;
update_rect->h = (y + 4) - update_rect->h; update_rect->h = (y + 4) - update_rect->y;
/*
Play the appropriate sound effect
// Play the appropriate sound effect We're calculating a value between 0-255 for where the mouse is
// horizontally across the canvas (0 is the left, ~128 is the center, 255
// We're calculating a value between 0-255 for where the mouse is is the right).
// across the canvas (0 is the left, ~128 is the center, 255 is the right).
//
// These are the exact values Tux Paint's "playsound()" wants,
// to determine what speaker to play the sound in.
// (So the sound will pan from speaker to speaker as you drag the
// mouse around the canvas!)
api->playsound(snd_effect[which], (x * 255) / canvas->w, // pan These are the exact values Tux Paint's "playsound()" wants, to determine
255); // distance what speaker to play the sound in. (So the sound will pan from speaker
to speaker as you drag the mouse around the canvas!)
*/
api->playsound(sound_effects[which],
(x * 255) / canvas->w, /* Left/right pan */
255 /* Near/far distance (loudness) */);
} }
// Affect the canvas on release: /* Affect the canvas on release: */
void void
example_release(magic_api * api, int which, example_release(magic_api * api, int which,
SDL_Surface * canvas, SDL_Surface * snapshot, int x, int y, SDL_Surface * canvas, SDL_Surface * snapshot, int x, int y,
SDL_Rect * update_rect) SDL_Rect * update_rect)
{ {
// Neither of our effects do anything special when the mouse is released /*
// from a click or click-and-drag, so there's no code here... Neither of our effects do anything special when the mouse is released
from a click or click-and-drag, so there's no code here...
*/
} }
// Accept colors /*
// Accept colors
// When any of our "Magic" tools are activated by the user,
// if that tool accepts colors, the current color selection is sent to us.
//
// Additionally, if one of our color-accepting tools is active when the
// user changes colors, we'll be informed of that, as well.
//
// The color comes in as RGB values.
When any of our 'Magig' tools are activated by the user, if that tool
accepts colors, the current color selection is sent to us.
Additionally, if one of our color-accepting tools is active when the user
changes their chosen, we'll be informed of that as well.
The color comes in as RGB (red, green, and blue) values from 0 (darkest) to
255 (brightest).
*/
void example_set_color(magic_api * api, Uint8 r, Uint8 g, Uint8 b) void example_set_color(magic_api * api, Uint8 r, Uint8 g, Uint8 b)
{ {
// We simply store the RGB values in the global variables we /*
// declared at the top of this file. We simply store the RGB values in the global variables we declared at
the top of this file.
*/
example_r = r; example_r = r;
example_g = g; example_g = g;
@ -465,114 +491,130 @@ void example_set_color(magic_api * api, Uint8 r, Uint8 g, Uint8 b)
/* The Magic Effect Routines! */ /* The Magic Effect Routines! */
/* ---------------------------------------------------------------------- */ /* ---------------------------------------------------------------------- */
// Our "callback" function /*
// Our 'callback' function
// We do the 'work' in this callback. Our plugin file has just one.
// Some "Magic" tool plugins may have more, depending on the tools they're
// providing. Some have none (since they're not click-and-drag
// painting-style tools).
//
// Our callback function gets called once for every point along a line between
// the mouse's previous and current position, as it's being dragged.
//
// It pays attention to 'which' to determine which of our plugin's tools
// is currently selected.
void example_line_callback(void *ptr, int which, SDL_Surface * canvas, We do the 'work' in this callback. Our plugin file has just one. Some
SDL_Surface * snapshot, int x, int y) 'Magic' tool plugins may have more, depending on the tools they're
providing. Some have none (since they're not click-and-drag painting-style
tools).
Our callback function gets called once for every point along a line between
the mouse's previous and current position, as it's being dragged.
Our callback pays attention to 'which' to determine which of our plugin's
tools is currently selected.
*/
void example_line_callback(void *pointer, int which, SDL_Surface * canvas,
SDL_Surface * snapshot, int x, int y)
{ {
// For technical reasons, we can't accept a pointer to the "magic_api" /*
// struct, like the other functions do. For technical reasons, we can't accept a pointer to the Tux Paint API's
// "magic_api" struct, like the other functions do.
// Instead, we receive a 'generic' pointer (a "void *").
// The line below declares a local "magic_api" pointer variable called "api", Instead, we receive a 'generic' pointer (a "void *"). The line below
// and then assigns it to the value of the 'generic' pointer we received. declares a local "magic_api" pointer variable called "api", and then
// assigns it to the value of the 'generic' pointer we received.
// (The "(magic_api *)" casts the generic pointer into the 'type' of
// pointer we want, a pointer to a "magic_api".) The "(magic_api *)" seen below casts the generic "void *" pointer into
magic_api *api = (magic_api *) ptr; the 'type' of pointer we want, a pointer to a "magic_api" struct.)
*/
magic_api *api = (magic_api *) pointer;
int xx, yy; int xx, yy;
/*
// This function handles both of our tools, so we need to check which This function handles both of our tools, so we need to check which is
// is being used right now. We compare the 'which' argument that being used right now. We compare the 'which' argument that Tux Paint
// Tux Paint sends to us with the values we enumerated above. sends to us with the values we enumerated above.
*/
if (which == TOOL_ONE) if (which == TOOL_ONE)
{ {
// Tool number 1 simply draws a single pixel at the (x,y) location. /*
// It's a 1x1 pixel brush Tool number 1 simply draws a single pixel at the (x,y) location. It acts
as a 1x1 pixel brush.
*/
api->putpixel(canvas, x, y, api->putpixel(canvas, x, y,
SDL_MapRGB(canvas->format, example_r, example_g, SDL_MapRGB(canvas->format,
example_b)); example_r, example_g, example_b));
// We use "SDL_MapRGB()" to convert the RGB value we receive from Tux Paint /*
// for the user's current color selection to a 'Uint32' pixel value We use "SDL_MapRGB()" to convert the RGB value we receive from Tux Paint
// we can send to Tux Paint's "putpixel()" function. for the user's current color selection to a 'Uint32' pixel value we can
send to Tux Paint's "putpixel()" function.
*/
} }
else if (which == TOOL_TWO) else if (which == TOOL_TWO)
{ {
// Tool number 2 copies an 8x8 square of pixels from the opposite side /*
// of the canvas and puts it under the cursor Tool number 2 copies an 8x8 square of pixels from the opposite side of
the canvas and puts it under the cursor.
*/
for (yy = -4; yy < 4; yy++) for (yy = -4; yy < 4; yy++)
{ {
for (xx = -4; xx < 4; xx++) for (xx = -4; xx < 4; xx++)
{ {
api->putpixel(canvas, x + xx, y + yy, api->putpixel(canvas, x + xx, y + yy,
api->getpixel(snapshot, canvas->w - x - xx, api->getpixel(snapshot,
canvas->h - y - yy)); snapshot->w - x - xx,
snapshot->h - y - yy));
// We simply use Tux Paint's "getpixel()" routine to pull pixel /*
// values from the 'snapshot', and then "putpixel()" to draw them Here we have simply use Tux Paint's "getpixel()" routine to pull pixel
// right into the 'canvas'. values from the 'snapshot', and then "putpixel()" to draw them right
into the 'snapshot'.
// Note: putpixel() and getpixel() are safe to use, even if your Note: putpixel() and getpixel() are safe to use, even if your X,Y values
// X,Y values are outside of the SDL surface (e.g., negative, or are outside of the SDL surface (e.g., negative, or greater than the
// greater than the surface's width or height). surface's width and/or height).
*/
} }
} }
} }
} }
// Switch-In event /*
// Switch-In event
// This happens whenever a Magic tool is enabled, either because the
// user just selected it, or they just came back to "Magic" after using
// another tool (e.g., Brush or Text), and this was the most-recently
// selected Magic tool.
//
// (This also applies to momentary tools, like
// Undo and Redo, and image-changing tools such as New and Open.)
//
// It also happens when a Magic tool's mode changes (it first
// receives a 'switchout()', below, for the old mode).
//
// Our example doesn't do anything when we switch to, or away from, our
// Magic tools, so we just do nothing here.
This happens whenever a Magic tool is enabled, either because the user just
selected it, or they just came back to 'Magic' after using another tool
(e.g., Brush or Text), and this was the most-recently selected Magic tool.
(This also applies to momentary tools, like Undo and Redo, and
image-changing tools such as New and Open.)
It also happens when a Magic tool's mode changes (we will first receive a
call to 'example_switchout()', below, for the old mode).
Our example doesn't do anything when we switch to, or away from, our Magic
tools, so we just do nothing here.
*/
void example_switchin(magic_api * api, int which, int mode, void example_switchin(magic_api * api, int which, int mode,
SDL_Surface * canvas) SDL_Surface * canvas)
{ {
} }
// Switch-Out event /*
// Switch-Out event
// This happens whenever a Magic tool is disabled, either because the
// user selected a different Magic tool, or they selected a completely
// different tool (e.g., Brush or Text).
//
// (This also applies to momentary tools, like Undo and Redo, and
// image-changing tools such as New and Open, in which case the
// switchin() function will be called moments later.)
//
// It also happens when a Magic tool's mode changes (it then
// receives a 'switchin()', above, for the new mode).
//
// Our example doesn't do anything when we switch to, or away from, our
// Magic tools, so we just do nothing here.
This happens whenever a Magic tool is disabled, either because the user
selected a different Magic tool, or they selected a completely different
tool (e.g., Brush or Text).
(This also applies to momentary tools, like Undo and Redo, and
image-changing tools such as New and Open.)
(And in that case, our example_switchin() function will be called moments
later.
It also happens when a Magic tool's mode changes (we will then receive a
call to 'example_switchin()', above, for the new mode).
Our example doesn't do anything when we switch to, or away from, our Magic
tools, so we just do nothing here.
*/
void example_switchout(magic_api * api, int which, int mode, void example_switchout(magic_api * api, int which, int mode,
SDL_Surface * canvas) SDL_Surface * canvas)
{ {

432
docs/ja_JP.UTF-8/html/tp_magic_example.c
View file

@ -1,7 +1,7 @@
/* tp_magic_example.c /* tp_magic_example.c
An example of a "Magic" tool plugin for Tux Paint An example of a "Magic" tool plugin for Tux Paint
2022年10月18日 2022年10月19日
*/ */
@ -26,12 +26,12 @@
enum enum
{ {
TOOL_ONE, // Becomes '0' TOOL_ONE, // Becomes '0'
TOOL_ONE, // Becomes '1' TOOL_TWO, // Becomes '1'
NUM_TOOLS // Becomes '2' NUM_TOOLS // Becomes '2'
}; };
/* A list of filenames for sounds and icons to load at startup: */ /* Lists of filenames for sounds and icons to load at startup: */
const char *sound_filenames[NUM_TOOLS] = { const char *sound_filenames[NUM_TOOLS] = {
"tool_one.wav", "tool_one.wav",
@ -61,7 +61,7 @@ const char *tool_names[NUM_TOOLS] = {
/* How to group the tools with other similar tools, within the 'Magic' selector: */ /* How to group the tools with other similar tools, within the 'Magic' selector: */
const int tool_groups[$NUM_TOOLS] = { const int tool_groups[NUM_TOOLS] = {
MAGIC_TYPE_PAINTING, MAGIC_TYPE_PAINTING,
MAGIC_TYPE_DISTORTS MAGIC_TYPE_DISTORTS
}; };
@ -83,7 +83,7 @@ const char *tool_descriptions[NUM_TOOLS] = {
Mix_Chunk *sound_effects[NUM_TOOLS]; Mix_Chunk *sound_effects[NUM_TOOLS];
/* The current color (an "RGB" -- red, green, blue -- value) the user has selected in Tux Paint: */ /* The current color (an "RGB" -- red, green, blue -- value) the user has selected in Tux Paint: */
Uint8 example_r, $example_g, $example_b; Uint8 example_r, example_g, example_b;
/* Our local function prototypes: */ /* Our local function prototypes: */
@ -97,11 +97,11 @@ _before_ them.
*/ */
void example_drag(magic_api * api, int which, SDL_Surface * canvas, void example_drag(magic_api * api, int which, SDL_Surface * canvas,
SDL_Surface * snapshot, int ox, int oy, int x, int y, SDL_Surface * snapshot, int old_x, int old_y, int x, int y,
SDL_Rect * update_rect); SDL_Rect * update_rect);
void example_line_callback(void *pointer, int which, SDL_Surface * canvas, void example_line_callback(void *pointer, int which, SDL_Surface * canvas,
SDL_Surface * snapshot, int x, int y); SDL_Surface * snapshot, int x, int y);
/* Setup Functions: */ /* Setup Functions: */
@ -154,13 +154,14 @@ int example_init(magic_api * api)
Use "api->data_directory" to figure out where our sounds should be. (The Use "api->data_directory" to figure out where our sounds should be. (The
"tp-magic-config --dataprefix" command would have told us when we installed "tp-magic-config --dataprefix" command would have told us when we installed
our plugin and its data.) our plugin and its data.)
*/
snprintf(filename, sizeof(filename), "%s/sounds/magic/%s", api->data_directory, snprintf(filename, sizeof(filename), "%s/sounds/magic/%s", api->data_directory,
sound_filenames[i]); sound_filenames[i]);
printf("Trying to load %s sound file\n", filename); printf("Trying to load %s sound file\n", filename);
// Try to load the file! /* Try to load the file! */
sound_effects[i] = Mix_LoadWAV(filename); sound_effects[i] = Mix_LoadWAV(filename);
} }
@ -168,80 +169,86 @@ int example_init(magic_api * api)
} }
// Report our tool count /*
// Report our tool count
// Tux Paint needs to know how many "Magic" tools we'll be providing.
// Return that number here. (We simply grab the value of "NUM_TOOLS"
// from our 'enum' above!)
//
// When Tux Paint is starting up and loading plugins, it will call
// some of the following setup functions once for each tool we report.
Tux Paint needs to know how many 'Magic' tools we'll be providing. Return
that number here. (We simply grab the value of 'NUM_TOOLS' from our 'enum'
above!)
When Tux Paint is starting up and loading plugins, it will call some of the
following setup functions once for each tool we report.
*/
int example_get_tool_count(magic_api * api) int example_get_tool_count(magic_api * api)
{ {
return (NUM_TOOLS); return (NUM_TOOLS);
} }
// Load icons /*
// Load our icons
// When Tux Paint is starting up and loading plugins, it asks us to
// provide icons for the "Magic" tool buttons.
When Tux Paint is starting up and loading plugins, it asks us to provide icons for the 'Magic' tool buttons.
*/
SDL_Surface *example_get_icon(magic_api * api, int which) SDL_Surface *example_get_icon(magic_api * api, int which)
{ {
char fname[1024]; char filename[1024];
// Assemble the filename from the "icon_filenames[]" array into /*
// a full path to a real file. Assemble the filename from the "icon_filenames[]" array into a full path to
// a real file.
// Use "api->data_directory" to figure out where our sounds should be.
// (The "tp-magic-config --dataprefix" command would have told us when
// we installed our plugin and its data.)
//
// We use 'which' (which of our tools Tux Paint is asking about)
// as an index into the array.
snprintf(fname, sizeof(fname), "%s/images/magic/%s.png", Use "api->data_directory" to figure out where our sounds should be. (The
"tp-magic-config --dataprefix" command would have told us when we installed
our plugin and its data.)
We use "which" (which of our tools Tux Paint is asking about) as an index
into the array.
*/
snprintf(filename, sizeof(filename), "%s/images/magic/%s",
api->data_directory, icon_filenames[which]); api->data_directory, icon_filenames[which]);
printf("Trying to load %s icon\n", filename);
// Try to load the image, and return the results to Tux Paint: /* Try to load the image, and return the results to Tux Paint: */
return (IMG_Load(fname)); return (IMG_Load(filename));
} }
// Report our "Magic" tool names /*
// Report our 'Magic' tool names
// When Tux Paint is starting up and loading plugins, it asks us to
// provide names (labels) for the "Magic" tool buttons.
When Tux Paint is starting up and loading plugins, it asks us to provide
names (labels) for the 'Magic' tool buttons.
*/
char *example_get_name(magic_api * api, int which) char *example_get_name(magic_api * api, int which)
{ {
const char *our_name_english; const char *our_name_english;
const char *our_name_localized; const char *our_name_localized;
// Get our name from the "names[]" array. /*
// Get our name from the "tool_names[]" array.
// We use 'which' (which of our tools Tux Paint is asking about)
// as an index into the array.
our_name_english = names[which]; We use 'which' (which of our tools Tux Paint is asking about) as an index
into the array.
*/
our_name_english = tool_names[which];
// Return a localized (aka translated) version of our name, /*
// if possible. Return a localized (aka translated) version of our name, if possible.
//
// We send "gettext()" the English version of the name from our array.
We send "gettext()" the English version of the name from our array.
*/
our_name_localized = gettext(our_name_english); our_name_localized = gettext(our_name_english);
// Finally, duplicate the string into a new section of memory, and /*
// send it to Tux Paint. (Tux Paint keeps track of the string and Finally, duplicate the string into a new section of memory, and send it to
// will free it for us, so we have one less thing to keep track of.) Tux Paint. (Tux Paint keeps track of the string and will free it for us,
so we have one less thing to keep track of.)
*/
return (strdup(our_name_localized)); return (strdup(our_name_localized));
} }
@ -306,9 +313,10 @@ char *example_get_description(magic_api * api, int which, int mode)
int example_requires_colors(magic_api * api, int which) int example_requires_colors(magic_api * api, int which)
{ {
// Both of our tools accept colors, so we're always returning '1' (for 'true') if (which == TOOL_ONE)
return 1;
return 1; else
return 0;
} }
@ -316,8 +324,10 @@ int example_requires_colors(magic_api * api, int which)
int example_modes(magic_api * api, int which) int example_modes(magic_api * api, int which)
{ {
// Both of our tools are painted (neither affect the full-screen), so we're /*
always returning 'MODE_PAINT' Both of our tools are painted (neither affect the full-screen), so we're
always returning 'MODE_PAINT'
*/
return MODE_PAINT; return MODE_PAINT;
} }
@ -347,114 +357,130 @@ void example_shutdown(magic_api * api)
/* Functions that respond to events in Tux Paint: */ /* Functions that respond to events in Tux Paint: */
/* ---------------------------------------------------------------------- */ /* ---------------------------------------------------------------------- */
// Affect the canvas on click: /* Affect the canvas on click: */
void void
example_click(magic_api * api, int which, int mode, example_click(magic_api * api, int which, int mode,
SDL_Surface * canvas, SDL_Surface * snapshot, int x, int y, SDL_Surface * canvas, SDL_Surface * snapshot, int x, int y,
SDL_Rect * update_rect) SDL_Rect * update_rect)
{ {
// In our case, a single click (which is also the start of a drag!) /*
// is identical to what dragging does, but just at one point, rather In our case, a single click (which is also the start of a drag!) is
// than across a line. identical to what dragging does, but just at one point, rather than across
// a line.
// So we 'cheat' here, by calling our draw() function with
// (x,y) for both the beginning and end points of a line. So we 'cheat' here, by calling our "example_draw()" function with (x,y) for
both the beginning and end points of a line.
*/
example_drag(api, which, canvas, snapshot, x, y, x, y, update_rect); example_drag(api, which, canvas, snapshot, x, y, x, y, update_rect);
} }
// Affect the canvas on drag: /* Affect the canvas on drag: */
void void
example_drag(magic_api * api, int which, SDL_Surface * canvas, example_drag(magic_api * api, int which,
SDL_Surface * snapshot, int ox, int oy, int x, int y, SDL_Surface * canvas, SDL_Surface * snapshot,
int old_x, int old_y, int x, int y,
SDL_Rect * update_rect) SDL_Rect * update_rect)
{ {
// Call Tux Paint's "line()" function. /*
// Call Tux Paint's "line()" (line-traversing) function.
// It will calculate a straight line between (ox,ox) and (x,y).
// Every N steps along that line (in this case, N is '1'), it
// will call _our_ function, "example_line_callback()", and send
// the current X,Y coordinates along the line, as well as other
// useful things (which of our "Magic" tools is being used and
// the current and snapshot canvases).
api->line((void *) api, which, canvas, snapshot, ox, oy, x, y, 1, It will calculate a straight line between (old_x,old_y) and (x,y). Every
N steps along that line (in this case, N is '1'), it will call _our_
function, "example_line_callback()", and send the current X,Y
coordinates along the line, as well as other useful things (which of our
'Magic' tools is being used and the current and snapshot canvases).
*/
api->line((void *) api, which, canvas, snapshot,
old_x, old_y, x, y, 1,
example_line_callback); example_line_callback);
/*
If we need to, swap the X and/or Y values, so that the coordinates
(old_x,old_y) is always the top left, and the coordinates (x,y) is
always the bottom right, so the values we put inside "update_rect" make
sense:
*/
// If we need to, swap the X and/or Y values, so that if (old_x > x)
// (ox,oy) is always the top left, and (x,y) is always the bottom right,
// so the values we put inside "update_rect" make sense:
if (ox > x)
{ {
int tmp = ox; int temp = old_x;
ox = x; old_x = x;
x = tmp; x = temp;
} }
if (oy > y) if (old_y > y)
{ {
int tmp = oy; int temp = old_y;
oy = y; old_y = y;
y = tmp; y = temp;
} }
// Fill in the elements of the "update_rect" SDL_Rect structure /*
// that Tux Paint is sharing with us. Fill in the elements of the "update_rect" SDL_Rect structure that Tux
Paint is sharing with us, therefore telling Tux Paint which part of the
canvas has been modified and should be updated.
*/
update_rect->x = ox - 4; update_rect->x = old_x - 4;
update_rect->y = oy - 4; update_rect->y = old_y - 4;
update_rect->w = (x + 4) - update_rect->x; update_rect->w = (x + 4) - update_rect->x;
update_rect->h = (y + 4) - update_rect->h; update_rect->h = (y + 4) - update_rect->y;
/*
Play the appropriate sound effect
// Play the appropriate sound effect We're calculating a value between 0-255 for where the mouse is
// horizontally across the canvas (0 is the left, ~128 is the center, 255
// We're calculating a value between 0-255 for where the mouse is is the right).
// across the canvas (0 is the left, ~128 is the center, 255 is the right).
//
// These are the exact values Tux Paint's "playsound()" wants,
// to determine what speaker to play the sound in.
// (So the sound will pan from speaker to speaker as you drag the
// mouse around the canvas!)
api->playsound(snd_effect[which], (x * 255) / canvas->w, // pan These are the exact values Tux Paint's "playsound()" wants, to determine
255); // distance what speaker to play the sound in. (So the sound will pan from speaker
to speaker as you drag the mouse around the canvas!)
*/
api->playsound(sound_effects[which],
(x * 255) / canvas->w, /* Left/right pan */
255 /* Near/far distance (loudness) */);
} }
// Affect the canvas on release: /* Affect the canvas on release: */
void void
example_release(magic_api * api, int which, example_release(magic_api * api, int which,
SDL_Surface * canvas, SDL_Surface * snapshot, int x, int y, SDL_Surface * canvas, SDL_Surface * snapshot, int x, int y,
SDL_Rect * update_rect) SDL_Rect * update_rect)
{ {
// Neither of our effects do anything special when the mouse is released /*
// from a click or click-and-drag, so there's no code here... Neither of our effects do anything special when the mouse is released
from a click or click-and-drag, so there's no code here...
*/
} }
// Accept colors /*
// Accept colors
// When any of our "Magic" tools are activated by the user,
// if that tool accepts colors, the current color selection is sent to us.
//
// Additionally, if one of our color-accepting tools is active when the
// user changes colors, we'll be informed of that, as well.
//
// The color comes in as RGB values.
When any of our 'Magig' tools are activated by the user, if that tool
accepts colors, the current color selection is sent to us.
Additionally, if one of our color-accepting tools is active when the user
changes their chosen, we'll be informed of that as well.
The color comes in as RGB (red, green, and blue) values from 0 (darkest) to
255 (brightest).
*/
void example_set_color(magic_api * api, Uint8 r, Uint8 g, Uint8 b) void example_set_color(magic_api * api, Uint8 r, Uint8 g, Uint8 b)
{ {
// We simply store the RGB values in the global variables we /*
// declared at the top of this file. We simply store the RGB values in the global variables we declared at
the top of this file.
*/
example_r = r; example_r = r;
example_g = g; example_g = g;
@ -465,114 +491,130 @@ void example_set_color(magic_api * api, Uint8 r, Uint8 g, Uint8 b)
/* The Magic Effect Routines! */ /* The Magic Effect Routines! */
/* ---------------------------------------------------------------------- */ /* ---------------------------------------------------------------------- */
// Our "callback" function /*
// Our 'callback' function
// We do the 'work' in this callback. Our plugin file has just one.
// Some "Magic" tool plugins may have more, depending on the tools they're
// providing. Some have none (since they're not click-and-drag
// painting-style tools).
//
// Our callback function gets called once for every point along a line between
// the mouse's previous and current position, as it's being dragged.
//
// It pays attention to 'which' to determine which of our plugin's tools
// is currently selected.
void example_line_callback(void *ptr, int which, SDL_Surface * canvas, We do the 'work' in this callback. Our plugin file has just one. Some
SDL_Surface * snapshot, int x, int y) 'Magic' tool plugins may have more, depending on the tools they're
providing. Some have none (since they're not click-and-drag painting-style
tools).
Our callback function gets called once for every point along a line between
the mouse's previous and current position, as it's being dragged.
Our callback pays attention to 'which' to determine which of our plugin's
tools is currently selected.
*/
void example_line_callback(void *pointer, int which, SDL_Surface * canvas,
SDL_Surface * snapshot, int x, int y)
{ {
// For technical reasons, we can't accept a pointer to the "magic_api" /*
// struct, like the other functions do. For technical reasons, we can't accept a pointer to the Tux Paint API's
// "magic_api" struct, like the other functions do.
// Instead, we receive a 'generic' pointer (a "void *").
// The line below declares a local "magic_api" pointer variable called "api", Instead, we receive a 'generic' pointer (a "void *"). The line below
// and then assigns it to the value of the 'generic' pointer we received. declares a local "magic_api" pointer variable called "api", and then
// assigns it to the value of the 'generic' pointer we received.
// (The "(magic_api *)" casts the generic pointer into the 'type' of
// pointer we want, a pointer to a "magic_api".) The "(magic_api *)" seen below casts the generic "void *" pointer into
magic_api *api = (magic_api *) ptr; the 'type' of pointer we want, a pointer to a "magic_api" struct.)
*/
magic_api *api = (magic_api *) pointer;
int xx, yy; int xx, yy;
/*
// This function handles both of our tools, so we need to check which This function handles both of our tools, so we need to check which is
// is being used right now. We compare the 'which' argument that being used right now. We compare the 'which' argument that Tux Paint
// Tux Paint sends to us with the values we enumerated above. sends to us with the values we enumerated above.
*/
if (which == TOOL_ONE) if (which == TOOL_ONE)
{ {
// Tool number 1 simply draws a single pixel at the (x,y) location. /*
// It's a 1x1 pixel brush Tool number 1 simply draws a single pixel at the (x,y) location. It acts
as a 1x1 pixel brush.
*/
api->putpixel(canvas, x, y, api->putpixel(canvas, x, y,
SDL_MapRGB(canvas->format, example_r, example_g, SDL_MapRGB(canvas->format,
example_b)); example_r, example_g, example_b));
// We use "SDL_MapRGB()" to convert the RGB value we receive from Tux Paint /*
// for the user's current color selection to a 'Uint32' pixel value We use "SDL_MapRGB()" to convert the RGB value we receive from Tux Paint
// we can send to Tux Paint's "putpixel()" function. for the user's current color selection to a 'Uint32' pixel value we can
send to Tux Paint's "putpixel()" function.
*/
} }
else if (which == TOOL_TWO) else if (which == TOOL_TWO)
{ {
// Tool number 2 copies an 8x8 square of pixels from the opposite side /*
// of the canvas and puts it under the cursor Tool number 2 copies an 8x8 square of pixels from the opposite side of
the canvas and puts it under the cursor.
*/
for (yy = -4; yy < 4; yy++) for (yy = -4; yy < 4; yy++)
{ {
for (xx = -4; xx < 4; xx++) for (xx = -4; xx < 4; xx++)
{ {
api->putpixel(canvas, x + xx, y + yy, api->putpixel(canvas, x + xx, y + yy,
api->getpixel(snapshot, canvas->w - x - xx, api->getpixel(snapshot,
canvas->h - y - yy)); snapshot->w - x - xx,
snapshot->h - y - yy));
// We simply use Tux Paint's "getpixel()" routine to pull pixel /*
// values from the 'snapshot', and then "putpixel()" to draw them Here we have simply use Tux Paint's "getpixel()" routine to pull pixel
// right into the 'canvas'. values from the 'snapshot', and then "putpixel()" to draw them right
into the 'snapshot'.
// Note: putpixel() and getpixel() are safe to use, even if your Note: putpixel() and getpixel() are safe to use, even if your X,Y values
// X,Y values are outside of the SDL surface (e.g., negative, or are outside of the SDL surface (e.g., negative, or greater than the
// greater than the surface's width or height). surface's width and/or height).
*/
} }
} }
} }
} }
// Switch-In event /*
// Switch-In event
// This happens whenever a Magic tool is enabled, either because the
// user just selected it, or they just came back to "Magic" after using
// another tool (e.g., Brush or Text), and this was the most-recently
// selected Magic tool.
//
// (This also applies to momentary tools, like
// Undo and Redo, and image-changing tools such as New and Open.)
//
// It also happens when a Magic tool's mode changes (it first
// receives a 'switchout()', below, for the old mode).
//
// Our example doesn't do anything when we switch to, or away from, our
// Magic tools, so we just do nothing here.
This happens whenever a Magic tool is enabled, either because the user just
selected it, or they just came back to 'Magic' after using another tool
(e.g., Brush or Text), and this was the most-recently selected Magic tool.
(This also applies to momentary tools, like Undo and Redo, and
image-changing tools such as New and Open.)
It also happens when a Magic tool's mode changes (we will first receive a
call to 'example_switchout()', below, for the old mode).
Our example doesn't do anything when we switch to, or away from, our Magic
tools, so we just do nothing here.
*/
void example_switchin(magic_api * api, int which, int mode, void example_switchin(magic_api * api, int which, int mode,
SDL_Surface * canvas) SDL_Surface * canvas)
{ {
} }
// Switch-Out event /*
// Switch-Out event
// This happens whenever a Magic tool is disabled, either because the
// user selected a different Magic tool, or they selected a completely
// different tool (e.g., Brush or Text).
//
// (This also applies to momentary tools, like Undo and Redo, and
// image-changing tools such as New and Open, in which case the
// switchin() function will be called moments later.)
//
// It also happens when a Magic tool's mode changes (it then
// receives a 'switchin()', above, for the new mode).
//
// Our example doesn't do anything when we switch to, or away from, our
// Magic tools, so we just do nothing here.
This happens whenever a Magic tool is disabled, either because the user
selected a different Magic tool, or they selected a completely different
tool (e.g., Brush or Text).
(This also applies to momentary tools, like Undo and Redo, and
image-changing tools such as New and Open.)
(And in that case, our example_switchin() function will be called moments
later.
It also happens when a Magic tool's mode changes (we will then receive a
call to 'example_switchin()', above, for the new mode).
Our example doesn't do anything when we switch to, or away from, our Magic
tools, so we just do nothing here.
*/
void example_switchout(magic_api * api, int which, int mode, void example_switchout(magic_api * api, int which, int mode,
SDL_Surface * canvas) SDL_Surface * canvas)
{ {

432
docs/ja_JP.UTF-8/tp_magic_example.c
View file

@ -1,7 +1,7 @@
/* tp_magic_example.c /* tp_magic_example.c
An example of a "Magic" tool plugin for Tux Paint An example of a "Magic" tool plugin for Tux Paint
2022年10月18日 2022年10月19日
*/ */
@ -26,12 +26,12 @@
enum enum
{ {
TOOL_ONE, // Becomes '0' TOOL_ONE, // Becomes '0'
TOOL_ONE, // Becomes '1' TOOL_TWO, // Becomes '1'
NUM_TOOLS // Becomes '2' NUM_TOOLS // Becomes '2'
}; };
/* A list of filenames for sounds and icons to load at startup: */ /* Lists of filenames for sounds and icons to load at startup: */
const char *sound_filenames[NUM_TOOLS] = { const char *sound_filenames[NUM_TOOLS] = {
"tool_one.wav", "tool_one.wav",
@ -61,7 +61,7 @@ const char *tool_names[NUM_TOOLS] = {
/* How to group the tools with other similar tools, within the 'Magic' selector: */ /* How to group the tools with other similar tools, within the 'Magic' selector: */
const int tool_groups[$NUM_TOOLS] = { const int tool_groups[NUM_TOOLS] = {
MAGIC_TYPE_PAINTING, MAGIC_TYPE_PAINTING,
MAGIC_TYPE_DISTORTS MAGIC_TYPE_DISTORTS
}; };
@ -83,7 +83,7 @@ const char *tool_descriptions[NUM_TOOLS] = {
Mix_Chunk *sound_effects[NUM_TOOLS]; Mix_Chunk *sound_effects[NUM_TOOLS];
/* The current color (an "RGB" -- red, green, blue -- value) the user has selected in Tux Paint: */ /* The current color (an "RGB" -- red, green, blue -- value) the user has selected in Tux Paint: */
Uint8 example_r, $example_g, $example_b; Uint8 example_r, example_g, example_b;
/* Our local function prototypes: */ /* Our local function prototypes: */
@ -97,11 +97,11 @@ _before_ them.
*/ */
void example_drag(magic_api * api, int which, SDL_Surface * canvas, void example_drag(magic_api * api, int which, SDL_Surface * canvas,
SDL_Surface * snapshot, int ox, int oy, int x, int y, SDL_Surface * snapshot, int old_x, int old_y, int x, int y,
SDL_Rect * update_rect); SDL_Rect * update_rect);
void example_line_callback(void *pointer, int which, SDL_Surface * canvas, void example_line_callback(void *pointer, int which, SDL_Surface * canvas,
SDL_Surface * snapshot, int x, int y); SDL_Surface * snapshot, int x, int y);
/* Setup Functions: */ /* Setup Functions: */
@ -154,13 +154,14 @@ int example_init(magic_api * api)
Use "api->data_directory" to figure out where our sounds should be. (The Use "api->data_directory" to figure out where our sounds should be. (The
"tp-magic-config --dataprefix" command would have told us when we installed "tp-magic-config --dataprefix" command would have told us when we installed
our plugin and its data.) our plugin and its data.)
*/
snprintf(filename, sizeof(filename), "%s/sounds/magic/%s", api->data_directory, snprintf(filename, sizeof(filename), "%s/sounds/magic/%s", api->data_directory,
sound_filenames[i]); sound_filenames[i]);
printf("Trying to load %s sound file\n", filename); printf("Trying to load %s sound file\n", filename);
// Try to load the file! /* Try to load the file! */
sound_effects[i] = Mix_LoadWAV(filename); sound_effects[i] = Mix_LoadWAV(filename);
} }
@ -168,80 +169,86 @@ int example_init(magic_api * api)
} }
// Report our tool count /*
// Report our tool count
// Tux Paint needs to know how many "Magic" tools we'll be providing.
// Return that number here. (We simply grab the value of "NUM_TOOLS"
// from our 'enum' above!)
//
// When Tux Paint is starting up and loading plugins, it will call
// some of the following setup functions once for each tool we report.
Tux Paint needs to know how many 'Magic' tools we'll be providing. Return
that number here. (We simply grab the value of 'NUM_TOOLS' from our 'enum'
above!)
When Tux Paint is starting up and loading plugins, it will call some of the
following setup functions once for each tool we report.
*/
int example_get_tool_count(magic_api * api) int example_get_tool_count(magic_api * api)
{ {
return (NUM_TOOLS); return (NUM_TOOLS);
} }
// Load icons /*
// Load our icons
// When Tux Paint is starting up and loading plugins, it asks us to
// provide icons for the "Magic" tool buttons.
When Tux Paint is starting up and loading plugins, it asks us to provide icons for the 'Magic' tool buttons.
*/
SDL_Surface *example_get_icon(magic_api * api, int which) SDL_Surface *example_get_icon(magic_api * api, int which)
{ {
char fname[1024]; char filename[1024];
// Assemble the filename from the "icon_filenames[]" array into /*
// a full path to a real file. Assemble the filename from the "icon_filenames[]" array into a full path to
// a real file.
// Use "api->data_directory" to figure out where our sounds should be.
// (The "tp-magic-config --dataprefix" command would have told us when
// we installed our plugin and its data.)
//
// We use 'which' (which of our tools Tux Paint is asking about)
// as an index into the array.
snprintf(fname, sizeof(fname), "%s/images/magic/%s.png", Use "api->data_directory" to figure out where our sounds should be. (The
"tp-magic-config --dataprefix" command would have told us when we installed
our plugin and its data.)
We use "which" (which of our tools Tux Paint is asking about) as an index
into the array.
*/
snprintf(filename, sizeof(filename), "%s/images/magic/%s",
api->data_directory, icon_filenames[which]); api->data_directory, icon_filenames[which]);
printf("Trying to load %s icon\n", filename);
// Try to load the image, and return the results to Tux Paint: /* Try to load the image, and return the results to Tux Paint: */
return (IMG_Load(fname)); return (IMG_Load(filename));
} }
// Report our "Magic" tool names /*
// Report our 'Magic' tool names
// When Tux Paint is starting up and loading plugins, it asks us to
// provide names (labels) for the "Magic" tool buttons.
When Tux Paint is starting up and loading plugins, it asks us to provide
names (labels) for the 'Magic' tool buttons.
*/
char *example_get_name(magic_api * api, int which) char *example_get_name(magic_api * api, int which)
{ {
const char *our_name_english; const char *our_name_english;
const char *our_name_localized; const char *our_name_localized;
// Get our name from the "names[]" array. /*
// Get our name from the "tool_names[]" array.
// We use 'which' (which of our tools Tux Paint is asking about)
// as an index into the array.
our_name_english = names[which]; We use 'which' (which of our tools Tux Paint is asking about) as an index
into the array.
*/
our_name_english = tool_names[which];
// Return a localized (aka translated) version of our name, /*
// if possible. Return a localized (aka translated) version of our name, if possible.
//
// We send "gettext()" the English version of the name from our array.
We send "gettext()" the English version of the name from our array.
*/
our_name_localized = gettext(our_name_english); our_name_localized = gettext(our_name_english);
// Finally, duplicate the string into a new section of memory, and /*
// send it to Tux Paint. (Tux Paint keeps track of the string and Finally, duplicate the string into a new section of memory, and send it to
// will free it for us, so we have one less thing to keep track of.) Tux Paint. (Tux Paint keeps track of the string and will free it for us,
so we have one less thing to keep track of.)
*/
return (strdup(our_name_localized)); return (strdup(our_name_localized));
} }
@ -306,9 +313,10 @@ char *example_get_description(magic_api * api, int which, int mode)
int example_requires_colors(magic_api * api, int which) int example_requires_colors(magic_api * api, int which)
{ {
// Both of our tools accept colors, so we're always returning '1' (for 'true') if (which == TOOL_ONE)
return 1;
return 1; else
return 0;
} }
@ -316,8 +324,10 @@ int example_requires_colors(magic_api * api, int which)
int example_modes(magic_api * api, int which) int example_modes(magic_api * api, int which)
{ {
// Both of our tools are painted (neither affect the full-screen), so we're /*
always returning 'MODE_PAINT' Both of our tools are painted (neither affect the full-screen), so we're
always returning 'MODE_PAINT'
*/
return MODE_PAINT; return MODE_PAINT;
} }
@ -347,114 +357,130 @@ void example_shutdown(magic_api * api)
/* Functions that respond to events in Tux Paint: */ /* Functions that respond to events in Tux Paint: */
/* ---------------------------------------------------------------------- */ /* ---------------------------------------------------------------------- */
// Affect the canvas on click: /* Affect the canvas on click: */
void void
example_click(magic_api * api, int which, int mode, example_click(magic_api * api, int which, int mode,
SDL_Surface * canvas, SDL_Surface * snapshot, int x, int y, SDL_Surface * canvas, SDL_Surface * snapshot, int x, int y,
SDL_Rect * update_rect) SDL_Rect * update_rect)
{ {
// In our case, a single click (which is also the start of a drag!) /*
// is identical to what dragging does, but just at one point, rather In our case, a single click (which is also the start of a drag!) is
// than across a line. identical to what dragging does, but just at one point, rather than across
// a line.
// So we 'cheat' here, by calling our draw() function with
// (x,y) for both the beginning and end points of a line. So we 'cheat' here, by calling our "example_draw()" function with (x,y) for
both the beginning and end points of a line.
*/
example_drag(api, which, canvas, snapshot, x, y, x, y, update_rect); example_drag(api, which, canvas, snapshot, x, y, x, y, update_rect);
} }
// Affect the canvas on drag: /* Affect the canvas on drag: */
void void
example_drag(magic_api * api, int which, SDL_Surface * canvas, example_drag(magic_api * api, int which,
SDL_Surface * snapshot, int ox, int oy, int x, int y, SDL_Surface * canvas, SDL_Surface * snapshot,
int old_x, int old_y, int x, int y,
SDL_Rect * update_rect) SDL_Rect * update_rect)
{ {
// Call Tux Paint's "line()" function. /*
// Call Tux Paint's "line()" (line-traversing) function.
// It will calculate a straight line between (ox,ox) and (x,y).
// Every N steps along that line (in this case, N is '1'), it
// will call _our_ function, "example_line_callback()", and send
// the current X,Y coordinates along the line, as well as other
// useful things (which of our "Magic" tools is being used and
// the current and snapshot canvases).
api->line((void *) api, which, canvas, snapshot, ox, oy, x, y, 1, It will calculate a straight line between (old_x,old_y) and (x,y). Every
N steps along that line (in this case, N is '1'), it will call _our_
function, "example_line_callback()", and send the current X,Y
coordinates along the line, as well as other useful things (which of our
'Magic' tools is being used and the current and snapshot canvases).
*/
api->line((void *) api, which, canvas, snapshot,
old_x, old_y, x, y, 1,
example_line_callback); example_line_callback);
/*
If we need to, swap the X and/or Y values, so that the coordinates
(old_x,old_y) is always the top left, and the coordinates (x,y) is
always the bottom right, so the values we put inside "update_rect" make
sense:
*/
// If we need to, swap the X and/or Y values, so that if (old_x > x)
// (ox,oy) is always the top left, and (x,y) is always the bottom right,
// so the values we put inside "update_rect" make sense:
if (ox > x)
{ {
int tmp = ox; int temp = old_x;
ox = x; old_x = x;
x = tmp; x = temp;
} }
if (oy > y) if (old_y > y)
{ {
int tmp = oy; int temp = old_y;
oy = y; old_y = y;
y = tmp; y = temp;
} }
// Fill in the elements of the "update_rect" SDL_Rect structure /*
// that Tux Paint is sharing with us. Fill in the elements of the "update_rect" SDL_Rect structure that Tux
Paint is sharing with us, therefore telling Tux Paint which part of the
canvas has been modified and should be updated.
*/
update_rect->x = ox - 4; update_rect->x = old_x - 4;
update_rect->y = oy - 4; update_rect->y = old_y - 4;
update_rect->w = (x + 4) - update_rect->x; update_rect->w = (x + 4) - update_rect->x;
update_rect->h = (y + 4) - update_rect->h; update_rect->h = (y + 4) - update_rect->y;
/*
Play the appropriate sound effect
// Play the appropriate sound effect We're calculating a value between 0-255 for where the mouse is
// horizontally across the canvas (0 is the left, ~128 is the center, 255
// We're calculating a value between 0-255 for where the mouse is is the right).
// across the canvas (0 is the left, ~128 is the center, 255 is the right).
//
// These are the exact values Tux Paint's "playsound()" wants,
// to determine what speaker to play the sound in.
// (So the sound will pan from speaker to speaker as you drag the
// mouse around the canvas!)
api->playsound(snd_effect[which], (x * 255) / canvas->w, // pan These are the exact values Tux Paint's "playsound()" wants, to determine
255); // distance what speaker to play the sound in. (So the sound will pan from speaker
to speaker as you drag the mouse around the canvas!)
*/
api->playsound(sound_effects[which],
(x * 255) / canvas->w, /* Left/right pan */
255 /* Near/far distance (loudness) */);
} }
// Affect the canvas on release: /* Affect the canvas on release: */
void void
example_release(magic_api * api, int which, example_release(magic_api * api, int which,
SDL_Surface * canvas, SDL_Surface * snapshot, int x, int y, SDL_Surface * canvas, SDL_Surface * snapshot, int x, int y,
SDL_Rect * update_rect) SDL_Rect * update_rect)
{ {
// Neither of our effects do anything special when the mouse is released /*
// from a click or click-and-drag, so there's no code here... Neither of our effects do anything special when the mouse is released
from a click or click-and-drag, so there's no code here...
*/
} }
// Accept colors /*
// Accept colors
// When any of our "Magic" tools are activated by the user,
// if that tool accepts colors, the current color selection is sent to us.
//
// Additionally, if one of our color-accepting tools is active when the
// user changes colors, we'll be informed of that, as well.
//
// The color comes in as RGB values.
When any of our 'Magig' tools are activated by the user, if that tool
accepts colors, the current color selection is sent to us.
Additionally, if one of our color-accepting tools is active when the user
changes their chosen, we'll be informed of that as well.
The color comes in as RGB (red, green, and blue) values from 0 (darkest) to
255 (brightest).
*/
void example_set_color(magic_api * api, Uint8 r, Uint8 g, Uint8 b) void example_set_color(magic_api * api, Uint8 r, Uint8 g, Uint8 b)
{ {
// We simply store the RGB values in the global variables we /*
// declared at the top of this file. We simply store the RGB values in the global variables we declared at
the top of this file.
*/
example_r = r; example_r = r;
example_g = g; example_g = g;
@ -465,114 +491,130 @@ void example_set_color(magic_api * api, Uint8 r, Uint8 g, Uint8 b)
/* The Magic Effect Routines! */ /* The Magic Effect Routines! */
/* ---------------------------------------------------------------------- */ /* ---------------------------------------------------------------------- */
// Our "callback" function /*
// Our 'callback' function
// We do the 'work' in this callback. Our plugin file has just one.
// Some "Magic" tool plugins may have more, depending on the tools they're
// providing. Some have none (since they're not click-and-drag
// painting-style tools).
//
// Our callback function gets called once for every point along a line between
// the mouse's previous and current position, as it's being dragged.
//
// It pays attention to 'which' to determine which of our plugin's tools
// is currently selected.
void example_line_callback(void *ptr, int which, SDL_Surface * canvas, We do the 'work' in this callback. Our plugin file has just one. Some
SDL_Surface * snapshot, int x, int y) 'Magic' tool plugins may have more, depending on the tools they're
providing. Some have none (since they're not click-and-drag painting-style
tools).
Our callback function gets called once for every point along a line between
the mouse's previous and current position, as it's being dragged.
Our callback pays attention to 'which' to determine which of our plugin's
tools is currently selected.
*/
void example_line_callback(void *pointer, int which, SDL_Surface * canvas,
SDL_Surface * snapshot, int x, int y)
{ {
// For technical reasons, we can't accept a pointer to the "magic_api" /*
// struct, like the other functions do. For technical reasons, we can't accept a pointer to the Tux Paint API's
// "magic_api" struct, like the other functions do.
// Instead, we receive a 'generic' pointer (a "void *").
// The line below declares a local "magic_api" pointer variable called "api", Instead, we receive a 'generic' pointer (a "void *"). The line below
// and then assigns it to the value of the 'generic' pointer we received. declares a local "magic_api" pointer variable called "api", and then
// assigns it to the value of the 'generic' pointer we received.
// (The "(magic_api *)" casts the generic pointer into the 'type' of
// pointer we want, a pointer to a "magic_api".) The "(magic_api *)" seen below casts the generic "void *" pointer into
magic_api *api = (magic_api *) ptr; the 'type' of pointer we want, a pointer to a "magic_api" struct.)
*/
magic_api *api = (magic_api *) pointer;
int xx, yy; int xx, yy;
/*
// This function handles both of our tools, so we need to check which This function handles both of our tools, so we need to check which is
// is being used right now. We compare the 'which' argument that being used right now. We compare the 'which' argument that Tux Paint
// Tux Paint sends to us with the values we enumerated above. sends to us with the values we enumerated above.
*/
if (which == TOOL_ONE) if (which == TOOL_ONE)
{ {
// Tool number 1 simply draws a single pixel at the (x,y) location. /*
// It's a 1x1 pixel brush Tool number 1 simply draws a single pixel at the (x,y) location. It acts
as a 1x1 pixel brush.
*/
api->putpixel(canvas, x, y, api->putpixel(canvas, x, y,
SDL_MapRGB(canvas->format, example_r, example_g, SDL_MapRGB(canvas->format,
example_b)); example_r, example_g, example_b));
// We use "SDL_MapRGB()" to convert the RGB value we receive from Tux Paint /*
// for the user's current color selection to a 'Uint32' pixel value We use "SDL_MapRGB()" to convert the RGB value we receive from Tux Paint
// we can send to Tux Paint's "putpixel()" function. for the user's current color selection to a 'Uint32' pixel value we can
send to Tux Paint's "putpixel()" function.
*/
} }
else if (which == TOOL_TWO) else if (which == TOOL_TWO)
{ {
// Tool number 2 copies an 8x8 square of pixels from the opposite side /*
// of the canvas and puts it under the cursor Tool number 2 copies an 8x8 square of pixels from the opposite side of
the canvas and puts it under the cursor.
*/
for (yy = -4; yy < 4; yy++) for (yy = -4; yy < 4; yy++)
{ {
for (xx = -4; xx < 4; xx++) for (xx = -4; xx < 4; xx++)
{ {
api->putpixel(canvas, x + xx, y + yy, api->putpixel(canvas, x + xx, y + yy,
api->getpixel(snapshot, canvas->w - x - xx, api->getpixel(snapshot,
canvas->h - y - yy)); snapshot->w - x - xx,
snapshot->h - y - yy));
// We simply use Tux Paint's "getpixel()" routine to pull pixel /*
// values from the 'snapshot', and then "putpixel()" to draw them Here we have simply use Tux Paint's "getpixel()" routine to pull pixel
// right into the 'canvas'. values from the 'snapshot', and then "putpixel()" to draw them right
into the 'snapshot'.
// Note: putpixel() and getpixel() are safe to use, even if your Note: putpixel() and getpixel() are safe to use, even if your X,Y values
// X,Y values are outside of the SDL surface (e.g., negative, or are outside of the SDL surface (e.g., negative, or greater than the
// greater than the surface's width or height). surface's width and/or height).
*/
} }
} }
} }
} }
// Switch-In event /*
// Switch-In event
// This happens whenever a Magic tool is enabled, either because the
// user just selected it, or they just came back to "Magic" after using
// another tool (e.g., Brush or Text), and this was the most-recently
// selected Magic tool.
//
// (This also applies to momentary tools, like
// Undo and Redo, and image-changing tools such as New and Open.)
//
// It also happens when a Magic tool's mode changes (it first
// receives a 'switchout()', below, for the old mode).
//
// Our example doesn't do anything when we switch to, or away from, our
// Magic tools, so we just do nothing here.
This happens whenever a Magic tool is enabled, either because the user just
selected it, or they just came back to 'Magic' after using another tool
(e.g., Brush or Text), and this was the most-recently selected Magic tool.
(This also applies to momentary tools, like Undo and Redo, and
image-changing tools such as New and Open.)
It also happens when a Magic tool's mode changes (we will first receive a
call to 'example_switchout()', below, for the old mode).
Our example doesn't do anything when we switch to, or away from, our Magic
tools, so we just do nothing here.
*/
void example_switchin(magic_api * api, int which, int mode, void example_switchin(magic_api * api, int which, int mode,
SDL_Surface * canvas) SDL_Surface * canvas)
{ {
} }
// Switch-Out event /*
// Switch-Out event
// This happens whenever a Magic tool is disabled, either because the
// user selected a different Magic tool, or they selected a completely
// different tool (e.g., Brush or Text).
//
// (This also applies to momentary tools, like Undo and Redo, and
// image-changing tools such as New and Open, in which case the
// switchin() function will be called moments later.)
//
// It also happens when a Magic tool's mode changes (it then
// receives a 'switchin()', above, for the new mode).
//
// Our example doesn't do anything when we switch to, or away from, our
// Magic tools, so we just do nothing here.
This happens whenever a Magic tool is disabled, either because the user
selected a different Magic tool, or they selected a completely different
tool (e.g., Brush or Text).
(This also applies to momentary tools, like Undo and Redo, and
image-changing tools such as New and Open.)
(And in that case, our example_switchin() function will be called moments
later.
It also happens when a Magic tool's mode changes (we will then receive a
call to 'example_switchin()', above, for the new mode).
Our example doesn't do anything when we switch to, or away from, our Magic
tools, so we just do nothing here.
*/
void example_switchout(magic_api * api, int which, int mode, void example_switchout(magic_api * api, int which, int mode,
SDL_Surface * canvas) SDL_Surface * canvas)
{ {