From a82a17711e6a3f06b910041eb9f06e28db7aa78b Mon Sep 17 00:00:00 2001 From: jmoenig Date: Sun, 20 Jun 2021 10:25:07 +0200 Subject: [PATCH] updated extensions documentation --- HISTORY.md | 5 +++++ snap.html | 2 +- src/extensions.js | 52 +++++++++++++++++++++++++++++++++++++++++++---- 3 files changed, 54 insertions(+), 5 deletions(-) diff --git a/HISTORY.md b/HISTORY.md index a48e4e7f..ce18a59e 100755 --- a/HISTORY.md +++ b/HISTORY.md @@ -4,9 +4,14 @@ * **New Features:** * new extension primitives +* **Notable Changes:** + * libraries no longer rely on the JSF primitive, project may need to re-import their libraries to run without having to enable JS exstensions * **Notable Fixes:** * fixed occasional invisible error messages +### 2021-06-19 +* updated extensions documentation + ### 2021-06-19 * extensions: added color extension primitives * byob: fixed search for dynamic extension menus diff --git a/snap.html b/snap.html index cfb40785..c2c9abe3 100755 --- a/snap.html +++ b/snap.html @@ -19,7 +19,7 @@ - + diff --git a/src/extensions.js b/src/extensions.js index a06d2057..fd43ff04 100644 --- a/src/extensions.js +++ b/src/extensions.js @@ -31,7 +31,7 @@ IDE_Morph, CamSnapshotDialogMorph, SoundRecorderDialogMorph, isSnapObject, nop, Color, contains*/ -modules.extensions = '2021-June-19'; +modules.extensions = '2021-June-20'; // Global stuff @@ -41,9 +41,19 @@ var SnapExtensions = { }; /* - SnapExtensions is a global dictionary of named functions which appear - in the drop-down menus of the hidden extension "primitive" blocks sorted - alphabetically. + SnapExtensions is a set of two global dictionaries of named functions to be + used as extension primitives for blocks or dynamic dropdown menus. Block + extensions are stored in the "primitives" dictionary of SnapExtensions, + dynamic dropdown menus in the "menus" section. + + + 1. Primitives (additional blocks) + ================================= + The names under which primitives are stored will apear in the dropdown + menus of the hidden extension "primitive" blocks sorted alphabetically. + (You can find those extension primitives in Snap's search bar or in dev + mode. There are two version of the primitive block, a command version and + a reporter one, both show the same list of available extensions. naming conventions ------------------ @@ -62,6 +72,40 @@ var SnapExtensions = { - functions are called by the "primitive" blocks with any arguments provided - "this" refers to the current snap object (sprite or stage) at call-time - a reference to the current process is always passed as last argument + + + 2. Menus (for input slots) + ========================== + The names of the available dynamic drowdown menus can be written into the + "options" dialog when defining an input slot. Additionally you can choose + from a list of available menus when holding down the shift-key while + clicking on the partial-gear button in Snap's input-slot dialog. + + naming conventions + ------------------ + domain-prefix_function-name + example: 'clr_number' + + - domain-prefix: max 3-letter lowercase identifier + followed by an underscore + e.g.: clr_, txt_, lst_ + + - function-name: short, single word if possible, lowercase + - NOTE: dynamic menu functions cannot have any inputs + + function semantics + ------------------ + - "this" refers to the current input-slot at call-time + - to get a handle on the current block use "this.parentThatIsA(BlockMorph") + - likewise to get a handle on the current sprite use + "this.parentThatIsA(IDE_Morph).currentSprite" + - if you want the menu of one input slot to depend on the contents of + another input slot of the same block, you can get a handle to the block + using the above method, and then access all inputs by calling + "block.inputs()". This will give you an array of all input slots. + You can access the contents of an input slot by calling "slot.evaluate()" + + Whatever you do, please use these extension capabilities sensibly. */ // errors & exceptions (err_):