API
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.AutomaticDefault
— TypeAutomaticDefault{T}
Signals that either a value of type T
is accepted or automatic
, for which the viewer application chooses appropriate behavior.
WriteDocx.Body
— TypeBody(sections::Vector{Section})
The document body which contains the sections of the document.
WriteDocx.ComplexField
— TypeComplexField(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.
WriteDocx.ComplexFieldEnd
— TypeComplexFieldEnd()
Every ComplexField
element must be paired with this element.
WriteDocx.DocDefaults
— TypeDocDefaults(; kwargs...)
Holds the default run and paragraph properties for a Document
. All properties are optional.
Keyword arguments
Keyword | Description |
---|---|
run:: RunProperties | The default properties for every Run . |
paragraph:: ParagraphProperties | The default properties for every Paragraph . |
WriteDocx.Document
— MethodDocument(body::Body; styles::Styles = Styles([]))
The root object containing all other elements that make up the document.
WriteDocx.Fonts
— TypeFonts(; [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.
WriteDocx.Footer
— TypeFooter(children::AbstractVector)
Contains elements for use in a Section
's footer section. Each element should satisfy is_block_element
.
WriteDocx.Footers
— TypeFooters(; default::Footer, [first::Footer, even::Footer])
Holds information about the Footer
s 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
.
WriteDocx.Header
— TypeHeader(children::AbstractVector)
Contains elements for use in a Section
's header section. Each element should satisfy is_block_element
.
WriteDocx.Headers
— TypeHeaders(; default::Header, [first::Header, even::Header])
Holds information about the Header
s 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
.
WriteDocx.HexColor
— TypeHexColor(s::String)
A color in hexadecimal RGB format, for example "FF0000" for red or "333333" for a dark gray.
WriteDocx.InlineDrawing
— TypeInlineDrawing{T}(; image::T, width::EMU, height::EMU)
Create an InlineDrawing
object which, as the name implies, can be placed inline with text inside Run
s.
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.
WriteDocx.PageSize
— MethodPageSize(width, height)
The size of a page. If width > height
, the page is set to PageOrientation.landscape
.
WriteDocx.Paragraph
— TypeParagraph(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
.
WriteDocx.ParagraphBorder
— TypeParagraphBorder(; kwargs...)
Holds properties for one border of a table cell and is used by ParagraphBorders
. All properties are optional.
Keyword arguments
Keyword | Description |
---|---|
color:: AutomaticDefault { [HexColor ]@ref} | The color of the border. |
shadow::Bool | Applies a shadow effect if true . |
space:: Point | The spacing between border and content. |
size:: EighthPoint | The thickness of the border line. |
style:: BorderStyle .T | The line style of the border. |
WriteDocx.ParagraphBorders
— TypeParagraphBorders(; kwargs...)
Holds properties for the borders of a Paragraph
and is used by ParagraphProperties
. All properties are optional.
Keyword arguments
Keyword | Description |
---|---|
top:: ParagraphBorder | The properties of the top border. |
bottom:: ParagraphBorder | The properties of the bottom border. |
left:: ParagraphBorder | The properties of the left border. |
right:: ParagraphBorder | The properties of the right border. |
between:: ParagraphBorder | The properties of horizontal border that lies between adjacent paragraphs. |
WriteDocx.ParagraphProperties
— TypeParagraphProperties(; kwargs...)
Holds properties for a Paragraph
. All properties are optional.
Keyword arguments
Keyword | Description |
---|---|
style::String | The name of the style applied to this Paragraph . |
justification:: Justification .T | The justification of the paragraph. |
WriteDocx.Run
— TypeRun(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.
WriteDocx.RunProperties
— TypeRunProperties(; kwargs...)
Holds properties for a Run
. All properties are optional.
Keyword arguments
Keyword | Description |
---|---|
style::String | The name of the style applied to this Run . |
color:: AutomaticDefault {HexColor} | The color of the text. |
size:: HalfPoint | The font size. |
valign:: VerticalAlignment .T | Whether text is shown with baseline, superscript or subscript style. |
fonts:: Fonts | The font settings for this text. |
bold::Bool | Whether text should be bold. Note that this works like a toggle when nested, turning boldness off again the second time it's true . |
italic::Bool | Whether text should be italic. Note that this works like a toggle when nested, turning italic style off again the second time it's true . |
WriteDocx.SVGWithPNGFallback
— TypeSVGWithPNGFallback(; 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.
WriteDocx.Section
— TypeSection(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 Section
s 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.
WriteDocx.SectionProperties
— TypeSectionProperties(; kwargs...)
Holds properties for a Section
.
Keyword arguments
Keyword | Description |
---|---|
pagesize::PageSize | The size of each page in the section. |
valign::PageVerticalAlign.T | The vertical alignment of content on each page of the section. |
headers:: Headers | Defines the header content shown at the top of each page of the section. |
footers:: Footers | Defines the footer content shown at the bottom of each page of the section. |
WriteDocx.Styles
— TypeStyles(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
.
WriteDocx.Table
— TypeTable(rows::Vector{TableRow}, properties::TableProperties)
Table(rows; kwargs...)
A table which can hold a vector of TableRow
s. The second convenience constructor forwards all keyword arguments to TableProperties
.
WriteDocx.TableCell
— TypeTableCell(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
.
WriteDocx.TableCellBorder
— TypeTableCellBorder(; kwargs...)
Holds properties for one border of a table cell and is used by TableCellBorders
. All properties are optional.
Keyword arguments
Keyword | Description |
---|---|
color:: AutomaticDefault { [HexColor ]@ref} | The color of the border. |
shadow::Bool | Applies a shadow effect if true . |
space:: Point | The spacing between border and content. |
size:: EighthPoint | The thickness of the border line. |
style:: BorderStyle .T | The line style of the border. |
WriteDocx.TableCellBorders
— TypeTableCellBorders(; kwargs...)
Holds properties for the borders of a TableCell
and is used by TableCellProperties
. All properties are optional.
Keyword arguments
Keyword | Description |
---|---|
top:: TableCellBorder | The properties of the top border. |
bottom:: TableCellBorder | The properties of the bottom border. |
start:: TableCellBorder | The properties of the left border in left-to-right text. |
stop:: TableCellBorder | The properties of the right border in left-to-right text. |
inside_h:: TableCellBorder | The properties of the horizontal border that lies between adjacent cells. |
inside_v:: TableCellBorder | The properties of the vertical border that lies between adjacent cells. |
tl2br:: TableCellBorder | The properties of the diagonal border going from the top left to the bottom right corner. |
tr2bl:: TableCellBorder | The properties of the diagonal border going from the top right to the bottom left corner. |
WriteDocx.TableCellMargins
— TypeTableCellMargins(; kwargs...)
Holds properties for the margins of a TableCell
and is used by TableCellProperties
. All properties are optional.
Keyword arguments
Keyword | Description |
---|---|
top:: Twip | The top margin. |
bottom:: Twip | The bottom margin. |
start:: Twip | The left margin in left-to-right text. |
stop:: Twip | The right margin in left-to-right text. |
WriteDocx.TableCellProperties
— TypeTableCellProperties(; kwargs...)
Holds properties for a TableCell
. All properties are optional.
Keyword arguments
Keyword | Description |
---|---|
borders::TableCellBorders | The border style of the cell. |
vertical_merge::Bool | Should be set to true if this cell should be merged with the one above it. |
gridspan::Int | The number of cells this cell should span in horizontal direction. |
margins::TableCellMargins | The margins of the cell. |
valign:: VerticalAlign .T | The vertical alignment of the content in the cell. |
hide_mark::Bool | If true , hides the editor mark so that the table cell can fully collapse if it's empty. |
WriteDocx.TableLevelCellMargins
— TypeTableCellMargins(; kwargs...)
Holds properties for the default margins of all TableCell
s in a Table
and is used by TableProperties
. All properties are optional.
Keyword arguments
Keyword | Description |
---|---|
top:: Twip | The top margin. |
bottom:: Twip | The bottom margin. |
start:: Twip | The left margin in left-to-right text. |
stop:: Twip | The right margin in left-to-right text. |
WriteDocx.TableProperties
— TypeTableProperties(; kwargs...)
Holds properties for a Table
. All properties are optional.
Keyword arguments
Keyword | Description |
---|---|
margins::TableLevelCellMargins | Margins for all cells in the table. |
spacing::Twip | The space between adjacent cells and the edges of the table. |
justification:: Justification .T | The justification of the table. |
WriteDocx.TableRow
— TypeTableRow(cells::Vector{TableCell}, properties::TableRowProperties)
TableRow(cells; kwargs...)
One row of a Table
which can hold a vector of TableCell
s. The second convenience constructor forwards all keyword arguments to TableRowProperties
.
WriteDocx.TableRowProperties
— TypeTableRowProperties(; kwargs...)
Holds properties for a TableRow
. All properties are optional.
Keyword arguments
Keyword | Description |
---|---|
header::Bool | Whether this row should be part of the header section which is repeated after every page break. |
height::TableRowHeight | The height of the table row. |
Length
s
WriteDocx.Centimeter
— TypeCentimeter(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.
WriteDocx.EMU
— TypeEMU(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)
.
WriteDocx.EighthPoint
— TypeEighthPoint(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)
.
WriteDocx.HalfPoint
— TypeHalfPoint(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)
.
WriteDocx.Inch
— TypeInch(value::Float64) <: Length
A length of one inch. For convenience, the constant inch
is provided for Inch(1)
.
WriteDocx.Length
— TypeLength
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.
WriteDocx.Point
— TypePoint(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)
.
WriteDocx.Twip
— TypeTwip(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)
.
Enums
WriteDocx.BorderStyle
— ModuleBorderStyle
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
WriteDocx.Justification
— ModuleJustification
An enum that can be either start
, stop
, center
, both
or distribute
.
WriteDocx.UnderlinePattern
— ModuleUnderlinePattern
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
.
WriteDocx.ShadingPattern
— ModuleShadingPattern
An enum that can be either clear
, diag_cross
, diag_stripe
, horz_cross
, horz_stripe
, nil
, thin_diag_cross
, or solid
.
WriteDocx.VerticalAlign
— ModuleVerticalAlign
An enum that can be bottom
, center
or top
.
WriteDocx.VerticalAlignment
— ModuleVerticalAlignment
An enum that can be either baseline
, subscript
or superscript
.