propresenter7-php-lib/src/ClearGroupDefinition.php
Thorsten Bus 9e3e719806 feat(library): add readers + writers for all ProPresenter global libraries and theme bundles
Add full IO support for every global ProPresenter library file plus
theme folders, and extend the existing Labels/Macros readers with
exporters and editable accessors so every supported document is now a
round-trippable, mutable object.

New library readers/writers (each: FileReader, FileWriter, Library
wrapper, element wrapper where applicable, CLI tool, tests, doc/api/*.md):

- Groups          (ProGroupsDocument)        + GroupDefinition
- ClearGroups     (ClearGroupsDocument)      + ClearGroupDefinition
- CCLI            (CCLIDocument)
- Messages        (MessageDocument)          + Message
- Timers          (TimersDocument + Clock)   + Timer
- Stage           (Stage.Document)           + StageLayout
- Workspace       (ProPresenterWorkspace)    + Screen
- Props           (PropDocument)             + Prop
- TestPatterns    (TestPatternDocument)
- Calendar        (new CalendarDocument)     + CalendarEvent
- KeyMappings     (new KeyMappingsDocument)  + KeyMapping
- CommunicationDevices (JSON file)           + CommunicationDevice
- Theme bundles   (Template.Document folder + Assets/) + ThemeBundle/Slide/Asset

Extensions to existing modules:

- LabelsFileWriter; Label and LabelLibrary gain setters, addLabel,
  removeLabel, setColor / setColorHex helpers
- MacrosFileWriter; Macro/MacroCollection/MacroLibrary gain UUID, name,
  color, image_type, image_data, trigger_on_startup setters plus
  add/remove for macros and collections

Two new minimal proto schemas were defined for documents that lacked
upstream definitions:

- proto/calendar.proto   - CalendarDocument with Event entries, raw
  bytes for the action/macro sub-messages so the schema can evolve
- proto/keyMappings.proto - KeyMappingsDocument with ApplicationInfo
  and a forward-looking Mapping message (sample only carries the info)

The Theme file turned out to be a regular Rv\Data\Template\Document, so
no new proto was required for theme content; ThemeBundle layers folder
+ Assets/ handling on top in the same spirit as PresentationBundle.

GroupDefinition is intentionally distinct from the existing Group class
(which wraps song-level CueGroup) to avoid breaking song APIs.

Verified with the full PHPUnit suite: 370 tests, 9200 assertions, all
green; LSP diagnostics clean across src/. The unmodified reference
samples for Labels, Groups, ClearGroups, TestPatterns, Calendar and
KeyMappings round-trip byte-for-byte; the others round-trip with the
same byte length (PHP protobuf is not canonically deterministic but
re-write-after-write stabilises).

doc/INDEX.md, doc/keywords.md and AGENTS.md updated so every new module
is discoverable from the top level.
2026-05-03 21:40:09 +02:00

200 lines
4.2 KiB
PHP

<?php
declare(strict_types=1);
namespace ProPresenter\Parser;
use Rv\Data\ClearGroupsDocument\ClearGroup as ClearGroupProto;
use Rv\Data\Color;
use Rv\Data\UUID;
class ClearGroupDefinition
{
public function __construct(
private readonly ClearGroupProto $group,
) {
}
public function getUuid(): string
{
return $this->group->getUuid()?->getString() ?? '';
}
public function setUuid(string $uuid): self
{
$proto = new UUID();
$proto->setString($uuid);
$this->group->setUuid($proto);
return $this;
}
public function getName(): string
{
return $this->group->getName();
}
public function setName(string $name): self
{
$this->group->setName($name);
return $this;
}
/**
* @return int[]
*/
public function getLayerTargets(): array
{
return iterator_to_array($this->group->getLayerTargets());
}
/**
* @param int[] $targets
*/
public function setLayerTargets(array $targets): self
{
$this->group->setLayerTargets($targets);
return $this;
}
public function isHiddenInPreview(): bool
{
return $this->group->getIsHiddenInPreview();
}
public function setHiddenInPreview(bool $hidden): self
{
$this->group->setIsHiddenInPreview($hidden);
return $this;
}
public function getImageData(): string
{
return $this->group->getImageData();
}
public function setImageData(string $imageData): self
{
$this->group->setImageData($imageData);
return $this;
}
public function getImageType(): int
{
return $this->group->getImageType();
}
public function setImageType(int $imageType): self
{
$this->group->setImageType($imageType);
return $this;
}
public function isIconTinted(): bool
{
return $this->group->getIsIconTinted();
}
public function setIconTinted(bool $tinted): self
{
$this->group->setIsIconTinted($tinted);
return $this;
}
/**
* @return array{r: float, g: float, b: float, a: float}|null
*/
public function getColor(): ?array
{
if (!$this->group->hasIconTintColor()) {
return null;
}
$color = $this->group->getIconTintColor();
return [
'r' => $color->getRed(),
'g' => $color->getGreen(),
'b' => $color->getBlue(),
'a' => $color->getAlpha(),
];
}
public function getColorHex(): ?string
{
$color = $this->getColor();
if ($color === null) {
return null;
}
return sprintf(
'#%02X%02X%02X',
(int) round(max(0.0, min(1.0, $color['r'])) * 255),
(int) round(max(0.0, min(1.0, $color['g'])) * 255),
(int) round(max(0.0, min(1.0, $color['b'])) * 255),
);
}
/**
* @param array{r: float, g: float, b: float, a?: float}|null $color
*/
public function setColor(?array $color): self
{
if ($color === null) {
$this->group->clearIconTintColor();
return $this;
}
$proto = new Color();
$proto->setRed((float) $color['r']);
$proto->setGreen((float) $color['g']);
$proto->setBlue((float) $color['b']);
$proto->setAlpha((float) ($color['a'] ?? 1.0));
$this->group->setIconTintColor($proto);
return $this;
}
/**
* @return int[]
*/
public function getTimelineTargets(): array
{
return iterator_to_array($this->group->getTimelineTargets());
}
/**
* @param int[] $targets
*/
public function setTimelineTargets(array $targets): self
{
$this->group->setTimelineTargets($targets);
return $this;
}
public function clearsPresentationNextSlide(): bool
{
return $this->group->getClearPresentationNextSlide();
}
public function setClearPresentationNextSlide(bool $clear): self
{
$this->group->setClearPresentationNextSlide($clear);
return $this;
}
public function getProto(): ClearGroupProto
{
return $this->group;
}
}