Decorations

This page documents how window decorations work

---

Window Decorations are the non-client areas of a window, so things like the Titlebar and Resize-Borders. Saucer offers an API to change Window Decorations to allow for custom titlebars, which you might’ve seen in desktop apps such as e.g. Spotify or Discord.

Example: Changing Window Decorations

window->set_decorations(saucer::window::decoration::partial);

There are three decoration-types to choose from (none, partial, full). Each of them behave differently. Their differences are listed in the table below:

Decoration	Titlebar	Resizable	Aero-Snap1	Window Shadows	Note
none					Prefer partial decorations if possible2
partial					-
full					The default window decorations

Gallery

decoration::none	decoration::partial	decoration::full

Webview Support

When the webview attributes (saucer::webview::options{.attributes = true}) setting is enabled (the default), you can use the following data-attributes to more easily implement a custom titlebar:

• data-webview-close

  When an element with this attribute is clicked, the window is closed

• data-webview-minimize

  When an element with this attribute is clicked, the window is minimized

• data-webview-maximize

  When an element with this attribute is clicked, the window is maximized or restored, depending on its current state

• data-webview-drag

  When an element with this attribute is held, the window will follow the mouse cursor

• data-webview-resize="<edge>"

  When an element with this attribute is held, the window will start resizing.
  <edge> should be one (or a combination³) of the following

  • t ≈ “top” window border
  • b ≈ “bottom” window border
  • l ≈ “left” window border
  • r ≈ “right” window border

• data-webview-ignore

  Add this to elements that trigger any kind of unwanted operation. This can happen when the parent of such an element has a data-webview attribute

Along with the attributes, the following window functions are also exposed:

• saucer.close()
• saucer.startDrag()
• saucer.startResize(saucer.windowEdge)
• saucer.minimize(bool) / saucer.minimized()
• saucer.maximize(bool) / saucer.maximized()

Footnotes

1. Refers to Window-Snapping, e.g. when dragging the window to the top of the screen, the operating system will usually prompt to maximize the window. ↩

2. Using decoration::none can make the app feel alien, because things like window shadows and snapping are disabled and have to be implemented by yourself. ↩

3. e.g. data-webview-resize="tr" to start resizing from the top right border. ↩