From adf56ef7e938dc5174e2961071446326248c6ce3 Mon Sep 17 00:00:00 2001 From: William Kendrick Date: Thu, 2 Aug 2007 21:04:42 +0000 Subject: [PATCH] tp-magic-config man moved to (1) Magic tool documentation now split into separate files, and referenced (as a directory) from README, so that users can find docs to any additional tools (ones not included by default with Tux Paint) that are installed. Added new --datadir option, to separate path to brushes/stamps/etc. from that of saved files. Improved docs on where savedir default is. Made sure --help, man tuxpaint, and OPTIONS docs all covered all command-line options. Noted SDL_Pango makes locale-specific fonts unnecessary. Added "--plugindocprefix" option to tp-magic-config, for where docs should go. Improved plugin API documentation. Improved layout of man pages a little. --- Makefile | 16 +- docs/CHANGES.txt | 12 +- docs/OPTIONS.txt | 90 +++++++-- docs/README.txt | 120 ++--------- docs/html/OPTIONS.html | 123 +++++++++--- docs/html/README.html | 132 ++---------- magic/docs/README.txt | 267 ++++++++++++++++++------- magic/docs/html/README.html | 239 ++++++++++++++++++---- magic/magic-docs/Makefile | 120 +++++++++++ magic/magic-docs/blocks.txt | 4 + magic/magic-docs/blur.txt | 5 + magic/magic-docs/bricks.txt | 5 + magic/magic-docs/cartoon.txt | 4 + magic/magic-docs/chalk.txt | 4 + magic/magic-docs/darken.txt | 6 + magic/magic-docs/drip.txt | 3 + magic/magic-docs/emboss.txt | 5 + magic/magic-docs/fade.txt | 6 + magic/magic-docs/fill.txt | 4 + magic/magic-docs/flip.txt | 6 + magic/magic-docs/flower.txt | 9 + magic/magic-docs/foam.txt | 5 + magic/magic-docs/glasstile.txt | 4 + magic/magic-docs/grass.txt | 7 + magic/magic-docs/html/blocks.html | 25 +++ magic/magic-docs/html/blur.html | 26 +++ magic/magic-docs/html/bricks.html | 26 +++ magic/magic-docs/html/cartoon.html | 25 +++ magic/magic-docs/html/chalk.html | 25 +++ magic/magic-docs/html/darken.html | 30 +++ magic/magic-docs/html/drip.html | 24 +++ magic/magic-docs/html/emboss.html | 25 +++ magic/magic-docs/html/fade.html | 30 +++ magic/magic-docs/html/fill.html | 25 +++ magic/magic-docs/html/flip.html | 27 +++ magic/magic-docs/html/flower.html | 31 +++ magic/magic-docs/html/foam.html | 25 +++ magic/magic-docs/html/glasstile.html | 24 +++ magic/magic-docs/html/grass.html | 29 +++ magic/magic-docs/html/kalidescope.html | 25 +++ magic/magic-docs/html/metalpaint.html | 24 +++ magic/magic-docs/html/mirror.html | 28 +++ magic/magic-docs/html/negative.html | 25 +++ magic/magic-docs/html/rainbow.html | 25 +++ magic/magic-docs/html/ripples.html | 24 +++ magic/magic-docs/html/smudge.html | 27 +++ magic/magic-docs/html/sparkles.html | 25 +++ magic/magic-docs/html/tint.html | 28 +++ magic/magic-docs/html/waves.html | 26 +++ magic/magic-docs/kalidescope.txt | 5 + magic/magic-docs/metalpaint.txt | 3 + magic/magic-docs/mirror.txt | 7 + magic/magic-docs/negative.txt | 4 + magic/magic-docs/rainbow.txt | 4 + magic/magic-docs/ripples.txt | 3 + magic/magic-docs/smudge.txt | 6 + magic/magic-docs/sparkles.txt | 4 + magic/magic-docs/tint.txt | 6 + magic/magic-docs/waves.txt | 5 + src/fonts.c | 5 +- src/get_fname.c | 98 ++++----- src/get_fname.h | 8 +- src/manpage/tp-magic-config.3 | 86 -------- src/manpage/tuxpaint.1 | 117 +++++++++-- src/tp-magic-config.sh.in | 12 +- src/tuxpaint.c | 178 ++++++++++++----- 66 files changed, 1809 insertions(+), 592 deletions(-) create mode 100644 magic/magic-docs/Makefile create mode 100644 magic/magic-docs/blocks.txt create mode 100644 magic/magic-docs/blur.txt create mode 100644 magic/magic-docs/bricks.txt create mode 100644 magic/magic-docs/cartoon.txt create mode 100644 magic/magic-docs/chalk.txt create mode 100644 magic/magic-docs/darken.txt create mode 100644 magic/magic-docs/drip.txt create mode 100644 magic/magic-docs/emboss.txt create mode 100644 magic/magic-docs/fade.txt create mode 100644 magic/magic-docs/fill.txt create mode 100644 magic/magic-docs/flip.txt create mode 100644 magic/magic-docs/flower.txt create mode 100644 magic/magic-docs/foam.txt create mode 100644 magic/magic-docs/glasstile.txt create mode 100644 magic/magic-docs/grass.txt create mode 100644 magic/magic-docs/html/blocks.html create mode 100644 magic/magic-docs/html/blur.html create mode 100644 magic/magic-docs/html/bricks.html create mode 100644 magic/magic-docs/html/cartoon.html create mode 100644 magic/magic-docs/html/chalk.html create mode 100644 magic/magic-docs/html/darken.html create mode 100644 magic/magic-docs/html/drip.html create mode 100644 magic/magic-docs/html/emboss.html create mode 100644 magic/magic-docs/html/fade.html create mode 100644 magic/magic-docs/html/fill.html create mode 100644 magic/magic-docs/html/flip.html create mode 100644 magic/magic-docs/html/flower.html create mode 100644 magic/magic-docs/html/foam.html create mode 100644 magic/magic-docs/html/glasstile.html create mode 100644 magic/magic-docs/html/grass.html create mode 100644 magic/magic-docs/html/kalidescope.html create mode 100644 magic/magic-docs/html/metalpaint.html create mode 100644 magic/magic-docs/html/mirror.html create mode 100644 magic/magic-docs/html/negative.html create mode 100644 magic/magic-docs/html/rainbow.html create mode 100644 magic/magic-docs/html/ripples.html create mode 100644 magic/magic-docs/html/smudge.html create mode 100644 magic/magic-docs/html/sparkles.html create mode 100644 magic/magic-docs/html/tint.html create mode 100644 magic/magic-docs/html/waves.html create mode 100644 magic/magic-docs/kalidescope.txt create mode 100644 magic/magic-docs/metalpaint.txt create mode 100644 magic/magic-docs/mirror.txt create mode 100644 magic/magic-docs/negative.txt create mode 100644 magic/magic-docs/rainbow.txt create mode 100644 magic/magic-docs/ripples.txt create mode 100644 magic/magic-docs/smudge.txt create mode 100644 magic/magic-docs/sparkles.txt create mode 100644 magic/magic-docs/tint.txt create mode 100644 magic/magic-docs/waves.txt delete mode 100644 src/manpage/tp-magic-config.3 diff --git a/Makefile b/Makefile index 7e29deba9..cfcdc5772 100644 --- a/Makefile +++ b/Makefile @@ -7,7 +7,7 @@ # bill@newbreedsoftware.com # http://www.tuxpaint.org/ -# June 14, 2002 - July 31, 2007 +# June 14, 2002 - August 2, 2007 # The version number, for release: @@ -529,7 +529,7 @@ uninstall: uninstall-i18n -rm $(MAN_PREFIX)/man1/tuxpaint.1.gz -rm $(MAN_PREFIX)/pl/man1/tuxpaint.1.gz -rm $(MAN_PREFIX)/man1/tuxpaint-import.1.gz - -rm $(MAN_PREFIX)/man3/tp-magic-config.3.gz + -rm $(MAN_PREFIX)/man1/tp-magic-config.1.gz -rm -f -r $(CONFDIR) -rm -r $(MAGIC_PREFIX) -rm -r $(INCLUDE_PREFIX)/tuxpaint @@ -743,6 +743,7 @@ install-doc: @echo "...Installing documentation..." @install -d $(DOC_PREFIX) @cp -R docs/* $(DOC_PREFIX) + @cp -R magic/magic-docs $(DOC_PREFIX) @chmod a=rX,g=rX,u=rwX $(DOC_PREFIX) @@ -753,8 +754,6 @@ install-man: @echo "...Installing man pages..." @# man1 directory... @install -d $(MAN_PREFIX)/man1 - @# man3 directory... - @install -d $(MAN_PREFIX)/man3 @# tuxpaint.1 @cp src/manpage/tuxpaint.1 $(MAN_PREFIX)/man1 @gzip -f $(MAN_PREFIX)/man1/tuxpaint.1 @@ -769,10 +768,10 @@ install-man: @cp src/manpage/tuxpaint-import.1 $(MAN_PREFIX)/man1/ @gzip -f $(MAN_PREFIX)/man1/tuxpaint-import.1 @chmod a+rx,g-w,o-w $(MAN_PREFIX)/man1/tuxpaint-import.1.gz - @# tp-magic-config.3 - @cp src/manpage/tp-magic-config.3 $(MAN_PREFIX)/man3/ - @gzip -f $(MAN_PREFIX)/man3/tp-magic-config.3 - @chmod a+rx,g-w,o-w $(MAN_PREFIX)/man3/tp-magic-config.3.gz + @# tp-magic-config.1 + @cp src/manpage/tp-magic-config.1 $(MAN_PREFIX)/man1/ + @gzip -f $(MAN_PREFIX)/man1/tp-magic-config.1 + @chmod a+rx,g-w,o-w $(MAN_PREFIX)/man1/tp-magic-config.1.gz @@ -940,6 +939,7 @@ tp-magic-config: src/tp-magic-config.sh.in Makefile -e s=__INCLUDE__=$(INCLUDE_PREFIX)/tuxpaint= \ -e s=__DATAPREFIX__=$(DATA_PREFIX)= \ -e s=__PLUGINPREFIX__=$(MAGIC_PREFIX)= \ + -e s=__PLUGINDOCPREFIX__=$(DOC_PREFIX)/magic-docs= \ > tp-magic-config # Make the "obj" directory to throw the object(s) into: diff --git a/docs/CHANGES.txt b/docs/CHANGES.txt index 2bd5f5e40..5c0d7d4d1 100644 --- a/docs/CHANGES.txt +++ b/docs/CHANGES.txt @@ -47,7 +47,8 @@ $Id$ source-code by using new "tp-magic-config" shell script to query for C compiler flags (which points to where "tp_magic_api.h" header file is installed) and directories Tux Paint uses (where plugin '.so' - files shoudl be stored, and where Tux Paint's global data files go). + files should be stored, and where Tux Paint's global data files and + documentation go). * Magic plugin development docs created. On Linux/Unix, installed into /usr/[local/]share/docs/tuxpaint-dev/ by default. (HTML and plaintext.) @@ -63,6 +64,11 @@ $Id$ affected (until mouse button is released and clicked again). Improves performance, especially where heavy math is used. + * Magic tool documentation now split into separate files, and referenced + (as a directory) from README, so that users can find docs to any + additional tools (ones not included by default with Tux Paint) that are + installed. + * Began adding support for using SDL_Pango, a wrapper to Pango, a library for layout and rendering of text, with an emphasis on internationalization. (The hope is to improve support for languages @@ -80,6 +86,10 @@ $Id$ * Print configuration is now saved between Tux Paint sessions on Mac OS X. Martin Fuhrer + * Saved-files directory and data directory (brushes, starters, etc.) can + now be different. Use "--datadir" option to override default data + directory, similar to "--savedir" has been for overriding save directory. + * New Brushes ----------- * Sparkles (based on old Magic Tool) diff --git a/docs/OPTIONS.txt b/docs/OPTIONS.txt index 4b3f3618d..5ab0fd415 100644 --- a/docs/OPTIONS.txt +++ b/docs/OPTIONS.txt @@ -9,7 +9,7 @@ bill@newbreedsoftware.com http://www.tuxpaint.org/ - July 4, 2007 + August 2, 2007 -------------------------------------------------------------------------- @@ -163,7 +163,7 @@ Windows Users printcfg=yes - (Windows only) + (Windows and Mac OS X only) Tux Paint will use a printer configuration file when printing. Push the [Alt] key while clicking the 'Print' button in @@ -318,20 +318,72 @@ Windows Users savedir=DIRECTORY - Use this option to change where Tux Paint saves pictures. By - default, this is "~/.tuxpaint/saved/" under Linux and Unix, and - "userdata\" under Windows. + Use this option to change where Tux Paint's "saved" + directory/folder is located, which is where Tux Paint saves and + opens pictures. - This can be useful in a Windows lab, where Tux Paint is - installed on a server, and children run it from workstations. - You can set savedir to be a folder in their home directory. - (e.g., "H:\tuxpaint\") + If you do not override it, the default location is: + + * Linux & Unix -- Under a hidden directory named ".tuxpaint" + in your home directory (aka "~" or "$HOME") + Example: "/home/username/.tuxpaint/saved/" + + * Windows -- Inside a folder named "TuxPaint" in your + "Application Data" folder. + Example: + "C:\Documents and Settings\Username\Application Data\TuxPaint\saved\" + + * Mac OS X -- Inside a folder named "TuxPaint" in your + "Application Support" folder. + Example: + "/Users/Username/Library/Application Support/TuxPaint/saved/" Note: When specifying a Windows drive (e.g., "H:\"), you must also specify a subdirectory. + Note: Prior to version 0.9.18, Tux Paint would also use the + setting or default for "savedir" as the place to search for + personal data files (brushes, stamps, starters and fonts). As of + version 0.9.18, they may be specified separately (see the + "datadir" option, below). + Example: savedir=Z:\tuxpaint\ + datadir=DIRECTORY + + Use this option to change where Tux Paint looks for personal + data files (brushes, stamps, starters and fonts specific to the + current user). + + Tux Paint will search for subdirectories/subfolders named + "brushes", "stamps", "starters" and "fonts" under the data + directory. + + If you do not override it, the default location is: + + * Linux & Unix -- Under a hidden directory named ".tuxpaint" + in your home directory (aka "~" or "$HOME") + Example: "/home/username/.tuxpaint/brushes/" + + * Windows -- Inside a folder named "TuxPaint" in your + "Application Data" folder. + Example: + "C:\Documents and Settings\Username\Application Data\TuxPaint\brushes\" + + * Mac OS X -- Inside a folder named "TuxPaint" in your + "Application Support" folder. + Example: + "/Users/Username/Library/Application Support/TuxPaint/brushes/" + + Note: Prior to version 0.9.18, Tux Paint would use the same + setting or default as for "savedir" to search for data files. As + of version 0.9.18, they may be specified separately. + + Note: When specifying a Windows drive (e.g., "H:\"), you must + also specify a subdirectory. + + Example: datadir=/home/johnny/tuxpaint-data/ + saveover=yes This disables the "Save over the old version...?" prompt when saving an existing file. With this option, the older version @@ -356,9 +408,8 @@ Windows Users test environment. autosave=yes - - This prevents Tux Paint from asking whether you want to save the current - picture when quitting, and assumes you do. + This prevents Tux Paint from asking whether you want to save the + current picture when quitting, and assumes you do. startblank=yes This causes Tux Paint to display a blank canvas when it first @@ -583,6 +634,8 @@ Windows Users --noprint --printdelay=SECONDS --printcfg + --altprintnever + --altprintalways --papersize=PAPERSIZE --simpleshapes --uppercase @@ -599,11 +652,13 @@ Windows Users --mirrorstamps --keyboard --savedir DIRECTORY + --datadir DIRECTORY --saveover --saveovernew --nosave --autosave --lang LANGUAGE + --colorfile FILE These enable or correspond to the configuration file options described above. @@ -618,6 +673,7 @@ Windows Users --print --printdelay=0 --noprintcfg + --altprintmod --complexshapes --mixedcase --dontgrab @@ -641,7 +697,7 @@ Windows Users ------------------------------------- - --locale locale + --locale LOCALE Run Tux Paint in one of the support languages. See the "Choosing a Different Language" section below for the locale @@ -971,6 +1027,12 @@ Setting Your Environment's Locale with the Tux Paint download, and are available separately. (See the table above, under the "Choosing a Different Language" section.) + Note: As of version 0.9.18, Tux Paint uses the "SDL_Pango" library, + which utilizes the "Pango" library to render text in the user + interface, rather than using "SDL_ttf" directly. Unless your copy of + Tux Paint was built without Pango support, special fonts should no + longer be necessary. + When running Tux Paint in a language that requires its own font, Tux Paint will try to load the font file from its system-wide "fonts" directory (under a "locale" subdirectory). The name of the file @@ -990,3 +1052,5 @@ Setting Your Environment's Locale Under Unix and Linux, you can use the Makefile that comes with the font to install the font in the appropriate location. + + -------------------------------------------------------------------------- diff --git a/docs/README.txt b/docs/README.txt index f242c60d9..84a3e9176 100644 --- a/docs/README.txt +++ b/docs/README.txt @@ -9,7 +9,7 @@ bill@newbreedsoftware.com http://www.tuxpaint.org/ - June 14, 2002 - June 27, 2007 + June 14, 2002 - August 2, 2007 -------------------------------------------------------------------------- @@ -329,104 +329,13 @@ Available Tools The 'Magic' tool is actually a set of special tools. Select one of the "magic" effects from - the selector on the right, and then click and - drag around the picture to apply the effect. + the selector on the right. Then, depending on + the tool, either click and drag around the + picture, or simply click the picture once, to + apply the effect. - Fill - This floods the picture with a color. - It lets you quickly fill parts of the - picture, as if it were a coloring - book. - - Grass - This paints grass on the image. The - higher up the canvas, the smaller the - grass is drawn, giving an illusion of - perspective. The grass can be tinted - various greenish hues by selecting - different colors in the color - palette. - - Bricks (Large and Small) - These two tools intelligently paint - large and small brick patterns on the - canvas. The bricks can be tinted - various redish hues by selecting - different colors in the color - palette. - - Rainbow - This is similar to the paint brush, - but as you move the mouse around, it - cycles through a spectrum of bright - colors. - - Sparkles - This draws glowing sparkles on the - canvas, in the currently-selected - color. - - Blur - This makes the picture fuzzy wherever - you drag the mouse. - - Smudge - This pushes the colors around under - the mouse, like finger painting with - wet paint. - - Lighten - This fades the colors wherever you - drag the mouse. (Do it to the same - spot many times, and it will - eventually become white.) - - Darken - This dakrens the colors wherever you - drag the mouse. (Do it to the same - spot many times, and it will - eventually become black.) - - Chalk - This makes parts of the picture - (where you move the mouse) look like - a chalk drawing. - - Blocks - This makes the picture blocky looking - ("pixelated") wherever you drag the - mouse. - - Negative - This inverts the colors wherever you - drag the mouse. (e.g., white becomes - black, and vice versa.) - - Tint - This changes the parts of the picture - to the selected color. - - Drip - This makes the paint "drip" wherever - you move the mouse. - - Cartoon - This makes the picture look like a - cartoon -- with thick outlines and - bright, solid colors -- wherever you - move the mouse. - - Mirror - When you click the mouse in your - picture with the "Mirror" magic - effect selected, the entire image - will be reversed, turning it into a - mirror image. - - Flip - Similar to "Mirror." Click and the - entire image will be turned - upside-down. + Each 'Magic' tool's instructions are contained + within the "magic-docs" folder. -------------------------------------------------------------------------- @@ -902,15 +811,18 @@ Doing it Manually Other documentation included with Tux Paint (in the "docs" folder/directory) include: + * "Magic" Tool Documentation ("magic-docs") + Documentation for each of the currently-installed + "Magic" tools. * AUTHORS.txt - List of authors and contributors + List of authors and contributors. * CHANGES.txt - Summary of changed between releases + Summary of changed between releases. * COPYING.txt - Copying license (The GNU General Public License) + Copying license (The GNU General Public License). * INSTALL.txt Instructions for compiling/installing, when - applicable + applicable. * EXTENDING.html Detailed instructions on creating brushes, stamps and starters, and adding fonts, to extend Tux Paint. @@ -920,10 +832,10 @@ Doing it Manually to use Tux Paint Config. * PNG.txt Notes on creating PNG format bitmapped images for use - in Tux Paint + in Tux Paint. * SVG.txt Notes on creating SVG format vector images for use in - Tux Paint + Tux Paint. -------------------------------------------------------------------------- diff --git a/docs/html/OPTIONS.html b/docs/html/OPTIONS.html index 6a4877345..ec2beb2a6 100644 --- a/docs/html/OPTIONS.html +++ b/docs/html/OPTIONS.html @@ -23,7 +23,7 @@ New Breed Software

