quds_reports library

Flutter band-report designer, together with the report engine.

import 'package:quds_office_editor/quds_reports.dart';

final ReportDesignerController controller =
    ReportDesignerController.fromXml(xml);
QudsReportDesigner(
  controller: controller,
  onExport: (ReportExportFormat format, Uint8List bytes) {},
);

This library is the designer (canvas, inspector, toolbox, preview, data explorer, bundled fonts, and ready-made templates) plus everything in package:quds_reports/quds_reports.dart: QudsReportEngine, .qrep packages, expressions, and PDF / XLSX / DOCX export. A server or CLI host that does not use Flutter depends on quds_reports alone.

Classes

ArabicCurrency: Currency definition for ArabicTafqeet and currency: formats.
ArabicNounForms: Grammatical forms of a counted Arabic noun (معدود).
ArabicTafqeet: Converts numbers to grammatical Arabic words.
BrokenLine: A laid-out line of shaped visual glyphs.
EnglishCurrency: English names of a currency's main unit and subunit.
EnglishWords: English words: EnglishWords.amount(1250.5, 'USD') → One thousand two hundred fifty US dollars and fifty cents only.
InlineCellEditor: Floating IME session synchronized with an in-place edit string.
OfficeStrings: Accessible labels for screen readers and chrome (English / Arabic).
OfficeSurfaceConfig: Host-facing chrome and interaction flags for an embedded surface.
OfficeTheme: Visual tokens for every custom RenderBox surface.
PdfSaveOptions: Options applied when compiling a PDF (PdfDocument.save).
QudsExpressionEngine: Evaluates ReportExpressions and interpolates ReportTemplateText.
QudsReportDesigner: Band report designer: toolbar, an insert panel, the design canvas or live preview, and the property inspector, all painted by custom RenderBoxes.
QudsReportEngine: Band report engine.
QudsReportXmlParser: Reads <QudsReport> XML into a ReportTemplate.
QudsReportXmlWriter: Serializes a ReportTemplate back to .qrep XML.
RenderReportDataExplorer: RenderBox behind ReportDataExplorer.
RenderReportDesigner: RenderBox behind ReportDesignerCanvas.
RenderReportInspector: RenderBox behind ReportInspector: collapsible sections with icon actions, switches, segmented buttons, steppers, preset combos, a color palette, the variables explorer, image and font cards with previews, a font picker that renders each family, and inline text editing.
RenderReportPreview: RenderBox behind ReportPreviewSurface.
RenderReportProblems: RenderBox behind ReportProblemsPanel.
RenderReportToolbar: RenderBox behind ReportToolbar.
RenderReportToolbox: RenderBox behind ReportToolbox.
RenderReportToolboxCard: RenderBox behind ReportToolboxCard.
ReportBand: One band section with its elements.
ReportBarcodeElement: Code 128 or QR symbol.
ReportBarcodePrimitive: Barcode modules painted inside bounds.
ReportBinary: Raw bytes (images bound from data such as {{Data.logo}}).
ReportBinaryExpr: Infix operator.
ReportBool: Boolean value.
ReportBundledFonts: Loads the TrueType faces bundled with the editor package into a ReportFontRegistry, so the report preview and exports embed real fonts (Liberation for Latin, Noto Naskh for Arabic) without host font files.
ReportCallExpr: NAME(args…)
ReportCanvasContextHit: Right-click target on the band canvas.
ReportChartData: Aggregated chart content ready to draw or export.
ReportChartElement: Vector chart fed by a data set (one category per distinct category value, one series per series entry) or by static points.
ReportChartPoint: <Point label="…" value="…" color="…"/> — a static data point.
ReportChartRenderer: Turns ReportChartData into page primitives inside a box.
ReportChartSeries: <Series name="…" value="…" color="…"/> — one plotted measure.
ReportChartSeriesData: One resolved series: a value per category.
ReportColor: Opaque or translucent sRGB color.
ReportCompleter: Computes completions from the template, the band being edited, and the data the preview uses (field names come from real or mock rows).
ReportCompletionItem: One suggestion.
ReportCompletionPopup: Painted suggestion list for {{ }} completions, shared by the design canvas and the inspector. Coordinates are the host's local pixels.
ReportCompletionResult: Suggestions for one caret position.
ReportConditionalExpr: cond ? a : b
ReportCrosstabElement: Pivot of one data set: one row per rowField, one column per columnField.
ReportCsv: Comma-separated values: header row + data rows.
ReportData: JSON-like data a host feeds to a report: nested maps for records, lists of maps for tables.
ReportDataColumn: One column of a ReportDataTable. A column with an expression is calculated for every row (qty * price) when the report is generated.
ReportDataColumnView: A column of the data explorer: declared in the template's ReportDataSchema (inSchema) or found in the data.
ReportDataContextHit: A right-click in the data explorer (the hit is selected first).
ReportDataExplorer: Data explorer of the report designer: the tables and fields the report is generated from, shown as an editable grid (like a BI data view).
ReportDataField: A single value outside the tables (Data.customer.name).
ReportDataSchema: What a report expects from its data (<DataSchema>), saved with the template so hosts and designers agree on names and types.
ReportDataTable: A data set (<Table name="items">): the rows a detail band, table, or chart repeats over.
ReportDataTableView: A table of the data explorer: a data set (items), or with an empty name the report's single-value fields (one row per field).
ReportDate: Date / time value.
ReportDesignerCanvas: Band canvas of the report designer.
ReportDesignerController: State of a report designer: template, selection, undo history, tools, inline editors, and the cached live preview.
ReportDesignerStrings: User-interface language of the report designer.
ReportDesignLayout: Geometry of the band canvas in document points: x is the physical page x, y stacks the bands top to bottom with a caption strip before each.
ReportDesignSlot: One band on the design surface: a caption strip above its body.
ReportDeviceFonts: Fonts installed on the device, listed on the inspector's Fonts page so they can be embedded in the report.
ReportDeviceFontScripts: A ReportDeviceFonts that also reports which writing systems each family covers, so font pickers preview it in its own script.
ReportDiagnostic: One validation finding with a template path (Bands/Detail/Table[0]).
ReportDiagnosticTarget: Where in a template a ReportDiagnostic points, parsed from its ReportDiagnostic.path (Bands/Detail/Text[2]@visibleWhen, Variables/total, DataSchema/items/amount, …).
ReportDocumentLayout: Complete paginated report.
ReportDocxWriter: Flow-based Word export.
ReportElement: Base of every positioned element.
ReportElementPainter: Paints template elements on the band canvas: text with its placeholders highlighted, tables as header + template row + totals, real barcode symbols, images, and shapes. Coordinates are document points.
ReportExpr: Expression syntax tree.
ReportExpression: A parsed expression with its source text.
ReportExpressionSegment: {{ expression | format }}
ReportFlowBand: A printed band with its positioned items (y relative to the band top).
ReportFlowCell: Evaluated table cell.
ReportFlowChart: Chart with its aggregated data (XLSX / DOCX write native charts).
ReportFlowEntry: Logical content of a band instance, independent of page geometry.
ReportFlowImage: Image element with resolved bytes.
ReportFlowItem: Positioned item inside a ReportFlowBand.
ReportFlowRule: Horizontal rule (a line shape flatter than it is wide).
ReportFlowSpan: One styled slice inside a ReportFlowText.
ReportFlowTableBlock: Table printed atomically inside a non-detail band.
ReportFlowTableRow: Table header, body row, or totals row.
ReportFlowText: Evaluated text element.
ReportFontFamily: Regular, bold, italic, and bold-italic faces of one family.
ReportFontFile: Reads TrueType headers without parsing glyphs, so a host can scan installed fonts quickly and reports only embed files they can draw.
ReportFontFileInfo: What a TrueType file declares in its name, OS/2, head and cmap tables.
ReportFontFiles: Regular and bold TrueType files of one embedded family. At least one is set; a missing face falls back to the other.
ReportFontRegistry: Families available to the report engine.
ReportFontSpec: Text style resolved for shaping.
ReportFormatDefaults: Locale-ish defaults applied when a format omits details.
ReportFormatter: Formats ReportValues for display.
ReportFunctionInfo: Built-in function documentation.
ReportGenerator: Lays out a ReportTemplate against data.
ReportGroupInfo: Current group while evaluating group bands and rows.
ReportIdentifierExpr: Bare name (item, System, total).
ReportImageElement: Picture from embedded bytes, a named resource, or a data binding.
ReportImagePrimitive: Raster image placed at imageRect, clipped to bounds.
ReportIndexExpr: target[index]
ReportInspector: Property inspector of the report designer.
ReportInspectorChoice: Choice-property click: hosts show the options and call ReportDesignerController.setProperty.
ReportLayoutPainter: Paints ReportDocumentLayout pages on a Flutter canvas.
ReportLinePrimitive: Straight line.
ReportList: Ordered list (data set rows, projections such as items.total).
ReportLiteralExpr: Constant.
ReportLiteralSegment: Literal text between expressions.
ReportMargins: Page margins in points.
ReportMemberExpr: target.name
ReportMockData: Builds plausible data for every binding a template uses, so a designer can preview pagination, grouping, and totals before real data exists.
ReportNull: Absent / null value.
ReportNumber: Integer or floating point number.
ReportPackage: A .qrep report file: xml layout plus pre-saved images and fonts.
ReportPageLayout: One output page.
ReportPageSize: Named page size in points (portrait).
ReportParseResult: Parse output: the template (best effort) plus diagnostics.
ReportPathPrimitive: Polyline or polygon (chart lines, areas, and pie wedges).
ReportPdfWriter: Writes report layouts with the writer-side PdfDocument.
ReportPreviewSurface: Paginated live preview of a ReportDocumentLayout.
ReportPrimitive: Drawing operation on a page. Coordinates are page points, y down.
ReportProblemsPanel: Problems panel of the report designer: every error and warning in the report (ReportDesignerController.problems) with what kind of problem it is and where. Clicking one takes the user there (ReportDesignerController.revealDiagnostic); the close button sets ReportDesignerController.problemsOpen to false.
ReportProperty: One inspector row. Values are strings so every kind shares one editor; ReportDesignerController.setProperty parses them back with type checks.
ReportRecord: Named fields (one data row, the root data object, System, Variables).
ReportRect: Axis-aligned rectangle in points.
ReportRectPrimitive: Rectangle, rounded rectangle, or ellipse.
ReportScope: Everything an expression can see.
ReportSection: One data region: optional group header, a detail band, optional group footer.
ReportShapedChar: Shaped code point with its advance multiplier (lam-alef ligatures).
ReportShapedText: Wrapped, shaped paragraph.
ReportShapeElement: Line, rectangle, rounded rectangle, or ellipse.
ReportShapeFeature: One named region (a country, a district, a custom polygon).
ReportShapeFile: A shape file read for a report: the layer to embed, and the attribute whose values are the region keys (null for a .qmap, which already stores them).
ReportShapeLayer: A set of regions drawn as one map.
ReportShapeRing: One closed ring. A hole is drawn in the ocean color.
ReportShapes: world and countries are the bundled atlas. Anything else is an embedded shape layer.
ReportSubreportElement: Renders another template stored at subreports/<name>.xml in the package.
ReportSystemInfo: Values exposed as System.*.
ReportTableCell: <Cell field="item.code" format="…"/> or <Cell text="{{…}}"/>.
ReportTableColumn: <Column width="…" header="…" align="…"/>.
ReportTableElement: Repeating grid bound to the detail data set.
ReportTemplate: A complete report template (<QudsReport>).
ReportTemplateArt: Sample pictures embedded in the ready-made templates (ReportTemplates).
ReportTemplateInfo: One catalog entry: XML plus the sample data, images, and fonts it needs.
ReportTemplateLibrary: The ready-made report templates: .qrep files in this package's templates/ folder, each with a template.json manifest.
ReportTemplateManifest: Catalog details of a template .qrep, saved in the package as entry (template.json). A report file that carries one is offered as a starting point (ReportTemplateInfo.fromPackage).
ReportTemplates: Catalog of professional starting points, grouped by ReportTemplateCategory; every family ships Arabic and English versions.
ReportTemplateText: Text with {{ … }} placeholders, parsed once and cached by source.
ReportText: Text value.
ReportTextElement: Static or bound text.
ReportTextLine: Logical slice of the source text placed on one line.
ReportTextPrimitive: Shaped paragraph inside contentRect.
ReportTextRun: One styled slice of a ReportTextElement.
ReportTextSegment: One piece of an interpolated template string.
ReportTextShaper: Shapes and wraps text with the same metrics the PDF writer paints.
ReportTextStyle: Font and color overrides for text. Null fields inherit report defaults.
ReportToolbar: Designer toolbar painted on a RenderBox; wraps onto more rows when narrow.
ReportToolbarItem: One toolbar button.
ReportToolbox: Vertical insert panel. Hover is reported so the designer can paint a card beside the panel; the card is wider than this box.
ReportToolboxCard: Hover card: name, a drawing of what the tool inserts, and a sentence.
ReportToolboxEntry: One insert tool in the side panel.
ReportToolboxHover: The button currently under the pointer.
ReportUnaryExpr: Prefix operator.
ReportUnits: Length parsing and formatting. All engine geometry is in points.
ReportValue: A value bound from report data or produced by an expression.
ReportVariable: Value stored in the template itself (<Variables>), referenced as {{Variables.name}}. Host values passed to the engine override it.
ReportXlsxWriter: Data-oriented Excel export of a laid-out report.
SfntFont: Parsed TrueType / OpenType SFNT font.
ShapedGlyph: Shaped visual glyph with document metrics in points.
TafqeetOptions: Output options for ArabicTafqeet.amount.
WorldCountries: Bundled admin-0 countries, keyed by ISO code and by English, Arabic, and French names.

