Widgets

widget

these properties apply to all widgets, and can be used anywhere!

Properties

  • class: string css class name
  • valign: string how to align this vertically. possible values: "fill", "baseline", "center", "start", "end"
  • halign: string how to align this horizontally. possible values: "fill", "baseline", "center", "start", "end"
  • vexpand: bool should this container expand vertically. Default: false.
  • hexpand: bool should this widget expand horizontally. Default: false.
  • width: int width of this element. note that this can not restrict the size if the contents stretch it
  • height: int height of this element. note that this can not restrict the size if the contents stretch it
  • active: bool If this widget can be interacted with
  • tooltip: string tooltip text (on hover)
  • visible: bool visibility of the widget
  • style: string inline css style applied to the widget
  • css: string scss code applied to the widget, i.e.: button {color: red;}

combo-box-text

A combo box allowing the user to choose between several items.

Properties

  • items: vec Items that should be displayed in the combo box
  • timeout: duration timeout of the command: Default: "200ms"
  • onchange: string runs the code when a item was selected, replacing {} with the item as a string

expander

A widget that can expand and collapse, showing/hiding it's children.

Properties

  • name: string name of the expander
  • expanded: bool sets if the tree is expanded

revealer

A widget that can reveal a child with an animation.

Properties

  • transition: string the name of the transition. Possible values: "slideright", "slideleft", "slideup", "slidedown", "crossfade", "none"
  • reveal: bool sets if the child is revealed or not
  • duration: duration the duration of the reveal transition. Default: "500ms"

a checkbox

A checkbox that can trigger events on checked / unchecked.

Properties

  • checked: bool whether the checkbox is toggled or not when created
  • timeout: duration timeout of the command. Default: "200ms"
  • onchecked: string action (command) to be executed when checked by the user
  • onunchecked: string similar to onchecked but when the widget is unchecked

color-button

A button opening a color chooser window

Properties

  • use-alpha: bool bool to whether or not use alpha
  • onchange: string runs the code when the color was selected
  • timeout: duration timeout of the command. Default: "200ms"

color-chooser

A color chooser widget

Properties

  • use-alpha: bool bool to wether or not use alpha
  • onchange: string runs the code when the color was selected
  • timeout: duration timeout of the command. Default: "200ms"

scale

A slider.

Properties

  • flipped: bool flip the direction
  • marks: string draw marks
  • draw-value: bool draw the value of the property
  • round-digits: int Sets the number of decimals to round the value to when it changes
  • value: float the value
  • min: float the minimum value
  • max: float the maximum value
  • timeout: duration timeout of the command. Default: "200ms"
  • onchange: string command executed once the value is changes. The placeholder {}, used in the command will be replaced by the new value.
  • orientation: string orientation of the widget. Possible values: "vertical", "v", "horizontal", "h"

progress

A progress bar. HINT: for the width property to work, you may need to set the min-width of progressbar > trough in your css.

Properties

  • flipped: bool flip the direction
  • value: float value of the progress bar (between 0-100)
  • orientation: string orientation of the progress bar. possible values: "vertical", "v", "horizontal", "h"

input

An input field. For this to be useful, set focusable="true" on the window.

Properties

  • value: string the content of the text field
  • onchange: string Command to run when the text changes. The placeholder {} will be replaced by the value
  • timeout: duration timeout of the command. Default: "200ms"
  • onaccept: string Command to run when the user hits return in the input field. The placeholder {} will be replaced by the value
  • password: bool if the input is obscured

button

A button

Properties

  • timeout: duration timeout of the command. Default: "200ms"
  • onclick: string a command that get's run when the button is clicked
  • onmiddleclick: string a command that get's run when the button is middleclicked
  • onrightclick: string a command that get's run when the button is rightclicked

image

A widget displaying an image

Properties

  • path: string path to the image file
  • image-width: int width of the image
  • image-height: int height of the image
  • icon: string name of a theme icon
  • icon-size: string size of the theme icon

box

the main layout container

Properties

  • spacing: int spacing between elements
  • orientation: string orientation of the box. possible values: "vertical", "v", "horizontal", "h"
  • space-evenly: bool space the widgets evenly.

overlay

a widget that places its children on top of each other. The overlay widget takes the size of its first child.

Properties

tooltip

A widget that have a custom tooltip. The first child is the content of the tooltip, the second one is the content of the widget.

Properties

centerbox

a box that must contain exactly three children, which will be layed out at the start, center and end of the container.

Properties

  • orientation: string orientation of the centerbox. possible values: "vertical", "v", "horizontal", "h"