http://www.tuxpaint.org/

-

July 4, 2007

+

August 2, 2007

@@ -90,7 +90,7 @@ New Breed Software

-

+

Available Options

@@ -215,7 +215,7 @@ New Breed Software

printcfg=yes
-

(Windows only)

+

(Windows and Mac OS X only)

Tux Paint will use a printer configuration file when printing. Push the [Alt] key while clicking the 'Print' button in @@ -399,21 +399,80 @@ New Breed Software

savedir=DIRECTORY
-

Use this option to change where Tux Paint saves pictures. - By default, this is "~/.tuxpaint/saved/" under Linux - and Unix, and "userdata\" under Windows.

+

Use this option to change where Tux Paint's "saved" + directory/folder is located, which is where Tux Paint saves and opens + pictures.

-

This can be useful in a Windows lab, where Tux Paint is - installed on a server, and children run it from workstations. - You can set savedir to be a folder in their home - directory. (e.g., "H:\tuxpaint\")

+

If you do not override it, the default location is: +

    +
  • Linux & Unix — Under a hidden directory named + ".tuxpaint" in your home directory (aka "~" + or "$HOME")
    + Example: "/home/username/.tuxpaint/saved/"
    +
    + +
  • Windows — Inside a folder named "TuxPaint" + in your "Application Data" folder.
    + Example: "C:\Documents and Settings\Username\Application Data\TuxPaint\saved\"
    +
    + +
  • Mac OS X — Inside a folder named "TuxPaint" in your + "Application Support" folder.
    + Example: "/Users/Username/Library/Application Support/TuxPaint/saved/"
    +
+

Note: When specifying a Windows drive (e.g., "H:\"), you must also specify a subdirectory.

+

Note: Prior to version 0.9.18, Tux Paint would also use + the setting or default for "savedir" as the place to + search for personal data files (brushes, stamps, starters and fonts). + As of version 0.9.18, they may be specified separately + (see the "datadir" option, below).

+

Example: savedir=Z:\tuxpaint\

+
datadir=DIRECTORY
+
+

Use this option to change where Tux Paint looks for personal + data files (brushes, stamps, starters and fonts specific to the + current user).

+ +

Tux Paint will search for subdirectories/subfolders named + "brushes", "stamps", "starters" + and "fonts" under the data directory.

+ +

If you do not override it, the default location is: +

    +
  • Linux & Unix — Under a hidden directory named + ".tuxpaint" in your home directory (aka "~" + or "$HOME")
    + Example: "/home/username/.tuxpaint/brushes/"
    +
    + +
  • Windows — Inside a folder named "TuxPaint" + in your "Application Data" folder.
    + Example: "C:\Documents and Settings\Username\Application Data\TuxPaint\brushes\"
    +
    + +
  • Mac OS X — Inside a folder named "TuxPaint" in your + "Application Support" folder.
    + Example: "/Users/Username/Library/Application Support/TuxPaint/brushes/"
    +
+

+ +

Note: Prior to version 0.9.18, Tux Paint would use the + same setting or default as for "savedir" to search for + data files. As of version 0.9.18, they may be specified separately.

+ +

Note: When specifying a Windows drive (e.g., + "H:\"), you must also specify a subdirectory.

+ +

Example: datadir=/home/johnny/tuxpaint-data/

+
+
saveover=yes
This disables the "Save over the old version...?" prompt when @@ -445,12 +504,12 @@ New Breed Software

autosave=yes
-
+
This prevents Tux Paint from asking whether you want to save the current picture when quitting, and assumes you do. - +
-
startblank=yes +
startblank=yes
This causes Tux Paint to display a blank canvas when it first starts up, rather than loading the last image that was being edited. @@ -916,6 +975,8 @@ New Breed Software

--noprint
--printdelay=SECONDS
--printcfg
+ --altprintnever
+ --altprintalways
--papersize=PAPERSIZE
--simpleshapes
--uppercase
@@ -932,11 +993,13 @@ New Breed Software

--mirrorstamps
--keyboard
--savedir DIRECTORY
+ --datadir DIRECTORY
--saveover
--saveovernew
--nosave
--autosave
--lang LANGUAGE
+ --colorfile FILE
These enable or correspond to the configuration file options @@ -954,6 +1017,7 @@ New Breed Software

--print
--printdelay=0
--noprintcfg
+ --altprintmod
--complexshapes
--mixedcase
--dontgrab
@@ -980,7 +1044,7 @@ New Breed Software

-
--locale locale
+
--locale LOCALE

Run Tux Paint in one of the support languages. See the "Choosing a Different @@ -1652,40 +1716,47 @@ New Breed Software

Special Fonts

- Some languages require special fonts be installed. These font +

Some languages require special fonts be installed. These font files (which are in TrueType format (TTF)), are much too large to include with the Tux Paint download, and are available separately. (See the table above, under the "Choosing a Different Language" - section.)

+ section.)

- When running Tux Paint in a language that requires its own font, +

Note: As of version 0.9.18, Tux Paint uses the "SDL_Pango" + library, which utilizes the "Pango" library to render text in the user + interface, rather than using "SDL_ttf" directly. Unless your copy of + Tux Paint was built without Pango support, special fonts should + no longer be necessary.

+ +

When running Tux Paint in a language that requires its own font, Tux Paint will try to load the font file from its system-wide "fonts" directory (under a "locale" subdirectory). The name of the file corresponds to the first two letters in the 'locale' code of the language (e.g., "ko" for Korean, "ja" for Japanese, - "zh_tw" for Traditional Chinese).

+ "zh_tw" for Traditional Chinese).

- For example, under Linux or Unix, when Tux Paint is run in Korean +

For example, under Linux or Unix, when Tux Paint is run in Korean (e.g., with the option "--lang korean"), - Tux Paint will attempt to load the following font file:

+ Tux Paint will attempt to load the following font file:

- /usr/share/tuxpaint/fonts/locale/ko.ttf -

+

/usr/share/tuxpaint/fonts/locale/ko.ttf

+
- You can download fonts for supported languages from Tux Paint's +

You can download fonts for supported languages from Tux Paint's website, http://www.tuxpaint.org/. - (Look in the 'Fonts' section under 'Download.')

+ (Look in the 'Fonts' section under 'Download.')

- Under Unix and Linux, you can use the Makefile that comes - with the font to install the font in the appropriate location.

+

Under Unix and Linux, you can use the Makefile that comes + with the font to install the font in the appropriate location.

+
diff --git a/docs/html/README.html b/docs/html/README.html index 5ccb8164e..1cf25d98f 100644 --- a/docs/html/README.html +++ b/docs/html/README.html @@ -25,7 +25,7 @@ New Breed Software

June 14, 2002 - - June 27, 2007

+ August 2, 2007

@@ -456,118 +456,14 @@ New Breed Software

The 'Magic' tool is actually a set of special tools. Select one of - the "magic" effects from the selector on the right, and then - click and drag around the picture to apply the effect.

+ the "magic" effects from the selector on the right. Then, depending + on the tool, either click and drag around the picture, or simply + click the picture once, to apply the effect.


-
-
Fill
-
- This floods the picture with a color. It lets you quickly - fill parts of the picture, as if it were a coloring book. -
- -
Grass
-
- This paints grass on the image. The higher up the canvas, - the smaller the grass is drawn, giving an illusion of perspective. - The grass can be tinted various greenish hues by selecting - different colors in the color palette. -
- -
Bricks (Large and Small)
-
- These two tools intelligently paint large and small brick - patterns on the canvas. The bricks can be tinted various redish - hues by selecting different colors in the color palette. -
- -
Rainbow
-
- This is similar to the paint brush, but as you move the mouse - around, it cycles through a spectrum of bright colors. -
- -
Sparkles
-
- This draws glowing sparkles on the canvas, in the currently-selected - color. -
- -
Blur
-
- This makes the picture fuzzy wherever you drag the mouse. -
- -
Smudge
-
- This pushes the colors around under the mouse, like finger painting - with wet paint. -
- -
Lighten
-
- This fades the colors wherever you drag the mouse. - (Do it to the same spot many times, and it will eventually become - white.) -
- -
Darken
-
- This dakrens the colors wherever you drag the mouse. - (Do it to the same spot many times, and it will eventually become - black.) -
- -
Chalk
-
- This makes parts of the picture (where you move the mouse) - look like a chalk drawing. -
- -
Blocks
-
- This makes the picture blocky looking ("pixelated") wherever - you drag the mouse. -
- -
Negative
-
- This inverts the colors wherever you drag the mouse. - (e.g., white becomes black, and vice versa.) -
- -
Tint
-
- This changes the parts of the picture to the selected color. -
- -
Drip
-
- This makes the paint "drip" wherever you move the mouse. -
- -
Cartoon
-
- This makes the picture look like a cartoon — with thick - outlines and bright, solid colors — wherever you move the mouse. -
- -
Mirror
-
- When you click the mouse in your picture with the "Mirror" - magic effect selected, the entire image will be reversed, - turning it into a mirror image. -
- -
Flip
-
- Similar to "Mirror." Click and the entire image will be turned - upside-down. -
- -
+

Each 'Magic' tool's instructions are contained within the + "magic-docs" folder.

@@ -1120,17 +1016,21 @@ New Breed Software

folder/directory) include:
    +
  • "Magic" Tool Documentation + ("magic-docs")
    + Documentation for each of the currently-installed "Magic" tools. +
  • AUTHORS.txt
    - List of authors and contributors + List of authors and contributors.
  • CHANGES.txt
    - Summary of changed between releases + Summary of changed between releases.
  • COPYING.txt
    - Copying license (The GNU General Public License) + Copying license (The GNU General Public License).
  • INSTALL.txt
    - Instructions for compiling/installing, when applicable + Instructions for compiling/installing, when applicable.
  • EXTENDING.html
    Detailed instructions on creating brushes, stamps and starters, @@ -1141,10 +1041,10 @@ New Breed Software

    for those who don't want to use Tux Paint Config.
  • PNG.txt
    - Notes on creating PNG format bitmapped images for use in Tux Paint + Notes on creating PNG format bitmapped images for use in Tux Paint.
  • SVG.txt
    - Notes on creating SVG format vector images for use in Tux Paint + Notes on creating SVG format vector images for use in Tux Paint.