Enums

OfficeDensity: Control spacing for host chrome (ribbons stay in the host).
OfficeFormFactor: Target form-factor. automatic is resolved from layout constraints.
OfficeInteractionMode: How the host wants the surface to behave when embedded.
ReportAlignAction: Alignment and sizing commands for the selection.
ReportBandKind: Band sections, in canonical document order.
ReportBarcodeType: Barcode symbology.
ReportBinaryOp: Binary operators, lowest precedence last in the parser.
ReportChartAggregate: How rows sharing a category are combined into one chart value.
ReportChartSort: Category order after aggregation.
ReportChartType: Chart family drawn by a ReportChartElement.
ReportCompletionKind: What a completion inserts.
ReportCoordinateOrigin: Origin of element x coordinates.
ReportDataArea: Part of the data explorer under a context click.
ReportDataType: Column or field type. Text values fed by a host are converted to it ('12.5' → 12.5, '2026-10-12' → a date).
ReportDesignMode: Designer surface: the band canvas or the paginated live preview.
ReportDesignTool: Pointer tool of the report designer canvas.
ReportDiagnosticKind: Broad nature of a ReportDiagnostic, for grouping and explaining it.
ReportDiagnosticPlace: Part of a report a ReportDiagnostic points at.
ReportDiagnosticSeverity: Severity of a ReportDiagnostic.
ReportElementType: Element kind (mirrors type="…").
ReportExportFormat: Output format of QudsReportEngine.export.
ReportImageFit: Image scaling.
ReportImageFormat: Image format accepted inside a .qrep package.
ReportInspectorPage: Pages of the report inspector.
ReportLineStyle: Stroke pattern.
ReportOrientation: Page orientation.
ReportProductArt: Products drawn by ReportTemplateArt.product.
ReportPropertyKind: How the inspector edits a property value.
ReportScript: Writing systems a font preview can be shown in, each with sample text and the code points that show a font covers it.
ReportSeriesStyle: How one combo series is drawn.
ReportShapeKind: Shape kind.
ReportTemplateCategory: What a template is for (designer grouping).
ReportTemplateLanguage: Language a template prints in.
ReportTextAlign: Horizontal text alignment. start/end follow the text direction.
ReportTextDirection: Paragraph direction override.
ReportToolbarIcon: Vector icons drawn by ReportToolbar.
ReportUnaryOp: Unary operators.
ReportUnit: Length unit accepted by template attributes such as x="10mm".
ReportVariableType: <Var name="…" value="…"/>. value may contain {{ }} placeholders. Data type of a template variable.
ReportVerticalAlign: Vertical alignment inside an element box.

