Sound pause/unpause Magic API functions...

...plus documenting them.
...plus using them in new "Comic Dots" Magic tool.

Makefile

@@ -4,7 +4,7 @@
 # Various contributors (see AUTHORS.txt)
 # https://tuxpaint.org/
 
-# June 14, 2002 - September 16, 2024
+# June 14, 2002 - September 17, 2024
 
 
 # The version number, for release:
@@ -26,7 +26,7 @@ else
   VER_DATE=$(shell date "+%Y-%m-%d")
 endif
 
-MAGIC_API_VERSION:=0x0000000A
+MAGIC_API_VERSION:=0x0000000B
 
 # Need to know the OS
 SYSNAME:=$(shell uname -s)

docs/CHANGES.txt

@@ -18,6 +18,14 @@ https://tuxpaint.org/
       - TODO needs icon
       Closes https://sourceforge.net/p/tuxpaint/feature-requests/257/
 
+  * Magic Tool Improvements:
+    ------------------------
+    * Sound pause/resume functions added to API
+      (`playingsound()`, `pausesound()`, and `unpausesound()`).
+      + Used by new "Comic Docs" magic tool.
+      + Note: `TP_MAGIC_API_VERSION` bumped to 0x0000000B.
+      + Bill Kendrick <bill@newbreedsoftware.com>
+
   * Improvements to Fill tool:
     --------------------------
     * New "Eraser" flood fill mode, to expose the background

docs/en/MAGIC-API.txt

@@ -6,7 +6,7 @@
         Copyright © 2007-2024 by various contributors; see AUTHORS.txt.
                              https://tuxpaint.org/
 
-                                 June 1, 2024
+                              September 17, 2024
 
 +--------------------------------------------------+
 |                Table of Contents                 |
@@ -22,6 +22,7 @@
 |           o Pixel Manipulations                  |
 |           o Helper Functions                     |
 |           o Informational                        |
+|           o Sound Functions                      |
 |           o Tux Paint System Calls               |
 |           o Color Conversions                    |
 |       + Helper Macros in "tp_magic_api.h"        |
@@ -640,12 +641,7 @@ char * data_directory
 
 
 
-Tux Paint System Calls
+Sound Functions
-
-void update_progress_bar(void)
-    Asks Tux Paint to animate and draw one frame of its progress bar (at the
-    bottom of the screen). Useful for routines that may take a long time, to
-    provide feedback to the user that Tux Paint has not crashed or frozen.
 
 void playsound(Mix_Chunk * snd, int pan, int dist)
 
@@ -670,6 +666,46 @@ void stopsound(void)
     silence effects when the user stops using the tool (in your 'release'
     function).
 
+int playingsound(void)
+
+    Call this function to determine whether a magic tool sound effect is still
+    currently playing. Can be used by magic tools that pause and unpause their
+    sounds (see below) to determine whether it's time to start a new sound —
+    call playsound() instead of unpausesound(). A '1' is returned if a sound is
+    playing; '0' otherwise.
+
+    Note: Added to Tux Paint 0.9.34; Magic API version 0x0000000B.
+
+
+
+void pausesound(void)
+
+    Pauses the magic tool sound effect; it may be unpaused to resume playing.
+    Useful when a magic tool sound is very long; avoid repeatedly playing just
+    a short clip of the beginning when the user draws small strokes by starting
+    (playsound()) and stopping (stopsound()) the sound. Use playingsound() to
+    determine whether you can unpause or must play from the start.
+
+    Note: Added to Tux Paint 0.9.34; Magic API version 0x0000000B.
+
+
+
+void unpausesound(void)
+
+    Resumes a paused magic tool sound effect, if one was playing.
+
+    Note: Added to Tux Paint 0.9.34; Magic API version 0x0000000B.
+
+
+
+
+Tux Paint System Calls
+
+void update_progress_bar(void)
+    Asks Tux Paint to animate and draw one frame of its progress bar (at the
+    bottom of the screen). Useful for routines that may take a long time, to
+    provide feedback to the user that Tux Paint has not crashed or frozen.
+
 void special_notify(int flag)
     This function notifies Tux Paint of special events. Various values defined
     in "tp_magic_api.h" can be 'or'ed together (using C's boolean 'or': "|")

docs/en/README.txt

@@ -6,7 +6,7 @@
         Copyright © 2002-2024 by various contributors; see AUTHORS.txt.
                              https://tuxpaint.org/
 
-                              September 16, 2024
+                              September 17, 2024
 
 +-------------------------------------------------+
 |                Table of Contents                |
@@ -105,6 +105,12 @@ D. What's New in Tux Paint version 0.9.34?
 
 New brushes
     New brushes for the Paint and Lines tools: Fluff (gradient).
+New Magic tool: Comic dots
+    Draws a repeating dot pattern, simulating the "Ben Day process" used in
+    early comic books.
+
+Magic API Updates
+    Sound pause and resume functions added.
 
 See CHANGES.txt for the complete list of changes.
 

docs/en/html/MAGIC-API.html

@@ -102,7 +102,7 @@
           </p>
 
           <p>
-            June  1, 2024          </p>
+            September 17, 2024          </p>
         </center>
       </header>
 
@@ -128,7 +128,7 @@
                     </ul>
                   </li>
                   <li><a href="#tpfuncs">Tux Paint Functions and Data</a>                    <ul>
-                      <li><a href="#pixel_manip">Pixel Manipulations</a></li>                      <li><a href="#helper_funcs">Helper Functions</a></li>                      <li><a href="#informational">Informational</a></li>                      <li><a href="#syscalls">Tux Paint System Calls</a></li>                      <li><a href="#color_convs">Color Conversions</a></li>                    </ul>
+                      <li><a href="#pixel_manip">Pixel Manipulations</a></li>                      <li><a href="#helper_funcs">Helper Functions</a></li>                      <li><a href="#informational">Informational</a></li>                      <li><a href="#sound">Sound Functions</a></li>                      <li><a href="#syscalls">Tux Paint System Calls</a></li>                      <li><a href="#color_convs">Color Conversions</a></li>                    </ul>
                   </li>
                   <li><a href="#macros">Helper Macros in "tp_magic_api.h"</a></li>                  <li><a href="#consts">Constant Definitions in "tp_magic_api.h"</a></li>                </ul>
               </li>
@@ -636,17 +636,13 @@
           </dl>
         </section><!-- H3: Informational -->
 
-        <section class="indent"><!-- H3: Tux Paint System Calls -->
+        <section class="indent"><!-- H3: Sound Functions -->
           <header>
-            <h3 id="syscalls">
+            <h3 id="sound">
-              Tux Paint System Calls            </h3>
+              Sound Functions            </h3>
           </header>
 
           <dl>
-            <dt><code><b>void update_progress_bar(void)</b></code></dt>
-            <dd>
-              Asks Tux Paint to animate and draw one frame of its progress bar (at the bottom of the screen).  Useful for routines that may take a long time, to provide feedback to the user that Tux Paint has not crashed or frozen.            </dd>
-
             <dt><code><b>void playsound(Mix_Chunk * snd, int pan, int dist)</b></code></dt>
             <dd>
               <p>
@@ -663,6 +659,43 @@
             <dd>
               This function stops playing a sound played by <code>playsound()</code>. It is useful to silence effects when the user stops using the tool (in your '<code>release</code>' function).            </dd>
 
+            <dt><code><b>int playingsound(void)</b></code></dt>
+            <dd>
+              <p>
+                Call this function to determine whether a magic tool sound effect is still currently playing. Can be used by magic tools that pause and unpause their sounds (see below) to determine whether it's time to start a new sound &mdash; call <code>playsound()</code> instead of <code>unpausesound()</code>.                A '1' is returned if a sound is playing; '0' otherwise.              </p>
+              <p>
+                <b>Note:</b> Added to Tux Paint 0.9.34; Magic API version 0x0000000B.              </p>
+            </dd>
+
+            <dt><code><b>void pausesound(void)</b></code></dt>
+            <dd>
+              <p>
+                Pauses the magic tool sound effect; it may be unpaused to resume playing. Useful when a magic tool sound is very long; avoid repeatedly playing just a short clip of the beginning when the user draws small strokes by starting (<code>playsound()</code>) and stopping (<code>stopsound()</code>) the sound. Use <code>playingsound()</code> to determine whether you can unpause or must play from the start.              </p>
+              <p>
+                <b>Note:</b> Added to Tux Paint 0.9.34; Magic API version 0x0000000B.              </p>
+            </dd>
+
+            <dt><code><b>void unpausesound(void)</b></code></dt>
+            <dd>
+              <p>
+                Resumes a paused magic tool sound effect, if one was playing.              </p>
+              <p>
+                <b>Note:</b> Added to Tux Paint 0.9.34; Magic API version 0x0000000B.              </p>
+            </dd>
+          </dl>
+        </section><!-- H3: Sound Functions -->
+
+        <section class="indent"><!-- H3: Tux Paint System Calls -->
+          <header>
+            <h3 id="syscalls">
+              Tux Paint System Calls            </h3>
+          </header>
+
+          <dl>
+            <dt><code><b>void update_progress_bar(void)</b></code></dt>
+            <dd>
+              Asks Tux Paint to animate and draw one frame of its progress bar (at the bottom of the screen).  Useful for routines that may take a long time, to provide feedback to the user that Tux Paint has not crashed or frozen.            </dd>
+
             <dt id="special_notify"><code><b>void special_notify(int flag)</b></code></dt>
             <dd>
               This function notifies Tux Paint of special events.  Various values defined in "<code>tp_magic_api.h</code>" can be 'or'ed together (using C's boolean 'or': "<code>|</code>") and sent to this function.              <dl>

docs/en/html/README.html

@@ -236,6 +236,9 @@
 
   <dt>New Magic tool: Comic dots</dt>
   <dd>Draws a repeating dot pattern, simulating the "Ben Day process" used in early comic books.</dd>
+
+  <dt>Magic API Updates</dt>
+  <dd>Sound pause and resume functions added.</dt>
 </dl>
 
     <p>

docs/es_ES.UTF-8/MAGIC-API.txt

@@ -6,7 +6,7 @@
         Copyright © 2007-2024 by various contributors; see AUTHORS.txt.
                              https://tuxpaint.org/
 
-                                 junio 1, 2024
+                              septiembre 17, 2024
 
 +--------------------------------------------------+
 |                Table of Contents                 |
@@ -22,6 +22,7 @@
 |           o Pixel Manipulations                  |
 |           o Helper Functions                     |
 |           o Informational                        |
+|           o Sound Functions                      |
 |           o Tux Paint System Calls               |
 |           o Color Conversions                    |
 |       + Helper Macros in "tp_magic_api.h"        |
@@ -640,12 +641,7 @@ char * data_directory
 
 
 
-Tux Paint System Calls
+Sound Functions
-
-void update_progress_bar(void)
-    Asks Tux Paint to animate and draw one frame of its progress bar (at the
-    bottom of the screen). Useful for routines that may take a long time, to
-    provide feedback to the user that Tux Paint has not crashed or frozen.
 
 void playsound(Mix_Chunk * snd, int pan, int dist)
 
@@ -670,6 +666,46 @@ void stopsound(void)
     silence effects when the user stops using the tool (in your 'release'
     function).
 
+int playingsound(void)
+
+    Call this function to determine whether a magic tool sound effect is still
+    currently playing. Can be used by magic tools that pause and unpause their
+    sounds (see below) to determine whether it's time to start a new sound —
+    call playsound() instead of unpausesound(). A '1' is returned if a sound is
+    playing; '0' otherwise.
+
+    Note: Added to Tux Paint 0.9.34; Magic API version 0x0000000B.
+
+
+
+void pausesound(void)
+
+    Pauses the magic tool sound effect; it may be unpaused to resume playing.
+    Useful when a magic tool sound is very long; avoid repeatedly playing just
+    a short clip of the beginning when the user draws small strokes by starting
+    (playsound()) and stopping (stopsound()) the sound. Use playingsound() to
+    determine whether you can unpause or must play from the start.
+
+    Note: Added to Tux Paint 0.9.34; Magic API version 0x0000000B.
+
+
+
+void unpausesound(void)
+
+    Resumes a paused magic tool sound effect, if one was playing.
+
+    Note: Added to Tux Paint 0.9.34; Magic API version 0x0000000B.
+
+
+
+
+Tux Paint System Calls
+
+void update_progress_bar(void)
+    Asks Tux Paint to animate and draw one frame of its progress bar (at the
+    bottom of the screen). Useful for routines that may take a long time, to
+    provide feedback to the user that Tux Paint has not crashed or frozen.
+
 void special_notify(int flag)
     This function notifies Tux Paint of special events. Various values defined
     in "tp_magic_api.h" can be 'or'ed together (using C's boolean 'or': "|")

docs/es_ES.UTF-8/README.txt

@@ -6,7 +6,7 @@
         Copyright © 2002-2024 by various contributors; see AUTHORS.txt.
                              https://tuxpaint.org/
 
-                              septiembre 16, 2024
+                              septiembre 17, 2024
 
 +-------------------------------------------------+
 |                Table of Contents                |
@@ -105,6 +105,12 @@ D. What's New in Tux Paint version 0.9.34?
 
 New brushes
     New brushes for the Paint and Lines tools: Fluff (gradient).
+New Magic tool: Comic dots
+    Draws a repeating dot pattern, simulating the "Ben Day process" used in
+    early comic books.
+
+Magic API Updates
+    Sound pause and resume functions added.
 
 See CHANGES.txt for the complete list of changes.
 

docs/es_ES.UTF-8/html/MAGIC-API.html

@@ -102,7 +102,7 @@
           </p>
 
           <p>
-            junio  1, 2024          </p>
+            septiembre 17, 2024          </p>
         </center>
       </header>
 
@@ -128,7 +128,7 @@
                     </ul>
                   </li>
                   <li><a href="#tpfuncs">Tux Paint Functions and Data</a>                    <ul>
-                      <li><a href="#pixel_manip">Pixel Manipulations</a></li>                      <li><a href="#helper_funcs">Helper Functions</a></li>                      <li><a href="#informational">Informational</a></li>                      <li><a href="#syscalls">Tux Paint System Calls</a></li>                      <li><a href="#color_convs">Color Conversions</a></li>                    </ul>
+                      <li><a href="#pixel_manip">Pixel Manipulations</a></li>                      <li><a href="#helper_funcs">Helper Functions</a></li>                      <li><a href="#informational">Informational</a></li>                      <li><a href="#sound">Sound Functions</a></li>                      <li><a href="#syscalls">Tux Paint System Calls</a></li>                      <li><a href="#color_convs">Color Conversions</a></li>                    </ul>
                   </li>
                   <li><a href="#macros">Helper Macros in "tp_magic_api.h"</a></li>                  <li><a href="#consts">Constant Definitions in "tp_magic_api.h"</a></li>                </ul>
               </li>
@@ -636,17 +636,13 @@
           </dl>
         </section><!-- H3: Informational -->
 
-        <section class="indent"><!-- H3: Tux Paint System Calls -->
+        <section class="indent"><!-- H3: Sound Functions -->
           <header>
-            <h3 id="syscalls">
+            <h3 id="sound">
-              Tux Paint System Calls            </h3>
+              Sound Functions            </h3>
           </header>
 
           <dl>
-            <dt><code><b>void update_progress_bar(void)</b></code></dt>
-            <dd>
-              Asks Tux Paint to animate and draw one frame of its progress bar (at the bottom of the screen).  Useful for routines that may take a long time, to provide feedback to the user that Tux Paint has not crashed or frozen.            </dd>
-
             <dt><code><b>void playsound(Mix_Chunk * snd, int pan, int dist)</b></code></dt>
             <dd>
               <p>
@@ -663,6 +659,43 @@
             <dd>
               This function stops playing a sound played by <code>playsound()</code>. It is useful to silence effects when the user stops using the tool (in your '<code>release</code>' function).            </dd>
 
+            <dt><code><b>int playingsound(void)</b></code></dt>
+            <dd>
+              <p>
+                Call this function to determine whether a magic tool sound effect is still currently playing. Can be used by magic tools that pause and unpause their sounds (see below) to determine whether it's time to start a new sound &mdash; call <code>playsound()</code> instead of <code>unpausesound()</code>.                A '1' is returned if a sound is playing; '0' otherwise.              </p>
+              <p>
+                <b>Note:</b> Added to Tux Paint 0.9.34; Magic API version 0x0000000B.              </p>
+            </dd>
+
+            <dt><code><b>void pausesound(void)</b></code></dt>
+            <dd>
+              <p>
+                Pauses the magic tool sound effect; it may be unpaused to resume playing. Useful when a magic tool sound is very long; avoid repeatedly playing just a short clip of the beginning when the user draws small strokes by starting (<code>playsound()</code>) and stopping (<code>stopsound()</code>) the sound. Use <code>playingsound()</code> to determine whether you can unpause or must play from the start.              </p>
+              <p>
+                <b>Note:</b> Added to Tux Paint 0.9.34; Magic API version 0x0000000B.              </p>
+            </dd>
+
+            <dt><code><b>void unpausesound(void)</b></code></dt>
+            <dd>
+              <p>
+                Resumes a paused magic tool sound effect, if one was playing.              </p>
+              <p>
+                <b>Note:</b> Added to Tux Paint 0.9.34; Magic API version 0x0000000B.              </p>
+            </dd>
+          </dl>
+        </section><!-- H3: Sound Functions -->
+
+        <section class="indent"><!-- H3: Tux Paint System Calls -->
+          <header>
+            <h3 id="syscalls">
+              Tux Paint System Calls            </h3>
+          </header>
+
+          <dl>
+            <dt><code><b>void update_progress_bar(void)</b></code></dt>
+            <dd>
+              Asks Tux Paint to animate and draw one frame of its progress bar (at the bottom of the screen).  Useful for routines that may take a long time, to provide feedback to the user that Tux Paint has not crashed or frozen.            </dd>
+
             <dt id="special_notify"><code><b>void special_notify(int flag)</b></code></dt>
             <dd>
               This function notifies Tux Paint of special events.  Various values defined in "<code>tp_magic_api.h</code>" can be 'or'ed together (using C's boolean 'or': "<code>|</code>") and sent to this function.              <dl>

docs/es_ES.UTF-8/html/README.html

@@ -236,6 +236,9 @@
 
   <dt>New Magic tool: Comic dots</dt>
   <dd>Draws a repeating dot pattern, simulating the "Ben Day process" used in early comic books.</dd>
+
+  <dt>Magic API Updates</dt>
+  <dd>Sound pause and resume functions added.</dt>
 </dl>
 
     <p>

docs/fr_FR.UTF-8/MAGIC-API.txt

@@ -6,7 +6,7 @@
         Copyright © 2007-2024 by various contributors; see AUTHORS.txt.
                              https://tuxpaint.org/
 
-                                 juin 1, 2024
+                              septembre 17, 2024
 
 +--------------------------------------------------+
 |                Table of Contents                 |
@@ -22,6 +22,7 @@
 |           o Pixel Manipulations                  |
 |           o Helper Functions                     |
 |           o Informational                        |
+|           o Sound Functions                      |
 |           o Tux Paint System Calls               |
 |           o Color Conversions                    |
 |       + Helper Macros in "tp_magic_api.h"        |
@@ -640,12 +641,7 @@ char * data_directory
 
 
 
-Tux Paint System Calls
+Sound Functions
-
-void update_progress_bar(void)
-    Asks Tux Paint to animate and draw one frame of its progress bar (at the
-    bottom of the screen). Useful for routines that may take a long time, to
-    provide feedback to the user that Tux Paint has not crashed or frozen.
 
 void playsound(Mix_Chunk * snd, int pan, int dist)
 
@@ -670,6 +666,46 @@ void stopsound(void)
     silence effects when the user stops using the tool (in your 'release'
     function).
 
+int playingsound(void)
+
+    Call this function to determine whether a magic tool sound effect is still
+    currently playing. Can be used by magic tools that pause and unpause their
+    sounds (see below) to determine whether it's time to start a new sound —
+    call playsound() instead of unpausesound(). A '1' is returned if a sound is
+    playing; '0' otherwise.
+
+    Note: Added to Tux Paint 0.9.34; Magic API version 0x0000000B.
+
+
+
+void pausesound(void)
+
+    Pauses the magic tool sound effect; it may be unpaused to resume playing.
+    Useful when a magic tool sound is very long; avoid repeatedly playing just
+    a short clip of the beginning when the user draws small strokes by starting
+    (playsound()) and stopping (stopsound()) the sound. Use playingsound() to
+    determine whether you can unpause or must play from the start.
+
+    Note: Added to Tux Paint 0.9.34; Magic API version 0x0000000B.
+
+
+
+void unpausesound(void)
+
+    Resumes a paused magic tool sound effect, if one was playing.
+
+    Note: Added to Tux Paint 0.9.34; Magic API version 0x0000000B.
+
+
+
+
+Tux Paint System Calls
+
+void update_progress_bar(void)
+    Asks Tux Paint to animate and draw one frame of its progress bar (at the
+    bottom of the screen). Useful for routines that may take a long time, to
+    provide feedback to the user that Tux Paint has not crashed or frozen.
+
 void special_notify(int flag)
     This function notifies Tux Paint of special events. Various values defined
     in "tp_magic_api.h" can be 'or'ed together (using C's boolean 'or': "|")

docs/fr_FR.UTF-8/README.txt

@@ -6,7 +6,7 @@
        Copyright © 2002-2024 by divers contributeurs; voir AUTHORS.txt.
                              https://tuxpaint.org/
 
-                              septembre 16, 2024
+                              septembre 17, 2024
 
 +-------------------------------------------------------+
 |                  Table des matières                   |
@@ -110,6 +110,12 @@ D. Qu'y a-t-il de neuf dans la version 0.9.34 de Tux Paint ?
 
 New brushes
     New brushes for the Paint and Lines tools: Fluff (gradient).
+New Magic tool: Comic dots
+    Draws a repeating dot pattern, simulating the "Ben Day process" used in
+    early comic books.
+
+Magic API Updates
+    Sound pause and resume functions added.
 
 Voir CHANGES.txt pour la liste complète des changements.
 

docs/fr_FR.UTF-8/html/MAGIC-API.html

@@ -102,7 +102,7 @@
           </p>
 
           <p>
-            juin  1, 2024          </p>
+            septembre 17, 2024          </p>
         </center>
       </header>
 
@@ -128,7 +128,7 @@
                     </ul>
                   </li>
                   <li><a href="#tpfuncs">Tux Paint Functions and Data</a>                    <ul>
-                      <li><a href="#pixel_manip">Pixel Manipulations</a></li>                      <li><a href="#helper_funcs">Helper Functions</a></li>                      <li><a href="#informational">Informational</a></li>                      <li><a href="#syscalls">Tux Paint System Calls</a></li>                      <li><a href="#color_convs">Color Conversions</a></li>                    </ul>
+                      <li><a href="#pixel_manip">Pixel Manipulations</a></li>                      <li><a href="#helper_funcs">Helper Functions</a></li>                      <li><a href="#informational">Informational</a></li>                      <li><a href="#sound">Sound Functions</a></li>                      <li><a href="#syscalls">Tux Paint System Calls</a></li>                      <li><a href="#color_convs">Color Conversions</a></li>                    </ul>
                   </li>
                   <li><a href="#macros">Helper Macros in "tp_magic_api.h"</a></li>                  <li><a href="#consts">Constant Definitions in "tp_magic_api.h"</a></li>                </ul>
               </li>
@@ -636,17 +636,13 @@
           </dl>
         </section><!-- H3: Informational -->
 
-        <section class="indent"><!-- H3: Tux Paint System Calls -->
+        <section class="indent"><!-- H3: Sound Functions -->
           <header>
-            <h3 id="syscalls">
+            <h3 id="sound">
-              Tux Paint System Calls            </h3>
+              Sound Functions            </h3>
           </header>
 
           <dl>
-            <dt><code><b>void update_progress_bar(void)</b></code></dt>
-            <dd>
-              Asks Tux Paint to animate and draw one frame of its progress bar (at the bottom of the screen).  Useful for routines that may take a long time, to provide feedback to the user that Tux Paint has not crashed or frozen.            </dd>
-
             <dt><code><b>void playsound(Mix_Chunk * snd, int pan, int dist)</b></code></dt>
             <dd>
               <p>
@@ -663,6 +659,43 @@
             <dd>
               This function stops playing a sound played by <code>playsound()</code>. It is useful to silence effects when the user stops using the tool (in your '<code>release</code>' function).            </dd>
 
+            <dt><code><b>int playingsound(void)</b></code></dt>
+            <dd>
+              <p>
+                Call this function to determine whether a magic tool sound effect is still currently playing. Can be used by magic tools that pause and unpause their sounds (see below) to determine whether it's time to start a new sound &mdash; call <code>playsound()</code> instead of <code>unpausesound()</code>.                A '1' is returned if a sound is playing; '0' otherwise.              </p>
+              <p>
+                <b>Note:</b> Added to Tux Paint 0.9.34; Magic API version 0x0000000B.              </p>
+            </dd>
+
+            <dt><code><b>void pausesound(void)</b></code></dt>
+            <dd>
+              <p>
+                Pauses the magic tool sound effect; it may be unpaused to resume playing. Useful when a magic tool sound is very long; avoid repeatedly playing just a short clip of the beginning when the user draws small strokes by starting (<code>playsound()</code>) and stopping (<code>stopsound()</code>) the sound. Use <code>playingsound()</code> to determine whether you can unpause or must play from the start.              </p>
+              <p>
+                <b>Note:</b> Added to Tux Paint 0.9.34; Magic API version 0x0000000B.              </p>
+            </dd>
+
+            <dt><code><b>void unpausesound(void)</b></code></dt>
+            <dd>
+              <p>
+                Resumes a paused magic tool sound effect, if one was playing.              </p>
+              <p>
+                <b>Note:</b> Added to Tux Paint 0.9.34; Magic API version 0x0000000B.              </p>
+            </dd>
+          </dl>
+        </section><!-- H3: Sound Functions -->
+
+        <section class="indent"><!-- H3: Tux Paint System Calls -->
+          <header>
+            <h3 id="syscalls">
+              Tux Paint System Calls            </h3>
+          </header>
+
+          <dl>
+            <dt><code><b>void update_progress_bar(void)</b></code></dt>
+            <dd>
+              Asks Tux Paint to animate and draw one frame of its progress bar (at the bottom of the screen).  Useful for routines that may take a long time, to provide feedback to the user that Tux Paint has not crashed or frozen.            </dd>
+
             <dt id="special_notify"><code><b>void special_notify(int flag)</b></code></dt>
             <dd>
               This function notifies Tux Paint of special events.  Various values defined in "<code>tp_magic_api.h</code>" can be 'or'ed together (using C's boolean 'or': "<code>|</code>") and sent to this function.              <dl>

docs/fr_FR.UTF-8/html/README.html

@@ -236,6 +236,9 @@
 
   <dt>New Magic tool: Comic dots</dt>
   <dd>Draws a repeating dot pattern, simulating the "Ben Day process" used in early comic books.</dd>
+
+  <dt>Magic API Updates</dt>
+  <dd>Sound pause and resume functions added.</dt>
 </dl>
 
     <p>

docs/gl_ES.UTF-8/MAGIC-API.txt

@@ -6,7 +6,7 @@
         Copyright © 2007-2024 by various contributors; see AUTHORS.txt.
                              https://tuxpaint.org/
 
-                                 Xuño 1, 2024
+                               Setembro 17, 2024
 
 +--------------------------------------------------+
 |                Table of Contents                 |
@@ -22,6 +22,7 @@
 |           o Pixel Manipulations                  |
 |           o Helper Functions                     |
 |           o Informational                        |
+|           o Sound Functions                      |
 |           o Tux Paint System Calls               |
 |           o Color Conversions                    |
 |       + Helper Macros in "tp_magic_api.h"        |
@@ -640,12 +641,7 @@ char * data_directory
 
 
 
-Tux Paint System Calls
+Sound Functions
-
-void update_progress_bar(void)
-    Asks Tux Paint to animate and draw one frame of its progress bar (at the
-    bottom of the screen). Useful for routines that may take a long time, to
-    provide feedback to the user that Tux Paint has not crashed or frozen.
 
 void playsound(Mix_Chunk * snd, int pan, int dist)
 
@@ -670,6 +666,46 @@ void stopsound(void)
     silence effects when the user stops using the tool (in your 'release'
     function).
 
+int playingsound(void)
+
+    Call this function to determine whether a magic tool sound effect is still
+    currently playing. Can be used by magic tools that pause and unpause their
+    sounds (see below) to determine whether it's time to start a new sound —
+    call playsound() instead of unpausesound(). A '1' is returned if a sound is
+    playing; '0' otherwise.
+
+    Note: Added to Tux Paint 0.9.34; Magic API version 0x0000000B.
+
+
+
+void pausesound(void)
+
+    Pauses the magic tool sound effect; it may be unpaused to resume playing.
+    Useful when a magic tool sound is very long; avoid repeatedly playing just
+    a short clip of the beginning when the user draws small strokes by starting
+    (playsound()) and stopping (stopsound()) the sound. Use playingsound() to
+    determine whether you can unpause or must play from the start.
+
+    Note: Added to Tux Paint 0.9.34; Magic API version 0x0000000B.
+
+
+
+void unpausesound(void)
+
+    Resumes a paused magic tool sound effect, if one was playing.
+
+    Note: Added to Tux Paint 0.9.34; Magic API version 0x0000000B.
+
+
+
+
+Tux Paint System Calls
+
+void update_progress_bar(void)
+    Asks Tux Paint to animate and draw one frame of its progress bar (at the
+    bottom of the screen). Useful for routines that may take a long time, to
+    provide feedback to the user that Tux Paint has not crashed or frozen.
+
 void special_notify(int flag)
     This function notifies Tux Paint of special events. Various values defined
     in "tp_magic_api.h" can be 'or'ed together (using C's boolean 'or': "|")

docs/gl_ES.UTF-8/README.txt

@@ -6,7 +6,7 @@
         Copyright © 2002-2024 by varios colaboradores; see AUTHORS.txt.
                              https://tuxpaint.org/
 
-                            16 de Setembro de 2024
+                            17 de Setembro de 2024
 
 +--------------------------------------------------------+
 |                         Índice                         |
@@ -106,6 +106,12 @@ D. What's New in Tux Paint version 0.9.34?
 
 New brushes
     New brushes for the Paint and Lines tools: Fluff (gradient).
+New Magic tool: Comic dots
+    Draws a repeating dot pattern, simulating the "Ben Day process" used in
+    early comic books.
+
+Magic API Updates
+    Sound pause and resume functions added.
 
 See CHANGES.txt for the complete list of changes.
 

docs/gl_ES.UTF-8/html/MAGIC-API.html

@@ -102,7 +102,7 @@
           </p>
 
           <p>
-            Xuño  1, 2024          </p>
+            Setembro 17, 2024          </p>
         </center>
       </header>
 
@@ -128,7 +128,7 @@
                     </ul>
                   </li>
                   <li><a href="#tpfuncs">Tux Paint Functions and Data</a>                    <ul>
-                      <li><a href="#pixel_manip">Pixel Manipulations</a></li>                      <li><a href="#helper_funcs">Helper Functions</a></li>                      <li><a href="#informational">Informational</a></li>                      <li><a href="#syscalls">Tux Paint System Calls</a></li>                      <li><a href="#color_convs">Color Conversions</a></li>                    </ul>
+                      <li><a href="#pixel_manip">Pixel Manipulations</a></li>                      <li><a href="#helper_funcs">Helper Functions</a></li>                      <li><a href="#informational">Informational</a></li>                      <li><a href="#sound">Sound Functions</a></li>                      <li><a href="#syscalls">Tux Paint System Calls</a></li>                      <li><a href="#color_convs">Color Conversions</a></li>                    </ul>
                   </li>
                   <li><a href="#macros">Helper Macros in "tp_magic_api.h"</a></li>                  <li><a href="#consts">Constant Definitions in "tp_magic_api.h"</a></li>                </ul>
               </li>
@@ -636,17 +636,13 @@
           </dl>
         </section><!-- H3: Informational -->
 
-        <section class="indent"><!-- H3: Tux Paint System Calls -->
+        <section class="indent"><!-- H3: Sound Functions -->
           <header>
-            <h3 id="syscalls">
+            <h3 id="sound">
-              Tux Paint System Calls            </h3>
+              Sound Functions            </h3>
           </header>
 
           <dl>
-            <dt><code><b>void update_progress_bar(void)</b></code></dt>
-            <dd>
-              Asks Tux Paint to animate and draw one frame of its progress bar (at the bottom of the screen).  Useful for routines that may take a long time, to provide feedback to the user that Tux Paint has not crashed or frozen.            </dd>
-
             <dt><code><b>void playsound(Mix_Chunk * snd, int pan, int dist)</b></code></dt>
             <dd>
               <p>
@@ -663,6 +659,43 @@
             <dd>
               This function stops playing a sound played by <code>playsound()</code>. It is useful to silence effects when the user stops using the tool (in your '<code>release</code>' function).            </dd>
 
+            <dt><code><b>int playingsound(void)</b></code></dt>
+            <dd>
+              <p>
+                Call this function to determine whether a magic tool sound effect is still currently playing. Can be used by magic tools that pause and unpause their sounds (see below) to determine whether it's time to start a new sound &mdash; call <code>playsound()</code> instead of <code>unpausesound()</code>.                A '1' is returned if a sound is playing; '0' otherwise.              </p>
+              <p>
+                <b>Note:</b> Added to Tux Paint 0.9.34; Magic API version 0x0000000B.              </p>
+            </dd>
+
+            <dt><code><b>void pausesound(void)</b></code></dt>
+            <dd>
+              <p>
+                Pauses the magic tool sound effect; it may be unpaused to resume playing. Useful when a magic tool sound is very long; avoid repeatedly playing just a short clip of the beginning when the user draws small strokes by starting (<code>playsound()</code>) and stopping (<code>stopsound()</code>) the sound. Use <code>playingsound()</code> to determine whether you can unpause or must play from the start.              </p>
+              <p>
+                <b>Note:</b> Added to Tux Paint 0.9.34; Magic API version 0x0000000B.              </p>
+            </dd>
+
+            <dt><code><b>void unpausesound(void)</b></code></dt>
+            <dd>
+              <p>
+                Resumes a paused magic tool sound effect, if one was playing.              </p>
+              <p>
+                <b>Note:</b> Added to Tux Paint 0.9.34; Magic API version 0x0000000B.              </p>
+            </dd>
+          </dl>
+        </section><!-- H3: Sound Functions -->
+
+        <section class="indent"><!-- H3: Tux Paint System Calls -->
+          <header>
+            <h3 id="syscalls">
+              Tux Paint System Calls            </h3>
+          </header>
+
+          <dl>
+            <dt><code><b>void update_progress_bar(void)</b></code></dt>
+            <dd>
+              Asks Tux Paint to animate and draw one frame of its progress bar (at the bottom of the screen).  Useful for routines that may take a long time, to provide feedback to the user that Tux Paint has not crashed or frozen.            </dd>
+
             <dt id="special_notify"><code><b>void special_notify(int flag)</b></code></dt>
             <dd>
               This function notifies Tux Paint of special events.  Various values defined in "<code>tp_magic_api.h</code>" can be 'or'ed together (using C's boolean 'or': "<code>|</code>") and sent to this function.              <dl>

docs/gl_ES.UTF-8/html/README.html

@@ -236,6 +236,9 @@
 
   <dt>New Magic tool: Comic dots</dt>
   <dd>Draws a repeating dot pattern, simulating the "Ben Day process" used in early comic books.</dd>
+
+  <dt>Magic API Updates</dt>
+  <dd>Sound pause and resume functions added.</dt>
 </dl>
 
     <p>

docs/is_IS.UTF-8/MAGIC-API.txt

@@ -6,7 +6,7 @@
    Höfundarréttur © 2007-2024 eftir various contributors; sjá AUTHORS-skrá.
                              https://tuxpaint.org/
 
-                                 1. júní 2024
+                              17. september 2024
 
 +--------------------------------------------------+
 |                   Efnisyfirlit                   |
@@ -22,6 +22,7 @@
 |           o Pixel Manipulations                  |
 |           o Helper Functions                     |
 |           o Til upplýsingar                      |
+|           o Sound Functions                      |
 |           o Tux Paint System Calls               |
 |           o Color Conversions                    |
 |       + Helper Macros in "tp_magic_api.h"        |
@@ -640,12 +641,7 @@ char * data_directory
 
 
 
-Tux Paint System Calls
+Sound Functions
-
-void update_progress_bar(void)
-    Asks Tux Paint to animate and draw one frame of its progress bar (at the
-    bottom of the screen). Useful for routines that may take a long time, to
-    provide feedback to the user that Tux Paint has not crashed or frozen.
 
 void playsound(Mix_Chunk * snd, int pan, int dist)
 
@@ -670,6 +666,46 @@ void stopsound(void)
     silence effects when the user stops using the tool (in your 'release'
     function).
 
+int playingsound(void)
+
+    Call this function to determine whether a magic tool sound effect is still
+    currently playing. Can be used by magic tools that pause and unpause their
+    sounds (see below) to determine whether it's time to start a new sound —
+    call playsound() instead of unpausesound(). A '1' is returned if a sound is
+    playing; '0' otherwise.
+
+    Note: Added to Tux Paint 0.9.34; Magic API version 0x0000000B.
+
+
+
+void pausesound(void)
+
+    Pauses the magic tool sound effect; it may be unpaused to resume playing.
+    Useful when a magic tool sound is very long; avoid repeatedly playing just
+    a short clip of the beginning when the user draws small strokes by starting
+    (playsound()) and stopping (stopsound()) the sound. Use playingsound() to
+    determine whether you can unpause or must play from the start.
+
+    Note: Added to Tux Paint 0.9.34; Magic API version 0x0000000B.
+
+
+
+void unpausesound(void)
+
+    Resumes a paused magic tool sound effect, if one was playing.
+
+    Note: Added to Tux Paint 0.9.34; Magic API version 0x0000000B.
+
+
+
+
+Tux Paint System Calls
+
+void update_progress_bar(void)
+    Asks Tux Paint to animate and draw one frame of its progress bar (at the
+    bottom of the screen). Useful for routines that may take a long time, to
+    provide feedback to the user that Tux Paint has not crashed or frozen.
+
 void special_notify(int flag)
     This function notifies Tux Paint of special events. Various values defined
     in "tp_magic_api.h" can be 'or'ed together (using C's boolean 'or': "|")

docs/is_IS.UTF-8/README.txt

@@ -6,7 +6,7 @@
         Copyright © 2002-2024 by various contributors; see AUTHORS.txt.
                              https://tuxpaint.org/
 
-                              september 16, 2024
+                              september 17, 2024
 
 +-------------------------------------------------+
 |                Table of Contents                |
@@ -105,6 +105,12 @@ D. What's New in Tux Paint version 0.9.34?
 
 New brushes
     New brushes for the Paint and Lines tools: Fluff (gradient).
+New Magic tool: Comic dots
+    Draws a repeating dot pattern, simulating the "Ben Day process" used in
+    early comic books.
+
+Magic API Updates
+    Sound pause and resume functions added.
 
 See CHANGES.txt for the complete list of changes.
 

docs/is_IS.UTF-8/html/MAGIC-API.html

@@ -102,7 +102,7 @@
           </p>
 
           <p>
-             1. júní 2024          </p>
+            17. september 2024          </p>
         </center>
       </header>
 
@@ -128,7 +128,7 @@
                     </ul>
                   </li>
                   <li><a href="#tpfuncs">Tux Paint Functions and Data</a>                    <ul>
-                      <li><a href="#pixel_manip">Pixel Manipulations</a></li>                      <li><a href="#helper_funcs">Helper Functions</a></li>                      <li><a href="#informational">Til upplýsingar</a></li>                      <li><a href="#syscalls">Tux Paint System Calls</a></li>                      <li><a href="#color_convs">Color Conversions</a></li>                    </ul>
+                      <li><a href="#pixel_manip">Pixel Manipulations</a></li>                      <li><a href="#helper_funcs">Helper Functions</a></li>                      <li><a href="#informational">Til upplýsingar</a></li>                      <li><a href="#sound">Sound Functions</a></li>                      <li><a href="#syscalls">Tux Paint System Calls</a></li>                      <li><a href="#color_convs">Color Conversions</a></li>                    </ul>
                   </li>
                   <li><a href="#macros">Helper Macros in "tp_magic_api.h"</a></li>                  <li><a href="#consts">Constant Definitions in "tp_magic_api.h"</a></li>                </ul>
               </li>
@@ -636,17 +636,13 @@
           </dl>
         </section><!-- H3: Informational -->
 
-        <section class="indent"><!-- H3: Tux Paint System Calls -->
+        <section class="indent"><!-- H3: Sound Functions -->
           <header>
-            <h3 id="syscalls">
+            <h3 id="sound">
-              Tux Paint System Calls            </h3>
+              Sound Functions            </h3>
           </header>
 
           <dl>
-            <dt><code><b>void update_progress_bar(void)</b></code></dt>
-            <dd>
-              Asks Tux Paint to animate and draw one frame of its progress bar (at the bottom of the screen).  Useful for routines that may take a long time, to provide feedback to the user that Tux Paint has not crashed or frozen.            </dd>
-
             <dt><code><b>void playsound(Mix_Chunk * snd, int pan, int dist)</b></code></dt>
             <dd>
               <p>
@@ -663,6 +659,43 @@
             <dd>
               This function stops playing a sound played by <code>playsound()</code>. It is useful to silence effects when the user stops using the tool (in your '<code>release</code>' function).            </dd>
 
+            <dt><code><b>int playingsound(void)</b></code></dt>
+            <dd>
+              <p>
+                Call this function to determine whether a magic tool sound effect is still currently playing. Can be used by magic tools that pause and unpause their sounds (see below) to determine whether it's time to start a new sound &mdash; call <code>playsound()</code> instead of <code>unpausesound()</code>.                A '1' is returned if a sound is playing; '0' otherwise.              </p>
+              <p>
+                <b>Note:</b> Added to Tux Paint 0.9.34; Magic API version 0x0000000B.              </p>
+            </dd>
+
+            <dt><code><b>void pausesound(void)</b></code></dt>
+            <dd>
+              <p>
+                Pauses the magic tool sound effect; it may be unpaused to resume playing. Useful when a magic tool sound is very long; avoid repeatedly playing just a short clip of the beginning when the user draws small strokes by starting (<code>playsound()</code>) and stopping (<code>stopsound()</code>) the sound. Use <code>playingsound()</code> to determine whether you can unpause or must play from the start.              </p>
+              <p>
+                <b>Note:</b> Added to Tux Paint 0.9.34; Magic API version 0x0000000B.              </p>
+            </dd>
+
+            <dt><code><b>void unpausesound(void)</b></code></dt>
+            <dd>
+              <p>
+                Resumes a paused magic tool sound effect, if one was playing.              </p>
+              <p>
+                <b>Note:</b> Added to Tux Paint 0.9.34; Magic API version 0x0000000B.              </p>
+            </dd>
+          </dl>
+        </section><!-- H3: Sound Functions -->
+
+        <section class="indent"><!-- H3: Tux Paint System Calls -->
+          <header>
+            <h3 id="syscalls">
+              Tux Paint System Calls            </h3>
+          </header>
+
+          <dl>
+            <dt><code><b>void update_progress_bar(void)</b></code></dt>
+            <dd>
+              Asks Tux Paint to animate and draw one frame of its progress bar (at the bottom of the screen).  Useful for routines that may take a long time, to provide feedback to the user that Tux Paint has not crashed or frozen.            </dd>
+
             <dt id="special_notify"><code><b>void special_notify(int flag)</b></code></dt>
             <dd>
               This function notifies Tux Paint of special events.  Various values defined in "<code>tp_magic_api.h</code>" can be 'or'ed together (using C's boolean 'or': "<code>|</code>") and sent to this function.              <dl>

docs/is_IS.UTF-8/html/README.html

@@ -236,6 +236,9 @@
 
   <dt>New Magic tool: Comic dots</dt>
   <dd>Draws a repeating dot pattern, simulating the "Ben Day process" used in early comic books.</dd>
+
+  <dt>Magic API Updates</dt>
+  <dd>Sound pause and resume functions added.</dt>
 </dl>
 
     <p>

docs/ja_JP.UTF-8/MAGIC-API.txt

@@ -6,7 +6,7 @@
         Copyright © 2007-2024 by various contributors; see AUTHORS.txt.
                              https://tuxpaint.org/
 
-                                  6月 1, 2024
+                                 9月 17, 2024
 
 +--------------------------------------------------+
 |                Table of Contents                 |
@@ -22,6 +22,7 @@
 |           o Pixel Manipulations                  |
 |           o Helper Functions                     |
 |           o Informational                        |
+|           o Sound Functions                      |
 |           o Tux Paint System Calls               |
 |           o Color Conversions                    |
 |       + Helper Macros in "tp_magic_api.h"        |
@@ -640,12 +641,7 @@ char * data_directory
 
 
 
-Tux Paint System Calls
+Sound Functions
-
-void update_progress_bar(void)
-    Asks Tux Paint to animate and draw one frame of its progress bar (at the
-    bottom of the screen). Useful for routines that may take a long time, to
-    provide feedback to the user that Tux Paint has not crashed or frozen.
 
 void playsound(Mix_Chunk * snd, int pan, int dist)
 
@@ -670,6 +666,46 @@ void stopsound(void)
     silence effects when the user stops using the tool (in your 'release'
     function).
 
+int playingsound(void)
+
+    Call this function to determine whether a magic tool sound effect is still
+    currently playing. Can be used by magic tools that pause and unpause their
+    sounds (see below) to determine whether it's time to start a new sound —
+    call playsound() instead of unpausesound(). A '1' is returned if a sound is
+    playing; '0' otherwise.
+
+    Note: Added to Tux Paint 0.9.34; Magic API version 0x0000000B.
+
+
+
+void pausesound(void)
+
+    Pauses the magic tool sound effect; it may be unpaused to resume playing.
+    Useful when a magic tool sound is very long; avoid repeatedly playing just
+    a short clip of the beginning when the user draws small strokes by starting
+    (playsound()) and stopping (stopsound()) the sound. Use playingsound() to
+    determine whether you can unpause or must play from the start.
+
+    Note: Added to Tux Paint 0.9.34; Magic API version 0x0000000B.
+
+
+
+void unpausesound(void)
+
+    Resumes a paused magic tool sound effect, if one was playing.
+
+    Note: Added to Tux Paint 0.9.34; Magic API version 0x0000000B.
+
+
+
+
+Tux Paint System Calls
+
+void update_progress_bar(void)
+    Asks Tux Paint to animate and draw one frame of its progress bar (at the
+    bottom of the screen). Useful for routines that may take a long time, to
+    provide feedback to the user that Tux Paint has not crashed or frozen.
+
 void special_notify(int flag)
     This function notifies Tux Paint of special events. Various values defined
     in "tp_magic_api.h" can be 'or'ed together (using C's boolean 'or': "|")

docs/ja_JP.UTF-8/README.txt

@@ -6,7 +6,7 @@
        Copyright © 2002-2024 by various contributors; AUTHORS.txt 参照.
                              https://tuxpaint.org/
 
-                                 2024年9月16日
+                                 2024年9月17日
 
 +--------------------------------------------------+
 |                       目次                       |
@@ -103,6 +103,12 @@ D. Tux Paint バージョン 0.9.34 での変更点
 
 ブラシの追加
     New brushes for the Paint and Lines tools: Fluff (gradient).
+New Magic tool: Comic dots
+    Draws a repeating dot pattern, simulating the "Ben Day process" used in
+    early comic books.
+
+Magic API Updates
+    Sound pause and resume functions added.
 
 全ての変更点については、CHANGES.txt をお読みください。
 

docs/ja_JP.UTF-8/html/MAGIC-API.html

@@ -102,7 +102,7 @@
           </p>
 
           <p>
-            6月  1, 2024          </p>
+            9月 17, 2024          </p>
         </center>
       </header>
 
@@ -128,7 +128,7 @@
                     </ul>
                   </li>
                   <li><a href="#tpfuncs">Tux Paint Functions and Data</a>                    <ul>
-                      <li><a href="#pixel_manip">Pixel Manipulations</a></li>                      <li><a href="#helper_funcs">Helper Functions</a></li>                      <li><a href="#informational">Informational</a></li>                      <li><a href="#syscalls">Tux Paint System Calls</a></li>                      <li><a href="#color_convs">Color Conversions</a></li>                    </ul>
+                      <li><a href="#pixel_manip">Pixel Manipulations</a></li>                      <li><a href="#helper_funcs">Helper Functions</a></li>                      <li><a href="#informational">Informational</a></li>                      <li><a href="#sound">Sound Functions</a></li>                      <li><a href="#syscalls">Tux Paint System Calls</a></li>                      <li><a href="#color_convs">Color Conversions</a></li>                    </ul>
                   </li>
                   <li><a href="#macros">Helper Macros in "tp_magic_api.h"</a></li>                  <li><a href="#consts">Constant Definitions in "tp_magic_api.h"</a></li>                </ul>
               </li>
@@ -636,17 +636,13 @@
           </dl>
         </section><!-- H3: Informational -->
 
-        <section class="indent"><!-- H3: Tux Paint System Calls -->
+        <section class="indent"><!-- H3: Sound Functions -->
           <header>
-            <h3 id="syscalls">
+            <h3 id="sound">
-              Tux Paint System Calls            </h3>
+              Sound Functions            </h3>
           </header>
 
           <dl>
-            <dt><code><b>void update_progress_bar(void)</b></code></dt>
-            <dd>
-              Asks Tux Paint to animate and draw one frame of its progress bar (at the bottom of the screen).  Useful for routines that may take a long time, to provide feedback to the user that Tux Paint has not crashed or frozen.            </dd>
-
             <dt><code><b>void playsound(Mix_Chunk * snd, int pan, int dist)</b></code></dt>
             <dd>
               <p>
@@ -663,6 +659,43 @@
             <dd>
               This function stops playing a sound played by <code>playsound()</code>. It is useful to silence effects when the user stops using the tool (in your '<code>release</code>' function).            </dd>
 
+            <dt><code><b>int playingsound(void)</b></code></dt>
+            <dd>
+              <p>
+                Call this function to determine whether a magic tool sound effect is still currently playing. Can be used by magic tools that pause and unpause their sounds (see below) to determine whether it's time to start a new sound &mdash; call <code>playsound()</code> instead of <code>unpausesound()</code>.                A '1' is returned if a sound is playing; '0' otherwise.              </p>
+              <p>
+                <b>Note:</b> Added to Tux Paint 0.9.34; Magic API version 0x0000000B.              </p>
+            </dd>
+
+            <dt><code><b>void pausesound(void)</b></code></dt>
+            <dd>
+              <p>
+                Pauses the magic tool sound effect; it may be unpaused to resume playing. Useful when a magic tool sound is very long; avoid repeatedly playing just a short clip of the beginning when the user draws small strokes by starting (<code>playsound()</code>) and stopping (<code>stopsound()</code>) the sound. Use <code>playingsound()</code> to determine whether you can unpause or must play from the start.              </p>
+              <p>
+                <b>Note:</b> Added to Tux Paint 0.9.34; Magic API version 0x0000000B.              </p>
+            </dd>
+
+            <dt><code><b>void unpausesound(void)</b></code></dt>
+            <dd>
+              <p>
+                Resumes a paused magic tool sound effect, if one was playing.              </p>
+              <p>
+                <b>Note:</b> Added to Tux Paint 0.9.34; Magic API version 0x0000000B.              </p>
+            </dd>
+          </dl>
+        </section><!-- H3: Sound Functions -->
+
+        <section class="indent"><!-- H3: Tux Paint System Calls -->
+          <header>
+            <h3 id="syscalls">
+              Tux Paint System Calls            </h3>
+          </header>
+
+          <dl>
+            <dt><code><b>void update_progress_bar(void)</b></code></dt>
+            <dd>
+              Asks Tux Paint to animate and draw one frame of its progress bar (at the bottom of the screen).  Useful for routines that may take a long time, to provide feedback to the user that Tux Paint has not crashed or frozen.            </dd>
+
             <dt id="special_notify"><code><b>void special_notify(int flag)</b></code></dt>
             <dd>
               This function notifies Tux Paint of special events.  Various values defined in "<code>tp_magic_api.h</code>" can be 'or'ed together (using C's boolean 'or': "<code>|</code>") and sent to this function.              <dl>

docs/ja_JP.UTF-8/html/README.html

@@ -236,6 +236,9 @@
 
   <dt>New Magic tool: Comic dots</dt>
   <dd>Draws a repeating dot pattern, simulating the "Ben Day process" used in early comic books.</dd>
+
+  <dt>Magic API Updates</dt>
+  <dd>Sound pause and resume functions added.</dt>
 </dl>
 
     <p>

docs/sq_AL.UTF-8/MAGIC-API.txt

@@ -6,7 +6,7 @@
         Copyright © 2007-2024 by various contributors; see AUTHORS.txt.
                              https://tuxpaint.org/
 
-                                qershor 1, 2024
+                               shtator 17, 2024
 
 +--------------------------------------------------+
 |                Table of Contents                 |
@@ -22,6 +22,7 @@
 |           o Pixel Manipulations                  |
 |           o Helper Functions                     |
 |           o Informational                        |
+|           o Sound Functions                      |
 |           o Tux Paint System Calls               |
 |           o Color Conversions                    |
 |       + Helper Macros in "tp_magic_api.h"        |
@@ -640,12 +641,7 @@ char * data_directory
 
 
 
-Tux Paint System Calls
+Sound Functions
-
-void update_progress_bar(void)
-    Asks Tux Paint to animate and draw one frame of its progress bar (at the
-    bottom of the screen). Useful for routines that may take a long time, to
-    provide feedback to the user that Tux Paint has not crashed or frozen.
 
 void playsound(Mix_Chunk * snd, int pan, int dist)
 
@@ -670,6 +666,46 @@ void stopsound(void)
     silence effects when the user stops using the tool (in your 'release'
     function).
 
+int playingsound(void)
+
+    Call this function to determine whether a magic tool sound effect is still
+    currently playing. Can be used by magic tools that pause and unpause their
+    sounds (see below) to determine whether it's time to start a new sound —
+    call playsound() instead of unpausesound(). A '1' is returned if a sound is
+    playing; '0' otherwise.
+
+    Note: Added to Tux Paint 0.9.34; Magic API version 0x0000000B.
+
+
+
+void pausesound(void)
+
+    Pauses the magic tool sound effect; it may be unpaused to resume playing.
+    Useful when a magic tool sound is very long; avoid repeatedly playing just
+    a short clip of the beginning when the user draws small strokes by starting
+    (playsound()) and stopping (stopsound()) the sound. Use playingsound() to
+    determine whether you can unpause or must play from the start.
+
+    Note: Added to Tux Paint 0.9.34; Magic API version 0x0000000B.
+
+
+
+void unpausesound(void)
+
+    Resumes a paused magic tool sound effect, if one was playing.
+
+    Note: Added to Tux Paint 0.9.34; Magic API version 0x0000000B.
+
+
+
+
+Tux Paint System Calls
+
+void update_progress_bar(void)
+    Asks Tux Paint to animate and draw one frame of its progress bar (at the
+    bottom of the screen). Useful for routines that may take a long time, to
+    provide feedback to the user that Tux Paint has not crashed or frozen.
+
 void special_notify(int flag)
     This function notifies Tux Paint of special events. Various values defined
     in "tp_magic_api.h" can be 'or'ed together (using C's boolean 'or': "|")

docs/sq_AL.UTF-8/README.txt

@@ -6,7 +6,7 @@
  Të drejta kopjimi © 2002-2024 nga kontribues të ndryshëm; shihni AUTHORS.txt.
                              https://tuxpaint.org/
 
-                                16 shtator 2024
+                                17 shtator 2024
 
 +---------------------------------------------------+
 |                 Pasqyrë e Lëndës                  |
@@ -105,6 +105,12 @@ D. What's New in Tux Paint version 0.9.34?
 
 New brushes
     New brushes for the Paint and Lines tools: Fluff (gradient).
+New Magic tool: Comic dots
+    Draws a repeating dot pattern, simulating the "Ben Day process" used in
+    early comic books.
+
+Magic API Updates
+    Sound pause and resume functions added.
 
 Për listën e plotë të ndryshimeve, shihni CHANGES.txt.
 

docs/sq_AL.UTF-8/html/MAGIC-API.html

@@ -102,7 +102,7 @@
           </p>
 
           <p>
-            qershor  1, 2024          </p>
+            shtator 17, 2024          </p>
         </center>
       </header>
 
@@ -128,7 +128,7 @@
                     </ul>
                   </li>
                   <li><a href="#tpfuncs">Tux Paint Functions and Data</a>                    <ul>
-                      <li><a href="#pixel_manip">Pixel Manipulations</a></li>                      <li><a href="#helper_funcs">Helper Functions</a></li>                      <li><a href="#informational">Informational</a></li>                      <li><a href="#syscalls">Tux Paint System Calls</a></li>                      <li><a href="#color_convs">Color Conversions</a></li>                    </ul>
+                      <li><a href="#pixel_manip">Pixel Manipulations</a></li>                      <li><a href="#helper_funcs">Helper Functions</a></li>                      <li><a href="#informational">Informational</a></li>                      <li><a href="#sound">Sound Functions</a></li>                      <li><a href="#syscalls">Tux Paint System Calls</a></li>                      <li><a href="#color_convs">Color Conversions</a></li>                    </ul>
                   </li>
                   <li><a href="#macros">Helper Macros in "tp_magic_api.h"</a></li>                  <li><a href="#consts">Constant Definitions in "tp_magic_api.h"</a></li>                </ul>
               </li>
@@ -636,17 +636,13 @@
           </dl>
         </section><!-- H3: Informational -->
 
-        <section class="indent"><!-- H3: Tux Paint System Calls -->
+        <section class="indent"><!-- H3: Sound Functions -->
           <header>
-            <h3 id="syscalls">
+            <h3 id="sound">
-              Tux Paint System Calls            </h3>
+              Sound Functions            </h3>
           </header>
 
           <dl>
-            <dt><code><b>void update_progress_bar(void)</b></code></dt>
-            <dd>
-              Asks Tux Paint to animate and draw one frame of its progress bar (at the bottom of the screen).  Useful for routines that may take a long time, to provide feedback to the user that Tux Paint has not crashed or frozen.            </dd>
-
             <dt><code><b>void playsound(Mix_Chunk * snd, int pan, int dist)</b></code></dt>
             <dd>
               <p>
@@ -663,6 +659,43 @@
             <dd>
               This function stops playing a sound played by <code>playsound()</code>. It is useful to silence effects when the user stops using the tool (in your '<code>release</code>' function).            </dd>
 
+            <dt><code><b>int playingsound(void)</b></code></dt>
+            <dd>
+              <p>
+                Call this function to determine whether a magic tool sound effect is still currently playing. Can be used by magic tools that pause and unpause their sounds (see below) to determine whether it's time to start a new sound &mdash; call <code>playsound()</code> instead of <code>unpausesound()</code>.                A '1' is returned if a sound is playing; '0' otherwise.              </p>
+              <p>
+                <b>Note:</b> Added to Tux Paint 0.9.34; Magic API version 0x0000000B.              </p>
+            </dd>
+
+            <dt><code><b>void pausesound(void)</b></code></dt>
+            <dd>
+              <p>
+                Pauses the magic tool sound effect; it may be unpaused to resume playing. Useful when a magic tool sound is very long; avoid repeatedly playing just a short clip of the beginning when the user draws small strokes by starting (<code>playsound()</code>) and stopping (<code>stopsound()</code>) the sound. Use <code>playingsound()</code> to determine whether you can unpause or must play from the start.              </p>
+              <p>
+                <b>Note:</b> Added to Tux Paint 0.9.34; Magic API version 0x0000000B.              </p>
+            </dd>
+
+            <dt><code><b>void unpausesound(void)</b></code></dt>
+            <dd>
+              <p>
+                Resumes a paused magic tool sound effect, if one was playing.              </p>
+              <p>
+                <b>Note:</b> Added to Tux Paint 0.9.34; Magic API version 0x0000000B.              </p>
+            </dd>
+          </dl>
+        </section><!-- H3: Sound Functions -->
+
+        <section class="indent"><!-- H3: Tux Paint System Calls -->
+          <header>
+            <h3 id="syscalls">
+              Tux Paint System Calls            </h3>
+          </header>
+
+          <dl>
+            <dt><code><b>void update_progress_bar(void)</b></code></dt>
+            <dd>
+              Asks Tux Paint to animate and draw one frame of its progress bar (at the bottom of the screen).  Useful for routines that may take a long time, to provide feedback to the user that Tux Paint has not crashed or frozen.            </dd>
+
             <dt id="special_notify"><code><b>void special_notify(int flag)</b></code></dt>
             <dd>
               This function notifies Tux Paint of special events.  Various values defined in "<code>tp_magic_api.h</code>" can be 'or'ed together (using C's boolean 'or': "<code>|</code>") and sent to this function.              <dl>

docs/sq_AL.UTF-8/html/README.html

@@ -236,6 +236,9 @@
 
   <dt>New Magic tool: Comic dots</dt>
   <dd>Draws a repeating dot pattern, simulating the "Ben Day process" used in early comic books.</dd>
+
+  <dt>Magic API Updates</dt>
+  <dd>Sound pause and resume functions added.</dt>
 </dl>
 
     <p>

magic/src/comicdot.c

@@ -22,7 +22,7 @@
   Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
   (See COPYING.txt)
 
-  Last updated: September 16, 2024
+  Last updated: September 17, 2024
 */
 
 #include <stdio.h>
@@ -222,7 +222,10 @@ void comicdot_drag(magic_api * api, int which, SDL_Surface * canvas,
   update_rect->w = (x + comicdot_radius) - update_rect->x;
   update_rect->h = (y + comicdot_radius) - update_rect->y;
 
-  api->playsound(comicdot_snd, 64 + ((x * 127) / canvas->w), 255);
+  if (api->playingsound())
+    api->unpausesound();
+  else
+    api->playsound(comicdot_snd, 64 + ((x * 127) / canvas->w), 255);
 }
 
 void comicdot_click(magic_api * api, int which, int mode,
@@ -251,18 +254,15 @@ void comicdot_release(magic_api * api ATTRIBUTE_UNUSED, int which ATTRIBUTE_UNUS
                  SDL_Surface * last ATTRIBUTE_UNUSED, int x ATTRIBUTE_UNUSED,
                  int y ATTRIBUTE_UNUSED, SDL_Rect * update_rect ATTRIBUTE_UNUSED)
 {
-  /* FIXME: Would be nice to be able to ask Tux Paint to pause
+  api->pausesound();
-     the sound (`Mix_Pause()`), and then resume (`Mix_Resume()`)
-     (or start new (`Mix_PlayChannel()`) if nothing is currently playing)
-     on click/drag.  That way the sound won't start over every time
-     you make small stroke. */
-  api->stopsound();
 }
 
 void comicdot_shutdown(magic_api * api ATTRIBUTE_UNUSED)
 {
   int i;
 
+  api->stopsound();
+
   if (comicdot_snd != NULL)
     Mix_FreeChunk(comicdot_snd);
 
@@ -298,6 +298,7 @@ void comicdot_switchin(magic_api * api ATTRIBUTE_UNUSED,
 void comicdot_switchout(magic_api * api ATTRIBUTE_UNUSED,
                    int which ATTRIBUTE_UNUSED, int mode ATTRIBUTE_UNUSED, SDL_Surface * canvas ATTRIBUTE_UNUSED)
 {
+  api->stopsound();
 }
 
 int comicdot_modes(magic_api * api ATTRIBUTE_UNUSED, int which ATTRIBUTE_UNUSED)

src/tp_magic_api.h.in

@@ -127,6 +127,16 @@ typedef struct magic_api_t {
      loudest) */
   void (*playsound)(Mix_Chunk *, int, int);
 
+  /* Asks Tux Paint whether a sound is currently being played (by 'playsound()') */
+  int (*playingsound)(void);
+
+  /* Asks Tux Paint to pause the sound being played by 'playsound()' */
+  void (*pausesound)(void);
+
+  /* Asks Tux Paint to resume (unpause) the sound being played by
+     'playsound()' (if any) */
+  void (*unpausesound)(void);
+
   /* Asks Tux Paint to stop playing the sound played by 'playsound()' */
   void (*stopsound)(void);
 

src/tuxpaint.c

@@ -2295,6 +2295,9 @@ static int magic_sort(const void *a, const void *b);
 
 Mix_Chunk *magic_current_snd_ptr;
 static void magic_playsound(Mix_Chunk * snd, int left_right, int up_down);
+static int magic_playingsound(void);
+static void magic_pausesound(void);
+static void magic_unpausesound(void);
 static void magic_stopsound(void);
 static void magic_line_func(void *mapi,
                             int which, SDL_Surface * canvas,
@@ -21729,6 +21732,9 @@ static void load_magic_plugins(void)
       magic_api_struct->xorpixel = magic_xorpixel;
       magic_api_struct->line = magic_line_func;
       magic_api_struct->playsound = magic_playsound;
+      magic_api_struct->playingsound = magic_playingsound;
+      magic_api_struct->pausesound = magic_pausesound;
+      magic_api_struct->unpausesound = magic_unpausesound;
       magic_api_struct->stopsound = magic_stopsound;
       magic_api_struct->special_notify = special_notify;
       magic_api_struct->button_down = magic_button_down;
@@ -22403,6 +22409,29 @@ static void magic_playsound(Mix_Chunk * snd, int left_right, int up_down)
 #endif
 }
 
+static int magic_playingsound(void)
+{
+#ifndef NOSOUND
+  int is_playing;
+  is_playing = Mix_Playing(0);
+  return is_playing;
+#endif
+}
+
+static void magic_pausesound(void)
+{
+#ifndef NOSOUND
+  return Mix_Pause(0);
+#endif
+}
+
+static void magic_unpausesound(void)
+{
+#ifndef NOSOUND
+  return Mix_Resume(0);
+#endif
+}
+
 /**
  * FIXME
  */