pxt-common-packages 9.5.1 → 9.5.2

package/libs/sprite-scaling/docs/reference/sprites/scaling/scale-by-percent.md

@@ -0,0 +1,77 @@
+# scale By Percent
+
+Scale a sprite by a percentage of its current size in a direction from an anchor point.
+
+```sig
+scaling.scaleByPercent(null, 50, ScaleDirection.Uniformly, ScaleAnchor.Middle)
+```
+
+A sprite can scale by a percentage of its original size in a direction from an anchor point. The scaling can be in just one direction or the sprite can scale uniformly.
+
+## Uniform scaling
+
+When the scaling **direction** is set to `uniformly`, the sprite is scaled so that the new size will have both the width and height changed by the same percentage **value**. If a sprite's current size is `64` x `32` and it's uniformly scaled by `50` percent, the new width is `32` and the new height is `16`.
+
+## Parameters
+
+* **sprite**: the sprite to scale by a percentage of its original size.
+* **value**: the [number](/types/number) that is the percentage to scale the sprite by.
+* **direction**: the direction to scale in:
+>* `horizontally`
+>* `vertically`
+>* `uniformly`
+* **anchor**: an anchor point to scale the sprite from:
+>* `middle`
+>* `top`
+>* `left`
+>* `right`
+>* `bottom`
+>* `top left`
+>* `top right`
+>* `bottom right`
+>* `bottom left`
+
+## Example #example
+
+### Scaling tester #ex1
+
+Make a program to test sprite scaling a sprite by expanding and shrinking it uniformly. Use the controller buttons to increase and decrease the scale of a sprite  by a percentage of its current size.
+
+```blocks
+controller.B.onEvent(ControllerButtonEvent.Pressed, function () {
+    scaling.scaleByPercent(mySprite, -50, ScaleDirection.Uniformly, ScaleAnchor.Middle)
+    info.setScore(mySprite.width)
+})
+controller.A.onEvent(ControllerButtonEvent.Pressed, function () {
+    scaling.scaleByPercent(mySprite, 50, ScaleDirection.Uniformly, ScaleAnchor.Middle)
+    info.setScore(mySprite.width)
+})
+let mySprite: Sprite = null
+mySprite = sprites.create(img`
+    22222222222222222222222222222222
+    25557777777777777777777777775552
+    25577777777777777777777777777552
+    25777777777777777777777777777752
+    27777777777777777777777777777772
+    27777777777777777777777777777772
+    27777777777777777777777777777772
+    27777777777777888877777777777772
+    27777777777777888877777777777772
+    27777777777777777777777777777772
+    27777777777777777777777777777772
+    27777777777777777777777777777772
+    25777777777777777777777777777752
+    25577777777777777777777777777552
+    25557777777777777777777777775552
+    22222222222222222222222222222222
+    `, SpriteKind.Player)
+info.setScore(mySprite.width)
+```
+
+## See also #seealso
+
+[scale to percent](/reference/sprites/scaling/scale-to-percent)
+
+```package
+sprite-scaling
+```

package/libs/sprite-scaling/docs/reference/sprites/scaling/scale-by-pixels.md

