API — ICoreEssentials/UI/Printing

The public contract of 3 header(s) under ICoreEssentials/UI/Printing — 3 class/struct definition(s), 24 declaration(s). Each section shows the header's banner and its public (and protected-virtual) surface exactly as the file writes it.

ICorePrintDialog.h#

ICoreEssentials/UI/Printing/ICorePrintDialog.h

ICorePrintDialog#

ICorePrintDialog.h:21 · class · pImpl · 6 declaration(s)

The operating system's own print panel — NSPrintPanel on macOS, the common print dialog on Windows, the CUPS/GTK panel on Linux — so the paper sizes, the tray and the queue are the machine's, not a...

class ICorePrintDialog {
public:
    ICorePrintDialog(ICorePrinter& printer, ICoreNativeWidget* parent);
    ~ICorePrintDialog();

    // Holds a reference to the printer it was opened for; copying one would
    // say nothing useful, and nothing in the tree does.
    ICorePrintDialog(const ICorePrintDialog&) = delete;
    ICorePrintDialog& operator=(const ICorePrintDialog&) = delete;

    void setTitle(const ICoreString& title);

    // Runs the panel modally. True = accepted; cancelling is false, and is
    // the user's business, not a failure.
    [[nodiscard]] bool exec() const;

private:
    class Impl;                    // the two-line residue; state lives here
    std::unique_ptr<Impl> impl;
};

ICorePrinter.h#

ICoreEssentials/UI/Printing/ICorePrinter.h

⚠ NO class QPrinter; HERE ANY MORE (A9.23, 2026-08-24). The one member that needed the name is nativeState() below, and the typed accessor that casts it lives in UI/Backends/Qt/ICoreNativeHandleAccess.h with the rest of the family.

ICorePrinter#

ICorePrinter.h:23 · class · pImpl · 10 declaration(s)

A page-producing device: a print queue's job, or a PDF written to a file — the same page from the same code either way, which is the reason its one client (ICoreCanvasPrinter) insisted on QPrinter-...

class ICorePrinter {
public:
    ICorePrinter();
    ~ICorePrinter();

    ICorePrinter(const ICorePrinter&) = delete;
    ICorePrinter& operator=(const ICorePrinter&) = delete;

    // What the print queue and the PDF metadata call the job.
    void setDocumentName(const ICoreString& name);

    // The page's uniform white border, in millimeters, printed and PDF alike.
    // The device's own hardware margin is respected on top of it.
    void setPageMarginsMillimeters(double margin);

    // Route the job to a PDF file instead of a print queue.
    void setPdfOutput(const ICoreString& filePath);

    // The paper sizes this API has been asked for. Mapped by a switch in the
    // .cpp — the values are this project's own.
    enum class PageSize { A4 };
    void setPageSize(PageSize size);

    enum class Orientation { Portrait, Landscape };
    void setOrientation(Orientation orientation);

    // The seam: the backend's own printing object, as an opaque address. A
    // `QPrinter*` on the Qt backend. Call from a .cpp inside a sanctioned zone
    // only — ICorePrintDialog and ICorePrinterPainter are the intended callers,
    // and they spell it `icoreQt(printer)`.
    //
    // ⚠ THIS WAS `QPrinter& qt() const` UNTIL 2026-08-24 (A9.23). The change is
    // a SEAL, not a widening: the same object comes back, the cast simply moved
    // to the one file that is allowed to know the type. ⚠ NEVER NULL while the
    // printer lives — the Impl owns the device outright, so a caller may
    // dereference without checking, exactly as the reference form promised.
    [[nodiscard]] void* nativeState() const;

private:
    class Impl;                    // the two-line residue; state lives here
    std::unique_ptr<Impl> impl;
};

ICorePrinterPainter.h#

ICoreEssentials/UI/Printing/ICorePrinterPainter.h

ICorePrinterPainter#

ICorePrinterPainter.h:18 · class · pImpl · 8 declaration(s)

Draws onto a printer instead of onto a widget — ICorePixmapPainter's shape with a page under it.

class ICorePrinterPainter {
public:
    explicit ICorePrinterPainter(ICorePrinter& target);
    ~ICorePrinterPainter();

    ICorePrinterPainter(const ICorePrinterPainter&) = delete;
    ICorePrinterPainter& operator=(const ICorePrinterPainter&) = delete;

    // Whether the device opened. False: no printer, unwritable path, ...
    [[nodiscard]] bool isActive() const;

    // Valid only while isActive().
    ICorePainter& painter();

    // The paintable area — inside the page margins, in the device's units.
    [[nodiscard]] ICoreRect pageRect() const;

    // Finish the job. Returns whether it completed; idempotent (repeats hand
    // back the first result), and the destructor calls it too.
    bool end();

private:
    class Impl;                    // the two-line residue; state lives here
    std::unique_ptr<Impl> impl;
};