Images

Putting a picture in a document takes two steps that are easy to conflate. doc.AddImage stores the image data in the package and returns a common.ImageRef; one of the drawing calls on a run is what makes it appear on a page. An image added but never drawn is carried in the file and shows up nowhere, which is why a document can be several hundred kilobytes larger than its visible content explains.

The reference is what ties the two steps together. It carries the relationship ID that AddImage assigned, and both drawing calls reject a reference without one. Call AddImage once per distinct image and reuse the reference wherever that image appears, or you will write the same bytes into the file repeatedly.

The second choice is inline against anchored. run.AddDrawingInline puts the image in the text flow like an oversized character, so it moves as the text around it moves and nothing sits beside it. run.AddDrawingAnchored positions it relative to the page, margin, column or paragraph, and the text flows around it according to one of seven wrap modes. Anchored drawings are also the only ones that can carry effects: shadow, glow and the rest are methods on AnchoredDrawing, and InlineDrawing has only SetSize.

Nothing scales an image for you. Both drawing types default to one point per pixel of the source, so a screenshot arrives comically large, and SetSize takes width and height independently without preserving the aspect ratio. ImageRef.RelativeHeight and RelativeWidth are there to derive the other dimension. Supported source formats are PNG, JPEG, GIF and EMF.

Watermarks are a different mechanism entirely. They are VML shapes placed in the document’s headers rather than drawings added to a run, which is what makes them repeat on every page and sit behind the body text. Both watermark types create a default header if the document has none.

Charts are worth a warning. UniOffice builds live, editable charts in spreadsheets, but the document package has no exported chart API. The guide here renders a chart to an image and inserts that, so what lands in the Word file is a picture, not something a reader can edit or refresh.

Where to look