API

AtLeast(length)

A minimum Length, for properties where Word may grow a measure past the given value to fit its content, such as the line of a Spacing.

AutomaticDefault{T}

Signals that either a value of type T is accepted or automatic, for which the viewer application chooses appropriate behavior.

Body(sections::Vector{Section})

The document body which contains the sections of the document.

Bookmark(name::String, children::AbstractVector = [])

Marks its children with a bookmark called name, which a Hyperlink or PageReference can point at. A bookmark without children marks a position in the document rather than a range of content.

Bookmarks can hold run elements, in which case they belong into a Paragraph, or block elements, in which case they go wherever a Paragraph can go. Names must be unique within a document, contain no whitespace and be at most 40 characters long, because Word silently truncates longer names and replaces whitespace with underscores, which would break every link pointing at them.

Column(; [width, space])

Describes a single column. width sets the column width, and space sets the whitespace after the column (before the next column).

See also: Columns

Columns(; kwargs...)

Sets the columns for a Section.

Keyword arguments

ComplexField(instruction::String; dirty = true)

Creates a complex field with a specific instruction that has an effect in the viewer application. If dirty === true, the field will be reevaluated when opening the docx file.

The ComplexField element must be paired with a following ComplexFieldEnd. For some purposes, other elements may appear between the two.

ComplexFieldEnd()

Every ComplexField element must be paired with this element.

DocDefaults(; kwargs...)

Holds the default run and paragraph properties for a Document. All properties are optional.

Keyword arguments

Document(body::Body; styles::Styles = Styles([]))

The root object containing all other elements that make up the document.

Fonts(; [ascii::String, high_ansi::String, complex::String, east_asia::String])
Fonts(font; kwargs...)

Specifies fonts to use for four different Unicode character ranges. The convenience constructor with one positional argument changes the font for ascii and high_ansi, which should usually be the same.

Footer(children::AbstractVector)

Contains elements for use in a Section's footer section. Each element should satisfy is_block_element.

Footers(; default::Footer, [first::Footer, even::Footer])

Holds information about the Footers of a Section. A default Footer must always be specified. If first is set, the first page of the section gets this separate footer. If even is set, every even-numbered page of the section gets this separate footer, making default effectively mean odd.

Header(children::AbstractVector)

Contains elements for use in a Section's header section. Each element should satisfy is_block_element.

Headers(; default::Header, [first::Header, even::Header])

Holds information about the Headers of a Section. A default Header must always be specified. If first is set, the first page of the section gets this separate header. If even is set, every even-numbered page of the section gets this separate header, making default effectively mean odd.

HexColor(s::String)

A color in hexadecimal RGB format, for example "FF0000" for red or "333333" for a dark gray.

Hyperlink(children::AbstractVector; anchor::String)

Turns its children into a link that jumps to the Bookmark called anchor, which must exist somewhere in the document.

The link is not styled differently from the surrounding text unless a style says so, because Word's blue underlined look comes from its built-in Hyperlink character style, which this package does not add to a document.

Image(m::MIME, object)

Represents an image of MIME type m that can be written to an appropriate file when writing out a docx document. The object needs to have a show method for m defined for the default behavior to work.

Image(path::String)

Create an Image pointing to the file at path. The MIME type is determined by file extension.

InlineDrawing{T}(; image::T, width::EMU, height::EMU)

Create an InlineDrawing object which, as the name implies, can be placed inline with text inside Runs.

WriteDocx supports different types T for the image argument. If T is a String, image is treated as the file path to an existing .png or .svg image. You can pass an Image object which can hold a reference to an object that can be written to a file with the desired MIME type at render time. You can also use SVGWithPNGFallback to place .svg images with better fallback behavior.

Width and height of the placed image are set via width and height, note that you have to determine these values yourself for any image you place, a correct aspect ratio will not be determined automatically.

LineSpacing(value)

The height of the lines in a paragraph, which is one of:

• a Percent of single spacing, so 150percent is one-and-a-half spacing
• a Length, for lines of exactly that height, such as 14pt
• an AtLeast, for a height that may grow to fit tall content

The bare value can be passed as the line of a Spacing as well, so line = 150percent and line = LineSpacing(150percent) are equivalent.

PageMargins(; top, right, bottom, left, kwargs...)

Describes page margins in a Section.

Keyword arguments

PageReference(anchor::String)