@@ -0,0 +1,144 @@
+# scale by Pixels
+
+Scale a sprite by a number of pixels in a direction from an anchor point.
+
+```sig
+scaling.scaleByPixels(null, 1, ScaleDirection.Uniformly, ScaleAnchor.Middle)
+```
+
+A sprite can scale to a number of pixels in a direction from an anchor point. The scaling can be in just in the direction chosen, or the sprite can scale proportionally in the other direction too. 
+
+## Proportional scaling
+
+If the scale direction is `vertically` or `horizontally` but **proportional** is set to `false`, the sprite will scale to the number of pixels given in **value** only in the chosen direction. The sprite will expand in height but the width will stay the same or the sprite will expand in width but the height will stat the same.
+
+If the scaling direction is `vertically` and the `proportional` parameter is `true`, the width will also expand by the same ratio of change as the height. With this setting, expanding a `32` x `16` sprite in the vertical direction by `16` pixels will also expand the width by `32`. The same ratio scaling will happen for the height if the direction is `horizontally`.
+
+## Uniform scaling
+
+When the scaling **direction** is set to `uniformly`, the sprite is scaled so that the new size will have both the width and height change by the same amount. If a sprite's current size is `64` x `16` and it's uniformly scaled by `64`, the new width is `128` and the new height is `80`.
+
+## Parameters
+
+* **sprite**: the sprite to scale by a pixel amount.
+* **value**: the [number](/types/number) of pixels to scale the sprite by.
+* **direction**: the direction to scale in:
+>* `horizontally`
+>* `vertically`
+>* `uniformly`
+* **anchor**: an anchor point to scale the sprite from:
+>* `middle`
+>* `top`
+>* `left`
+>* `right`
+>* `bottom`
+>* `top left`
+>* `top right`
+>* `bottom right`
+>* `bottom left`
+* **proportional**: a [boolean](/types/boolean) value that when `true` will scale the sprite proportionally. If `false`, the sprite will only scale by **direction**. This parameter has no effect when **direction** is set to `uniformly`.
+
+## Example #example
+
+### Scaling tester #ex1
+
+Make a program to test sprite scaling in both directions for expanding and shrinking. Use the controller buttons to increase and decrease the scale. Use buttons to turn **proportional** to `true` or `false`.
+
+```blocks
+controller.up.onEvent(ControllerButtonEvent.Pressed, function () {
+    scaling.scaleByPixels(mySprite, pixelMin, ScaleDirection.Vertically, ScaleAnchor.Middle, proportion)
+})
+controller.B.onEvent(ControllerButtonEvent.Pressed, function () {
+    proportion = false
+    game.showLongText("Proportional = FALSE", DialogLayout.Bottom)
+})
+controller.A.onEvent(ControllerButtonEvent.Pressed, function () {
+    proportion = true
+    game.showLongText("Proportional = TRUE", DialogLayout.Bottom)
+})
+controller.left.onEvent(ControllerButtonEvent.Pressed, function () {
+    if (mySprite.width > pixelMin) {
+        scaling.scaleByPixels(mySprite, pixelMin * -1, ScaleDirection.Horizontally, ScaleAnchor.Middle, proportion)
+    }
+})
+controller.right.onEvent(ControllerButtonEvent.Pressed, function () {
+    scaling.scaleByPixels(mySprite, pixelMin, ScaleDirection.Horizontally, ScaleAnchor.Middle, proportion)
+})
+controller.down.onEvent(ControllerButtonEvent.Pressed, function () {
+    if (mySprite.width > pixelMin) {
+        scaling.scaleByPixels(mySprite, pixelMin * -1, ScaleDirection.Vertically, ScaleAnchor.Middle, proportion)
+    }
+})
+let proportion = false
+let pixelMin = 0
+let mySprite: Sprite = null
+mySprite = sprites.create(img`
+    2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 
+    2 5 5 5 7 7 7 7 7 7 7 7 5 5 5 2 
+    2 5 5 7 7 7 7 7 7 7 7 7 7 5 5 2 
+    2 5 7 7 7 7 7 7 7 7 7 7 7 7 5 2 
+    2 7 7 7 7 7 7 7 7 7 7 7 7 7 7 2 
+    2 7 7 7 7 7 7 7 7 7 7 7 7 7 7 2 
+    2 7 7 7 7 7 7 7 7 7 7 7 7 7 7 2 
+    2 7 7 7 7 7 7 8 8 7 7 7 7 7 7 2 
+    2 7 7 7 7 7 7 8 8 7 7 7 7 7 7 2 
+    2 7 7 7 7 7 7 7 7 7 7 7 7 7 7 2 
+    2 7 7 7 7 7 7 7 7 7 7 7 7 7 7 2 
+    2 7 7 7 7 7 7 7 7 7 7 7 7 7 7 2 
+    2 5 7 7 7 7 7 7 7 7 7 7 7 7 5 2 
+    2 5 5 7 7 7 7 7 7 7 7 7 7 5 5 2 
+    2 5 5 5 7 7 7 7 7 7 7 7 5 5 5 2 
+    2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 
+    `, SpriteKind.Player)
+pixelMin = mySprite.width
+let pixelMax = pixelMin * 5
+game.showLongText("Proportional = FALSE", DialogLayout.Bottom)
+```
+
+### Uniformity tester #ex2
+
+Test uniformly scaling a nonsquare sprite. Use the controller buttons to change the increased or decreased scale.
+
+```blocks
+controller.up.onEvent(ControllerButtonEvent.Pressed, function () {
+    scaling.scaleByPixels(mySprite, pixelMax, ScaleDirection.Uniformly, ScaleAnchor.Middle)
+    info.setScore(mySprite.width)
+})
+controller.down.onEvent(ControllerButtonEvent.Pressed, function () {
+    if (my)
+    scaling.scaleByPixels(mySprite, pixelMin * -1, ScaleDirection.Uniformly, ScaleAnchor.Middle)
+    info.setScore(mySprite.width)
+})
+let pixelMax = 0
+let pixelMin = 0
+let mySprite: Sprite = null
+mySprite = sprites.create(img`
+    22222222222222222222222222222222
+    25557777777777777777777777775552
+    25577777777777777777777777777552
+    25777777777777777777777777777752
+    27777777777777777777777777777772
+    27777777777777777777777777777772
+    27777777777777777777777777777772
+    27777777777777888877777777777772
+    27777777777777888877777777777772
+    27777777777777777777777777777772
+    27777777777777777777777777777772
+    27777777777777777777777777777772
+    25777777777777777777777777777752
+    25577777777777777777777777777552
+    25557777777777777777777777775552
+    22222222222222222222222222222222
+    `, SpriteKind.Player)
+pixelMin = mySprite.height
+pixelMax = pixelMin * 5
+info.setScore(mySprite.width)
+```
+
+## See also #seealso
+
+[scale by pixels](/reference/sprites/scaling/scale-by-pixels)
+
+```package
+sprite-scaling
+```

