From 2579cadad1a19d22508722708f4496e75bb25384 Mon Sep 17 00:00:00 2001 From: Rik Roots Date: Thu, 27 Apr 2023 13:07:58 +0100 Subject: [PATCH] update documentation --- .../before-after-slider-infographic.html | 2 +- docs/source/core/user-interaction.html | 68 +--- docs/source/factory/cell.html | 315 ++++++------------ docs/source/factory/phrase.html | 229 ++++++------- 4 files changed, 206 insertions(+), 408 deletions(-) diff --git a/docs/demo/snippets/before-after-slider-infographic.html b/docs/demo/snippets/before-after-slider-infographic.html index 7c6a00c67..8bd0b6792 100644 --- a/docs/demo/snippets/before-after-slider-infographic.html +++ b/docs/demo/snippets/before-after-slider-infographic.html @@ -942,7 +942,7 @@
The exported function
- 
            const navItems = getNavigationData(element.querySelector(':scope > nav'));
+ 
            const navItems = getNavigationData(element.querySelector(':scope > nav'), {});
diff --git a/docs/source/core/user-interaction.html b/docs/source/core/user-interaction.html index 6e62cd145..9f732d06d 100644 --- a/docs/source/core/user-interaction.html +++ b/docs/source/core/user-interaction.html @@ -1278,53 +1278,9 @@

