improved user interaction scenarios for buttons, handles and sliders

Author: jmoenig

HISTORY.md

@@ -2,6 +2,10 @@
 
 ## in development:
 
+### 2025-03-19
+* morphic: added lockMouseFocus() mechanism and the concept of a clickTarget, improved user interaction scenarios for buttons, handles and sliders 
+* gui: improved user interaction scenarios for buttons, handles and sliders 
+
 ### 2025-03-17
 * new dev version
 * morphic: simplified BoxMorph & CircleBoxMorph outlinePath rendering with new Canvas roundRect() primitive

src/morphic.txt renamed to docs/morphic.txt

@@ -7,10 +7,10 @@
     written by Jens Mönig
     [email protected]
 
-    Copyright (C) 2010-2022 by Jens Mönig
-
-    This documentation last changed: August 03, 2022
+    Copyright (C) 2010-2025 by Jens Mönig
 
+    This documentation last changed: March 19, 2025
+    
     This file is part of Snap!.
 
     Snap! is free software: you can redistribute it and/or modify
@@ -50,6 +50,7 @@
             (f) resize event
             (g) combined mouse-keyboard events
             (h) text editing events
+            (i) indicating unsaved changes
         (4) stepping
         (5) creating new kinds of morphs
             (a) drawing the shape
