Region

Namespace: Com\Tecnick\Pdf\Page

abstract class Region extends Settings

Extends: Settings

Source: src/Region.php:42

Constants

MAX_BANDS

Maximum number of horizontal slices buildWritableRegions() may cut the content area into.

public const MAX_BANDS = 1000

Source: src/Region.php:47

Methods

add()

Add a new page.

public add(PageInputData $data = []): PageData

Parameters:

• $data (PageInputData): Page data:

  annotrefs   : array containing the annotation object references.
  autobreak   : true to automatically add a page when the content reaches the breaking point.
  box         : array containing page box boundaries and settings (@see setBox).
  columns     : number of equal vertical columns, if set it will automatically populate the region array.
  content     : string containing the raw page content.
  format      : page format name, or alternatively you can set width and height as below.
  group       : page group number.
  height      : page height.
  margin      : page margins:
                - booklet : true to enable booklet mode
                - PL : page left margin measured from the left page edge
                - PR : page right margin measured from the right page edge
                - PT : page top or header top measured distance from the top page edge
                - HB : header bottom measured from the top page edge
                - CT : content top measured from the top page edge
                - CB : content bottom (page breaking point) measured from the bottom page edge
                - FT : footer top measured from the bottom page edge
                - PB : page bottom (footer bottom) measured from the bottom page edge
  num         : if set overwrites the page number.
  orientation : page orientation ('P' or 'L').
  region      : array containing the ordered list of rectangular areas where it is allowed to write,
                each region is defined by:
                - RX : horizontal coordinate of top-left corner
                - RY : vertical coordinate of top-left corner
                - RW : region width
                - RH : region height
  rotation    : the number of degrees by which the page shall be rotated clockwise when displayed or printed.
  time        : UTC page modification time in seconds.
  transition  : array containing page transition data (@see getPageTransition).
  width       : page width.
  zoom        : preferred zoom (magnification) factor: 1.0 = 100%.
  

  NOTE: if $data is empty and the stack is not, the last page is cloned.

Returns: PageData: Page data with additional Page ID property ‘pid’.

Throws:

• Exception

Source: src/Region.php:99

addNoWriteRegion()

Append a single no-write area to the page and rebuild the writable regions.

setNoWriteRegions() must have been called first to set the band height.

public addNoWriteRegion(NoWriteArea $noWriteArea, int $pid = -1): PageData

Parameters:

• $noWriteArea (NoWriteArea): No-write area (page coordinates, user units).
• $pid (int): Page index. Omit or set it to -1 for the current page.

Returns: PageData: Page data.

Throws:

• Exception

Source: src/Region.php:818

buildWritableRegions()

Build the ordered list of writable rectangular regions that avoid the given no-write areas.

The content area is sliced into horizontal bands of height $bandHeight, and for each band the widest rectangle that does not overlap any no-write area is kept. Vertically-contiguous bands with the same horizontal extent are merged, so the area above and below an obstacle collapses to a single tall region and only the obstacle span is finely banded. The result is a stack of axis-aligned rectangles ordered top-to-bottom, suitable as the ‘region’ value of add() or as the input of setNoWriteRegions().

Each no-write area can be defined in one of two ways (page coordinates, user units):

• side-anchored segment, where the obstacle spans from a page side to a vertical, possibly slanted, segment: ‘xt’,‘yt’ : segment top point, ‘xb’,‘yb’ : segment bottom point, ‘side’ : ‘L’ to block from the left page edge to the segment, ‘R’ for the right.
• free rectangle (floating obstacle, e.g. an image): ‘x’,‘y’ : top-left corner, ‘w’ : width, ‘h’ : height.

NOTE: only the widest of the writable columns a floating area splits a band into is kept, so text does not wrap on both sides of a floating obstacle.

public buildWritableRegions(
    array<int,NoWriteArea> $noWriteAreas,
    float $bandHeight,
    int $pid = -1
): array<int,array{RX: float, RY: float, RW: float, RH: float}>

Parameters:

• $noWriteAreas (array<int,NoWriteArea>): No-write areas (page coordinates, user units).
• $bandHeight (float): Height of each horizontal slice (must be > 0 and yield at most MAX_BANDS slices).
• $pid (int): Page index. Omit or set it to -1 for the current page.

Returns: array<int,array{RX: float, RY: float, RW: float, RH: float}>: Ordered writable regions.

Throws:

• Exception

Source: src/Region.php:753

checkRegionBreak()

Move to the next page region if required.

Only a vertical overflow past the region bottom triggers the break.

public checkRegionBreak(float $height = 0.0, ?float $ypos = null, int $pid = -1): PageData

