layout

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: 13 Imported by: 0

README

LibNSLayout Architecture

LibNSLayout is a library for performing layout on a Document Object Model for HTML. Its purpose is to allow client applications to provide DOM information and convert that into a render list, which can be displayed by the client.

Dependencies

Clients of LibNSLayout must use the following additional libraries, because their types are used in the LibNSLayout interface:

  • LibDOM is used to provide the DOM interface.
  • LibCSS is used to provide the CSS handling.
  • LibWapcaplet is used for interned strings.
  • LibNSLog for logging.

Interface

The devision of responsibilities between LibNSLayout and its clients are as follows:

Client
  • Fetching the document to be displayed.
  • Creating a CSS selection context (with default user-agent, and user CSS).
  • Generating DOM.
  • Creating a LibNSLayout layout for the document, passing the DOM document, CSS selection context, appropriate CSS media descriptor, and scale.
  • Listening to DOM changes.
    • Fetching resources needed by DOM.
      • CSS (STYLE elements, and LINK elements):
        • Parsing the CSS.
        • Updating CSS selection context as stylesheets are fetched, and notifying LibNSLayout.
      • JavaScript (SCRIPT elements, and LINK elements)
        • Executing JavaScript.
      • Favicons (LINK elements.)
      • Images, Frames, Iframes.
    • Notifying LibNSLayout of DOM changes.
  • Performing resource fetches on behalf of LibNSLayout.
    • (Such as when LibNSLayout requires a background image or web font for an element due to CSS.)
  • Asking LibNSLayout to perform layout.
    • Displaying the returned render list.
  • Asking LibNSLayout for layout info (e.g. due to JavaScript.)
  • Passing mouse actions to LibNSLayout.
  • Passing keyboard input to LibNSLayout.
  • Passing scale changes to LibNSLayout.
  • Performing measurement of text; given a string & style, calculating its width in pixels.
LibNSLayout
  • Creates a layout object that's opaque to the client, and returns its handle.
  • Performs CSS selection as appropriate when DOM changes.
  • Asking client to fetch a resource that's needed for a computed style.
  • Asking client to measure text.
  • Performs line breaking.
  • Performs layout (if required) when asked by client and returns render list.
  • Performs layout (if required) when asked by client for layout info.

Box Layout

Module Layout is responsible for creating the render trecreating the render tree. This includes line-breaking for paragraphs.

When the client requires a layout, we would then walk the tree, ensuring every layout node has a valid x, y, width, and height.

Rendering

The client is responsible for rendering, and any compositing. When the client asks the layouter to layout, we return a render list.

Documentation

Overview

Package layout produces a render tree from a styled tree.

Overview

Early draft, nothing useful here yet.

BSD License

Copyright (c) 2017–2020, 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

This section is empty.

Variables

View Source 
var ErrAnonBoxNotFound = fmt.Errorf("No anonymous box found for index")

ErrAnonBoxNotFound flags an error condition where an anonymous box should be present but could not be found.

View Source 
var ErrNullChild = fmt.Errorf("Child box max not be null")

ErrNullChild flags an error condition when a non-nil child has been expected.

Functions

func DefaultDisplayModeForHTMLNode 

func DefaultDisplayModeForHTMLNode(h *html.Node) (DisplayMode, DisplayMode)

DefaultDisplayModeForHTMLNode returns the default display mode for a HTML node type, as described by the CSS specification.

TODO possibly move this to package style (= part of browser defaults) If, then return a string.

func DisplayModesForDOMNode 

func DisplayModesForDOMNode(domnode *dom.W3CNode) (outerMode DisplayMode, innerMode DisplayMode)

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

func ParseDisplay 

func ParseDisplay(display string) (DisplayMode, DisplayMode, error)

ParseDisplay returns mode flags from a display property string (outer and inner).

func ReorderBoxTree 

func ReorderBoxTree(boxRoot *PrincipalBox) error

ReorderBoxTree reorders box nodes of a render tree to account for "position" CSS properties. In a future version, CSS regions will be supported as well.

func T 

func T() tracing.Trace

T traces to the engine tracer.

Types

type AnonymousBox 

type AnonymousBox struct {
	tree.Node          // an anonymous box is a node within the layout tree
	Box       *box.Box // an anoymous box cannot be styled

	ChildInxFrom uint32 // this box represents children starting at #ChildInxFrom of the principal box
	ChildInxTo   uint32 // this box represents children to #ChildInxTo
	// contains filtered or unexported fields
}

