From 84bfec33659ba1990a548ef9856880bcde1ebe7c Mon Sep 17 00:00:00 2001 From: Bill Kendrick Date: Tue, 11 Apr 2023 21:55:39 -0700 Subject: [PATCH] Sync docs & more info re: forthcoming Magic size feature --- docs/CHANGES.txt | 4 ++++ docs/en/MAGIC-API.txt | 29 +++++++++++++++++++++++++++- docs/en/html/MAGIC-API.html | 18 ++++++++++++++++- docs/es_ES.UTF-8/MAGIC-API.txt | 29 +++++++++++++++++++++++++++- docs/es_ES.UTF-8/html/MAGIC-API.html | 18 ++++++++++++++++- docs/fr_FR.UTF-8/MAGIC-API.txt | 29 +++++++++++++++++++++++++++- docs/fr_FR.UTF-8/html/MAGIC-API.html | 18 ++++++++++++++++- docs/gl_ES.UTF-8/MAGIC-API.txt | 29 +++++++++++++++++++++++++++- docs/gl_ES.UTF-8/html/MAGIC-API.html | 18 ++++++++++++++++- docs/ja_JP.UTF-8/MAGIC-API.txt | 29 +++++++++++++++++++++++++++- docs/ja_JP.UTF-8/html/MAGIC-API.html | 18 ++++++++++++++++- src/tp_magic_api.h.in | 4 ++++ 12 files changed, 233 insertions(+), 10 deletions(-) diff --git a/docs/CHANGES.txt b/docs/CHANGES.txt index 41d7a00ff..632b223c3 100644 --- a/docs/CHANGES.txt +++ b/docs/CHANGES.txt @@ -25,8 +25,12 @@ https://tuxpaint.org/ * Improvements to Magic tools: ---------------------------- * WIP Support for sizes in Magic tools via the plugin API. + WIP Adds a new UI element for setting sizes in the Magic tool. + WIP May be disabled with the "nomagicsizes" option. Closes https://sourceforge.net/p/tuxpaint/feature-requests/220/ Note: Bumps `TP_MAGIC_API_VERSION` to 0x00000008. + WIP Plugins' "init()" functions are sent a new "disabled_features" + argument containing bitmask of Magic-relevant disabled features. Bill Kendrick * Other Improvements: diff --git a/docs/en/MAGIC-API.txt b/docs/en/MAGIC-API.txt index 760c62407..cb7ae1d64 100644 --- a/docs/en/MAGIC-API.txt +++ b/docs/en/MAGIC-API.txt @@ -177,7 +177,7 @@ Magic Tool Plugin API Documentation Note: Called once by Tux Paint, at startup. It is called first. - int init(magic_api * api) + int init(magic_api * api, Uint32 disabled_features) The plugin should do any initialization here. Return '1' if initialization was successful, or '0' if not (and Tux Paint will @@ -187,6 +187,21 @@ Magic Tool Plugin API Documentation "api_version()", if Tux Paint believes your plugin to be compatible. + The disabled_features value contains bits set for any Tux Paint + features relevant to Magic tools which have been disabled in this + session. Test using the C bitwise 'and' operator, '&'. The + features are defined in tp_magic_api.h: + * MAGIC_FEATURE_SIZE: Magic tool size (Magic tool size) + Your Magic tool(s) may wish to react differently depending on + whether one or more features have been disabled. (For example, the + "Brick" Magic tool always offered two tool variations: large and + small. With the addition of the size feature, only one tool is + necessary. However, with the size option disabled, the plugin is + able to revert back to providing two separate tools.) + + Note: Changed most recently in Tux Paint 0.9.30; Magic API version + 0x00000008. + int get_tool_count(magic_api * api) This should return the number of Magic tools this plugin provides @@ -304,6 +319,18 @@ Magic Tool Plugin API Documentation Note: Called once for each Magic tool your plugin claims to contain (by your "get_tool_count()"). + int default_size(magic_api * api, int which) + + Return the default size the 'Magic' tool accepts. This will be the + default setting for the tool the first time it is used during a + Tux Paint session. If Tux Paint is being invoked with the sizing + option disabled, this will be the only size requested by Tux + Paint. Return a number between '1' and the amount you returned in + accepted_sizes(). + + Note: Called once for each Magic tool your plugin claims to + contain (by your "get_tool_count()"). + void shutdown(magic_api * api) The plugin should do any cleanup here. If you allocated any memory diff --git a/docs/en/html/MAGIC-API.html b/docs/en/html/MAGIC-API.html index 9e9de16f4..7866a75e7 100644 --- a/docs/en/html/MAGIC-API.html +++ b/docs/en/html/MAGIC-API.html @@ -281,12 +281,20 @@ Note: Called once by Tux Paint, at startup. It is called first.

