Skip to content

page_builder

page_builder #

PageBuilder — a function that builds components becomes a function returning a Page.

  1. Calling the decorated function opens a Build, then builds and opens a fresh VStack as the root, so every component the body constructs attaches to the innermost open stack, the way procedure nodes attach to the recording context under @cg.procedure.
  2. When the body returns, the root and the title a Title set become the Page the wrapper returns; the wrapper is annotated to return Page, so @cgserver.page and @cg.pure_function accept it as they would a hand-written page function.

PageBuilder #

Decorate a component-building function into one that returns its Page.

The body constructs components in document order; with on an HStack or VStack nests them; Title names the page. The body returns nothing.

@cg.ui.PageBuilder()
def overview(session: Session) -> None:
    cg.ui.Title(session.captured.date().isoformat())
    cg.ui.ImageViewer(session.photo)
    with cg.ui.HStack():
        cg.ui.Stat("Width", session.photo.width, unit="px")
        cg.ui.Stat("Height", session.photo.height, unit="px")


page = overview(session)
Source code in capturegraph-lib/capturegraph/ui/page_builder.py 
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
class PageBuilder:
    """Decorate a component-building function into one that returns its ``Page``.

    The body constructs components in document order; ``with`` on an
    ``HStack`` or ``VStack`` nests them; ``Title`` names the page. The body
    returns nothing.

    ```python
    @cg.ui.PageBuilder()
    def overview(session: Session) -> None:
        cg.ui.Title(session.captured.date().isoformat())
        cg.ui.ImageViewer(session.photo)
        with cg.ui.HStack():
            cg.ui.Stat("Width", session.photo.width, unit="px")
            cg.ui.Stat("Height", session.photo.height, unit="px")


    page = overview(session)
    ```
    """

    def __call__[**P](self, func: Callable[P, None]) -> Callable[P, Page]:
        """``func`` wrapped to return the page its body built."""

        @functools.wraps(func)
        def build(*args: P.args, **kwargs: P.kwargs) -> Page:
            with Build() as building:
                root = VStack()
                building.push(root)
                func(*args, **kwargs)
            return Page.declare(root, title=building.title)

        build.__annotations__ = {**func.__annotations__, "return": Page}
        return build

__call__(func) #

func wrapped to return the page its body built.

Source code in capturegraph-lib/capturegraph/ui/page_builder.py 
46
47
48
49
50
51
52
53
54
55
56
57
58
def __call__[**P](self, func: Callable[P, None]) -> Callable[P, Page]:
    """``func`` wrapped to return the page its body built."""

    @functools.wraps(func)
    def build(*args: P.args, **kwargs: P.kwargs) -> Page:
        with Build() as building:
            root = VStack()
            building.push(root)
            func(*args, **kwargs)
        return Page.declare(root, title=building.title)

    build.__annotations__ = {**func.__annotations__, "return": Page}
    return build