Writer now has a set of new automation commands and APIs that allow clients to build user interface for citation handling that's more advanced than the default in-Writer bibliography support.

This work is primarily for Collabora Online, see the CODE release notes for one possible way to use this.

Motivation¶

Users frequently using scientific citations are probably familiar with the limits of Writer's built-in bibliography support, and solutions like Zotero appeared (with a LibreOffice extension included) to improve that situation.

This means that instead of storing all your scientific notes and data locally, you can store them on a Zotero server, then work with that from anywhere, once you provide your credentials.

The trouble comes when you want to combine this with collaborative editing, which is provided by Online, but you can't use the extension made for the desktop.

The above CODE release notes explains how an end user can use this feature, this post is meant to document what new UNO commands and LOK APIs I added that serve as a backend for this. Especially the UNO commands are also useful in other contexts, like in macros or other extensions.

Results so far¶

Zotero can store citations using 3 markups in documents: fields (DOCX only), bookmarks (DOCX and ODT) and finally reference marks / sections (ODT only). The added plumbing allows several operations for all 3 cases, to work with existing documents using any of these markups.

The citation and the bibliography is handled the same way for fields (Writer's fieldmarks) and bookmarks. The last case uses reference marks for citations, but sections for the bibliography.

The following operations are supported:

• create the citation / bibliography

• read the object under the cursor

• read all objects of a given type in the document

• update the object under the cursor

• update all objects of a given type in the document

• delete all objects of a given type in the document

Reading is only available to LOK clients, you need to call the getCommandValues() API. The rest is normal UNO commands that you can invoke from document macros or extensions as well.

The added plumbing is the following:

How is this implemented?¶

If you would like to know a bit more about how this works, continue reading... :-)

As usual, the high-level problem was addressed by a series of small changes:

• sw: add new FieldType parameter for the .uno:TextFormField command
• sw: add new FieldCode parameter for the .uno:TextFormField command
• sw, .uno:TextFormField command: accept HTML in the FieldResult parameter
• sw lok, .uno:TextFormFields: expose field code of fieldmarks
• comphelper: support property values arrays in JsonToPropertyValues()
• sw: add a new .uno:TextFormFields UNO command
• sw: hide TextFormFields from the customization dialog like
• sw lok, .uno:SetDocumentProperties: expose value of custom document properties
• libreofficekit: add a way to invoke getCommandValues()
• sfx2: extend .uno:SetDocumentProperties to update custom doc props
• sw, .uno:InsertBookmark: add a new BookmarkText parameter and accept HTML there
• sw: split out some of the LOK parts of SwXTextDocument into a separate file
• sw, lok: implement a getCommandValues(Bookmarks)
• sw: add a new .uno:UpdateBookmarks UNO command
• sw, field insert: handle the Content param for refmarks and accept HTML there
• sw UI: fix crash on inserting a fieldmark inside a fieldmark
• sw, lok: implement a getCommandValues(Fields)
• sw, UpdateFields: add new TypeName, NamePrefix and Fields parameters
• sw lok: expose field type & command of fieldmark under cursor
• sw update of refmarks: fix handling of ignored refmarks
• sw: UpdateFieldContents: fix typos
• sw: add a new .uno:UpdateTextFormField UNO command
• sw lok: get all refmarks: sort the refmarks array
• sw, .uno:InsertSection: add a new Content parameter and accept HTML there
• sw: document FN_UPDATE_TEXT_FORMFIELD and FN_UPDATE_TEXT_FORMFIELDS
• sw, lok: implement a getCommandValues(Sections)
• vcl ITiledRenderable: rename supportsCommandValues() to supportsCommand()
• sw, UpdateBookmarks: support renaming bookmarks
• sw: add a new .uno:UpdateSections command
• sw: add a new .uno:DeleteTextFormFields UNO command
• sw: fix FN_UPDATE_TEXT_FORMFIELD typo
• sw lok: expose name of bookmark under cursor
• sw: add a new .uno:UpdateBookmark UNO command
• sw, UpdateSections: remove not needed StateMethod
• sw lok: expose name of refmark under cursor
• sw, FN_DELETE_TEXT_FORMFIELDS: allow deleting all fieldmarks
• sw: rename getBookmarkFor() to getInnerBookmarkFor()
• sw: add a new .uno:UpdateField UNO command
• sw: add a new .uno:DeleteBookmarks UNO command
• sw: add a new .uno:DeleteFields UNO command
• sw, UpdateBookmark: address some minor performance nits
• sw, UpdateFieldContent: address a minor performance nit
• sw: disable AutoUpdate for many new recent field/book/refmark UNO commands
• sw: .uno:TextFormField: add new Wrapper parameter
• sw: .uno:TextFormField: handle Endnote as a value for the Wrapper parameter
• sw: rename getBookmarkFor() further to getOneInnermostBookmarkFor()
• sw, .uno:InsertField: add a new Wrapper parameter
• sw, .uno:InsertField: handle Endnote as a value for the Wrapper parameter
• sw: add a new .uno:DeleteSections UNO command