Functions

compareReportValues(ReportValue a, ReportValue b) → int: Ordering used by MIN, MAX, comparisons, and group sorting.
reportEnumByName<T extends Enum>(List<T> values, String? name) → T?: Enum value for name ignoring case, -, and _.
reportStyleFont(ReportTextStyle style, ReportFontSpec base) → ReportFontSpec: style over base. Empty fields keep base.
reportValuesEqual(ReportValue a, ReportValue b) → bool: Loose equality used by == in expressions ('5' == 5 is true).

Typedefs

ReportDataPicker = Future<({String name, String text})?> Function(): Asks the host for a data file (.json or .csv); completes with null when cancelled.
ReportFontPicker = Future<List<({Uint8List bytes, String name})>?> Function(): Asks the host for TrueType files (.ttf); completes with null or an empty list when cancelled.
ReportFunction = ReportValue Function(List<ReportValue> arguments): Host-provided function: MYFN(a, b) receives evaluated arguments.
ReportImagePicker = Future<({Uint8List bytes, String name})?> Function(): Asks the host for a PNG / JPEG file; completes with null when cancelled.
ReportShapePicker = Future<({Uint8List? attributes, Uint8List bytes, String name})?> Function(): Asks the host for a shapefile (.shp, with attributes the .dbf), GeoJSON, or a .qmap layer. Completes with null when cancelled.
TableRows = ({double body, double footer, double header}): Header, body, and totals row heights of a table on the canvas.

Exceptions / Errors

ReportDataException: Thrown for malformed JSON or CSV data.
ReportElementException: Thrown by the named-element API (QudsReportEngine.element and the setters) when no element has the name or it is of another type.
ReportExpressionException: Thrown for malformed expressions or evaluation failures.
ReportFontException: Thrown when a font cannot be used for embedding.
ReportFormatException: Thrown when a length or color attribute cannot be parsed.
ReportPackageException: Thrown when .qrep bytes are neither a valid package nor plain XML.
ReportShapeException: Thrown when shape bytes are not a shapefile, GeoJSON, or a shape layer.
ReportTemplateException: Thrown when a template has validation errors.
TafqeetException: Thrown for unknown currency codes or out-of-range amounts.

quds_reports library

Classes

Enums

Functions

Typedefs

Exceptions / Errors

quds_office_editor package

quds_reports library