-
int init(magic_api * api)
+
int init(magic_api * api, Uint32 disabled_features)

The plugin should do any initialization here. Return '1' if initialization was successful, or '0' if not (and Tux Paint will not present any 'Magic' tools from the plugin).

Note: Called once by Tux Paint, at startup. It is called after "api_version()", if Tux Paint believes your plugin to be compatible.

+

+ The disabled_features value contains bits set for any Tux Paint features relevant to Magic tools which have been disabled in this session. Test using the C bitwise 'and' operator, '&'. The features are defined in tp_magic_api.h:

    +
  • + MAGIC_FEATURE_SIZE: Magic tool size (Magic tool size)
    • +
+ Your Magic tool(s) may wish to react differently depending on whether one or more features have been disabled. (For example, the "Brick" Magic tool always offered two tool variations: large and small. With the addition of the size feature, only one tool is necessary. However, with the size option disabled, the plugin is able to revert back to providing two separate tools.)

+

+ Note: Changed most recently in Tux Paint 0.9.30; Magic API version 0x00000008.

int get_tool_count(magic_api * api)
@@ -393,6 +401,14 @@ Note: Called once for each Magic tool your plugin claims to contain (by your "get_tool_count()").

+
int default_size(magic_api * api, int which)
+
+

+ Return the default size the 'Magic' tool accepts. This will be the default setting for the tool the first time it is used during a Tux Paint session. If Tux Paint is being invoked with the sizing option disabled, this will be the only size requested by Tux Paint. Return a number between '1' and the amount you returned in accepted_sizes().

+

+ Note: Called once for each Magic tool your plugin claims to contain (by your "get_tool_count()").

+
+
void shutdown(magic_api * api)

