frame

package
v0.1.0-experimental.3 Latest Latest
Warning

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

 Go to latest Published: Nov 24, 2021 License: BSD-3-Clause Imports: 17 Imported by: 0

Documentation

Overview

Package frame deals with typesetting frames.

Typesetting may be understood as the process of placing boxes within larger boxes. The smallest type of box is a glyph, i.e. a printable letter. The largest type of box is a page—or even a book, where page-boxes are placed into.

The box model is very versatile. Nevertheless we will generalize the notion of a box to mean the bounding box of a polygon. Typesetting in irregular shapes is a feature available in most modern systems, e.g. when letting text flow around a non-rectangular illustration.

This module deals with rectangular boxes, starting at the glyph level. Boxes follow the CSS box model. Nevertheless, the notation oftentimes follows the one introduced by the TeX typesetting system.

______________________________________________________________________

BSD License

Copyright (c) 2017–2021, 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 (
	Top int = iota
	Right
	Bottom
	Left
)

For padding, margins, etc. 4-way values always start at the top and travel clockwise.

Variables

View Source 
var ErrContentScaling error = errors.New("box scales with content")

ErrContentScaling is returned if a dimension calculation encounters a dimension-specification which is dependent on the box's content.

View Source 
var ErrUnderspecified error = errors.New("box width dimensions are underspecified")

ErrUnderspecified is returned if a dimension calculation cannot be completed because the input values are underspecified.

View Source 
var ErrUnfixedScaledUnit error = errors.New("font/view dependent dimension is unfixed")

ErrUnfixedScaledUnit is returned if a dimension calculation encounters a dimension-specification which is dependent on view-size or font-size.

Functions

func CollapseMargins 

func CollapseMargins(box1, box2 *Box) (css.DimenT, css.DimenT)

CollapseMargins returns the greater margin between bottom margin of box1 and top margin of box2, and the smaller one as the second return value.

If any of the boxes' margins are unset, return values may be unset, too.

func DisplayModeForDOMNode 

func DisplayModeForDOMNode(domnode *dom.W3CNode) css.DisplayMode

DisplayModeForDOMNode returns outer and inner display mode for a given DOM node.

func FixDimensionsFromEnclosingWidth 

func FixDimensionsFromEnclosingWidth(box *Box, enclosingWidth dimen.Dimen) (bool, error)

FixDimensionsFromEnclosingWidth calculates missing/auto dimensions from the width of the enclosing box.

This will distribute space according to the equation (ref. CSS spec): 

margin-left + border-width-left + padding-left + width +
  padding-right + border-width-right + margin-right = width of containing block

Returns a flag denoting whether there was enough information to specify each width dimension.

func T 

func T() tracing.Trace

T traces to the engine tracer.

Types

type BorderStyle 

type BorderStyle struct {
	LineColor    color.Color
	LineStyle    int8
	CornerRadius dimen.Dimen
}

BorderStyle is a type for simple borders.

type Box 

type Box struct {
	Rect            // either content box or border box, depending on box-sizing
	Min             Size
	Max             Size
	BorderBoxSizing bool          // box-sizing = border-box ?
	Padding         [4]css.DimenT // inside of border
	BorderWidth     [4]css.DimenT // thickness of border
	Margins         [4]css.DimenT // outside of border, maybe unknown
}

Box type, following the CSS box model.

func InitEmptyBox 

func InitEmptyBox(box *Box) *Box

InitEmptyBox initializes padding, border and margins to 0 and box.W to auto.

func (*Box) BorderBoxHeight 

func (box *Box) BorderBoxHeight() css.DimenT

BorderBoxHeight returns the width of a box, including padding and border. If box has box-sizing set to `content-box`and at least one of the dimensions is not of fixed value, an unset dimension is returned.

func (*Box) BorderBoxWidth 

func (box *Box) BorderBoxWidth() css.DimenT

BorderBoxWidth returns the width of a box, including padding and border. If box has box-sizing set to `content-box`and at least one of the dimensions is not of fixed value, an unset dimension is returned.

func (*Box) ContentHeight 

func (box *Box) ContentHeight() css.DimenT

ContentHeight returns the height of the content box. If this box has box-sizing set to `border-box` and the height dimensions do not have fixed values, an unset dimension is returned.

func (*Box) ContentWidth 

func (box *Box) ContentWidth() css.DimenT

ContentWidth returns the width of the content box. If this box has box-sizing set to `border-box` and the width dimensions do not have fixed values, an unset dimension is returned.