diff --git a/magic/docs/README.txt b/magic/docs/README.txt index 53319bfb7..9393c1bf0 100644 --- a/magic/docs/README.txt +++ b/magic/docs/README.txt @@ -6,7 +6,7 @@ bill@newbreedsoftware.com http://www.tuxpaint.org/ - July 5, 2007 - July 31, 2007 + July 5, 2007 - August 2, 2007 -------------------------------------------------------------------------- @@ -98,7 +98,7 @@ Interfaces to build a plugin, you should use the command-line tool "tp-magic-config" to get the appropriate compiler flags (such as where the compiler can find the Tux Paint plugin header file, as well as SDL's - header files) for building a plugin. + 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 @@ -553,29 +553,86 @@ Compiling shared object file (".so") based on your 'Magic' tool plugin's C source code. - Additionally, use the "tp-magic-config --cflags" command, supplied as - part of Tux Paint, to provide additional command-line flags to your C - compiler that will help it build your plugin. + 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. - As a stand-alone command, using the GNU C Compiler and BASH shell, for - example: + Command-Line Example - $ gcc -shared `tp-magic-config --cflags` my_plugin.c -o my_plugin.so + As a stand-alone command, using the GNU C Compiler and BASH shell, + for example: - Note: The characters around the "tp-magic-config" command are a - grave/backtick/backquote ("`"), and not an apostrophe/single-quote - ("'"). They tell the shell to execute the command within (in this - case, "tp-magic-config ..."), and use its output as an argument to the - command being executed (in this case, "gcc ..."). + $ gcc -shared `tp-magic-config --cflags` my_plugin.c -o + my_plugin.so - A snippet from a more generalized Makefile might look like this: + Note: The characters around the "tp-magic-config" command are a + grave/backtick/backquote ("`"), and not an apostrophe/single-quote + ("'"). They tell the shell to execute the command within (in this + case, "tp-magic-config ..."), and use its output as an argument to + the command being executed (in this case, "gcc ..."). - +----------------------------------------------------+ - | CFLAGS=-Wall -O2 $(shell tp-magic-config --cflags) | - | | - | my_plugin.so: my_plugin.c | - | $(CC) -shared $(CFLAGS) -o $@ $< | - +----------------------------------------------------+ + Makefile Example + + A snippet from a Makefile to compile a Tux Paint "Magic" tool plugin + might look like this: + + +------------------------------------------------------+ + | CFLAGS=-Wall -O2 $(shell tp-magic-config --cflags) | + | | + | my_plugin.so: my_plugin.c | + | gcc -shared $(CFLAGS) -o my_plugin.so my_plugin.c | + +------------------------------------------------------+ + + The first line sets up Makefile variable ("CFLAGS") that contains + flags for the compiler. "-Wall" asks for all compiler warnings to be + shown. "-O2" asks for level 2 optimization. + "($shell tp-magic-config --cflags)" runs "tp-magic-config" to + retrieve additional compiler flags that "Magic" tool plugins + require. (The "$(shell ...)" directive is similar to the ` ("grave") + character in the BASH shell examples, above.) + + The next line defines a Makefile target, "my_plugin.so", and states + that it depends on the C source file "my_plugin.c". (Any time the C + file changes, "make" will know to recompile it and produce an + updated ".so" file. If the C file hadn't changed, it won't bother + recompiling.) + + The last line defines the command "make" should run when it + determines that it needs to (re)compile the ".so" file. Here, we're + using "gcc", with "-shared and "$(CFLAGS)" command-line arguments, + like above. "-o my_plugin.so" tells the C compiler that the output + file should be "my_plugin.so". The last argument is the C file to + compile, in this case "my_plugin.c". + + Note: Commands listed below a Makefile target should be intented + using a single tab character. + + Advanced Makefile + + An even more generalized Makefile might look like this: + + +----------------------------------------------------+ + | CFLAGS=-Wall -O2 $(shell tp-magic-config --cflags) | + | | + | my_plugin_1.so: my_plugin_1.c | + | $(CC) -shared $(CFLAGS) -o $@ $< | + | | + | my_plugin_2.so: my_plugin_2.c | + | $(CC) -shared $(CFLAGS) -o $@ $< | + +----------------------------------------------------+ + + As before, there are lines that define the command "make" should run + when it determines that it needs to (re)compile the ".so" file(s). + However, more general terms are used... + + "$(CC)" gets expanded to your default C compiler (e.g., "gcc"). + "-shared and "$(CFLAGS)" are command-line arguments to the compiler, + like above. "-o $@" tells the C compiler what the output file should + be; "make" replaces "$@" with the name of the target, in this case + "my_plugin_1.so" or "my_plugin_2.so". And finally, the last argument + is the C file to compile; "make" replaces it with the target's + dependency, in this case "my_plugin_1.c" or "my_plugin_2.c". Windows @@ -591,54 +648,108 @@ Installing Linux and other Unix-like Platforms - Use the "tp-magic-config --pluginprefix" command, supplied as part of - Tux Paint, to determine where the plugin shared object (".so") files - should be installed. The value returned by this command will be the - global location where the installed version of Tux Paint looks for - plugins (e.g., ""). + 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 + should go. - As stand-alone commands, using the BASH shell, for example: + Shared Object - # cp my_plugin.so `tp-magic-config --pluginprefix` - # chmod 644 `tp-magic-config --pluginprefix`/my_plugin.so + Use "tp-magic-config --pluginprefix" to determine where the plugin + shared object (".so") files should be installed. The value returned + by this command will be the global location where the installed copy + of Tux Paint looks for plugins (e.g., "/usr/lib/tuxpaint/plugins"). - Additionally, use the "tp-magic-config --dataprefix" command, supplied - as part of Tux Paint, to determine where data files (PNG icon, - Ogg Vorbis sound effects, etc.) should be installed. The value - returned by this command will be the same as the value of the - "data_directory" string stored within the "magic_api" structure that - your plugin's functions receive. + As stand-alone commands, using the BASH shell, for example: - Note: Tux Paint's default Magic tool plugins install their data within - "magic" subdirectories of Tux Paint's "images" and "sounds" data - directories (e.g., "/usr/share/tuxpaint/images/magic/"). You are - encouraged to do the same. + # cp my_plugin.so `tp-magic-config --pluginprefix` + # chmod 644 `tp-magic-config --pluginprefix`/my_plugin.so - As stand-alone commands, using the BASH shell, for example: + Note: See the note above regarding the "`" (grave) character. - # cp my_plugin_icon.png `tp-magic-config --dataprefix`/images/magic/ - # chmod 644 `tp-magic-config - --dataprefix`/images/magic/my_plugin_icon.png + Documentation + + Use the "tp-magic-config --plugindocprefix" command to determine + where documentation for your "Magic" tools should go. The value + returned by this command will be the location where the + documentation to the installed copy of Tux Paint is stored. The main + documentation includes a link to a folder where "Magic" tools' + documentation is expected to be installed + + (e.g., "/usr/share/doc/tuxpaint/magic-docs"). + + Note: It's best to include both HTML and plain-text versions of your + documentation. An "html" subdirectory exists within the "magic-docs" + directory, and is where the HTML versions should go. + + As stand-alone commands, using the BASH shell, for example: + + # cp my_plugin.html `tp-magic-config --plugindocprefix`/html + # cp my_plugin.txt `tp-magic-config --plugindocprefix` + + Note: See the note above regarding the "`" (grave) character. + + Icons, Sounds and other Data Files + + Use the "tp-magic-config --dataprefix" command, supplied as part of + Tux Paint, to determine where data files (PNG icon, Ogg Vorbis sound + effects, etc.) should be installed. The value returned by this + command will be the same as the value of the "data_directory" string + stored within the "magic_api" structure that your plugin's functions + receive. + + Note: Tux Paint's default Magic tool plugins install their data + within "magic" subdirectories of Tux Paint's "images" and "sounds" + data directories (e.g., "/usr/share/tuxpaint/images/magic/"). You + are encouraged to do the same. + + As stand-alone commands, using the BASH shell, for example: + + # cp my_plugin_icon.png `tp-magic-config + --dataprefix`/images/magic/ + # chmod 644 `tp-magic-config + --dataprefix`/images/magic/my_plugin_icon.png + + Note: See the note above regarding the "`" (grave) character. Putting it Together in a Makefile A snippet from a more generalized Makefile might look like this: - +------------------------------------------------------+ - | PLUGINPREFIX=$(shell tp-magic-config --pluginprefix) | - | DATAPREFIX=$(shell tp-magic-config --dataprefix) | - | | - | install: | - | mkdir -p $(PLUGINPREFIX) | - | cp *.so $(PLUGINPREFIX)/ | - | chmod 644 $(PLUGINPREFIX)/*.so | - | mkdir -p $(DATAPREFIX)/images/magic | - | cp *.png $(DATAPREFIX)/images/magic/ | - | chmod 644 $(DATAPREFIX)/images/magic/*.png | - +------------------------------------------------------+ + +------------------------------------------------------------+ + | PLUGINPREFIX=$(shell tp-magic-config --pluginprefix) | + | PLUGINDOCPREFIX=$(shell tp-magic-config --plugindocprefix) | + | DATAPREFIX=$(shell tp-magic-config --dataprefix) | + | | + | install: | + | # | + | # Install plugin | + | mkdir -p $(PLUGINPREFIX) | + | cp *.so $(PLUGINPREFIX)/ | + | chmod 644 $(PLUGINPREFIX)/*.so | + | # | + | # Install icons | + | mkdir -p $(DATAPREFIX)/images/magic | + | cp icons/*.png $(DATAPREFIX)/images/magic/ | + | chmod 644 $(DATAPREFIX)/images/magic/*.png | + | # | + | # Install sound effects | + | mkdir -p $(DATAPREFIX)/sounds/magic | + | cp sounds/*.ogg $(DATAPREFIX)/sounds/magic/ | + | chmod 644 $(DATAPREFIX)/sounds/magic/*.ogg | + | # | + | # Install docs | + | mkdir -p $(PLUGINDOCPREFIX)/html | + | cp docs/*.html $(PLUGINDOCPREFIX)/html/ | + | cp docs/*.txt $(PLUGINDOCPREFIX)/ | + | chmod 644 $(PLUGINDOCPREFIX)/html/*.html | + | chmod 644 $(PLUGINDOCPREFIX)/*.txt | + +------------------------------------------------------------+ - The first two lines set up Makefile variables that contain the paths - returned by the "tp-magic-config" command-line tool. + The first three lines set up Makefile variables that contain the + paths returned by the "tp-magic-config" command-line tool. (The + "$(shell ...)" directive is similar to the ` ("grave") character in + the BASH shell examples, above.) Below that is an "install" target in the Makefile. (Invoked by, for example, "$ sudo make install" or "# make install".) @@ -648,7 +759,9 @@ Installing into it, and invokes "chmod" to make sure they are readable. It then does a similar series of commands to install icon files - (".png" images) into a subdirectory within Tux Paint's data + (".png" images) and sound effects (".ogg" files) into subdirectories + within Tux Paint's data directory, and to install documentation + (".html" and ".txt" files) within Tux Paint's documentation directory. Windows @@ -696,7 +809,10 @@ Creating plugins with multiple effects for (i = 0; i < NUM_TOOLS; i++) { - snprintf(fname, sizeof(fname), "%s/%s", + /* 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]; my_plugin_snds[i] = Mix_LoadWAV(fname); @@ -705,6 +821,11 @@ Creating plugins with multiple effects * Similarly, do the same to free them later (such as freeing sound effects during your "shutdown()"). + int i; + + for (i = 0; i < NUM_TOOLS; i++) + Mix_FreeChunk(my_plugin_snds[i]); + * Use "which" values sent to your functions as an index into those arrays (e.g., for playing the appropriate sound effect for a tool). @@ -787,6 +908,8 @@ Glossary * free(): A C function that frees (deallocates) memory allocated by other C functions (such as "strdup()"). * function: See "C function" + * gcc: TBD (See also the "gcc(1)" man page) + * GNU C Compiler: See "gcc" * grave: The "`" character; used by the BASH shell to use the output of a command as the command-line arguments to another. * green: See "RGBA" @@ -807,6 +930,8 @@ Glossary * macro: TBD * magic_api: A C structure that is passed along to a plugin's functions that exposes data and functions within the running copy of Tux Paint. + * make: TBD + * Makefile: TBD * Magic tool: One of a number of effects or drawing tools in Tux Paint, made available via the "Magic" tool button. * Mix_Chunk *: (A pointer to) a C structure defined by SDL_mixer that @@ -816,9 +941,10 @@ Glossary * Mix_LoadWAV(): An SDL_mixer function that loads a sound file (WAV, Ogg Vorbis, etc.) and returns it as a "Mix_Chunk *". * namespace: TBD - * Ogg Vorbis: TBD + * OGG: See "Ogg Vorbis" + * Ogg Vorbis: TBD (See also: "WAV") * Plugin: TBD - * PNG: TBD + * PNG: TBD (See also the "png(5) man page) * pointer: See "C pointer" * red: See "RGBA" * release: The action of releasing a button on a mouse. @@ -827,19 +953,21 @@ Glossary * saturation: See "HSV" * SDL: See "Simple DirectMedia Layer" * SDL_FreeSurface(): An libSDL function that frees (deallocates) memory - allocated for an SDL surface ("SDL_Surface *"). + allocated for an SDL surface ("SDL_Surface *"). (See also the + "SDL_FreeSurface(3)" man page) * SDL_GetRGB(): A libSDL function that, given a Uint32 pixel value (e.g., one returned from the Tux Paint's Magic tool API helper function "getpixel()"), the format of the surface the pixel was taken from, and pointers to three Uint8 variables, will place the Red, Green and Blue (RGB) values of the pixel into the three Uint8 variables. (Example: "SDL_GetRGB(getpixel(surf, x, y), surf->format, &r, &g, - &b);".) + &b);".) (See also the "SDL_GetRGB(3)" man page) * SDL_MapRGB(): A libSDL function that, given the format of a surface and Uint8 values representing Red, Green and Blue values for a pixel, returns a Uint32 pixel value that can be placed in the surface (e.g., using Tux Paint's Magic tool API helper function "putpixel()"). (Example: "putpixel(surf, x, y, SDL_MapRGB(surf->format, r, g, b));".) + (See also the "SDL_MapRGB(3)" man page) * SDL_image: A library on top of libSDL that can load various kinds of image files (e.g., PNG) and return them as an "SDL_Surface *". * SDL_mixer: A library on top of libSDL that can load various kinds of @@ -848,15 +976,15 @@ Glossary * SDL_Rect: A C structure defined by libSDL that represents a rectangular area. It contains elements representing the coordinates of the top left corner of the rectange (x,y) and the dimensions of the - rectangle (w,h). + rectangle (w,h). (See also the "SDL_Rect(3)" man page) * SDL_Surface *: (A pointer to) a C structure defined by libSDL that - contains a drawing surface. + contains a drawing surface. (See also the "SDL_Surface(3)" man page) * Shared Object: A piece of code that's compiled separately from the main application, and loaded dynamically, at runtime. * Simple DirectMedia Layer: A programming library that allows programs portable low level access to a video framebuffer, audio output, mouse, - and keyboard. - * snprintf(): TBD + and keyboard. (See also: http://www.libsdl.org/) + * snprintf(): TBD (See also the "snprintf(3)" man page) * .so: See "Shared Object" * sRBG: See "RGBA" * star: "*". A symbol in C that, when used in the declaration of @@ -869,7 +997,7 @@ Glossary integer that's being pointed to.) * strdup(): A C function that allocates enough memory to store a copy of a string, copies the string to it, and returns a "char *" pointer to - the new copy. + the new copy. (See also the "strdup(3)" man page) * struct: See "C structure" * The GIMP: An Open Source image manipulation and paint program. * tp_magic_api.h: A header file that defines Tux Paint's Magic tool API. @@ -877,7 +1005,8 @@ Glossary * tp-magic-config: A command-line program that provides information about the installed version of Tux Paint to plugin developers (such as what C compiler flags they should compile with, and where plugin - shared objects and data files should be installed). + shared objects and data files should be installed). (See also the + "tp-magic-config(3)" man page.) * Uint32: A 32-bit, unsigned integer (defined by libSDL). In other words, four bytes that can represent 0 through 4294967295. (Typically used to hold enough information to store three or four bytes @@ -887,6 +1016,6 @@ Glossary * unsigned: TBD * value: See "HSV" * variable: TBD - * WAV: TBD + * WAV: TBD (See also "Ogg Vorbis") * (w,h): See "Dimensions" * (x,y): See "Coordinates" diff --git a/magic/docs/html/README.html b/magic/docs/html/README.html index ecf9ca797..e5e044890 100644 --- a/magic/docs/html/README.html +++ b/magic/docs/html/README.html @@ -15,7 +15,7 @@ New Breed Software