package/libs/sprite-scaling/docs/reference/sprites/scaling/scale-to-percent.md

@@ -0,0 +1,83 @@
+# scale To Percent
+
+Scale a sprite to a percentage of its original size in a direction from an anchor point.
+
+```sig
+scaling.scaleToPercent(null, 100, ScaleDirection.Uniformly, ScaleAnchor.Middle)
+```
+
+A sprite can scale to a percentage of its original size in a direction from an anchor point. The scaling can be in just one direction or the sprite can scale uniformly.
+
+## Uniform scaling
+
+When the scaling **direction** is set to `uniformly`, the sprite is scaled so that the new size will have both the width and height changed by the same percentage **value**. If a sprite's original size is `64` x `32` and it's uniformly scaled to `50` percent, the new width is `32` and the new height is `16`.
+
+## Parameters
+
+* **sprite**: the sprite to scale to a percentage of its original size.
+* **value**: the [number](/types/number) that is the percentage to scale the sprite to.
+* **direction**: the direction to scale in:
+>* `horizontally`
+>* `vertically`
+>* `uniformly`
+* **anchor**: an anchor point to scale the sprite from:
+>* `middle`
+>* `top`
+>* `left`
+>* `right`
+>* `bottom`
+>* `top left`
+>* `top right`
+>* `bottom right`
+>* `bottom left`
+
+## Example #example
+
+### Scaling tester #ex1
+
+Make a program to test sprite scaling in both directions for expanding and shrinking. Use the controller buttons to increase and decrease the scale to a percentage of the original sprite by direction. Use button `A` to set the pixel back to its original size.
+
+```blocks
+controller.A.onEvent(ControllerButtonEvent.Pressed, function () {
+    scaling.scaleToPercent(mySprite, 100, ScaleDirection.Uniformly, ScaleAnchor.Middle)
+})
+controller.up.onEvent(ControllerButtonEvent.Pressed, function () {
+    scaling.scaleToPercent(mySprite, 200, ScaleDirection.Vertically, ScaleAnchor.Middle)
+})
+controller.left.onEvent(ControllerButtonEvent.Pressed, function () {
+    scaling.scaleToPercent(mySprite, 50, ScaleDirection.Horizontally, ScaleAnchor.Middle)
+})
+controller.right.onEvent(ControllerButtonEvent.Pressed, function () {
+    scaling.scaleToPercent(mySprite, 200, ScaleDirection.Horizontally, ScaleAnchor.Middle)
+})
+controller.down.onEvent(ControllerButtonEvent.Pressed, function () {
+    scaling.scaleToPercent(mySprite, 50, ScaleDirection.Vertically, ScaleAnchor.Middle)
+})
+let mySprite: Sprite = null
+mySprite = sprites.create(img`
+    22222222222222222222222222222222
+    25557777777777777777777777775552
+    25577777777777777777777777777552
+    25777777777777777777777777777752
+    27777777777777777777777777777772
+    27777777777777777777777777777772
+    27777777777777777777777777777772
+    27777777777777888877777777777772
+    27777777777777888877777777777772
+    27777777777777777777777777777772
+    27777777777777777777777777777772
+    27777777777777777777777777777772
+    25777777777777777777777777777752
+    25577777777777777777777777777552
+    25557777777777777777777777775552
+    22222222222222222222222222222222
+    `, SpriteKind.Player)
+```
+
+## See also #seealso
+
+[scale by percent](/reference/sprites/scaling/scale-by-percent)
+
+```package
+sprite-scaling
+```

