Skip to content

Commit

Permalink
Merge pull request #362 from gaphor/chore/css-doc-edits
Browse files Browse the repository at this point in the history 
Polish Style Sheet Documentation
  • Loading branch information
@amolenaar
amolenaar committed Jul 17, 2020
2 parents 8c84184 + 9266e60 commit 316ff8a
Showing 1 changed file with 76 additions and 64 deletions.
140 changes: 76 additions & 64 deletions docs/style_sheets.md
View file
Original file line number Diff line number Diff line change
@@ -1,19 +1,23 @@
# Style Sheets

Since Gaphor 2.0, Gaphor diagrams can have a different look by means of style sheets.
Style sheets use Cascading Style Sheets (CSS) syntax.
CSS is most known for it's application in web pages (HTML).
Since Gaphor 2.0, Gaphor diagrams can have a different look by means of style
sheets. Style sheets use the Cascading Style Sheets (CSS) syntax. CSS is used
to describe the presentation of a document written in a markup language, and is
most commonly used with HTML for web pages.

On the [W3C CSS home page](https://www.w3.org/Style/CSS/Overview.en.html), CSS is described as:
On the [W3C CSS home page](https://www.w3.org/Style/CSS/Overview.en.html), CSS
is described as:

> Cascading Style Sheets (CSS) is a simple mechanism for adding style (e.g., fonts, colors, spacing) to Web documents.
> Cascading Style Sheets (CSS) is a simple mechanism for adding style (e.g.,
fonts, colors, spacing) to Web documents.

It's application goes well beyond web documents, though.
Gaphor uses CSS to provide style elements to items in diagrams.
CSS allows us, users of Gaphor, to change the visual appearance of our diagrams.
Color and line styles can be changed to make it easier to read the diagrams.
Its application goes well beyond web documents, though. Gaphor uses CSS to
provide style elements to items in diagrams. CSS allows us, users of Gaphor, to
change the visual appearance of our diagrams. Color and line styles can be
changed to make it easier to read the diagrams.

Since we're dealing with a diagram, and not a HTML document, some CSS features have been left out.
Since we're dealing with a diagram, and not a HTML document, some CSS features
have been left out.

The style is part of the model, so everyone working on a model will have the
same style.
Expand All @@ -34,8 +38,8 @@ node component {
}
```

The diagram itself is also expressed as a CSS node.
It's pretty easy to define a "dark" style:
The diagram itself is also expressed as a CSS node. It's pretty easy to define
a "dark" style:

``` css
diagram {
Expand All @@ -48,15 +52,14 @@ diagram {
}
```

Here you already see the first custom attribute: `text-color`.
This property allows you to control the color of the text drawn in an item.
`color` is used for the lines (strokes) that make the layout of a diagram item.
Here you already see the first custom attribute: `text-color`. This property
allows you to control the color of the text drawn in an item. `color` is used
for the lines (strokes) that make the layout of a diagram item.

## Supported selectors

We're dealing with diagrams, models.
Therefore we do not need all features of CSS.
Below you'll find a summation of all CSS features supported by Gaphor.
Since we are dealing with diagrams and models, we do not need all the features
of CSS. Below you'll find a summary of all CSS features supported by Gaphor.

```eval_rst
============================= ============================
Expand All @@ -72,38 +75,39 @@ Below you'll find a summation of all CSS features supported by Gaphor.
``diagram[name|=draft]`` A diagram with a name is "draft" or starts with "draft-".
``\*:focus`` The focused item. Other pseudo classes are:
- ``:active`` selected items;
- ``:hover`` for the item under the mouse;
- ``:drop`` if an item is draggen and can be dropped on this item.
- ``:active`` selected items
- ``:hover`` for the item under the mouse
- ``:drop`` if an item is dragged and can be dropped on this item
``node:empty`` A node containing no child nodes in the diagram.
``:root`` An item is at the top level of the diagram.
This is only applicable for the diagram
``:has()`` The item has contains any of the provided selectors.
``:has()`` The item contains any of the provided selectors.
E.g. ``node:has(component)``: a node containing a component item.
``:is()`` Match any of the provided selectors.
E.g. ``:is(node, subsystem) > component``: a node or synsystem.
E.g. ``:is(node, subsystem) > component``: a node or subsystem.
``:not()`` Negate the selector.
E.g. ``:not([subject])``: Any item that has no "subject".
============================= ============================
```

* The official specification of [CSS3 attribute selectors](https://www.w3.org/TR/2018/REC-selectors-3-20181106/#attribute-selectors).
* The `|=` attribute selector is provided for the sake of completeness. It's probably not very useful in a Gaphor context.
* Please note that Gaphor CSS does not support ID's for diagram items,
so the CSS syntax for id's (`#some-id`) is not used.
Also class syntax (`.some-class`) is not supported.
* We provide the `|=` attribute selector for the sake of completeness. It's
probably not very useful in a Gaphor context.
* Please note that Gaphor CSS does not support IDs for diagram items, so the
CSS syntax for IDs (`#some-id`) is not used. Also, class syntax
(`.some-class`) is not supported.

## Style properties

Gaphor supports a subset of CSS properties and some Gaphor specific properties.
The style sheet interpreter is relatively straight forward.
All widths, heights and sizes are measured in pixels.
No complex style declarations are supported,
like the `font` property in HTML/CSS which can contain font family, size, weight.
The style sheet interpreter is relatively straight forward. We measure all
widths, heights, and sizes in pixels. We don't support complex style
declarations, like the `font` property in HTML/CSS which can contain font
family, size, weight.

### Colors

Expand All @@ -125,69 +129,73 @@ like the `font` property in HTML/CSS which can contain font family, size, weight
```

* A color can be any [CSS3 color code](https://www.w3.org/TR/2018/REC-css-color-3-20180619/),
as described in the CSS documentation.
All color notations are supported: `rgb()`, `rgba()`, `hsl()`, `hsla()`, Hex code (`#ffffff`) and color names.
as described in the CSS documentation. We support all color notations:
`rgb()`, `rgba()`, `hsl()`, `hsla()`, Hex code (`#ffffff`) and color names.

### Text and fonts

```eval_rst
======================= =======================================
``font-family`` A single font name (e.g. ``sans``, ``serif``, ``courier``)
``font-size`` Font size: ``font-size: 14``.
``font-size`` Font size: ``font-size: 14``
``font-style`` Either ``normal`` or ``italic``
``font-weight`` Either ``normal`` or ``bold``
``text-align`` Either ``left``, ``center``, ``right``
``text-decoration`` Either ``none`` or ``underline``
``vertical-align`` Vertical alignment for text.
``vertical-align`` Vertical alignment for text
Either ``top``, ``middle`` or ``bottom``.
``vertical-spacing`` Set vertical spacing for icon-like items (actors, start state).
Either ``top``, ``middle`` or ``bottom``
``vertical-spacing`` Set vertical spacing for icon-like items (actors, start state)
Example: ``vertical-spacing: 4``
======================= =======================================
```

* `font-family` can be only one font name, not a list of (fallback) names, as is used for HTML.
* `font-family` can be only one font name, not a list of (fallback) names, as
is used for HTML.

### Drawing and spacing

```eval_rst
======================= =======================================
``border-radius`` Radius for rectangles: ``border-radius: 4``.
``dash-style`` Style for dashed lines: ``dash-style: 7 5``.
``line-style`` Either ``normal`` or ``sloppy [factor]``.
``line-width`` Set the width for lines: ``line-width: 2``.
``min-height`` Set minimal height for an item: ``min-height: 50``.
``min-width`` Set minimal width for an item: ``min-width: 100``.
``padding`` CSS style padding (top, right, bottom, left).
``border-radius`` Radius for rectangles: ``border-radius: 4``
``dash-style`` Style for dashed lines: ``dash-style: 7 5``
``line-style`` Either ``normal`` or ``sloppy [factor]``
``line-width`` Set the width for lines: ``line-width: 2``
``min-height`` Set minimal height for an item: ``min-height: 50``
``min-width`` Set minimal width for an item: ``min-width: 100``
``padding`` CSS style padding (top, right, bottom, left)
Example: ``padding: 3 4``
======================= =======================================
```

* `padding` is defined by 1 to 4 numbers. No unit (px, pt, em) needs to be used. All values are in pixel distance.
* `padding` is defined by integers in the range of 1 to 4. No unit (px, pt, em)
needs to be used. All values are in pixel distance.
* `dash-style` is a list of numbers (line, gap, line, gap, ...)
* `line-style` has only effect when defined on a `diagram`. A sloppiness factor can be provided, somewhere between -2 and 2.
* `line-style` only has an effect when defined on a `diagram`. A sloppiness
factor can be provided in the range of -2 to 2.

### Diagram styles

Only a few properties can be defined on a diagram, namely `background-color`
and `line-style`. The diagram style is defined separately from the diagram item
and `line-style`. We define the diagram style separately from the diagram item
styles. That way it's possible to set the background color for diagrams
specifically. The line style can be normal, straight, lines or a more playful
"sloppy" style. For the sloppy style an optional factor can be provided. This
factor determines the level of wobblyness of the lines. 0.5 is default, 0.0 is
a straight line. The value should be between -2.0 and 2.0. Values between 0.0
and 0.5 make for a subtle effect.
specifically. The line style can be the normal straight lines, or a more
playful "sloppy" style. For the sloppy style an optional wobliness factor can
be provided to set the level of line wobbliness. 0.5 is default, 0.0 is a
straight line. The value should be between -2.0 and 2.0. Values between 0.0 and
0.5 make for a subtle effect.

## Ideas

Here are some ideas that go just beyond changing a color or a font.
With the following examples we dig in to Gaphor's model structure to reveal more
Here are some ideas that go just beyond changing a color or a font. With the
following examples we dig in to Gaphor's model structure to reveal more
information to the users.

To create your own expression you may want to use the Console (Tools -> Console, in the Hamburger ment).
Drop us a line on [Gitter](https://gitter.im/gaphor/Lobby) and we're happy to help you.
To create your own expression you may want to use the Console (Tools ->
Console, in the Hamburger menu). Drop us a line on
[Gitter](https://gitter.im/gaphor/Lobby) and we would be happy to help you.

### The drafts package

Expand All @@ -201,10 +209,12 @@ diagram[namespace.name=drafts] {

### Unconnected relationships

All items on a diagram that are not backed by a model element, should be drawn in a dark red color.
This can be used to spot not-so-well connected relationships, such as Generalization, Implementation, and Dependency.
These items will only be backed by a model element once both line ends are connected.
This rule will exclude simple elements line lines and boxes, which will never have a backing model element.
All items on a diagram that are not backed by a model element, should be drawn
in a dark red color. This can be used to spot not-so-well connected
relationships, such as Generalization, Implementation, and Dependency.
These items will only be backed by a model element once you connect both line
ends. This rule will exclude simple elements, like lines and boxes, which will
never have a backing model element.

```css
:not([subject], :is(line, box, ellipse, commentline)) {
Expand All @@ -214,9 +224,11 @@ This rule will exclude simple elements line lines and boxes, which will never ha

### Navigable associations

Say you create a model and for some reason at least one end should be navigable.
This is actually the case for the model file used to create Gaphor's data model.
If no end is navigable I'd like to signal this by coloring the association blue.
An example of how to apply a style to a navigable association is to color an
association blue if neither of the ends are navigable. This color could act as
a validation rule for a model where at least one end of each association should
be navigable. This is actually the case for the model file used to create
Gaphor's data model.

```css
association:not([memberEnd.navigability*=true]) {
Expand Down

0 comments on commit 316ff8a

Please sign in to comment.