diff --git a/CHANGELOG.md b/CHANGELOG.md index ed527b0..5c80d0e 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -6,6 +6,24 @@ All notable changes to this project are documented here. The format follows ## [Unreleased] +### Added + +- **A picture may be drawn in a shape.** `mask` on `::image` names the shape the picture is + drawn in: `circle`, `ellipse`, `roundrect`, `triangle`, `diamond`, `hexagon`, `chevron`, + `arrow`, `star`, `heart`, `teardrop`, `cloud`, `moon`, `donut`, `frame` and `plaque`. + + The shape is the picture's own rather than a frame drawn around it: the file writes it as + the geometry of the picture, which is what PowerPoint writes for a picture cropped to a + shape — so a picture masked in a deck is a picture cropped to that shape in PowerPoint, and + can be cropped to another one there. + + The mask is a shape and not a size: the picture keeps the box it was given, and the shape + is drawn in it. A `circle` and an `ellipse` are the same shape, and the picture's own + proportions decide which of the two it looks like. + + It needs a PHPPresentation that can write it, which the patch this library carries now + does. + ### Fixed - **A deck read back into Markdown carries no title it never had.** PHPPresentation gives diff --git a/README.md b/README.md index 068ddad..2600bfe 100644 --- a/README.md +++ b/README.md @@ -67,6 +67,7 @@ The patch adds these to PHPPresentation: | `Fill::getGradientStops` | the writer and the reader | the stops a gradient is painted with, so that a gradient may have a colour in the middle of it | | `GradientStop::getPosition` | the writer and the reader | where one stop of a gradient sits, so that the stops need not be spread evenly | | `BackgroundGradient::getFill` | the writer and the reader | the gradient a background is painted with, which is the same fill a shape is painted with | +| `AbstractDrawingAdapter::setGeometry` | the writer | the shape a picture is drawn in, which is what a picture cropped to a shape is written with | The writer is the direction that writes a `.pptx`; the reader is the direction that takes one apart, and it reads a deck through the patched `PowerPoint2007` reader. The check asks for @@ -1362,6 +1363,7 @@ is refused rather than one of them being dropped. | `border-radius` | `::roundrect` only | in pixels | | `label` | the ten ink shapes | the shape's own text — see [Text inside a shape](#text-inside-a-shape) | | `src`, `alt`, `fit` | `::image` | | +| `mask` | `::image` only | the shape the picture is drawn in — see [A picture in a shape](#a-picture-in-a-shape) | | `color`, `font-size`, `font-family`, `align`, `vertical-align`, `padding` | `::content`, `::slide-number` | | | `of` | `::slide-number` only | the number of the deck after the number of the slide | | `shadow-color`, `shadow-distance`, `shadow-blur`, `shadow-direction`, `shadow-alpha` | all thirteen | see [A shadow](#a-shadow) | @@ -1490,6 +1492,59 @@ A shadow is on the shape, not on the words inside it: a `label` takes the shadow sits in, and a `:::content` block casts one from its own border. `::image` casts one too — a `p:pic` carries an effect list of its own. +#### A panel over a picture + +A shape painted with a colour and an alpha is seen through the page. `alpha` is one percentage +for the whole shape, written into the colour of the fill and of the stroke, so the shape is seen +slightly through the page rather than a fill and an outline that disagree about how solid they +are. + +That is what gives words over a picture something to be read against. The picture, a panel over +it and the words over that are three shapes, and the order they are written in is the order they +are drawn in: + +```markdown +::image{src="landscape.webp" left=0 top=0 width=100% height=100% fit=stretch layer=back} +::rectangle{left=0 top=0 width=100% height=100% fill=lt1 alpha=75 layer=back} +:::content{left=8% top=38% width=84% height=24% color=dk1} +Words on a panel. +::: +``` + +The library knows the colour of the panel and the colour of the words, and not what the +photograph is made of — so how readable the words are is a thing to look at rather than a thing +the library can promise. + +**A box behind the words** is the same shape with an opaque fill, and only the words are on it: +the picture around the box keeps its own colours. `fill=lt1` alone would be opaque as well — a +colour without an alpha is whole — so `alpha=100` says it rather than leaving it to be read. + +```markdown +::image{src="landscape.webp" left=0 top=0 width=100% height=100% fit=stretch layer=back} +:::content{left=7% top=28% width=58% height=34% fill=lt1 alpha=100 padding=16} +Words in a box. +::: +``` + +#### A picture in a shape + +A picture is drawn in a rectangle, and a picture can be drawn in another shape instead. The shape +is the picture's own rather than a frame drawn around it: the file writes it as the geometry of +the picture, which is what PowerPoint writes for a picture cropped to a shape. + +```markdown +::image{src="logo.png" mask=circle left=10% top=20% width=30% height=30% fit=contain} +``` + +The masks are `circle`, `ellipse`, `roundrect`, `triangle`, `diamond`, `hexagon`, `chevron`, +`arrow`, `star`, `heart`, `teardrop`, `cloud`, `moon`, `donut`, `frame` and `plaque` — and a name +outside them is refused with the list of what would have worked, the way every other name +outside a vocabulary is. + +The mask is a shape and not a size: the picture keeps the box it was given, and the shape is +drawn in it. A `circle` and an `ellipse` are the same shape, and the picture's own proportions +decide which of the two it looks like. + #### What is refused, and how it reads An attribute a directive does not read is refused rather than ignored, and that is the whole of @@ -1533,7 +1588,7 @@ Slide 1 gives "rectangle" a fill of "chartreuse". A colour is either no colour a Slide 1 gives "rectangle" a rotate of "22.5". A rotation is a whole number of degrees, and turns the shape about the middle of its box: rotate=45, rotate=-30, rotate=45deg. -Slide 1 gives "image" an attribute "fill", which it does not read. The attributes are: alt, anchor, bleed, fit, height, layer, left, rotate, shadow-alpha, shadow-blur, shadow-color, shadow-direction, shadow-distance, src, top, width. +Slide 1 gives "image" an attribute "fill", which it does not read. The attributes are: alt, anchor, bleed, fit, height, layer, left, mask, rotate, shadow-alpha, shadow-blur, shadow-color, shadow-direction, shadow-distance, src, top, width. Slide 1 gives "rectangle" a left of "10%,". Attributes are separated by a space, not a comma. A length is a number, a number of pixels, a number of points, or — for a position or a size — a percentage of the slide: left=40%, left=320, font-size=24pt. ``` diff --git a/composer.json b/composer.json index 804d2db..9a63d0a 100644 --- a/composer.json +++ b/composer.json @@ -39,9 +39,9 @@ "patches": { "phpoffice/phppresentation": [ { - "description": "PHPPresentation 1.2.0 brought up to upstream's master, with the fixes that give a picture the path, the bytes and the name it was read from, that find the folder of a part of a package with the slashes of the package, that write a chart series in the order the schema names it, that write the data points of a series and the fill of the series itself, and that give a category axis a tick label skip of its own, and that write a gradient of more than two stops and a background painted with a gradient", - "url": "https://raw.githubusercontent.com/markdown-office/PHPPresentation/c6de3987c9019a1d60876b4aa1964f15e1abc132/patches/phpoffice-phppresentation-1.2.0-to-master.patch", - "sha256": "bb422f73ad2211948835cf9c5f1aed7ec993c3e4595d6e11bd9836e2f9a5f8d5" + "description": "PHPPresentation 1.2.0 brought up to upstream's master, with the fixes that give a picture the path, the bytes and the name it was read from, that find the folder of a part of a package with the slashes of the package, that write a chart series in the order the schema names it, that write the data points of a series and the fill of the series itself, and that give a category axis a tick label skip of its own, and that write a gradient of more than two stops and a background painted with a gradient, and that give a picture the geometry it is drawn in", + "url": "https://raw.githubusercontent.com/markdown-office/PHPPresentation/a95169ca0d678cd2b4cd0fd6ec1e072b83d421cd/patches/phpoffice-phppresentation-1.2.0-to-master.patch", + "sha256": "4665f3095852e58b915f48f744125d6d700f477ef0daff3e0eb6757122484f01" } ] } diff --git a/examples/README.md b/examples/README.md index b430692..c037c79 100644 --- a/examples/README.md +++ b/examples/README.md @@ -37,6 +37,8 @@ quietly. The profile and the scratch script go to the temporary directory, so | `17-corporate-template.md` | `17-corporate-template.pptx` | A whole corporate template: a theme of the company's own, a brand mark in two colours — one for a light page and one for a dark one — and the furniture of a deck written once and named by every slide that wants it. Eight slides of the kinds a company deck is made of: a cover, an agenda, a headline, two columns with a chart, a quote, a table, a divider and a closing. The company is invented | | `19-gradient-background.md` | `19-gradient-background.pptx` | A gradient on a shape — two stops, three stops with the middle one at half, a radial one, and an angle of 0° — a background painted with a colour, with a gradient and with a radial gradient, a slide that names the theme's values for itself, and a template that carries settings of its own | | `20-deck-settings.md` | `20-deck-settings.pptx` | The settings of the deck: a page and an ink every slide of the deck is drawn with, and the two slides that name a setting of their own — one that wins over the deck's, and one that leaves the deck's other settings standing | +| `21-masked-images.md` | `21-masked-images.pptx` | Pictures drawn in a shape rather than in a rectangle: six masks on one picture — a circle, a hexagon, a star, a heart, a teardrop and a rounded rectangle — and what the mask is and is not | +| `22-legible-over-image.md` | `22-legible-over-image.pptx` | Words over a picture, three times: with nothing between them and the photograph, with a translucent panel over the whole picture, and in an opaque box behind the words alone | ## The deck that is not anybody's business diff --git a/examples/build.php b/examples/build.php index 8318f47..97a05f0 100644 --- a/examples/build.php +++ b/examples/build.php @@ -58,6 +58,8 @@ '09-inline-markup' => 'The eight things a paragraph turns into runs.', '11-type-scale-default' => 'One deck at the library\'s own type scale.', '11-type-scale-dense' => 'The same slides at thirteen points, with the gaps with them.', + '21-masked-images' => 'Pictures drawn in a shape rather than in a rectangle: six masks on one picture, and what the mask is and is not.', + '22-legible-over-image' => 'Words over a picture: with nothing between them and the photograph, with a translucent panel over it, and in an opaque box behind the words alone.', ]; $assets = SOURCES . '/assets'; diff --git a/examples/markdown/21-masked-images.md b/examples/markdown/21-masked-images.md new file mode 100644 index 0000000..70d9f81 --- /dev/null +++ b/examples/markdown/21-masked-images.md @@ -0,0 +1,45 @@ +--- +title: A picture in a shape +theme: default +description: Pictures drawn in a shape rather than in a rectangle. +--- + +# A picture in a shape + +A picture is drawn in a rectangle, and a picture can be drawn in another shape instead. The +shape is the picture's own, not a frame drawn around it: the file writes it as the geometry of +the picture, which is what PowerPoint writes for a picture cropped to a shape. + +`mask` names the shape, and a name outside the list below is refused with the list rather than +passed on to the file as a shape nobody can draw. + +- `circle` `ellipse` `roundrect` `triangle` `diamond` `hexagon` `chevron` `arrow` +- `star` `heart` `teardrop` `cloud` `moon` `donut` `frame` `plaque` + +The mask is a shape and not a size: the picture keeps the box it was given, and the shape is +drawn in it. A `circle` and an `ellipse` are the same shape, and the picture's own proportions +decide which of the two it looks like. + +--- +layout: blank +--- + +# The same picture in six shapes + +::image{src="assets/logo.png" mask=circle left=6% top=30% width=20% height=20% fit=contain alt="The logo in a circle"} + +::image{src="assets/logo.png" mask=hexagon left=30% top=30% width=20% height=20% fit=contain alt="The logo in a hexagon"} + +::image{src="assets/logo.png" mask=star left=54% top=30% width=20% height=20% fit=contain alt="The logo in a star"} + +::image{src="assets/logo.png" mask=heart left=78% top=30% width=20% height=20% fit=contain alt="The logo in a heart"} + +::image{src="assets/logo.png" mask=teardrop left=6% top=58% width=20% height=20% fit=contain alt="The logo in a teardrop"} + +::image{src="assets/logo.png" mask=roundrect left=30% top=58% width=20% height=20% fit=contain alt="The logo in a rounded rectangle"} + +:::content{left=54% top=58% width=42% height=28% font-size=15} +Six pictures, one file, six shapes. The mask is written into the picture and travels with it, +so a picture that was masked in a deck and opened in PowerPoint is a picture cropped to that +shape — and can be cropped to another one there. +::: diff --git a/examples/markdown/22-legible-over-image.md b/examples/markdown/22-legible-over-image.md new file mode 100644 index 0000000..5bce6e2 --- /dev/null +++ b/examples/markdown/22-legible-over-image.md @@ -0,0 +1,73 @@ +--- +title: Words over a picture +theme: default +description: A picture, a translucent panel over it, and an opaque box behind the words. +--- + +# Words over a picture + +A picture under words is a photograph with words on it, and the words are read against the +photograph rather than against the page. Something between the two is what gives them a surface +of their own to be read against, and there are two ways to put it there: a panel over the whole +picture, or a box behind the words alone. + +Both are a shape painted with a colour and an alpha, and the alpha is one percentage for the +whole shape — written into the colour of the fill and of the stroke, so the shape is seen +slightly through the page rather than a fill and an outline that disagree about how solid they +are. + +--- +layout: blank +--- + +# The words, on the picture + +::image{src="assets/landscape.webp" left=0 top=0 width=100% height=100% fit=stretch layer=back} + +:::content{left=8% top=38% width=84% height=24% font-size=20 color=dk1 align=center vertical-align=middle} +**The words sit on the picture.** There is nothing between the words and the photograph, so +they are read against whatever the photograph happens to be — which is a thing the author of a +deck cannot see while the deck is written. +::: + +--- +layout: blank +--- + +# The words, on a panel + +::image{src="assets/landscape.webp" left=0 top=0 width=100% height=100% fit=stretch layer=back} + +::rectangle{left=0 top=0 width=100% height=100% fill=lt1 alpha=75 layer=back} + +:::content{left=8% top=38% width=84% height=24% font-size=20 color=dk1 align=center vertical-align=middle} +**The words sit on a panel.** The picture is the same one, and the panel is the page's own +colour at 75% — so the picture shows through it and the words have something of their own to be +read against. +::: + +:::content{left=8% top=66% width=84% height=18% font-size=13 color=dk1 align=center} +The panel is drawn before the words and after the picture, so it is between them. The library +knows the colour of the panel and the colour of the words, and not what the photograph is made +of — so how readable the words are is a thing to look at rather than a thing the library can +promise. +::: + +--- +layout: blank +--- + +# The words, in a box + +::image{src="assets/landscape.webp" left=0 top=0 width=100% height=100% fit=stretch layer=back} + +:::content{left=7% top=28% width=58% height=34% fill=lt1 alpha=100 padding=16 font-size=19} +**The words sit in a box.** The box is the page's own colour and it is opaque, so the words have +the page to be read against — and the picture around the box keeps its own colours, because the +box is behind the words and nowhere else. +::: + +:::content{left=7% top=68% width=58% height=18% font-size=13 color=dk1} +A box rather than a panel over the whole picture: the shape is the same, and only its alpha +differs. `fill=lt1` alone would be opaque as well — a colour without an alpha is whole. +::: diff --git a/src/Fixes.php b/src/Fixes.php index 0eaa041..a984869 100644 --- a/src/Fixes.php +++ b/src/Fixes.php @@ -8,6 +8,7 @@ use PhpOffice\PhpPresentation\Reader\PowerPoint2007; use PhpOffice\PhpPresentation\Slide\Background\Gradient as BackgroundGradient; use PhpOffice\PhpPresentation\Shape\AutoShape; +use PhpOffice\PhpPresentation\Shape\Drawing\AbstractDrawingAdapter; use PhpOffice\PhpPresentation\Shape\Drawing\Gd; use PhpOffice\PhpPresentation\Shape\RichText; use PhpOffice\PhpPresentation\Shape\Table; @@ -20,8 +21,8 @@ * The library writes a few things a released PHPPresentation cannot: a table that says * which row is its header, a shape that says how round its corners are, a run of text * that says what it is, a picture that says where it was read from, a gradient of more - * than two stops, and a background painted with a gradient. It gets them from a patch - * applied to the installed package. + * than two stops, a background painted with a gradient, and a picture that says what + * shape it is drawn in. It gets them from a patch applied to the installed package. * * The check is made once per conversion because the alternative is a fatal error in the * middle of the work naming a method rather than the reason. A reader of that error @@ -51,6 +52,7 @@ final class Fixes Fill::class => 'getGradientStops', GradientStop::class => 'getPosition', BackgroundGradient::class => 'getFill', + AbstractDrawingAdapter::class => 'setGeometry', ]; /** diff --git a/src/Render/Free/FreePicture.php b/src/Render/Free/FreePicture.php index 5003835..cb7d843 100644 --- a/src/Render/Free/FreePicture.php +++ b/src/Render/Free/FreePicture.php @@ -14,6 +14,9 @@ * all one set of rules rather than two: `::image{src="logo.png"}` and `![Logo](logo.png)` find * the same file through the same {@see \MarkdownPresentation\Filesystem\PathScope}, and a * picture outside it fails the same way. + * + * The kind is the picture's own and is not asked for: a free shape that is a picture is + * {@see ShapeKind::Image}, and the ten ink shapes are the ones that are asked for. */ final class FreePicture extends FreeShape { @@ -21,28 +24,30 @@ final class FreePicture extends FreeShape * @param string $fit {@see self::CONTAIN} or {@see self::STRETCH}; see * {@see \MarkdownPresentation\Render\Free\Pictures::fit()} for what a * third would cost. + * @param Mask|null $mask The shape the picture is drawn in, or null where it is drawn in + * the rectangle a picture is drawn in. */ private function __construct( - ShapeKind $kind, Placement $placement, int $step, Paint $paint, public readonly Image $image, public readonly string $fit, + public readonly ?Mask $mask, ?Shadow $shadow, ) { - parent::__construct($kind, $placement, $step, $paint, '', $shadow); + parent::__construct(ShapeKind::Image, $placement, $step, $paint, '', $shadow); } public static function at( - ShapeKind $kind, Placement $placement, int $step, Paint $paint, Image $image, string $fit, + ?Mask $mask, ?Shadow $shadow, ): self { - return new self($kind, $placement, $step, $paint, $image, $fit, $shadow); + return new self($placement, $step, $paint, $image, $fit, $mask, $shadow); } } diff --git a/src/Render/Free/Mask.php b/src/Render/Free/Mask.php new file mode 100644 index 0000000..ba2680b --- /dev/null +++ b/src/Render/Free/Mask.php @@ -0,0 +1,114 @@ + AutoShape::TYPE_OVAL, + self::RoundRect => AutoShape::TYPE_ROUNDED_RECTANGLE, + self::Triangle => AutoShape::TYPE_ISOSCELES_TRIANGLE, + self::Diamond => AutoShape::TYPE_DIAMOND, + self::Hexagon => AutoShape::TYPE_HEXAGON, + self::Chevron => AutoShape::TYPE_CHEVRON, + self::Arrow => AutoShape::TYPE_RIGHT_ARROW, + self::Star => AutoShape::TYPE_5_POINT_STAR, + self::Heart => AutoShape::TYPE_HEART, + self::Teardrop => AutoShape::TYPE_TEAR, + self::Cloud => AutoShape::TYPE_CLOUD, + self::Moon => AutoShape::TYPE_MOON, + self::Donut => AutoShape::TYPE_DONUT, + self::Frame => AutoShape::TYPE_FRAME, + self::Plaque => AutoShape::TYPE_PLAQUE, + }; + } + + /** + * The mask the deck asked for, or null where it asked for none. + * + * @throws MalformedShape + */ + public static function read(int $slide, string $name, DirectiveAttributes $attributes): ?self + { + $written = Length::written($slide, $name, 'mask', $attributes, ''); + + if ($written === '') { + return null; + } + + $mask = self::tryFrom(strtolower(trim($written))); + + if ($mask !== null) { + return $mask; + } + + throw MalformedShape::attributeValue( + $slide, + $name, + 'mask', + $written, + sprintf('A mask is one of: %s.', implode(', ', self::names())), + ); + } + + /** + * Every mask this format offers, sorted, for a message that has to name them. + * + * @return list + */ + public static function names(): array + { + $names = array_map(static fn (self $mask): string => $mask->value, self::cases()); + sort($names); + + return $names; + } +} diff --git a/src/Render/Free/ShapeKind.php b/src/Render/Free/ShapeKind.php index aef8044..ff8b3fb 100644 --- a/src/Render/Free/ShapeKind.php +++ b/src/Render/Free/ShapeKind.php @@ -86,8 +86,10 @@ enum ShapeKind: string */ private const LABEL = ['label']; - /** What a picture is taken from and how it is fitted to its box. */ - private const PICTURE = ['src', 'alt', 'fit']; + /** + * What a picture is taken from, how it is fitted to its box, and what shape it is drawn in. + */ + private const PICTURE = ['src', 'alt', 'fit', 'mask']; /** * The autoshape this is drawn as, or null where it is not drawn as one. diff --git a/src/Render/Free/ShapeReader.php b/src/Render/Free/ShapeReader.php index 1a9d48f..7097f51 100644 --- a/src/Render/Free/ShapeReader.php +++ b/src/Render/Free/ShapeReader.php @@ -115,12 +115,12 @@ private function shape( return match (true) { $kind === ShapeKind::Image => FreePicture::at( - $kind, $placement, $state->step, $paint, $this->picture($attributes, $state), Pictures::fit($state->slide, $kind->value, $attributes), + Mask::read($state->slide, $kind->value, $attributes), $shadow, ), // Before the text block, which is a box whose body the deck wrote: this one's body diff --git a/src/Render/ShapeWriter.php b/src/Render/ShapeWriter.php index fc74f8c..7cf991f 100644 --- a/src/Render/ShapeWriter.php +++ b/src/Render/ShapeWriter.php @@ -730,6 +730,13 @@ private function freePicture(Slide $slide, FreePicture $shape): AbstractDrawingA { $written = $this->drawing($slide, $shape); + // The shape the picture is drawn in, which is the picture's own rather than a frame + // around it: the file writes the shape as the geometry of the picture, so the mask moves + // with the picture and the picture moves with the mask. + if ($shape->mask !== null) { + $written->setGeometry($shape->mask->prst()); + } + // The alt text is what a screen reader reads and what PowerPoint's own pane shows, and // a file path read aloud is not a description of a picture. {@see self::image()} has // the longer version of why nothing in the file records where the deck found it. diff --git a/tests/Unit/free-shapes.php b/tests/Unit/free-shapes.php index 630eea9..3c285b5 100644 --- a/tests/Unit/free-shapes.php +++ b/tests/Unit/free-shapes.php @@ -458,7 +458,7 @@ function freeShapePicture(): string // The one mistake in this vocabulary that would otherwise leave no trace: a shape drawn // without the fill that was asked for, on a deck that looks rendered. expect(fn () => placedShapes("::image{src=\"logo.png\" padding=8}\n")) - ->toThrow(MalformedShape::class, 'The attributes are: alt, anchor, bleed, fit, height, layer, left, rotate, shadow-alpha, shadow-blur, shadow-color, shadow-direction, shadow-distance, src, top, width.'); + ->toThrow(MalformedShape::class, 'The attributes are: alt, anchor, bleed, fit, height, layer, left, mask, rotate, shadow-alpha, shadow-blur, shadow-color, shadow-direction, shadow-distance, src, top, width.'); }); it('gives each directive its own attribute vocabulary', function (ShapeKind $kind, string $last) { diff --git a/tests/Unit/masks.php b/tests/Unit/masks.php new file mode 100644 index 0000000..3d6eb6c --- /dev/null +++ b/tests/Unit/masks.php @@ -0,0 +1,143 @@ +render((new DeckParser())->parse($markdown), $path); + + return Pptx::open($path); +} + +/** The shapes of one slide, read through the parser. */ +function maskShapes(string $markdown): array +{ + return (new BlockTranslator())->parse( + $markdown, + 1, + Scratch::directory(), + new PathScope([Scratch::directory()]), + Theme::defaults(), + )->shapes(); +} + +/** A deck with one picture in it, and the picture's file. */ +function maskDeck(string $attributes): string +{ + $picture = Scratch::file('mask.png', base64_decode( + 'iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNk+M9QDwADhgGAWjR9awAAAABJRU5ErkJggg==', + )); + + return sprintf( + "---\nlayout: blank\n---\n\n::image{src=\"%s\" %s width=100 height=100}\n", + basename($picture), + $attributes, + ); +} + +it('writes the shape the picture is drawn in', function (string $mask, string $prst) { + $deck = maskDeckFile(maskDeck(sprintf('mask=%s', $mask))); + + expect($deck->part('ppt/slides/slide1.xml')) + ->toContain(sprintf('', $prst)); +})->with([ + 'circle' => ['circle', 'ellipse'], + 'ellipse' => ['ellipse', 'ellipse'], + 'roundrect' => ['roundrect', 'roundRect'], + 'triangle' => ['triangle', 'triangle'], + 'diamond' => ['diamond', 'diamond'], + 'hexagon' => ['hexagon', 'hexagon'], + 'chevron' => ['chevron', 'chevron'], + 'arrow' => ['arrow', 'rightArrow'], + 'star' => ['star', 'star5'], + 'heart' => ['heart', 'heart'], + 'teardrop' => ['teardrop', 'teardrop'], + 'cloud' => ['cloud', 'cloud'], + 'moon' => ['moon', 'moon'], + 'donut' => ['donut', 'donut'], + 'frame' => ['frame', 'frame'], + 'plaque' => ['plaque', 'plaque'], +]); + +it('writes a picture without a mask in a rectangle', function () { + $deck = maskDeckFile(maskDeck('')); + + expect($deck->part('ppt/slides/slide1.xml'))->toContain(''); +}); + +it('writes the shape as the geometry of the picture and not of a frame around it', function () { + // The mask is the picture's own: the geometry is written inside the picture's own + // `p:spPr`, which is where PowerPoint writes it for a picture cropped to a shape. + $deck = maskDeckFile(maskDeck('mask=heart')); + + expect($deck->part('ppt/slides/slide1.xml')) + ->toMatch('#.*?.*?#s'); +}); + +it('refuses a mask that is not one of the names it offers', function () { + expect(fn () => maskDeckFile(maskDeck('mask=blob'))) + ->toThrow( + MalformedShape::class, + 'A mask is one of: arrow, chevron, circle, cloud, diamond, donut, ellipse, frame, ' + . 'heart, hexagon, moon, plaque, roundrect, star, teardrop, triangle.', + ); +}); + +it('refuses a mask on a shape that is not a picture', function () { + // The attribute belongs to the picture and to nothing else: a shape that is drawn in a + // shape is a picture, and a shape that is not one is a shape. + expect(fn () => maskDeckFile( + "---\nlayout: blank\n---\n\n::rectangle{mask=circle width=100 height=100}\n", + ))->toThrow(MalformedShape::class, 'mask'); +}); + +it('carries the mask on the shape the deck wrote', function () { + $shapes = maskShapes(maskDeck('mask=heart')); + + expect($shapes)->toHaveCount(1) + ->and($shapes[0])->toBeInstanceOf(FreePicture::class) + ->and($shapes[0]->mask)->toBe(Mask::Heart) + ->and($shapes[0]->mask?->prst())->toBe(AutoShape::TYPE_HEART); +}); + +it('carries no mask on a picture that was given none', function () { + $shapes = maskShapes(maskDeck('')); + + expect($shapes)->toHaveCount(1) + ->and($shapes[0]->mask)->toBeNull(); +}); + +it('leaves the box of the picture the mask it was given', function () { + // The mask is a shape and not a size: the picture keeps the box it was placed in, and the + // shape is drawn in it. + $masked = maskDeckFile(maskDeck('mask=circle')); + $plain = maskDeckFile(maskDeck('')); + + expect($masked->positionOf('image'))->toEqual($plain->positionOf('image')); +}); diff --git a/tests/Unit/opacity.php b/tests/Unit/opacity.php new file mode 100644 index 0000000..039a722 --- /dev/null +++ b/tests/Unit/opacity.php @@ -0,0 +1,98 @@ +render((new DeckParser())->parse($markdown), $path); + + return Pptx::open($path); +} + +it('writes the alpha of a placed text block into the colour of its fill', function () { + // A panel the words sit on: the text block is a box like any other and takes a fill and an + // alpha like any other, which is what makes a picture under it readable. + $deck = opacityDeckFile( + "---\nlayout: blank\n---\n\n:::content{left=10 top=10 width=400 height=200 fill=accent1 alpha=60}\nWords.\n:::\n", + ); + + expect($deck->part('ppt/slides/slide1.xml'))->toContain(''); +}); + +it('writes the alpha of an ink shape into the colour of its fill and of its stroke', function () { + // One alpha for the shape rather than one per colour: a shape that is seen slightly through + // the page is one shape, not a fill and an outline that disagree about how solid they are. + $deck = opacityDeckFile( + "---\nlayout: blank\n---\n\n::rectangle{left=10 top=10 width=200 height=100 fill=accent1 stroke=accent2 alpha=75}\n", + ); + + expect($deck->part('ppt/slides/slide1.xml')) + ->toContain('') + ->and(substr_count($deck->part('ppt/slides/slide1.xml'), ''))->toBe(2); +}); + +it('writes an alpha of zero as an alpha of zero', function () { + // The whole of the shape is gone rather than the whole of it being there: a shape that is + // invisible and a shape that is opaque are two different things, and one is not the other. + $deck = opacityDeckFile( + "---\nlayout: blank\n---\n\n::rectangle{left=10 top=10 width=200 height=100 fill=accent1 alpha=0}\n", + ); + + expect($deck->part('ppt/slides/slide1.xml'))->toContain(''); +}); + +it('writes the alpha of a gradient into every stop of it', function () { + $deck = opacityDeckFile( + "---\nlayout: blank\n---\n\n::rectangle{left=10 top=10 width=200 height=100 gradient=accent1,accent2 alpha=70}\n", + ); + + expect(substr_count($deck->part('ppt/slides/slide1.xml'), ''))->toBe(2); +}); + +it('refuses an alpha on a picture', function () { + // A picture is painted by its own bytes: it takes no fill and no alpha, and the attribute + // is refused rather than ignored, so that a deck that asks for one is told why. + expect(fn () => opacityDeckFile( + "---\nlayout: blank\n---\n\n::image{src=\"logo.png\" alpha=50}\n", + ))->toThrow(MalformedShape::class, 'alpha'); +}); + +it('draws the picture, then the panel over it, then the words over that', function () { + // The order the shapes are written in is the order they are drawn in, and it is what makes + // the words legible over a photograph: the panel between them is what the words are read + // against. + $picture = Scratch::file('opacity.png', base64_decode( + 'iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNk+M9QDwADhgGAWjR9awAAAABJRU5ErkJggg==', + )); + + $deck = opacityDeckFile(sprintf( + "---\nlayout: blank\n---\n\n::image{src=\"%s\" left=0 top=0 width=960 height=540}\n" + . "::rectangle{left=0 top=0 width=960 height=540 fill=accent1 alpha=60}\n" + . ":::content{left=40 top=200 width=600 height=140}\nReadable\n:::\n", + basename($picture), + )); + + expect($deck->shapeNames())->toBe(['image', 'rectangle', 'content']) + ->and($deck->slideText())->toContain('Readable'); +});