diff --git a/docs/es_ES.UTF-8/MAGIC-API.txt b/docs/es_ES.UTF-8/MAGIC-API.txt index 0f4d6a341..4fa642b34 100644 --- a/docs/es_ES.UTF-8/MAGIC-API.txt +++ b/docs/es_ES.UTF-8/MAGIC-API.txt @@ -177,7 +177,7 @@ Magic Tool Plugin API Documentation Note: Called once by Tux Paint, at startup. It is called first. - int init(magic_api * api) + int init(magic_api * api, Uint32 disabled_features) The plugin should do any initialization here. Return '1' if initialization was successful, or '0' if not (and Tux Paint will @@ -187,6 +187,21 @@ Magic Tool Plugin API Documentation "api_version()", if Tux Paint believes your plugin to be compatible. + The disabled_features value contains bits set for any Tux Paint + features relevant to Magic tools which have been disabled in this + session. Test using the C bitwise 'and' operator, '&'. The + features are defined in tp_magic_api.h: + * MAGIC_FEATURE_SIZE: Magic tool size (Magic tool size) + Your Magic tool(s) may wish to react differently depending on + whether one or more features have been disabled. (For example, the + "Brick" Magic tool always offered two tool variations: large and + small. With the addition of the size feature, only one tool is + necessary. However, with the size option disabled, the plugin is + able to revert back to providing two separate tools.) + + Note: Changed most recently in Tux Paint 0.9.30; Magic API version + 0x00000008. + int get_tool_count(magic_api * api) This should return the number of Magic tools this plugin provides @@ -304,6 +319,18 @@ Magic Tool Plugin API Documentation Note: Called once for each Magic tool your plugin claims to contain (by your "get_tool_count()"). + int default_size(magic_api * api, int which) + + Return the default size the 'Magic' tool accepts. This will be the + default setting for the tool the first time it is used during a + Tux Paint session. If Tux Paint is being invoked with the sizing + option disabled, this will be the only size requested by Tux + Paint. Return a number between '1' and the amount you returned in + accepted_sizes(). + + Note: Called once for each Magic tool your plugin claims to + contain (by your "get_tool_count()"). + void shutdown(magic_api * api) The plugin should do any cleanup here. If you allocated any memory diff --git a/docs/es_ES.UTF-8/html/MAGIC-API.html b/docs/es_ES.UTF-8/html/MAGIC-API.html index fcdbf3c5e..84869a65d 100644 --- a/docs/es_ES.UTF-8/html/MAGIC-API.html +++ b/docs/es_ES.UTF-8/html/MAGIC-API.html @@ -281,12 +281,20 @@ Note: Called once by Tux Paint, at startup. It is called first.

-
int init(magic_api * api)
+
int init(magic_api * api, Uint32 disabled_features)

The plugin should do any initialization here. Return '1' if initialization was successful, or '0' if not (and Tux Paint will not present any 'Magic' tools from the plugin).

Note: Called once by Tux Paint, at startup. It is called after "api_version()", if Tux Paint believes your plugin to be compatible.

+

+ The disabled_features value contains bits set for any Tux Paint features relevant to Magic tools which have been disabled in this session. Test using the C bitwise 'and' operator, '&'. The features are defined in tp_magic_api.h:

    +
  • + MAGIC_FEATURE_SIZE: Magic tool size (Magic tool size)
    • +
+ Your Magic tool(s) may wish to react differently depending on whether one or more features have been disabled. (For example, the "Brick" Magic tool always offered two tool variations: large and small. With the addition of the size feature, only one tool is necessary. However, with the size option disabled, the plugin is able to revert back to providing two separate tools.)

+

+ Note: Changed most recently in Tux Paint 0.9.30; Magic API version 0x00000008.

int get_tool_count(magic_api * api)
@@ -393,6 +401,14 @@ Note: Called once for each Magic tool your plugin claims to contain (by your "get_tool_count()").

+
int default_size(magic_api * api, int which)
+
+

+ Return the default size the 'Magic' tool accepts. This will be the default setting for the tool the first time it is used during a Tux Paint session. If Tux Paint is being invoked with the sizing option disabled, this will be the only size requested by Tux Paint. Return a number between '1' and the amount you returned in accepted_sizes().

+

+ Note: Called once for each Magic tool your plugin claims to contain (by your "get_tool_count()").

+
+
void shutdown(magic_api * api)

diff --git a/docs/fr_FR.UTF-8/MAGIC-API.txt b/docs/fr_FR.UTF-8/MAGIC-API.txt index 599ba734d..d380d588d 100644 --- a/docs/fr_FR.UTF-8/MAGIC-API.txt +++ b/docs/fr_FR.UTF-8/MAGIC-API.txt @@ -177,7 +177,7 @@ Magic Tool Plugin API Documentation Note: Called once by Tux Paint, at startup. It is called first. - int init(magic_api * api) + int init(magic_api * api, Uint32 disabled_features) The plugin should do any initialization here. Return '1' if initialization was successful, or '0' if not (and Tux Paint will @@ -187,6 +187,21 @@ Magic Tool Plugin API Documentation "api_version()", if Tux Paint believes your plugin to be compatible. + The disabled_features value contains bits set for any Tux Paint + features relevant to Magic tools which have been disabled in this + session. Test using the C bitwise 'and' operator, '&'. The + features are defined in tp_magic_api.h: + * MAGIC_FEATURE_SIZE: Magic tool size (Magic tool size) + Your Magic tool(s) may wish to react differently depending on + whether one or more features have been disabled. (For example, the + "Brick" Magic tool always offered two tool variations: large and + small. With the addition of the size feature, only one tool is + necessary. However, with the size option disabled, the plugin is + able to revert back to providing two separate tools.) + + Note: Changed most recently in Tux Paint 0.9.30; Magic API version + 0x00000008. + int get_tool_count(magic_api * api) This should return the number of Magic tools this plugin provides @@ -304,6 +319,18 @@ Magic Tool Plugin API Documentation Note: Called once for each Magic tool your plugin claims to contain (by your "get_tool_count()"). + int default_size(magic_api * api, int which) + + Return the default size the 'Magic' tool accepts. This will be the + default setting for the tool the first time it is used during a + Tux Paint session. If Tux Paint is being invoked with the sizing + option disabled, this will be the only size requested by Tux + Paint. Return a number between '1' and the amount you returned in + accepted_sizes(). + + Note: Called once for each Magic tool your plugin claims to + contain (by your "get_tool_count()"). + void shutdown(magic_api * api) The plugin should do any cleanup here. If you allocated any memory diff --git a/docs/fr_FR.UTF-8/html/MAGIC-API.html b/docs/fr_FR.UTF-8/html/MAGIC-API.html index d3fa2acc4..61e54002e 100644 --- a/docs/fr_FR.UTF-8/html/MAGIC-API.html +++ b/docs/fr_FR.UTF-8/html/MAGIC-API.html @@ -281,12 +281,20 @@ Note: Called once by Tux Paint, at startup. It is called first.

-
int init(magic_api * api)
+
int init(magic_api * api, Uint32 disabled_features)

The plugin should do any initialization here. Return '1' if initialization was successful, or '0' if not (and Tux Paint will not present any 'Magic' tools from the plugin).

Note: Called once by Tux Paint, at startup. It is called after "api_version()", if Tux Paint believes your plugin to be compatible.

+

+ The disabled_features value contains bits set for any Tux Paint features relevant to Magic tools which have been disabled in this session. Test using the C bitwise 'and' operator, '&'. The features are defined in tp_magic_api.h:

    +
  • + MAGIC_FEATURE_SIZE: Magic tool size (Magic tool size)
    • +
+ Your Magic tool(s) may wish to react differently depending on whether one or more features have been disabled. (For example, the "Brick" Magic tool always offered two tool variations: large and small. With the addition of the size feature, only one tool is necessary. However, with the size option disabled, the plugin is able to revert back to providing two separate tools.)

+

+ Note: Changed most recently in Tux Paint 0.9.30; Magic API version 0x00000008.

int get_tool_count(magic_api * api)
@@ -393,6 +401,14 @@ Note: Called once for each Magic tool your plugin claims to contain (by your "get_tool_count()").

+
int default_size(magic_api * api, int which)
+
+

+ Return the default size the 'Magic' tool accepts. This will be the default setting for the tool the first time it is used during a Tux Paint session. If Tux Paint is being invoked with the sizing option disabled, this will be the only size requested by Tux Paint. Return a number between '1' and the amount you returned in accepted_sizes().

+

+ Note: Called once for each Magic tool your plugin claims to contain (by your "get_tool_count()").

+
+
void shutdown(magic_api * api)

diff --git a/docs/gl_ES.UTF-8/MAGIC-API.txt b/docs/gl_ES.UTF-8/MAGIC-API.txt index 5aa7e4e39..e14df669b 100644 --- a/docs/gl_ES.UTF-8/MAGIC-API.txt +++ b/docs/gl_ES.UTF-8/MAGIC-API.txt @@ -177,7 +177,7 @@ Magic Tool Plugin API Documentation Note: Called once by Tux Paint, at startup. It is called first. - int init(magic_api * api) + int init(magic_api * api, Uint32 disabled_features) The plugin should do any initialization here. Return '1' if initialization was successful, or '0' if not (and Tux Paint will @@ -187,6 +187,21 @@ Magic Tool Plugin API Documentation "api_version()", if Tux Paint believes your plugin to be compatible. + The disabled_features value contains bits set for any Tux Paint + features relevant to Magic tools which have been disabled in this + session. Test using the C bitwise 'and' operator, '&'. The + features are defined in tp_magic_api.h: + * MAGIC_FEATURE_SIZE: Magic tool size (Magic tool size) + Your Magic tool(s) may wish to react differently depending on + whether one or more features have been disabled. (For example, the + "Brick" Magic tool always offered two tool variations: large and + small. With the addition of the size feature, only one tool is + necessary. However, with the size option disabled, the plugin is + able to revert back to providing two separate tools.) + + Note: Changed most recently in Tux Paint 0.9.30; Magic API version + 0x00000008. + int get_tool_count(magic_api * api) This should return the number of Magic tools this plugin provides @@ -304,6 +319,18 @@ Magic Tool Plugin API Documentation Note: Called once for each Magic tool your plugin claims to contain (by your "get_tool_count()"). + int default_size(magic_api * api, int which) + + Return the default size the 'Magic' tool accepts. This will be the + default setting for the tool the first time it is used during a + Tux Paint session. If Tux Paint is being invoked with the sizing + option disabled, this will be the only size requested by Tux + Paint. Return a number between '1' and the amount you returned in + accepted_sizes(). + + Note: Called once for each Magic tool your plugin claims to + contain (by your "get_tool_count()"). + void shutdown(magic_api * api) The plugin should do any cleanup here. If you allocated any memory diff --git a/docs/gl_ES.UTF-8/html/MAGIC-API.html b/docs/gl_ES.UTF-8/html/MAGIC-API.html index 8c940d22a..a9a9ca2f2 100644 --- a/docs/gl_ES.UTF-8/html/MAGIC-API.html +++ b/docs/gl_ES.UTF-8/html/MAGIC-API.html @@ -281,12 +281,20 @@ Note: Called once by Tux Paint, at startup. It is called first.

-
int init(magic_api * api)
+
int init(magic_api * api, Uint32 disabled_features)

The plugin should do any initialization here. Return '1' if initialization was successful, or '0' if not (and Tux Paint will not present any 'Magic' tools from the plugin).

Note: Called once by Tux Paint, at startup. It is called after "api_version()", if Tux Paint believes your plugin to be compatible.

+

+ The disabled_features value contains bits set for any Tux Paint features relevant to Magic tools which have been disabled in this session. Test using the C bitwise 'and' operator, '&'. The features are defined in tp_magic_api.h:

    +
  • + MAGIC_FEATURE_SIZE: Magic tool size (Magic tool size)
    • +
+ Your Magic tool(s) may wish to react differently depending on whether one or more features have been disabled. (For example, the "Brick" Magic tool always offered two tool variations: large and small. With the addition of the size feature, only one tool is necessary. However, with the size option disabled, the plugin is able to revert back to providing two separate tools.)

+

+ Note: Changed most recently in Tux Paint 0.9.30; Magic API version 0x00000008.

int get_tool_count(magic_api * api)
@@ -393,6 +401,14 @@ Note: Called once for each Magic tool your plugin claims to contain (by your "get_tool_count()").

+
int default_size(magic_api * api, int which)
+
+

+ Return the default size the 'Magic' tool accepts. This will be the default setting for the tool the first time it is used during a Tux Paint session. If Tux Paint is being invoked with the sizing option disabled, this will be the only size requested by Tux Paint. Return a number between '1' and the amount you returned in accepted_sizes().

+

+ Note: Called once for each Magic tool your plugin claims to contain (by your "get_tool_count()").

+
+
void shutdown(magic_api * api)

diff --git a/docs/ja_JP.UTF-8/MAGIC-API.txt b/docs/ja_JP.UTF-8/MAGIC-API.txt index facf26cd0..9949273ef 100644 --- a/docs/ja_JP.UTF-8/MAGIC-API.txt +++ b/docs/ja_JP.UTF-8/MAGIC-API.txt @@ -177,7 +177,7 @@ Magic Tool Plugin API Documentation Note: Called once by Tux Paint, at startup. It is called first. - int init(magic_api * api) + int init(magic_api * api, Uint32 disabled_features) The plugin should do any initialization here. Return '1' if initialization was successful, or '0' if not (and Tux Paint will @@ -187,6 +187,21 @@ Magic Tool Plugin API Documentation "api_version()", if Tux Paint believes your plugin to be compatible. + The disabled_features value contains bits set for any Tux Paint + features relevant to Magic tools which have been disabled in this + session. Test using the C bitwise 'and' operator, '&'. The + features are defined in tp_magic_api.h: + * MAGIC_FEATURE_SIZE: Magic tool size (Magic tool size) + Your Magic tool(s) may wish to react differently depending on + whether one or more features have been disabled. (For example, the + "Brick" Magic tool always offered two tool variations: large and + small. With the addition of the size feature, only one tool is + necessary. However, with the size option disabled, the plugin is + able to revert back to providing two separate tools.) + + Note: Changed most recently in Tux Paint 0.9.30; Magic API version + 0x00000008. + int get_tool_count(magic_api * api) This should return the number of Magic tools this plugin provides @@ -304,6 +319,18 @@ Magic Tool Plugin API Documentation Note: Called once for each Magic tool your plugin claims to contain (by your "get_tool_count()"). + int default_size(magic_api * api, int which) + + Return the default size the 'Magic' tool accepts. This will be the + default setting for the tool the first time it is used during a + Tux Paint session. If Tux Paint is being invoked with the sizing + option disabled, this will be the only size requested by Tux + Paint. Return a number between '1' and the amount you returned in + accepted_sizes(). + + Note: Called once for each Magic tool your plugin claims to + contain (by your "get_tool_count()"). + void shutdown(magic_api * api) The plugin should do any cleanup here. If you allocated any memory diff --git a/docs/ja_JP.UTF-8/html/MAGIC-API.html b/docs/ja_JP.UTF-8/html/MAGIC-API.html index edeb55682..705bd8500 100644 --- a/docs/ja_JP.UTF-8/html/MAGIC-API.html +++ b/docs/ja_JP.UTF-8/html/MAGIC-API.html @@ -281,12 +281,20 @@ Note: Called once by Tux Paint, at startup. It is called first.

-
int init(magic_api * api)
+
int init(magic_api * api, Uint32 disabled_features)

The plugin should do any initialization here. Return '1' if initialization was successful, or '0' if not (and Tux Paint will not present any 'Magic' tools from the plugin).

Note: Called once by Tux Paint, at startup. It is called after "api_version()", if Tux Paint believes your plugin to be compatible.

+

+ The disabled_features value contains bits set for any Tux Paint features relevant to Magic tools which have been disabled in this session. Test using the C bitwise 'and' operator, '&'. The features are defined in tp_magic_api.h:

    +
  • + MAGIC_FEATURE_SIZE: Magic tool size (Magic tool size)
    • +
+ Your Magic tool(s) may wish to react differently depending on whether one or more features have been disabled. (For example, the "Brick" Magic tool always offered two tool variations: large and small. With the addition of the size feature, only one tool is necessary. However, with the size option disabled, the plugin is able to revert back to providing two separate tools.)

+

+ Note: Changed most recently in Tux Paint 0.9.30; Magic API version 0x00000008.

int get_tool_count(magic_api * api)
@@ -393,6 +401,14 @@ Note: Called once for each Magic tool your plugin claims to contain (by your "get_tool_count()").

+
int default_size(magic_api * api, int which)
+
+

+ Return the default size the 'Magic' tool accepts. This will be the default setting for the tool the first time it is used during a Tux Paint session. If Tux Paint is being invoked with the sizing option disabled, this will be the only size requested by Tux Paint. Return a number between '1' and the amount you returned in accepted_sizes().

+

+ Note: Called once for each Magic tool your plugin claims to contain (by your "get_tool_count()").

+
+
void shutdown(magic_api * api)

diff --git a/src/tp_magic_api.h.in b/src/tp_magic_api.h.in index 5332d83fb..2be981a27 100644 --- a/src/tp_magic_api.h.in +++ b/src/tp_magic_api.h.in @@ -184,5 +184,9 @@ enum { MAGIC_TYPE_ARTISTIC }; +/* Magic-relevant Tux Paint features (which may be reported as disabled) */ + +#define MAGIC_FEATURE_SIZE 0x00000001 + #endif