Want to start using this?¶

You can get a snapshot / demo of Collabora Office 22.05 and try it out yourself right now: try the unstable snapshot. Collabora intends to continue supporting and contributing to LibreOffice, the code is merged so we expect all of this work will be available in TDF's next release too (7.6).

Number portions generated when using lists/numberings/bullets in Writer now can have formatting which is preserved in ODT files as well.

First, thanks Docmosis for funding this work by Collabora.

Motivation¶

Word and DOCX files support explicit character properties for the paragraph marker, and these are also used for the formatting of a number portion if the paragraph has one. This was already loaded from / saved to DOCX, but it was lost when saving to ODT.

Results so far¶

First, we got a bug document, where the reference rendering and our rendering differed:

In this case, what happened was that part of the heading text was covered by a bookmark, so we first created multiple character ranges (outside the bookmark, inside the bookmark), then as an optimization we even unified them to be a single formatted character range, covering the entire paragraph. This was a document model that is different from the bookmark-free version, where the character formatting was set on the paragraph itself.

This was fixed at render time and at DOCX export time to consider both full-paragraph character ranges and in-paragraph character properties. For a while, this looked like the entire story, since this now looks good in Writer:

A bit later another, related bug was discovered. Given a reference document:

Just opening this DOCX file in Writer, it looked like this:

Note how the first number portion turned into bold! This was expected after the above layout change to consider full-paragraph formatted character ranges, but it also meant that Word can have one set of character formatting for the entire character range of a paragraph, and another for the paragraph marker.

To make the problem worse, this second document was showing that even the ODT export/export feature had problems, still:

The fix to solve all of the above was to undo the previous render / DOCX export change, then teach the ODT export to explicitly save the paragraph marker formatting (as an empty span at the end of the text node) to ODT, and also to load it back.

This means that now Writer can render the second document correctly, without breaking the first document:

How is this implemented?¶

If you would like to know a bit more about how this works, continue reading... :-)

As usual, the high-level problem was addressed by a series of small changes:

• sw, numbering portion format: consider full-para char formats as well
• DOCX export, numbering portion format: consider full-para char formats as well
• sw, numbering portion format: ignore char formats covering the entire paragraph
• sw: ODT import/export of DOCX's paragraph marker formatting
• sw: fix ODT import of paragraph marker formatting

Want to start using this?¶

You can get a snapshot / demo of Collabora Office 22.05 and try it out yourself right now: try the unstable snapshot. Collabora intends to continue supporting and contributing to LibreOffice, the code is merged so we expect all of this work will be available in TDF's next release too (7.6).

The PDF export now supports various additional properties for the optional PDF watermark.

First, thanks Docmosis for funding this work by Collabora.

Motivation¶

When you hear the word "watermark", you probably have something like the above picture in mind.

Instead, what the PDF export had is more like a proof of concept:

The request was to add new options to control the font size, font name, rotation angle and color of the watermark, so in case an organization already has a given style of watermarks they prefer, our PDF export can be adapted accordingly.

Results so far¶

First, now you can specify a custom color, e.g. gray (#7f7f7f), using:

soffice --convert-to pdf:writer_pdf_Export:'{"Watermark":{"type":"string","value":"draft"}, "WatermarkColor":{"type":"long","value":"8355711"}}' test.odt

Then you can also customize the font size, in case the automatic size would not fit your needs, using:

soffice --convert-to pdf:writer_pdf_Export:'{"Watermark":{"type":"string","value":"draft"}, "WatermarkFontHeight":{"type":"long","value":"100"}}' test.odt

Or perhaps you want a serif font, not a sans one:

soffice --convert-to pdf:writer_pdf_Export:'{"Watermark":{"type":"string","value":"draft"}, "WatermarkFontName":{"type":"string","value":"Times"}}' test.odt

Finally you can have a custom rotate angle:

soffice --convert-to pdf:writer_pdf_Export:'{"Watermark":{"type":"string","value":"draft"}, "WatermarkRotateAngle":{"type":"long","value":"450"}}' test.odt

Using these building blocks, you can also build combinations, the first screenshot above was created using:

soffice --convert-to pdf:writer_pdf_Export:'{"Watermark":{"type":"string","value":"draft"}, "WatermarkRotateAngle":{"type":"long","value":"450"}, "WatermarkColor":{"type":"long","value":"8355711"}}' test.odt

i.e. the configuration JSON is:

{
    "Watermark": {
        "type": "string",
        "value": "draft"
    },
    "WatermarkRotateAngle": {
        "type": "long",
        "value": "450"
    },
    "WatermarkColor": {
        "type": "long",
        "value": "8355711"
    }
}

How is this implemented?¶

If you would like to know a bit more about how this works, continue reading... :-)