Shows the number of the page that the Bookmark called anchor is on, and links to it. Word computes the number when it recalculates the document's fields, so it is correct in print and export but may show as empty until then.

PageSize(width, height)

The size of a page. If width > height, the page is set to PageOrientation.landscape.

Paragraph(children::Vector{Any}, properties::ParagraphProperties)
Paragraph(children::AbstractVector; kwargs...)

A paragraph can contain children that satisfy is_run_element. The second convenience constructor forwards all keyword arguments to ParagraphProperties.

ParagraphBorder(; kwargs...)

Holds properties for one border of a table cell and is used by ParagraphBorders. All properties are optional.

Keyword arguments

ParagraphBorders(; kwargs...)

Holds properties for the borders of a Paragraph and is used by ParagraphProperties. All properties are optional.

Keyword arguments

ParagraphProperties(; kwargs...)

Holds properties for a Paragraph. All properties are optional.

Keyword arguments

Percent(value::Float64)

A relative measure for the properties where Word takes a proportion of some other quantity instead of an absolute Length, such as the width of a TableProperties or the line of a Spacing. For convenience, the constant percent is provided for Percent(1).

Run(children::AbstractVector, properties::RunProperties)
Run(children::AbstractVector; kwargs...)

Create a Run with children who all have to satisfy is_inline_element.

The second convenience constructor forwards all keyword arguments to the RunProperties constructor.

RunProperties(; kwargs...)

Holds properties for a Run. All properties are optional.

Keyword arguments

SVGWithPNGFallback(; svg, png)

Create a SVGWithPNGFallback for the svg svg and the fallback png. If svg or png are AbstractStrings, they will be treated as paths to image files. Otherwise, they should be Images with the appropriate MIME types. Use SVGImage and PNGImage as shortcuts to create these.

Word Online and other services like Slack preview don't work when a simple svg file is added via InlineDrawing{String}. SVGWithPNGFallback supplies a fallback png file which will be used for display in those situations. Note that it is your responsibility to check whether the png file is an accurate replacement for the svg.

Section(children::AbstractVector, properties::SectionProperties)
Section(children::AbstractVector; kwargs...)

A section of a document contains a vector of children which should satisfy is_block_element. The docx format does not have a concept of individual pages, although Section might be thought of as a group of related "page"s.

The content within a document's Sections is laid out into actual pages dynamically in the viewer application. A Section has SectionProperties which then control how those pages are rendered.

The second convenience constructor forwards all keyword arguments to the SectionProperties constructor.

SectionProperties(; kwargs...)

Holds properties for a Section.

Keyword arguments

Shading(; pattern = ShadingPattern.clear, fill = automatic, color = automatic)

Specifies the background shading of an element, where fill is the background color, color the foreground color of the pattern drawn on top of it.

Spacing(; before = nothing, after = nothing, line = nothing)

Holds the spacing properties of a Paragraph, where before and after are the space above and below it and line is its LineSpacing.

Styles(styles::Vector{Style}, doc_defaults::DocDefaults)
Styles(styles; kwargs...)

Holds style information for a Document. The second convenience constructor forwards all keyword arguments to DocDefaults.

Tab()

A tab character in a Run, which advances to the next TabStop of the surrounding Paragraph.

TabStop(position::Length; alignment = TabAlignment.start, leader = TabLeader.none)

A tab stop of a ParagraphProperties, where position is measured from the left margin. A Tab in the paragraph's text advances to the next stop, filling the jumped space with the leader character.

Table(rows::Vector{TableRow}, properties::TableProperties; grid = Twip[])
Table(rows; grid = Twip[], kwargs...)

A table which can hold a vector of TableRows. The grid holds the widths of the table's columns, which Word lays the cells out at if properties.layout is TableLayout.fixed, so grid = [4cm, 2cm] describes a two-column table. The second convenience constructor forwards all remaining keyword arguments to TableProperties.

TableCell(children::Vector{Any}, properties::TableCellProperties)
TableCell(children::AbstractVector; kwargs...)

One cell of a Table which can hold elements that satisfy is_block_element. The second convenience constructor forwards all keyword arguments to TableCellProperties.

TableCellBorder(; kwargs...)

Holds properties for one border of a table cell and is used by TableCellBorders. All properties are optional.

Keyword arguments

TableCellBorders(; kwargs...)