AnonymousBox is a type for CSS anonymous boxes.

From the spec: "If a container box (inline or block) has a block-level box inside it, then we force it to have only block-level boxes inside it."

These block-level boxes are anonymous boxes. There are anonymous inline-level boxes, too. Both are not directly stylable by the user, but rather inherit the styles of their principal boxes.

func (*AnonymousBox) ChildIndices 

func (anon *AnonymousBox) ChildIndices() (uint32, uint32)

ChildIndices returns the positional indices of all child-boxes in reference to the principal box.

func (*AnonymousBox) DOMNode 

func (anon *AnonymousBox) DOMNode() w3cdom.Node

DOMNode returns the underlying DOM node for a render tree element.

func (*AnonymousBox) DisplayModes 

func (anon *AnonymousBox) DisplayModes() (DisplayMode, DisplayMode)

DisplayModes returns outer and inner display mode of this box.

func (*AnonymousBox) IsAnonymous 

func (anon *AnonymousBox) IsAnonymous() bool

IsAnonymous will always return true for an anonymous box.

func (*AnonymousBox) IsText 

func (anon *AnonymousBox) IsText() bool

IsText will always return false for an anonymous box.

func (*AnonymousBox) String 

func (anon *AnonymousBox) String() string

func (*AnonymousBox) TreeNode 

func (anon *AnonymousBox) TreeNode() *tree.Node

TreeNode returns the underlying tree node for a box.

type Container 

type Container interface {
	DOMNode() w3cdom.Node
	TreeNode() *tree.Node
	IsAnonymous() bool
	IsText() bool
	DisplayModes() (DisplayMode, DisplayMode)
	ChildIndices() (uint32, uint32)
}

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

func BuildBoxTree 

func BuildBoxTree(domRoot *dom.W3CNode) (Container, error)

BuildBoxTree creates a render box tree from a styled tree.

func NewBoxForDOMNode 

func NewBoxForDOMNode(domnode *dom.W3CNode) Container

NewBoxForDOMNode creates an adequately initialized box for a given DOM node.

type DisplayMode 

type DisplayMode uint16

DisplayMode is a type for CSS property "display". 

const (
	NoMode       DisplayMode = iota   // unset or error condition
	DisplayNone  DisplayMode = 0x0001 // CSS outer display = none
	FlowMode     DisplayMode = 0x0002 // CSS inner display = flow
	BlockMode    DisplayMode = 0x0004 // CSS block context (inner or outer)
	InlineMode   DisplayMode = 0x0008 // CSS inline context
	ListItemMode DisplayMode = 0x0010 // CSS list-item display
	FlowRoot     DisplayMode = 0x0020 // CSS flow-root display property
	FlexMode     DisplayMode = 0x0040 // CSS inner display = flex
	GridMode     DisplayMode = 0x0080 // CSS inner display = grid
	TableMode    DisplayMode = 0x0100 // CSS table display property (inner or outer)
	ContentsMode DisplayMode = 0x0200 // CSS contents display mode, experimental !
)

Flags for box context and display mode (outer and inner).

func (DisplayMode) Contains 

func (disp DisplayMode) Contains(d DisplayMode) bool

Contains checks if a display mode contains a given atomic mode. Returns false for d = NoMode.

func (DisplayMode) FullString 

func (disp DisplayMode) FullString() string

FullString returns all atomic modes set in a display mode.

func (DisplayMode) Overlaps 

func (disp DisplayMode) Overlaps(d DisplayMode) bool

Overlaps returns true if a given display mode shares at least one atomic mode flag with disp (excluding NoMode).

func (*DisplayMode) Set 

func (disp *DisplayMode) Set(d DisplayMode)

Set sets a given atomic mode within this display mode.

func (DisplayMode) String 

func (i DisplayMode) String() string

func (DisplayMode) Symbol 

func (disp DisplayMode) Symbol() string

Symbol returns a Unicode symbol for a mode.

type PrincipalBox 

type PrincipalBox struct {
	tree.Node                // a container is a node within the layout tree
	Box       *box.StyledBox // styled box for a DOM node

	ChildInx uint32 // this box represents child #ChildInx of the parent principal box
	// contains filtered or unexported fields
}