bill@newbreedsoftware.com
http://www.tuxpaint.org/

-

July 5, 2007 - July 31, 2007

+

July 5, 2007 - August 2, 2007

@@ -79,7 +79,7 @@ concept.)

  • Creating plugins with multiple effects
  • Example Code
  • Getting Help -
  • Glossary +
  • Glossary @@ -126,7 +126,8 @@ invokes them.

    Also, when you run the C compiler to build a plugin, you should use the command-line tool "tp-magic-config" to get the appropriate compiler flags (such as where the compiler can find the Tux Paint -plugin header file, as well as SDL's header files) for building a plugin.

    +plugin header file, as well as SDL's 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 @@ -711,9 +712,15 @@ also contains some helper macros that you may use.

    a shared object file (".so") based on your 'Magic' tool plugin's C source code.

    -

    Additionally, use the "tp-magic-config --cflags" command, - supplied as part of Tux Paint, to provide additional command-line - flags to your C compiler that will help it build your plugin.

    +

    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.

    + +

    Command-Line Example

    + +

    As a stand-alone command, using the GNU C Compiler and BASH shell, for example:

    @@ -724,7 +731,8 @@ also contains some helper macros that you may use.

    -

    Note: The characters around the "tp-magic-config" +

    Note: + The characters around the "tp-magic-config" command are a grave/backtick/backquote ("`"), and not an apostrophe/single-quote ("'"). @@ -733,17 +741,87 @@ also contains some helper macros that you may use.

    as an argument to the command being executed (in this case, "gcc ...").

    -

    A snippet from a more generalized Makefile might look like this:

    + + +

    Makefile Example

    + +
    + +

    A snippet from a Makefile to compile a Tux Paint "Magic" tool + plugin might look like this:

    CFLAGS=-Wall -O2 $(shell tp-magic-config --cflags)

    my_plugin.so: my_plugin.c
    +    gcc -shared $(CFLAGS) -o my_plugin.so my_plugin.c +

    +
    + +

    The first line sets up Makefile variable ("CFLAGS") that + contains flags for the compiler. "-Wall" asks for all compiler + warnings to be shown. "-O2" asks for level 2 optimization. + "($shell tp-magic-config --cflags)" runs + "tp-magic-config" to retrieve additional compiler flags that + "Magic" tool plugins require. (The "$(shell ...)" + directive is similar to the ` + ("grave") character in the BASH shell examples, above.)

    + +

    The next line defines a Makefile target, "my_plugin.so", + and states that it depends on the C source file + "my_plugin.c". (Any time the C file changes, "make" + will know to recompile it and produce an updated ".so" file. + If the C file hadn't changed, it won't bother recompiling.)

    + +

    The last line defines the command "make" should + run when it determines that it needs to (re)compile the ".so" + file. Here, we're using "gcc", with "-shared and + "$(CFLAGS)" command-line arguments, like above. + "-o my_plugin.so" tells the C compiler that the output file + should be "my_plugin.so". The last argument is the C file to + compile, in this case "my_plugin.c".

    + +

    Note: Commands listed below a Makefile target should be + intented using a single tab character.

    + +
    + +

    Advanced Makefile

    + +
    + +

    An even more generalized Makefile might look like this:

    + +
    +

    + CFLAGS=-Wall -O2 $(shell tp-magic-config --cflags)
    +
    + my_plugin_1.so: my_plugin_1.c
    +    $(CC) -shared $(CFLAGS) -o $@ $<
    +
    + my_plugin_2.so: my_plugin_2.c
       $(CC) -shared $(CFLAGS) -o $@ $<

    +

    As before, there are lines that define the command "make" + should run when it determines that it needs to (re)compile the + ".so" file(s). However, more general terms are used...

    + +

    "$(CC)" gets expanded to your default C compiler (e.g., + "gcc"). "-shared and "$(CFLAGS)" + are command-line arguments to the compiler, like above. + "-o $@" tells the C compiler what the output file + should be; "make" replaces "$@" with the name + of the target, in this case "my_plugin_1.so" or + "my_plugin_2.so". And finally, + the last argument is the C file to compile; "make" replaces + it with the target's dependency, in this case + "my_plugin_1.c" or "my_plugin_2.c".

    + +
    +

    Windows

    @@ -769,23 +847,70 @@ also contains some helper macros that you may use.

    Linux and other Unix-like Platforms

    -

    Use the "tp-magic-config --pluginprefix" - command, supplied as part of Tux Paint, to determine where the - plugin shared object (".so") files should be installed. - The value returned by this command will be the global location where - the installed version of Tux Paint looks for plugins - (e.g., "").

    +

    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 should go.

    + +

    Shared Object

    + +
    + +

    Use "tp-magic-config --pluginprefix" + to determine where the plugin shared object (".so") + files should be installed. The value returned by this command will be + the global location where the installed copy of Tux Paint looks + for plugins (e.g., "/usr/lib/tuxpaint/plugins").

    As stand-alone commands, using the BASH shell, for example:

    # cp my_plugin.so `tp-magic-config --pluginprefix`
    - # chmod 644 `tp-magic-config --pluginprefix`/my_plugin.so + # chmod 644 `tp-magic-config --pluginprefix`/my_plugin.so

    -

    Additionally, use the "tp-magic-config --dataprefix" +

    Note: See the note above regarding the + "`" (grave) character.

    + +
    + +

    Documentation

    + +
    +

    Use the "tp-magic-config --plugindocprefix" + command to determine where documentation for your "Magic" tools should go. + The value returned by this command will be the location where the + documentation to the installed copy of Tux Paint is stored. + The main documentation includes a link to a folder where "Magic" tools' + documentation is expected to be installed

    + (e.g., "/usr/share/doc/tuxpaint/magic-docs").

    + +

    Note: It's best to include both HTML and plain-text versions + of your documentation. An "html" subdirectory exists within + the "magic-docs" directory, and is where the HTML versions + should go.

    + +

    As stand-alone commands, using the BASH shell, for example:

    + +
    +

    + # cp my_plugin.html `tp-magic-config --plugindocprefix`/html
    + # cp my_plugin.txt `tp-magic-config --plugindocprefix` +

    +
    + +

    Note: See the note above regarding the + "`" (grave) character.

    + +
    + +

    Icons, Sounds and other Data Files

    + +
    + +

    Use the "tp-magic-config --dataprefix" command, supplied as part of Tux Paint, to determine where data files (PNG icon, Ogg Vorbis sound effects, etc.) should be installed. The value returned by this command will be the same as the value of the @@ -807,6 +932,11 @@ also contains some helper macros that you may use.

    +

    Note: See the note above regarding the + "`" (grave) character.

    + +
    +

    Putting it Together in a Makefile

    @@ -816,20 +946,40 @@ also contains some helper macros that you may use.

    PLUGINPREFIX=$(shell tp-magic-config --pluginprefix)
    + PLUGINDOCPREFIX=$(shell tp-magic-config --plugindocprefix)
    DATAPREFIX=$(shell tp-magic-config --dataprefix)

    install:
    +    #
    +    # Install plugin
       mkdir -p $(PLUGINPREFIX)
       cp *.so $(PLUGINPREFIX)/
       chmod 644 $(PLUGINPREFIX)/*.so
    +    #
    +    # Install icons
       mkdir -p $(DATAPREFIX)/images/magic
    -    cp *.png $(DATAPREFIX)/images/magic/
    -    chmod 644 $(DATAPREFIX)/images/magic/*.png +    cp icons/*.png $(DATAPREFIX)/images/magic/
    +    chmod 644 $(DATAPREFIX)/images/magic/*.png
    +    #
    +    # Install sound effects
    +    mkdir -p $(DATAPREFIX)/sounds/magic
    +    cp sounds/*.ogg $(DATAPREFIX)/sounds/magic/
    +    chmod 644 $(DATAPREFIX)/sounds/magic/*.ogg
    +    #
    +    # Install docs
    +    mkdir -p $(PLUGINDOCPREFIX)/html
    +    cp docs/*.html $(PLUGINDOCPREFIX)/html/
    +    cp docs/*.txt $(PLUGINDOCPREFIX)/
    +    chmod 644 $(PLUGINDOCPREFIX)/html/*.html
    +    chmod 644 $(PLUGINDOCPREFIX)/*.txt

    -

    The first two lines set up Makefile variables that contain the - paths returned by the "tp-magic-config" command-line tool.

    +

    The first three lines set up Makefile variables that contain the + paths returned by the "tp-magic-config" command-line tool. + (The "$(shell ...)" directive is similar to the + ` ("grave") character + in the BASH shell examples, above.)

    Below that is an "install" target in the Makefile. (Invoked by, for example, "$ sudo make install" @@ -841,8 +991,11 @@ also contains some helper macros that you may use.

    "chmod" to make sure they are readable.

    It then does a similar series of commands to install icon files - (".png" images) into a subdirectory within Tux Paint's - data directory.

    + (".png" images) and sound effects + (".ogg" files) into subdirectories within Tux Paint's + data directory, and to install documentation + (".html" and ".txt" files) within Tux Paint's + documentation directory.

    @@ -905,7 +1058,9 @@ effects:


    for (i = 0; i < NUM_TOOLS; i++)
    {
    -   snprintf(fname, sizeof(fname), "%s/%s",
    +   /* 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];

      my_plugin_snds[i] = Mix_LoadWAV(fname);
    @@ -914,7 +1069,12 @@ effects:

  • Similarly, do the same to free them later (such as freeing sound effects during your "shutdown()").
    -
    +
    + int i;
    +
    + for (i = 0; i < NUM_TOOLS; i++)
    +   Mix_FreeChunk(my_plugin_snds[i]); +
  • Use "which" values sent to your functions as an index into those arrays (e.g., for playing the appropriate sound effect @@ -960,7 +1120,7 @@ mailing lists:
    -

    Glossary

    +

    Glossary

    • alpha: See "RGBA" @@ -999,6 +1159,8 @@ mailing lists:
    • format: TBD
    • free(): A C function that frees (deallocates) memory allocated by other C functions (such as "strdup()").
    • function: See "C function" +
    • gcc: TBD (See also the "gcc(1)" man page) +
    • GNU C Compiler: See "gcc"
    • grave: The "`" character; used by the BASH shell to use the output of a command as the command-line arguments to another.
    • green: See "RGBA"
    • ->: See "arrow" @@ -1015,14 +1177,17 @@ mailing lists:
    • linear: TBD
    • macro: TBD
    • magic_api: A C structure that is passed along to a plugin's functions that exposes data and functions within the running copy of Tux Paint. +
    • make: TBD +
    • Makefile: TBD
    • Magic tool: One of a number of effects or drawing tools in Tux Paint, made available via the "Magic" tool button.
    • Mix_Chunk *: (A pointer to) a C structure defined by SDL_mixer that contains a sound.
    • Mix_FreeChunk(): An SDL_mixer function that frees (deallocates) memory allocated for an SDL_mixer sound 'chunk' ("Mix_Chunk *").
    • Mix_LoadWAV(): An SDL_mixer function that loads a sound file (WAV, Ogg Vorbis, etc.) and returns it as a "Mix_Chunk *".
    • namespace: TBD -
    • Ogg Vorbis: TBD +
    • OGG: See "Ogg Vorbis" +
    • Ogg Vorbis: TBD (See also: "WAV")
    • Plugin: TBD -
    • PNG: TBD +
    • PNG: TBD (See also the "png(5) man page)
    • pointer: See "C pointer"
    • red: See "RGBA"
    • release: The action of releasing a button on a mouse. @@ -1030,30 +1195,30 @@ mailing lists:
    • RGB: See "RBGA"
    • saturation: See "HSV"
    • SDL: See "Simple DirectMedia Layer" -
    • SDL_FreeSurface(): An libSDL function that frees (deallocates) memory allocated for an SDL surface ("SDL_Surface *"). -
    • SDL_GetRGB(): A libSDL function that, given a Uint32 pixel value (e.g., one returned from the Tux Paint's Magic tool API helper function "getpixel()"), the format of the surface the pixel was taken from, and pointers to three Uint8 variables, will place the Red, Green and Blue (RGB) values of the pixel into the three Uint8 variables. (Example: "SDL_GetRGB(getpixel(surf, x, y), surf->format, &r, &g, &b);".) -
    • SDL_MapRGB(): A libSDL function that, given the format of a surface and Uint8 values representing Red, Green and Blue values for a pixel, returns a Uint32 pixel value that can be placed in the surface (e.g., using Tux Paint's Magic tool API helper function "putpixel()"). (Example: "putpixel(surf, x, y, SDL_MapRGB(surf->format, r, g, b));".) +
    • SDL_FreeSurface(): An libSDL function that frees (deallocates) memory allocated for an SDL surface ("SDL_Surface *"). (See also the "SDL_FreeSurface(3)" man page) +
    • SDL_GetRGB(): A libSDL function that, given a Uint32 pixel value (e.g., one returned from the Tux Paint's Magic tool API helper function "getpixel()"), the format of the surface the pixel was taken from, and pointers to three Uint8 variables, will place the Red, Green and Blue (RGB) values of the pixel into the three Uint8 variables. (Example: "SDL_GetRGB(getpixel(surf, x, y), surf->format, &r, &g, &b);".) (See also the "SDL_GetRGB(3)" man page) +
    • SDL_MapRGB(): A libSDL function that, given the format of a surface and Uint8 values representing Red, Green and Blue values for a pixel, returns a Uint32 pixel value that can be placed in the surface (e.g., using Tux Paint's Magic tool API helper function "putpixel()"). (Example: "putpixel(surf, x, y, SDL_MapRGB(surf->format, r, g, b));".) (See also the "SDL_MapRGB(3)" man page)
    • SDL_image: A library on top of libSDL that can load various kinds of image files (e.g., PNG) and return them as an "SDL_Surface *".
    • SDL_mixer: A library on top of libSDL that can load various kinds of sound files (WAV, Ogg Vorbis, etc.) and play back multiple sounds at once (mix them). -
    • SDL_Rect: A C structure defined by libSDL that represents a rectangular area. It contains elements representing the coordinates of the top left corner of the rectange (x,y) and the dimensions of the rectangle (w,h). -
    • SDL_Surface *: (A pointer to) a C structure defined by libSDL that contains a drawing surface. +
    • SDL_Rect: A C structure defined by libSDL that represents a rectangular area. It contains elements representing the coordinates of the top left corner of the rectange (x,y) and the dimensions of the rectangle (w,h). (See also the "SDL_Rect(3)" man page) +
    • SDL_Surface *: (A pointer to) a C structure defined by libSDL that contains a drawing surface. (See also the "SDL_Surface(3)" man page)
    • Shared Object: A piece of code that's compiled separately from the main application, and loaded dynamically, at runtime. -
    • Simple DirectMedia Layer: A programming library that allows programs portable low level access to a video framebuffer, audio output, mouse, and keyboard. -
    • snprintf(): TBD +
    • Simple DirectMedia Layer: A programming library that allows programs portable low level access to a video framebuffer, audio output, mouse, and keyboard. (See also: http://www.libsdl.org/) +
    • snprintf(): TBD (See also the "snprintf(3)" man page)
    • .so: See "Shared Object"
    • sRBG: See "RGBA"
    • star: "*". A symbol in C that, when used in the declaration of variables (e.g., arguments to a function), denotes that the variable is a pointer. (For example, "int * p;" means that "p" is a pointer to an integer.) When used next to a pointer, it 'dereferences' the variable. (For example, later "*p = 50;" assigns the value of 50 to the memory that "p" points to; it does not change the value of "p", which is still a pointer to an integer. In essence, it changed the integer that's being pointed to.) -
    • strdup(): A C function that allocates enough memory to store a copy of a string, copies the string to it, and returns a "char *" pointer to the new copy. +
    • strdup(): A C function that allocates enough memory to store a copy of a string, copies the string to it, and returns a "char *" pointer to the new copy. (See also the "strdup(3)" man page)
    • struct: See "C structure"
    • The GIMP: An Open Source image manipulation and paint program.
    • tp_magic_api.h: A header file that defines Tux Paint's Magic tool API. Plugins must '#include' it. -
    • tp-magic-config: A command-line program that provides information about the installed version of Tux Paint to plugin developers (such as what C compiler flags they should compile with, and where plugin shared objects and data files should be installed). +
    • tp-magic-config: A command-line program that provides information about the installed version of Tux Paint to plugin developers (such as what C compiler flags they should compile with, and where plugin shared objects and data files should be installed). (See also the "tp-magic-config(3)" man page.)
    • Uint32: A 32-bit, unsigned integer (defined by libSDL). In other words, four bytes that can represent 0 through 4294967295. (Typically used to hold enough information to store three or four bytes representing a pixel's color; i.e., RBGA value).
    • Uint8: An 8-bit, unsigned integer (defined by libSDL). In other words, a byte that can represent 0 through 255.
    • unsigned: TBD
    • value: See "HSV"
    • variable: TBD -
    • WAV: TBD +
    • WAV: TBD (See also "Ogg Vorbis")
    • (w,h): See "Dimensions"
    • (x,y): See "Coordinates"
    diff --git a/magic/magic-docs/Makefile b/magic/magic-docs/Makefile new file mode 100644 index 000000000..6ea838ae0 --- /dev/null +++ b/magic/magic-docs/Makefile @@ -0,0 +1,120 @@ +# Makefile for Tux Paint Magic Tool Plugin API docs +# +# Uses "links" to convert docs from HTML to plain text. +# (Normally only ran by the developers after updating the HTML, prior to +# release.) +# +# Bill Kendrick +# bill@newbreedsoftware.com +# +# August 2, 2007 - August 2, 2007 +# $Id$ + +LINKS=links -dump -no-numbering -no-references + +TXT_FILES= \ + blocks.txt \ + blur.txt \ + bricks.txt \ + cartoon.txt \ + chalk.txt \ + darken.txt \ + drip.txt \ + emboss.txt \ + fade.txt \ + fill.txt \ + flip.txt \ + flower.txt \ + foam.txt \ + glasstile.txt \ + grass.txt \ + kalidescope.txt \ + metalpaint.txt \ + mirror.txt \ + negative.txt \ + rainbow.txt \ + ripples.txt \ + smudge.txt \ + sparkles.txt \ + tint.txt \ + waves.txt + +all: $(TXT_FILES) + +clean: + @-rm $(TXT_FILES) + +blocks.txt: html/blocks.html + @$(LINKS) $< > $@ + +blur.txt: html/blur.html + @$(LINKS) $< > $@ + +bricks.txt: html/bricks.html + @$(LINKS) $< > $@ + +cartoon.txt: html/cartoon.html + @$(LINKS) $< > $@ + +chalk.txt: html/chalk.html + @$(LINKS) $< > $@ + +darken.txt: html/darken.html + @$(LINKS) $< > $@ + +drip.txt: html/drip.html + @$(LINKS) $< > $@ + +emboss.txt: html/emboss.html + @$(LINKS) $< > $@ + +fade.txt: html/fade.html + @$(LINKS) $< > $@ + +fill.txt: html/fill.html + @$(LINKS) $< > $@ + +flip.txt: html/flip.html + @$(LINKS) $< > $@ + +flower.txt: html/flower.html + @$(LINKS) $< > $@ + +foam.txt: html/foam.html + @$(LINKS) $< > $@ + +glasstile.txt: html/glasstile.html + @$(LINKS) $< > $@ + +grass.txt: html/grass.html + @$(LINKS) $< > $@ + +kalidescope.txt: html/kalidescope.html + @$(LINKS) $< > $@ + +metalpaint.txt: html/metalpaint.html + @$(LINKS) $< > $@ + +mirror.txt: html/mirror.html + @$(LINKS) $< > $@ + +negative.txt: html/negative.html + @$(LINKS) $< > $@ + +rainbow.txt: html/rainbow.html + @$(LINKS) $< > $@ + +ripples.txt: html/ripples.html + @$(LINKS) $< > $@ + +smudge.txt: html/smudge.html + @$(LINKS) $< > $@ + +sparkles.txt: html/sparkles.html + @$(LINKS) $< > $@ + +tint.txt: html/tint.html + @$(LINKS) $< > $@ + +waves.txt: html/waves.html + @$(LINKS) $< > $@ diff --git a/magic/magic-docs/blocks.txt b/magic/magic-docs/blocks.txt new file mode 100644 index 000000000..75fd83e16 --- /dev/null +++ b/magic/magic-docs/blocks.txt @@ -0,0 +1,4 @@ + Tux Paint "Magic" Tool: Blocks + + This makes the picture blocky looking ("pixelated") wherever you drag the + mouse. diff --git a/magic/magic-docs/blur.txt b/magic/magic-docs/blur.txt new file mode 100644 index 000000000..3ba147357 --- /dev/null +++ b/magic/magic-docs/blur.txt @@ -0,0 +1,5 @@ + Tux Paint "Magic" Tool: Blur + + This makes the picture fuzzy wherever you drag the mouse. + + See also: Smudge. diff --git a/magic/magic-docs/bricks.txt b/magic/magic-docs/bricks.txt new file mode 100644 index 000000000..a9d166fbd --- /dev/null +++ b/magic/magic-docs/bricks.txt @@ -0,0 +1,5 @@ + Tux Paint "Magic" Tool: Bricks + + These two tools intelligently paint large and small brick patterns on the + canvas. The bricks can be tinted various redish hues by selecting + different colors in the color palette. diff --git a/magic/magic-docs/cartoon.txt b/magic/magic-docs/cartoon.txt new file mode 100644 index 000000000..a4055da3d --- /dev/null +++ b/magic/magic-docs/cartoon.txt @@ -0,0 +1,4 @@ + Tux Paint "Magic" Tool: Cartoon + + This makes the picture look like a cartoon -- with thick outlines and + bright, solid colors -- wherever you move the mouse. diff --git a/magic/magic-docs/chalk.txt b/magic/magic-docs/chalk.txt new file mode 100644 index 000000000..73de7118b --- /dev/null +++ b/magic/magic-docs/chalk.txt @@ -0,0 +1,4 @@ + Tux Paint "Magic" Tool: Chalk + + This makes parts of the picture (where you move the mouse) look like a + chalk drawing. diff --git a/magic/magic-docs/darken.txt b/magic/magic-docs/darken.txt new file mode 100644 index 000000000..cc7a47917 --- /dev/null +++ b/magic/magic-docs/darken.txt @@ -0,0 +1,6 @@ + Tux Paint "Magic" Tool: Darken + + This dakrens the colors wherever you drag the mouse. (Do it to the same + spot many times, and it will eventually become black.) + + See also: Darken and Tint. diff --git a/magic/magic-docs/drip.txt b/magic/magic-docs/drip.txt new file mode 100644 index 000000000..4bae1d0b3 --- /dev/null +++ b/magic/magic-docs/drip.txt @@ -0,0 +1,3 @@ + Tux Paint "Magic" Tool: Drip + + This makes the paint "drip" wherever you move the mouse. diff --git a/magic/magic-docs/emboss.txt b/magic/magic-docs/emboss.txt new file mode 100644 index 000000000..2cc098661 --- /dev/null +++ b/magic/magic-docs/emboss.txt @@ -0,0 +1,5 @@ + Tux Paint "Magic" Tool: Emboss + + This makes parts of your picture look "embossed." Wherever there are sharp + edges in your picture, the picture will look raised like it was stamped in + metal. diff --git a/magic/magic-docs/fade.txt b/magic/magic-docs/fade.txt new file mode 100644 index 000000000..2eac95669 --- /dev/null +++ b/magic/magic-docs/fade.txt @@ -0,0 +1,6 @@ + Tux Paint "Magic" Tool: Fade + + This fades the colors wherever you drag the mouse. (Do it to the same spot + many times, and it will eventually become white.) + + See also: Darken and Tint. diff --git a/magic/magic-docs/fill.txt b/magic/magic-docs/fill.txt new file mode 100644 index 000000000..7448940fc --- /dev/null +++ b/magic/magic-docs/fill.txt @@ -0,0 +1,4 @@ + Tux Paint "Magic" Tool: Fill + + This floods the picture with a color. It lets you quickly fill parts of + the picture, as if it were a coloring book. diff --git a/magic/magic-docs/flip.txt b/magic/magic-docs/flip.txt new file mode 100644 index 000000000..147ca472e --- /dev/null +++ b/magic/magic-docs/flip.txt @@ -0,0 +1,6 @@ + Tux Paint "Magic" Tool: Flip + + Similar to "Mirror." Click and the entire image will be turned + upside-down. + + See also: Mirror. diff --git a/magic/magic-docs/flower.txt b/magic/magic-docs/flower.txt new file mode 100644 index 000000000..2364f35f0 --- /dev/null +++ b/magic/magic-docs/flower.txt @@ -0,0 +1,9 @@ + Tux Paint "Magic" Tool: Flower + + This tool draws small flowers, with leafy bases and stalks. Click to set + the base, then drag the mouse upwards to drawe the stalk, and finally + release the mouse button to finish the flower. It will be drawn in the + currently-selected color. The shape and length of the stalk depends on how + you move the mouse while you drag. + + See also: Grass. diff --git a/magic/magic-docs/foam.txt b/magic/magic-docs/foam.txt new file mode 100644 index 000000000..240ee1de0 --- /dev/null +++ b/magic/magic-docs/foam.txt @@ -0,0 +1,5 @@ + Tux Paint "Magic" Tool: Foam + + Click and drag the mouse to draw foamy bubbles. The more you drag the + mouse in a particular spot, the more likely small bubbles will combine to + form bigger bubbles. diff --git a/magic/magic-docs/glasstile.txt b/magic/magic-docs/glasstile.txt new file mode 100644 index 000000000..1496ebbc3 --- /dev/null +++ b/magic/magic-docs/glasstile.txt @@ -0,0 +1,4 @@ + Tux Paint "Magic" Tool: Glass Tile + + Click and drag over your picture to make it look like it's being seen + through glass tiles. diff --git a/magic/magic-docs/grass.txt b/magic/magic-docs/grass.txt new file mode 100644 index 000000000..e57170d57 --- /dev/null +++ b/magic/magic-docs/grass.txt @@ -0,0 +1,7 @@ + Tux Paint "Magic" Tool: Grass + + This paints grass on the image. The higher up the canvas, the smaller the + grass is drawn, giving an illusion of perspective. The grass can be tinted + various greenish hues by selecting different colors in the color palette. + + See also: Flower. diff --git a/magic/magic-docs/html/blocks.html b/magic/magic-docs/html/blocks.html new file mode 100644 index 000000000..d03faf2fd --- /dev/null +++ b/magic/magic-docs/html/blocks.html @@ -0,0 +1,25 @@ + +Tux Paint "Magic" Tool: + +Blocks + + + + + + + +

    Tux Paint "Magic" Tool: + +Blocks + +

    + +

    + This makes the picture blocky looking ("pixelated") wherever + you drag the mouse. +

    + + + diff --git a/magic/magic-docs/html/blur.html b/magic/magic-docs/html/blur.html new file mode 100644 index 000000000..18ef4db29 --- /dev/null +++ b/magic/magic-docs/html/blur.html @@ -0,0 +1,26 @@ + +Tux Paint "Magic" Tool: + +Blur + + + + + + + +

    Tux Paint "Magic" Tool: + +Blur + +

    + +

    + This makes the picture fuzzy wherever you drag the mouse. +

    + +

    See also: Smudge.

    + + + diff --git a/magic/magic-docs/html/bricks.html b/magic/magic-docs/html/bricks.html new file mode 100644 index 000000000..9721b1afb --- /dev/null +++ b/magic/magic-docs/html/bricks.html @@ -0,0 +1,26 @@ + +Tux Paint "Magic" Tool: + +Bricks + + + + + + + +

    Tux Paint "Magic" Tool: + +Bricks + +

    + +

    + These two tools intelligently paint large and small brick + patterns on the canvas. The bricks can be tinted various redish + hues by selecting different colors in the color palette. +

    + + + diff --git a/magic/magic-docs/html/cartoon.html b/magic/magic-docs/html/cartoon.html new file mode 100644 index 000000000..a93b72d54 --- /dev/null +++ b/magic/magic-docs/html/cartoon.html @@ -0,0 +1,25 @@ + +Tux Paint "Magic" Tool: + +Cartoon + + + + + + + +

    Tux Paint "Magic" Tool: + +Cartoon + +

    + +

    + This makes the picture look like a cartoon — with thick + outlines and bright, solid colors — wherever you move the mouse. +

    + + + diff --git a/magic/magic-docs/html/chalk.html b/magic/magic-docs/html/chalk.html new file mode 100644 index 000000000..98488403c --- /dev/null +++ b/magic/magic-docs/html/chalk.html @@ -0,0 +1,25 @@ + +Tux Paint "Magic" Tool: + +Chalk + + + + + + + +

    Tux Paint "Magic" Tool: + +Chalk + +

    + +

    + This makes parts of the picture (where you move the mouse) + look like a chalk drawing. +

    + + + diff --git a/magic/magic-docs/html/darken.html b/magic/magic-docs/html/darken.html new file mode 100644 index 000000000..543989d45 --- /dev/null +++ b/magic/magic-docs/html/darken.html @@ -0,0 +1,30 @@ + +Tux Paint "Magic" Tool: + +Darken + + + + + + + +

    Tux Paint "Magic" Tool: + +Darken + +

    + +

    + This dakrens the colors wherever you drag the mouse. + (Do it to the same spot many times, and it will eventually become + black.) +

    + +

    See also: Darken +and Tint.

    + + + + diff --git a/magic/magic-docs/html/drip.html b/magic/magic-docs/html/drip.html new file mode 100644 index 000000000..8c59bc7f0 --- /dev/null +++ b/magic/magic-docs/html/drip.html @@ -0,0 +1,24 @@ + +Tux Paint "Magic" Tool: + +Drip + + + + + + + +

    Tux Paint "Magic" Tool: + +Drip + +

    + +

    + This makes the paint "drip" wherever you move the mouse. +

    + + + diff --git a/magic/magic-docs/html/emboss.html b/magic/magic-docs/html/emboss.html new file mode 100644 index 000000000..9f1b481e3 --- /dev/null +++ b/magic/magic-docs/html/emboss.html @@ -0,0 +1,25 @@ + +Tux Paint "Magic" Tool: + +Emboss + + + + + + + +

    Tux Paint "Magic" Tool: + +Emboss + +

    + +

    This makes parts of your picture look "embossed." Wherever there are +sharp edges in your picture, the picture will look raised like it was +stamped in metal. +

    + + + diff --git a/magic/magic-docs/html/fade.html b/magic/magic-docs/html/fade.html new file mode 100644 index 000000000..326dbb893 --- /dev/null +++ b/magic/magic-docs/html/fade.html @@ -0,0 +1,30 @@ + +Tux Paint "Magic" Tool: + +Fade + + + + + + + +

    Tux Paint "Magic" Tool: + +Fade + +

    + +

    + This fades the colors wherever you drag the mouse. + (Do it to the same spot many times, and it will eventually become + white.) +

    + +

    See also: Darken +and Tint.

    + + + + diff --git a/magic/magic-docs/html/fill.html b/magic/magic-docs/html/fill.html new file mode 100644 index 000000000..d32728ced --- /dev/null +++ b/magic/magic-docs/html/fill.html @@ -0,0 +1,25 @@ + +Tux Paint "Magic" Tool: + +Fill + + + + + + + +

    Tux Paint "Magic" Tool: + +Fill + +

    + +

    + This floods the picture with a color. It lets you quickly + fill parts of the picture, as if it were a coloring book. +

    + + + diff --git a/magic/magic-docs/html/flip.html b/magic/magic-docs/html/flip.html new file mode 100644 index 000000000..c7b1ed473 --- /dev/null +++ b/magic/magic-docs/html/flip.html @@ -0,0 +1,27 @@ + +Tux Paint "Magic" Tool: + +Flip + + + + + + + +

    Tux Paint "Magic" Tool: + +Flip + +

    + +

    + Similar to "Mirror." Click and the entire image will be turned + upside-down. +

    + +

    See also: Mirror.

    + + + diff --git a/magic/magic-docs/html/flower.html b/magic/magic-docs/html/flower.html new file mode 100644 index 000000000..d7fc7c4d9 --- /dev/null +++ b/magic/magic-docs/html/flower.html @@ -0,0 +1,31 @@ + +Tux Paint "Magic" Tool: + +Flower + + + + + + + +

    Tux Paint "Magic" Tool: + +Flower + +

    + +

    +This tool draws small flowers, with leafy bases and stalks. +Click to set the base, then drag the mouse upwards to drawe the stalk, +and finally release the mouse button to finish the flower. It will be drawn +in the currently-selected color. +The shape and length of the stalk depends on how you move the mouse +while you drag. +

    + +

    See also: Grass.

    + + + diff --git a/magic/magic-docs/html/foam.html b/magic/magic-docs/html/foam.html new file mode 100644 index 000000000..ca16fd583 --- /dev/null +++ b/magic/magic-docs/html/foam.html @@ -0,0 +1,25 @@ + +Tux Paint "Magic" Tool: + +Foam + + + + + + + +

    Tux Paint "Magic" Tool: + +Foam + +

    + +

    Click and drag the mouse to draw foamy bubbles. The more you drag the +mouse in a particular spot, the more likely small bubbles will combine to +form bigger bubbles. +

    + + + diff --git a/magic/magic-docs/html/glasstile.html b/magic/magic-docs/html/glasstile.html new file mode 100644 index 000000000..b6e75ec0f --- /dev/null +++ b/magic/magic-docs/html/glasstile.html @@ -0,0 +1,24 @@ + +Tux Paint "Magic" Tool: + +Glass Tile + + + + + + + +

    Tux Paint "Magic" Tool: + +Glass Tile + +

    + +

    Click and drag over your picture to make it look like it's being seen +through glass tiles. +

    + + + diff --git a/magic/magic-docs/html/grass.html b/magic/magic-docs/html/grass.html new file mode 100644 index 000000000..92e9983c7 --- /dev/null +++ b/magic/magic-docs/html/grass.html @@ -0,0 +1,29 @@ + +Tux Paint "Magic" Tool: + +Grass + + + + + + + +

    Tux Paint "Magic" Tool: + +Grass + +

    + +

    + This paints grass on the image. The higher up the canvas, + the smaller the grass is drawn, giving an illusion of perspective. + The grass can be tinted various greenish hues by selecting + different colors in the color palette. +

    + +

    See also: Flower.

    + + + diff --git a/magic/magic-docs/html/kalidescope.html b/magic/magic-docs/html/kalidescope.html new file mode 100644 index 000000000..e861ff048 --- /dev/null +++ b/magic/magic-docs/html/kalidescope.html @@ -0,0 +1,25 @@ + +Tux Paint "Magic" Tool: + +Kaleidoscope + + + + + + + +

    Tux Paint "Magic" Tool: + +Kaleidoscope + +

    + +

    This paint brush draws in four places at the same time, mirroring +symmetrically, both horizontally and vertically. It uses the currently +selected color. +

    + + + diff --git a/magic/magic-docs/html/metalpaint.html b/magic/magic-docs/html/metalpaint.html new file mode 100644 index 000000000..483d8fa52 --- /dev/null +++ b/magic/magic-docs/html/metalpaint.html @@ -0,0 +1,24 @@ + +Tux Paint "Magic" Tool: + +Metal Paint + + + + + + + +

    Tux Paint "Magic" Tool: + +Metal Paint + +

    + +

    +Click and drag to draw shiny metal using the current color. +

    + + + diff --git a/magic/magic-docs/html/mirror.html b/magic/magic-docs/html/mirror.html new file mode 100644 index 000000000..30db4c00e --- /dev/null +++ b/magic/magic-docs/html/mirror.html @@ -0,0 +1,28 @@ + +Tux Paint "Magic" Tool: + +Mirror + + + + + + + +

    Tux Paint "Magic" Tool: + +Mirror + +

    + +

    + When you click the mouse in your picture with the "Mirror" + magic effect selected, the entire image will be reversed, + turning it into a mirror image. +

    + +

    See also: Flip.

    + + + diff --git a/magic/magic-docs/html/negative.html b/magic/magic-docs/html/negative.html new file mode 100644 index 000000000..a4489d03f --- /dev/null +++ b/magic/magic-docs/html/negative.html @@ -0,0 +1,25 @@ + +Tux Paint "Magic" Tool: + +Negative + + + + + + + +

    Tux Paint "Magic" Tool: + +Negagtive + +

    + +

    + This inverts the colors wherever you drag the mouse. + (e.g., white becomes black, and vice versa.) +

    + + + diff --git a/magic/magic-docs/html/rainbow.html b/magic/magic-docs/html/rainbow.html new file mode 100644 index 000000000..cfe2919ce --- /dev/null +++ b/magic/magic-docs/html/rainbow.html @@ -0,0 +1,25 @@ + +Tux Paint "Magic" Tool: + +Rainbow + + + + + + + +

    Tux Paint "Magic" Tool: + +Rainbow + +

    + +

    + This is similar to the paint brush, but as you move the mouse + around, it cycles through a spectrum of bright colors. +

    + + + diff --git a/magic/magic-docs/html/ripples.html b/magic/magic-docs/html/ripples.html new file mode 100644 index 000000000..75ed1d991 --- /dev/null +++ b/magic/magic-docs/html/ripples.html @@ -0,0 +1,24 @@ + +Tux Paint "Magic" Tool: + +Ripples + + + + + + + +

    Tux Paint "Magic" Tool: + +Ripples + +

    + +

    +Click in your picture to make water ripple distortions appear over it. +

    + + + diff --git a/magic/magic-docs/html/smudge.html b/magic/magic-docs/html/smudge.html new file mode 100644 index 000000000..f8bb0326d --- /dev/null +++ b/magic/magic-docs/html/smudge.html @@ -0,0 +1,27 @@ + +Tux Paint "Magic" Tool: + +Smudge + + + + + + + +

    Tux Paint "Magic" Tool: + +Smudge + +

    + +

    + This pushes the colors around under the mouse, like finger painting + with wet paint. +

    + +

    See also: Blur.

    + + + diff --git a/magic/magic-docs/html/sparkles.html b/magic/magic-docs/html/sparkles.html new file mode 100644 index 000000000..bb23893aa --- /dev/null +++ b/magic/magic-docs/html/sparkles.html @@ -0,0 +1,25 @@ + +Tux Paint "Magic" Tool: + +Sparkles + + + + + + + +

    Tux Paint "Magic" Tool: + +Sparkles + +

    + +

    + This draws glowing sparkles on the canvas, in the currently-selected + color. +

    + + + diff --git a/magic/magic-docs/html/tint.html b/magic/magic-docs/html/tint.html new file mode 100644 index 000000000..bf019f407 --- /dev/null +++ b/magic/magic-docs/html/tint.html @@ -0,0 +1,28 @@ + +Tux Paint "Magic" Tool: + +Tint + + + + + + + +

    Tux Paint "Magic" Tool: + +Tint + +

    + +

    + This changes the color (or hue) of the parts of the picture to + the selected color. +

    + +

    See also: Fade +and Darken.

    + + + diff --git a/magic/magic-docs/html/waves.html b/magic/magic-docs/html/waves.html new file mode 100644 index 000000000..6d3d32e13 --- /dev/null +++ b/magic/magic-docs/html/waves.html @@ -0,0 +1,26 @@ + +Tux Paint "Magic" Tool: + +Waves + + + + + + + +

    Tux Paint "Magic" Tool: + +Waves + +

    + +

    +Click to make the entire picture wavy. Drag the mouse up and down to +change the height of the ripples, and left and right to change the width. +Release the mouse button when it looks the way you like it. +

    + + + diff --git a/magic/magic-docs/kalidescope.txt b/magic/magic-docs/kalidescope.txt new file mode 100644 index 000000000..82ab2c739 --- /dev/null +++ b/magic/magic-docs/kalidescope.txt @@ -0,0 +1,5 @@ + Tux Paint "Magic" Tool: Kaleidoscope + + This paint brush draws in four places at the same time, mirroring + symmetrically, both horizontally and vertically. It uses the currently + selected color. diff --git a/magic/magic-docs/metalpaint.txt b/magic/magic-docs/metalpaint.txt new file mode 100644 index 000000000..e71a687a5 --- /dev/null +++ b/magic/magic-docs/metalpaint.txt @@ -0,0 +1,3 @@ + Tux Paint "Magic" Tool: Metal Paint + + Click and drag to draw shiny metal using the current color. diff --git a/magic/magic-docs/mirror.txt b/magic/magic-docs/mirror.txt new file mode 100644 index 000000000..083d1ab1e --- /dev/null +++ b/magic/magic-docs/mirror.txt @@ -0,0 +1,7 @@ + Tux Paint "Magic" Tool: Mirror + + When you click the mouse in your picture with the "Mirror" magic effect + selected, the entire image will be reversed, turning it into a mirror + image. + + See also: Flip. diff --git a/magic/magic-docs/negative.txt b/magic/magic-docs/negative.txt new file mode 100644 index 000000000..4867cb6a7 --- /dev/null +++ b/magic/magic-docs/negative.txt @@ -0,0 +1,4 @@ + Tux Paint "Magic" Tool: Negagtive + + This inverts the colors wherever you drag the mouse. (e.g., white becomes + black, and vice versa.) diff --git a/magic/magic-docs/rainbow.txt b/magic/magic-docs/rainbow.txt new file mode 100644 index 000000000..204401465 --- /dev/null +++ b/magic/magic-docs/rainbow.txt @@ -0,0 +1,4 @@ + Tux Paint "Magic" Tool: Rainbow + + This is similar to the paint brush, but as you move the mouse around, it + cycles through a spectrum of bright colors. diff --git a/magic/magic-docs/ripples.txt b/magic/magic-docs/ripples.txt new file mode 100644 index 000000000..0bd0cf3f0 --- /dev/null +++ b/magic/magic-docs/ripples.txt @@ -0,0 +1,3 @@ + Tux Paint "Magic" Tool: Ripples + + Click in your picture to make water ripple distortions appear over it. diff --git a/magic/magic-docs/smudge.txt b/magic/magic-docs/smudge.txt new file mode 100644 index 000000000..3acbca078 --- /dev/null +++ b/magic/magic-docs/smudge.txt @@ -0,0 +1,6 @@ + Tux Paint "Magic" Tool: Smudge + + This pushes the colors around under the mouse, like finger painting with + wet paint. + + See also: Blur. diff --git a/magic/magic-docs/sparkles.txt b/magic/magic-docs/sparkles.txt new file mode 100644 index 000000000..014c74286 --- /dev/null +++ b/magic/magic-docs/sparkles.txt @@ -0,0 +1,4 @@ + Tux Paint "Magic" Tool: Sparkles + + This draws glowing sparkles on the canvas, in the currently-selected + color. diff --git a/magic/magic-docs/tint.txt b/magic/magic-docs/tint.txt new file mode 100644 index 000000000..7629ea0a5 --- /dev/null +++ b/magic/magic-docs/tint.txt @@ -0,0 +1,6 @@ + Tux Paint "Magic" Tool: Tint + + This changes the color (or hue) of the parts of the picture to the + selected color. + + See also: Fade and Darken. diff --git a/magic/magic-docs/waves.txt b/magic/magic-docs/waves.txt new file mode 100644 index 000000000..cb1f3bbb7 --- /dev/null +++ b/magic/magic-docs/waves.txt @@ -0,0 +1,5 @@ + Tux Paint "Magic" Tool: Waves + + Click to make the entire picture wavy. Drag the mouse up and down to + change the height of the ripples, and left and right to change the width. + Release the mouse button when it looks the way you like it. diff --git a/src/fonts.c b/src/fonts.c index c9e9b7bbf..189617240 100644 --- a/src/fonts.c +++ b/src/fonts.c @@ -663,11 +663,12 @@ int load_user_fonts(SDL_Surface * screen, void *vp) #endif } - homedirdir = get_fname("fonts"); + homedirdir = get_fname("fonts", DIR_DATA); loadfonts(screen, homedirdir); free(homedirdir); + #ifdef WIN32 - homedirdir = get_fname("data/fonts"); + homedirdir = get_fname("data/fonts", DIR_DATA); loadfonts(screen, homedirdir); free(homedirdir); #endif diff --git a/src/get_fname.c b/src/get_fname.c index a825f0b87..febd847b8 100644 --- a/src/get_fname.c +++ b/src/get_fname.c @@ -10,89 +10,71 @@ #include "debug.h" char *savedir; +char *datadir; /* The filename for the current image: */ -char *get_fname(const char *const name) +char *get_fname(const char *const name, int kind) { char f[512]; - const char *tux_settings_dir; + char * dir; - /* Where is the user's data directory? - This is where their saved files are stored, - local fonts, brushes and stamps can be found, - and where the "current_id.txt" file is saved */ + /* DIR_SAVE: Where is the user's saved directory? + This is where their saved files are stored + and where the "current_id.txt" file is saved. + + Windows predefines "savedir" as: + "C:\Documents and Settings\%USERNAME%\Application Data\TuxPaint" + though it may get overridden with "--savedir" option + + BeOS similarly predefines "savedir" as "./userdata"... + + Macintosh: It's under ~/Library/Application Support/TuxPaint + + Linux & Unix: It's under ~/.tuxpaint + + DIR_DATA: Where is the user's data directory? + This is where local fonts, brushes and stamps can be found. */ + + if (kind == DIR_SAVE) + dir = savedir; + else if (kind == DIR_DATA) + dir = datadir; + else + return NULL; + #ifdef WIN32 - /* Windows predefines "savedir" as: - "C:\Documents and Settings\%USERNAME%\Application Data\TuxPaint" - though it may get overridden with "--savedir" option */ - - snprintf(f, sizeof(f), "%s/%s", savedir, name); - + snprintf(f, sizeof(f), "%s/%s", dir, name); #elif __BEOS__ - /* BeOS similarly predefines "savedir" as "./userdata"... */ - if (*name == '\0') - strcpy(f, savedir); + strcpy(f, dir); else - snprintf(f, sizeof(f), "%s/%s", savedir, name); - -#elif __APPLE__ - /* Macintosh: It's under ~/Library/Application Support/TuxPaint */ - - tux_settings_dir = "Library/Application Support/TuxPaint"; -#else - /* Linux & Unix: It's under ~/.tuxpaint */ - - tux_settings_dir = ".tuxpaint"; + snprintf(f, sizeof(f), "%s/%s", dir, name); #endif /* Put together home directory path + settings directory + filename... */ - if (savedir == NULL) + if (dir == NULL) { - /* Save directory not overridden: */ + fprintf(stderr, "Warning: get_fname() has a NULL dir...!?\n"); + return strdup(name);; + } - if (getenv("HOME") != NULL) - { - if (*name == '\0') - { - /* (Some mkdir()'s don't like trailing slashes) */ + if (*name != '\0') + { + /* (Some mkdir()'s don't like trailing slashes) */ - snprintf(f, sizeof(f), "%s/%s", getenv("HOME"), tux_settings_dir); - } - else - { - snprintf(f, sizeof(f), "%s/%s/%s", - getenv("HOME"), tux_settings_dir, name); - } - } - else - { - /* WOAH! Don't know where HOME directory is! Last resort, use '.'! */ - - strcpy(f, name); - } + snprintf(f, sizeof(f), "%s/%s", dir, name); } else { - /* User had overridden save directory with "--savedir" option: */ - - if (*name != '\0') - { - /* (Some mkdir()'s don't like trailing slashes) */ - - snprintf(f, sizeof(f), "%s/%s", savedir, name); - } - else - { - snprintf(f, sizeof(f), "%s", savedir); - } + snprintf(f, sizeof(f), "%s", dir); } return strdup(f); } + diff --git a/src/get_fname.h b/src/get_fname.h index fde35fa65..8a6f9c3ca 100644 --- a/src/get_fname.h +++ b/src/get_fname.h @@ -6,8 +6,14 @@ #define GET_FNAME_H extern char *savedir; +extern char *datadir; -char *get_fname(const char *const name); +enum { + DIR_SAVE, + DIR_DATA +}; + +char *get_fname(const char *const name, int kind); #endif diff --git a/src/manpage/tp-magic-config.3 b/src/manpage/tp-magic-config.3 deleted file mode 100644 index ab75115a0..000000000 --- a/src/manpage/tp-magic-config.3 +++ /dev/null @@ -1,86 +0,0 @@ -.\" tp-magic-config - 2007.07.31 -.TH TP-MAGIC-CONFIG 3 "31 Jul 2007" "2007.07.31" "Tux Paint Import" -.SH NAME -tp-magic-config -- Helps creating 'Magic' tool plugins for Tux Paint(1) - -.SH SYNOPSYS -.TP 16 -.B tp-magic-config [\-\-apiversion | \-\-version | \-\-cflags | \-\-pluginprefix | \-\-dataprefix] - -.SH DESCRIPTION -\fItp-magic-config\fP is a simple shell script that responds with various -pieces of information about the currently-installed version of -\fITux Paint\fP(1) that are useful when building 'Magic' tool plugins. - -.SH OPTIONS -.TP 8 -.B \-\-apiversion -Outputs the version of the \fITux Paint\fP 'Magic' tool plugin API that the -installed copy of \fITux Paint\fP supports. (For API compatibility testing.) -.TP 8 -.B \-\-version -Outputs the version of \fITux Paint\fP that \fItp-magic-config\fP -corresponds to. -.TP 8 -.B \-\-cflags -Outputs the compiler flags that \fITux Paint\fP 'Magic' tool plugins should -be compiled with. (For example, a "\-I" include path option that tells the -compiler where it can find the plugin API header file, "tp_magic_config.h", -that plugins must #include.) -.TP 8 -.B \-\-pluginprefix -Outputs the directory where the installed copy of \fITux Paint\fP expects -to find 'Magic' tool plugins (".so" shared objects). -.TP 8 -.B \-\-dataprefix -Outputs the directory where the installed copy of \fITux Paint\fP keeps its -global data files (e.g., "/usr/share/tuxpaint/"). This is the same value that -plugins will receive in the "data_directory" string within the -"magic_api" structure sent to the plugins' functions. - -.SH SHELL EXAMPLES -gcc -shared `tp-magic-config --cflags` my_plugin.c -o my_plugin.so -.PP -sudo cp my_plugin.so `tp-magic-config \-\-pluginprefix` -.PP -sudo cp my_plugin_icon.png `tp-magic-config \-\-dataprefix`/images/magic/ - -.SH MAKEFILE EXAMPLE -MAGIC_CFLAGS=$(shell tp-magic-config --cflags) -.br -MAGIC_PREFIX=$(shell tp-magic-config --pluginprefix) -.br -DATA_PREFIX=$(shell tp-magic-config --dataprefix) -.PP -all: my_plugin.so -.PP -my_plugin.so: my_plugin.c -.PP $(CC) -shared $(MAGIC_CFLAGS) my_plugin.c -o my_plugin.so -.PP -install: install-so install-data -.PP -install-so: -.br - mkdir -p $(MAGIC_PREFIX) -.br - cp my_plugin.so $(MAGIC_PREFIX)/ -.br - chmod 644 $(MAGIC_PREFIX)/my_plugin.so -.PP -install-data: -.br - mkdir -p $(DATA_PREFIX) -.br - cp icons/my_plugin_icon.png $(DATA_PREFIX)/images/magic/ -.br - chmod 644 $(DATA_PREFIX)/images/magic/my_plugin_icon.png - -.SH AUTHOR -Bill Kendrick. - - -.SH "SEE ALSO" -.BR tuxpaint (1), -.PP -And documentation within /usr/[local/]share/doc/tuxpaint/. - diff --git a/src/manpage/tuxpaint.1 b/src/manpage/tuxpaint.1 index 7cfb2dc93..271997abd 100644 --- a/src/manpage/tuxpaint.1 +++ b/src/manpage/tuxpaint.1 @@ -1,7 +1,7 @@ -.\" tuxpaint.1 - 2007.07.24 -.TH TUXPAINT 1 "24 July 2007" "0.9.18" "Tux Paint" +.\" tuxpaint.1 - 2007.08.02 +.TH TUXPAINT 1 "2 August 2007" "0.9.18" "Tux Paint" .SH NAME -tuxpaint -- A drawing program for young children. +tuxpaint -- "Tux Paint", a drawing program for young children. .SH SYNOPSYS .B tuxpaint @@ -10,62 +10,127 @@ tuxpaint -- A drawing program for young children. .TP 9 .B tuxpaint [\-\-fullscreen] -[\-\-native] +.br [\-\-WIDTHxHEIGHT] +.br +[\-\-native] +.br +[\-\-orient=portrait] +.br [\-\-startblank] +.br [\-\-nosound] +.br [\-\-noquit] +.br [\-\-noprint] +.br [\-\-printdelay=\fISECONDS\fP] +.br [\-\-printcfg] +.br +[\-\-altprintalways | \-\-altprintnever] +.br [\-\-papersize \fIPAPERSIZE\fP | \-\-papersize help] +.br [\-\-simpleshapes] +.br [\-\-uppercase] +.br [\-\-grab] +.br [\-\-noshortcuts] +.br [\-\-nowheelmouse] +.br [\-\-nobuttondistinction] +.br [\-\-nofancycursors] +.br [\-\-hidecursor] +.br [\-\-nooutlines] +.br [\-\-nostamps] +.br [\-\-nostampcontrols] +.br [\-\-mirrorstamps] +.br [\-\-keyboard] +.br [\-\-nosysfonts] +.br [\-\-savedir \fIDIR\fP] +.br +[\-\-datadir \fIDIR\fP] +.br [\-\-saveover] +.br [\-\-saveovernew] +.br [\-\-nosave] +.br [\-\-autosave] +.br [\-\-colorfile \fIFILE\fP] .TP 9 .B tuxpaint (defaults) [\-\-windowed] +.br [\-\-800x600] +.br +[\-\-orient=landscape] +.br [\-\-startlast] +.br [\-\-sound] +.br [\-\-quit] +.br [\-\-print] +.br [\-\-printdelay=0] +.br [\-\-noprintcfg] +.br +[\-\-altprintmod] +.br [\-\-complexshapes] +.br [\-\-mixedcase] +.br [\-\-dontgrab] +.br [\-\-shortcuts] +.br [\-\-wheelmouse] +.br [\-\-buttondistinction] +.br [\-\-fancycursors] +.br [\-\-showcursor] +.br [\-\-outlines] +.br [\-\-stamps] +.br [\-\-stampcontrols] +.br [\-\-dontmirrorstamps] +.br [\-\-mouse] +.br [\-\-sysfonts] +.br [\-\-saveoverask] +.br [\-\-save] +.br +[\-\-noautosave] +.br .TP 9 .B tuxpaint @@ -77,7 +142,9 @@ tuxpaint -- A drawing program for young children. .TP 9 .B tuxpaint -[\-\-nosysconfig] [\-\-nolockfile] +[\-\-nosysconfig] +.br +[\-\-nolockfile] .SH DESCRIPTION .PP @@ -124,7 +191,16 @@ When in fullscreen mode, use the system's default screen resolution. .B \-\-WIDTHxHEIGHT Run \fITux Paint\fP in a particularly-sized window, or at a particular fullscreen resolution (if \-\-native is not used). Default is 800x600. -Minimum is 640x480. Portrait and landscape orientations are both supported. +Minimum width is 640. Minimum height is 480. Portrait and landscape +orientations are both supported. (Also see \-\-orient, below.) + +.TP 8 +.B \-\-orient=landscape \-\-orient=portrait +If \-\-orient=portraitis set, asks \fITux Paint\fP to swap the WIDTH and HEIGHT +values it uses for windowed or fullscreen mode, without having to actually +change the WIDTH and HEIGHT values in the configuration file or on the +command-line. (This is useful on devices where the screen can be rotated, +e.g. tablet PCs.) .TP 8 .B \-\-nosound \-\-sound @@ -148,14 +224,24 @@ seconds. Default is 0 (no limitation). .TP 8 .B \-\-printcfg \-\-noprintcfg -(Windows only.) Enable or disable loading and saving of printer settings. -By default, \fITux Paint\fP will print to the default printer with default -settings. Pressing \fI[ALT]\fP while pushing the \fIPrint\fP button -will cause a Windows printer dialog to appear (as long as you're not in -fullscreen mode.) If \-\-printcfg is used, your previous settings will +(Windows and Mac OS X only.) Enable or disable loading and saving of +printer settings. By default, \fITux Paint\fP will print to the default +printer with default settings. Pressing \fI[ALT]\fP while pushing the +\fIPrint\fP button will cause a printer dialog to appear (as long as you're +not in fullscreen mode; see also \-\-altprintalways and \-\-altprintnever, +below.) Unless \-\-noprintcfg is used, your previous settings will be loaded when \fITux Paint\fP starts up, and setting changes will be saved for next time. +.TP 8 +.B \-\-altprintmod \-\-altprintnever \-\-altprintalways +These options control whether an system printer dialog appears when the +user clicks the \fIPrint\fP button. By default (\-\-altprintmod), pressing +\fI[ALT]\fP while clicking \fIPrint\fP will bring up a dialog (unless you're +in fullscreen mode). With \-\-altprintalways, the dialog will always appear, +even if \fI[ALT]\fP is not being held. With \-\-altprintnever, the dialog +will never appear, even if \fI[ALT]\fP is being held. + .TP 8 .B \-\-papersize \fIPAPERSIZE\fP (Only when PostScript printing is used \- not Windows, Mac OS X or BeOS.) @@ -254,8 +340,12 @@ use the \fInosysfonts\fP option to disable this feature. .TP 8 .B \-\-savedir \fIDIR\fP -Specify where \fITux Paint\fP should save files. By default, this is -"~/.tuxpaint/saved" under Linux and Unix, and "userdata\\" under Windows. +Specify where \fITux Paint\fP should save files. + +.TP 8 +.B \-\-datadir \fIDIR\fP +Specify where \fITux Paint\fP should look for personal data files +(brushes, stamps, etc.). .TP 8 .B \-\-saveover \-\-saveovernew \-\-saveoverask @@ -764,6 +854,7 @@ Martin Zhekov. .SH "SEE ALSO" .BR tuxpaint-import (1), .BR tuxpaint-config (1), +.BR tp-magic-config (1), .BR xpaint (1), .BR gpaint (1), .BR gimp (1), diff --git a/src/tp-magic-config.sh.in b/src/tp-magic-config.sh.in index 88a37b954..e1f7db362 100755 --- a/src/tp-magic-config.sh.in +++ b/src/tp-magic-config.sh.in @@ -26,11 +26,11 @@ # (See COPYING.txt) # Note: "__VERSION__", "__APIVERSION__", "__INCLUDE__", -# "__PLUGINPREFIX__" and "__DATAPREFIX__" are replaced by -# values in Tux Paint's Makefile, via 'sed', by the 'make tp-magic-config' +# "__PLUGINPREFIX__", "__PLUGINDOCPREFIX__" and "__DATAPREFIX__" are replaced +# by values in Tux Paint's Makefile, via 'sed', by the 'make tp-magic-config' # target. -# July 5, 2007 - July 31, 2007 +# July 5, 2007 - August 2, 2007 if [ $# -ne 0 ]; then @@ -54,7 +54,11 @@ if [ $# -ne 0 ]; then echo "__PLUGINPREFIX__" exit fi + if [ $1 = "--plugindocprefix" ]; then + echo "__PLUGINDOCPREFIX__" + exit + fi fi -echo "Usage: tp-magic-config [--apiversion | --version | --cflags | --pluginprefix | --dataprefix]" +echo "Usage: tp-magic-config [--apiversion | --version | --cflags | --pluginprefix | --plugindocprefix | --dataprefix]" diff --git a/src/tuxpaint.c b/src/tuxpaint.c index a2790b96f..c23dd0f32 100644 --- a/src/tuxpaint.c +++ b/src/tuxpaint.c @@ -4874,23 +4874,32 @@ static void show_usage(FILE * f, char *prg) "Usage: %s {--usage | --help | --version | --verbose-version | --copying}\n" "\n" " %s [--windowed | --fullscreen]\n" - " %s [--WIDTHxHEIGHT | --native] [--orient=landscape | --orient=portrait]\n" - " %s [--startblank | --startlast ]\n" - " %s [--sound | --nosound] [--quit | --noquit]\n" - " %s [--print | --noprint] [--complexshapes | --simpleshapes]\n" + " %s [--WIDTHxHEIGHT | --native]\n" + " %s [--orient=landscape | --orient=portrait]\n" + " %s [--startblank | --startlast]\n" + " %s [--sound | --nosound]\n" + " %s [--quit | --noquit]\n" + " %s [--print | --noprint]\n" + " %s [--complexshapes | --simpleshapes]\n" " %s [--mixedcase | --uppercase]\n" - " %s [--fancycursors | --nofancycursors | --hidecursor ]\n" - " %s [--mouse | --keyboard] [--dontgrab | --grab]\n" - " %s [--noshortcuts | --shortcuts] [--wheelmouse | --nowheelmouse]\n" - " %s [--nobuttondistinction | --buttondistinction ]\n" - " %s [--outlines | --nooutlines] [--stamps | --nostamps]\n" + " %s [--fancycursors | --nofancycursors]\n" + " %s [--hidecursor | --showcursor]\n" + " %s [--mouse | --keyboard]\n" + " %s [--dontgrab | --grab]\n" + " %s [--noshortcuts | --shortcuts]\n" + " %s [--wheelmouse | --nowheelmouse]\n" + " %s [--nobuttondistinction | --buttondistinction]\n" + " %s [--outlines | --nooutlines]\n" + " %s [--stamps | --nostamps]\n" " %s [--sysfonts | --nosysfonts]\n" " %s [--nostampcontrols | --stampcontrols]\n" " %s [--mirrorstamps | --dontmirrorstamps]\n" " %s [--saveoverask | --saveover | --saveovernew]\n" - " %s [--nosave | --save] [--autosave | --noautosave]\n" + " %s [--nosave | --save]\n" + " %s [--autosave | --noautosave]\n" " %s [--savedir DIRECTORY]\n" -#ifdef WIN32 + " %s [--datadir DIRECTORY]\n" +#if defined(WIN32) || defined(__APPLE__) " %s [--printcfg | --noprintcfg]\n" #endif " %s [--printdelay=SECONDS]\n" @@ -4899,11 +4908,15 @@ static void show_usage(FILE * f, char *prg) " %s [--papersize PAPERSIZE | --papersize help]\n" #endif " %s [--lang LANGUAGE | --locale LOCALE | --lang help]\n" - " %s [--nosysconfig] [--nolockfile]\n" + " %s [--nosysconfig]\n" + " %s [--nolockfile]\n" " %s [--colorfile FILE]\n" /* " %s [--record FILE | --playback FILE]\n" */ "\n", prg, prg, + blank, blank, blank, blank, + blank, blank, blank, + blank, blank, blank, blank, blank, blank, blank, blank, blank, blank, blank, blank, blank, blank, blank, blank, blank, blank, @@ -5519,7 +5532,7 @@ static void load_stamp_dir(SDL_Surface * screen, const char *const dir) static void load_stamps(SDL_Surface * screen) { - char *homedirdir = get_fname("stamps"); + char *homedirdir = get_fname("stamps", DIR_DATA); default_stamp_size = compute_default_scale_factor(1.0); @@ -5530,7 +5543,7 @@ static void load_stamps(SDL_Surface * screen) #endif #ifdef WIN32 free(homedirdir); - homedirdir = get_fname("data/stamps"); + homedirdir = get_fname("data/stamps", DIR_DATA); load_stamp_dir(screen, homedirdir); #endif @@ -5688,13 +5701,41 @@ static void setup(int argc, char *argv[]) #ifdef WIN32 - savedir = GetDefaultSaveDir("TuxPaint"); -#elif __BEOS__ - savedir = strdup("./userdata"); -#else - savedir = NULL; -#endif + /* Windows */ + savedir = GetDefaultSaveDir("TuxPaint"); + datadir = GetDefaultDataDir("TuxPaint"); +#elif __BEOS__ + /* BeOS */ + + savedir = strdup("./userdata"); + datadir = strdup("./userdata"); +#else + /* Mac OS X & Linux */ + + if (getenv("HOME") != NULL) + { + char tmp[MAX_PATH]; + + snprintf(tmp, MAX_PATH, "%s/%s", getenv("HOME"), +#ifdef __APPLE__ + "Library/Application Support/TuxPaint" +#else + ".tuxpaint" +#endif + ); + + savedir = strdup(tmp); + datadir = strdup(tmp); + } + else + { + /* Woah, don't know where $HOME is? */ + + fprintf(stderr, "Error: You have no $HOME environment variable!\n"); + exit(1); + } +#endif /* Load options from global config file: */ @@ -5739,7 +5780,7 @@ static void setup(int argc, char *argv[]) #if defined(WIN32) /* Default local config file in users savedir directory on Windows */ - snprintf(str, sizeof(str), "%s/tuxpaint.cfg", savedir); + snprintf(str, sizeof(str), "%s/tuxpaint.cfg", savedir); /* FIXME */ #elif defined(__BEOS__) /* BeOS: Use a "tuxpaint.cfg" file: */ @@ -6044,15 +6085,15 @@ static void setup(int argc, char *argv[]) } else if (strcmp(argv[i], "--noprintcfg") == 0) { -#ifndef WIN32 - fprintf(stderr, "Note: printcfg option only applies to Windows!\n"); +#if !defined(WIN32) && !defined(__APPLE__) + fprintf(stderr, "Note: printcfg option only applies to Windows and Mac OS X!\n"); #endif use_print_config = 0; } else if (strcmp(argv[i], "--printcfg") == 0) { -#ifndef WIN32 - fprintf(stderr, "Note: printcfg option only applies to Windows!\n"); +#if !defined(WIN32) && !defined(__APPLE__) + fprintf(stderr, "Note: printcfg option only applies to Windows and Mac OS X!\n"); #endif use_print_config = 1; } @@ -6126,6 +6167,26 @@ static void setup(int argc, char *argv[]) exit(1); } } + else if (strcmp(argv[i], "--datadir") == 0) + { + if (i < argc - 1) + { + if (datadir != NULL) + free(datadir); + + datadir = strdup(argv[i + 1]); + remove_slash(datadir); + i++; + } + else + { + /* Forgot to specify the directory name! */ + + fprintf(stderr, "%s takes an argument\n", argv[i]); + show_usage(stderr, (char *) getfilename(argv[0])); + exit(1); + } + } else if (strcmp(argv[i], "--record") == 0 || strcmp(argv[i], "--playback") == 0) { @@ -6251,9 +6312,9 @@ static void setup(int argc, char *argv[]) /* Look for the lockfile... */ #ifndef WIN32 - lock_fname = get_fname("lockfile.dat"); + lock_fname = get_fname("lockfile.dat", DIR_SAVE); #else - lock_fname = get_temp_fname("lockfile.dat"); + lock_fname = get_temp_fname("lockfile.dat", DIR_SAVE); #endif fi = fopen(lock_fname, "r"); @@ -6289,7 +6350,7 @@ static void setup(int argc, char *argv[]) /* Okay to run; create/update the lockfile */ /* (Make sure the directory exists, first!) */ - homedirdir = get_fname(""); + homedirdir = get_fname("", DIR_SAVE); mkdir(homedirdir, 0755); free(homedirdir); @@ -6978,11 +7039,11 @@ static void setup(int argc, char *argv[]) /* Load brushes: */ load_brush_dir(screen, DATA_PREFIX "brushes"); - homedirdir = get_fname("brushes"); + homedirdir = get_fname("brushes", DIR_DATA); load_brush_dir(screen, homedirdir); #ifdef WIN32 free(homedirdir); - homedirdir = get_fname("data/brushes"); + homedirdir = get_fname("data/brushes", DIR_DATA); load_brush_dir(screen, homedirdir); #endif @@ -10401,7 +10462,7 @@ static void load_starter_id(char *saved_id) int r, g, b; snprintf(fname, sizeof(fname), "saved/%s.dat", saved_id); - rname = get_fname(fname); + rname = get_fname(fname, DIR_SAVE); starter_id[0] = '\0'; @@ -10457,7 +10518,7 @@ static void load_starter(char *img_id) if (starter_personal == 0) dirname = strdup(DATA_PREFIX "starters"); else - dirname = get_fname("starters"); + dirname = get_fname("starters", DIR_DATA); /* Clear them to NULL first: */ img_starter = NULL; @@ -10562,7 +10623,7 @@ static void load_current(void) /* Determine the current picture's ID: */ - fname = get_fname("current_id.txt"); + fname = get_fname("current_id.txt", DIR_SAVE); fi = fopen(fname, "r"); if (fi == NULL) @@ -10594,7 +10655,7 @@ static void load_current(void) { snprintf(ftmp, sizeof(ftmp), "saved/%s%s", file_id, FNAME_EXTENSION); - fname = get_fname(ftmp); + fname = get_fname(ftmp, DIR_SAVE); tmp = IMG_Load(fname); @@ -10634,7 +10695,7 @@ static int make_directory(const char *path, const char *errmsg) char *fname; int res; - fname = get_fname(path); + fname = get_fname(path, DIR_SAVE); res = mkdir(fname, 0755); if (res != 0 && errno != EEXIST) { @@ -10662,7 +10723,7 @@ static void save_current(void) draw_tux_text(TUX_OOPS, strerror(errno), 0); } - fname = get_fname("current_id.txt"); + fname = get_fname("current_id.txt", DIR_SAVE); fi = fopen(fname, "w"); if (fi == NULL) @@ -11360,9 +11421,9 @@ static void cleanup(void) FILE *fi; #ifndef WIN32 - lock_fname = get_fname("lockfile.dat"); + lock_fname = get_fname("lockfile.dat", DIR_SAVE); #else - lock_fname = get_temp_fname("lockfile.dat"); + lock_fname = get_temp_fname("lockfile.dat", DIR_SAVE); #endif zero_time = (time_t) 0; @@ -11802,7 +11863,7 @@ static int do_save(int tool, int dont_show_success_results) /* Save the file: */ snprintf(tmp, sizeof(tmp), "saved/%s%s", file_id, FNAME_EXTENSION); - fname = get_fname(tmp); + fname = get_fname(tmp, DIR_SAVE); debug(fname); fi = fopen(fname, "wb"); @@ -11835,7 +11896,7 @@ static int do_save(int tool, int dont_show_success_results) /* (Was thumbnail in old directory, rather than under .thumbs?) */ snprintf(tmp, sizeof(tmp), "saved/%s-t%s", file_id, FNAME_EXTENSION); - fname = get_fname(tmp); + fname = get_fname(tmp, DIR_SAVE); fi = fopen(fname, "r"); if (fi != NULL) { @@ -11848,7 +11909,7 @@ static int do_save(int tool, int dont_show_success_results) snprintf(tmp, sizeof(tmp), "saved/.thumbs/%s-t%s", file_id, FNAME_EXTENSION); - fname = get_fname(tmp); + fname = get_fname(tmp, DIR_SAVE); } debug(fname); @@ -11880,7 +11941,7 @@ static int do_save(int tool, int dont_show_success_results) canvas_color_b != 255) { snprintf(tmp, sizeof(tmp), "saved/%s.dat", file_id); - fname = get_fname(tmp); + fname = get_fname(tmp, DIR_SAVE); fi = fopen(fname, "w"); if (fi != NULL) { @@ -12165,7 +12226,7 @@ int do_open(void) { /* First, check for saved-images: */ - dirname[places_to_look] = get_fname("saved"); + dirname[places_to_look] = get_fname("saved", DIR_SAVE); } else if (places_to_look == PLACE_PERSONAL_STARTERS_DIR) { @@ -12926,7 +12987,7 @@ int do_open(void) snprintf(fname, sizeof(fname), "saved/%s%s", d_names[which], d_exts[which]); - rfname = get_fname(fname); + rfname = get_fname(fname, DIR_SAVE); debug(rfname); if (unlink(rfname) == 0) @@ -12940,7 +13001,7 @@ int do_open(void) "saved/.thumbs/%s-t.png", d_names[which]); free(rfname); - rfname = get_fname(fname); + rfname = get_fname(fname, DIR_SAVE); debug(rfname); unlink(rfname); @@ -12952,7 +13013,7 @@ int do_open(void) snprintf(fname, sizeof(fname), "saved/%s-t.png", d_names[which]); free(rfname); - rfname = get_fname(fname); + rfname = get_fname(fname, DIR_SAVE); debug(rfname); unlink(rfname); @@ -12964,7 +13025,7 @@ int do_open(void) snprintf(fname, sizeof(fname), "saved/%s.dat", d_names[which]); free(rfname); - rfname = get_fname(fname); + rfname = get_fname(fname, DIR_SAVE); debug(rfname); unlink(rfname); @@ -13201,7 +13262,7 @@ int do_slideshow(void) /* Load list of saved-images: */ - dirname = get_fname("saved"); + dirname = get_fname("saved", DIR_SAVE); /* Read directory of images and build thumbnails: */ @@ -14522,7 +14583,7 @@ void do_print(void) char f[512]; int show = (want_alt_printcommand && !fullscreen); - snprintf(f, sizeof(f), "%s/%s", savedir, "print.cfg"); + snprintf(f, sizeof(f), "%s/%s", savedir, "print.cfg"); // FIXME { const char *error = @@ -15176,16 +15237,16 @@ static void parse_options(FILE * fi) } else if (strcmp(str, "printcfg=yes") == 0) { -#ifndef WIN32 - fprintf(stderr, "Note: printcfg option only applies to Windows!\n"); +#if !defined(WIN32) && !defined(__APPLE__) + fprintf(stderr, "Note: printcfg option only applies to Windows and Mac OS X!\n"); #endif use_print_config = 1; } else if (strcmp(str, "printcfg=no") == 0 || strcmp(str, "noprintcfg=yes") == 0) { -#ifndef WIN32 - fprintf(stderr, "Note: printcfg option only applies to Windows!\n"); +#if !defined(WIN32) && !defined(__APPLE__) + fprintf(stderr, "Note: printcfg option only applies to Windows and Mac OS X!\n"); #endif use_print_config = 0; } @@ -15248,6 +15309,15 @@ static void parse_options(FILE * fi) #ifdef DEBUG printf("savedir set to: %s\n", savedir); +#endif + } + else if (strstr(str, "datadir=") == str) + { + datadir = strdup(str + 8); + remove_slash(datadir); + +#ifdef DEBUG + printf("datadir set to: %s\n", datadir); #endif } } @@ -16698,7 +16768,7 @@ int do_new_dialog(void) { /* Check for coloring-book style 'starter' images in our folder: */ - dirname[places_to_look] = get_fname("starters"); + dirname[places_to_look] = get_fname("starters", DIR_DATA); } else if (places_to_look == PLACE_STARTERS_DIR) {