As usual, the high-level problem was addressed by a series of small changes:

• Related: tdf#54053 PDF export: add UNO API to customize the watermark color
• Related: tdf#54053 PDF export: add UNO API to customize the watermark font size
• Related: tdf#54053 PDF export: add UNO API to customize the watermark font name
• Related: tdf#54053 PDF export: add UNO API to customize the watermark rotation

Want to start using this?¶

You can get a snapshot / demo of Collabora Office 22.05 and try it out yourself right now: try the unstable snapshot. Collabora intends to continue supporting and contributing to LibreOffice, the code is merged so we expect all of this work will be available in TDF's next release too (7.5).

Writer now supports titles and tags for content controls, which helps providing context for the filled in text even if the placeholder text is replaced already.

This work is primarily for Collabora Online, see the previous post for background.

Motivation¶

Once several content controls are added to a document, it's easy to forget what was the exact purpose of what content control. Think of a press release for example – those regularly start with a location and a date, but once this information is provided, one no longer knows which content control was for which content.

Titles solve this problem for the user: similar to Writer's header/footer buttons, this button appears when you enter the content control and reminds you what content is expected there, even if the placeholder is already replaced.

Tags serve a similar purpose, but they are unique, machine-readable keys or identifiers, so once the form is filled in, an external consumer can easily extract the information from the document, given a specific tag.

Results so far¶

Titles (also known as aliases) and tags are now not only preserved, but also we have a UI to create, show, edit and delete them. This is available in the desktop rendering and also in the LOK API.

Somewhat related, in case a content control breaks into multiple lines or has formatting to break into multiple text portions, we now only emit one PDF widget for it, taking the description of the widget from the content control's title.

The last related improvement is that now we handle data binding for date content controls, which means that you can specify a timestamp, a language and a date format, and we'll format that timestamp and update the content control's string value at import time from DOCX.

How is this implemented?¶

If you would like to know a bit more about how this works, continue reading... :-)

As usual, the high-level problem was addressed by a series of small changes:

• sw content controls: preserve alias
• sw content controls: preserve tag
• sw content controls: emit only one PDF widget for multiple text portions
• tdf#151190 sw content controls: make them read-write in protected sections
• sw content controls: add rendering for the alias
• sw content controls, alias and tag: add ODT filter
• sw content controls, alias and tag: add UI
• sw content controls, alias: add LOK API
• sw content controls, alias: add PDF export
• sw content controls: enable data binding for date

Want to start using this?¶

You can get a snapshot / demo of Collabora Office 22.05 and try it out yourself right now: try the unstable snapshot. Collabora intends to continue supporting and contributing to LibreOffice, the code is merged so we expect all of this work will be available in TDF's next release too (7.5).

Writer now supports exporting content controls to PDF and a 7th content control type: it is possible to differentiate between drop-downs and combo boxes.

This work is primarily for Collabora Online, see the previous post for background.

Motivation¶

Writer users can create fillable forms using content controls, but the PDF export only contained the plain text representation of them. PDF can also have fillable widgets for form filling, so it's logical to map content controls to PDF widgets.

A perfect mapping is not possible, since PDF widgets are always a single rectangle and Writer content controls is a list of rectangles (text portions), but this doesn't cause a problem in most cases. The size of the PDF rectangle is determined based on the placeholder's size from Writer.

Benefits includes not having to insert a control shape, manually positioned to look like it's in line with the surrounding text. An other benefit is that this way the widget's style (font name, size, etc) can be specified using Writer styles, not with shape properties. It's also interesting that Word itself doesn't seem to support content controls in its PDF export at the time of writing.

Results so far¶

PDF export now automatically turns Writer content controls into fillable widgets for the rich text, plain text, checkbox, drop-down, combo box and date types.

Combo box itself is a new type: now combo box content can be either free-form or one of its list items, while drop-down can only be one of its list items.

How is this implemented?¶

If you would like to know a bit more about how this works, continue reading... :-)

As usual, the high-level problem was addressed by a series of small changes:

• sw content controls, rich text: add initial PDF export
• sw content controls, checkbox: add PDF export
• sw content controls, dropdown: add PDF export
• sw content controls, date: add PDF export
• sw content controls: add PDF export of font properties
• sw content controls: fix getString() and setString() on SwXContentControl
• sw content controls, plain text: enable DOCX filter with data binding
• sw content controls: add a11y description for PDF export
• sw content controls, combo box: add doc model & UNO API
• sw content controls, combo box: make the dropdown case read-only
• sw content controls, combo box: add ODT filter
• sw content controls, combo box: add DOCX filter
• sw content controls, combo box: add insert UI
• sw content controls, combo box: add PDF export

Want to start using this?¶

You can get a snapshot / demo of Collabora Office 22.05 and try it out yourself right now: try unstable snapshot. Collabora intends to continue supporting and contributing to LibreOffice, the code is merged so we expect all of this work will be available in TDF's next release too (7.5).

Impress now supports cropped videos in slide edit mode and during slideshow for documents imported from PowerPoint.

First, thanks to our partner SUSE for working with Collabora to make this possible.

Motivation¶

PowerPoint handles videos by taking a preview bitmap from the video, and then it allows users to apply various effects on that bitmap, like cropping. The complex aspect of this is that such filters are also respected while playing the video as well.

Impress didn't store such properties on the media shape, which lead to distorted aspect ratio when playing some cropped videos from PPTX files. This lead to this preview in Impress before the work:

Results so far¶

The first problem was that the Impress preview was picked from the 3rd second of the video (presumably to avoid a black preview in many videos that start with a short black fade-in), while PowerPoint can store an explicit preview from the video (seems to be the first frame), so no matter what effects you apply, the previews were just different as the source bitmap was different. This could be fixed by looking for an explicitly provided bitmap for the video first, and only then asking the various avmedia/ backends to produce a preview.

Once the preview's initial bitmap was OK, it was necessary to take cropping into account. This was first done for the preview bitmap, and then also for the gstreamer backend (the relevant one for Linux, as a start) of avmedia/, which is responsible for the actual video playback. The gstreamer bits were done by first creating a videocrop element and then connecting that to the existing playbin.

With these sorted out, we get rendering which matches the reference:

The last step was to load/save the explicit preview and the crop from/to ODF as well, not only PPTX. We use a markup like this to store the information:

<style:style style:name="gr1">
  <style:graphic-properties fo:clip="rect(0cm, 1.356cm, 0cm, 1.356cm)"/>
</style:style>

And now that the gr1 automatic style is defined, we can refer to it from a media shape:

<draw:frame draw:name="test" draw:style-name="gr1">
  <draw:plugin xlink:href="..." xlink:type="simple" xlink:show="embed" xlink:actuate="onLoad" draw:mime-type="application/vnd.sun.star.media">
    ...
  </draw:plugin>
  <draw:image xlink:href="Pictures/MediaPreview1.png"/>
</draw:frame>

The nice property of this markup is that automatic styles are already used for other shapes and image previews are also used for e.g. table shapes, so this is just using existing markup in a new context, but the ODF spec already allows this markup.

How is this implemented?¶

If you would like to know a bit more about how this works, continue reading... :-)

As usual, the high-level problem was addressed by a series of small changes:

• Related: tdf#149971 svx: support explicitly provided snapshots for media shapes
• Related: tdf#149971 avmedia: add doc model and render for crop of media objects
• tdf#149971 avmedia: implement video crop support in the gsteamer backend
• avmedia: implement video crop support in the ODP filter
• xmloff: extract ExportGraphicPreview() from XMLShapeExport::ImpExportTableShape()

User interface to create such a crop, support for other video effects (e.g. black-and-white) and other backends (Windows, macOS) could be done, but is future work currently.

Want to start using this?¶

You can get a snapshot / demo of Collabora Office and try it out yourself right now: try unstable snapshot. Collabora intends to continue supporting and contributing to LibreOffice, the code is merged so we expect all of this work will be available in TDF's next release too (7.5).

Writer now supports a 6th content control type: it is possible to insert a plain text content control.

This work is primarily for Collabora Online, done as a HackWeek project, but the feature is fully available in desktop Writer as well.

Motivation¶

Writer users can put a content control around a piece of rich text, see Content controls in Writer: dropdown, picture and date types for the first five types.

The next step in this journey is plain text: even if one of the big advantages of content controls over input fields is that they allow rich formatting, sometimes you want to restrict this. For example, if one has to fill in their name, then it makes no sense to mark the family name as bold while leaving the given name as non-bold. This would just lead to inconsistent look.

Results so far¶