Holds properties for the borders of a TableCell and is used by TableCellProperties. All properties are optional.

Keyword arguments

TableCellMargins(; kwargs...)

Holds properties for the margins of a TableCell and is used by TableCellProperties. All properties are optional.

Keyword arguments

TableCellProperties(; kwargs...)

Holds properties for a TableCell. All properties are optional.

Keyword arguments

TableCellMargins(; kwargs...)

Holds properties for the default margins of all TableCells in a Table and is used by TableProperties. All properties are optional.

Keyword arguments

TableProperties(; kwargs...)

Holds properties for a Table. All properties are optional.

Keyword arguments

TableRow(cells::Vector{TableCell}, properties::TableRowProperties)
TableRow(cells; kwargs...)

One row of a Table which can hold a vector of TableCells. The second convenience constructor forwards all keyword arguments to TableRowProperties.

TableRowProperties(; kwargs...)

Holds properties for a TableRow. All properties are optional.

Keyword arguments

TableWidth(value)

The width of a Table or a TableCell, which is one of:

• a Percent of the surrounding text column for a table, or of the table for a cell, so 100percent makes a table fill the column
• a Length, for an absolute width such as 12cm
• automatic, which sizes the table or cell to fit its content

The bare value can be passed as a width as well, so width = 100percent and width = TableWidth(100percent) are equivalent.

Underline(; color = automatic, pattern = UnderlinePattern.single)

Specifies how text is underlined. Use pattern = UnderlinePattern.none to switch off an underline inherited from a style.

Centimeter(value::Float64) <: Length

A length of one centimeter, or 1/2.54 of an inch. For convenience, the constants cm and mm are provided for Centimeter(1) and Centimeter(0.1), respectively.

EMU(value::Float64) <: Length

A length of one English metric unit, or 1/914400 of an inch. For convenience, the constant emu is provided for EMU(1).

EighthPoint(value::Float64) <: Length

A length of one eight of a typographic point, or 1/576 of an inch. For convenience, the constant eighthpt is provided for EighthPoint(1).

HalfPoint(value::Float64) <: Length

A length of a half typographic point, or 1/144 of an inch. For convenience, the constant halfpt is provided for HalfPoint(1).

Inch(value::Float64) <: Length

A length of one inch. For convenience, the constant inch is provided for Inch(1).

Length

The supertype for all length metrics that WriteDocx can handle. Each Length can be converted to any other Length and can therefore be passed to any struct that stores a specific length type.

Point(value::Float64) <: Length

A length of one typographic point, or 1/72 of an inch. For convenience, the constant pt is provided for Point(1).

Twip(value::Float64) <: Length

A length of one twip, or twentieth of a point, or 1/1440 of an inch. For convenience, the constant twip is provided for Twip(1).

BorderStyle

An enum that can be either single, dash_dot_stroked, dashed, dash_small_gap, dot_dash, dot_dot_dash, dotted, double, double_wave, inset, nil, none, outset, thick, thick_thin_large_gap, thick_thin_medium_gap, thick_thin_small_gap, thin_thick_large_gap, thin_thick_medium_gap, thin_thick_small_gap, thin_thick_thin_large_gap, thin_thick_thin_medium_gap, thin_thick_thin_small_gap, three_d_emboss, three_d_engrave, triple or wave

Justification

An enum that can be either start, stop, center, both or distribute.

UnderlinePattern

An enum that can be either dash, dash_dot_dot_heavy, dash_dot_heavy, dashed_heavy, dash_long, dash_long_heavy, dot_dash, dot_dot_dash, dotted, dotted_heavy, double, none, single, thick, wave, wavy_double, wavy_heavy or words.

ShadingPattern

An enum that can be either clear, diag_cross, diag_stripe, horz_cross, horz_stripe, nil, thin_diag_cross, or solid.

VerticalAlign

An enum that can be bottom, center or top.

VerticalAlignment

An enum that can be either baseline, subscript or superscript.

TableLayout

An enum that can be either autofit or fixed. With fixed, Word lays the columns out at the widths given by the table's grid, with autofit it sizes them to their content.

TabAlignment

An enum that can be either start, stop, center, decimal, bar or clear, where clear removes a tab stop that the paragraph's style defines.

TabLeader

An enum that can be either none, dot, hyphen, underscore, heavy or middle_dot, the character with which Word fills the space a tab jumps.