switchin() and switchout() Magic functions now used.
Documented new switchin() and switchout() functions.
This commit is contained in:
William Kendrick
parent
b4ed444f0f
commit
2e61076718
4 changed files with 183 additions and 37 deletions
|
|
@ -1,14 +1,14 @@
|
|||
Creating Tux Paint Magic Tool Plugins
|
||||
|
||||
Copyright 2007-2007 by Bill Kendrick and others
|
||||
Copyright 2007-2008 by Bill Kendrick and others
|
||||
New Breed Software
|
||||
|
||||
bill@newbreedsoftware.com
|
||||
http://www.tuxpaint.org/
|
||||
|
||||
July 5, 2007 - November 21, 2007
|
||||
July 5, 2007 - July 7, 2008
|
||||
|
||||
--------------------------------------------------------------------------
|
||||
----------------------------------------------------------------------
|
||||
|
||||
Overview
|
||||
|
||||
|
|
@ -22,50 +22,39 @@ Overview
|
|||
graphics tools, such as The GIMP, should be familiar with this plugin
|
||||
concept.)
|
||||
|
||||
--------------------------------------------------------------------------
|
||||
----------------------------------------------------------------------
|
||||
|
||||
Table of Contents
|
||||
|
||||
* Prequisites
|
||||
* Interfaces
|
||||
|
||||
* 'Magic' tool plugin functions
|
||||
|
||||
* Common arguments to plugin functions
|
||||
* Required Plugin Functions
|
||||
|
||||
* Plugin "housekeeping" functions
|
||||
* Plugin event functions
|
||||
|
||||
* Tux Paint Functions and Data
|
||||
|
||||
* Pixel Manipulations
|
||||
* Helper Functions
|
||||
* Informational
|
||||
* Tux Paint System Calls
|
||||
* Color Conversions
|
||||
|
||||
* Helper Macros in "tp_magic_api.h"
|
||||
* Constant Definitions in "tp_magic_api.h"
|
||||
|
||||
* Compiling
|
||||
|
||||
* Linux and other Unix-like Platforms
|
||||
* Windows
|
||||
* Mac OS X
|
||||
|
||||
* Installing
|
||||
|
||||
* Linux and other Unix-like Platforms
|
||||
* Windows
|
||||
* Mac OS X
|
||||
|
||||
* Creating plugins with multiple effects
|
||||
* Example Code
|
||||
* Getting Help
|
||||
* Glossary
|
||||
|
||||
--------------------------------------------------------------------------
|
||||
----------------------------------------------------------------------
|
||||
|
||||
Prerequisites
|
||||
|
||||
|
|
@ -76,7 +65,7 @@ Prerequisites
|
|||
Familiarity with the SDL API is highly recommended, but some basic SDL
|
||||
concepts will be covered in this document.
|
||||
|
||||
--------------------------------------------------------------------------
|
||||
----------------------------------------------------------------------
|
||||
|
||||
Interfaces
|
||||
|
||||
|
|
@ -101,7 +90,7 @@ Interfaces
|
|||
header files) for building a plugin. (See "Compiling", below.)
|
||||
|
||||
The C header file and command-line tool mentioned above are included
|
||||
with Tux Paint -- or in some cases, as part of a "Tux Paint 'Magic' Tool
|
||||
with Tux Paint - or in some cases, as part of a "Tux Paint 'Magic' Tool
|
||||
Plugin Development package".
|
||||
|
||||
'Magic' tool plugin functions
|
||||
|
|
@ -117,7 +106,6 @@ Interfaces
|
|||
|
||||
Here is a description of arguments that many of your plugin's
|
||||
functions will need to accept.
|
||||
|
||||
* magic_api * api
|
||||
Pointer to a C structure containing pointers to Tux Paint
|
||||
functions and other data that the plugin can (and sometimes
|
||||
|
|
@ -258,6 +246,40 @@ Interfaces
|
|||
|
||||
Plugin event functions:
|
||||
|
||||
* void switchin(magic_api * api, int which,
|
||||
SDL_Surface * snapshot, SDL_Surface * canvas)
|
||||
void switchout(magic_api * api, int which,
|
||||
SDL_Surface * snapshot, SDL_Surface * canvas)
|
||||
switchin() is called whenever one of the plugin's Magic tools
|
||||
becomes active, and switchout() is called whenever one becomes
|
||||
inactive. This can be because the user just clicked a specific
|
||||
Magic tool (the current one is switched-out, and a new one is
|
||||
switched-in).
|
||||
|
||||
It can also happen when user leaves/returns from the selection
|
||||
of "Magic" tools when doing some other activity (i.e., using a
|
||||
different tool, such as "Text" or "Brush", activating a
|
||||
momentary tool, such as "Undo" and "Redo", or returning from a
|
||||
dialog - possibly with a new picture when it switches back -
|
||||
such as "Open", "New" or "Quit"). In this case, the same Magic
|
||||
tool is first 'switched-out', and then 'switched-back-in',
|
||||
usually moments later.
|
||||
|
||||
These functions allow users to interact in complicated was with
|
||||
Magic tools (for example, a tool that lets the user draw
|
||||
multiple freehand strokes, and then uses that as input such as
|
||||
handwriting - normally, the user could click somewhere in the
|
||||
canvas to tell the Magic tool they are 'finished', but if they
|
||||
switch to another tool, the Magic tool may want to undo any
|
||||
temporary changes to the canvas).
|
||||
|
||||
These functions could also be used to streamline certain
|
||||
effects; a behind-the-scenes copy of the entire canvas could be
|
||||
altered in some way when the user first switches to the canvas,
|
||||
and then pieces of that copy could be drawn on the canvas when
|
||||
they draw with the Magic tool.
|
||||
Note: Added to Tux Paint 0.9.21; Magic API version '0x00000002'
|
||||
|
||||
* void set_color(magic_api * api, Uint8 r, Uint8 g, Uint8 g)
|
||||
Tux Paint will call this function to inform the plugin of the
|
||||
RGB values of the currently-selected color in Tux Paint's
|
||||
|
|
@ -468,8 +490,7 @@ Interfaces
|
|||
This function notifies Tux Paint of special events. Various
|
||||
values defined in "tp_magic_api.h" can be 'or'ed together (using
|
||||
C's boolean 'or': "|") and sent to this function.
|
||||
|
||||
* SPECIAL_FLIP -- The contents of the canvas has been flipped
|
||||
* SPECIAL_FLIP - The contents of the canvas has been flipped
|
||||
vertically.
|
||||
|
||||
If a 'Starter' image was used as the basis of this image,
|
||||
|
|
@ -479,7 +500,7 @@ Interfaces
|
|||
(or unflipped) should be recorded on disk when the current
|
||||
drawing is saved.
|
||||
|
||||
* SPECIAL_MIRROR -- Similar to SPECIAL_FLIP, but for magic
|
||||
* SPECIAL_MIRROR - Similar to SPECIAL_FLIP, but for magic
|
||||
tools that mirror the contents of the canvas horizontally.
|
||||
|
||||
Color Conversions
|
||||
|
|
@ -559,7 +580,7 @@ Interfaces
|
|||
These are flags for Tux Paint's "special_notify()" helper
|
||||
function. They are described above.
|
||||
|
||||
--------------------------------------------------------------------------
|
||||
----------------------------------------------------------------------
|
||||
|
||||
Compiling
|
||||
|
||||
|
|
@ -570,9 +591,9 @@ Compiling
|
|||
source code.
|
||||
|
||||
Use the "tp-magic-config --cflags" command, supplied as part of
|
||||
Tux Paint -- or in some cases, as part of a "Tux Paint 'Magic' Tool
|
||||
Plugin Development package" -- to provide additional command-line
|
||||
flags to your C compiler that will help it build your plugin.
|
||||
Tux Paint - or in some cases, as part of a "Tux Paint 'Magic' Tool
|
||||
Plugin Development package" - to provide additional command-line flags
|
||||
to your C compiler that will help it build your plugin.
|
||||
|
||||
Command-Line Example
|
||||
|
||||
|
|
@ -658,15 +679,15 @@ Compiling
|
|||
|
||||
TBD
|
||||
|
||||
--------------------------------------------------------------------------
|
||||
----------------------------------------------------------------------
|
||||
|
||||
Installing
|
||||
|
||||
Linux and other Unix-like Platforms
|
||||
|
||||
Use the "tp-magic-config" command-line tool, supplied as part of
|
||||
Tux Paint -- or in some cases, as part of a "Tux Paint 'Magic' Tool
|
||||
Plugin Development package" -- to determine where your plugins' files
|
||||
Tux Paint - or in some cases, as part of a "Tux Paint 'Magic' Tool
|
||||
Plugin Development package" - to determine where your plugins' files
|
||||
should go.
|
||||
|
||||
Shared Object
|
||||
|
|
@ -803,7 +824,7 @@ Installing
|
|||
|
||||
TBD
|
||||
|
||||
--------------------------------------------------------------------------
|
||||
----------------------------------------------------------------------
|
||||
|
||||
Creating plugins with multiple effects
|
||||
|
||||
|
|
@ -842,7 +863,7 @@ Creating plugins with multiple effects
|
|||
{
|
||||
/* Becomes, for example,
|
||||
"/usr/share/tuxpaint/sounds/magic/one.ogg" */
|
||||
|
||||
|
||||
snprintf(fname, sizeof(fname), "%s/sounds/magic/%s",
|
||||
api->data_prefix, my_plugin_snd_filenames[i];
|
||||
|
||||
|
|
@ -865,14 +886,14 @@ Creating plugins with multiple effects
|
|||
an effect with little effort. ("NUM_TOOLS" will simply be '1', your
|
||||
arrays will be of length '1', etc.)
|
||||
|
||||
--------------------------------------------------------------------------
|
||||
----------------------------------------------------------------------
|
||||
|
||||
Example Code
|
||||
|
||||
The C source file "tp_magic_example.c" contains a complete example of a
|
||||
plugin with multiple simple effects.
|
||||
|
||||
--------------------------------------------------------------------------
|
||||
----------------------------------------------------------------------
|
||||
|
||||
Getting Help
|
||||
|
||||
|
|
@ -884,7 +905,7 @@ Getting Help
|
|||
"tuxpaint-devel" and "tuxpaint-users" mailing lists:
|
||||
http://www.tuxpaint.org/lists/.
|
||||
|
||||
--------------------------------------------------------------------------
|
||||
----------------------------------------------------------------------
|
||||
|
||||
Glossary
|
||||
|
||||
|
|
|
|||
|
|
@ -9,13 +9,13 @@ alink="#FF00FF">
|
|||
<center>
|
||||
<h1>Creating Tux Paint Magic Tool Plugins</h1>
|
||||
|
||||
<p>Copyright 2007-2007 by Bill Kendrick and others<br>
|
||||
<p>Copyright 2007-2008 by Bill Kendrick and others<br>
|
||||
New Breed Software</p>
|
||||
|
||||
<p><a href="mailto:bill@newbreedsoftware.com">bill@newbreedsoftware.com</a><br>
|
||||
<a href="http://www.tuxpaint.org/">http://www.tuxpaint.org/</a></p>
|
||||
|
||||
<p>July 5, 2007 - November 21, 2007</p>
|
||||
<p>July 5, 2007 - July 7, 2008</p>
|
||||
</center>
|
||||
|
||||
<hr size=2 noshade>
|
||||
|
|
@ -319,6 +319,45 @@ then the names of your functions must begin with "<code><b>zoom_</b></code>"
|
|||
<h5><a name="eventfuncs">Plugin event functions:</a></h5>
|
||||
|
||||
<ul>
|
||||
<li><code><b>void switchin(magic_api * api,
|
||||
int which,
|
||||
SDL_Surface * snapshot, SDL_Surface * canvas)
|
||||
</b></code><br>
|
||||
<code><b>void switchout(magic_api * api,
|
||||
int which,
|
||||
SDL_Surface * snapshot, SDL_Surface * canvas)
|
||||
</b></code><br>
|
||||
<code>switchin()</code> is called whenever one of the plugin's Magic
|
||||
tools becomes active, and <code>switchout()</code> is called whenever
|
||||
one becomes inactive. This can be because the user just clicked a
|
||||
specific Magic tool (the current one is switched-out, and a new one
|
||||
is switched-in).<br>
|
||||
<br>
|
||||
It can also happen when user leaves/returns
|
||||
from the selection of "Magic" tools when doing some other activity
|
||||
(i.e., using a different tool, such as "Text" or "Brush", activating
|
||||
a momentary tool, such as "Undo" and "Redo", or returning from a
|
||||
dialog — possibly with a new picture when it switches back
|
||||
— such as "Open", "New" or "Quit"). In this case, the same
|
||||
Magic tool is first 'switched-out', and then 'switched-back-in', usually
|
||||
moments later.<br>
|
||||
<br>
|
||||
These functions allow users to interact in complicated was with Magic
|
||||
tools (for example, a tool that lets the user draw <i>multiple</i>
|
||||
freehand strokes, and then uses that as input such as handwriting —
|
||||
normally, the user could click somewhere in the canvas to tell the
|
||||
Magic tool they are 'finished', but if they switch to another tool, the
|
||||
Magic tool may want to undo any temporary changes to the canvas).<br>
|
||||
<br>
|
||||
These functions could also be used to streamline certain effects;
|
||||
a behind-the-scenes copy of the entire canvas could be altered in some
|
||||
way when the user first switches to the canvas, and then pieces of that
|
||||
copy could be drawn on the canvas when they draw with the Magic tool.
|
||||
<br>
|
||||
<i>Note: Added to Tux Paint 0.9.21; Magic API version
|
||||
'0x00000002'</i><br>
|
||||
<br>
|
||||
|
||||
<li><code><b>void set_color(magic_api * api,
|
||||
Uint8 r, Uint8 g, Uint8 g)
|
||||
</b></code><br>
|
||||
|
|
|
|||
|
|
@ -1,6 +1,7 @@
|
|||
/* tp_magic_example.c
|
||||
|
||||
An example of a "Magic" tool plugin for Tux Paint
|
||||
Last modified: 2008.07.07
|
||||
*/
|
||||
|
||||
|
||||
|
|
@ -481,3 +482,34 @@ void example_line_callback(void * ptr, int which,
|
|||
}
|
||||
}
|
||||
|
||||
// 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.)
|
||||
//
|
||||
// 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, SDL_Surface * canvas)
|
||||
{
|
||||
}
|
||||
|
||||
// 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.)
|
||||
//
|
||||
// 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, SDL_Surface * canvas)
|
||||
{
|
||||
}
|
||||
|
||||
|
|
|
|||
|
|
@ -1550,6 +1550,9 @@ SDL_Surface * magic_scale(SDL_Surface * surf, int w, int h, int aspect);
|
|||
void reset_touched(void);
|
||||
Uint8 magic_touched(int x, int y);
|
||||
|
||||
void magic_switchin(SDL_Surface * last);
|
||||
void magic_switchout(SDL_Surface * last);
|
||||
|
||||
#ifdef DEBUG
|
||||
static char *debug_gettext(const char *str);
|
||||
static int charsize(Uint16 c);
|
||||
|
|
@ -1953,7 +1956,9 @@ static void mainloop(void)
|
|||
|
||||
if (event.type == SDL_QUIT)
|
||||
{
|
||||
magic_switchout(canvas);
|
||||
done = do_quit(cur_tool);
|
||||
magic_switchin(canvas);
|
||||
}
|
||||
else if (event.type == SDL_ACTIVEEVENT)
|
||||
{
|
||||
|
|
@ -1974,7 +1979,9 @@ static void mainloop(void)
|
|||
|
||||
if (key == SDLK_ESCAPE && !disable_quit)
|
||||
{
|
||||
magic_switchout(canvas);
|
||||
done = do_quit(cur_tool);
|
||||
magic_switchin(canvas);
|
||||
}
|
||||
else if (key == SDLK_s && (mod & KMOD_ALT))
|
||||
{
|
||||
|
|
@ -2000,18 +2007,24 @@ static void mainloop(void)
|
|||
else if (key == SDLK_ESCAPE &&
|
||||
(mod & KMOD_SHIFT) && (mod & KMOD_CTRL))
|
||||
{
|
||||
magic_switchout(canvas);
|
||||
done = do_quit(cur_tool);
|
||||
magic_switchin(canvas);
|
||||
}
|
||||
#ifdef WIN32
|
||||
else if (key == SDLK_F4 && (mod & KMOD_ALT))
|
||||
{
|
||||
magic_switchout(canvas);
|
||||
done = do_quit(cur_tool);
|
||||
magic_switchin(canvas);
|
||||
}
|
||||
#endif
|
||||
else if (key == SDLK_z && (mod & KMOD_CTRL) && !noshortcuts)
|
||||
{
|
||||
/* Ctrl-Z - Undo */
|
||||
|
||||
magic_switchout(canvas);
|
||||
|
||||
if (tool_avail[TOOL_UNDO])
|
||||
{
|
||||
hide_blinking_cursor();
|
||||
|
|
@ -2024,11 +2037,15 @@ static void mainloop(void)
|
|||
update_screen_rect(&r_tools);
|
||||
shape_tool_mode = SHAPE_TOOL_MODE_DONE;
|
||||
}
|
||||
|
||||
magic_switchin(canvas);
|
||||
}
|
||||
else if (key == SDLK_r && (mod & KMOD_CTRL) && !noshortcuts)
|
||||
{
|
||||
/* Ctrl-R - Redo */
|
||||
|
||||
magic_switchout(canvas);
|
||||
|
||||
if (tool_avail[TOOL_REDO])
|
||||
{
|
||||
hide_blinking_cursor();
|
||||
|
|
@ -2036,11 +2053,15 @@ static void mainloop(void)
|
|||
update_screen_rect(&r_tools);
|
||||
shape_tool_mode = SHAPE_TOOL_MODE_DONE;
|
||||
}
|
||||
|
||||
magic_switchin(canvas);
|
||||
}
|
||||
else if (key == SDLK_o && (mod & KMOD_CTRL) && !noshortcuts)
|
||||
{
|
||||
/* Ctrl-O - Open */
|
||||
|
||||
magic_switchout(canvas);
|
||||
|
||||
disable_avail_tools();
|
||||
draw_toolbar();
|
||||
draw_colors(COLORSEL_CLOBBER_WIPE);
|
||||
|
|
@ -2075,11 +2096,15 @@ static void mainloop(void)
|
|||
|
||||
/* FIXME: Make delay configurable: */
|
||||
control_drawtext_timer(1000, tool_tips[cur_tool], 0);
|
||||
|
||||
magic_switchin(canvas);
|
||||
}
|
||||
else if ((key == SDLK_n && (mod & KMOD_CTRL)) && !noshortcuts)
|
||||
{
|
||||
/* Ctrl-N - New */
|
||||
|
||||
magic_switchout(canvas);
|
||||
|
||||
hide_blinking_cursor();
|
||||
shape_tool_mode = SHAPE_TOOL_MODE_DONE;
|
||||
|
||||
|
|
@ -2114,11 +2139,15 @@ static void mainloop(void)
|
|||
draw_shapes();
|
||||
else if (cur_tool == TOOL_ERASER)
|
||||
draw_erasers();
|
||||
|
||||
magic_switchin(canvas);
|
||||
}
|
||||
else if (key == SDLK_s && (mod & KMOD_CTRL) && !noshortcuts)
|
||||
{
|
||||
/* Ctrl-S - Save */
|
||||
|
||||
magic_switchout(canvas);
|
||||
|
||||
hide_blinking_cursor();
|
||||
if (do_save(cur_tool, 0))
|
||||
{
|
||||
|
|
@ -2131,6 +2160,8 @@ static void mainloop(void)
|
|||
/* cur_tool = old_tool; */
|
||||
draw_toolbar();
|
||||
update_screen_rect(&r_tools);
|
||||
|
||||
magic_switchin(canvas);
|
||||
}
|
||||
#ifdef __APPLE__
|
||||
else if (key == SDLK_p && (mod & KMOD_CTRL) && (mod & KMOD_SHIFT) &&
|
||||
|
|
@ -2339,6 +2370,8 @@ static void mainloop(void)
|
|||
{
|
||||
/* A tool on the left has been pressed! */
|
||||
|
||||
magic_switchout(canvas);
|
||||
|
||||
which = GRIDHIT_GD(r_tools, gd_tools);
|
||||
|
||||
if (which < NUM_TOOLS && tool_avail[which] &&
|
||||
|
|
@ -2368,7 +2401,6 @@ static void mainloop(void)
|
|||
}
|
||||
}
|
||||
|
||||
|
||||
old_tool = cur_tool;
|
||||
cur_tool = which;
|
||||
draw_toolbar();
|
||||
|
|
@ -2473,6 +2505,7 @@ static void mainloop(void)
|
|||
magic_current_snd_ptr = NULL;
|
||||
draw_magic();
|
||||
draw_colors(magics[cur_magic].colors);
|
||||
|
||||
if (magics[cur_magic].colors)
|
||||
magic_funcs[magics[cur_magic].handle_idx].set_color(
|
||||
magic_api_struct,
|
||||
|
|
@ -2638,6 +2671,8 @@ static void mainloop(void)
|
|||
update_screen_rect(&r_toolopt);
|
||||
update_screen_rect(&r_ttoolopt);
|
||||
}
|
||||
|
||||
magic_switchin(canvas);
|
||||
}
|
||||
else if (HIT(r_toolopt) && valid_click(event.button.button))
|
||||
{
|
||||
|
|
@ -3101,6 +3136,8 @@ static void mainloop(void)
|
|||
}
|
||||
else if (cur_tool == TOOL_MAGIC)
|
||||
{
|
||||
magic_switchout(canvas);
|
||||
|
||||
if (cur_thing != cur_magic)
|
||||
{
|
||||
cur_magic = cur_thing;
|
||||
|
|
@ -3118,6 +3155,8 @@ static void mainloop(void)
|
|||
|
||||
if (do_draw)
|
||||
draw_magic();
|
||||
|
||||
magic_switchin(canvas);
|
||||
}
|
||||
|
||||
/* Update the screen: */
|
||||
|
|
@ -18765,3 +18804,18 @@ Uint32 magic_getpixel(SDL_Surface * surface, int x, int y)
|
|||
}
|
||||
|
||||
|
||||
void magic_switchout(SDL_Surface * last)
|
||||
{
|
||||
if (cur_tool == TOOL_MAGIC)
|
||||
magic_funcs[magics[cur_magic].handle_idx].switchout(magic_api_struct,
|
||||
magics[cur_magic].idx,
|
||||
canvas, last);
|
||||
}
|
||||
|
||||
void magic_switchin(SDL_Surface * last)
|
||||
{
|
||||
if (cur_tool == TOOL_MAGIC)
|
||||
magic_funcs[magics[cur_magic].handle_idx].switchin(magic_api_struct,
|
||||
magics[cur_magic].idx,
|
||||
canvas, last);
|
||||
}
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue