WIP New _get_order() function in API

So far just CHANGES.txt update and sync'ing update tp_magic_example.c
in the docs.

docs/CHANGES.txt

@@ -9,14 +9,18 @@ https://tuxpaint.org/
 2024.January.16 (0.9.32)
   * Improvements to Magic tools:
     ----------------------------
-    * Support for complexity levels in Magic tools via the plugin API.
+    * Magic tool plugin API updates
-      (Closes https://sourceforge.net/p/tuxpaint/feature-requests/247/)
+      + Support for complexity levels in Magic tools via the plugin API.
-      + Complexity/expertise level may be set via configuration,
+        (Closes https://sourceforge.net/p/tuxpaint/feature-requests/247/)
-        `--complexity`; values may be "advanced" (default), "beginner",
+        - Complexity/expertise level may be set via configuration,
-        or "novice".
+          `--complexity`; values may be "advanced" (default), "beginner",
-      + Plugins' "init()" functions are sent a new `complexity_level`
+          or "novice".
-        argument.
+        - Plugins' "init()" functions are sent a new `complexity_level`
-      + Note: Bumps `TP_MAGIC_API_VERSION` to 0x00000009.
+          argument.
+      + WIP Magic tools can provide a value that allows them to be
+        sorted and grouped together (rather than always relying on the
+        localized name of the tool).
+      + Note: `TP_MAGIC_API_VERSION` bumped to 0x00000009.
       Bill Kendrick <bill@newbreedsoftware.com>
 
     * "Clone" tool does not operate when Tux Paint is in "novice"

docs/en/html/tp_magic_example.c

@@ -1,7 +1,7 @@
 /* tp_magic_example.c
 
    An example of a "Magic" tool plugin for Tux Paint
-   January 15, 2024
+   January 16, 2024
 */
 
 
@@ -192,7 +192,8 @@ int example_get_tool_count(magic_api * api)
 /*
 Load our icons
 
-When Tux Paint is starting up and loading plugins, it asks us to provide icons for the 'Magic' tool buttons.
+When Tux Paint is starting up and loading plugins, it asks us to provide
+icons for the 'Magic' tool buttons.
 */
 SDL_Surface *example_get_icon(magic_api * api, int which)
 {
@@ -275,6 +276,20 @@ int example_get_group(magic_api * api, int which)
 }
 
 
+/*
+Return grouping/ordering number
+
+When Tux Paint is starting up and loading plugins, it asks us to provide a
+numeric value used for sorting 'Magic' tools within a group.  Tools will be
+ordered based on this number, and those with the same number will be sorted
+alphabetically by their localized name (see 'example_get_name').
+*/
+int *example_get_order(int which)
+{
+  return 0;
+}
+
+
 /*
 Report our 'Magic' tool descriptions
 

docs/en/tp_magic_example.c

@@ -1,7 +1,7 @@
 /* tp_magic_example.c
 
    An example of a "Magic" tool plugin for Tux Paint
-   January 15, 2024
+   January 16, 2024
 */
 
 
@@ -192,7 +192,8 @@ int example_get_tool_count(magic_api * api)
 /*
 Load our icons
 
-When Tux Paint is starting up and loading plugins, it asks us to provide icons for the 'Magic' tool buttons.
+When Tux Paint is starting up and loading plugins, it asks us to provide
+icons for the 'Magic' tool buttons.
 */
 SDL_Surface *example_get_icon(magic_api * api, int which)
 {
@@ -275,6 +276,20 @@ int example_get_group(magic_api * api, int which)
 }
 
 
+/*
+Return grouping/ordering number
+
+When Tux Paint is starting up and loading plugins, it asks us to provide a
+numeric value used for sorting 'Magic' tools within a group.  Tools will be
+ordered based on this number, and those with the same number will be sorted
+alphabetically by their localized name (see 'example_get_name').
+*/
+int *example_get_order(int which)
+{
+  return 0;
+}
+
+
 /*
 Report our 'Magic' tool descriptions
 

docs/es_ES.UTF-8/html/tp_magic_example.c

@@ -1,7 +1,7 @@
 /* tp_magic_example.c
 
    An example of a "Magic" tool plugin for Tux Paint
-   enero 15, 2024
+   enero 16, 2024
 */
 
 
@@ -192,7 +192,8 @@ int example_get_tool_count(magic_api * api)
 /*
 Load our icons
 
-When Tux Paint is starting up and loading plugins, it asks us to provide icons for the 'Magic' tool buttons.
+When Tux Paint is starting up and loading plugins, it asks us to provide
+icons for the 'Magic' tool buttons.
 */
 SDL_Surface *example_get_icon(magic_api * api, int which)
 {
@@ -275,6 +276,20 @@ int example_get_group(magic_api * api, int which)
 }
 
 
+/*
+Return grouping/ordering number
+
+When Tux Paint is starting up and loading plugins, it asks us to provide a
+numeric value used for sorting 'Magic' tools within a group.  Tools will be
+ordered based on this number, and those with the same number will be sorted
+alphabetically by their localized name (see 'example_get_name').
+*/
+int *example_get_order(int which)
+{
+  return 0;
+}
+
+
 /*
 Report our 'Magic' tool descriptions
 

docs/es_ES.UTF-8/tp_magic_example.c

@@ -1,7 +1,7 @@
 /* tp_magic_example.c
 
    An example of a "Magic" tool plugin for Tux Paint
-   enero 15, 2024
+   enero 16, 2024
 */
 
 
@@ -192,7 +192,8 @@ int example_get_tool_count(magic_api * api)
 /*
 Load our icons
 
-When Tux Paint is starting up and loading plugins, it asks us to provide icons for the 'Magic' tool buttons.
+When Tux Paint is starting up and loading plugins, it asks us to provide
+icons for the 'Magic' tool buttons.
 */
 SDL_Surface *example_get_icon(magic_api * api, int which)
 {
@@ -275,6 +276,20 @@ int example_get_group(magic_api * api, int which)
 }
 
 
+/*
+Return grouping/ordering number
+
+When Tux Paint is starting up and loading plugins, it asks us to provide a
+numeric value used for sorting 'Magic' tools within a group.  Tools will be
+ordered based on this number, and those with the same number will be sorted
+alphabetically by their localized name (see 'example_get_name').
+*/
+int *example_get_order(int which)
+{
+  return 0;
+}
+
+
 /*
 Report our 'Magic' tool descriptions
 

docs/fr_FR.UTF-8/html/tp_magic_example.c

@@ -1,7 +1,7 @@
 /* tp_magic_example.c
 
    An example of a "Magic" tool plugin for Tux Paint
-   janvier 15, 2024
+   janvier 16, 2024
 */
 
 
@@ -192,7 +192,8 @@ int example_get_tool_count(magic_api * api)
 /*
 Load our icons
 
-When Tux Paint is starting up and loading plugins, it asks us to provide icons for the 'Magic' tool buttons.
+When Tux Paint is starting up and loading plugins, it asks us to provide
+icons for the 'Magic' tool buttons.
 */
 SDL_Surface *example_get_icon(magic_api * api, int which)
 {
@@ -275,6 +276,20 @@ int example_get_group(magic_api * api, int which)
 }
 
 
+/*
+Return grouping/ordering number
+
+When Tux Paint is starting up and loading plugins, it asks us to provide a
+numeric value used for sorting 'Magic' tools within a group.  Tools will be
+ordered based on this number, and those with the same number will be sorted
+alphabetically by their localized name (see 'example_get_name').
+*/
+int *example_get_order(int which)
+{
+  return 0;
+}
+
+
 /*
 Report our 'Magic' tool descriptions
 

docs/fr_FR.UTF-8/tp_magic_example.c

@@ -1,7 +1,7 @@
 /* tp_magic_example.c
 
    An example of a "Magic" tool plugin for Tux Paint
-   janvier 15, 2024
+   janvier 16, 2024
 */
 
 
@@ -192,7 +192,8 @@ int example_get_tool_count(magic_api * api)
 /*
 Load our icons
 
-When Tux Paint is starting up and loading plugins, it asks us to provide icons for the 'Magic' tool buttons.
+When Tux Paint is starting up and loading plugins, it asks us to provide
+icons for the 'Magic' tool buttons.
 */
 SDL_Surface *example_get_icon(magic_api * api, int which)
 {
@@ -275,6 +276,20 @@ int example_get_group(magic_api * api, int which)
 }
 
 
+/*
+Return grouping/ordering number
+
+When Tux Paint is starting up and loading plugins, it asks us to provide a
+numeric value used for sorting 'Magic' tools within a group.  Tools will be
+ordered based on this number, and those with the same number will be sorted
+alphabetically by their localized name (see 'example_get_name').
+*/
+int *example_get_order(int which)
+{
+  return 0;
+}
+
+
 /*
 Report our 'Magic' tool descriptions
 

docs/gl_ES.UTF-8/html/tp_magic_example.c

@@ -1,7 +1,7 @@
 /* tp_magic_example.c
 
    An example of a "Magic" tool plugin for Tux Paint
-   Xaneiro 15, 2024
+   Xaneiro 16, 2024
 */
 
 
@@ -192,7 +192,8 @@ int example_get_tool_count(magic_api * api)
 /*
 Load our icons
 
-When Tux Paint is starting up and loading plugins, it asks us to provide icons for the 'Magic' tool buttons.
+When Tux Paint is starting up and loading plugins, it asks us to provide
+icons for the 'Magic' tool buttons.
 */
 SDL_Surface *example_get_icon(magic_api * api, int which)
 {
@@ -275,6 +276,20 @@ int example_get_group(magic_api * api, int which)
 }
 
 
+/*
+Return grouping/ordering number
+
+When Tux Paint is starting up and loading plugins, it asks us to provide a
+numeric value used for sorting 'Magic' tools within a group.  Tools will be
+ordered based on this number, and those with the same number will be sorted
+alphabetically by their localized name (see 'example_get_name').
+*/
+int *example_get_order(int which)
+{
+  return 0;
+}
+
+
 /*
 Report our 'Magic' tool descriptions
 

docs/gl_ES.UTF-8/tp_magic_example.c

@@ -1,7 +1,7 @@
 /* tp_magic_example.c
 
    An example of a "Magic" tool plugin for Tux Paint
-   Xaneiro 15, 2024
+   Xaneiro 16, 2024
 */
 
 
@@ -192,7 +192,8 @@ int example_get_tool_count(magic_api * api)
 /*
 Load our icons
 
-When Tux Paint is starting up and loading plugins, it asks us to provide icons for the 'Magic' tool buttons.
+When Tux Paint is starting up and loading plugins, it asks us to provide
+icons for the 'Magic' tool buttons.
 */
 SDL_Surface *example_get_icon(magic_api * api, int which)
 {
@@ -275,6 +276,20 @@ int example_get_group(magic_api * api, int which)
 }
 
 
+/*
+Return grouping/ordering number
+
+When Tux Paint is starting up and loading plugins, it asks us to provide a
+numeric value used for sorting 'Magic' tools within a group.  Tools will be
+ordered based on this number, and those with the same number will be sorted
+alphabetically by their localized name (see 'example_get_name').
+*/
+int *example_get_order(int which)
+{
+  return 0;
+}
+
+
 /*
 Report our 'Magic' tool descriptions
 

docs/is_IS.UTF-8/html/tp_magic_example.c

@@ -1,7 +1,7 @@
 /* tp_magic_example.c
 
    An example of a "Magic" tool plugin for Tux Paint
-   15. janúar 2024
+   16. janúar 2024
 */
 
 
@@ -192,7 +192,8 @@ int example_get_tool_count(magic_api * api)
 /*
 Load our icons
 
-When Tux Paint is starting up and loading plugins, it asks us to provide icons for the 'Magic' tool buttons.
+When Tux Paint is starting up and loading plugins, it asks us to provide
+icons for the 'Magic' tool buttons.
 */
 SDL_Surface *example_get_icon(magic_api * api, int which)
 {
@@ -275,6 +276,20 @@ int example_get_group(magic_api * api, int which)
 }
 
 
+/*
+Return grouping/ordering number
+
+When Tux Paint is starting up and loading plugins, it asks us to provide a
+numeric value used for sorting 'Magic' tools within a group.  Tools will be
+ordered based on this number, and those with the same number will be sorted
+alphabetically by their localized name (see 'example_get_name').
+*/
+int *example_get_order(int which)
+{
+  return 0;
+}
+
+
 /*
 Report our 'Magic' tool descriptions
 

docs/is_IS.UTF-8/tp_magic_example.c

@@ -1,7 +1,7 @@
 /* tp_magic_example.c
 
    An example of a "Magic" tool plugin for Tux Paint
-   15. janúar 2024
+   16. janúar 2024
 */
 
 
@@ -192,7 +192,8 @@ int example_get_tool_count(magic_api * api)
 /*
 Load our icons
 
-When Tux Paint is starting up and loading plugins, it asks us to provide icons for the 'Magic' tool buttons.
+When Tux Paint is starting up and loading plugins, it asks us to provide
+icons for the 'Magic' tool buttons.
 */
 SDL_Surface *example_get_icon(magic_api * api, int which)
 {
@@ -275,6 +276,20 @@ int example_get_group(magic_api * api, int which)
 }
 
 
+/*
+Return grouping/ordering number
+
+When Tux Paint is starting up and loading plugins, it asks us to provide a
+numeric value used for sorting 'Magic' tools within a group.  Tools will be
+ordered based on this number, and those with the same number will be sorted
+alphabetically by their localized name (see 'example_get_name').
+*/
+int *example_get_order(int which)
+{
+  return 0;
+}
+
+
 /*
 Report our 'Magic' tool descriptions
 

docs/ja_JP.UTF-8/html/tp_magic_example.c

@@ -1,7 +1,7 @@
 /* tp_magic_example.c
 
    An example of a "Magic" tool plugin for Tux Paint
-   1月 15, 2024
+   1月 16, 2024
 */
 
 
@@ -192,7 +192,8 @@ int example_get_tool_count(magic_api * api)
 /*
 Load our icons
 
-When Tux Paint is starting up and loading plugins, it asks us to provide icons for the 'Magic' tool buttons.
+When Tux Paint is starting up and loading plugins, it asks us to provide
+icons for the 'Magic' tool buttons.
 */
 SDL_Surface *example_get_icon(magic_api * api, int which)
 {
@@ -275,6 +276,20 @@ int example_get_group(magic_api * api, int which)
 }
 
 
+/*
+Return grouping/ordering number
+
+When Tux Paint is starting up and loading plugins, it asks us to provide a
+numeric value used for sorting 'Magic' tools within a group.  Tools will be
+ordered based on this number, and those with the same number will be sorted
+alphabetically by their localized name (see 'example_get_name').
+*/
+int *example_get_order(int which)
+{
+  return 0;
+}
+
+
 /*
 Report our 'Magic' tool descriptions
 

docs/ja_JP.UTF-8/tp_magic_example.c

@@ -1,7 +1,7 @@
 /* tp_magic_example.c
 
    An example of a "Magic" tool plugin for Tux Paint
-   1月 15, 2024
+   1月 16, 2024
 */
 
 
@@ -192,7 +192,8 @@ int example_get_tool_count(magic_api * api)
 /*
 Load our icons
 
-When Tux Paint is starting up and loading plugins, it asks us to provide icons for the 'Magic' tool buttons.
+When Tux Paint is starting up and loading plugins, it asks us to provide
+icons for the 'Magic' tool buttons.
 */
 SDL_Surface *example_get_icon(magic_api * api, int which)
 {
@@ -275,6 +276,20 @@ int example_get_group(magic_api * api, int which)
 }
 
 
+/*
+Return grouping/ordering number
+
+When Tux Paint is starting up and loading plugins, it asks us to provide a
+numeric value used for sorting 'Magic' tools within a group.  Tools will be
+ordered based on this number, and those with the same number will be sorted
+alphabetically by their localized name (see 'example_get_name').
+*/
+int *example_get_order(int which)
+{
+  return 0;
+}
+
+
 /*
 Report our 'Magic' tool descriptions