package/libs/sprite-scaling/docs/reference/sprites/scaling/scale-to-pixels.md

@@ -0,0 +1,140 @@
+# scale To Pixels
+
+Scale a sprite to a number of pixels in a direction from an anchor point.
+
+```sig
+scaling.scaleToPixels(null, 1, ScaleDirection.Uniformly, ScaleAnchor.Middle)
+```
+
+A sprite can scale to a number of pixels in a direction from an anchor point. The scaling can be in just in the direction chosen, or the sprite can scale proportionally in the other direction too. 
+
+## Proportional scaling
+
+If the scale direction is `vertically` or `horizontally` but **proportional** is set to `false`, the sprite will scale to the number of pixels given in **value** only in the chosen direction. The sprite will expand in height but the width will stay the same or the sprite will expand in width but the height will stat the same.
+
+If the scaling direction is `vertically` and the `proportional` parameter is `true`, the width will also expand by the same ratio of change as the height. With this setting, expanding a `32` x `16` sprite in the vertical direction to `32` pixels will also expand the width to `64`. The same ratio scaling will happen for the height if the direction is `horizontally`.
+
+## Uniform scaling
+
+When the scaling **direction** is set to `uniformly`, the sprite is scaled so that te new size will have both the width and height the same. If a sprite's current size is `64` x `16` and it's uniformly scaled to `128`, the new width and height will both be `128`.
+
+## Parameters
+
+* **sprite**: the sprite to scale to a pixel amount.
+* **value**: the [number](/types/number) of pixels to scale the sprite to.
+* **direction**: the direction to scale in:
+>* `horizontally`
+>* `vertically`
+>* `uniformly`
+* **anchor**: an anchor point to scale the sprite from:
+>* `middle`
+>* `top`
+>* `left`
+>* `right`
+>* `bottom`
+>* `top left`
+>* `top right`
+>* `bottom right`
+>* `bottom left`
+* **proportional**: a [boolean](/types/boolean) value that when `true` will scale the sprite proportionally. If `false`, the sprite will only scale by **direction**. This parameter has no effect when **direction** is set to `uniformly`.
+
+## Example #example
+
+### Scaling tester #ex1
+
+Make a program to test sprite scaling in both directions for expanding and shrinking. Use the controller buttons to increase and decrease the scale. Use buttons to turn **proportional** to `true` or `false`.
+
+```blocks
+controller.B.onEvent(ControllerButtonEvent.Pressed, function () {
+    proportion = false
+    game.showLongText("Proportional = FALSE", DialogLayout.Bottom)
+})
+controller.A.onEvent(ControllerButtonEvent.Pressed, function () {
+    proportion = true
+    game.showLongText("Proportional = TRUE", DialogLayout.Bottom)
+})
+controller.left.onEvent(ControllerButtonEvent.Pressed, function () {
+    scaling.scaleToPixels(mySprite, pixelMin, ScaleDirection.Horizontally, ScaleAnchor.Middle, proportion)
+})
+controller.right.onEvent(ControllerButtonEvent.Pressed, function () {
+    scaling.scaleToPixels(mySprite, pixelMax, ScaleDirection.Horizontally, ScaleAnchor.Middle, proportion)
+})
+controller.up.onEvent(ControllerButtonEvent.Pressed, function () {
+    scaling.scaleToPixels(mySprite, pixelMax, ScaleDirection.Vertically, ScaleAnchor.Middle, proportion)
+})
+controller.down.onEvent(ControllerButtonEvent.Pressed, function () {
+    scaling.scaleToPixels(mySprite, pixelMin, ScaleDirection.Vertically, ScaleAnchor.Middle, proportion)
+})
+let proportion = false
+let pixelMax = 0
+let pixelMin = 0
+let mySprite: Sprite = null
+mySprite = sprites.create(img`
+    2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 
+    2 5 5 5 7 7 7 7 7 7 7 7 5 5 5 2 
+    2 5 5 7 7 7 7 7 7 7 7 7 7 5 5 2 
+    2 5 7 7 7 7 7 7 7 7 7 7 7 7 5 2 
+    2 7 7 7 7 7 7 7 7 7 7 7 7 7 7 2 
+    2 7 7 7 7 7 7 7 7 7 7 7 7 7 7 2 
+    2 7 7 7 7 7 7 7 7 7 7 7 7 7 7 2 
+    2 7 7 7 7 7 7 8 8 7 7 7 7 7 7 2 
+    2 7 7 7 7 7 7 8 8 7 7 7 7 7 7 2 
+    2 7 7 7 7 7 7 7 7 7 7 7 7 7 7 2 
+    2 7 7 7 7 7 7 7 7 7 7 7 7 7 7 2 
+    2 7 7 7 7 7 7 7 7 7 7 7 7 7 7 2 
+    2 5 7 7 7 7 7 7 7 7 7 7 7 7 5 2 
+    2 5 5 7 7 7 7 7 7 7 7 7 7 5 5 2 
+    2 5 5 5 7 7 7 7 7 7 7 7 5 5 5 2 
+    2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 2 
+    `, SpriteKind.Player)
+pixelMin = mySprite.width
+pixelMax = pixelMin * 5
+game.showLongText("Proportional = FALSE", DialogLayout.Bottom)
+```
+
+### Uniformity tester #ex2
+
+Test uniformly scaling a nonsquare sprite. Use the `up` and `down` controller buttons to increase and decrease the scale.
+
+```blocks
+controller.up.onEvent(ControllerButtonEvent.Pressed, function () {
+    scaling.scaleToPixels(mySprite, pixelMax, ScaleDirection.Uniformly, ScaleAnchor.Middle)
+    info.setScore(mySprite.width)
+})
+controller.down.onEvent(ControllerButtonEvent.Pressed, function () {
+    scaling.scaleToPixels(mySprite, pixelMin, ScaleDirection.Uniformly, ScaleAnchor.Middle)
+    info.setScore(mySprite.width)
+})
+let pixelMax = 0
+let pixelMin = 0
+let mySprite: Sprite = null
+mySprite = sprites.create(img`
+    22222222222222222222222222222222
+    25557777777777777777777777775552
+    25577777777777777777777777777552
+    25777777777777777777777777777752
+    27777777777777777777777777777772
+    27777777777777777777777777777772
+    27777777777777777777777777777772
+    27777777777777888877777777777772
+    27777777777777888877777777777772
+    27777777777777777777777777777772
+    27777777777777777777777777777772
+    27777777777777777777777777777772
+    25777777777777777777777777777752
+    25577777777777777777777777777552
+    25557777777777777777777777775552
+    22222222222222222222222222222222
+    `, SpriteKind.Player)
+pixelMin = mySprite.height
+pixelMax = pixelMin * 5
+info.setScore(mySprite.width)
+```
+
+## See also #seealso
+
+[scale by pixels](/reference/sprites/scaling/scale-to-pixels)
+
+```package
+sprite-scaling
+```

