style

package
v0.0.0-...-ae32867 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Dec 12, 2020 License: BSD-3-Clause Imports: 7 Imported by: 0

Documentation

Overview

Package style provides functionality for CSS styling properties.

Status

This is a very first draft. It is unstable and the API will change without notice. Please be patient.

Overview

We strive to separate content from presentation. In typesetting, this is probably an impossible claim, but we'll try anyway. Presentation is governed with CSS (Cascading Style Sheets). CSS uses a box model more complex than TeX's, which is well described here: 

https://developer.mozilla.org/en-US/docs/Learn/CSS/Introduction_to_CSS/Box_model

If you think about it: a typesetter using the HTML/CSS box model is effectively a browser with output type PDF. Browsers are large and complex pieces of code, a fact that implies that we should seek out where to reduce complexity.

A good explanation of styling may be found in 

https://hacks.mozilla.org/2017/08/inside-a-super-fast-css-engine-quantum-css-aka-stylo/

CSSOM is the "CSS Object Model", similar to the DOM for HTML. There is not very much open source Go code around for supporting us in implementing a styling engine, except the great work of https://godoc.org/github.com/andybalholm/cascadia. Therefore we will have to compromise on many feature in order to complete this in a realistic time frame. For a reminder of why that is, refer to https://www.youtube.com/watch?v=S68fcV09nGQ .

The styling engine produces a tree data structure, called "styled tree". Different web browser implementations call it differentyl ("render tree", ...). We define appropriate interfaces to de-couple the styled tree implmentation from the styling engine. This may sound odd, as the styled tree is such a central data structure to the engine. However, we expect to use different implementations of styled trees, depending on wether it is used for print or for interactive use.

A concrete default implementations may be found in package dom.styledtree.

References 

https://www.tutorialrepublic.com/css-reference/css3-properties.php
https://www.w3schools.com/css/css3_multiple_columns.asp
https://www.mediaevent.de/xhtml/kernattribute.html

BSD License

Copyright (c) 2017–20, Norbert Pillmayer

All rights reserved.

Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:

1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.

2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.

3. Neither the name of this software nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

Index

Constants

View Source 
const (
	PGMargins   = "Margins"
	PGPadding   = "Padding"
	PGBorder    = "Border"
	PGDimension = "Dimension"
	PGDisplay   = "Display"
	PGRegion    = "Region"
	PGX         = "X"
)

Symbolic names for string literals, denoting PropertyGroups.

Variables

This section is empty.

Functions

func GroupNameFromPropertyKey 

func GroupNameFromPropertyKey(key string) string

GroupNameFromPropertyKey returns the style property group name for a style property. Example: 

GroupNameFromPropertyKey("margin-top") => "Margins"

Unknown style property keys will return a group name of "X".

func T 

func T() tracing.Trace

T returns a global tracer. We trace to the EngineTracer

Types

type Creator 

type Creator interface {
	StyleForHTMLNode(*html.Node) *tree.Node
	ToStyler(*tree.Node) Styler
	SetStyles(*tree.Node, *PropertyMap)
}

Creator is a function to create a style node for a given HTML node. You can think of this interface as an adapter from a certain tree implementation to a styled tree.

type Interf 

type Interf func(*tree.Node) Styler

Interf is a mapper from a concrete tree node to an interface implementation for Styler. You can think of this function type as an adapter from a certain tree implementation to a styled tree.

type KeyValue 

type KeyValue struct {
	Key   string
	Value Property
}

KeyValue is a container for a style property.

func SplitCompoundProperty 

func SplitCompoundProperty(key string, value Property) ([]KeyValue, error)

SplitCompoundProperty splits up a shortcut property into its individual components. Returns a slice of key-value pairs representing the individual (fine grained) style properties. Example: 

SplitCompountProperty("padding", "3px")

will return 

"padding-top"    => "3px"
"padding-right"  => "3px"
"padding-bottom" => "3px"
"padding-left  " => "3px"

For the logic behind this, refer to e.g. https://www.w3schools.com/css/css_padding.asp .

type Property 

type Property string

Property is a raw value for a CSS property. For example, with 

color: black

a property value of "black" is set. The main purpose of wrapping the raw string value into type Property is to provide a set of convenient type conversion functions and other helpers. 

const NullStyle Property = ""

NullStyle is an empty property value.

func DisplayPropertyForHTMLNode 

func DisplayPropertyForHTMLNode(node *html.Node) Property

DisplayPropertyForHTMLNode returns the *display* CSS property for an HTML node.

func GetCascadedProperty 

func GetCascadedProperty(n *tree.Node, key string, sty Interf) (Property, error)

GetCascadedProperty gets the value of a property. The search cascades to parent property maps, if available.

Clients will usually call GetProperty(…) instead as this will respect CSS semantics for inherited properties.

The call to GetCascadedProperty will flag an error if the style property isn't found (which should not happen, as every property should be included in the 'user-agent' default style properties).

func GetDefaultProperty 

func GetDefaultProperty(styler Styler, key string) Property

GetDefaultProperty returns the default property for a given key.

func GetLocalProperty 

func GetLocalProperty(pmap *PropertyMap, key string) (Property, bool)

