API

Note

Positional arguments are only considered part of the API where they are explicitly mentioned in the docstrings. Otherwise, the API is built on keyword arguments so that missing options and properties can be added in the future without breaking existing code.

Types

WriteDocx.AutomaticDefaultType
AutomaticDefault{T}

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

source
WriteDocx.BodyType
Body(sections::Vector{Section})

The document body which contains the sections of the document.

source
WriteDocx.ComplexFieldType
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.

source
WriteDocx.DocumentMethod
Document(body::Body; styles::Styles = Styles([]))

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

source
WriteDocx.FontsType
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.

source
WriteDocx.FooterType
Footer(children::AbstractVector)

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

source
WriteDocx.FootersType
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.

source
WriteDocx.HeaderType
Header(children::AbstractVector)

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

source
WriteDocx.HeadersType
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.

source
WriteDocx.HexColorType
HexColor(s::String)

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

source
WriteDocx.InlineDrawingType
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 a .png or .svg image. 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.

source
WriteDocx.PageSizeMethod
PageSize(width, height)

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

source
WriteDocx.ParagraphType
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.

source
WriteDocx.ParagraphBorderType
ParagraphBorder(; kwargs...)

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

Keyword arguments

KeywordDescription
color::AutomaticDefault{[HexColor]@ref}The color of the border.
shadow::BoolApplies a shadow effect if true.
space::PointThe spacing between border and content.
size::EighthPointThe thickness of the border line.
style::BorderStyle.TThe line style of the border.
source
WriteDocx.ParagraphBordersType
ParagraphBorders(; kwargs...)

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

Keyword arguments

KeywordDescription
top::ParagraphBorderThe properties of the top border.
bottom::ParagraphBorderThe properties of the bottom border.
left::ParagraphBorderThe properties of the left border.
right::ParagraphBorderThe properties of the right border.
between::ParagraphBorderThe properties of horizontal border that lies between adjacent paragraphs.
source
WriteDocx.ParagraphPropertiesType
ParagraphProperties(; kwargs...)

Holds properties for a Paragraph. All properties are optional.

Keyword arguments

KeywordDescription
style::StringThe name of the style applied to this Paragraph.
justification::Justification.TThe justification of the paragraph.
source
WriteDocx.RunType
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.

source
WriteDocx.RunPropertiesType
RunProperties(; kwargs...)

Holds properties for a Run. All properties are optional.

Keyword arguments

KeywordDescription
style::StringThe name of the style applied to this Run.
color::AutomaticDefault{HexColor}The color of the text.
size::HalfPointThe font size.
valign::VerticalAlignment.TWhether text is shown with baseline, superscript or subscript style.
fonts::FontsThe font settings for this text.
bold::BoolWhether text should be bold. Note that this works like a toggle when nested, turning boldness off again the second time it's true.
italic::BoolWhether text should be italic. Note that this works like a toggle when nested, turning italic style off again the second time it's true.
source
WriteDocx.SVGWithPNGFallbackType
SVGWithPNGFallback(; svg::String, png::String)

Create a SVGWithPNGFallback for the svg file at path svg and the fallback png file at path png.

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.

source
WriteDocx.SectionType
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.

source
WriteDocx.SectionPropertiesType
SectionProperties(; kwargs...)

Holds properties for a Section.

Keyword arguments

KeywordDescription
pagesize::PageSizeThe size of each page in the section.
valign::PageVerticalAlign.TThe vertical alignment of content on each page of the section.
headers::HeadersDefines the header content shown at the top of each page of the section.
footers::FootersDefines the footer content shown at the bottom of each page of the section.
source
WriteDocx.StylesType
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.

source
WriteDocx.TableType
Table(rows::Vector{TableRow}, properties::TableProperties)
Table(rows; kwargs...)

A table which can hold a vector of TableRows. The second convenience constructor forwards all keyword arguments to TableProperties.

source
WriteDocx.TableCellType
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.

source
WriteDocx.TableCellBorderType
TableCellBorder(; kwargs...)

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

Keyword arguments

KeywordDescription
color::AutomaticDefault{[HexColor]@ref}The color of the border.
shadow::BoolApplies a shadow effect if true.
space::PointThe spacing between border and content.
size::EighthPointThe thickness of the border line.
style::BorderStyle.TThe line style of the border.
source
WriteDocx.TableCellBordersType
TableCellBorders(; kwargs...)

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

Keyword arguments

KeywordDescription
top::TableCellBorderThe properties of the top border.
bottom::TableCellBorderThe properties of the bottom border.
start::TableCellBorderThe properties of the left border in left-to-right text.
stop::TableCellBorderThe properties of the right border in left-to-right text.
inside_h::TableCellBorderThe properties of the horizontal border that lies between adjacent cells.
inside_v::TableCellBorderThe properties of the vertical border that lies between adjacent cells.
tl2br::TableCellBorderThe properties of the diagonal border going from the top left to the bottom right corner.
tr2bl::TableCellBorderThe properties of the diagonal border going from the top right to the bottom left corner.
source
WriteDocx.TableCellPropertiesType
TableCellProperties(; kwargs...)

Holds properties for a TableCell. All properties are optional.

Keyword arguments

KeywordDescription
borders::TableCellBordersThe border style of the cell.
vertical_merge::BoolShould be set to true if this cell should be merged with the one above it.
gridspan::IntThe number of cells this cell should span in horizontal direction.
margins::TableCellMarginsThe margins of the cell.
valign::VerticalAlign.TThe vertical alignment of the content in the cell.
hide_mark::BoolIf true, hides the editor mark so that the table cell can fully collapse if it's empty.
source
WriteDocx.TablePropertiesType
TableProperties(; kwargs...)

Holds properties for a Table. All properties are optional.

Keyword arguments

KeywordDescription
margins::TableLevelCellMarginsMargins for all cells in the table.
spacing::TwipThe space between adjacent cells and the edges of the table.
justification::Justification.TThe justification of the table.
source
WriteDocx.TableRowPropertiesType
TableRowProperties(; kwargs...)

Holds properties for a TableRow. All properties are optional.

Keyword arguments

KeywordDescription
header::BoolWhether this row should be part of the header section which is repeated after every page break.
height::TableRowHeightThe height of the table row.
source

Lengths

WriteDocx.CentimeterType
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.

source
WriteDocx.EMUType
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).

source
WriteDocx.EighthPointType
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).

source
WriteDocx.HalfPointType
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).

source
WriteDocx.InchType
Inch(value::Float64) <: Length

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

source
WriteDocx.LengthType
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.

source
WriteDocx.PointType
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).

source
WriteDocx.TwipType
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).

source

Enums

WriteDocx.BorderStyleModule
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

source
WriteDocx.UnderlinePatternModule
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.

source
WriteDocx.ShadingPatternModule

ShadingPattern

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

source