func (*Box) DebugString 

func (box *Box) DebugString() string

DebugString returns a textual representation of a box's dimensions. Intended for debugging.

func (*Box) DecorationWidth 

func (box *Box) DecorationWidth(includeMargins bool) css.DimenT

DecorationWidth returns the cumulated width of padding, borders and margins if all of them have known values, and an unset dimension otherwise.

func (*Box) FixBorderBoxWidth 

func (box *Box) FixBorderBoxWidth(w dimen.Dimen)

FixBorderBoxWidth sets a known border box width for a box.

If box has box-sizing set to `content-box` and at least one of the internal widths has a variable value, the size is not set. Otherwise padding and border have to be set beforehand to have a correct result for the width-calculation.

Will return true if all inner horizontal dimensions (i.e., excluding margins) are fixed.

func (*Box) FixContentWidth 

func (box *Box) FixContentWidth(w dimen.Dimen) bool

FixContentWidth sets a known value for the width of the content box. If padding or border have any %-relative values, those will be set to fixed dimensions as well. If box has box-sizing set to `border-box` and one of the width dimensions is of unknown value, false is returned and the content width is not set.

func (*Box) FixPercentages 

func (box *Box) FixPercentages(enclosingWidth dimen.Dimen) bool

func (*Box) HasFixedBorderBoxHeight 

func (box *Box) HasFixedBorderBoxHeight(includeMargins bool) bool

HasFixedBorderBoxHeight return true if box.W, horizontal margins and border width for left and right border have fixed (known) values. If includeMargins is true, left and right margins are checked as well.

func (*Box) HasFixedBorderBoxWidth 

func (box *Box) HasFixedBorderBoxWidth(includeMargins bool) bool

HasFixedBorderBoxWidth return true if box.W, horizontal margins and border width for left and right border have fixed (known) values. If includeMargins is true, left and right margins are checked as well.

func (*Box) OuterBox 

func (box *Box) OuterBox() Rect

func (*Box) SetWidth 

func (box *Box) SetWidth(w css.DimenT)

SetWidth sets the width of a box. Depending on wether `box-sizing` is set to `content-box` (default) or `border-box`, this box.W will then reflect either the content box width or the border box width.

TODO remove this ?

func (*Box) TotalHeight 

func (box *Box) TotalHeight() css.DimenT

TotalHeight returns the overall height of a box.

func (*Box) TotalWidth 

func (box *Box) TotalWidth() css.DimenT

TotalWidth returns the overall width of a box, including margins. If one of the dimensions is not of fixed value, an unset dimension is returned.

type ColorStyle 

type ColorStyle struct {
	Foreground color.Color
	Background color.Color // may be (semi-)transparent
}

ColorStyle is a type for styling with color.

type Container 

type Container interface {
	Type() ContainerType
	DOMNode() *dom.W3CNode
	TreeNode() *tree.Node
	CSSBox() *Box
	DisplayMode() css.DisplayMode // CSS display property
	Context() Context             // return the containers formatting context
	SetContext(Context)           // context will be injected
	PresetContained() bool        // pre-set contraints for children containers
	ChildIndex() int
}

Container is an interface type for render tree nodes, i.e., boxes.

type ContainerBase 

type ContainerBase struct {
	tree.Node                 // a container is a node within the layout tree
	ChildInx  uint32          // this box represents child #childInx of the parent principal box
	Display   css.DisplayMode // inner and outer display mode
}

func (*ContainerBase) ChildIndex 

func (b *ContainerBase) ChildIndex() int

ChildIndex returns the index of this container within the children of the enclosing container.

func (*ContainerBase) DisplayMode 

func (b *ContainerBase) DisplayMode() css.DisplayMode

DisplayMode returns the computed display mode of this box.

func (*ContainerBase) Self 

func (b *ContainerBase) Self() interface{}

Self points to the implementing type

func (*ContainerBase) TreeNode 

func (b *ContainerBase) TreeNode() *tree.Node

TreeNode returns the underlying tree node for a box.

type ContainerType 

type ContainerType uint8
const (
	TypeUnknown ContainerType = iota
)

type Context 

type Context interface {
	Type() FormattingContextType
	Container() Container                    // container which creates this formatting context
	Contained() []Container                  // contained children
	AddContained(Container)                  // add a child to contain
	Layout(*FlowRoot) error                  // layout sub-container
	Measure() (Size, css.DimenT, css.DimenT) // return dimensions of context bounding box
	IsFlowRoot() bool                        // this is a self-contained BFC
	FlowRoot() *FlowRoot                     // non-nil if this context is a flow root
}