Parameters:

• $height (float): Height of the block to add.
• $ypos (?float): Starting Y position or NULL for current position.
• $pid (int): Page index. Omit or set it to -1 for the current page.

Returns: PageData: Page data.

Throws:

• Exception

Source: src/Region.php:529

enableAutoPageBreak()

Enable or disable automatic page break.

public enableAutoPageBreak(bool $isenabled = true, int $pid = -1): void

Parameters:

• $isenabled (bool): Set this to true to enable automatic page break.
• $pid (int): Page index. Omit or set it to -1 for the current page.

Throws:

• Exception

Source: src/Region.php:580

getNextPage()

Returns the next page data.

Creates a new page if required and page break is enabled.

public getNextPage(int $pid = -1): PageData

Parameters:

• $pid (int): Page index. Omit or set it to -1 for the current page.

Returns: PageData: Page data.

Throws:

• Exception

Source: src/Region.php:466

getNextRegion()

Returns the page data with the next selected region.

If there are no more regions available, then the first region on the next page is selected. A new page is added if required.

public getNextRegion(int $pid = -1): PageData

Parameters:

• $pid (int): Page index. Omit or set it to -1 for the current page.

Returns: PageData: Current page data.

Throws:

• Exception

Source: src/Region.php:492

getNoWriteRegions()

Return the no-write areas currently stored for the page.

public getNoWriteRegions(int $pid = -1): array<int,NoWriteArea>

Parameters:

• $pid (int): Page index. Omit or set it to -1 for the current page.

Returns: array<int,NoWriteArea>: No-write areas.

Throws:

• Exception

Source: src/Region.php:838

getPage()

Returns the specified page data.

public getPage(int $pid = -1): PageData

Parameters:

• $pid (int): Page index. Omit or set it to -1 for the current page.

Returns: PageData: Page data.

Throws:

• Exception

Source: src/Region.php:275

getRegion()

Returns the current region data.

public getRegion(int $pid = -1): RegionData

Parameters:

• $pid (int): Page index. Omit or set it to -1 for the current page.

Returns: RegionData: Region.

Throws:

• Exception

Source: src/Region.php:443

getX()

Return the absolute horizontal cursor position for the current region.

public getX(int $pid = -1): float

Parameters:

• $pid (int): Page index. Omit or set it to -1 for the current page.

Returns: float

Throws:

• Exception

Source: src/Region.php:656

getY()

Return the absolute vertical cursor position for the current region.

public getY(int $pid = -1): float

Parameters:

• $pid (int): Page index. Omit or set it to -1 for the current page.

Returns: float

Throws:

• Exception

Source: src/Region.php:669

isAutoPageBreakEnabled()

Return the auto-page-break status.

public isAutoPageBreakEnabled(int $pid = -1): bool

Parameters:

• $pid (int): Page index. Omit or set it to -1 for the current page.

Returns: bool: True if the auto page break is enabled, false otherwise.

Throws:

• Exception

Source: src/Region.php:562

isXOutRegion()

Check if the specified horizontal position is outside the region.

public isXOutRegion(?float $posx = null, float $width = 0.0, int $pid = -1): bool

Parameters:

• $posx (?float): X position or NULL for current position.
• $width (float): Additional width to add.
• $pid (int): Page index. Omit or set it to -1 for the current page.

Returns: bool

Throws:

• Exception

Source: src/Region.php:640

isYOutRegion()

Check if the specified vertical position is outside the region.

public isYOutRegion(?float $posy = null, float $height = 0.0, int $pid = -1): bool

Parameters:

• $posy (?float): Y position or NULL for current position.
• $height (float): Additional height to add.
• $pid (int): Page index. Omit or set it to -1 for the current page.

Returns: bool

Throws:

• Exception

Source: src/Region.php:622

removeNoWriteRegion()

Remove the no-write area with the given index and rebuild the writable regions.

public removeNoWriteRegion(int $index, int $pid = -1): PageData

Parameters:

• $index (int): Index of the no-write area to remove.
• $pid (int): Page index. Omit or set it to -1 for the current page.

Returns: PageData: Page data.

Throws:

• Exception

Source: src/Region.php:854

selectRegion()

Select the specified page region.

public selectRegion(int $idr, int $pid = -1): RegionData

Parameters:

• $idr (int): ID of the region.
• $pid (int): Page index. Omit or set it to -1 for the current page.

Returns: RegionData: Selected region data.

Throws:

• Exception

Source: src/Region.php:421

setCurrentPage()

Set the current page number (move to the specified page).

public setCurrentPage(int $pid = -1): PageData