There is now a new Form → Content Controls → Insert Plain Text Content Control menu item to create a plain text content control. If you try to make a selection that is a subset of the text inside the content control and you try to format it, the whole text in the content control is formatted to maintain the invariant that plain text has no formatting itself, just the formatting of the whole content control.

As usual, you can delete this content control later. You can also load/save it to ODT/DOCX and it's preserved.

How is this implemented?¶

If you would like to know a bit more about how this works, continue reading... :-)

As usual, the high-level problem was addressed by a series of small changes:

• sw content controls, plain text: add doc model & UNO API
• sw content controls, plain text: apply formatting to the entire contents
• sw content controls, plain text: add ODT filter
• sw: fix heap-use-after-free in SwTextNode::InsertHint()
• sw content controls, plain text: add DOCX export
• sw content controls, plain text: add DOCX import
• sw content controls, plain text: add insert UI

Want to start using this?¶

You can get a snapshot / demo of Collabora Office 22.05 and try it out yourself right now: try unstable snapshot. Collabora intends to continue supporting and contributing to LibreOffice, the code is merged so we expect all of this work will be available in TDF's next release too (7.5).

Impress now has the next step of document theme support: it is possible to refer to the theme colors from shape fill colors (including effects).

This work is primarily for Collabora Online, but the feature is fully available in desktop Impress as well.

Motivation¶

PowerPoint users can attach a set of colors (and fonts, etc.) to master pages, and then refer to these in many areas, like shape text or shape fill. It was already possible to define theme colors and refer to them from shape text (see Start of document themes in Impress: shape text for details).

The next step in this journey is shape fill: if your shape is filled with some color, it can be a theme color, as visible on the above screenshot. One interesting aspect of this is that the default shape fill color can now depend on the master page, and it may not be the same for all slides (this is what would happen with styles, when not using theming).

Results so far¶

Here is a demo that shows how it works:

If one opens the svx/qa/unit/data/theme.pptx test file from core.git, it looks like this:

The middle row has 3 rounded rectangles: the first is filled with the 'Accent 1' color, the second is the same, but 60% lighter and finally the last one is the same, but 25% darker.

Here is how you can change what the 'Accent 1' color is:

• Click 'Master View' on the sidebar to go to the master of the current slide.
• Right click -> 'Slide Properties' opens the 'Slide Properties' dialog.
• The 'Theme' page has an 'Accent 1' row, with a blue color.
• Change that to an orange color: click on the 'Accent 1' drop-down, then select 'Theme colors', finally the 6th choice is orange in the first row -- this comes from the document's theme.
• Click 'OK' to close the dialog, followed by 'Close Master View' on the sidebar.

Here is how your shapes now look like:

What you can see here is that the color effect (darker, lighter, default) of the rounded rectangles' fill color was preserved, but all the blue colors are replaced with orange.

As a cherry on the cake, now if you insert a new shape, that will also have an orange fill color by default as well.

You can see how this is useful when designing templates: a designer can create something good-looking, and all you have to do is to set the theme to the colors of your organization, and you're done.

How is this implemented?¶

If you would like to know a bit more about how this works, continue reading... :-)

As usual, the high-level problem was addressed by a series of small changes:

• sd theme: fix applying new colors after theme change for group shapes
• sd theme: add doc model for shape fill color
• sd theme: add UNO API for shape fill color
• sd theme: add rendering for shape fill color
• sd theme: add PPTX import for shape fill color
• sd theme: add ODP import/export for shape fill color
• sd theme: add PPTX export for shape fill color
• sd theme: add UI (area dialog) for shape fill color
• sd theme: add UI (sidebar) for shape fill color
• sd theme: add UNO API for shape fill color effects
• sd theme: add rendering for shape fill color effects
• sd theme: add PPTX import for shape fill color effects
• sd theme: add ODP import/export for shape fill color effects
• tdf#148929 sd theme: limit PPTX import for shape fill effects to lum mod/off
• tdf#148961 sd theme: add PPTX export for shape fill color effects
• sd theme: add UI (area dialog) for shape fill color effects
• tdf#149205 sd theme: fix PPTX export loosing dk1 and lt1 colors
• sd theme: add UI (sidebar) for shape fill color effects
• sd theme: consider accent1 color when inserting shape with solid fill
• tdf#149748 sd theme: fix crash on selecting none from color bar

Want to start using this?¶

You can get a snapshot / demo of Collabora Office 22.05 and try it out yourself right now: try unstable snapshot. Collabora intends to continue supporting and contributing to LibreOffice, the code is merged so we expect all of this work will be available in TDF's next release too (7.4).