PrincipalBox is a (CSS-)styled box which may contain other boxes. It references a node in the styled tree, i.e., a stylable DOM element node.

func TreeNodeAsPrincipalBox 

func TreeNodeAsPrincipalBox(n *tree.Node) *PrincipalBox

TreeNodeAsPrincipalBox retrieves the payload of a tree node as a PrincipalBox. Will be called from clients as 

box := layout.PrincipalBoxFromNode(n)

func (*PrincipalBox) AddChild 

func (pbox *PrincipalBox) AddChild(child *PrincipalBox) error

AddChild appends a child box to its parent principal box. The child is a principal box itself, i.e. references a styleable DOM node. The child must have its child index set.

func (*PrincipalBox) AddTextChild 

func (pbox *PrincipalBox) AddTextChild(child *TextBox) error

AddTextChild appends a child box to its parent principal box. The child is a text box, i.e., references a HTML text node. The child must have its child index set.

func (*PrincipalBox) AppendChild 

func (pbox *PrincipalBox) AppendChild(child *PrincipalBox)

AppendChild appends a child box to a principal box. The child is a principal box itself, i.e. references a styleable DOM node. It is appended as the last child of pbox.

func (*PrincipalBox) ChildIndices 

func (pbox *PrincipalBox) ChildIndices() (uint32, uint32)

ChildIndices returns the positional index of this box reference to the parent principal box. To comply with the PrincipalBox interface, it returns the index twice (from, to).

func (*PrincipalBox) DOMNode 

func (pbox *PrincipalBox) DOMNode() w3cdom.Node

DOMNode returns the underlying DOM node for a render tree element.

func (*PrincipalBox) DisplayModes 

func (pbox *PrincipalBox) DisplayModes() (DisplayMode, DisplayMode)

DisplayModes returns outer and inner display mode of this box.

func (*PrincipalBox) IsAnonymous 

func (pbox *PrincipalBox) IsAnonymous() bool

IsAnonymous will always return false for a container.

func (*PrincipalBox) IsPrincipal 

func (pbox *PrincipalBox) IsPrincipal() bool

IsPrincipal returns true if this is a principal box.

Some HTML elements create a mini-hierachy of boxes for rendering. The outermost box is called the principal box. It will always refer to the styled node. An example would be an "li"-element: it will create two sub-boxes, one for the list item marker and one for the item's text/content. Another example are anonymous boxes, which will be generated for reconciling context/level-discrepancies.

func (*PrincipalBox) IsText 

func (pbox *PrincipalBox) IsText() bool

IsText will always return false for a principal box.

func (*PrincipalBox) String 

func (pbox *PrincipalBox) String() string

func (*PrincipalBox) TreeNode 

func (pbox *PrincipalBox) TreeNode() *tree.Node

TreeNode returns the underlying tree node for a box.

type TextBox 

type TextBox struct {
	tree.Node          // a text box is a node within the layout tree
	Box       *box.Box // text box cannot be explicitely styled

	//outerMode DisplayMode  // container lives in this mode (block or inline)
	ChildInx uint32 // this box represents a text node at #ChildInx of the principal box
	// contains filtered or unexported fields
}

TextBox is a type for CSS inline text boxes. It references a text node in the DOM. They are not directly stylable by the user, but rather inherit the styles of their principal boxes. Text boxes have an inner display type of inline.

func (*TextBox) ChildIndices 

func (tbox *TextBox) ChildIndices() (uint32, uint32)

ChildIndices returns the positional index of the text node in reference to the principal box. To comply with the PrincipalBox interface, it returns the index twice (from, to).

func (*TextBox) DOMNode 

func (tbox *TextBox) DOMNode() w3cdom.Node

DOMNode returns the underlying DOM node for a render tree element.

func (*TextBox) DisplayModes 

func (tbox *TextBox) DisplayModes() (DisplayMode, DisplayMode)

DisplayModes always returns inline.

func (*TextBox) IsAnonymous 

func (tbox *TextBox) IsAnonymous() bool

IsAnonymous will always return true for a text box.

func (*TextBox) IsText 

func (tbox *TextBox) IsText() bool

IsText will always return true for a text box.

func (*TextBox) TreeNode 

func (tbox *TextBox) TreeNode() *tree.Node

TreeNode returns the underlying tree node for a box.

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.