Parameters:

• $pid (int): Page index. Omit or set it to -1 for the current page.

Returns: PageData: Page data.

Throws:

• Exception

Source: src/Region.php:259

setNoWriteRegions()

Set the no-write page areas, replacing any previously stored areas for the page.

The writable regions are (re)built and assigned to the page.

public setNoWriteRegions(
    array<int,NoWriteArea> $noWriteAreas,
    float $bandHeight,
    int $pid = -1
): PageData

Parameters:

• $noWriteAreas (array<int,NoWriteArea>): No-write areas (page coordinates, user units).
• $bandHeight (float): Height of each horizontal slice (must be > 0 and yield at most MAX_BANDS slices).
• $pid (int): Page index. Omit or set it to -1 for the current page.

Returns: PageData: Page data.

Throws:

• Exception

Source: src/Region.php:792

setPagePHeight()

Overrides the page height and returns the current value in points.

The MediaBox and the orientation are updated to match. The other boxes keep their declared coordinates and are intersected with the MediaBox on output, so passing the returned value back restores the original geometry. The format name, the margins and the regions are not recomputed: reassign them with setNoWriteRegions() or a new add() if the writable area must follow.

public setPagePHeight(float $pheight, int $pid = -1): float

Parameters:

• $pheight (float): new page height in internal points (must be positive).
• $pid (int): Page index. Omit or set it to -1 for the current page.

Returns: float: original page height in points.

Throws:

• Exception

Source: src/Region.php:302

setPagePWidth()

Overrides the page width and returns the current value in points.

The MediaBox and the orientation are updated to match. The other boxes keep their declared coordinates and are intersected with the MediaBox on output, so passing the returned value back restores the original geometry. The format name, the margins and the regions are not recomputed: reassign them with setNoWriteRegions() or a new add() if the writable area must follow.

public setPagePWidth(float $pwidth, int $pid = -1): float

Parameters:

• $pwidth (float): new page width in internal points (must be positive).
• $pid (int): Page index. Omit or set it to -1 for the current page.

Returns: float: original page width in points.

Throws:

• Exception

Source: src/Region.php:337

setX()

Set the absolute horizontal cursor position for the current region.

public setX(float $xpos, int $pid = -1): static

Parameters:

• $xpos (float): X position relative to the page coordinates.
• $pid (int): Page index. Omit or set it to -1 for the current page.

Returns: static

Throws:

• Exception

Source: src/Region.php:683

setY()

Set the absolute vertical cursor position for the current region.

public setY(float $ypos, int $pid = -1): static

Parameters:

• $ypos (float): Y position relative to the page coordinates.
• $pid (int): Page index. Omit or set it to -1 for the current page.

Returns: static

Throws:

• Exception

Source: src/Region.php:707

Inherited members

From Box

• BOX: Page box names.
• setBox(): Set page boundaries.
• setPageBoxes(): Initialize page boxes.
• swapCoordinates(): Swap X and Y coordinates of page boxes (change page boxes orientation).

From Format

• FORMAT: Array of page formats (width, height).
• UNITRATIO: Array of conversion ratios relative to points.
• convertPoints(): Convert Points to another unit.
• getPageFormatSize(): Get page dimensions.
• getPageOrientation(): Returns the page orientation.
• getPageOrientedSize(): Returns the page dimensions oriented as specified.
• getUnitRatio(): Get the unit ratio for the specified unit of measure.

From Mode

• getDisplay(): Get the canonical page display mode.
• getLayout(): Get the canonical page layout name.

From Settings

• EPS: Epsilon precision used to compare floating point values.
• MAX_COLUMNS: Maximum number of equal vertical columns a page can be split into.
• PAGE_NUM: Alias for page number.
• PAGE_TOT: Alias for total number of pages in a group.
• getPageID(): Return the current page ID.
• sanitizeAnnotRefs(): Sanitize or set the annotation references.
• sanitizeBoxData(): Sanitize or set the page boxes containing the page boundaries.
• sanitizeContent(): Sanitize or set the page content.
• sanitizeGroup(): Sanitize or set the page group.
• sanitizeMargins(): Sanitize or set the page margins.
• sanitizePageFormat(): Sanitize or set the page format.
• sanitizePageNumber(): Sanitize or set the page number.
• sanitizeRegions(): Sanitize or set the page regions (columns).
• sanitizeRotation(): Sanitize or set the page rotation.
• sanitizeTime(): Sanitize or set the page modification time.
• sanitizeTransitions(): Sanitize or set the page transitions.
• sanitizeZoom(): Sanitize or set the page preferred zoom (magnification) factor.