Context establishes a CSS formatting context.

“Boxes in the normal flow belong to a formatting context, which may be block or inline, but not both simultaneously. Block-level boxes participate in a block formatting context. Inline-level boxes participate in an inline formatting context.”

type ContextBase 

type ContextBase struct {
	tree.Node
	C         Container
	IsRootCtx bool
	// contains filtered or unexported fields
}

func (ContextBase) Contained 

func (ctx ContextBase) Contained() []Container

func (ContextBase) Container 

func (ctx ContextBase) Container() Container

func (ContextBase) FlowRoot 

func (ctx ContextBase) FlowRoot() *FlowRoot

func (ContextBase) IsFlowRoot 

func (ctx ContextBase) IsFlowRoot() bool

func (ContextBase) TreeNode 

func (ctx ContextBase) TreeNode() *tree.Node

type FloatList 

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

func (*FloatList) AppendFloat 

func (l *FloatList) AppendFloat(float Container)

func (*FloatList) Contains 

func (l *FloatList) Contains(float Container) bool

func (*FloatList) Floats 

func (l *FloatList) Floats() []Container

func (*FloatList) Remove 

func (l *FloatList) Remove(float Container) bool

type FlowRoot 

type FlowRoot struct {
	PositionedFloats   *FloatList
	UnpositionedFloats *FloatList
}

type FormattingContextType 

type FormattingContextType uint8
const (
	NoContext FormattingContextType = iota
)

type LineStyle 

type LineStyle int8

LineStyle is a type for border line styles. 

const (
	LSSolid  LineStyle = 0
	LSDashed LineStyle = 1
	LSDotted LineStyle = 2
)

We support these line styles only

type Rect 

type Rect struct {
	TopL dimen.Point
	Size
}

type Size 

type Size struct {
	W css.DimenT
	H css.DimenT
}

type StyleSet 

type StyleSet struct {
	Props      *style.PropertyMap
	EmbBidiDir bidi.Direction // embedding bidi text direction
}

StyleSet is a type to hold CSS-styles/properties for runs of text (of a paragraph).

func (StyleSet) BidiDir 

func (set StyleSet) BidiDir() bidi.Direction

func (StyleSet) Equals 

func (set StyleSet) Equals(other styled.Style) bool

Equals is part of interface cords.styled.Style, not intended for client usage.

func (StyleSet) Font 

func (set StyleSet) Font() *font.TypeCase

func (StyleSet) Parindent 

func (set StyleSet) Parindent() dimen.Dimen

func (StyleSet) Space 

func (set StyleSet) Space() (dimen.Dimen, dimen.Dimen, dimen.Dimen)

func (StyleSet) String 

func (set StyleSet) String() string

String is part of interface cords.styled.Style.

func (StyleSet) Styles 

func (set StyleSet) Styles() *style.PropertyMap

func (StyleSet) Whitespace 

func (set StyleSet) Whitespace(ws string) string

type StyledBox 

type StyledBox struct {
	Box
	Styles *Styling
}

StyledBox is a type for a fully stylable box.

type Styling 

type Styling struct {
	TextStyle TextStyle
	Colors    ColorStyle
	Border    BorderStyle
}

Styling rolls all styling options into one type.

type TextStyle 

type TextStyle struct {
	Typecase *font.TypeCase
}

TextStyle is a type for styling text.

Source Files

View all Source files

Directories

Path Synopsis
Package boxtree produces a box-tree from a styled tree (DOM).
 Package boxtree produces a box-tree from a styled tree (DOM).
Package inline produces line boxes from khipus.
 Package inline produces line boxes from khipus.
experiments
Package khipu is about encoding text into typesetting items.
 Package khipu is about encoding text into typesetting items.
linebreak
Package linebreak collects types for line-breaking.
 Package linebreak collects types for line-breaking.
linebreak/firstfit
Package firstfit implements a straightforward line-breaking algorithm where lines are broken at the first suitable breakpoint.
 Package firstfit implements a straightforward line-breaking algorithm where lines are broken at the first suitable breakpoint.
linebreak/knuthplass
Package knuthplass implements (in an early draft) a line breaking algorithm described by D.E. Knuth and M.F. Plass.
 Package knuthplass implements (in an early draft) a line breaking algorithm described by D.E. Knuth and M.F. Plass.
Package layout produces a render tree from a styled tree.
 Package layout produces a render tree from a styled tree.

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.