From f31cf735f56ff60353a5a31034266945e21ef49e Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Fabian=20Gra=C3=9Fl?= Date: Sun, 8 Nov 2026 19:10:38 +0100 Subject: [PATCH 1/6] A picture may be drawn 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. `mask` names it, and there are sixteen: circle, ellipse, roundrect, triangle, diamond, hexagon, chevron, arrow, star, heart, teardrop, cloud, moon, donut, frame and plaque. 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. It needs a PHPPresentation that can write it, which the patch this library carries now does: a drawing carries the name of a preset, and the writer writes it as the geometry of the picture. --- CHANGELOG.md | 18 ++++ README.md | 23 ++++- composer.json | 6 +- examples/README.md | 1 + examples/build.php | 1 + examples/markdown/21-masked-images.md | 45 +++++++++ src/Fixes.php | 6 +- src/Render/Free/FreePicture.php | 6 +- src/Render/Free/Mask.php | 114 ++++++++++++++++++++++ src/Render/Free/ShapeKind.php | 6 +- src/Render/Free/ShapeReader.php | 1 + src/Render/ShapeWriter.php | 7 ++ tests/Unit/free-shapes.php | 2 +- tests/Unit/masks.php | 134 ++++++++++++++++++++++++++ 14 files changed, 360 insertions(+), 10 deletions(-) create mode 100644 examples/markdown/21-masked-images.md create mode 100644 src/Render/Free/Mask.php create mode 100644 tests/Unit/masks.php 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..938f9c9 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,25 @@ 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 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 +1554,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..6c2ba3c 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/0925ca87673f93562b6ab5db630bd56756dfc045/patches/phpoffice-phppresentation-1.2.0-to-master.patch", + "sha256": "4665f3095852e58b915f48f744125d6d700f477ef0daff3e0eb6757122484f01" } ] } diff --git a/examples/README.md b/examples/README.md index b430692..3447e85 100644 --- a/examples/README.md +++ b/examples/README.md @@ -37,6 +37,7 @@ 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 | ## The deck that is not anybody's business diff --git a/examples/build.php b/examples/build.php index 8318f47..7fcd892 100644 --- a/examples/build.php +++ b/examples/build.php @@ -58,6 +58,7 @@ '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.', ]; $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/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..4172d5d 100644 --- a/src/Render/Free/FreePicture.php +++ b/src/Render/Free/FreePicture.php @@ -21,6 +21,8 @@ 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, @@ -29,6 +31,7 @@ private function __construct( Paint $paint, public readonly Image $image, public readonly string $fit, + public readonly ?Mask $mask, ?Shadow $shadow, ) { parent::__construct($kind, $placement, $step, $paint, '', $shadow); @@ -41,8 +44,9 @@ public static function at( Paint $paint, Image $image, string $fit, + ?Mask $mask, ?Shadow $shadow, ): self { - return new self($kind, $placement, $step, $paint, $image, $fit, $shadow); + return new self($kind, $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..4f026c4 100644 --- a/src/Render/Free/ShapeReader.php +++ b/src/Render/Free/ShapeReader.php @@ -121,6 +121,7 @@ private function shape( $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..5a90c65 --- /dev/null +++ b/tests/Unit/masks.php @@ -0,0 +1,134 @@ +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('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')); +}); From fe0587d5473a97767adabb4d6384b4ac8ebde110 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Fabian=20Gra=C3=9Fl?= Date: Sun, 8 Nov 2026 19:10:46 +0100 Subject: [PATCH 2/6] Words over a picture, and the panel they are read against A picture under words is a photograph with words on it, and the words are read against the photograph rather than against the page. A panel between the two is what gives them something of their own to be read against: a shape painted with a colour and an alpha, so that the picture shows through it and the words sit on the panel. The alpha is one percentage for the whole shape, and it is written into the colour of the fill and of the stroke. What is checked here is that it reaches the colours of every kind of shape that takes one -- the ink shapes, the placed text block and the stops of a gradient -- and that the panel is drawn between the picture and the words, so that 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. The example says so. --- README.md | 23 +++++ examples/README.md | 1 + examples/build.php | 1 + examples/markdown/22-legible-over-image.md | 53 ++++++++++++ tests/Unit/opacity.php | 98 ++++++++++++++++++++++ 5 files changed, 176 insertions(+) create mode 100644 examples/markdown/22-legible-over-image.md create mode 100644 tests/Unit/opacity.php diff --git a/README.md b/README.md index 938f9c9..442d8fd 100644 --- a/README.md +++ b/README.md @@ -1492,6 +1492,29 @@ 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 picture in a shape A picture is drawn in a rectangle, and a picture can be drawn in another shape instead. The shape diff --git a/examples/README.md b/examples/README.md index 3447e85..ba258cc 100644 --- a/examples/README.md +++ b/examples/README.md @@ -38,6 +38,7 @@ quietly. The profile and the scratch script go to the temporary directory, so | `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, once with nothing between them and the photograph and once with a translucent panel, which is what the words are read against | ## The deck that is not anybody's business diff --git a/examples/build.php b/examples/build.php index 7fcd892..3ab18bb 100644 --- a/examples/build.php +++ b/examples/build.php @@ -59,6 +59,7 @@ '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 and without a translucent panel between them.', ]; $assets = SOURCES . '/assets'; diff --git a/examples/markdown/22-legible-over-image.md b/examples/markdown/22-legible-over-image.md new file mode 100644 index 0000000..b27d62c --- /dev/null +++ b/examples/markdown/22-legible-over-image.md @@ -0,0 +1,53 @@ +--- +title: Words over a picture +theme: default +description: A picture, a translucent panel over it, and the words on the panel. +--- + +# 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. A panel between the two is what gives them something of +their own to be read against: a shape painted with a colour and an alpha, so that the picture +shows through it and the words sit on the panel. + +The alpha is one percentage for the whole shape. It is 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. +::: 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'); +}); From ef2d1df12a6187185e8e1a183e9621263af5f25b Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Fabian=20Gra=C3=9Fl?= Date: Sun, 8 Nov 2026 19:15:18 +0100 Subject: [PATCH 3/6] The mask is the picture's own and the test says so The geometry is written inside the picture's own `p:spPr`, which is where PowerPoint writes it for a picture cropped to a shape -- and the test says that, rather than that the slide holds the shape somewhere. --- tests/Unit/masks.php | 9 +++++++++ 1 file changed, 9 insertions(+) diff --git a/tests/Unit/masks.php b/tests/Unit/masks.php index 5a90c65..3d6eb6c 100644 --- a/tests/Unit/masks.php +++ b/tests/Unit/masks.php @@ -91,6 +91,15 @@ function maskDeck(string $attributes): string 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( From f6a1bd2a61a60924e31c3c5399f84697651beb87 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Fabian=20Gra=C3=9Fl?= Date: Sun, 8 Nov 2026 19:19:13 +0100 Subject: [PATCH 4/6] The picture is a picture, and does not have to be asked The kind of a free shape that is a picture is `image`, and there is no other: the ten ink shapes are the ones that are asked for, because there are ten of them. Asking for it here made the method one parameter longer than the ceiling, and the parameter carried nothing. The ceiling is the suite's own: a method with more than seven parameters is one thing too many, and a picture that is a picture does not need to be told which kind it is. --- src/Render/Free/FreePicture.php | 9 +++++---- src/Render/Free/ShapeReader.php | 1 - 2 files changed, 5 insertions(+), 5 deletions(-) diff --git a/src/Render/Free/FreePicture.php b/src/Render/Free/FreePicture.php index 4172d5d..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 { @@ -25,7 +28,6 @@ final class FreePicture extends FreeShape * the rectangle a picture is drawn in. */ private function __construct( - ShapeKind $kind, Placement $placement, int $step, Paint $paint, @@ -34,11 +36,10 @@ private function __construct( 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, @@ -47,6 +48,6 @@ public static function at( ?Mask $mask, ?Shadow $shadow, ): self { - return new self($kind, $placement, $step, $paint, $image, $fit, $mask, $shadow); + return new self($placement, $step, $paint, $image, $fit, $mask, $shadow); } } diff --git a/src/Render/Free/ShapeReader.php b/src/Render/Free/ShapeReader.php index 4f026c4..7097f51 100644 --- a/src/Render/Free/ShapeReader.php +++ b/src/Render/Free/ShapeReader.php @@ -115,7 +115,6 @@ private function shape( return match (true) { $kind === ShapeKind::Image => FreePicture::at( - $kind, $placement, $state->step, $paint, From 25c30999857a212a6ee5900750e38d27edecafb6 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Fabian=20Gra=C3=9Fl?= Date: Sun, 8 Nov 2026 20:05:44 +0100 Subject: [PATCH 5/6] The pin names the commit the patch is on The patch is the same file it was -- the fix and the re-rolled patch did not change -- and the commit it sits on has a new hash, because the commits that carry it now say what the change is called. --- composer.json | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/composer.json b/composer.json index 6c2ba3c..9a63d0a 100644 --- a/composer.json +++ b/composer.json @@ -40,7 +40,7 @@ "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, and that give a picture the geometry it is drawn in", - "url": "https://raw.githubusercontent.com/markdown-office/PHPPresentation/0925ca87673f93562b6ab5db630bd56756dfc045/patches/phpoffice-phppresentation-1.2.0-to-master.patch", + "url": "https://raw.githubusercontent.com/markdown-office/PHPPresentation/a95169ca0d678cd2b4cd0fd6ec1e072b83d421cd/patches/phpoffice-phppresentation-1.2.0-to-master.patch", "sha256": "4665f3095852e58b915f48f744125d6d700f477ef0daff3e0eb6757122484f01" } ] From 9f40859698f7c0b540d5ef97a554fdf251a51a84 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Fabian=20Gra=C3=9Fl?= Date: Sun, 8 Nov 2026 20:56:09 +0100 Subject: [PATCH 6/6] The words in a box, and the picture around them The panel over the whole picture is one way to give words over a photograph something to be read against, and it veils the picture to do it. The other way is a box behind the words alone: the same shape, painted with the page's own colour and opaque, so the words have the page to be read against and 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. --- README.md | 11 +++++++ examples/README.md | 2 +- examples/build.php | 2 +- examples/markdown/22-legible-over-image.md | 34 +++++++++++++++++----- 4 files changed, 40 insertions(+), 9 deletions(-) diff --git a/README.md b/README.md index 442d8fd..2600bfe 100644 --- a/README.md +++ b/README.md @@ -1515,6 +1515,17 @@ The library knows the colour of the panel and the colour of the words, and not w 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 diff --git a/examples/README.md b/examples/README.md index ba258cc..c037c79 100644 --- a/examples/README.md +++ b/examples/README.md @@ -38,7 +38,7 @@ quietly. The profile and the scratch script go to the temporary directory, so | `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, once with nothing between them and the photograph and once with a translucent panel, which is what the words are read against | +| `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 3ab18bb..97a05f0 100644 --- a/examples/build.php +++ b/examples/build.php @@ -59,7 +59,7 @@ '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 and without a translucent panel between them.', + '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/22-legible-over-image.md b/examples/markdown/22-legible-over-image.md index b27d62c..5bce6e2 100644 --- a/examples/markdown/22-legible-over-image.md +++ b/examples/markdown/22-legible-over-image.md @@ -1,19 +1,20 @@ --- title: Words over a picture theme: default -description: A picture, a translucent panel over it, and the words on the panel. +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. A panel between the two is what gives them something of -their own to be read against: a shape painted with a colour and an alpha, so that the picture -shows through it and the words sit on the panel. +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. -The alpha is one percentage for the whole shape. It is 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. +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 @@ -51,3 +52,22 @@ knows the colour of the panel and the colour of the words, and not what the phot 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. +:::