scroll

a container with a single child that can scroll.

Properties

  • hscroll: bool scroll horizontally
  • vscroll: bool scroll vertically

eventbox

a container which can receive events and must contain exactly one child. Supports :hover and :active css selectors.

Properties

  • timeout: duration timeout of the command. Default: "200ms"
  • onscroll: string event to execute when the user scrolls with the mouse over the widget. The placeholder {} used in the command will be replaced with either up or down.
  • onhover: string event to execute when the user hovers over the widget
  • onhoverlost: string event to execute when the user losts hovers over the widget
  • cursor: string Cursor to show while hovering (see gtk3-cursors for possible names)
  • ondropped: string Command to execute when something is dropped on top of this element. The placeholder {} used in the command will be replaced with the uri to the dropped thing.
  • dragvalue: string URI that will be provided when dragging from this widget
  • dragtype: string Type of value that should be dragged from this widget. Possible values: "file", "text"
  • onclick: string a command that get's run when the button is clicked
  • onmiddleclick: string a command that get's run when the button is middleclicked
  • onrightclick: string a command that get's run when the button is rightclicked

label

A text widget giving you more control over how the text is displayed

Properties

  • text: string the text to display
  • truncate: bool whether to truncate text (or pango markup). If show-truncated is false, or if limit-width has a value, this property has no effect and truncation is enabled.
  • limit-width: int maximum count of characters to display
  • truncate-left: bool whether to truncate on the left side
  • show-truncated: bool show whether the text was truncated. Disabling it will also disable dynamic truncation (the labels won't be truncated more than limit-width, even if there is not enough space for them), and will completly disable truncation on pango markup.
  • unindent: bool whether to remove leading spaces
  • markup: string Pango markup to display
  • wrap: bool Wrap the text. This mainly makes sense if you set the width of this widget.
  • angle: float the angle of rotation for the label (between 0 - 360)
  • gravity: string the gravity of the string (south, east, west, north, auto). Text will want to face the direction of gravity.
  • xalign: float the alignment of the label text on the x axis (between 0 - 1, 0 -> left, 0.5 -> center, 1 -> right)
  • yalign: float the alignment of the label text on the y axis (between 0 - 1, 0 -> bottom, 0.5 -> center, 1 -> top)
  • justify: string the justification of the label text (left, right, center, fill)

literal

A widget that allows you to render arbitrary yuck.

Properties

  • content: string inline yuck that will be rendered as a widget.

calendar

A widget that displays a calendar

Properties

  • day: float the selected day
  • month: float the selected month
  • year: float the selected year
  • show-details: bool show details
  • show-heading: bool show heading line
  • show-day-names: bool show names of days
  • show-week-numbers: bool show week numbers
  • onclick: string command to run when the user selects a date. The {0} placeholder will be replaced by the selected day, {1} will be replaced by the month, and {2} by the year.
  • timeout: duration timeout of the command. Default: "200ms"

stack

A widget that displays one of its children at a time

Properties

  • selected: int index of child which should be shown
  • transition: string the name of the transition. Possible values: "slideright", "slideleft", "slideup", "slidedown", "crossfade", "none"
  • same-size: bool sets whether all children should be the same size

transform

A widget that applies transformations to its content. They are applied in the following

Properties

  • rotate: float the percentage to rotate
  • translate-x: string the amount to translate in the x direction (px or %)
  • translate-y: string the amount to translate in the y direction (px or %)
  • scale-x: string the amount to scale in the x direction (px or %)
  • scale-y: string the amount to scale in the y direction (px or %)

circular-progress

A widget that displays a circular progress bar

Properties

  • value: float the value, between 0 - 100
  • start-at: float the percentage that the circle should start at
  • thickness: float the thickness of the circle
  • clockwise: bool wether the progress bar spins clockwise or counter clockwise

graph

A widget that displays a graph showing how a given value changes over time

Properties

  • value: float the value, between 0 - 100
  • thickness: float the thickness of the line
  • time-range: duration the range of time to show
  • min: float the minimum value to show (defaults to 0 if value_max is provided)
  • max: float the maximum value to show
  • dynamic: bool whether the y range should dynamically change based on value
  • line-style: string changes the look of the edges in the graph. Values: "miter" (default), "round",

systray

Tray for system notifier icons

Properties

  • spacing: int spacing between elements
  • orientation: string orientation of the box. possible values: "vertical", "v", "horizontal", "h"
  • space-evenly: bool space the widgets evenly.
  • icon-size: int size of icons in the tray
  • prepend-new: bool prepend new icons.