package/libs/sprite-scaling/scaling.ts

@@ -1,4 +1,4 @@
-//% color="#95078E" weight=99 icon="\u2195" block="Sprite Scaling"
+//% color="#95078E" weight=99 icon="\uf338"
 namespace scaling {
     //% blockId=sprite_scale_to_percent_ex
     //% block="set $sprite=variables_get(mySprite) scale to $value percent $direction anchor $anchor"
@@ -7,7 +7,7 @@ namespace scaling {
     //% value.defl=150
     //% direction.defl=ScaleDirection.Uniformly
     //% anchor.defl=ScaleAnchor.Middle
-    //% help=sprites/sprite-scaling/scale
+    //% help=sprites/scaling/scale-to-percent
     export function scaleToPercent(sprite: Sprite, value: number, direction?: ScaleDirection, anchor?: ScaleAnchor): void {
         value /= 100;
         direction = direction || ScaleDirection.Uniformly;
@@ -29,7 +29,7 @@ namespace scaling {
     //% value.defl=50
     //% direction.defl=ScaleDirection.Uniformly
     //% anchor.defl=ScaleAnchor.Middle
-    //% help=sprites/sprite-scaling/scale
+    //% help=sprites/scaling/scale-by-percent
     export function scaleByPercent(sprite: Sprite, value: number, direction?: ScaleDirection, anchor?: ScaleAnchor): void {
         value /= 100;
         direction = direction || ScaleDirection.Uniformly;
@@ -52,7 +52,7 @@ namespace scaling {
     //% direction.defl=ScaleDirection.Horizontally
     //% anchor.defl=ScaleAnchor.Middle
     //% proportional.defl=0
-    //% help=sprites/sprite-scaling/scale
+    //% help=sprites/scaling/scale-to-pixels
     export function scaleToPixels(sprite: Sprite, value: number, direction?: ScaleDirection, anchor?: ScaleAnchor, proportional?: boolean): void {
         direction = direction || ScaleDirection.Horizontally;
         anchor = anchor || ScaleAnchor.Middle;
@@ -85,7 +85,7 @@ namespace scaling {
     //% direction.defl=ScaleDirection.Horizontally
     //% anchor.defl=ScaleAnchor.Middle
     //% proportional.defl=0
-    //% help=sprites/sprite-scaling/scale
+    //% help=sprites/scaling/scale-by-pixels
     export function scaleByPixels(sprite: Sprite, value: number, direction?: ScaleDirection, anchor?: ScaleAnchor, proportional?: boolean): void {
         direction = direction || ScaleDirection.Horizontally;
         anchor = anchor || ScaleAnchor.Middle;