Spire Trading Inc. - User contributions [en]

Model

2025-04-23T19:29:56Z

Jon: fix: remove duplicate 'event' in 'Input Event' link

User interfaces are composed of reusable semantic elements called components. Each component is specified by a set of documents: <code>model.txt</code>, <code>preview.xd</code>, <code>components.xd</code>, <code>layout.xd</code>, <code>user_flow.drawio</code>, and <code>use_cases.drawio</code>. This page covers the <code>model.txt</code> document.

<code>model.txt</code> provides the complete description of the data the component operates on and displays, the state of the component, and the signals it produces. Any component with new behavior requires <code>model.txt</code>. Components that simply customize the properties of existing components omit <code>model.txt</code> as there is nothing to describe that is not already defined in <code>components.xd</code>.


== Data and Behavior ==

<code>model.txt</code> is necessary when the component being defined has specific data that it displays or manipulates or introduces novel behavior not found elsewhere in the UI Kit.


=== Example: AccountListItem ===

<pre>Data:
identicon: A unique icon identifier for the account.
id: A unique username for the account.
name: The full name associated with the account.</pre>
The model for <code>AccountListItem</code> is very simple and deals only with data. There is no special behavior associated with <code>AccountListItem</code>: it behaves no differently than any other <code>ListItem</code> that has been defined elsewhere. <code>AccountListItem</code> takes a structured set of data:
* <code>identicon</code>
* <code>id</code>
* <code>name</code>

Using a specific <code>AccountListItem</code> for displaying user accounts in this way keeps components contained and simple.


=== Example: Button ===

<pre>Data:
body: The component to display inside of the button.

State:
press: Whether the button is currently pressed.

Signals:
Click: Indicates that the button was clicked.</pre>
<code>Button</code> is a more generic component. From <code>body</code>, we see that it can be used to display any component, so there is no specific data associated with it. What distinguishes <code>Button</code> from <code>Component</code> is its behavior:
* <code>press</code> is a new '''State''' that <code>Button</code> can be in.
* <code>Click</code> is a new '''Signal''' that <code>Button</code> can send.


== Getting Started ==

<code>model.txt</code> is written after <code>preview.xd</code>. Clarifying in writing what data the component uses greatly simplifies the making of <code>components.xd</code>, <code>use_cases.drawio</code> and <code>user_flow.drawio</code>.

Most expected behavior is specified in <code>Component</code>, the base component for all UI components. Any property or signal found in <code>Component</code> can be used by any component without repeating them in the model. This makes the model for most components sparse and keeps the focus on their ''unique'' data and behavior.

Components are built using composition: complexity is built up from simple elements that manage a small set of responsibilities. These smaller elements are the <code>children</code> and when we consider the model for a component it is helpful to think about what responsibilities are handled by its children rather than being its concern.


=== Example: DropDownBox ===

[[File:drop_down_box_preview.png|640px|Preview of a drop down box in open and closed states]]

<code>DropDownBox</code> lets the user select a single value from a list of options and submit that value. It has a child <code>DropDownList</code>: the list of options and whether the list is open or closed can be thought of as properties of <code>DropDownList</code>.

To describe <code>DropDownBox</code>, we need to understand a little more of its behavior:
* It represents a single value that the user can select.
* Selecting a value is different from submitting a value. The user can select a value without submitting it.
* The user can revert a selection to what was last submitted (by pressing the Escape key).
* Focusing out of the <code>DropDownBox</code> is treated as a submission when the selected value has changed from the last submitted value.
* It can be set to be read only.

Based on its behavior, we need a few properties:
* A property to track the selected value
* A property to track the last submitted value
* A property to indicate if it is read only

Other components will need to be notified when the user has made a submission so they can respond to changes. We can add one more requirement:
* A signal to indicate a submission

<pre>Data:
read_only: Whether the value is modifiable by the user.
current: The item currently represented by the DropDownBox.

State:
submission: The last value submitted by the user.
modified: Whether current has been modified since last Submit.

Signals:
Submit: Indicates the user is submitting current.</pre>
Reviewing the <code>model.txt</code>, we see the following:
* <code>current</code> to track the selected value
* <code>submission</code> to track the last submitted value
* <code>read_only</code> to indicate if it is read only
* <code>modified</code> to track whether <code>current</code> changed from <code>submission</code> (not strictly necessary)
* <code>Submit</code>, a signal to indicate a submission

We note that <code>read_only</code> and <code>current</code> have been placed in <code>Data</code>, while <code>submission</code> and <code>modified</code> are in <code>State</code>. This means that external components can modify <code>read_only</code> and <code>current</code>, while <code>DropDownBox</code> manages <code>submission</code> and <code>modified</code> itself. <code>Submit</code> is placed in <code>Signals</code>. Properties are named using '''snake_case''' while signals use '''PascalCase'''.

It may be useful for external components to respond to changes in <code>current</code> as well as <code>submission</code>, such as showing a preview based on the current selection, but a <code>Current</code> signal is not necessary for this. Because properties in <code>Data</code> are read-write for external components, components can subscribe to property changes directly without requiring a signal.


== Anatomy ==

The structure of <code>model.txt</code> is a linear document divided into preset sections. These sections are as follows:
* Definitions
* Styles
* Selectors
* Pseudo-Elements
* Data
* State
* Signals

<code>Definitions</code> serve as an optional index for terms used throughout the model. <code>Selectors</code> are used in older specs but should be avoided for simplicity. <code>Pseudo-Elements</code> define sub-sections of the component and make them available for styling. The remaining sections <code>Styles</code>, <code>Data</code>, <code>State</code>, and <code>Signals</code> can be conceptualized as relating to the interface as shown:

[[File: Model_Component_anatomy.png | 640px | Diagram of a component with Data, Styles, State and Signals shown as wires between and within the boundary]]

<code>Data</code> flows through the interface, depending on the component, both external resources and the user may be able to modify <code>Data</code> properties.

<code>Styles</code> can be set by external components to change the appearance of the component. Generally, the user doesn’t directly modify the style of a component, so these can be thought of as one-way.

<code>State</code> is managed internally by the component. It can be influenced by user interactions, by <code>Data</code>, or any combination of properties, but it remains encapsulated.

<code>Signals</code> are messages sent out by the component. They inform other components about changes that are useful to know about resulting from a user action.


=== Breakdown ===

Within each section is a list of properties followed by their definitions.

<pre>Section Heading:
property_name: Property description. Optional default.</pre>
Property names should balance brevity with self-description. Leaning on familiar and established terminology is preferred over introducing new terms with the same meaning.

Descriptions should be precise, concise, and readable, expressing in plain language the meaning of the property. If a property can only be one of a finite set of values, the possible values are enumerated directly in the definition by nesting them below the property name and definition.

<pre>Section Heading:
property_name: Property description.
POSSIBLE_VALUE_1: Value description for 1. Default.
POSSIBLE_VALUE_2: Value description for 2.</pre>
Values are distinguished using UPPERCASE.

Properties can consist of sub-properties, such as list or tabular data, or properties consisting of multiple orthogonal components such as the <code>x</code> and <code>y</code> components of a position. Sub-properties are nested beneath properties.

<pre>Section Heading:
property_name: Property description. Optional default.
sub_property_name: Sub property description. Optional default.</pre>
Descriptions can include inline expressions provided they are trivial. With expressions, it is understood that they represent a ''binding'': they update automatically without requiring a sub-flow in <code>user_flow.drawio</code>. When an expression is used, it is placed on its own line below the last sentence for the description. The equality is implied.

<pre>Section Heading:
property_name_1: Property description. Optional default.
property_name_2: Property description.
property_name_1 + 10</pre>

=== Example: Component ===

<pre>Styles:
visibility: Shows or hides the component.
VISIBLE: The component is visible, (default).
INVISIBLE: The component is invisible.
NONE: The component is both invisible and removed from the layout.</pre>
In the above excerpt from <code>model.txt</code> for <code>Component</code>, the <code>visibility</code> property is defined within the <code>Styles</code> section. <code>visibility</code> can be one of three values:
* <code>VISIBLE</code>
* <code>INVISIBLE</code>
* <code>NONE</code>

Each possible value is named and defined directly below the definition for <code>visibility</code>.

<pre>Data:
parent: The parent of this component, for top-level components this is NULL.
window: The window that this component belongs to.
children: The list of this component's children.
width: The width of the component in pixels.
height: The height of the component in pixels.
position: The position of the component relative to its parent, if the
component has no parent, then the position is equal to
screen_position.
x - The x-coordinate in pixels.
y - The y-coordinate in pixels.</pre>
Continuing to the <code>Data</code> section, the <code>position</code> property is a composite of two independent values: <code>x</code> and <code>y</code>. These properties can be referenced in other documentation with dot notation as <code>position.x</code> and <code>position.y</code>.


=== Example: SaleConditionBox ===

<pre>State:
conditions_list: A list of all conditions.
code: The identifier for the condition.
name: The name for the condition.
terms: The list of words from the name for the condition.
name.split(' ')</pre>
<code>conditions_list</code> is a list of items, where each item has the fields specified. Visually it can be shown as tabular data. Below is what some of this data might look like:

{| class="wikitable"
|-
! code!! name!! terms
|-
| @ || Regular Settlement || Regular, Settlement
|-
| C || Cash Settlement || Cash, Settlement
|-
| N || Next Day Settlement || Next, Day, Settlement
|-
| R || Seller Settlement || Seller, Settlement
|-
| F || Intermarket Sweep || Intermarket, Sweep
|-
| O || Opening Print || Opening, Print
|-
| 4 || Derivative Priced || Derivative, Priced
|-
| 5 || Re-Opening Print || Re-Opening, Print
|-
| 6 || Closing Print || Closing, Print
|}

<code>terms</code> is clearly derived from <code>name</code>, the result of the inline expression. If the expression is non-trivial or not unconditionally true, then it does not belong in <code>model.txt</code>. If you are unsure if an expression improves the clarity of the model, leave it out.


=== Example: InputBox ===

Boolean (true or false) properties have implied values.

<pre>Data:
read_only: Whether the InputBox is in read_only mode.
rejected: Whether the last submission was rejected.</pre>
<code>InputBox</code> has two boolean properties: <code>read_only</code> and <code>rejected</code>. Each may be <code>true</code> or <code>false</code>, which is implied from their definitions.


== Definitions ==

This section is optional. It provides definitions for terms used throughout the model to improve clarity.


=== Example: TimeAndSalesWindow ===

<pre>Definitions:
TimeAndSale: A trade on a security.
timestamp: The time of the trade.
price: The price of the trade.
size: The number of shares traded.
condition: A code that indicates the conditions of the trade.
market_center: The market that facilitated the trade.
bbo_indicator: An indicator that relates the price to the bbo.
BBO_UNKNOWN: The bbo is unknown.
ABOVE_ASK: The price is above the ask.
AT_ASK: The price is equal to the ask.
INSIDE: The price is between the bid and the ask.
AT_BID: The price is equal to the bid.
BELOW_BID: The price is below the bid.</pre>
<code>Definitions</code> is used to define a <code>TimeAndSale</code>. Each <code>TimeAndSale</code> has a set of properties associated with it:
* <code>timestamp</code>
* <code>price</code>
* <code>size</code>
* <code>condition</code>
* <code>market_center</code>
* <code>bbo_indicator</code>

<code>TimeAndSale</code> can be referenced elsewhere in the model.

It is at the designer’s discretion whether to include a <code>Definitions</code> section or to provide the description inline where the term is used. The following heuristics are helpful in determining whether to place a definition in a <code>Definitions</code> section:
* The term is referenced by multiple properties throughout the model
* The definition is long or contains multiple levels of nesting which would impede the readability if included directly in the normal flow of the document

When unsure, err on the side of putting the description inline rather than including a Definitions section.


== Styles ==

<code>Styles</code> is for defining any style properties available on the component. Style properties affect the visual appearance of a component but do not directly relate to the data it displays. Style properties can be inputs that are provided externally to the component.


=== Example: Box ===

<pre>Styles:
background_color: The background color. #FFFFFF by default.
border_top_size: The height of the top border.
border_right_size: The width of the right border.
border_bottom_size: The height of the bottom border.
border_left_size: The width of the left border.
...</pre>
<code>Box</code> defines a number of style properties for customizing its color, border, and padding. External components using <code>Box</code> can make use of any of these properties as needed.

No matter how deep in the component hierarchy a <code>Box</code> is nested as a child, the component can access the properties for that <code>Box</code> and make customizations. This avoids creating redundant properties to enable customization.


=== Example: TimeAndSale ===

<pre>Styles:
font: The font used to render the text in the cells.
Default 10px Roboto 500.
bbo_unknown: The bbo is unknown.
background_color: Default #FFFFFF.
text_color: Default #000000.
above_ask: The price is above the ask.
background_color: Default #D2F6E0.
text_color: Default #007735.
at_ask: The price is equal to the ask.
background_color: Default #D2F6E0.
text_color: Default #007735.
inside: The price is between the bid and the ask.
background_color: Default #FFFFFF.
text_color: Default #000000.
at_bid: The price is equal to the bid.
background_color: Default #FAD8D9.
text_color: Default #B71C1C.
below_bid: The price is below the bid.
background_color: Default #FAD8D9.
text_color: Default #B71C1C.</pre>
<code>TimeAndSale</code> defines a number of style properties specific to its function. <code>font</code> is defined in <code>TextBox</code> and ordinarily does not need to be redefined: here it is done for convenience so that all the children of <code>TimeAndSale</code> are styled with the same font without having to make separate declarations for each child. The remaining properties relate to <code>TimeAndSale</code>: they depend on a comparison between the price of the <code>TimeAndSale</code> to the bid and ask prices.

Note that each comparative style (<code>bbo_unknown</code>, <code>above_ask</code>, etc.) is a composite style of <code>background_color</code> and <code>text_color</code>: coordinating separate styles into a set of presets is a common use case for <code>Styles</code>.

The basic styles are all available in <code>Box</code> and <code>TextBox</code>. Components should only define styles that are sensible to their function. Styles are not restricted to the properties and selectors of CSS or other languages, they are defined within <code>model.txt</code> to suit the specific needs of the component.


== Selectors ==

Selectors may be deprecated. They were used to bundle <code>Styles</code> and <code>State</code> in an opt-in manner. It is recommended to use <code>Styles</code> in combination with <code>State</code> for any properties that can be used to style the component.


== Pseudo-Elements ==

Pseudo-elements are a way to give full styling properties to portions of a component that are not components themselves. They are used infrequently but can be useful for fundamental components that consist of semantic portions that are not components. Consider the following usage in TextBox:

<pre>Pseudo-elements:
placeholder: Styles the placeholder sub-component.</pre>
This enables the placeholder to be styled using the same properties as for TextBox, even though it is not itself a component. Text is the most obvious use case for pseudo-elements, as it can be broken up semantically into granular parts. See [https://web.dev/learn/css/pseudo-elements/ Pseudo-Elements on Web.dev] and [https://developer.mozilla.org/en-US/docs/Learn/CSS/Building_blocks/Selectors/Pseudo-classes_and_pseudo-elements#what_is_a_pseudo-element Pseudo-Elements on MDN] for more detail.


== Data ==

<code>Data</code> is for properties that do not deal directly with styling and are provided externally. Properties in <code>Data</code> are read-write to external components and may be modifiable by the user (such as the value of an input field).

<code>Data</code> properties are not fixed, they can be updated from an external source at any time. It is common to have <code>Data</code> properties that represent a stream, such as quotes from an exchange, which update as soon as they change without requiring a user-initiated update request. Anytime a property in <code>Data</code> is changed, the change is immediately reflected in the component. It is sufficient to declare where the value resides in the component and it will always reflect the latest value.

A default value is often declared. Where the data comes from is not specified (e.g. from a backend or a local file), that should be determined by the type of data and the application architecture.

The following heuristic may be useful in determining whether property values belong in <code>Data</code> or <code>State</code>. It belongs in <code>Data</code> if:
* The value can be modified by the user through interaction with the component
* The value is read from an external source requiring real-time updates
* There are obvious use-cases where external components will need to read or write to the value

Otherwise, put the value in <code>State</code>.


=== Example: TextBox ===

<pre>Data:
current: The text currently represented by the TextBox.
cursor_position: The current cursor position. When 0, the cursor is at the
start of the TextBox.
selection_start: The index position of the character in current at
the start of selection.
selection_end: The index position of the character in current at the
end of selection. When selection_end < selection_start,
the direction of selection is opposite of reading order.
read_only: Whether the text is modifiable by the user.
placeholder: The text to be displayed when current is empty.
max_length: The maximum number of characters to accept.</pre>
<code>TextBox</code> has a number of bi-directional properties: <code>current</code>, <code>cursor_position</code>, <code>selection_start</code>, and <code>selection_end</code> are all typically driven by user actions, but they can also be set by external components or when the component is customized, such as setting an initial <code>current</code> value to display. There are also properties that are not modifiable by the user: <code>read_only</code>, <code>placeholder</code>, and <code>max_length</code>. However, it is possible for external components to modify these, so a component could be made that let the user change these properties.


=== Standard Property Names ===

Properties are directly defined in the <code>model.txt</code> and may be anything the designer can define. That said, there are commonly recurring properties that have come to form an implicit convention and it is preferable to use consistent names and descriptions when the intended behavior is the same.


==== Current ====

In the <code>TextBox</code> example, the text is named <code>current</code> and not <code>text</code> or <code>value</code>. This is intentional: <code>current</code> is a standard property name.


===== Example: DecimalBox =====

In <code>DecimalBox</code>, <code>current</code> refers to a number rather than a text string.

<pre>Data:
current: The current number represented by the DecimalBox.</pre>

===== Example: DateBox =====

In <code>DateBox</code>, <code>current</code> refers to a date value, not a number or text string.

<pre>Data:
current: The current date represented by the DateBox, in ISO format
(YYYY-MM-DD).</pre>
By convention, <code>current</code> refers to the current value of the component. The type of the value is generally defined by what the component displays.


===== Example: ScalarFilterPanel =====

If there is no logical single current value for the component, it should not have <code>current</code>.

<pre>Data:
min: If set defines the minimum value to include.
default_min: The default min value.
max: If set defines the maximum value to include.
default_max: The default max value.</pre>
<code>ScalarFilterPanel</code> has two <code>DecimalBox</code>, one aliased as <code>MinValue</code> and another aliased as <code>MaxValue</code>, and has access to <code>MinValue.current</code> and <code>MaxValue.current</code>. It does not have a <code>current</code> as it does not represent a single value.


===== Example: TableBody =====

<code>current</code> can be made more specific where appropriate.

<pre>Data:
rows: A list of table_rows each having an equal number of columns, used to
populate the body.
row_selection_mode: The selection mode used by rows (NONE by default).
row_selection: Stores the list of selected rows.
column_selection_mode: The selection mode used by columns (NONE by default).
column_selection: Stores the list of selected columns.
cell_selection: Stores the list of selected cells, indexed by row and column.
cell_selection_mode: The selection mode used by cells (NONE by default).
current_cell: The currently selected cell (null by default). The current cell
can be used to implicitly specify a current row and current column
if such functionality is desirable, for example the current cell's
row is implicitly the current row.</pre>
<code>TableBody</code> has a <code>current_cell</code> property but no <code>current</code> property. Because <code>TableBody</code> can only have one cell as current, it makes sense that this is a property of <code>TableBody</code> and not of any of its children. However, <code>TableBody</code> does not represent a single cell, so <code>current</code> without added specificity could cause confusion.


===== Example: ListView =====

Do not use current for lists of data: <code>current</code> refers to one value that varies in time.

<pre>Data:
current: The view's current value, can be null.
selected: The value of the selected list item.
items: A list of items used to populate the list.
component: The component to display in the list.
value: A text value associated with an item, used to select an item by
keyboard.</pre>
<code>ListView</code> uses <code>current</code> for the single value that is current, and <code>items</code> contains the list of values that make up the list. While <code>ListView</code> represents a list of values, only a single value can be <code>current</code>.


==== Body ====

<code>body</code> represents a slot that fills the entirety of the component. Some components, like <code>Button</code>, are generic enough that they can be used to display anything, and <code>body</code> is the name these components are assigned to.


===== Example: Box =====

<pre>Data:
body: The component displayed in the box.</pre>

===== Example: Button =====

<pre>Data:
body: The component to display inside of the button.</pre>

==== Items ====

<code>items</code> represents a generic list of values that are managed by a single component.


===== Example: ListView =====

<pre>
Data:
current: The view's current value, can be null.
selected: The value of the selected list item.
items: A list of items used to populate the list.
component: The component to display in the list.
value: A text value associated with an item, used to select an item by
keyboard.</pre>
Note that, strictly following the <code>body</code> naming convention, <code>items.component</code> should be named <code>items.body</code>.


== State ==

<code>State</code> is for declaring properties that are internal to the component. These are properties that are useful to have because they simplify descriptions of the component’s behavior and map to the user’s mental model of the component. A common use-case for <code>State</code> is for declaring properties that can be used for styling the component.


=== Example: Component ===

<pre>State:
active: Whether the component belongs to the currently active window.
enabled: The negation of disabled, enabled = !disabled.
hover: Whether the mouse is located on top of the component.
focus: Whether the component receives keyboard input.
focus_in: Whether the component or any of its descendants has focus.
focus_visible: Whether the box has focus and it is determined that focus
should be indicated on the box to assist the user:
- the user focused the box via non-pointing device
- the box received programmatic focus from a component that
had focus_visible</pre>
<code>component</code> declares a number of <code>State</code> properties that are used for styling purposes by many components. It is common for a component to have a certain appearance when it is <code>hover</code>. Because <code>hover</code> is defined in <code>component</code>, it is trivial to style a component like a button based on its hover state. Each component doesn’t need to reinvent or redeclare the logic for what <code>hover</code> means.


=== Example: SecurityBox ===

A common use-case for <code>State</code> is for storing data that is intrinsic to the component that the user cannot manipulate.

<pre>State:
security_list: A list of all tradeable securities.
symbol: The symbol of the security.
name: The full name of the security.
country: The ISO country code for the country in which the security's
exchange is located in.</pre>
In <code>SecurityBox</code>, <code>security_list</code> is all tradeable securities. This list is dynamic, since securities are delisted and new securities listed all the time. It could be obtained from a remote resource that is periodically updated. Unlike with <code>Data</code>, it is not automatically assumed that this data is continuously flowing as a stream. Because the <code>security_list</code> is neither a real-time feed or modifiable by the user, <code>State</code> is an appropriate location for it. This also ensures that <code>security_list</code> cannot be tampered with by external components and makes using <code>SecurityBox</code> more ergonomic: <code>SecurityBox</code> always contains the list of all tradeable securities.


== Signals ==

Signals are how components notify other components about changes to their internal state. Any external component can listen for a signal from a specific component and respond accordingly. Use signals whenever there is a change in a component that it would be useful for external components to know about based on real use cases.

Signals are not necessary for notifying external components about simple changes in <code>Data</code>: the properties in <code>Data</code> are already externally accessible: an external component can see if <code>DecimalBox.current</code> changed without needing a signal. However, sometimes a component will need to perform some operations on the data when it changes, and it should send a signal when these operations are completed.

Signals should reflect the behavior of the component they belong to. Components should not pass along signals from their children if it does not make sense to their function.

Components can define signals with the same name as their children. For a component with a child <code>DecimalBox</code>, it can define its own <code>Submit</code> signal which is what is referenced by <code>A.Submit</code>. The <code>DecimalBox</code> is specified with dot notation as <code>A.DecimalBox.Submit</code>. Ideally, only <code>A</code> should be interested in <code>DecimalBox.Submit</code>, while other components should subscribe to <code>A.Submit</code>.


=== Standard Signal Names ===

As with properties, there are a few standard signals.


==== Change ====

The <code>Change</code> signal may be fired by a component that needs to notify other components of a change to the <code>current</code> of its children. This may be useful when some logic should be performed such as validation before sending out the signal so that components listening for changes do not concern themselves with handling an invalid change. It is similar to the [https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/input_event Input Event] in HTML


==== Submit ====

<code>Submit</code> indicates that the user has submitted the value. A <code>Submit</code> signal should only be generated in response to an intentional user action, such as a key press. <code>Submit</code> is conventionally signaled on a <code>FocusOut</code> event when <code>current</code> has changed from its previous value: the user’s change in focus is interpreted as an implicit submission. <code>Submit</code> typically follows an Enter key press. It is similar to the [https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/change_event Change Event] in HTML.


==== Reject ====

<code>Reject</code> is fired to indicate that a submitted value was rejected.


=== Payload ===

When a signal is fired, it carries with it a payload that components can read. For the <code>Submit</code> signal, its payload consists of <code>submission</code> by default. The payload of any signal can be customized to better suit the use-cases.


==== Example: TimeFilterPanel ====

<pre>Signals:
Submit: The user has submitted their time range.
start: The submitted start time of the range or NULL if offset is set.
end: The submitted end time of the range or NULL if offset is set.
offset: The submitted offset to filter by or NULL if start and end are set.</pre>
The <code>Submit</code> payload carries three values: <code>start</code>, <code>end</code>, and <code>offset</code>. This reflects <code>TimeFilterPanel</code> which lacks a <code>current</code> or <code>submission</code> but has <code>start</code>, <code>end</code>, and <code>offset</code> values. Within <code>user_flow.drawio</code>, the values used for each payload slot are clarified.


== Ordering ==

Keep the sections ordered as they appear in this overview and repeated below:
* Definitions
* Styles
* Pseudo-Elements
* Data
* State
* Signals

Omit any section that is unused.


== Usage ==

When placing data into <code>components.xd</code>, use the property names exactly as they appear in <code>model.txt</code>. States used by selectors in <code>components.xd</code> should also appear exactly as they appear in <code>model.txt</code>. The property and signal names should also carry over to <code>layout.xd</code>, <code>use_cases.drawio</code>, and <code>user_flow.drawio</code>.

<code>model.txt</code> is the most powerful tool in the designer’s toolkit; taking time upfront to provide good descriptions in the model can save a lot of designer and developer headaches later on.


== References ==

* [https://web.dev/learn/css/pseudo-elements/ Web.dev: Pseudo-Elements]
* [https://developer.mozilla.org/en-US/docs/Learn/CSS/Building_blocks/Selectors/Pseudo-classes_and_pseudo-elements#what_is_a_pseudo-element MDN: Pseudo-Elements]
* [https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/input_event MDN: The Input Event]
* [https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/change_event MDN: The Change Event]

Styling Grammar

2024-09-06T21:39:00Z

Jon: Add syntax highlighting to code snippets

= Syntax =

== Declarations ==

A property and value pair is called a declaration'''.''' The pair is separated by a colon, '<code>:</code>'. White spaces are ignored. Properties and values are case-insensitive. If the value is invalid for the property, the declaration will be ignored.

<syntaxhighlight lang="css">Property value
background-color: white</syntaxhighlight>

== Declaration blocks ==

A pair of brackets, ‘<code>{</code>’ and ‘<code>}</code>’, are used to group multiple declarations into a block. The semicolon ‘<code>;</code>’ is used to separate different declarations.

<syntaxhighlight lang="css">{
background-color: white;
border-size: 1px;
}</syntaxhighlight>

== Selector ==

The selector specifies which components are being applied for styles.

Selector types:

{| class="wikitable simple-table"
|-
| | '''Selector'''
| | '''Explanation'''
| | '''Example'''
| | '''Spire styling'''
|-
| | Any selector (universal selector)
| | Selects all components.
| | *
| | Any()
|-
| | Type selector
| | Selects all instances of the selector and of its subclasses.
| | TextBox
| | is_a<Type>
|-
| | Property selector
| | Selects elements based on the element having a given attribute explicitly set.
| | Button[visibility=none] 
Button:not([visibility=none]) 

| | Button && matches(Visibility::NONE) 
Button && !matches(Visibility::NONE) 

|-
| | & nesting selector
| | The & nesting selector makes the nested child rule selectors relative to the parent element. Without the & nesting selector, the child rule selector selects child elements.
| | <code>parentRule {</code> 
<code>/* parent rule style properties */</code> 
<code>& childRule {</code> 
<code>/* child rule style properties */</code> 
 
} 
} 

| |
|}

The class selector and ID selector in CSS are not supported since the Spire styling doesn’t support them.

{| class="wikitable simple-table"
|-
| | <s>Class selector</s>
| | Selects all instances of the selector.
| | .TextBox
| | Not support
|-
| | <s>ID selector</s>
| | Matches all instances that has a specific object name.
| | #my-label
| | Not support
|}

== Pseudo-classes ==

The pseudo-class specifies a given state to the components. It starts with a colon.

<syntaxhighlight lang="css">:pseudo-class {
property: value;
}</syntaxhighlight>
{| class="wikitable simple-table"
|-
| | '''Selector'''
| | '''Explanation'''
| | '''Related components'''
|-
| | :active
| | Selects a component that is or belongs to the active window.
| | All components
|-
| | :disabled
| | Selects a disabled component.
| | All components
|-
| | :hover
| | Selects a hovered component.
| | All components
|-
| | :focus
| | Selects a focused component.
| | All components
|-
| | :focus-in
| | Selects a component that has focus or has a child that has focus..
| | All components
|-
| | :focus-visible
| | Selects a component if it was focused using a non-pointing device
| | All components
|-
| | :drag
| | Selects a Dragged component.
| | SplitView, ScrollBar
|-
| | :press
| | Selects a pressed component.
| | Button, Slider, Slider2D, MenuButton
|-
| | :read-only
| | Selects a read-only component.
| | All input boxes.
|-
| | :rejected
| | Selects a a component whose input value is rejected.
| | TextBox, DurationBox, DestinationBox, SaleConditionBox, DateBox
|-
| | :checked
| | Selects a checked CheckBox.
| | CheckBox
|-
| | :selected
| | Selects a selected list item.
| | ListItem
|-
| | :current
| | Selects the current list item.
| | ListItem
|-
| | :precedes-current
| | Selects the list item precedes the current item.
| | ListItem
|-
| | :hover-item
| | Selects the hovered table item
| | TableItem
|-
| | :current-row
| | Selects the current row in the table.
| | TableBody
|-
| | :current-column
| | Selects the current column in the table.
| | TableBody
|-
| | :sortable
| | Selects the column when it's sort order is not UNORDERED.
| | TableHeaderItem
|-
| | :filtered
| | Selects the column when a filter is applied.
| | TableHeaderItem
|-
| | :pop-up
| | Selects the widget displaying a pop-up.
| | DropDownBox
|-
| | :high-lighted
| | Selects the highlighted widget.
| | ColorSwatch
|-
| | :is-positive
| | Selects the DecimalBox when its value is positive.
| | DecimalBox
|-
| | :is-negative
| | Selects the DecimalBox when its value is negative.
| | DecimalBox
|-
| | :uptick
| | Selects the DecimalBox when its value has increased.
| | DecimalBox
|-
| | :downtick
| | Selects the DecimalBox when its value has decreased.
| | DecimalBox
|-
| | :modifier-key
| | Selects the KeyTag when it's displaying a modifier key.
| | KeyTag
|-
| | :escape-key
| | Selects the KeyTag when it's displaying the ESC key.
| | KeyTag
|-
| | :today
| | Selects the CalendarDatePicker when the current day is today.
| | CalendarDatePicker
|-
| | :out-of-month
| | Selects the CalendarDatePicker when a day is outside of the current month.
| | CalendarDatePicker
|-
| | :has()
| | Takes a selector as its argument and matches any element matching this selector.
| | All components
|-
| | :not()
| | Selects a component that is not selected by a selector.
| | All components
|-
| | :flip()
| | Flips what elements are selected.
| | All components
|-
| | :is()
| | Selects any element that can be selected by one of the selectors in its list. 
 
<code>:is(selector1, selector2, ...)</code>
| | All components
|}

== Pseudo-elements ==

A pseudo-element selects components that are the specific part of a selector. The pseudo-element must be used in combination with a block-level element selector. This means you cannot use pseudo-elements on its own without specifying a block-level element. Pseudo-elements start with a double colon <code>::</code> .

<syntaxhighlight lang="css">selector::pseudo-element {
property: value;
}</syntaxhighlight>
{| class="wikitable simple-table"
|-
| | '''Selector'''
| | '''Explanation'''
| | '''Related components'''
| | '''Spire styling'''
|-
| | ::placeholder
| | Select the placeholder in the text box.
| | TextBox, TextAreaBox
| | <code>PseudoElement</code>
|}

== Sub-controls ==

Selectors can contain sub-controls that make it possible to restrict the application of a rule to specific sub-controls. Its syntax is same as pseudo-element’s.

<syntaxhighlight lang="css">selector::sub-controls{
property: value;
}</syntaxhighlight>
{| class="wikitable simple-table"
|-
| | '''Selector'''
| | '''Explanation'''
| | '''Related components'''
|-
| | ::row
| | Selects all rows in the table.
| | TableBody
|-
| | ::column
| | Selects all columns in the table.
| | TableBody
|-
| | ::prompt
| | Selects the prompt in a key input box.
| | KeyInputBox
|-
| | ::divider
| | Selects the divider.
| | TabView, SplitView
|-
| | ::body
| | Selects the body component of a box or button.
| | Box, Button
|-
| | ::empty-cell
| | Selects the empty table cell in the EditableTableView.
| | TableItem(EditableTableView)
|-
| | ::delete-button
| | Selects the delete button in the EditableTableView.
| | TableItem(EditableTableView)
|-
| | ::label
| | Selects the label inside the TableHeaderItem.
| | TableHeaderItem
|-
| | ::filter-button
| | Selects the filter button inside the TableHeaderItem.
| | TableHeaderItem
|-
| | ::hover-element
| | Selects the hover element inside the TableHeaderItem.
| | TableHeaderItem
|-
| | ::track
| | Selects the track of the slider.
| | Slider, Slider2D
|-
| | ::thumb
| | Selects the thumb of the slider.
| | Slider, Slider2D
|-
| | ::track-rail
| | Selects the track rail of the slider.
| | Slider
|-
| | ::track-fill
| | Selects the track fill of the slider.
| | Slider
|-
| | ::track-pad
| | Selects the track pad of the 2d slider.
| | Slider2D
|-
| | ::scrollbar-track
| | Selects the track of the scroll bar.
| | ScrollBar
|-
| | ::scrollbar-thumb
| | Selects the thumb of the scroll bar.
| | ScrollBar
|-
| | ::colon
| | Selects the colon field.
| | DurationBox
|-
| | ::alpha
| | Selects the alpha component in the ColorCodePanel.
| | ColorCodePanel
|-
| | ::primary
| | Selects the primary component in the SplitView.
| | SplitView
|-
| | ::secondary
| | Selects the secondary component in the SplitView.
| | SplitView
|}

== Selectors Combination ==

{| class="wikitable simple-table"
|-
| | '''Selector'''
| | '''Explanation'''
| | '''Syntax'''
| | '''Example'''
| | '''CSS supports'''
|-
| | Child selector
| | Selects a component matched by the second selector that is the direct child of the component matched by the first.
| | <code>selector1 > selector2</code>
| | <code>TableView > TableBody</code>
| | Yes
|-
| | Descendant selector
| | Selects a component matched by the second selector that is the descendant of the component matched by the first.
| | <code>selector >> descendant- selector</code>
| | <code>ColorPicker >> Alpha</code>
| | Yes, but a single space is used.
|-
| | Parent selector
| | Selects a component matched by the second selector that is the direct parent of the component matched by the first.
| | <code>:has(> child-selector)</code> 
 

| | <code>ListItem:has(> TextBox)</code> 
 

| | The <code>:has() </code>pseudo-class can achieve the functionality.
|-
| | Ancestor selector
| | Selects a component matched by the second selector that is the ancestor of the component matched by the first.
| | <code>:has(>> descendant-selector)</code> 
 

| | <code>TableItem:has(>> TableItem)</code> 
 

| | The <code>:has() </code>pseudo-class can achieve the functionality.
|-
| | And selector
| | Selects components that are matched by both selectors.
| | <code><selector1><selector2></code>
| | <code>TextBox:hover</code> 
 

| | Combining Type selector and Pseudo-Class
|-
| | Flip selector
| | Flips what elements are selected.
| | <code>:flip()</code>
| | <code>*:flip(:has(>> ListItem))</code>
| | No
|-
| | Not selector
| | Selects a component that is not selected by a selector.
| | <code>:not()</code>
| | <code>:not(:hover)</code>
| | <code>:not()</code>
|-
| | Or selector
| | Selects a component that is selected by at least one of two selectors.
| | <code>selector1, selector2</code>
| | <code>:hover, :focus</code> 
<code>or</code> 
 
 
<code>:is(:hover, :focus)</code>
| | selector list
|-
| | Sibling selector
| | Selects a component matched by the second selector that is the sibling of the component matched by the first.
| | <code>selector % sibling-selector</code>
| | <code>TextBox % Button</code>
| | Yes, but <code>+</code> is used.
|}

Examples:

=== Child selector ===

<syntaxhighlight lang="css">is_a<Button>() > is_a<TextBox>()

Button > TextBox {
}

or

Button {
TextBox {
}
}

or

Button {
& > TextBox {
}
}</syntaxhighlight>

=== Descendant selector ===

<syntaxhighlight lang="css">is_a<Button>() >> is_a<TextBox>()

Button >> TextBox {
}

or

Button {
& >> TextBox {
}
}</syntaxhighlight>

=== Parent selector ===

<syntaxhighlight lang="css">is_a<Button>() < is_a<TextBox>()

Button:has(> TextBox) {</syntaxhighlight>
Cases used in practice:

<syntaxhighlight lang="css">auto body_selector = Any() > is_a<TableBody>();
auto item_selector = body_selector > Row() > is_a<TableItem>();
style.get((item_selector > EmptyCell()) < (HoverItem() || Current())).
set(border_color(QColor(Qt::transparent)));

TableView > TableBody > TableBody::row >
TableItem:has(> TableItem::empty-cell):hover-item,
TableView > TableBody > TableBody::row >
TableItem:has(> TableItem::empty-cell):current {
}

or

TableView {
TableBody {
TableBody::row {
TableItem {
&:has(> ::empty-cell) {
& :hover-item,
& :current {
border-color: transparent;
}
}
}
}
}
}
}

or

TableView {
TableBody {
TableBody::row {
TableItem {
&:has(> ::empty-cell):is(:hover-item, :current) {
border-color: transparent;
}
}
}
}
}
}</syntaxhighlight>

=== Ancestor selector ===

<syntaxhighlight lang="css">is_a<Button>() << is_a<TextBox>(

Button:has(>> TextBox) {
}</syntaxhighlight>

=== And selector ===

<syntaxhighlight lang="css">is_a<TextBox>() && Hover()

TextBox:hover</syntaxhighlight>
<syntaxhighlight lang="css">is_a<TextBox>() && ReadOnly() && Disabled()

TextBox:read-only:disabled</syntaxhighlight>
<syntaxhighlight lang="css">is_a<TextBox>() && !Prompt()

TextBox:not(KeyInputBox::Prompt)</syntaxhighlight>

=== Flip selector ===

<syntaxhighlight lang="css">+Any()

*:flip()</syntaxhighlight>

=== Not selector ===

<syntaxhighlight lang="css">!Hover()

:not(:hover)</syntaxhighlight>
<syntaxhighlight lang="css">!Prompt()

:not(KeyInputBox::prompt)</syntaxhighlight>

=== Or selector ===

<syntaxhighlight lang="css">is_a<TextBox>() && (Hover() || Focus()).
set(border_color(QColor(0x4B23A0)));

TextBox:hover, TextBox:focus {
border-color: 0x4B23A0;
}

or

TextBox {
&:hover,
&:focus {
border-color: 0x4B23A0;
}
}

or

TextBox {
&:is(:hover, :focus) {
border-color: 0x4B23A0;
}
}</syntaxhighlight>

=== Sibling selector ===

<syntaxhighlight lang="css">is_a<TextBox>() % is_a<Button>()

TextBox % Button

TextBox {
& % Button {
}
}</syntaxhighlight>

== Rules ==

A selector list and an associated declaration block are called a rule.

<syntaxhighlight lang="css">TextBox {
background-color: white;
border-size: 1px;
}</syntaxhighlight>
A commas, ‘<code>,</code>’, is used to separated different selectors which have the the same declaration block.

<syntaxhighlight lang="css">TextBox, Button {
background-color: white;
border-size: 1px;
}</syntaxhighlight>

== Inheritance ==

Unlike CSS, a component doesn’t automatically inherit font and color settings from its parent component.

== Nesting style ==

Nesting refers to the practice of placing rules inside other rules. It allows you to group related styles together to improve readability and reduce repetition.

<syntaxhighlight lang="css">parent {
/* parent styles */
child {
/* child of parent styles */
}
}

parent {
/* parent styles */
& child {
/* child of parent styles */
}
}</syntaxhighlight>
The difference between using <code>&</code> nesting selectors and not using nesting selectors.

* ''without'' the <code>&</code> nesting selector

<syntaxhighlight lang="css">Button {
/* parent styles */
:hover {
/* child of parent styles */
}
}</syntaxhighlight>
It automatically adds the Child selector <code>></code> between the selectors to create a new selector rule(CSS adds a whitespace between the selectors, building the descendant relationship between selectors by default). The following code shows the equivalent non-nested rules:

<syntaxhighlight lang="css">Button {
/* parent styles */
}

/* styles the hovered button's children. */
Button > :hover {
/* child of parent styles */
}

is_a<Button>() > Hover()</syntaxhighlight>
* ''with'' the <code>&</code> nesting selector

<syntaxhighlight lang="css">Button {
/* parent styles */
& :hover {
/* child of parent styles */
}
}</syntaxhighlight>
With the <code>&</code> nesting selector added with no whitespace, the above block equals to the following code:

<syntaxhighlight lang="css">Button {
/* parent styles */
}

/* styles the hovered button. */
Button:hover {
}

is_a<Button>() && Hover()</syntaxhighlight>
Other examples

<syntaxhighlight lang="css">is_a<Button>() >> is_a<TextBox>()

Button {
/* parent styles */
& >> TextBox {
/* child of parent styles */
}
}

or

Button {
>> TextBox {
background-color: black;
}
}

Button {
/* parent styles */
}

/* styles the hovered button. */
Button >> TextBox {
/* child of parent styles */
}</syntaxhighlight>

= Values =

== Number ==

A decimal integer or a real number.

Example:

<code>0, 1, 10, 1.5</code>

== Length ==

Syntax:

<code>Number(px | pt | ch)</code>

== Color ==

<ol style="list-style-type: decimal;">
<li>'''Hexadecimal Colors'''
Syntax:
<code>#rrggbb</code>
Example:
<code>TextBox {background-color: #ff0000;}</code></li></ol>

<ol start="2" style="list-style-type: decimal;">
<li>'''Hexadecimal Colors With Transparency'''
Syntax:
<code>#rrggbbaa</code>
Example:
<code>TextBox {background-color: #ff000008;}</code></li></ol>

<ol start="3" style="list-style-type: decimal;">
<li>'''RGB Colors'''
An RGB color value is specified with syntax <code>rgb()</code>, which has the following syntax:
<code>rgb(red, green, blue)</code>
Each parameter is an integer between 0 and 255.
Example:
<code>TextBox {background-color: rgb(255, 0, 0);} </code></li></ol>

<ol start="4" style="list-style-type: decimal;">
<li>'''RGBA Colors'''
RGBA color values are an extension of RGB color values with an alpha channel. The syntax is
<code>rgba(red, green, blue, alpha)</code>
The alpha parameter is a number between 0.0 (fully transparent) and 1.0 (fully opaque).
Example:
<code>TextBox {background-color: rgba(255, 0, 0, 0.3);} </code></li></ol>

<ol start="5" style="list-style-type: decimal;">
<li>'''Predefined Color Names'''
Only three color names that have been used in Spire are defined here.
<ul>
<li>transparent</li></ul>

<ul>
<li>white</li></ul>

<ul>
<li>black</li></ul>

Example:
<code>TextBox {background-color: transparent;} </code></li></ol>

== Font Style ==

* '''normal'''

* '''italic'''

* '''oblique'''

Example:

<code>#TextBox {font-style: italic;} </code>

== Font Weight ==

Predefined weight values which Qt supports:

<ul>
<li>'''thin'''
Same as 100.</li></ul>

<ul>
<li>'''extra-light'''
Same as 200.</li></ul>

<ul>
<li>'''light'''
Same as 300.</li></ul>

<ul>
<li>'''normal'''
Same as 400.</li></ul>

<ul>
<li>'''medium'''
Same as 500.</li></ul>

<ul>
<li>'''demi-bold'''
Same as 600.</li></ul>

<ul>
<li>'''bold'''
Same as 700.</li></ul>

<ul>
<li>'''extra-bold'''
Same as 800.</li></ul>

<ul>
<li>'''black'''
Same as 900.</li></ul>

== Alignment ==

<code>{left | right | top | bottom | center}*</code>

== Time ==

It represents a time value expressed in seconds or milliseconds. There is no space between Number and <code>s </code>or <code>ms</code>.

Syntax:

<code>Number(s | ms)</code>

== Overflow ==

<ul>
<li>'''none'''
The list extends indefinitely.</li></ul>

<ul>
<li>'''wrap'''
List items wrap to fill the perpendicular space.</li></ul>

== EdgeNavigation ==

<ul>
<li>'''contain'''
Selection stops at the current selection.</li></ul>

<ul>
<li>'''wrap'''
Selection moves from the first item to last item and vice versa.</li></ul>

== Orientation ==

<ul>
<li>'''horizontal'''
The element is laid out horizontally.</li></ul>

<ul>
<li>'''vertical'''
The element is laid out vertically.</li></ul>

== DateFormat ==

<ul>
<li>'''YYYYMMDD'''
The year, month, and day can be input in a YYYY-MM-DD format.</li></ul>

<ul>
<li>'''MMDD'''
The month and day can be input in a MM-DD format.</li></ul>

== Visibility ==

<ul>
<li>'''visible'''
The element is visible.</li></ul>

<ul>
<li>'''invisible'''
The element is invisible.</li></ul>

<ul>
<li>'''none'''
The element is treated as if it has a width and height of 0.</li></ul>

= Properties =

== all ==

The <code>all</code> property is a property that resets all properties.

Value:

<ul>
<li>unset
The unset keyword clears styles of all properties, which has the different meaning with CSS unset. In CSS, unset specifies that all the element's properties should be changed to their inherited values if they inherit by default, or to their initial values if not.</li></ul>

Syntax:

<code>all: unset;</code> 
 
Example: 

<syntaxhighlight lang="css">TextBox:read-only {
all: unset;
}

style.get(ReadOnly()).clear();</syntaxhighlight>

== Font ==

=== '''font-family''' ===

Example:

<code>#TextBox {font-family: "Roboto";}</code>

=== '''font-style''' ===

Example:

<code>#TextBox {font-style: normal;}</code>

=== '''font-weight''' ===

The weights available depend on the <code>font-style</code> that is currently set. It doesn’t support arbitrary values since QFont::setWeight() uses QFont::Weight enumeration as the parameter. Referring to <code>Font weight</code>.

Example:

<code>#TextBox {font-weight: normal;}</code>

=== '''font-size''' ===

Sets the element's font size. Only pt and px metrics are supported. 
Example: 

<code>#TextBox {font-size: 12px;}</code>

=== '''font (shorthand)''' ===

Syntax: 
 
<code>font = font-style? font-weight? font-size font-family</code>

Example:

<code>#TextBox {font: normal medium 12px "Roboto";}</code>

== Icon ==

=== '''url''' ===

Syntax:

<code>url(filename)</code>

filename is the name of a file on the local disk or stored using the Qt resource system.

Example:

<code>url(":/Icons/spire.svg”)</code>

=== '''fill''' ===

Syntax:

<code>fill = color | none</code>

Example:

<syntaxhighlight lang="css">Icon { fill: 0xA0A0A0; }
Icon { fill: none; }</syntaxhighlight>

=== '''icon-image''' ===

Syntax:

<code>icon-image = url (width height)?</code>

Example:

<syntaxhighlight lang="css">Icon { icon-image: url(":/Icons/spire.svg”) 16px 16px; }</syntaxhighlight>

== Text ==

=== '''text-align''' ===

Value: Alignment

Example:

<syntaxhighlight lang="css">TextBox {
text-align: left;
}</syntaxhighlight>

=== '''text-color''' ===

Value: Color

Example:

<syntaxhighlight lang="css">TextBox {
text-color: black;
}</syntaxhighlight>

=== '''text-style''' (Shorthand) ===

Syntax:

<code>text-style = font text-color</code>

Example:

<syntaxhighlight lang="css">TextBox {
text-style: normal 12px "Roboto" black;
}</syntaxhighlight>

== Border ==

=== '''border-top-size''' ===

Styles the size of the top border.

Value: Length

Example:

<code>Box { border-top-size: 1px; }</code>

=== '''border-right-size''' ===

Styles the size of the right border.

Value: Length

Example:

<code>Box { border-right-size: 1px; }</code>

=== '''border-bottom-size''' ===

Styles the size of the bottom border.

Value: Length

Example:

<code>Box { border-bottom-size: 1px; }</code>

=== '''border-left-size''' ===

Styles the size of the left border.

Value: Length

Example:

<code>Box { border-left-size: 1px; }</code>

=== '''border-top-color''' ===

Styles the color of the top border.

Value: Color

Example:

<code>Box { border-top-color: 0x4B23A0; }</code>

=== '''border-right-color''' ===

Styles the color of the right border.

Value: Color

Example:

<code>Box { border-right-color: 0x4B23A0; }</code>

=== '''border-bottom-color''' ===

Styles the color of the bottom border.

Value: Color

Example:

<code>Box { border-bottom-color: 0x4B23A0; }</code>

=== '''border-left-color''' ===

Styles the color of the left border.

Value: Color

Example:

<code>Box { border-left-color: 0x4B23A0; }</code>

=== '''border-top-left-radius''' ===

Styles the radius of the border's top left corner.

Value: Length

Example:

<code>Box { border-top-left-radius: 1px; }</code>

=== '''border-top-right-radius''' ===

Styles the radius of the border's top right corner.

Value: Length

Example:

<code>Box { border-top-right-radius: 1px; }</code>

=== '''border-bottom-right-radius''' ===

Styles the radius of the border's bottom right corner.

Value: Length

Example:

<code>Box { border-bottom-right-radius: 1px; }</code>

=== '''border-bottom-left-radius''' ===

Styles the radius of the border's bottom left corner.

Value: Length

Example:

<code>Box { border-bottom-left-radius: 1px; }</code>

=== '''border-size''' ===

Applies a single size to all four borders: '''border-top-size, border-right-size, border-bottom-size and border-left-size.'''

Value: Length

Example:

<code>Box { border-size: 1px; }</code>

=== '''border-color''' ===

Applies a single color to all four border: '''border-top-color, border-right-color, border-bottom-color and border-left-color.'''

Value: Color

Example:

<code>Box { border-color: 0x4B23A0; }</code>

=== '''border-radius''' ===

Applies a single radius to all four corners: '''border-top-left-radius, border-top-right-radius, border-bottom-right-radius and border-bottom-left-radius.'''

Value: Length

Example:

<code>Box { border-radius: 1px; }</code>

=== '''border (shorthand)''' ===

Styles all border colors and sizes.

Syntax:

<code>border = border-size border-color</code>

Example:

<syntaxhighlight lang="css">TextBox {
border: 1px 0x4B23A0;
}</syntaxhighlight>

== Padding ==

=== '''padding-top''' ===

Styles the size of the top padding.

Value: Length

Example:

<code>Box { padding-top: 8px; }</code>

=== '''padding-right''' ===

Styles the size of the right padding.

Value: Length

Example:

<code>Box { padding-right: 8px; }</code>

=== '''padding-bottom''' ===

Styles the size of the bottom padding.

Value: Length

Example:

<code>Box { padding-bottom: 8px; }</code>

=== '''padding-left''' ===

Styles the size of the left padding.

Value: Length

Example:

<code>Box { padding-left: 8px; }</code>

=== '''horizontal-padding''' ===

Styles the size of the left and right padding.

Value: Length

Example:

<code>Box { horiztontal-padding: 8px; }</code>

=== '''vertical-padding''' ===

Styles the size of the top and bottom padding.

Value: Length

Example:

<code>Box { vertical-padding: 8px; }</code>

=== '''padding''' ===

Styles all four padding size of an element at once.

Value: Length

Example:

<code>Box { padding: 8px; }</code>

== Spacing ==

=== '''horizontal-spacing''' ===

Styles the horizontal spacing between items in the table body.

Value: Length

Example:

<code>TableBody { horizontal-spacing: 8px; }</code>

=== '''vertical-spacing''' ===

Styles the vertical spacing between items in the table body.

Value: Length

Example:

<code>TableBody { vertical-spacing: 8px; }</code>

=== '''spacing''' ===

Styles the spacing between items in the table body.

Value: Length

Example:

<code>TableBody { spacing: 8px; }</code>

== Grid Color ==

=== '''horizontal-grid-color''' ===

Styles the color of the horizontal grid lines in the table body.

Value: Color

Example:

<code>TableBody { horizontal-grid-color: transparent; }</code>

=== '''vertical-grid-color''' ===

Styles the color of the vertical grid lines in the table body.

Value: Color

Example:

<code>TableBody { vertical-grid-color: transparent; }</code>

=== '''grid-color''' ===

Styles the color of the grid lines.

Value: Color

Example:

<code>TableBody { grid-color: transparent; }</code>

== background-color ==

Sets the background color of an element.

Value: Color

Example:

<code>Box { background-color: transparent; }</code>

== body-align ==

Sets the alignment of the body in a box.

Value: Alignment

Example:

<code>DurationBox { body-align: center; }</code>

== leading-zeros ==

The number of leading zeros added as padding to a number.

Value: Number

Example:

<code>DecimalBox { leading-zeros: 4; }</code>

== trailing-zeros ==

The number of trailing zeros added as padding to the fractional part of a number.

Value: Number

Example:

<code>DecimalBox { trailing-zeros: 4; }</code>

== list-item-gap ==

Sets the spacing between list items.

Value: Length

Example:

<code>ListView { list-item-gap: 2px; }</code>

== list-over-flow-gap ==

Sets the gap between list items on overflow=WRAP in direction perpendicular to list direction.

Value: Length

Example:

<code>ListView { list-over-flow-gap: 2px; }</code>

== line-height ==

Styles the line height as a percentage of the font height in the TextAreaBox.

Value: Number

Example:

<code>TextAreaBox { line-height: 1.2; }</code>

= Attributes =

== overflow ==

Specifies how to layout items on overflow in the ListView.

Value: Overflow

Example:

<syntaxhighlight lang="css">ListView { overflow: wrap; }

ListView[overflow=wrap] {
}</syntaxhighlight>

== edge-navigation ==

Specifies the navigation behavior when the first or last list item is selected and the key for next or previous list item is pressed.

Value: EdgeNavigation

Example:

<syntaxhighlight lang="css">ListView { edge-navigation: wrap; }

ListView[edge-navigation=wrap] {
}</syntaxhighlight>

== orientation ==

Specifies the orientation of the ListView.

Value: Orientation

Example:

<syntaxhighlight lang="css">ListView { orientation: vertical; }

ListView[orientation=vertical] {
}</syntaxhighlight>

== date-format ==

Specifies the accepted date format of the DateBox.

Value: DateFormat

Example:

<syntaxhighlight lang="css">DateBox { date-format: YYYYMMDD; }

DateBox[date-format=YYYYMMDD] {
}</syntaxhighlight>

== visibility ==

It specifies whether an element is visible.

Value: Visibility

Example:

<syntaxhighlight lang="css">Tag:read-only > Button {
visibility: none;
}</syntaxhighlight>

= Expression (Function) =

== chain ==

It chains two Expressions together, evaluating to the first until the first expression terminates, and then evaluating to the second.

Syntax:

<code>chain(expression1, expression2)</code>

Example:

<syntaxhighlight lang="css">TextBox {
border-color: chain(timeout(0xB71C1C, 550ms), revert);
}</syntaxhighlight>

== linear ==

It calculates a linear transition between two sub-expressions.

Syntax:

<code>linear(initial-expression, end-expression, duration)</code>

Example:

<syntaxhighlight lang="css">TextBox {
border-color: linear(0xB71C1C, revert, 300ms);
}</syntaxhighlight>

== minimum ==

It calculates the minimum of two values.

Syntax:

<code>min(expression1, expression2) </code>

Example:

<syntaxhighlight lang="css">Box {
border-size: min(10, 20);
}</syntaxhighlight>

== revert ==

It reverts a property's value as if it had not been set by the current rule. It doesn’t take any parameters.

Syntax:

<code>revert</code>

Example:

<syntaxhighlight lang="css">TextBox {
border-color: chain(timeout(0xF2F2FF, 250ms),
linear(0xF2F2FF, revert, 300ms));
}</syntaxhighlight>

== timeout ==

It evaluates an expression for a specified duration and then terminates.

Syntax:

<code>timout(expression, duration)</code>

Example:

<syntaxhighlight lang="css">TextBox {
border-color: chain(timeout(0xB71C1C, 550ms), revert);
}</syntaxhighlight>

= Some examples =

== Child selector with pseudo-classes ==

<syntaxhighlight lang="css">Button
style.get((Checked() && !Hover() && !Press()) > is_a<Icon>()).
set(Fill(QColor(0x7F5EEC)));

Button:checked:not(:hover):not(:press) > Icon {
fill: 0x7F5EEC;
}</syntaxhighlight>

== Flip in the DecimalBox ==

<syntaxhighlight lang="css">update_style(*decimal_box, [] (auto& style) {
style.get(ReadOnly() > is_a<Button>()).set(Visibility::NONE);
style.get(+Any() > (is_a<Button>() && !matches(Visibility::NONE))).
set(PaddingRight(scale_width(24)));
});

DecimalBox {
& :read-only {
Button {
visibility: none;
}
}
& :flip(> Button:not([visibility=none])) {
padding-right: 24px;
}
}</syntaxhighlight>

== Clear ==

<syntaxhighlight lang="css">update_style(*m_text_box, [] (auto& style) {
style.get(ReadOnly()).clear();
style.get(Disabled()).clear();
style.get(ReadOnly() && Disabled()).clear();
});

DropDownBox > TextBox {
& :read-only {
all: unset;
}
& :disabled {
all: unset;
}
& :read-only:disabled {
all: unset;
}
}</syntaxhighlight>

== Update icons for the Slider ==

<syntaxhighlight lang="css"> auto track_image = QImage(":/Icons/hue-spectrum.png");
auto thumb_image =
imageFromSvg(":/Icons/color-thumb.svg", scale(14, 14));
update_style(*slider, [&] (auto& style) {
style.get(Any() > Track()).set(IconImage(track_image));
style.get(Any() > Thumb() > is_a<Icon>()).
set(Fill(boost::optional<QColor>())).
set(IconImage(thumb_image));
style.get(Focus() > Thumb() > is_a<Icon>()).
set(Fill(QColor(0x808080)));
});

Slider {
::track {
icon-image: url(":/Icons/hue-spectrum.png");
}
::thumb > Icon {
icon-image: url(":/Icons/color-thumb.svg") 14px 14px;
fill: none;
}
& :focus {
::thumb > Icon {
fill: 0x808080;
}
}
}</syntaxhighlight>

== LabelButton styling ==

<syntaxhighlight lang="css"> style.get(Any() > Body()).
set(TextAlign(Qt::Alignment(Qt::AlignCenter))).
set(border(scale_width(1), QColor(Qt::transparent))).
set(BackgroundColor(QColor(0xEBEBEB))).
set(horizontal_padding(scale_width(8)));
style.get(Hover() > Body()).
set(TextColor(QColor(0xFFFFFF))).
set(BackgroundColor(QColor(0x4B23A0)));
style.get(Press() > Body()).
set(TextColor(QColor(0xFFFFFF))).
set(BackgroundColor(QColor(0x7E71B8)));
style.get(FocusVisible() > Body()).set(border_color(QColor(0x4B23A0)));
style.get(Disabled() > Body()).set(TextColor(QColor(0xB8B8B8)));

Button {
::body {
text-align: center;
boder: 1px transparent;
background-color: 0xEBEBEB;
horizontal-padding: 8px;
}
&:hover {
::body {
text-color: 0xFFFFFF;
background-color: 0x4B23A0;
}
}
&:press {
::body {
text-color: 0xFFFFFF;
background-color: 0x7E71B8;
}
}
&:focus-visible {
::body {
border-color: 0x4B23A0;
}
}
&:disabled {
::body {
text-color: 0xB8B8B8;
}
}
}</syntaxhighlight>

== DeleteIconButton styling ==

<syntaxhighlight lang="css">update_style(*button, [] (auto& style) {
style.get(Any() > is_a<Box>()).
set(BackgroundColor(QColor(Qt::transparent)));
style.get(Any() > is_a<Icon>()).
set(BackgroundColor(QColor(Qt::transparent))).
set(Fill(QColor(0xA0A0A0)));
style.get((Hover() || Press()) > is_a<Icon>()).
set(BackgroundColor(QColor(0xEBEBEB))).
set(Fill(QColor(0x4B23A0)));
style.get(Disabled() > is_a<Icon>()).set(Fill(QColor(0xD0D0D0)));
});

Button {
Box {
background-color: transparent;
}
Icon {
background-color: transparent;
fill: 0xA0A0A0;
}
& :hover,
& :press {
Icon {
background-color: 0xEBEBEB;
fill: 0x4B23A0;
}
}
& :disabled {
Icon {
fill: 0xD0D0D0;
}
}
}</syntaxhighlight>

== TextBox styling ==

<syntaxhighlight lang="css">TextBox
auto style = StyleSheet();
auto font = QFont("Roboto");
font.setWeight(QFont::Normal);
font.setPixelSize(scale_width(12));
style.get(Any()).
set(BackgroundColor(QColor(0xFFFFFF))).
set(border(scale_width(1), QColor(0xC8C8C8))).
set(text_style(font, QColor(Qt::black))).
set(TextAlign(Qt::Alignment(Qt::AlignLeft) | Qt::AlignVCenter)).
set(horizontal_padding(scale_width(8))).
set(vertical_padding(scale_height(5)));
style.get(Hover() || Focus()).
set(border_color(QColor(0x4B23A0)));
style.get(ReadOnly()).
set(BackgroundColor(QColor(Qt::transparent))).
set(border_color(QColor(Qt::transparent))).
set(horizontal_padding(0));
style.get(Disabled()).
set(BackgroundColor(QColor(0xF5F5F5))).
set(border_color(QColor(0xC8C8C8))).
set(TextColor(QColor(0xC8C8C8)));
style.get(ReadOnly() && Disabled()).
set(BackgroundColor(QColor(Qt::transparent))).
set(border_color(QColor(Qt::transparent)));
style.get(Rejected()).
set(BackgroundColor(chain(timeout(QColor(0xFFF1F1), milliseconds(250)),
linear(QColor(0xFFF1F1), revert, milliseconds(300))))).
set(border_color(
chain(timeout(QColor(0xB71C1C), milliseconds(550)), revert)));
style.get(Placeholder()).set(TextColor(QColor(0xA0A0A0)));
style.get(Disabled() > Placeholder()).set(TextColor(QColor(0xC8C8C8)));
</syntaxhighlight>

<syntaxhighlight lang="css">TextBox {
background-color: 0xFFFFFF;
border: 1px 0xC8C8C8;
text-style: normal 12px "Roboto" black;
text-align: left;
horizontal-padding: 8px;
vertical-padding: 5px;
& :hover,
& :focus {
border-color: 0x4B23A0;
}
& :read-only {
background-color: transparent;
border-color: transparent;
horizontal-padding: 0px;
}
& :disabled {
background-color: 0xF5F5F5;
border-color: 0xC8C8C8;
text-color: 0xC8C8C8;
}
& :read-only:disabled {
background-color: transparent;
border-color: transparent;
}
& :rejected {
background-color: chain(timeout(0xB71C1C, 250ms), linear(0xFFF1F1, revert, 300ms));
border-color: chain(timeout(0xB71C1C, 550ms), revert);
}
& ::placeholder {
text-color: 0xA0A0A0;
}
& :disabled::placeholder {
text-color: 0xC8C8C8;
}
}</syntaxhighlight>

== DropDownBox styling ==

<syntaxhighlight lang="css">auto style = StyleSheet();
style.get(ReadOnly() > is_a<TextBox>()).
set(BackgroundColor(QColor(Qt::transparent))).
set(border_color(QColor(Qt::transparent))).
set(horizontal_padding(0));
style.get(Disabled() > is_a<TextBox>()).
set(BackgroundColor(QColor(0xF5F5F5))).
set(border_color(QColor(0xC8C8C8))).
set(TextColor(QColor(0xC8C8C8)));
style.get((ReadOnly() && Disabled()) > is_a<TextBox>()).
set(BackgroundColor(QColor(Qt::transparent))).
set(border_color(QColor(Qt::transparent)));
style.get(Any() > (is_a<Icon>() && !(+Any() << is_a<ListItem>()))).
set(Fill(QColor(0x333333))).
set(BackgroundColor(QColor(Qt::transparent)));
style.get(Disabled() > (is_a<Icon>() && !(+Any() << is_a<ListItem>()))).
set(Fill(QColor(0xC8C8C8)));
style.get(ReadOnly() > (is_a<Icon>() && !(+Any() << is_a<ListItem>()))).
set(Visibility::NONE);
style.get(Any() > (is_a<TextBox>() && !(+Any() << is_a<ListItem>()))).
set(PaddingRight(scale_width(14)));
style.get(PopUp() > is_a<TextBox>() ||
(+Any() > is_a<Button>() && (Hover() || FocusIn())) > is_a<TextBox>()).
set(border_color(QColor(0x4B23A0)));
style.get(ReadOnly() > (is_a<TextBox>() && !(+Any() << is_a<ListItem>()))).
set(horizontal_padding(0)).
set(border_color(QColor(Qt::transparent))).
set(BackgroundColor(QColor(Qt::transparent)));
</syntaxhighlight>

<syntaxhighlight lang="css">DropDownBox {
& :read-only > TextBox {
background-color: transparent;
border-color: transparent;
horizontal-padding: 0;
}
& :disabled > TextBox {
background-color: 0xF5F5F5;
border-color: 0xC8C8C8;
text-color: 0xC8C8C8;
}
& :read-only:disabled > TextBox {
background-color: transparent;
border-color: transparent;
}
& :not(:flip(:has(>> ListItem))) {
Icon {
fill: 0x333333;
background-color: transparent;
}
TextBox {
padding-right: 14px;
}
}
& :disabled:not(:flip(:has(>> ListItem))) > Icon {
fill: 0xC8C8C8;
}
& :read-only:not(:flip(:has(>> ListItem))) > Icon {
visibility: none;
}
& :pop-up,
& :hover:flip(> Button),
& :focus-in:flip(> Button) {
TextBox {
border-color: 0x4B23A0;
}
}
& :read-only:not(:flip(:has(>> ListItem))) {
TextBox {
horizontal-padding: 0;
border-color: transparent;
background-color: transparent;
}
}
}

or

& :pop-up,
& :flip(> Button):is(:hover, :focus-in) {
TextBox {
border-color: 0x4B23A0;
}
}</syntaxhighlight>

== EditableTableView styling ==

<syntaxhighlight lang="css"> auto style = StyleSheet();
auto body_selector = Any() > is_a<TableBody>();
auto item_selector = body_selector > Row() > is_a<TableItem>();
style.get(item_selector > Any() >
(ReadOnly() && !(+Any() << is_a<ListItem>()) && !Prompt())).
set(horizontal_padding(scale_width(8)));
style.get(item_selector > Any() > ReadOnly() >
(is_a<TextBox>() && !(+Any() << is_a<ListItem>()) && !Prompt())).
set(horizontal_padding(scale_width(8)));
style.get((item_selector > !ReadOnly()) << Current()).
set(border_color(QColor(Qt::transparent)));
style.get(body_selector > Row() > Current()).
set(BackgroundColor(Qt::transparent));
style.get(body_selector > Row() > HoverItem()).
set(border_color(QColor(0xA0A0A0)));
style.get(body_selector > (Row() && Hover())).
set(BackgroundColor(0xF2F2FF));
style.get(item_selector > DeleteButton()).
set(Visibility(Visibility::INVISIBLE));
style.get(item_selector > DeleteButton() > is_a<Box>()).
set(BackgroundColor(QColor(Qt::transparent))).
set(horizontal_padding(scale_width(2))).
set(vertical_padding(scale_height(2)));
style.get(item_selector > DeleteButton() > is_a<Icon>()).
set(BackgroundColor(QColor(Qt::transparent)));
style.get(body_selector > (CurrentRow() || (Row() && Hover())) >
is_a<TableItem>() > DeleteButton()).
set(Visibility(Visibility::VISIBLE));
style.get((body_selector > (CurrentRow() || (Row() && Hover()))) >
DeleteButton() > is_a<Icon>()).
set(Fill(QColor(0x535353)));
style.get(body_selector > (Row() && Hover()) > DeleteButton() >
(is_a<Icon>() && Hover())).
set(BackgroundColor(QColor(0xDFDFEB))).
set(Fill(QColor(0xB71C1C)));
style.get(body_selector > CurrentRow() > DeleteButton() >
(is_a<Icon>() && Hover())).
set(BackgroundColor(QColor(0xD0CEEB))).
set(Fill(QColor(0xB71C1C)));
style.get((item_selector > EmptyCell()) << (HoverItem() || Current())).
set(border_color(QColor(Qt::transparent)));
style.get(body_selector > CurrentRow()).
set(BackgroundColor(QColor(0xE2E0FF)));
style.get(body_selector > CurrentColumn()).
set(BackgroundColor(Qt::transparent));

</syntaxhighlight>

<syntaxhighlight lang="css">EditableTableView {
TableBody {
TableBody::row {
TableItem {
* {
:not(:flip(:has(>> ListItem))) {
:read-only:not(KeyInputBox::prompt) {
horizontal-padding: 8px;
}
}
:read-only:not(:flip(:has(>> ListItem))) {
TextBox:not(KeyInputBox::prompt) {
horizontal-padding: 8px;
}
}
}
}
& :current:has(> :not(:read-only)) {
border-color: transparent;
}
& :current {
background-color: transparent;
}
& :hover-item {
border-color: 0xA0A0A0;
}
::delete-button {
visibility: invisible;
Box {
background-color: transparent;
horizontal-padding: 2px;
vertical-padding: 2px;
}
Icon {
background-color: transparent;
}
}
& :has(> ::empty-cell) {
& :hover-item,
& :current {
border-color: transparent;
}
}
}
& :hover {
background-color: 0xF2F2FF;
TableItem::delete-button {
visibility: visible;
Icon {
fill: 0x535353;
& :hover {
background-color: 0xDFDFEB;
fill: 0xB71C1C;
}
}
}
}
& :current-row {
background-color: 0xE2E0FF;
TableItem::delete-button {
visibility: visible;
Icon {
fill: 0x535353;
& :hover {
background-color: 0xDFDFEB;
fill: 0xB71C1C;
}
}
}
}
& :current-column {
background-color: transparent;
}
}
}</syntaxhighlight>

Styling Grammar

2024-09-06T19:24:31Z

Jon: Detailed reference of the styling grammar for the UI.

= Syntax =

== Declarations ==

A property and value pair is called a declaration'''.''' The pair is separated by a colon, '<code>:</code>'. White spaces are ignored. Properties and values are case-insensitive. If the value is invalid for the property, the declaration will be ignored.

<pre>Property value
background-color: white</pre>

== Declaration blocks ==

A pair of brackets, ‘<code>{</code>’ and ‘<code>}</code>’, are used to group multiple declarations into a block. The semicolon ‘<code>;</code>’ is used to separate different declarations.

<pre>{
background-color: white;
border-size: 1px;
}</pre>

== Selector ==

The selector specifies which components are being applied for styles.

Selector types:

{| class="wikitable simple-table"
|-
| | '''Selector'''
| | '''Explanation'''
| | '''Example'''
| | '''Spire styling'''
|-
| | Any selector (universal selector)
| | Selects all components.
| | *
| | Any()
|-
| | Type selector
| | Selects all instances of the selector and of its subclasses.
| | TextBox
| | is_a<Type>
|-
| | Property selector
| | Selects elements based on the element having a given attribute explicitly set.
| | Button[visibility=none] 
Button:not([visibility=none]) 

| | Button && matches(Visibility::NONE) 
Button && !matches(Visibility::NONE) 

|-
| | & nesting selector
| | The & nesting selector makes the nested child rule selectors relative to the parent element. Without the & nesting selector, the child rule selector selects child elements.
| | <code>parentRule {</code> 
<code>/* parent rule style properties */</code> 
<code>& childRule {</code> 
<code>/* child rule style properties */</code> 
 
} 
} 

| |
|}

The class selector and ID selector in CSS are not supported since the Spire styling doesn’t support them.

{| class="wikitable simple-table"
|-
| | <s>Class selector</s>
| | Selects all instances of the selector.
| | .TextBox
| | Not support
|-
| | <s>ID selector</s>
| | Matches all instances that has a specific object name.
| | #my-label
| | Not support
|}

== Pseudo-classes ==

The pseudo-class specifies a given state to the components. It starts with a colon.

<pre>:pseudo-class {
property: value;
}</pre>
{| class="wikitable simple-table"
|-
| | '''Selector'''
| | '''Explanation'''
| | '''Related components'''
|-
| | :active
| | Selects a component that is or belongs to the active window.
| | All components
|-
| | :disabled
| | Selects a disabled component.
| | All components
|-
| | :hover
| | Selects a hovered component.
| | All components
|-
| | :focus
| | Selects a focused component.
| | All components
|-
| | :focus-in
| | Selects a component that has focus or has a child that has focus..
| | All components
|-
| | :focus-visible
| | Selects a component if it was focused using a non-pointing device
| | All components
|-
| | :drag
| | Selects a Dragged component.
| | SplitView, ScrollBar
|-
| | :press
| | Selects a pressed component.
| | Button, Slider, Slider2D, MenuButton
|-
| | :read-only
| | Selects a read-only component.
| | All input boxes.
|-
| | :rejected
| | Selects a a component whose input value is rejected.
| | TextBox, DurationBox, DestinationBox, SaleConditionBox, DateBox
|-
| | :checked
| | Selects a checked CheckBox.
| | CheckBox
|-
| | :selected
| | Selects a selected list item.
| | ListItem
|-
| | :current
| | Selects the current list item.
| | ListItem
|-
| | :precedes-current
| | Selects the list item precedes the current item.
| | ListItem
|-
| | :hover-item
| | Selects the hovered table item
| | TableItem
|-
| | :current-row
| | Selects the current row in the table.
| | TableBody
|-
| | :current-column
| | Selects the current column in the table.
| | TableBody
|-
| | :sortable
| | Selects the column when it's sort order is not UNORDERED.
| | TableHeaderItem
|-
| | :filtered
| | Selects the column when a filter is applied.
| | TableHeaderItem
|-
| | :pop-up
| | Selects the widget displaying a pop-up.
| | DropDownBox
|-
| | :high-lighted
| | Selects the highlighted widget.
| | ColorSwatch
|-
| | :is-positive
| | Selects the DecimalBox when its value is positive.
| | DecimalBox
|-
| | :is-negative
| | Selects the DecimalBox when its value is negative.
| | DecimalBox
|-
| | :uptick
| | Selects the DecimalBox when its value has increased.
| | DecimalBox
|-
| | :downtick
| | Selects the DecimalBox when its value has decreased.
| | DecimalBox
|-
| | :modifier-key
| | Selects the KeyTag when it's displaying a modifier key.
| | KeyTag
|-
| | :escape-key
| | Selects the KeyTag when it's displaying the ESC key.
| | KeyTag
|-
| | :today
| | Selects the CalendarDatePicker when the current day is today.
| | CalendarDatePicker
|-
| | :out-of-month
| | Selects the CalendarDatePicker when a day is outside of the current month.
| | CalendarDatePicker
|-
| | :has()
| | Takes a selector as its argument and matches any element matching this selector.
| | All components
|-
| | :not()
| | Selects a component that is not selected by a selector.
| | All components
|-
| | :flip()
| | Flips what elements are selected.
| | All components
|-
| | :is()
| | Selects any element that can be selected by one of the selectors in its list. 
 
<code>:is(selector1, selector2, ...)</code>
| | All components
|}

== Pseudo-elements ==

A pseudo-element selects components that are the specific part of a selector. The pseudo-element must be used in combination with a block-level element selector. This means you cannot use pseudo-elements on its own without specifying a block-level element. Pseudo-elements start with a double colon <code>::</code> .

<pre>selector::pseudo-element {
property: value;
}</pre>
{| class="wikitable simple-table"
|-
| | '''Selector'''
| | '''Explanation'''
| | '''Related components'''
| | '''Spire styling'''
|-
| | ::placeholder
| | Select the placeholder in the text box.
| | TextBox, TextAreaBox
| | <code>PseudoElement</code>
|}

== Sub-controls ==

Selectors can contain sub-controls that make it possible to restrict the application of a rule to specific sub-controls. Its syntax is same as pseudo-element’s.

<pre>selector::sub-controls{
property: value;
}</pre>
{| class="wikitable simple-table"
|-
| | '''Selector'''
| | '''Explanation'''
| | '''Related components'''
|-
| | ::row
| | Selects all rows in the table.
| | TableBody
|-
| | ::column
| | Selects all columns in the table.
| | TableBody
|-
| | ::prompt
| | Selects the prompt in a key input box.
| | KeyInputBox
|-
| | ::divider
| | Selects the divider.
| | TabView, SplitView
|-
| | ::body
| | Selects the body component of a box or button.
| | Box, Button
|-
| | ::empty-cell
| | Selects the empty table cell in the EditableTableView.
| | TableItem(EditableTableView)
|-
| | ::delete-button
| | Selects the delete button in the EditableTableView.
| | TableItem(EditableTableView)
|-
| | ::label
| | Selects the label inside the TableHeaderItem.
| | TableHeaderItem
|-
| | ::filter-button
| | Selects the filter button inside the TableHeaderItem.
| | TableHeaderItem
|-
| | ::hover-element
| | Selects the hover element inside the TableHeaderItem.
| | TableHeaderItem
|-
| | ::track
| | Selects the track of the slider.
| | Slider, Slider2D
|-
| | ::thumb
| | Selects the thumb of the slider.
| | Slider, Slider2D
|-
| | ::track-rail
| | Selects the track rail of the slider.
| | Slider
|-
| | ::track-fill
| | Selects the track fill of the slider.
| | Slider
|-
| | ::track-pad
| | Selects the track pad of the 2d slider.
| | Slider2D
|-
| | ::scrollbar-track
| | Selects the track of the scroll bar.
| | ScrollBar
|-
| | ::scrollbar-thumb
| | Selects the thumb of the scroll bar.
| | ScrollBar
|-
| | ::colon
| | Selects the colon field.
| | DurationBox
|-
| | ::alpha
| | Selects the alpha component in the ColorCodePanel.
| | ColorCodePanel
|-
| | ::primary
| | Selects the primary component in the SplitView.
| | SplitView
|-
| | ::secondary
| | Selects the secondary component in the SplitView.
| | SplitView
|}

== Selectors Combination ==

{| class="wikitable simple-table"
|-
| | '''Selector'''
| | '''Explanation'''
| | '''Syntax'''
| | '''Example'''
| | '''CSS supports'''
|-
| | Child selector
| | Selects a component matched by the second selector that is the direct child of the component matched by the first.
| | <code>selector1 > selector2</code>
| | <code>TableView > TableBody</code>
| | Yes
|-
| | Descendant selector
| | Selects a component matched by the second selector that is the descendant of the component matched by the first.
| | <code>selector >> descendant- selector</code>
| | <code>ColorPicker >> Alpha</code>
| | Yes, but a single space is used.
|-
| | Parent selector
| | Selects a component matched by the second selector that is the direct parent of the component matched by the first.
| | <code>:has(> child-selector)</code> 
 

| | <code>ListItem:has(> TextBox)</code> 
 

| | The <code>:has() </code>pseudo-class can achieve the functionality.
|-
| | Ancestor selector
| | Selects a component matched by the second selector that is the ancestor of the component matched by the first.
| | <code>:has(>> descendant-selector)</code> 
 

| | <code>TableItem:has(>> TableItem)</code> 
 

| | The <code>:has() </code>pseudo-class can achieve the functionality.
|-
| | And selector
| | Selects components that are matched by both selectors.
| | <code><selector1><selector2></code>
| | <code>TextBox:hover</code> 
 

| | Combining Type selector and Pseudo-Class
|-
| | Flip selector
| | Flips what elements are selected.
| | <code>:flip()</code>
| | <code>*:flip(:has(>> ListItem))</code>
| | No
|-
| | Not selector
| | Selects a component that is not selected by a selector.
| | <code>:not()</code>
| | <code>:not(:hover)</code>
| | <code>:not()</code>
|-
| | Or selector
| | Selects a component that is selected by at least one of two selectors.
| | <code>selector1, selector2</code>
| | <code>:hover, :focus</code> 
<code>or</code> 
 
 
<code>:is(:hover, :focus)</code>
| | selector list
|-
| | Sibling selector
| | Selects a component matched by the second selector that is the sibling of the component matched by the first.
| | <code>selector % sibling-selector</code>
| | <code>TextBox % Button</code>
| | Yes, but <code>+</code> is used.
|}

Examples:

=== Child selector ===

<pre>is_a<Button>() > is_a<TextBox>()

Button > TextBox {
}

or

Button {
TextBox {
}
}

or

Button {
& > TextBox {
}
}</pre>

=== Descendant selector ===

<pre>is_a<Button>() >> is_a<TextBox>()

Button >> TextBox {
}

or

Button {
& >> TextBox {
}
}</pre>

=== Parent selector ===

<pre>is_a<Button>() < is_a<TextBox>()

Button:has(> TextBox) {</pre>
Cases used in practice:

<pre>auto body_selector = Any() > is_a<TableBody>();
auto item_selector = body_selector > Row() > is_a<TableItem>();
style.get((item_selector > EmptyCell()) < (HoverItem() || Current())).
set(border_color(QColor(Qt::transparent)));

TableView > TableBody > TableBody::row >
TableItem:has(> TableItem::empty-cell):hover-item,
TableView > TableBody > TableBody::row >
TableItem:has(> TableItem::empty-cell):current {
}

or

TableView {
TableBody {
TableBody::row {
TableItem {
&:has(> ::empty-cell) {
& :hover-item,
& :current {
border-color: transparent;
}
}
}
}
}
}
}

or

TableView {
TableBody {
TableBody::row {
TableItem {
&:has(> ::empty-cell):is(:hover-item, :current) {
border-color: transparent;
}
}
}
}
}
}</pre>

=== Ancestor selector ===

<pre>is_a<Button>() << is_a<TextBox>(

Button:has(>> TextBox) {
}</pre>

=== And selector ===

<pre>is_a<TextBox>() && Hover()

TextBox:hover</pre>
<pre>is_a<TextBox>() && ReadOnly() && Disabled()

TextBox:read-only:disabled</pre>
<pre>is_a<TextBox>() && !Prompt()

TextBox:not(KeyInputBox::Prompt)</pre>

=== Flip selector ===

<pre>+Any()

*:flip()</pre>

=== Not selector ===

<pre>!Hover()

:not(:hover)</pre>
<pre>!Prompt()

:not(KeyInputBox::prompt)</pre>

=== Or selector ===

<pre>is_a<TextBox>() && (Hover() || Focus()).
set(border_color(QColor(0x4B23A0)));

TextBox:hover, TextBox:focus {
border-color: 0x4B23A0;
}

or

TextBox {
&:hover,
&:focus {
border-color: 0x4B23A0;
}
}

or

TextBox {
&:is(:hover, :focus) {
border-color: 0x4B23A0;
}
}</pre>

=== Sibling selector ===

<pre>is_a<TextBox>() % is_a<Button>()

TextBox % Button

TextBox {
& % Button {
}
}</pre>

== Rules ==

A selector list and an associated declaration block are called a rule.

<pre>TextBox {
background-color: white;
border-size: 1px;
}</pre>
A commas, ‘<code>,</code>’, is used to separated different selectors which have the the same declaration block.

<pre>TextBox, Button {
background-color: white;
border-size: 1px;
}</pre>

== Inheritance ==

Unlike CSS, a component doesn’t automatically inherit font and color settings from its parent component.

== Nesting style ==

Nesting refers to the practice of placing rules inside other rules. It allows you to group related styles together to improve readability and reduce repetition.

<pre>parent {
/* parent styles */
child {
/* child of parent styles */
}
}

parent {
/* parent styles */
& child {
/* child of parent styles */
}
}</pre>
The difference between using <code>&</code> nesting selectors and not using nesting selectors.

* ''without'' the <code>&</code> nesting selector

<pre>Button {
/* parent styles */
:hover {
/* child of parent styles */
}
}</pre>
It automatically adds the Child selector <code>></code> between the selectors to create a new selector rule(CSS adds a whitespace between the selectors, building the descendant relationship between selectors by default). The following code shows the equivalent non-nested rules:

<pre>Button {
/* parent styles */
}

/* styles the hovered button's children. */
Button > :hover {
/* child of parent styles */
}

is_a<Button>() > Hover()</pre>
* ''with'' the <code>&</code> nesting selector

<pre>Button {
/* parent styles */
& :hover {
/* child of parent styles */
}
}</pre>
With the <code>&</code> nesting selector added with no whitespace, the above block equals to the following code:

<pre>Button {
/* parent styles */
}

/* styles the hovered button. */
Button:hover {
}

is_a<Button>() && Hover()</pre>
Other examples

<pre>is_a<Button>() >> is_a<TextBox>()

Button {
/* parent styles */
& >> TextBox {
/* child of parent styles */
}
}

or

Button {
>> TextBox {
background-color: black;
}
}

Button {
/* parent styles */
}

/* styles the hovered button. */
Button >> TextBox {
/* child of parent styles */
}</pre>

= Values =

== Number ==

A decimal integer or a real number.

Example:

<code>0, 1, 10, 1.5</code>

== Length ==

Syntax:

<code>Number(px | pt | ch)</code>

== Color ==

<ol style="list-style-type: decimal;">
<li>'''Hexadecimal Colors'''
Syntax:
<code>#rrggbb</code>
Example:
<code>TextBox {background-color: #ff0000;}</code></li></ol>

<ol start="2" style="list-style-type: decimal;">
<li>'''Hexadecimal Colors With Transparency'''
Syntax:
<code>#rrggbbaa</code>
Example:
<code>TextBox {background-color: #ff000008;}</code></li></ol>

<ol start="3" style="list-style-type: decimal;">
<li>'''RGB Colors'''
An RGB color value is specified with syntax <code>rgb()</code>, which has the following syntax:
<code>rgb(red, green, blue)</code>
Each parameter is an integer between 0 and 255.
Example:
<code>TextBox {background-color: rgb(255, 0, 0);} </code></li></ol>

<ol start="4" style="list-style-type: decimal;">
<li>'''RGBA Colors'''
RGBA color values are an extension of RGB color values with an alpha channel. The syntax is
<code>rgba(red, green, blue, alpha)</code>
The alpha parameter is a number between 0.0 (fully transparent) and 1.0 (fully opaque).
Example:
<code>TextBox {background-color: rgba(255, 0, 0, 0.3);} </code></li></ol>

<ol start="5" style="list-style-type: decimal;">
<li>'''Predefined Color Names'''
Only three color names that have been used in Spire are defined here.
<ul>
<li>transparent</li></ul>

<ul>
<li>white</li></ul>

<ul>
<li>black</li></ul>

Example:
<code>TextBox {background-color: transparent;} </code></li></ol>

== Font Style ==

* '''normal'''

* '''italic'''

* '''oblique'''

Example:

<code>#TextBox {font-style: italic;} </code>

== Font Weight ==

Predefined weight values which Qt supports:

<ul>
<li>'''thin'''
Same as 100.</li></ul>

<ul>
<li>'''extra-light'''
Same as 200.</li></ul>

<ul>
<li>'''light'''
Same as 300.</li></ul>

<ul>
<li>'''normal'''
Same as 400.</li></ul>

<ul>
<li>'''medium'''
Same as 500.</li></ul>

<ul>
<li>'''demi-bold'''
Same as 600.</li></ul>

<ul>
<li>'''bold'''
Same as 700.</li></ul>

<ul>
<li>'''extra-bold'''
Same as 800.</li></ul>

<ul>
<li>'''black'''
Same as 900.</li></ul>

== Alignment ==

<code>{left | right | top | bottom | center}*</code>

== Time ==

It represents a time value expressed in seconds or milliseconds. There is no space between Number and <code>s </code>or <code>ms</code>.

Syntax:

<code>Number(s | ms)</code>

== Overflow ==

<ul>
<li>'''none'''
The list extends indefinitely.</li></ul>

<ul>
<li>'''wrap'''
List items wrap to fill the perpendicular space.</li></ul>

== EdgeNavigation ==

<ul>
<li>'''contain'''
Selection stops at the current selection.</li></ul>

<ul>
<li>'''wrap'''
Selection moves from the first item to last item and vice versa.</li></ul>

== Orientation ==

<ul>
<li>'''horizontal'''
The element is laid out horizontally.</li></ul>

<ul>
<li>'''vertical'''
The element is laid out vertically.</li></ul>

== DateFormat ==

<ul>
<li>'''YYYYMMDD'''
The year, month, and day can be input in a YYYY-MM-DD format.</li></ul>

<ul>
<li>'''MMDD'''
The month and day can be input in a MM-DD format.</li></ul>

== Visibility ==

<ul>
<li>'''visible'''
The element is visible.</li></ul>

<ul>
<li>'''invisible'''
The element is invisible.</li></ul>

<ul>
<li>'''none'''
The element is treated as if it has a width and height of 0.</li></ul>

= Properties =

== all ==

The <code>all</code> property is a property that resets all properties.

Value:

<ul>
<li>unset
The unset keyword clears styles of all properties, which has the different meaning with CSS unset. In CSS, unset specifies that all the element's properties should be changed to their inherited values if they inherit by default, or to their initial values if not.</li></ul>

Syntax:

<code>all: unset;</code> 
 
Example: 

<pre>TextBox:read-only {
all: unset;
}

style.get(ReadOnly()).clear();</pre>

== Font ==

=== '''font-family''' ===

Example:

<code>#TextBox {font-family: "Roboto";}</code>

=== '''font-style''' ===

Example:

<code>#TextBox {font-style: normal;}</code>

=== '''font-weight''' ===

The weights available depend on the <code>font-style</code> that is currently set. It doesn’t support arbitrary values since QFont::setWeight() uses QFont::Weight enumeration as the parameter. Referring to <code>Font weight</code>.

Example:

<code>#TextBox {font-weight: normal;}</code>

=== '''font-size''' ===

Sets the element's font size. Only pt and px metrics are supported. 
Example: 

<code>#TextBox {font-size: 12px;}</code>

=== '''font (shorthand)''' ===

Syntax: 
 
<code>font = font-style? font-weight? font-size font-family</code>

Example:

<code>#TextBox {font: normal medium 12px "Roboto";}</code>

== Icon ==

=== '''url''' ===

Syntax:

<code>url(filename)</code>

filename is the name of a file on the local disk or stored using the Qt resource system.

Example:

<code>url(":/Icons/spire.svg”)</code>

=== '''fill''' ===

Syntax:

<code>fill = color | none</code>

Example:

<pre>Icon { fill: 0xA0A0A0; }
Icon { fill: none; }</pre>

=== '''icon-image''' ===

Syntax:

<code>icon-image = url (width height)?</code>

Example:

<pre>Icon { icon-image: url(":/Icons/spire.svg”) 16px 16px; }</pre>

== Text ==

=== '''text-align''' ===

Value: Alignment

Example:

<pre>TextBox {
text-align: left;
}</pre>

=== '''text-color''' ===

Value: Color

Example:

<pre>TextBox {
text-color: black;
}</pre>

=== '''text-style''' (Shorthand) ===

Syntax:

<code>text-style = font text-color</code>

Example:

<pre>TextBox {
text-style: normal 12px "Roboto" black;
}</pre>

== Border ==

=== '''border-top-size''' ===

Styles the size of the top border.

Value: Length

Example:

<code>Box { border-top-size: 1px; }</code>

=== '''border-right-size''' ===

Styles the size of the right border.

Value: Length

Example:

<code>Box { border-right-size: 1px; }</code>

=== '''border-bottom-size''' ===

Styles the size of the bottom border.

Value: Length

Example:

<code>Box { border-bottom-size: 1px; }</code>

=== '''border-left-size''' ===

Styles the size of the left border.

Value: Length

Example:

<code>Box { border-left-size: 1px; }</code>

=== '''border-top-color''' ===

Styles the color of the top border.

Value: Color

Example:

<code>Box { border-top-color: 0x4B23A0; }</code>

=== '''border-right-color''' ===

Styles the color of the right border.

Value: Color

Example:

<code>Box { border-right-color: 0x4B23A0; }</code>

=== '''border-bottom-color''' ===

Styles the color of the bottom border.

Value: Color

Example:

<code>Box { border-bottom-color: 0x4B23A0; }</code>

=== '''border-left-color''' ===

Styles the color of the left border.

Value: Color

Example:

<code>Box { border-left-color: 0x4B23A0; }</code>

=== '''border-top-left-radius''' ===

Styles the radius of the border's top left corner.

Value: Length

Example:

<code>Box { border-top-left-radius: 1px; }</code>

=== '''border-top-right-radius''' ===

Styles the radius of the border's top right corner.

Value: Length

Example:

<code>Box { border-top-right-radius: 1px; }</code>

=== '''border-bottom-right-radius''' ===

Styles the radius of the border's bottom right corner.

Value: Length

Example:

<code>Box { border-bottom-right-radius: 1px; }</code>

=== '''border-bottom-left-radius''' ===

Styles the radius of the border's bottom left corner.

Value: Length

Example:

<code>Box { border-bottom-left-radius: 1px; }</code>

=== '''border-size''' ===

Applies a single size to all four borders: '''border-top-size, border-right-size, border-bottom-size and border-left-size.'''

Value: Length

Example:

<code>Box { border-size: 1px; }</code>

=== '''border-color''' ===

Applies a single color to all four border: '''border-top-color, border-right-color, border-bottom-color and border-left-color.'''

Value: Color

Example:

<code>Box { border-color: 0x4B23A0; }</code>

=== '''border-radius''' ===

Applies a single radius to all four corners: '''border-top-left-radius, border-top-right-radius, border-bottom-right-radius and border-bottom-left-radius.'''

Value: Length

Example:

<code>Box { border-radius: 1px; }</code>

=== '''border (shorthand)''' ===

Styles all border colors and sizes.

Syntax:

<code>border = border-size border-color</code>

Example:

<pre>TextBox {
border: 1px 0x4B23A0;
}</pre>

== Padding ==

=== '''padding-top''' ===

Styles the size of the top padding.

Value: Length

Example:

<code>Box { padding-top: 8px; }</code>

=== '''padding-right''' ===

Styles the size of the right padding.

Value: Length

Example:

<code>Box { padding-right: 8px; }</code>

=== '''padding-bottom''' ===

Styles the size of the bottom padding.

Value: Length

Example:

<code>Box { padding-bottom: 8px; }</code>

=== '''padding-left''' ===

Styles the size of the left padding.

Value: Length

Example:

<code>Box { padding-left: 8px; }</code>

=== '''horizontal-padding''' ===

Styles the size of the left and right padding.

Value: Length

Example:

<code>Box { horiztontal-padding: 8px; }</code>

=== '''vertical-padding''' ===

Styles the size of the top and bottom padding.

Value: Length

Example:

<code>Box { vertical-padding: 8px; }</code>

=== '''padding''' ===

Styles all four padding size of an element at once.

Value: Length

Example:

<code>Box { padding: 8px; }</code>

== Spacing ==

=== '''horizontal-spacing''' ===

Styles the horizontal spacing between items in the table body.

Value: Length

Example:

<code>TableBody { horizontal-spacing: 8px; }</code>

=== '''vertical-spacing''' ===

Styles the vertical spacing between items in the table body.

Value: Length

Example:

<code>TableBody { vertical-spacing: 8px; }</code>

=== '''spacing''' ===

Styles the spacing between items in the table body.

Value: Length

Example:

<code>TableBody { spacing: 8px; }</code>

== Grid Color ==

=== '''horizontal-grid-color''' ===

Styles the color of the horizontal grid lines in the table body.

Value: Color

Example:

<code>TableBody { horizontal-grid-color: transparent; }</code>

=== '''vertical-grid-color''' ===

Styles the color of the vertical grid lines in the table body.

Value: Color

Example:

<code>TableBody { vertical-grid-color: transparent; }</code>

=== '''grid-color''' ===

Styles the color of the grid lines.

Value: Color

Example:

<code>TableBody { grid-color: transparent; }</code>

== background-color ==

Sets the background color of an element.

Value: Color

Example:

<code>Box { background-color: transparent; }</code>

== body-align ==

Sets the alignment of the body in a box.

Value: Alignment

Example:

<code>DurationBox { body-align: center; }</code>

== leading-zeros ==

The number of leading zeros added as padding to a number.

Value: Number

Example:

<code>DecimalBox { leading-zeros: 4; }</code>

== trailing-zeros ==

The number of trailing zeros added as padding to the fractional part of a number.

Value: Number

Example:

<code>DecimalBox { trailing-zeros: 4; }</code>

== list-item-gap ==

Sets the spacing between list items.

Value: Length

Example:

<code>ListView { list-item-gap: 2px; }</code>

== list-over-flow-gap ==

Sets the gap between list items on overflow=WRAP in direction perpendicular to list direction.

Value: Length

Example:

<code>ListView { list-over-flow-gap: 2px; }</code>

== line-height ==

Styles the line height as a percentage of the font height in the TextAreaBox.

Value: Number

Example:

<code>TextAreaBox { line-height: 1.2; }</code>

= Attributes =

== overflow ==

Specifies how to layout items on overflow in the ListView.

Value: Overflow

Example:

<pre>ListView { overflow: wrap; }

ListView[overflow=wrap] {
}</pre>

== edge-navigation ==

Specifies the navigation behavior when the first or last list item is selected and the key for next or previous list item is pressed.

Value: EdgeNavigation

Example:

<pre>ListView { edge-navigation: wrap; }

ListView[edge-navigation=wrap] {
}</pre>

== orientation ==

Specifies the orientation of the ListView.

Value: Orientation

Example:

<pre>ListView { orientation: vertical; }

ListView[orientation=vertical] {
}</pre>

== date-format ==

Specifies the accepted date format of the DateBox.

Value: DateFormat

Example:

<pre>DateBox { date-format: YYYYMMDD; }

DateBox[date-format=YYYYMMDD] {
}</pre>

== visibility ==

It specifies whether an element is visible.

Value: Visibility

Example:

<pre>Tag:read-only > Button {
visibility: none;
}</pre>

= Expression (Function) =

== chain ==

It chains two Expressions together, evaluating to the first until the first expression terminates, and then evaluating to the second.

Syntax:

<code>chain(expression1, expression2)</code>

Example:

<pre>TextBox {
border-color: chain(timeout(0xB71C1C, 550ms), revert);
}</pre>

== linear ==

It calculates a linear transition between two sub-expressions.

Syntax:

<code>linear(initial-expression, end-expression, duration)</code>

Example:

<pre>TextBox {
border-color: linear(0xB71C1C, revert, 300ms);
}</pre>

== minimum ==

It calculates the minimum of two values.

Syntax:

<code>min(expression1, expression2) </code>

Example:

<pre>Box {
border-size: min(10, 20);
}</pre>

== revert ==

It reverts a property's value as if it had not been set by the current rule. It doesn’t take any parameters.

Syntax:

<code>revert</code>

Example:

<pre>TextBox {
border-color: chain(timeout(0xF2F2FF, 250ms),
linear(0xF2F2FF, revert, 300ms));
}</pre>

== timeout ==

It evaluates an expression for a specified duration and then terminates.

Syntax:

<code>timout(expression, duration)</code>

Example:

<pre>TextBox {
border-color: chain(timeout(0xB71C1C, 550ms), revert);
}</pre>

= Some examples =

== Child selector with pseudo-classes ==

<pre>Button
style.get((Checked() && !Hover() && !Press()) > is_a<Icon>()).
set(Fill(QColor(0x7F5EEC)));

Button:checked:not(:hover):not(:press) > Icon {
fill: 0x7F5EEC;
}</pre>

== Flip in the DecimalBox ==

<pre>update_style(*decimal_box, [] (auto& style) {
style.get(ReadOnly() > is_a<Button>()).set(Visibility::NONE);
style.get(+Any() > (is_a<Button>() && !matches(Visibility::NONE))).
set(PaddingRight(scale_width(24)));
});

DecimalBox {
& :read-only {
Button {
visibility: none;
}
}
& :flip(> Button:not([visibility=none])) {
padding-right: 24px;
}
}</pre>

== Clear ==

<pre>update_style(*m_text_box, [] (auto& style) {
style.get(ReadOnly()).clear();
style.get(Disabled()).clear();
style.get(ReadOnly() && Disabled()).clear();
});

DropDownBox > TextBox {
& :read-only {
all: unset;
}
& :disabled {
all: unset;
}
& :read-only:disabled {
all: unset;
}
}</pre>

== Update icons for the Slider ==

<pre> auto track_image = QImage(":/Icons/hue-spectrum.png");
auto thumb_image =
imageFromSvg(":/Icons/color-thumb.svg", scale(14, 14));
update_style(*slider, [&] (auto& style) {
style.get(Any() > Track()).set(IconImage(track_image));
style.get(Any() > Thumb() > is_a<Icon>()).
set(Fill(boost::optional<QColor>())).
set(IconImage(thumb_image));
style.get(Focus() > Thumb() > is_a<Icon>()).
set(Fill(QColor(0x808080)));
});

Slider {
::track {
icon-image: url(":/Icons/hue-spectrum.png");
}
::thumb > Icon {
icon-image: url(":/Icons/color-thumb.svg") 14px 14px;
fill: none;
}
& :focus {
::thumb > Icon {
fill: 0x808080;
}
}
}</pre>

== LabelButton styling ==

<pre> style.get(Any() > Body()).
set(TextAlign(Qt::Alignment(Qt::AlignCenter))).
set(border(scale_width(1), QColor(Qt::transparent))).
set(BackgroundColor(QColor(0xEBEBEB))).
set(horizontal_padding(scale_width(8)));
style.get(Hover() > Body()).
set(TextColor(QColor(0xFFFFFF))).
set(BackgroundColor(QColor(0x4B23A0)));
style.get(Press() > Body()).
set(TextColor(QColor(0xFFFFFF))).
set(BackgroundColor(QColor(0x7E71B8)));
style.get(FocusVisible() > Body()).set(border_color(QColor(0x4B23A0)));
style.get(Disabled() > Body()).set(TextColor(QColor(0xB8B8B8)));

Button {
::body {
text-align: center;
boder: 1px transparent;
background-color: 0xEBEBEB;
horizontal-padding: 8px;
}
&:hover {
::body {
text-color: 0xFFFFFF;
background-color: 0x4B23A0;
}
}
&:press {
::body {
text-color: 0xFFFFFF;
background-color: 0x7E71B8;
}
}
&:focus-visible {
::body {
border-color: 0x4B23A0;
}
}
&:disabled {
::body {
text-color: 0xB8B8B8;
}
}
}</pre>

== DeleteIconButton styling ==

<pre>update_style(*button, [] (auto& style) {
style.get(Any() > is_a<Box>()).
set(BackgroundColor(QColor(Qt::transparent)));
style.get(Any() > is_a<Icon>()).
set(BackgroundColor(QColor(Qt::transparent))).
set(Fill(QColor(0xA0A0A0)));
style.get((Hover() || Press()) > is_a<Icon>()).
set(BackgroundColor(QColor(0xEBEBEB))).
set(Fill(QColor(0x4B23A0)));
style.get(Disabled() > is_a<Icon>()).set(Fill(QColor(0xD0D0D0)));
});

Button {
Box {
background-color: transparent;
}
Icon {
background-color: transparent;
fill: 0xA0A0A0;
}
& :hover,
& :press {
Icon {
background-color: 0xEBEBEB;
fill: 0x4B23A0;
}
}
& :disabled {
Icon {
fill: 0xD0D0D0;
}
}
}</pre>

== TextBox styling ==

<pre>TextBox
auto style = StyleSheet();
auto font = QFont("Roboto");
font.setWeight(QFont::Normal);
font.setPixelSize(scale_width(12));
style.get(Any()).
set(BackgroundColor(QColor(0xFFFFFF))).
set(border(scale_width(1), QColor(0xC8C8C8))).
set(text_style(font, QColor(Qt::black))).
set(TextAlign(Qt::Alignment(Qt::AlignLeft) | Qt::AlignVCenter)).
set(horizontal_padding(scale_width(8))).
set(vertical_padding(scale_height(5)));
style.get(Hover() || Focus()).
set(border_color(QColor(0x4B23A0)));
style.get(ReadOnly()).
set(BackgroundColor(QColor(Qt::transparent))).
set(border_color(QColor(Qt::transparent))).
set(horizontal_padding(0));
style.get(Disabled()).
set(BackgroundColor(QColor(0xF5F5F5))).
set(border_color(QColor(0xC8C8C8))).
set(TextColor(QColor(0xC8C8C8)));
style.get(ReadOnly() && Disabled()).
set(BackgroundColor(QColor(Qt::transparent))).
set(border_color(QColor(Qt::transparent)));
style.get(Rejected()).
set(BackgroundColor(chain(timeout(QColor(0xFFF1F1), milliseconds(250)),
linear(QColor(0xFFF1F1), revert, milliseconds(300))))).
set(border_color(
chain(timeout(QColor(0xB71C1C), milliseconds(550)), revert)));
style.get(Placeholder()).set(TextColor(QColor(0xA0A0A0)));
style.get(Disabled() > Placeholder()).set(TextColor(QColor(0xC8C8C8)));
</pre>

<pre>TextBox {
background-color: 0xFFFFFF;
border: 1px 0xC8C8C8;
text-style: normal 12px "Roboto" black;
text-align: left;
horizontal-padding: 8px;
vertical-padding: 5px;
& :hover,
& :focus {
border-color: 0x4B23A0;
}
& :read-only {
background-color: transparent;
border-color: transparent;
horizontal-padding: 0px;
}
& :disabled {
background-color: 0xF5F5F5;
border-color: 0xC8C8C8;
text-color: 0xC8C8C8;
}
& :read-only:disabled {
background-color: transparent;
border-color: transparent;
}
& :rejected {
background-color: chain(timeout(0xB71C1C, 250ms), linear(0xFFF1F1, revert, 300ms));
border-color: chain(timeout(0xB71C1C, 550ms), revert);
}
& ::placeholder {
text-color: 0xA0A0A0;
}
& :disabled::placeholder {
text-color: 0xC8C8C8;
}
}</pre>

== DropDownBox styling ==

<pre>auto style = StyleSheet();
style.get(ReadOnly() > is_a<TextBox>()).
set(BackgroundColor(QColor(Qt::transparent))).
set(border_color(QColor(Qt::transparent))).
set(horizontal_padding(0));
style.get(Disabled() > is_a<TextBox>()).
set(BackgroundColor(QColor(0xF5F5F5))).
set(border_color(QColor(0xC8C8C8))).
set(TextColor(QColor(0xC8C8C8)));
style.get((ReadOnly() && Disabled()) > is_a<TextBox>()).
set(BackgroundColor(QColor(Qt::transparent))).
set(border_color(QColor(Qt::transparent)));
style.get(Any() > (is_a<Icon>() && !(+Any() << is_a<ListItem>()))).
set(Fill(QColor(0x333333))).
set(BackgroundColor(QColor(Qt::transparent)));
style.get(Disabled() > (is_a<Icon>() && !(+Any() << is_a<ListItem>()))).
set(Fill(QColor(0xC8C8C8)));
style.get(ReadOnly() > (is_a<Icon>() && !(+Any() << is_a<ListItem>()))).
set(Visibility::NONE);
style.get(Any() > (is_a<TextBox>() && !(+Any() << is_a<ListItem>()))).
set(PaddingRight(scale_width(14)));
style.get(PopUp() > is_a<TextBox>() ||
(+Any() > is_a<Button>() && (Hover() || FocusIn())) > is_a<TextBox>()).
set(border_color(QColor(0x4B23A0)));
style.get(ReadOnly() > (is_a<TextBox>() && !(+Any() << is_a<ListItem>()))).
set(horizontal_padding(0)).
set(border_color(QColor(Qt::transparent))).
set(BackgroundColor(QColor(Qt::transparent)));
</pre>

<pre>DropDownBox {
& :read-only > TextBox {
background-color: transparent;
border-color: transparent;
horizontal-padding: 0;
}
& :disabled > TextBox {
background-color: 0xF5F5F5;
border-color: 0xC8C8C8;
text-color: 0xC8C8C8;
}
& :read-only:disabled > TextBox {
background-color: transparent;
border-color: transparent;
}
& :not(:flip(:has(>> ListItem))) {
Icon {
fill: 0x333333;
background-color: transparent;
}
TextBox {
padding-right: 14px;
}
}
& :disabled:not(:flip(:has(>> ListItem))) > Icon {
fill: 0xC8C8C8;
}
& :read-only:not(:flip(:has(>> ListItem))) > Icon {
visibility: none;
}
& :pop-up,
& :hover:flip(> Button),
& :focus-in:flip(> Button) {
TextBox {
border-color: 0x4B23A0;
}
}
& :read-only:not(:flip(:has(>> ListItem))) {
TextBox {
horizontal-padding: 0;
border-color: transparent;
background-color: transparent;
}
}
}

or

& :pop-up,
& :flip(> Button):is(:hover, :focus-in) {
TextBox {
border-color: 0x4B23A0;
}
}</pre>

== EditableTableView styling ==

<pre> auto style = StyleSheet();
auto body_selector = Any() > is_a<TableBody>();
auto item_selector = body_selector > Row() > is_a<TableItem>();
style.get(item_selector > Any() >
(ReadOnly() && !(+Any() << is_a<ListItem>()) && !Prompt())).
set(horizontal_padding(scale_width(8)));
style.get(item_selector > Any() > ReadOnly() >
(is_a<TextBox>() && !(+Any() << is_a<ListItem>()) && !Prompt())).
set(horizontal_padding(scale_width(8)));
style.get((item_selector > !ReadOnly()) << Current()).
set(border_color(QColor(Qt::transparent)));
style.get(body_selector > Row() > Current()).
set(BackgroundColor(Qt::transparent));
style.get(body_selector > Row() > HoverItem()).
set(border_color(QColor(0xA0A0A0)));
style.get(body_selector > (Row() && Hover())).
set(BackgroundColor(0xF2F2FF));
style.get(item_selector > DeleteButton()).
set(Visibility(Visibility::INVISIBLE));
style.get(item_selector > DeleteButton() > is_a<Box>()).
set(BackgroundColor(QColor(Qt::transparent))).
set(horizontal_padding(scale_width(2))).
set(vertical_padding(scale_height(2)));
style.get(item_selector > DeleteButton() > is_a<Icon>()).
set(BackgroundColor(QColor(Qt::transparent)));
style.get(body_selector > (CurrentRow() || (Row() && Hover())) >
is_a<TableItem>() > DeleteButton()).
set(Visibility(Visibility::VISIBLE));
style.get((body_selector > (CurrentRow() || (Row() && Hover()))) >
DeleteButton() > is_a<Icon>()).
set(Fill(QColor(0x535353)));
style.get(body_selector > (Row() && Hover()) > DeleteButton() >
(is_a<Icon>() && Hover())).
set(BackgroundColor(QColor(0xDFDFEB))).
set(Fill(QColor(0xB71C1C)));
style.get(body_selector > CurrentRow() > DeleteButton() >
(is_a<Icon>() && Hover())).
set(BackgroundColor(QColor(0xD0CEEB))).
set(Fill(QColor(0xB71C1C)));
style.get((item_selector > EmptyCell()) << (HoverItem() || Current())).
set(border_color(QColor(Qt::transparent)));
style.get(body_selector > CurrentRow()).
set(BackgroundColor(QColor(0xE2E0FF)));
style.get(body_selector > CurrentColumn()).
set(BackgroundColor(Qt::transparent));

</pre>

<pre>EditableTableView {
TableBody {
TableBody::row {
TableItem {
* {
:not(:flip(:has(>> ListItem))) {
:read-only:not(KeyInputBox::prompt) {
horizontal-padding: 8px;
}
}
:read-only:not(:flip(:has(>> ListItem))) {
TextBox:not(KeyInputBox::prompt) {
horizontal-padding: 8px;
}
}
}
}
& :current:has(> :not(:read-only)) {
border-color: transparent;
}
& :current {
background-color: transparent;
}
& :hover-item {
border-color: 0xA0A0A0;
}
::delete-button {
visibility: invisible;
Box {
background-color: transparent;
horizontal-padding: 2px;
vertical-padding: 2px;
}
Icon {
background-color: transparent;
}
}
& :has(> ::empty-cell) {
& :hover-item,
& :current {
border-color: transparent;
}
}
}
& :hover {
background-color: 0xF2F2FF;
TableItem::delete-button {
visibility: visible;
Icon {
fill: 0x535353;
& :hover {
background-color: 0xDFDFEB;
fill: 0xB71C1C;
}
}
}
}
& :current-row {
background-color: 0xE2E0FF;
TableItem::delete-button {
visibility: visible;
Icon {
fill: 0x535353;
& :hover {
background-color: 0xDFDFEB;
fill: 0xB71C1C;
}
}
}
}
& :current-column {
backgournd-color: transparent;
}
}
}</pre>

Layout

2024-03-19T16:19:12Z

Jon: Created page with "<code>layout.xd</code> defines the visual composition for a component and its child elements. It’s required whenever a new element arrangement is needed. <code>layout.xd</co..."

<code>layout.xd</code> defines the visual composition for a component and its child elements. It’s required whenever a new element arrangement is needed. <code>layout.xd</code> is not necessary when it inherits its layout from another component and does not modify that layout. For example, <code>Label</code> is a customized <code>TextBox</code> that makes no changes to the layout, so <code>layout.xd</code> is not needed.

This document is the go-to for widths, heights, and positions; it takes precedence in the event of conflicts with <code>preview.xd</code> or <code>components.xd</code>. However, dynamic adjustments tied to user input can override it, as specified in <code>user_flow.drawio</code>.

While <code>components.xd</code> outlines the parts of a component, <code>layout.xd</code> is about fitting these parts together. <code>layout.xd</code> answers the question: “What goes where?” It should include the following details:
* '''Position:''' Specifying where child components are positioned relative to each other.
* '''Size Policy:''' Define the size or proportions of child components and how they change with resizing.
* '''Spacing:''' Detailing the spacing or gaps between child components.
* '''Layer Hierarchy:''' How the elements of a child component are visually stacked.

== Getting Started ==

<code>layout.xd</code> comes after <code>preview.xd</code>, <code>model.txt</code>, and <code>components.xd</code>. It is generally advised to ensure <code>components.xd</code> is finalized first, as the names defined there carry over to <code>layout.xd</code>.

<code>layout.xd</code> communicates spatial relations (position and size policy) through a primarily visual language. Each element is portrayed as a rectangle, with constraints along each edge indicated by edge color. When first learning the system, start by reviewing the [https://drive.spiretrading.com/f/91480 layout reference document].

Before starting <code>layout.xd</code>, the visual design for all scenarios should already be worked out, with the key ones ideally captured in <code>preview.xd</code>. Use <code>layout.xd</code> to formalize the layout.

Sketch the component’s layout and that of each child at the preferred size. Maintain simplicity by restricting layouts to a single depth level; nesting layouts within layouts isn’t a convention in the visual layout language. If a child’s layout is specified elsewhere and remains unchanged, omit it. When included, consider it an ''override'': the specified layout takes precedence over the existing one within the component instance.

=== Example: Slider ===

[[File:Slider_preview.png | 720px | Preview of a slider showing horizontal and vertical orientations and use cases in a Color Picker.]]

From the preview, we can see that <code>Slider</code> has a different layout depending on its orientation. Based on the examples, it appears that the thumb and the track are customizable.

<pre>Styles:
orientation: The orientation of the slider.
HORIZONTAL - The thumb can be dragged horizontally.
VERTICAL - The thumb can be dragged vertically.

Data:
current: The current value represented by the slider. Cannot be null.
Defaults to halfway between min and max.
min: The minimum value that current is allowed to be. Default 0.
max: The maximum value that current is allowed to be. Default 100.
step: The granularity that current must adhere to. Default 0.
default_increment: The amount of change in current when the user increments or
decrements the slider.
shift_increment: The amount of change in current when the user increments or
decrements the slider while holding the shift key.
track: The component representing the track of the slider.
thumb: The component representing the thumb of the slider.
...</pre>
The model for <code>Slider</code> shows a style <code>orientation</code> (<code>HORIZONTAL</code> | <code>VERTICAL</code>) corresponding to the preview. There are also two slots <code>track</code> and <code>thumb</code>, indicating that these are customizable.

[[File:Slider_components.png | 720px | Definition cards for children of Slider.]]

In <code>components.xd</code>, child names and styles are defined.

[[File:Slider_Layouts.png | 720px | Layout for Slider.]]

By contrast with <code>components.xd</code>, in <code>layout.xd</code> the bottommost (outermost) element receives the title of the component itself. This is necessary to clarify how the component’s children are arranged within it and to provide its size constraints. In the above, <code>Slider</code> is a <code>Box</code> that contains <code>track</code> on layer 0 and <code>thumb</code> on layer 1.

'''Note''': The <code>Box</code> did not appear in <code>components.xd</code> as no customization is done to it, but it is required in <code>layout.xd</code> to define <code>Slider</code>. The use of <code>Box</code> means that components using <code>Slider</code> can customize it with <code>Box</code>-specific styling such as <code>border</code>, <code>padding</code>, and <code>background_color</code>.

Separate layers in <code>Box.body</code> allow for overlap between <code>thumb</code> and <code>track</code>. Similarly, two layers are used in the layout of <code>Track.body</code> for <code>Rail</code> and <code>Fill</code>. To avoid overriding <code>Track</code>’s layout, <code>Track.body</code> is laid out instead. Generally, when a component has slots, composition is done by laying out the slots without altering the overall layout.

The width of <code>Fill</code> is determined by an expression, creating a ''binding'' that updates with model property changes.

<code>Thumb</code> is laid out directly using absolute <code>FIXED</code> size. Here, an ''anonymous'' element is used to specify the size without overriding the layout.

To understand <code>layout.xd</code>, one must be familiar with Spire’s visual layout language.

== Visual Layout Language ==

Within <code>layout.xd</code>, each element has a specific color and an identifier, rather than appearing as they do in <code>preview.xd</code>. These colors convey size constraints.

=== Elements ===

Layouts are composed of ''elements'', representing components like <code>Box</code> or <code>Button</code>, spacers for visual separation, or containers strictly for layout. Elements are generally depicted as rectangles, with center-aligned identifiers like <code><ElementName></code>. The appearance of the identifier doesn’t align with text orientation within the element. An element without an identifier is ''anonymous''. Each element can be thought of as having <code>top</code>, <code>bottom</code>, <code>left</code>, and <code>right</code> for its position and <code>width</code> and <code>height</code> for its size.

[[File:Element Basics.png | 720px | An element drawn as a box with its identifier and the properties top, right, bottom, left, width, and height labelled.]]

=== Size Constraints ===

Elements are sized through either fixed dimensions, expressed in pixels, or by occupying all available container space. An element’s size may also come from its contents, but ultimately any contents are either <code>FIXED</code> or <code>FILL</code>.

{| class="wikitable"
|-
! Constraint
! Meaning
|-
| <code>FIXED</code>
| The size of the component is a literal value that comes directly from the visual. An element drawn 12px wide is rendered 12px wide. As the size of the layout changes, the element size is unchanged.
|-
| <code>FILL</code>
| The size of the component fills the available space. The literal size of the depicted element represents the ''preferred'' size if no preferred size can be determined from the layout bottom-up. As the size of the layout changes, the element shrinks or grows to fill all available space. When multiple components in a layout have this constraint, the available space is distributed equally among them.
|-
| <code>FIT</code>
| The size of the component is determined by its contents. The literal size of the depicted element represents the ''preferred'' size if no preferred size can be determined from the layout bottom-up. This is often used for text which takes on a fixed value at any time, but changes dynamically or for windows that can be resized by the user and simultaneously restricted by their contents.
|}

Uniform constraints (same in both axes) encode edges and background color with the appropriate constraint color. For non-uniform constraints, edges are color-encoded, and the background remains neutral. Optionally, a neutral background helps distinguish adjacent components with identical constraints.

[[File:LayoutSpecificity.png | 720px | Three rectangles showing different constraints. (1) Non-uniform constraints: neutral background and different colors for horizontal and vertical borders. (2) Uniform constraints: colored background and same color borders. (3) Uniform constraints (alternate): neutral background and same color borders.]]

Color-encoding for borders and backgrounds is as follows:

[[File:LayoutColorSemantics.png | 720px | Five rectangles showing meaning of constraint colors. (1) Fixed Size: yellow. (2) Fill Available Space: blue. (3) Fit to Content: green. (4) Repeat: light purple. (5) Repeat Direction: dark purple.]]

A <code>Repeat</code> element can be used to describe repetitive layouts. <code>Repeat</code> duplicates adjacent layouts, following the color-encoded <code>Repeat Direction</code>. It is useful for dynamic lists where the content dictates the number of items.

[[File:LayoutExamples.png | 720px | Three collections of rectangles demonstrating different combinations of constraints. (1) Non-Uniform Constraints: rectangles with a neutral background color and differently colored vertical and horizontal borders (combinations of yellow, blue, and green). (2) Size Limit Examples: a neutral background rectangle with blue horizontal borders and yellow vertical borders. A note next to it says "width: min(100%, 500px)". (3) Repeater Constraint Examples: rectangles with a light purple background and a single dark purple border on the top, left, bottom or right indicating repeat from top to bottom, repeat from right to left, repeat from bottom to top, and repeat from left to right respectively.]]

==== Example: Box ====

[[File:Box_preview.png | 720px | Preview showing an empty Box, a TextBox, a LabelButton and other use cases.]]

<code>Box</code> establishes the basic style properties. The relevant properties are detailed in <code>model.txt</code>:

<pre>Styles:
border_top_size: The height of the top border.
border_right_size: The width of the right border.
border_bottom_size: The height of the bottom border.
border_left_size: The width of the left border.
...
padding_top: The amount of padding on the top of the box.
padding_right: The amount of padding to the right of the box.
padding_bottom: The amount of padding on the bottom of top of the box.
padding_left: The amount of padding to the left of the box.
...

Data:
body: The component displayed in the box.
</pre>
<code>Box</code> has a <code>border</code>, <code>padding</code>, and a <code>body</code>. <code>border</code> and <code>padding</code> are specified as fixed sizes for each edge, while <code>body</code> can be any component. <code>layout.xd</code> for <code>Box</code> shows how these elements are arranged:

[[File:Box_layout.png | 720px | A rectangle labeled body enclosed by trapezoids labeled padding_left, padding_top, padding_right, padding_bottom, enclosed by trapezoids labeled border_left, border_top, border_right, border_bottom.]]

In the layout, <code>body</code> adopts <code>FIT</code> constraints on all sides. By default, the size of the <code>Box</code> adapts to its content. <code>padding</code> is specified with separate components for each edge using <code>FIXED</code> constraints. <code>border</code>, akin to <code>padding</code>, uses the same specifications but lies outside it. The layout makes clear that <code>border</code> extends beyond <code>padding</code>, and both consume space that <code>body</code> cannot occupy.

'''Note:''' <code>Box</code> introduces a unique scenario as both <code>border</code> and <code>padding</code> elements converge at angles, presenting trapezoids instead of rectangles.

=== Position Constraints ===

The positioning of an element is considered relative to its container.

[[File:Positioning 1.png | 720px | A rectangle labeled Item inside a larger rectangle with markers between the left, top, right, and bottom edges of the two rectangles.]]

In the above diagram, the element <code>Item</code> is placed inside a container at some distances to its edges. Within the visual layout language, the layout must be drawn so that all of the space is taken up by elements, as shown below:

[[File:Positioning 2.png | 720px | A rectangle labeled Item inside a larger rectangle with rectangles labeled A, B, C, and D occupying the space between the edges of the outer rectangle and Item.]]

Above, the position of <code>Item</code> is defined by the surrounding elements <code>A</code>, <code>B</code>, <code>C</code>, and <code>D</code>. These elements can be other components or ''anonymous'' and they each have their own size constraints. How <code>Item</code> is positioned will depend on the ''size'' of the adjacent elements. The layout ensures no underflow, meaning no unoccupied space between components (the gaps shown in the diagram are for illustration only).

Edges of elements that touch are bound together. Where the right edge of <code>A</code> is adjacent to the left edge of <code>B</code>, it signifies <code>A.right = B.left</code>. Likewise, where the bottom edge of <code>B</code> aligns with the top edge of <code>Item</code>, it signifies <code>B.bottom = Item.top</code>.

==== Example: A Fixed and B Fill ====

[[File:Example1_1.png | 720px | Two rectangles labeled A and B side-by-side with the same height and an overall width of 320 pixels.]]

In this scenario, <code>A</code> is <code>FIXED</code>, signifying a literal size, while <code>B</code> has <code>FILL</code> constraints so that it occupies the available space.

When the width is reduced, <code>B</code> goes to zero width:

[[File:Example1_2.png | 720px | One rectangle labeled A with a width of 128 pixels.]]

When the width is increased, <code>B</code> stretches to fill the available space:

[[File:Example1_3.png | 720px | Two rectangles labeled A and B side-by-side with the same height and an overall width of 640 pixels.]]

For the horizontal direction, the constraints are:

<pre>A.left = left
A.right = left + 128px
B.left = A.right
B.right = right</pre>
And in the vertical direction:

<pre>A.top = top
A.bottom = top + 128px
B.top = top
B.bottom = bottom</pre>
Since underflow is forbidden, the layout cannot exceed the height of <code>A</code>: there’s nothing to occupy the additional space.

=== Spacers ===

Negative space is specified with spacers — elements absent from <code>components.xd</code> and devoid of interactive and styling attributes. Spacers, often ''anonymous'', serve the sole purpose of defining space between components.

'''Note:''' Negative space can also be introduced by using internal padding on adjacent components. Doing so is often preferred for <code>FIXED</code> spacing.

==== Example: A Fixed and B Fixed ====

[[File:Example2_1.png | 720px | Three rectangles side-by-side, all the same height and with an overall width of 320 pixels. The rectangles on each end are labeled A and B, and the rectangle in the middle is unlabeled.]]

In this scenario, both <code>A</code> and <code>B</code> are <code>FIXED</code>, with literal sizes of 128px in <code>width</code> and <code>height</code>. They are positioned on opposite ends of the layout through the use of a spacer that is constrained to <code>FILL</code> the available space. The spacer lacks an identifier: it is ''anonymous''.

When the width of the layout is reduced, the spacer collapses and <code>A</code> and <code>B</code> touch:

[[File:Example2_2.png | 720px | Two rectangles side-by-side, labeled A and B, with the same height and an overall width of 256 pixels.]]

When the width of the layout is increased, the spacer expands to fill the available space:

[[File:Example2_3.png | 720px | Three rectangles side-by-side, all the same height and with an overall width of 640 pixels. The rectangles on each end are labeled A and B, and the rectangle in the middle is unlabeled.]]

For the horizontal constraints:

<pre>A.left = left
A.right = left + 128px
spacer.left = A.right
spacer.right = B.left
B.left = right - 128px
B.right = right</pre>
For the vertical constraints:

<pre>A.top = top
A.bottom = top + 128px
spacer.top = top
spacer.bottom = bottom
B.top = top
B.bottom = top + 128px</pre>

=== Containers ===

Layouts can be subdivided at the designer’s choosing using containers. They are used to encapsulate the arrangement of elements. Unlike spacers, containers cannot be anonymous; they require identification for referencing.

==== Example: ListView ====

When <code>direction = VERTICAL and overflow = WRAP</code> , the layout is divided into containers named <code>Column</code>. <code>Column</code> is purely a layout element, without any representation in <code>components.xd</code>

[[File:ListView_layout.png | 720px | Two elements labeled Column arranged left-to-right with a Repeat-Left-to-Right element between them.]]

The layout for <code>Column</code> is shown the same as for any other component.

[[File:ListView_layout-2.png | 720px | Two elements labeled Item arranged top-to-bottom with a Repeat-Top-to-Bottom element between them.]]

=== Example: TitleBar ===

[[File:TitleBar_preview-2.png | 720px | A window titlebar.]]

From <code>preview.xd</code>, we can see that <code>TitleBar</code> consists of a few elements:
* Icon
* Title
* Window controls
* Container

The height of <code>TitleBar</code> is constant, while its width can vary.

[[File:TitleBar_components.png | 720px | Definition cards for TitleBar's children.]]

<code>components.xd</code> introduces aliases:
* WindowIcon
* WindowName
* Minimize, Maximize, and Close
* Box

Appearance tweaks—background colors, icons, and title text—are handled in the property declarations.

[[File:TitleBar_layout.png | 720px | Layout for TitleBar.]]

<code>WindowIcon</code> is an <code>Icon</code> with <code>FIXED</code> size of 10px that is vertically centered. Top and bottom spacers with <code>FILL</code> size ensure center alignment.

'''Note:''' Centering is indicated because the two elements are equally sized. Any positional bias could be provided by adjusting the relative sizes of the spacers.

The contents of <code>TitleBar</code> are arranged in <code>Box.body</code>:
* <code>WindowIcon</code> is given a vertical constraint of <code>FILL</code> and a horizontal constraint of <code>FIT</code>. It will be as tall as allowed by <code>Box</code> and only as wide as required by its content.
* <code>WindowName</code> is constrained vertically as <code>FILL</code> and horizontally as <code>FILL</code>, adapting to available space.
* <code>Minimize</code>, <code>Maximize</code>, and <code>Close</code> are all given constraints of <code>FIXED</code> in height and width (22px x 26px). Their literal size is defined by the visual.

<code>Box</code> is the container with a vertical constraint of <code>FIT</code> and a horizontal constraint of <code>FILL</code>. An expression for width restricts its minimum size.

<syntaxhighlight lang="css">width: max(FIT_CONTENT, 100%)</syntaxhighlight>
This takes precedence over the sketch.

The layout ensures that <code>TitleBar</code> matches the width of its parent window without getting so narrow that the user is unable to interact with the controls.

== Anatomy ==

The structure of <code>layout.xd</code> is a vertical list of sections, each dedicated to the layout of a single element. Each section is divided into a grid with columns for scenarios and rows for layers and property declarations.

==== Example: SplitView ====

[[File:SplitView_layout_anatomy.png | 720px | Layout section for SplitView with the various parts highlighted and labeled. Identified parts are: Section, Heading, Scenarios, Scenario Condition, Layers, Layer Name, Scenario Layout, Identifier, and Scenario Property Declarations.]]

The heading is the name of the element being laid out.

Layers are stacked vertically in the column for a scenario. If only one layer is needed, the layer name is omitted.

When the scenario shown is the default condition, the scenario condition heading is omitted.

Each scenario and layer has a layout. Layouts are sketched at 1:1 scale.

At the bottom of each column are property declarations. These declarations supersede visual layout statements. They are useful for specifying sizes that are impractical to depict visually and for incorporating expressions.

== Heading ==

The heading identifies the element that is being laid out. If an alias is assigned in <code>components.xd</code>, the alias is used.

== Scenarios ==

Scenarios are used to create conditional layouts. While the presence or absence of components can be handled in <code>components.xd</code> using the <code>visibility</code> property, specific positioning of children must be specified in <code>layout.xd</code>

==== Example: OverlayPanel ====

<pre>Data:
parent: The component that showed the OverlayPanel.
...
positioning: Specifies the positioning of the panel relative to the parent:
NONE: The panel is not positioned relative to any other component.
PARENT: The panel is positioned relative to the parent. Default.

State:
vertical_orientation: Whether the OverlayPanel is placed above or below the
its parent, this is determined based on the position
of the parent and the size of the body. If the body
can fit entirely below the parent then the orientation
will be BELOW, otherwise it will be ABOVE.
BELOW: The OverlayPanel is below the parent.
ABOVE: The OverlayPanel is above the parent.

...</pre>

[[File:OverlayPanel_layout.png | 720px | Layout for OverlayPanel.]]

<code>OverlayPanel</code> has a conditional layout based on whether the panel is: - <code>default</code> - <code>positioning = PARENT and vertical_orientation = BELOW</code> - <code>positioning = PARENT and vertical_orientation = ABOVE</code>

These are the scenario conditions.

Scenario evaluation follows a right-to-left (and bottom-to-top if applicable) sequence: the first matching scenario takes effect. In the <code>OverlayPanel</code> example, the match depends on <code>parent</code>’s location relative to the screen and the size of <code>Box</code>.

Scenario conditions are written using selectors. Refer to the [https://wiki.spiretrading.com/index.php/Components#Selectors documentation for selectors on components] for details on using selectors to specify a condition.

== Layers ==

Layouts can be separated into layers. This is done by prepending <code>layer n:</code> before the layout, where <code>n</code> is the layer number. Layers are zero-indexed and arranged vertically from bottom to top. Lower layers have ''z-priority''.

Layers are useful for specifying where components need to overlap.

=== Example: DecimalBox ===

[[File:DecimalBox_layout.png | 720px | Layout for DecimalBox.]]

A <code>TextBox</code> is placed on layer 0 while the step buttons <code>Increment</code> and <code>Decrement</code> are placed on layer 1. This allows the step buttons to be visually nested in the <code>TextBox</code> without modifying the <code>TextBox</code> layout.

[[File:DecimalBox_preview.png | 720px | Preview for DecimalBox.]]

== Layout ==

The layout is a 1:1 scale sketch of the scenario using the visual layout language. The size used to represent a layout is the ''preferred size''.

Through the use of the visual layout language and property declarations, the layout fully specifies the positions and sizes of an element’s children for all possible sizes of the element.

== Identifier ==

Each element is labeled with an identifier. The identifier is shown in angle brackets as <code><ElementName></code>. Naming follows the '''PascalCase''' convention from <code>components.xd</code>.

When an identifier matches the name of an existing component, the layout is for an ''instance'' of that component.

''Slots'', components specified in <code>model.txt</code> under Data, earmark children open to substitution with different components. When identifying slots, the '''snake_case''' convention from <code>model.txt</code> is used.

When an identifier does not match a component name or a slot, the layout is for a spacer or a container used for organizational purposes within the document.

=== Example: SplitView ===

The model for <code>SplitView</code> shows two slots: <code>primary</code> and <code>secondary</code>.

<pre>...
Data:
primary: The primary pane.
secondary: The secondary pane.
...</pre>

In <code>layout.xd</code>, these are represented as <code><primary></code> and <code><secondary></code>.

[[File:SplitView_layout.png | 720px | Layout for SplitView for HORIZONTAL orientation.]]

Additionally, three named elements are depicted—<code>Padding</code>, <code>Offset</code>, and <code>Sash</code>. These lack correspondence to any components or slots and serve as reference points for property declarations.

While <code>Padding</code> is intended to be 2px wide, it’s shown at an enlarged size for readability. The declaration is used to provide the true size. A similar approach applies to <code>Sash</code>.

== Multiples ==

In a component, you might have several instances of the same type, and their layouts could be identical. In such cases, the element identifiers in <code>layout.xd</code> drop the index found in <code>components.xd</code>.

=== Example: ListView ===

[[File:ListView_components.png | 720px | Definition card for Item within ListView.]]

In <code>components.xd</code> there is a child <code>Item[i]</code>, as there are multiple <code>Item</code> children depending on the data given to <code>ListView</code>.

[[File:ListView_layout-2.png | 720px | Layout of Column element in ListView showing two elements labeled Item arranged top-to-bottom with a Repeat-Top-to-Bottom element between them.]]

However, in <code>layout.xd</code>, we simply use <code>Item</code> without an index in the identifier. Because the layout is positioning the items, specific index values would not accurately convey our intent. Instead, the <code>Repeat</code> element is used to signify repetition and dictate the direction.

== Property Declaration ==

Property declarations take precedence over the visual layout. Properties come from the child being defined. To understand what’s available, consult its <code>model.txt</code>. Generally, only size and position properties, such as <code>width</code>, <code>height</code>, and <code>position</code> should be declared in <code>layout.xd</code>.

The key properties are as follows:

{| class="wikitable"
|-
! Property
! Definition
|-
| <code>width</code>
| The width of the component in pixels.
|-
| <code>height</code>
| The height of the component in pixels.
|-
| <code>position</code>
| The position of the component relative to its parent, if the component has no parent, then the position is equal to <code>screen_position</code>.
|-
|
| <code>x</code> The x-coordinate in pixels.
|-
|
| <code>y</code> The y-coordinate in pixels.
|}

Property declarations are made using expressions which support basic mathematical operators (<code>+</code>, <code>×</code>, <code>/</code>, <code>-</code>) and various functions. These are used for more complex constraints that are not easily visually represented.

A fluid layout with a minimum width of 20px and a maximum width of 100px can be specified as:

<syntaxhighlight lang="css">width: clamp(20px, FILL_AVAILABLE, 100px)</syntaxhighlight>
The preferred size is the middle value (<code>FILL_AVAILABLE</code>), but it is bounded by 20px and 100px on either side.

Expressions containing dependencies establish a binding.

<syntaxhighlight lang="css">Offset.width: primary.width - (Sash.width - Divider.width) / 2</syntaxhighlight>
Whenever <code>primary.width</code> changes, <code>Offset.width</code> will also change.

=== Expression Values and Units ===

Expressions use a fixed set of units and preset values.

{| class="wikitable"
|-
! Unit / Value
! Description
|-
| <code>n</code> px
| A literal amount in pixels
|-
| <code>n</code> ch
| The width of the “0” character for the element font. A width value of <code>6ch</code> is approximately 6 characters wide in the specified font.
|-
| <code>n</code> em
| Represents the calculated font size of the element.
|-
| <code>n</code> %
| A percentage amount relative to the immediate parent layout
|-
| <code>FILL_AVAILABLE</code>
| Fills its parent
|-
| <code>FIT_CONTENT</code>
| Fits its contents
|}

Additional units may be used provided they have compelling use cases and are documented. The above units come from [https://developer.mozilla.org/en-US/docs/Web/CSS/length CSS]

=== Expression Functions ===

Any function can be used in an expression provided its definition is provided or it is sufficiently self-explanatory. In practice, it is best to stick to a limited set of functions. The following have been used in layout specifications:

{| class="wikitable"
|-
! Function
! Description
|-
| <code>min(a, b)</code>
| The minimum of <code>a</code> and <code>b</code>
|-
| <code>max(a, b)</code>
| The maximum of <code>a</code> and <code>b</code>
|-
| <code>clamp(lower, value, upper)</code>
| <code>value</code>, clamped to between <code>lower</code> and <code>upper</code> (inclusive)
|}

These have CSS equivalents:
* [https://developer.mozilla.org/en-US/docs/Web/CSS/min min()]
* [https://developer.mozilla.org/en-US/docs/Web/CSS/max max()]
* [https://developer.mozilla.org/en-US/docs/Web/CSS/clamp clamp()]

Expressions can also be set to animation values as outlined in the documentation on [https://wiki.spiretrading.com/index.php/Animations Animations].

==== Example: DropDownList ====

[[File:DropDownList_layout.png | 720px | Layout for DropDownList.]]

<code>DropDownList</code> sets the <code>width</code> to the greater of its parent’s width or the content width of the <code>ScrollableListBox</code>. The <code>height</code> is set dynamically to display either ten items or all available items, whichever is less.

== Ordering ==

When structuring <code>layout.xd</code>, maintain an order mirroring <code>components.xd</code>—from innermost to outermost. This ensures clarity and consistency.

=== Example: TabView ===

<code>components.xd</code> lists a <code>Box</code>, a <code>ScrollableListBox</code>, and a custom <code>ListView</code> that uses a <code>Tab</code> component for each <code>ListItem</code>.

[[File:TabView_components.png | 720px | Definition cards for the children of TabView.]]

From top to bottom, the order is:
* Tab[i]
* ListItem[i]
* ListView:TabList
* ScrollableListBox
* Box:TabBar

<code>layout.xd</code> lays out <code>TabView</code> as <code>TabBar</code> and <code>body</code>, along with two spacing elements. <code>TabBar</code> is laid out as <code>ScrollableListBox</code> and a spacer, and <code>ScrollableListBox</code> is laid out as <code>TabList</code>.

[[File:TabView_layout.png | 720px | Layout for TabView.]]

From top to bottom, the order is:
* ScrollableListBox
* TabBar
* TabView

Unlike <code>components.xd</code>, <code>TabView</code> itself is included in <code>layout.xd</code>. As in <code>components.xd</code>, <code>ScrollableListBox</code> comes before <code>TabBar</code> as the order moves from innermost to outermost. While <code>components.xd</code> lists <code>TabList</code>, <code>ListItem[i]</code> and <code>Tab[i]</code>, they are absent from <code>layout.xd</code>. As these components all specify their layouts and <code>TabView</code> does not override any of these layouts, they are omitted.

== Referencing ==

In property declarations, only elements positioned higher in the document can be referenced.

=== Example: HighlightPicker ===

[[File:HighlightPicker_layout.png | Layout for HighlightPicker.]]

The property declaration in <code>OverlayPanel.body</code> references the width of <code>ListItem</code>:

<syntaxhighlight lang="css">HighlightPalette.width: 8 * ListItem.width</syntaxhighlight>
This is a valid reference, as <code>ListItem</code> is a child of <code>OverlayPanel.body</code> so the layout for <code>ListItem.body</code> comes above that for <code>OverlayPanel.body</code>.

== Adaptive Layouts ==

Sometimes it is necessary to specify a different layout according to the available space. Instead of a gradual transition of elements, a step-change may be appropriate such as switching between an even grid and a linear arrangement, or switching labels between a long-form and a short-hand. Consider the <code>TechnicalsPanel</code> from <code>BookView</code>:

[[File:TechnicalsPanel_preview.png | 720px | Preview for Technicals Panel showing Book View Window at different widths.]]

The six technical indicators <code>High</code>, <code>Low</code>, <code>Open</code>, <code>Close</code>, <code>Def</code>, and <code>Vol</code> are shown stacked in a 3x2 grid or linearly as a 6x1 row. They are also shown either as a full name (e.g. <code>High</code>) or an abbreviation (e.g. <code>H</code>). There should be a step-change between the 3x2 and 6x1 arrangements, as a partially filled second row makes for more difficult reading. There should also be a step-change between full labels and abbreviations, since if the labels are not coordinated it becomes visually confusing.

This behavior is not specified directly in the visual layout language. Instead, a purpose-built component <code>AdaptiveBox</code> is used.

To use <code>AdaptiveBox</code>, the designer specifies each layout within <code>components.xd</code>. It is convention to use size-based naming: <code>ExtraSmall</code>, <code>Small</code>, <code>Medium</code>, <code>Large</code>, but this can be adjusted to suit the specific use-case. <code>AdaptiveBox</code> is placed in <code>components.xd</code> and its <code>components</code> property is set to a list containing the named layouts.

[[File:TechnicalsPanel_components.png | 720px | Definition cards for children of TechnicalsPanel.]]

The <code>components</code> are listed in order of largest size to smallest size when passed to <code>AdaptiveBox</code>. Within <code>layout.xd</code>, the layout for <code>AdaptiveBox</code> and each layout in <code>layouts</code> is specified.

[[File:TechnicalsPanel_layout.png | 720px | Layout for TechnicalsPanel.]]

<code>AdaptiveBox</code> then manages which layout is displayed based on the available space. There is no specifying of fixed-pixel ''breakpoints''.

== Usage ==

When laying out children from <code>components.xd</code> that have been assigned an alias, use the alias to title the layout. When laying out a component slot, use dot notation to title the slot (e.g. <code>Box.body</code>) and avoid repeating the layout for the component itself.

<code>layout.xd</code> is used to bring a component together, formalizing the position and size relations of it and its children. Approach <code>layout.xd</code> after fully utilizing <code>components.xd</code> to enumerate the component’s children and with a firm understanding of how the component will adjust at different sizes.

== References ==

* [https://drive.spiretrading.com/f/91480 Layout Reference Document]
* [https://wiki.spiretrading.com/index.php/Components#Selectors Selectors Documentation]
* [https://developer.mozilla.org/en-US/docs/Web/CSS/length CSS Length Units]
* [https://developer.mozilla.org/en-US/docs/Web/CSS/clamp Clamp Function]

File:TechnicalsPanel layout.png

2024-03-19T15:32:43Z

Jon: Layout for Technicals Panel component.

== Summary ==
Layout for Technicals Panel component.

File:TechnicalsPanel components.png

2024-03-19T15:32:15Z

Jon: Definition cards for the children of Technicals Panel in components.xd.

== Summary ==
Definition cards for the children of Technicals Panel in components.xd.

File:TechnicalsPanel preview.png

2024-03-19T15:31:35Z

Jon: Preview of the Technicals Panel component.

== Summary ==
Preview of the Technicals Panel component.

File:HighlightPicker layout.png

2024-03-19T15:31:01Z

Jon: Layout for HighlightPicker component.

== Summary ==
Layout for HighlightPicker component.

File:TabView layout.png

2024-03-19T15:30:33Z

Jon: Layout for TabView component.

== Summary ==
Layout for TabView component.

File:TabView components.png

2024-03-19T15:30:06Z

Jon: Definition cards for the children of TabView in components.xd.

== Summary ==
Definition cards for the children of TabView in components.xd.

File:DropDownList layout.png

2024-03-19T15:29:27Z

Jon: Layout for DropDownList component.

== Summary ==
Layout for DropDownList component.

File:ListView components.png

2024-03-19T15:28:53Z

Jon: Definition card for Item sub-component for ListView.

== Summary ==
Definition card for Item sub-component for ListView.

File:SplitView layout.png

2024-03-19T15:28:01Z

Jon: Layout for SplitView component when orientation is HORIZONTAL.

== Summary ==
Layout for SplitView component when orientation is HORIZONTAL.

File:DecimalBox preview.png

2024-03-19T15:26:12Z

Jon: Preview for the DecimalBox component.

== Summary ==
Preview for the DecimalBox component.

File:DecimalBox layout.png

2024-03-19T15:25:32Z

Jon: Layout for the DecimalBox component.

== Summary ==
Layout for the DecimalBox component.

File:OverlayPanel layout.png

2024-03-19T15:25:09Z

Jon: Layout for the OverlayPanel component.

== Summary ==
Layout for the OverlayPanel component.

File:SplitView layout anatomy.png

2024-03-19T15:24:24Z

Jon: Jon uploaded a new version of File:SplitView layout anatomy.png

== Summary ==
Breakdown of a layout section for the SplitView component.

File:SplitView layout anatomy.png

2024-03-19T15:21:24Z

Jon: Breakdown of a layout section for the SplitView component.

== Summary ==
Breakdown of a layout section for the SplitView component.

File:Slider Layouts.png

2024-03-19T15:01:36Z

Jon: Layout for the Slider component.

== Summary ==
Layout for the Slider component.

File:TitleBar layout.png

2024-03-19T14:58:04Z

Jon: Layout for the TitleBar component.

== Summary ==
Layout for the TitleBar component.

File:TitleBar preview-2.png

2024-03-19T14:57:05Z

Jon: Preview for the TitleBar component.

== Summary ==
Preview for the TitleBar component.

File:ListView layout-2.png

2024-03-19T14:56:04Z

Jon: Layout for the Column element within the ListView component.

== Summary ==
Layout for the Column element within the ListView component.

File:ListView layout.png

2024-03-19T14:55:20Z

Jon: Layout for the body of the Box sub-component of ListView when the direction is VERTICAL and the overflow is WRAP.

== Summary ==
Layout for the body of the Box sub-component of ListView when the direction is VERTICAL and the overflow is WRAP.

File:Example2 3.png

2024-03-19T14:54:00Z

Jon: Example layout of three elements: A, an anonymous spacer, and B, with an overall width of 640 pixels.

== Summary ==
Example layout of three elements: A, an anonymous spacer, and B, with an overall width of 640 pixels.

File:Example2 2.png

2024-03-19T14:53:19Z

Jon: Example layout of two elements A and B with an overall width of 256 pixels.

== Summary ==
Example layout of two elements A and B with an overall width of 256 pixels.

File:Example2 1.png

2024-03-19T14:52:44Z

Jon:

== Summary ==
Example layout of three elements: A, an anonymous spacer, and B, with an overall width of 320 pixels.

File:Example2 1.png

2024-03-19T14:52:23Z

Jon: Example layout of three elements: A, and anonymous spacer, and B, with an overall width of 320 pixels.

== Summary ==
Example layout of three elements: A, and anonymous spacer, and B, with an overall width of 320 pixels.

File:Example1 3.png

2024-03-19T14:51:42Z

Jon: Example layout of two elements A and B with an overall width of 640 pixels.

== Summary ==
Example layout of two elements A and B with an overall width of 640 pixels.

File:Example1 2.png

2024-03-19T14:51:00Z

Jon: Example layout showing a single element A with an overall width of 128 pixels.

== Summary ==
Example layout showing a single element A with an overall width of 128 pixels.

File:Example1 1.png

2024-03-19T14:50:21Z

Jon: Example layout for two elements A and B with an overall width of 320 pixels.

== Summary ==
Example layout for two elements A and B with an overall width of 320 pixels.

File:Positioning 2.png

2024-03-19T14:48:39Z

Jon: Diagram of an element named Item positioned within its parent container. Surrounding elements A, B, C, and D fill the space between Item and the edges of the container.

== Summary ==
Diagram of an element named Item positioned within its parent container. Surrounding elements A, B, C, and D fill the space between Item and the edges of the container.

File:Positioning 1.png

2024-03-19T14:47:12Z

Jon: Diagram of an element named Item arbitrarily positioned within its parent container.

== Summary ==
Diagram of an element named Item arbitrarily positioned within its parent container.

File:Box layout.png

2024-03-19T14:45:43Z

Jon: Layout for Box, detailing the arrangement of border, padding, and body elements.

== Summary ==
Layout for Box, detailing the arrangement of border, padding, and body elements.

File:Box preview.png

2024-03-19T14:44:38Z

Jon: Preview of Box component, showing its usage in various components including TextBox and LabelButton.

== Summary ==
Preview of Box component, showing its usage in various components including TextBox and LabelButton.

File:LayoutExamples.png

2024-03-19T14:43:23Z

Jon: Examples of layout elements with color-encoded constraints applied.

== Summary ==
Examples of layout elements with color-encoded constraints applied.

File:LayoutColorSemantics.png

2024-03-19T14:42:15Z

Jon: Overview of color encoding of elements and their semantics within a layout.

== Summary ==
Overview of color encoding of elements and their semantics within a layout.

File:LayoutSpecificity.png

2024-03-19T14:41:34Z

Jon: Overview of constraint specificity for elements within a layout.

== Summary ==
Overview of constraint specificity for elements within a layout.

File:Element Basics.png

2024-03-19T14:40:30Z

Jon: Diagram of basic element properties within a layout.

== Summary ==
Diagram of basic element properties within a layout.

File:Slider layout Slider.png

2024-03-19T14:39:44Z

Jon: Layout section for Slider.

== Summary ==
Layout section for Slider.

File:Slider layout Box.body.png

2024-03-19T14:38:04Z

Jon: Layout for the body of Box sub-component of Slider.

== Summary ==
Layout for the body of Box sub-component of Slider.

File:Slider layout Track.body.png

2024-03-19T14:37:34Z

Jon: Layout for the body of Track sub-component of Slider.

== Summary ==
Layout for the body of Track sub-component of Slider.

File:Slider layout Thumb.png

2024-03-19T14:36:46Z

Jon: Layout for Thumb sub-component of Slider.

== Summary ==
Layout for Thumb sub-component of Slider.

File:Slider components.png

2024-03-19T14:35:49Z

Jon: Definition cards for Slider's children from components.xd.

== Summary ==
Definition cards for Slider's children from components.xd.

File:Slider preview.png

2024-03-19T14:33:53Z

Jon: Preview for Slider component.

== Summary ==
Preview for Slider component.

Animations

2024-01-30T20:41:31Z

Jon: Created page with "Animations in Spire follow a philosophy of enhancing clarity and communication without embellishment or impedance to the user. In CSS there are transitions, in Spire an anima..."

Animations in Spire follow a philosophy of enhancing clarity and communication without embellishment or impedance to the user.

In CSS there are transitions, in Spire an animation is just a value. This means that a property value such as <code>background_color</code> or <code>border_color</code> can be directly set to an animation value to achieve a property value that changes over time.

== Example: Rejected Style for InputBox ==

[[File:TextBox_Rejected.gif|720px|Animation of TextBox Rejected style]]

When the InputBox is in the <code>rejected</code> state, an animation plays. The animation can be defined as follows:

<syntaxhighlight lang="css">background_color: chain(timeout(#FFF1F1, 250ms), linear(#FFF1F1, revert, 300ms))
border_color: chain(timeout(#B71C1C, 550ms), revert)</syntaxhighlight>
In this case the value says:

<blockquote>Chain together two styles, the first style is a value of <code>#FFF1F1</code> that times out after 250ms, the second value is a linear interpolation from <code>#FFF1F1</code> to whatever the style was before (that’s what <code>revert</code> does), over 300ms.
</blockquote>
Border color is styled as:

<blockquote>Chain two styles, the first is the color <code>#B71C1C</code> that expires after 550ms and then reverts to whatever it was previously.
</blockquote>
This is reflected in <code>components.xd</code> for InputBox.

[[File:InputBox_components.png|720px|Definition card for Box in InputBox]]

When the InputBox is <code>rejected</code>, property declarations are made for the <code>background_color</code> and <code>color</code> that are animation values. Whenever the InputBox is put into the <code>rejected</code> state, the animations will play.

Each property value is independent, and there is no necessary connection between the timing used for the animation values for each property.

== Example: Uptick/Downtick Style for DecimalBox ==

[[File:DecimalBox_Uptick_Downtick.gif|720px|Uptick and downtick animation style on DecimalBox]]

When the DecimalBox uses the uptick/downtick styling, its background color flashes when its value changes, reflecting whether the value increased or decreased.

When the value increases, it is uptick:

<syntaxhighlight lang="css">background_color: linear(#EBFFF0, revert, 550ms)</syntaxhighlight>
When the value decreases, it is downtick:

<syntaxhighlight lang="css">background_color: linear(#FFF1F1, revert, 550ms)</syntaxhighlight>

== Functions ==

Unlike static values, animation values use functions that allow them to change over time. The list of functions that have been used are as follows:

{| class="wikitable"
|-
! Function!! Decription
|-
| <code>chain(X, Y, *ARGS)</code> || An animation that applies <code>X</code> until <code>X</code> ends, then applies <code>Y</code> until <code>Y</code> ends, and so on for any additional arguments.
|-
| <code>timeout(X, Y)</code> || Applies <code>X</code> for a period of <code>Y</code>.
|-
| <code>linear(X, Y, Z)</code> || Linearly interpolates from <code>X</code> to <code>Y</code> over a period <code>Z</code>. <code>linear = cubic_bezier(0.0, 0.0, 1.0, 1.0)</code>.
|-
| <code>ease(X, Y, Z)</code> || Interpolates from <code>X</code> to <code>Y</code> over a period <code>Z</code> using the <code>ease</code> timing function. <code>ease = cubic_bezier(0.25, 0.1, 0.25, 1.0)</code>.
|}

Additional functions may be added provided they have a clear use case and are documented.

== Keywords ==

Values within functions may be literal values (e.g. a color value or a time in milliseconds), or they may be a keyword with a defined meaning.

{| class="wikitable"
|-
! Keyword!! Decription
|-
| <code>revert</code> || Applies whatever style would have otherwise been applied.
|}

== References ==

* [https://developer.mozilla.org/en-US/docs/Web/CSS/easing-function Easing Functions]
* [https://easings.net/ Easing Functions Cheat Sheet]

File:TextBox Rejected.gif

2024-01-30T20:40:32Z

Jon: Rejected animation style for TextBox.

== Summary ==
Rejected animation style for TextBox.

File:DecimalBox Uptick Downtick.gif

2024-01-30T20:40:02Z

Jon: Uptick and Downtick animation style for DecimalBox.

== Summary ==
Uptick and Downtick animation style for DecimalBox.

File:DecimalBox Uptick Downtick.webp

2024-01-30T19:32:32Z

Jon: Uptick and downtick animations for DecimalBox.

== Summary ==
Uptick and downtick animations for DecimalBox.

File:TextBox Rejected.webp

2024-01-30T19:07:27Z

Jon: Rejected animation for TextBox

== Summary ==
Rejected animation for TextBox

File:InputBox components.png

2024-01-30T18:55:05Z

Jon: Definition card for Box from components.xd for InputBox

== Summary ==
Definition card for Box from components.xd for InputBox