GetLocalProperty returns a style property value, if it is set locally for a styled node's property map. No cascading is performed.

func GetProperty 

func GetProperty(n *tree.Node, key string, sty Interf) (Property, error)

GetProperty gets the value of a property. If the property is not set locally on the style node and the property is inheritable, he search cascades to parent property maps, if available.

The call to GetProperty will flag an error if the style property isn't found (which should not happen, as every property should be included in the 'user-agent' default style properties).

func (Property) IsEmpty 

func (p Property) IsEmpty() bool

IsEmpty checks wether a property is empty, i.e. the null-string.

func (Property) IsInherited 

func (p Property) IsInherited() bool

IsInherited denotes if a property is of inheritence-type "inheritet"

func (Property) IsInitial 

func (p Property) IsInitial() bool

IsInitial denotes if a property is of inheritence-type "initial"

func (Property) String 

func (p Property) String() string

type PropertyGroup 

type PropertyGroup struct {
	Parent *PropertyGroup
	// contains filtered or unexported fields
}

PropertyGroup is a collection of propertes sharing a common topic. CSS knows a whole lot of properties. We split them up into organisatorial groups.

The mapping of property into groups is documented with GroupNameFromPropertyKey[...].

func NewPropertyGroup 

func NewPropertyGroup(groupname string) *PropertyGroup

NewPropertyGroup creates a new empty property group, given its name.

func (*PropertyGroup) Add 

func (pg *PropertyGroup) Add(key string, p Property)

Add a property's value. Does not overwrite an existing value, i.e., does nothing if a value is already set.

func (*PropertyGroup) Cascade 

func (pg *PropertyGroup) Cascade(key string) *PropertyGroup

Cascade finds the ancesiting PropertyGroup containing the given property-key.

func (*PropertyGroup) ForkOnProperty 

func (pg *PropertyGroup) ForkOnProperty(key string, p Property, cascade bool) (*PropertyGroup, bool)

ForkOnProperty creates a new PropertyGroup, pre-filled with a given property. If 'cascade' is true, the new PropertyGroup will be linking to the ancesting PropertyGroup containing this property.

func (*PropertyGroup) Get 

func (pg *PropertyGroup) Get(key string) (Property, bool)

Get a property's value.

Style property values are always converted to lower case.

func (*PropertyGroup) IsSet 

func (pg *PropertyGroup) IsSet(key string) bool

IsSet is a predicated wether a property is set within this group.

func (*PropertyGroup) Name 

func (pg *PropertyGroup) Name() string

Name returns the name of the property group. Once named (during construction, property groups may not be renamed.

func (*PropertyGroup) Properties 

func (pg *PropertyGroup) Properties() []KeyValue

Properties returns all properties of a group.

func (*PropertyGroup) Set 

func (pg *PropertyGroup) Set(key string, p Property)

Set a property's value. Overwrites an existing value, if present.

Style property values are always converted to lower case.

func (*PropertyGroup) String 

func (pg *PropertyGroup) String() string

Stringer for property groups; used for debugging.

type PropertyMap 

type PropertyMap struct {
	// contains filtered or unexported fields
}

PropertyMap holds CSS properties. nil is a legal (empty) property map. A property map is the entity styling a DOM node: a DOM node links to a property map, which contains zero or more property groups. Property maps may share property groups.

func InitializeDefaultPropertyValues 

func InitializeDefaultPropertyValues(additionalProps []KeyValue) *PropertyMap

InitializeDefaultPropertyValues creates an internal data structure to hold all the default values for CSS properties. In real-world browsers these are the user-agent CSS values.

func NewPropertyMap 

func NewPropertyMap() *PropertyMap

NewPropertyMap returns a new empty property map.

func (*PropertyMap) Add 

func (pmap *PropertyMap) Add(key string, value Property)

Add adds a property to this property map, e.g., 

pm.Add("funny-margin", "big")

func (*PropertyMap) AddAllFromGroup 

func (pmap *PropertyMap) AddAllFromGroup(group *PropertyGroup, overwrite bool) *PropertyMap

AddAllFromGroup transfers all style properties from a property group to a property map. If overwrite is set, existing style property values will be overwritten, otherwise only new values are set.

If the property map does not yet contain a group of this kind, it will simply set this group (instead of copying values).

func (*PropertyMap) GetPropertyValue 

func (pmap *PropertyMap) GetPropertyValue(key string, node *tree.Node, styler Interf) Property

GetPropertyValue returns the property value for a given key. If the property is inherited, it may cascade.

func (*PropertyMap) Group 

func (pmap *PropertyMap) Group(groupname string) *PropertyGroup

Group returns the property group for a group name or nil.

func (*PropertyMap) Property 

func (pmap *PropertyMap) Property(key string) (Property, bool)

Property returns a style property value, together with an indicator wether it has been found in the properties map. No cascading is performed

func (*PropertyMap) Size 

func (pmap *PropertyMap) Size() int

Size returns the number of property groups.

func (*PropertyMap) String 

func (pmap *PropertyMap) String() string

type Styler 

type Styler interface {
	HTMLNode() *html.Node
	Styles() *PropertyMap
}

Styler is an interface all concrete types of styled tree nodes will have to implement to be usable for layout, rendering, etc.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.