Cascade interac } }; -const updatePhraseEntitys = function () { - - - - -
  • -
    - -
    - § -
    -

    for (const [name, ent] of _entries(library.entity)) {

    - -
    - -
    • - - -
  • -
    - -
    - § -
    - 
    if (ent.type == T_PHRASE) {
-
    - -
    - -
    • - - -
  • -
    - -
    - § -
    - 
        ent.dirtyDimensions = true;
-    ent.dirtyFont = true;
-}
-
    -

    }

    +const updatePhraseEntitys = function () { -
    - - 
        _values(library.entity).forEach(ent => {
+    _values(library.entity).forEach(ent => {
 
         if (ent.type == T_PHRASE) {
 
@@ -1337,11 +1293,11 @@ 
    Cascade interac
    • -
  • +
  • - § + §

    Internal functions that get triggered when setting a DOM-based artefact’s trackHere attribute. They add/remove an event listener to the artefact’s domElement.

    @@ -1382,11 +1338,11 @@

    Cascade interac

    • -
  • +
  • - § + §

    Animation object which checks whether any window event listeners have fired, and actions accordingly

    @@ -1438,11 +1394,11 @@

    Cascade interac

    • -
  • +
  • - § + §

    Exported functions (to modules and the scrawl object). Event listeners can be a drain on web page efficiency. If a web page contains only static canvas (and/or stack) displays, with no requirement for user interaction, we can minimize Scrawl-canvas’s impact on those pages by switching off the core listeners (and also the core animation loop).

    @@ -1470,11 +1426,11 @@

    Cascade interac

    • -
  • +
  • - § + §

    Helper function

    @@ -1511,11 +1467,11 @@

    Cascade interac

    • -
  • +
  • - § + §

    Exported functions (to modules). Invoke the resize and/or scroll event listeners once, outside the regular requestAnimationFrame tick.

    diff --git a/docs/source/factory/cell.html b/docs/source/factory/cell.html index 316612f71..da91483f1 100644 --- a/docs/source/factory/cell.html +++ b/docs/source/factory/cell.html @@ -1116,54 +1116,7 @@

    Kill functionality

    §
    -

    Remove artefact from all canvases -_entries(canvas).forEach(([name, cvs]) => {

    - -
    - -
    • - - -
  • -
    - -
    - § -
    - 
    if (cvs.cells.includes(myname)) cvs.removeCell(myname);
-
    - -
    - -
    • - - -
  • -
    - -
    - § -
    - 
    if (cvs.base && cvs.base.name == myname) {
-
    - -
    - -
    • - - -
  • -
    - -
    - § -
    - 
        cvs.set({
-        visibility: false,
-    });
-}
-
    -

    });

    +

    Remove artefact from all canvases

    @@ -1182,89 +1135,13 @@

    Kill functionality

    • -
  • -
    - -
    - § -
    -

    Remove from other artefacts -_entries(artefact).forEach(([name, art]) => {

    - -
    - -
    • - - -
  • -
    - -
    - § -
    - 
    if (art.name !== myname) {
-
    - -
    - -
    • - - -
  • -
    - -
    - § -
    - 
        const state = art.state;
-
    - -
    - -
    • - - -
  • -
    - -
    - § -
    - 
        if (state) {
-
    - -
    - -
    • - - -
  • -
    - -
    - § -
    - 
            const fill = state.fillStyle,
-            stroke = state.strokeStyle;
-
    - -
    - -
    • - - -
  • +
  • - § + §
    - 
            if (fill.name && fill.name == myname) state.fillStyle = state.defs.fillStyle;
-        if (stroke.name && stroke.name == myname) state.strokeStyle = state.defs.strokeStyle;
-    }
-}
-
    -

    });

    +

    Remove from other artefacts

    @@ -1288,11 +1165,11 @@

    Kill functionality

    • -
  • +
  • - § + §

    Kill group

    @@ -1304,11 +1181,11 @@

    Kill functionality

    • -
  • +
  • - § + §

    Get, Set, deltaSet

    @@ -1321,11 +1198,11 @@

    Get, Set, deltaSet

    • -
  • +
  • - § + §

    get - overwrites the mixin/position function

    @@ -1363,11 +1240,11 @@

    Get, Set, deltaSet

    • -
  • +
  • - § + §

    width

    @@ -1390,11 +1267,11 @@

    Get, Set, deltaSet

    • -
  • +
  • - § + §

    height

    @@ -1431,11 +1308,11 @@

    Get, Set, deltaSet

    • -
  • +
  • - § + §

    Internal setters

    @@ -1453,11 +1330,11 @@

    Get, Set, deltaSet

    • -
  • +
  • - § + §

    Display cycle Boolean flags cleared, compiled, shown

    @@ -1468,11 +1345,11 @@

    Get, Set, deltaSet

    • -
  • +
  • - § + §

    If we try to clear the cell with a transparent color, it will not clear. Setting it to an empty string fixes this issue

    @@ -1501,11 +1378,11 @@

    Get, Set, deltaSet

    • -
  • +
  • - § + §

    Display cycle order attributes compileOrder, showOrder - argument should be a positive integer Number

    @@ -1525,11 +1402,11 @@

    Get, Set, deltaSet

    • -
  • +
  • - § + §

    Stash coordinates and dimensions - which are stored in Coordinate arrays - allow us to store, and export to an image asset, a portion of the Cell’s current display which can then be used (for instance) by Pattern styles.

      @@ -1630,11 +1507,11 @@

      Get, Set, deltaSet

      -
    • +
    • - § + §

      smoothFont - handle this directly; don’t save the attribute state

      @@ -1667,11 +1544,11 @@

      Get, Set, deltaSet

      • -
    • +
    • - § + §

      checkForEntityHover, onEntityHover, onEntityNoHover - these are group-specific attributes which we can set on the Cell’s named group via the Cell’s wrapper

      @@ -1699,11 +1576,11 @@

      Get, Set, deltaSet

      • -
    • +
    • - § + §

      group - get the Cell’s namesake group

        @@ -1720,11 +1597,11 @@

        Get, Set, deltaSet

        -
      • +
      • - § + §

        Prototype functions

        @@ -1733,11 +1610,11 @@

        Prototype functions

        • -
      • +
      • - § + §

        checkSource - internal function

        @@ -1751,11 +1628,11 @@

        Prototype functions

        • -
      • +
      • - § + §

        getData - internal function, invoked when a Cell wrapper is used as an entity’s pattern style

        @@ -1771,11 +1648,11 @@

        Prototype functions

        • -
      • +
      • - § + §

        updateArtefacts - passes the items argument object through to each of the Cell’s Groups for forwarding to their artefacts’ setDelta function

        @@ -1810,11 +1687,11 @@

        Prototype functions

        • -
      • +
      • - § + §

        cleanDimensionsAdditionalActions - overwrites mixin/position function:

          @@ -1843,11 +1720,11 @@

          Prototype functions

          -
        • +
        • - § + §

          DEPRECATED (because it is a really bad name) isComponent replaced by baseMatchesCanvasDimensions

          @@ -1915,11 +1792,11 @@

          Prototype functions

          • -
        • +
        • - § + §

          notifySubscriber - Overrides mixin/asset.js function

          @@ -1942,11 +1819,11 @@

          Prototype functions

          • -
        • +
        • - § + §

          subscribeAction - Overrides mixin/asset.js function

          @@ -1963,11 +1840,11 @@

          Prototype functions

          • -
        • +
        • - § + §

          installElement - internal function, used by the constructor

          @@ -1990,11 +1867,11 @@

          Prototype functions

          • -
        • +
        • - § + §

          updateControllerCells - internal function: ask the Cell’s Canvas controller to review/update its cells data

          @@ -2016,11 +1893,11 @@

          Prototype functions

          • -
        • +
        • - § + §

          clear

          @@ -2096,11 +1973,11 @@

          Prototype functions

          • -
        • +
        • - § + §

          compile

          @@ -2132,11 +2009,11 @@

          Prototype functions

          • -
        • +
        • - § + §

          show - Note that functionality here differs for base cells and other Cell wrappers

          @@ -2147,11 +2024,11 @@

          Prototype functions

          • -
        • +
        • - § + §

          get the destination cell’s canvas context

          @@ -2169,11 +2046,11 @@

          Prototype functions

          • -
        • +
        • - § + §

          Cannot draw to the destination canvas if either of its dimensions === 0

          @@ -2212,11 +2089,11 @@

          Prototype functions

          • -
        • +
        • - § + §

          copy the base canvas over to the display canvas. This copy operation ignores any scale, roll or position attributes set on the base cell, instead complying with the controller’s fit attribute requirements

          @@ -2242,11 +2119,11 @@

          Prototype functions

          • -
        • +
        • - § + §

          base must copy into display resized, centered, letterboxing if necessary, maintaining aspect ratio

          @@ -2276,11 +2153,11 @@

          Prototype functions

          • -
        • +
        • - § + §

          base must copy into display resized, centered, leaving no letterbox area, maintaining aspect ratio

          @@ -2310,11 +2187,11 @@

          Prototype functions

          • -
        • +
        • - § + §

          base must copy into display resized, distorting the aspect ratio as necessary

          @@ -2332,11 +2209,11 @@

          Prototype functions

          • -
        • +
        • - § + §

          base copies into display as-is, centred, maintaining aspect ratio

          @@ -2356,11 +2233,11 @@

          Prototype functions

          • -
        • +
        • - § + §

          Cell canvases are treated like entitys on the base canvas: they can be positioned, scaled and rotated. Positioning will respect lockTo; flipReverse and flipUpend; and can be pivoted to other artefacts, or follow a path entity, etc. If pivoted to the mouse, they will use the base canvas’s .here attribute, which takes into account differences between the base and display canvas dimensions.

          @@ -2389,11 +2266,11 @@

          Prototype functions

          • -
        • +
        • - § + §

          applyFilters - Internal function - add filters to the Cell’s current output.

          @@ -2419,11 +2296,11 @@

          Prototype functions

          • -
        • +
        • - § + §

          stashOutputAction - Internal function - stash the Cell’s current output. While this function can be called at any time, the simplest way to invoke it is to set the Cell’s stashOutput flag to true, which will then invoke this function at the end of the compile step of the Display cycle (after any filters have been applied to the cell display).

            @@ -2453,11 +2330,11 @@

            Prototype functions

            -
          • +
          • - § + §

            Keep the stashed image within bounds of the Cell’s dimensions.

            @@ -2485,11 +2362,11 @@

            Prototype functions

            • -
          • +
          • - § + §

            Get the imageData object, and stash it

            @@ -2503,11 +2380,11 @@

            Prototype functions

            • -
          • +
          • - § + §

            Get the dataUrl String, updating the stashed <img> element with it

            @@ -2551,11 +2428,11 @@

            Prototype functions

            • -
          • +
          • - § + §

            getHost - Internal function - get a reference to the Cell’s current host (where it will be stamping itself as part of the Display cycle).

              @@ -2581,11 +2458,11 @@

              Prototype functions

              -
            • +
            • - § + §

              updateBaseHere - Internal function - keeping the Canvas object’s ‘base’ Cell’s .here attribute up-to-date with accurate mouse/pointer/touch cursor data

              @@ -2681,11 +2558,11 @@

              Prototype functions

              • -
            • +
            • - § + §

              prepareStamp - Internal function - steps to be performed before the Cell stamps its visual contents onto a Canvas object’s base cell’s canvas. Will be invoked as part of the Display cycle ‘show’ functionality.

                @@ -2737,11 +2614,11 @@

                Prototype functions

                -
              • +
              • - § + §

                cleanPathObject - Calculate the Cell’s Path2D object

                @@ -2771,11 +2648,11 @@

                Prototype functions

                • -
              • +
              • - § + §

                updateHere - Internal function - get the Cell to update its .here information

                @@ -2860,11 +2737,11 @@

                Prototype functions

                • -
              • +
              • - § + §

                checkEngineScale DPR is detected in the core/events.js file, but mainly handled here

                @@ -2895,11 +2772,11 @@

                Prototype functions

                • -
              • +
              • - § + §

                Factory

                diff --git a/docs/source/factory/phrase.html b/docs/source/factory/phrase.html index b0b30a171..875ee7731 100644 --- a/docs/source/factory/phrase.html +++ b/docs/source/factory/phrase.html @@ -2511,53 +2511,18 @@

                Display cycle functionality

                let currentFont = defaultFont, currentFillStyle = defaultFillStyle, currentStrokeStyle = defaultStrokeStyle, - currentSpace = defaultSpace;
              - -
              • - - -
            • -
              - -
              - § -
              -

              const highlightStyle = (this.highlightStyle) ? makeStyle(this.highlightStyle) : false; -let highlightFlag = false;

              + currentSpace = defaultSpace; -
              - -
              • - - -
            • -
              - -
              - § -
              -

              const underlineStyle = (this.underlineStyle) ? makeStyle(this.underlineStyle) : false, - underlinePosition = this.underlinePosition; -let underlineFlag = false;

              + /* + const highlightStyle = (this.highlightStyle) ? makeStyle(this.highlightStyle) : false; -
              - -
              • - - -
            • -
              - -
              - § -
              -

              const overlineStyle = (this.overlineStyle) ? makeStyle(this.overlineStyle) : false, - overlinePosition = this.overlinePosition; -let overlineFlag = false;

              + const underlineStyle = (this.underlineStyle) ? makeStyle(this.underlineStyle) : false, + underlinePosition = this.underlinePosition; + + const overlineStyle = (this.overlineStyle) ? makeStyle(this.overlineStyle) : false, + overlinePosition = this.overlinePosition; + */ -
              - - 
                   if (this.highlightStyle) makeStyle(this.highlightStyle);
     if (this.underlineStyle) makeStyle(this.underlineStyle);
     if (this.overlineStyle) makeStyle(this.overlineStyle);
@@ -2570,11 +2535,11 @@ 
              Display cycle functionality
              • -
            • +
            • - § + §
              1. Create textGlyphs array
                2. @@ -2594,11 +2559,11 @@

                Display cycle functionality

                -
              2. +
              3. - § + §

                textGlyphs = (treatWordAsGlyph) ? mytext.split(SPACE) : mytext.split(ZERO_STR); fontArray.push(currentFont);

                @@ -2608,11 +2573,11 @@

                Display cycle functionality

                4. -
              4. +
              5. - § + §
                1. textPositions array will include an array of data for each glyph
                  2. @@ -2635,11 +2600,11 @@

                  Display cycle functionality

                  -
                2. +
                3. - § + §
                  1. Process the sectionStyles array to start populating the textPositions arrays
                    2. @@ -2743,11 +2708,11 @@

                    Display cycle functionality

                    -
                  2. +
                  3. - § + §

                    Setup textGlyphWidths array, populating it with current letterSpacing values

                    @@ -2759,11 +2724,11 @@

                    Display cycle functionality

                    4. -
                  4. +
                  5. - § + §

                    Finish populating textGlyphWidths

                    @@ -2779,11 +2744,11 @@

                    Display cycle functionality

                    6. -
                  6. +
                  7. - § + §
                    1. Calculate the text height value
                      2. @@ -2810,11 +2775,11 @@

                      Display cycle functionality

                      -
                    2. +
                    3. - § + §

                      browsers differ in the value thy return for this measurement

                      @@ -2832,11 +2797,11 @@

                      Display cycle functionality

                      4. -
                    4. +
                    5. - § + §
                      1. Calculate glyph width values
                        2. @@ -2884,11 +2849,11 @@

                        Display cycle functionality

                        -
                      2. +
                      3. - § + §

                        Calculate text line arrays

                        @@ -2910,11 +2875,11 @@

                        Display cycle functionality

                        4. -
                      4. +
                      5. - § + §

                        Need starts to be less than ends

                          @@ -2940,11 +2905,11 @@

                          Display cycle functionality

                          -
                        • +
                        • - § + §

                          Need to pick up the last (or only) line

                          @@ -2955,11 +2920,11 @@

                          Display cycle functionality

                          • -
                        • +
                        • - § + §

                          Pick up single line

                          @@ -2977,11 +2942,11 @@

                          Display cycle functionality

                          • -
                        • +
                        • - § + §

                          Final line of multiline text

                          @@ -3002,11 +2967,11 @@

                          Display cycle functionality

                          • -
                        • +
                        • - § + §

                          … And complete the population of data for highlight, overline, underline

                          @@ -3024,11 +2989,11 @@

                          Display cycle functionality

                          • -
                        • +
                        • - § + §
                          1. Calculate localHeight
                            2. @@ -3050,11 +3015,11 @@

                            Display cycle functionality

                            -
                          2. +
                          3. - § + §

                            Handle path positioning (which we’ll assume will need to be done for every display cycle) separately during stamping

                            @@ -3065,11 +3030,11 @@

                            Display cycle functionality

                            4. -
                          4. +
                          5. - § + §
                            1. We should now be in a position where we can calculate each glyph’s startXY values
                              2. @@ -3083,11 +3048,11 @@

                              Display cycle functionality

                              -
                            2. +
                            3. - § + §

                              Scenario 1: justify === 'full'

                              @@ -3128,11 +3093,11 @@

                              Display cycle functionality

                              4. -
                            4. +
                            5. - § + §

                              Scenario 2: regular text - justify === 'left', or 'centre', or 'right'

                              @@ -3156,11 +3121,11 @@

                              Display cycle functionality

                              6. -
                            6. +
                            7. - § + §

                              BUG: There’s an issue here which causes the function to fail when treatWordAsGlyph flag is set to true. Affects non-path-referencing Phrase entitys. This test to see if item exists is a temporary fix.

                                @@ -3188,11 +3153,11 @@

                                Display cycle functionality

                                -
                              • +
                              • - § + §
                                1. Clean up and exit
                                  2. @@ -3245,11 +3210,11 @@

                                  Display cycle functionality

                                  -
                                2. +
                                3. - § + §
                                  Stamping the entity onto a Cell wrapper <canvas> element
                                  @@ -3258,11 +3223,11 @@
                                  Stamping the ent
                                  4. -
                                4. +
                                5. - § + §

                                  regularStamp - overwrites the mixin/entity.js function

                                  @@ -3283,11 +3248,11 @@
                                  Stamping the ent
                                  6. -
                                6. +
                                7. - § + §

                                  Scrawl-canvas clips canvases to the Phrase’s hit area

                                    @@ -3309,11 +3274,11 @@
                                    Stamping the ent -
                                  • +
                                  • - § + §

                                    Needs investigating: for some reason when applying a filter to a phrase entity the pool cell gets its baseline reset to default, which displaces the filter effect upwards. These lines fix the immediate issue, but don’t solve the deeper mystery.

                                    @@ -3334,11 +3299,11 @@
                                    Stamping the ent
                                    • -
                                  • +
                                  • - § + §

                                    TODO: is this still needed?

                                    @@ -3369,11 +3334,11 @@
                                    Stamping the ent
                                    • -
                                  • +
                                  • - § + §

                                    TODO: is this still needed?

                                    @@ -3392,11 +3357,11 @@
                                    Stamping the ent
                                    • -
                                  • +
                                  • - § + §

                                    … See above

                                    @@ -3420,11 +3385,11 @@
                                    Stamping the ent
                                    • -
                                  • +
                                  • - § + §

                                    calculateGlyphPathPositions - internal helper function called by regularStamp

                                    @@ -3450,11 +3415,11 @@
                                    Stamping the ent
                                    • -
                                  • +
                                  • - § + §

                                    textPathPosition Array indexes [ 0-font - font definition, or null @@ -3514,11 +3479,11 @@

                                    Stamping the ent
                                    • -
                                  • +
                                  • - § + §

                                    preStamper - internal helper function called by regularStamp

                                    @@ -3546,11 +3511,11 @@
                                    Stamping the ent
                                    • -
                                  • +
                                  • - § + §

                                    data[0] - glyph data[1] - xpos @@ -3588,11 +3553,11 @@

                                    Stamping the ent
                                    • -
                                  • +
                                  • - § + §

                                    stamper - object holding stamp method functions - functions called by regularStamp

                                    @@ -3603,11 +3568,11 @@
                                    Stamping the ent
                                    • -
                                  • +
                                  • - § + §

                                    stamper.draw

                                    @@ -3621,11 +3586,11 @@
                                    Stamping the ent
                                    • -
                                  • +
                                  • - § + §

                                    stamper.fill

                                    @@ -3639,11 +3604,11 @@
                                    Stamping the ent
                                    • -
                                  • +
                                  • - § + §

                                    stamper.drawAndFill

                                    @@ -3662,11 +3627,11 @@
                                    Stamping the ent
                                    • -
                                  • +
                                  • - § + §

                                    stamper.fillAndDraw

                                    @@ -3685,11 +3650,11 @@
                                    Stamping the ent
                                    • -
                                  • +
                                  • - § + §

                                    stamper.drawThenFill

                                    @@ -3704,11 +3669,11 @@
                                    Stamping the ent
                                    • -
                                  • +
                                  • - § + §

                                    stamper.fillThenDraw

                                    @@ -3723,11 +3688,11 @@
                                    Stamping the ent
                                    • -
                                  • +
                                  • - § + §

                                    stamper.clear

                                    @@ -3745,11 +3710,11 @@
                                    Stamping the ent
                                    • -
                                  • +
                                  • - § + §

                                    drawBoundingBox - internal helper function called by regularStamp

                                    @@ -3772,11 +3737,11 @@
                                    Stamping the ent
                                    • -
                                  • +
                                  • - § + §

                                    performRotation - internal helper function called by regularStamp

                                      @@ -3801,11 +3766,11 @@
                                      Stamping the ent -
                                    • +
                                    • - § + §

                                      Factory

                                      scrawl.makePhrase({