@@ -318,7 +319,6 @@
                 var	world1, world2;
 
                 window.onload = function () {
-                    disableRetinaSupport();
                     world1 = new WorldMorph(
                         document.getElementById('world1'), false);
                     world2 = new WorldMorph(
@@ -327,7 +327,7 @@
                 };
 
                 function loop() {
-            requestAnimationFrame(loop);
+                    requestAnimationFrame(loop);
                     world1.doOneCycle();
                     world2.doOneCycle();
                 }
@@ -492,6 +492,19 @@
     currently pressed mouse button, which is either 'left' or 'right'.
     You can use this to let users interact with 3D environments.
 
+    Mouse move and click events are only triggered when and as long as the
+    mouse pointer is within a morph's bounds. If you wish to confine and
+    retain mouse interaction to a particular morph while a mouse button is
+    pressed you can call the morph's
+    
+        lockMouseFocus()
+
+    method, preferrably in one of its mouseDown methods. Afterwards the
+    ensuing mouse events will be routed to the locked morph even after the
+    mouse pointer has left its bounds, and the mouseLeave event will not
+    occur until the mouse button is released again. This is useful for
+    creating sliders and handle widgets for resizing, moving, rotating etc.
+
     The
 
         mouseEnterDragging(morph)
@@ -858,6 +871,19 @@
     single-line text elements can hold them apart.
 
 
+    (i) indicating unsaved changes
+    ------------------------------
+    Before closing a browser tab with a Morphic world any top level morph
+    can signal unsaved changes by implementing a
+    
+        hasUnsavedChanges()
+    
+    method, which returns a Boolean value indicating whether it is safe to
+    destroy. If any top level morph indicates unsaved changes the browser
+    pops up a dialog box warning about unsaved changes and prompting for user
+    confirmation to close it.
+
+
     (4) stepping
     ------------
     Stepping is what makes Morphic "magical". Two properties control
@@ -1230,6 +1256,24 @@
 
     are implemented.
 
+    Animations can also be used to schedule a function execution just once
+    in lockstep with the Morphic scheduler, avoiding the setTimeout() pattern.
+    A syntactic shortcut for single-time scheduling exists in the WorldMorph's
+
+        schedule()
+
+    method.
+
+    For usage examples look at how TriggerMorph implements
+
+        bubbleHelp()
+
+    or at MenuItemMorph's
+
+        delaySubmenu()
+
+    method.
+
 
     (10) minifying morphic.js
     -------------------------

snap.html

@@ -13,14 +13,14 @@
         <meta name="mobile-web-app-title" content="Snap!">
         <meta name="msapplication-TileImage" content="img/snap-icon-144.png">
         <meta name="msapplication-TileColor" content="#FFFFFF">
-        <script src="src/morphic.js?version=2025-03-17"></script>
+        <script src="src/morphic.js?version=2025-03-19"></script>
         <script src="src/symbols.js?version=2024-11-24"></script>
         <script src="src/widgets.js?version=2025-03-17"></script>
         <script src="src/blocks.js?version=2025-01-25"></script>
         <script src="src/threads.js?version=2025-02-26"></script>
         <script src="src/objects.js?version=2025-03-17"></script>
         <script src="src/scenes.js?version=2024-05-28"></script>
-        <script src="src/gui.js?version=2025-03-17"></script>
+        <script src="src/gui.js?version=2025-03-19"></script>
         <script src="src/paint.js?version=2023-05-24"></script>
         <script src="src/lists.js?version=2025-02-27"></script>
         <script src="src/byob.js?version=2024-12-18"></script>

src/gui.js

@@ -87,7 +87,7 @@ HatBlockMorph*/
 
 // Global stuff ////////////////////////////////////////////////////////
 
-modules.gui = '2025-March-17';
+modules.gui = '2025-March-19';
 
 // Declarations
 
@@ -12819,6 +12819,7 @@ function StageHandleMorph(target) {
 
 StageHandleMorph.prototype.init = function (target) {
     this.target = target || null;
+    this.offset = null;
     this.userState = 'normal'; // or 'highlight'
     HandleMorph.uber.init.call(this);
     this.color = IDE_Morph.prototype.isBright ?
@@ -12897,37 +12898,6 @@ StageHandleMorph.prototype.fixLayout = function () {
     if (ide) {ide.add(this); } // come to front
 };
 
-// StageHandleMorph stepping:
-
-StageHandleMorph.prototype.step = null;
-
-StageHandleMorph.prototype.mouseDownLeft = function (pos) {
-    var world = this.world(),
-        offset = this.right() - pos.x,
-        ide = this.target.parentThatIsA(IDE_Morph);
-
-    if (!this.target) {
-        return null;
-    }
-    ide.isSmallStage = true;
-    ide.controlBar.stageSizeButton.refresh();
-
-    this.step = function () {
-        var newPos, newWidth;
-        if (world.hand.mouseButton) {
-            newPos = world.hand.bounds.origin.x + offset;
-            newWidth = this.target.right() - newPos;
-            ide.stageRatio = newWidth / this.target.dimensions.x;
-            ide.setExtent(world.extent());
-
-        } else {
-            this.step = null;
-            ide.isSmallStage = (ide.stageRatio !== 1);
-            ide.controlBar.stageSizeButton.refresh();
-        }
-    };
-};
-
 // StageHandleMorph events:
 
 StageHandleMorph.prototype.mouseEnter = function () {
@@ -12940,6 +12910,26 @@ StageHandleMorph.prototype.mouseLeave = function () {
     this.rerender();
 };
 
+StageHandleMorph.prototype.mouseDownLeft = function (pos) {
+    var ide = this.target.parentThatIsA(IDE_Morph);
+    this.offset = this.right() - pos.x;
+    ide.isSmallStage = true;
+    ide.controlBar.stageSizeButton.refresh();
+    this.lockMouseFocus();
+};
+
+StageHandleMorph.prototype.mouseMove = function (pos) {
+    var ide = this.target.parentThatIsA(IDE_Morph),
+        newPos = pos.x + this.offset,
+        newWidth = this.target.right() - newPos;
+    ide.stageRatio = newWidth / this.target.dimensions.x;
+    if (ide.isSmallStage !== (ide.stageRatio !== 1)) {
+        ide.isSmallStage = (ide.stageRatio !== 1);
+        ide.controlBar.stageSizeButton.refresh();
+    }
+    ide.setExtent(ide.world().extent());
+};
+
 StageHandleMorph.prototype.mouseDoubleClick = function () {
     this.target.parentThatIsA(IDE_Morph).toggleStageSize(true, 1);
 };
@@ -12963,6 +12953,7 @@ function PaletteHandleMorph(target) {
 
 PaletteHandleMorph.prototype.init = function (target) {
     this.target = target || null;
+    this.offset = null;
     this.userState = 'normal';
     HandleMorph.uber.init.call(this);
     this.color = IDE_Morph.prototype.isBright ?
@@ -12989,40 +12980,6 @@ PaletteHandleMorph.prototype.fixLayout = function () {
     if (ide) {ide.add(this); } // come to front
 };
 
-// PaletteHandleMorph stepping:
-
-PaletteHandleMorph.prototype.step = null;
-
-PaletteHandleMorph.prototype.mouseDownLeft = function (pos) {
-    var world = this.world(),
-        offset = this.right() - pos.x,
-        ide = this.target.parentThatIsA(IDE_Morph),
-        cnf = ide.config,
-        border = cnf.border || 0;
-
-    if (!this.target) {
-        return null;
-    }
-    this.step = function () {
-        var newPos;
-        if (world.hand.mouseButton) {
-            newPos = world.hand.bounds.origin.x + offset;
-            ide.paletteWidth = Math.min(
-                Math.max(
-                    200, newPos - ide.left() - border * 2),
-                    cnf.noSprites ?
-                        ide.width() - border * 2
-                        : ide.stageHandle.left() -
-                            ide.spriteBar.tabBar.width()
-            );
-            ide.setExtent(world.extent());
-
-        } else {
-            this.step = null;
-        }
-    };
-};
-
 // PaletteHandleMorph events:
 
 PaletteHandleMorph.prototype.mouseEnter
@@ -13031,6 +12988,27 @@ PaletteHandleMorph.prototype.mouseEnter
 PaletteHandleMorph.prototype.mouseLeave
     = StageHandleMorph.prototype.mouseLeave;
 
+PaletteHandleMorph.prototype.mouseDownLeft = function (pos) {
+    this.offset = this.right() - pos.x;
+    this.lockMouseFocus();
+};
+
+PaletteHandleMorph.prototype.mouseMove = function (pos) {
+    var ide = this.target.parentThatIsA(IDE_Morph),
+        cnf = ide.config,
+        border = cnf.border || 0,
+        newPos = pos.x + this.offset;
+    ide.paletteWidth = Math.min(
+        Math.max(
+            200, newPos - ide.left() - border * 2),
+            cnf.noSprites ?
+                ide.width() - border * 2
+                : ide.stageHandle.left() -
+                    ide.spriteBar.tabBar.width()
+    );
+    ide.setExtent(ide.world().extent());
+};
+
 PaletteHandleMorph.prototype.mouseDoubleClick = function () {
     this.target.parentThatIsA(IDE_Morph).setPaletteWidth(200);
 };