Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
18 changes: 18 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
57 changes: 56 additions & 1 deletion README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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) |
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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.
```
Expand Down
6 changes: 3 additions & 3 deletions composer.json
Original file line number Diff line number Diff line change
Expand Up @@ -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"
}
]
}
Expand Down
2 changes: 2 additions & 0 deletions examples/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down
2 changes: 2 additions & 0 deletions examples/build.php
Original file line number Diff line number Diff line change
Expand Up @@ -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';
Expand Down
45 changes: 45 additions & 0 deletions examples/markdown/21-masked-images.md
Original file line number Diff line number Diff line change
@@ -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.
:::
73 changes: 73 additions & 0 deletions examples/markdown/22-legible-over-image.md
Original file line number Diff line number Diff line change
@@ -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.
:::
6 changes: 4 additions & 2 deletions src/Fixes.php
Original file line number Diff line number Diff line change
Expand Up @@ -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;
Expand All @@ -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
Expand Down Expand Up @@ -51,6 +52,7 @@ final class Fixes
Fill::class => 'getGradientStops',
GradientStop::class => 'getPosition',
BackgroundGradient::class => 'getFill',
AbstractDrawingAdapter::class => 'setGeometry',
];

/**
Expand Down
13 changes: 9 additions & 4 deletions src/Render/Free/FreePicture.php
Original file line number Diff line number Diff line change
Expand Up @@ -14,35 +14,40 @@
* 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
{
/**
* @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);
}
}
Loading
Loading