materials

package module
v0.0.0-...-36fab3e Latest Latest
Warning

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

 Go to latest Published: Dec 20, 2020 License: MIT, Unlicense Imports: 18 Imported by: 2

README

materials

This package provides various material design components for gio.

State

This package has no stable API, and should always be locked to a particular commit with go modules.

The included components attempt to conform to the material design specifications whenever possible, but they may not support unusual style tweaks or especially exotic configurations.

Implemented Components

The list of currently-Implemented components follows:

Navigation Drawer (static and modal)

The navigation drawer specified here is mostly implemented by the type NavDrawer, and the modal variant can be created with a ModalNavDrawer. The modal variant looks like this:

modal navigation drawer example screenshot

Features:

  • Animated drawer open/close.
  • Navigation items respond to hovering.
  • Navigation selection is animated.
  • Navigation item icons are optional.
  • Content can be anchored to the bottom of the drawer for pairing with a bottom app bar.

Modal features:

  • Swipe or touch scrim to close the drawer.

Known issues:

  • API targets a fairly static and simplistic menu. Sub-sections with dividers are not yet supported. An API-driven way to traverse the current menu options is also not yet supported. Contributions welcome!
App Bar (Top and Bottom)

The App Bar specified here is mostly implemented by the type AppBar. It looks like this:

Normal state:

modal navigation drawer example screenshot

Contextual state:

modal navigation drawer example screenshot

Features:

  • Action buttons and overflow menu contents can be changed easily.
  • Overflow button disappears when no items overflow.
  • Overflow menu can be dismissed by touching the scrim outside of it.
  • Action items disapper into overflow when screen is too narrow to fit them. This is animated.
  • Navigation button icon is customizable, and the button is not drawn if no icon is provided.
  • Contextual app bar can be triggered and dismissed programatically.
  • Bar supports use as a top and bottom app bar (animates the overflow menu in the proper direction).

Known Issues:

  • Compact and prominent App Bars are not yet implemented.
Side sheet (static and modal)

Side sheets (specified here) are implemented by the Sheet and ModalSheet types.

Features:

  • Animated appear/disappear

Modal features:

  • Swipe to close
  • Touch scrim to close

Known Issues:

  • Only sheets anchored on the left are currently supported (contributions welcome!)
Text Fields

Text Fields (specified here) are implemented by the TextField type.

Features:

  • Animated label transition when selected
  • Responds to hover events
  • Exposes underlying gio editor

Known Issues:

  • Icons, hint text, error text, prefix/suffix, and other features are not yet implemented.

Example

Want to see it?

git clone https://git.sr.ht/~whereswaldon/materials
cd materials
go run ./example

You can also see the demo using a bottom bar with:

go run ./example/ -bottom-bar

Contributing

Contributions to this collection are welcome! All contributions should adhere to the material design specifications for the components that they implement.

You can send bug reports, feature requests, questions, and patches to my public inbox.

All patches should be Signed-off to indicate conformance with the LICENSE of this repo.

License

Dual MIT/Unlicense; same as Gio

Documentation

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func Interpolate 

func Interpolate(a, b color.NRGBA, progress float32) color.NRGBA

func SimpleIconButton 

func SimpleIconButton(th *material.Theme, state *widget.Clickable, icon *widget.Icon) material.IconButtonStyle

SimpleIconButton creates an IconButtonStyle that is pre-configured to be the right size for use as an AppBarAction

func SwapGrounds 

func SwapGrounds(p material.Palette) material.Palette

SwapGrounds swaps the foreground and background colors of both the contrast and non-constrast colors.

Bg <-> Fg ContrastBg <-> ContrastFg

func SwapPairs 

func SwapPairs(p material.Palette) material.Palette

SwapPairs swaps the contrast and non-constrast colors.

Bg <-> ContrastBg Fg <-> ContrastFg

func WithAlpha 

func WithAlpha(c color.NRGBA, a uint8) color.NRGBA

WithAlpha returns the input color with the new alpha value.

Types

type AlphaPalette 

type AlphaPalette struct {
	Hover, Selected uint8
}

AlphaPalette is the set of alpha values to be applied for certain material design states like hover, selected, etc...

type AppBar 

type AppBar struct {
	NavigationButton       widget.Clickable
	NavigationIcon         *widget.Icon
	Title, ContextualTitle string
	// The modal layer is used to lay out the overflow menu. The nav
	// bar is not functional if this field is not supplied.
	*ModalLayer
	// Anchor indicates whether the app bar is anchored at the
	// top or bottom edge of the interface. It defaults to Top, and
	// is used to orient the layout of menus relative to the bar.
	Anchor VerticalAnchorPosition
	// contains filtered or unexported fields
}

AppBar implements the material design App Bar documented here: https://material.io/components/app-bars-top

TODO(whereswaldon): implement support for RTL layouts

func NewAppBar 

func NewAppBar(modal *ModalLayer) *AppBar

NewAppBar creates and initializes an App Bar.

func (*AppBar) CloseOverflowMenu 

func (a *AppBar) CloseOverflowMenu(when time.Time)

CloseOverflowMenu requests that the overflow menu be closed if it is open.

func (*AppBar) Events 

func (a *AppBar) Events(gtx layout.Context) []AppBarEvent

Events returns a slice of all AppBarActions to occur since the last frame.

func (*AppBar) Layout 

func (a *AppBar) Layout(gtx layout.Context, theme *material.Theme) layout.Dimensions

Layout renders the app bar. It will span all available horizontal space (gtx.Constraints.Max.X), but has a fixed height.

func (*AppBar) SetActions 

func (a *AppBar) SetActions(actions []AppBarAction, overflows []OverflowAction)

SetActions configures the set of actions available in the action item area of the app bar. They will be displayed in the order provided (from left to right) and will collapse into the overflow menu from right to left. The provided OverflowActions will always be in the overflow menu in the order provided.

func (*AppBar) SetContextualActions 

func (a *AppBar) SetContextualActions(actions []AppBarAction, overflows []OverflowAction)

SetContextualActions configures the actions that should be available in the next Contextual mode that this action bar enters.

func (*AppBar) StartContextual 

func (a *AppBar) StartContextual(when time.Time, title string)

StartContextual causes the AppBar to transform into a contextual App Bar with a different set of actions than normal. If the App Bar is already in contextual mode, this has no effect. The title will be used as the contextual app bar title.

func (*AppBar) StopContextual 

func (a *AppBar) StopContextual(when time.Time)

StopContextual causes the AppBar to stop showing a contextual menu if one is currently being displayed.

func (*AppBar) ToggleContextual 

func (a *AppBar) ToggleContextual(when time.Time, title string)

ToggleContextual switches between contextual an noncontextual mode. If it transitions to contextual mode, the provided title is used.

type AppBarAction 

type AppBarAction struct {
	OverflowAction
	Layout func(gtx layout.Context, bg, fg color.NRGBA) layout.Dimensions
}

AppBarAction configures an action in the App Bar's action items. The embedded OverflowAction provides the action information for when this item disappears into the overflow menu.

func SimpleIconAction 

func SimpleIconAction(th *material.Theme, state *widget.Clickable, icon *widget.Icon, overflow OverflowAction) AppBarAction

SimpleIconAction configures an AppBarAction that functions as a simple IconButton. To receive events from the button, use the standard methods on the provided state parameter.

type AppBarContextMenuDismissed 

type AppBarContextMenuDismissed struct{}

AppBarContextMenuDismissed indicates that the app bar context menu was dismissed during the last frame.

func (AppBarContextMenuDismissed) AppBarEvent 

func (a AppBarContextMenuDismissed) AppBarEvent()

func (AppBarContextMenuDismissed) String 

func (a AppBarContextMenuDismissed) String() string

type AppBarEvent 

type AppBarEvent interface {
	AppBarEvent()
}

AppBarEvent

type AppBarNavigationClicked 

type AppBarNavigationClicked struct{}

AppBarNavigationClicked indicates that the navigation icon was clicked during the last frame.

func (AppBarNavigationClicked) AppBarEvent 

func (a AppBarNavigationClicked) AppBarEvent()

func (AppBarNavigationClicked) String 

func (a AppBarNavigationClicked) String() string

type AppBarOverflowActionClicked 

type AppBarOverflowActionClicked struct {
	Tag interface{}
}

AppBarOverflowActionClicked indicates that an action in the app bar overflow menu was clicked during the last frame.

func (AppBarOverflowActionClicked) AppBarEvent 

func (a AppBarOverflowActionClicked) AppBarEvent()

func (AppBarOverflowActionClicked) String 

func (a AppBarOverflowActionClicked) String() string

type C 

type C = layout.Context

type D 

type D = layout.Dimensions

type Hoverable 

type Hoverable struct {
	widget.Clickable
	// contains filtered or unexported fields
}

Hoverable tracks mouse hovers over some area.

func (*Hoverable) Hovered 

func (h *Hoverable) Hovered() bool

Hovered if mouse has entered the area.

func (*Hoverable) Layout 

func (h *Hoverable) Layout(gtx C) D

Layout Hoverable according to min constraints.

type ModalLayer 

type ModalLayer struct {
	VisibilityAnimation
	Scrim
	Widget func(gtx layout.Context, th *material.Theme, anim *VisibilityAnimation) layout.Dimensions
}

ModalLayer is a widget drawn on top of the normal UI that can be populated by other material components with dismissble modal dialogs. For instance, the App Bar can render its overflow menu within the modal layer, and the modal navigation drawer is entirely within the modal layer.

func NewModal 

func NewModal() *ModalLayer

NewModal creates an initializes a modal layer.

func (*ModalLayer) Layout 

func (m *ModalLayer) Layout(gtx layout.Context, th *material.Theme) layout.Dimensions

Layout renders the modal layer. Unless a modal widget has been triggered, this will do nothing.

type ModalNavDrawer 

type ModalNavDrawer struct {
	*NavDrawer
	// contains filtered or unexported fields
}

ModalNavDrawer implements the Material Design Modal Navigation Drawer described here: https://material.io/components/navigation-drawer

func ModalNavFrom 

func ModalNavFrom(nav *NavDrawer, modal *ModalLayer) *ModalNavDrawer

func NewModalNav 

func NewModalNav(modal *ModalLayer, title, subtitle string) *ModalNavDrawer

NewModalNav configures a modal navigation drawer that will render itself into the provided ModalLayer

func (*ModalNavDrawer) Appear 

func (m *ModalNavDrawer) Appear(when time.Time)

func (*ModalNavDrawer) Disappear 

func (m *ModalNavDrawer) Disappear(when time.Time)

func (*ModalNavDrawer) Layout 

func (m *ModalNavDrawer) Layout() layout.Dimensions

func (*ModalNavDrawer) ToggleVisibility 

func (m *ModalNavDrawer) ToggleVisibility(when time.Time)

type ModalSheet 

type ModalSheet struct {
	// MaxWidth constrains the maximum amount of horizontal screen real-estate
	// covered by the drawer. If the screen is narrower than this value, the
	// width will be inferred by reserving space for the scrim and using the
	// leftover area for the drawer. Values between 200 and 400 Dp are recommended.
	//
	// The default value used by NewModalNav is 400 Dp.
	MaxWidth unit.Value

	Modal *ModalLayer

	Sheet
	// contains filtered or unexported fields
}

ModalSheet implements the Modal Side Sheet component specified at https://material.io/components/sheets-side#modal-side-sheet

func NewModalSheet 

func NewModalSheet(m *ModalLayer) *ModalSheet

NewModalSheet creates a modal sheet that can render a widget on the modal layer.

func (*ModalSheet) Appear 

func (s *ModalSheet) Appear(when time.Time)

Appear triggers the appearance of the ModalSheet.

func (*ModalSheet) Disappear 

func (s *ModalSheet) Disappear(when time.Time)

Disappear triggers the appearance of the ModalSheet.

func (*ModalSheet) LayoutModal 

func (s *ModalSheet) LayoutModal(contents func(gtx layout.Context, th *material.Theme, anim *VisibilityAnimation) layout.Dimensions)

ConfigureModal requests that the sheet prepare the associated ModalLayer to render itself (rather than another modal widget).

func (*ModalSheet) ToggleVisibility 

func (s *ModalSheet) ToggleVisibility(when time.Time)

ToggleVisibility triggers the appearance or disappearance of the ModalSheet. 

type NavDrawer struct {
	AlphaPalette

	Title    string
	Subtitle string

	// Anchor indicates whether content in the nav drawer should be anchored to
	// the upper or lower edge of the drawer. This value should match the anchor
	// of an app bar if an app bar is used in conjunction with this nav drawer.
	Anchor VerticalAnchorPosition
	// contains filtered or unexported fields
}

NavDrawer implements the Material Design Navigation Drawer described here: https://material.io/components/navigation-drawer

func NewNav 

func NewNav(title, subtitle string) NavDrawer

NewNav configures a navigation drawer 

func (m *NavDrawer) AddNavItem(item NavItem)

AddNavItem inserts a navigation target into the drawer. This should be invoked only from the layout thread to avoid nasty race conditions. 

func (m *NavDrawer) CurrentNavDestination() interface{}

CurrentNavDestination returns the tag of the navigation destination selected in the drawer. 

func (m *NavDrawer) Layout(gtx layout.Context, th *material.Theme, anim *VisibilityAnimation) layout.Dimensions
func (m *NavDrawer) LayoutContents(gtx layout.Context, th *material.Theme, anim *VisibilityAnimation) layout.Dimensions
func (m *NavDrawer) NavDestinationChanged() bool

NavDestinationChanged returns whether the selected navigation destination has changed since the last frame. 

func (m *NavDrawer) SetNavDestination(tag interface{})

SetNavDestination changes the selected navigation item to the item with the provided tag. If the provided tag does not exist, it has no effect. 

type NavItem struct {
	// Tag is an externally-provided identifier for the view
	// that this item should navigate to. It's value is
	// opaque to navigation elements.
	Tag  interface{}
	Name string

	// Icon, if set, renders the provided icon to the left of the
	// item's name. Material specifies that either all navigation
	// items should have an icon, or none should. As such, if this
	// field is nil, the Name will be aligned all the way to the
	// left. A mixture of icon and non-icon items will be misaligned.
	// Users should either set icons for all elements or none.
	Icon *widget.Icon
}

type OverflowAction 

type OverflowAction struct {
	Name string
	Tag  interface{}
}

OverflowAction holds information about an action available in an overflow menu

type Progress 

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

Progress is an animation primitive that tracks progress of time over a fixed duration as a float between [0, 1].

Progress is reversable.

Widgets map async UI events to state changes: stop, forward, reverse. Widgets then interpolate visual data based on progress value.

Update method must be called every tick to update the progress value.

func (Progress) Direction 

func (p Progress) Direction() ProgressDirection

Direction reports the current direction.

func (Progress) Finished 

func (p Progress) Finished() bool

func (Progress) Progress 

func (p Progress) Progress() float32

Progress reports the current progress as a float between [0, 1].

func (*Progress) Start 

func (p *Progress) Start(began time.Time, direction ProgressDirection, duration time.Duration)

Start the progress in the given direction over the given duration.

func (Progress) Started 

func (p Progress) Started() bool

Started reports true if progression has started.

func (*Progress) Stop 

func (p *Progress) Stop()

Stop the progress.

func (*Progress) Update 

func (p *Progress) Update(now time.Time)

type ProgressDirection 

type ProgressDirection int

ProgressDirection specifies how to update progress every tick. 

const (
	// Forward progresses from 0 to 1.
	Forward ProgressDirection = iota
	// Reverse progresses from 1 to 0.
	Reverse
)

func (ProgressDirection) String 

func (d ProgressDirection) String() string

type Rect 

type Rect struct {
	Color color.NRGBA
	Size  image.Point
	Radii float32
}

func (Rect) Layout 

func (r Rect) Layout(gtx C) D

type Scrim 

type Scrim struct {
	// FinalAlpha is the final opacity of the scrim on a scale from 0 to 255.
	FinalAlpha uint8
	widget.Clickable
}

Scrim implments a clickable translucent overlay. It can animate appearing and disappearing as a fade-in, fade-out transition from zero opacity to a fixed maximum opacity.

func (*Scrim) Layout 

func (s *Scrim) Layout(gtx layout.Context, th *material.Theme, anim *VisibilityAnimation) layout.Dimensions

Layout draws the scrim using the provided animation. If the animation indicates that the scrim is not visible, this is a no-op.

type Sheet 

type Sheet struct{}

Sheet implements the standard side sheet described here: https://material.io/components/sheets-side#usage

func NewSheet 

func NewSheet() Sheet

NewSheet returns a new sheet

func (Sheet) Layout 

func (s Sheet) Layout(gtx layout.Context, th *material.Theme, anim *VisibilityAnimation, widget layout.Widget) layout.Dimensions

Layout renders the provided widget on a background. The background will use the maximum space available.

type TextField 

type TextField struct {
	// Editor contains the edit buffer.
	widget.Editor
	// Hoverable detects mouse hovers.
	Hoverable Hoverable
	// Alignment specifies where to anchor the text.
	Alignment layout.Alignment

	// Helper text to give additional context to a field.
	Helper string
	// CharLimit specifies the maximum number of characters the text input
	// will allow. Zero means "no limit".
	CharLimit uint
	// Prefix appears before the content of the text input.
	Prefix layout.Widget
	// Suffix appears after the content of the text input.
	Suffix layout.Widget
	// contains filtered or unexported fields
}

TextField implements the Material Design Text Field described here: https://material.io/components/text-fields

func (*TextField) Clear 

func (in *TextField) Clear()

Clear the input text and reset any error status.

func (*TextField) ClearError 

func (in *TextField) ClearError()

ClearError clears any errored status.

func (TextField) IsActive 

func (in TextField) IsActive() bool

IsActive if input is in an active state (Active, Focused or Errored).

func (*TextField) IsErrored 

func (in *TextField) IsErrored() bool

IsErrored if input is in an errored state. Typically this is when the validator has returned an error message.

func (*TextField) Layout 

func (in *TextField) Layout(gtx C, th *material.Theme, hint string) D

func (*TextField) SetError 

func (in *TextField) SetError(err string)

SetError puts the input into an errored state with the specified error text.

func (*TextField) TextTooLong 

func (in *TextField) TextTooLong() bool

TextTooLong returns whether the current editor text exceeds the set character limit.

func (*TextField) Update 

func (in *TextField) Update(gtx C, th *material.Theme, hint string)

type TruncatingLabelStyle 

type TruncatingLabelStyle material.LabelStyle

TruncatingLabelStyle is a type that forces a label to fit on one line and adds a truncation indicator symbol to the end of the line if the text has been truncated.

func (TruncatingLabelStyle) Layout 

func (t TruncatingLabelStyle) Layout(gtx layout.Context) layout.Dimensions

Layout renders the label into the provided context.

type Validator 

type Validator = func(string) string

Validator validates text and returns a string describing the error. Error is displayed as helper text.

type VerticalAnchorPosition 

type VerticalAnchorPosition uint

VerticalAnchorPosition indicates the anchor position for the content of a component. Conventionally, this is use by AppBars and NavDrawers to decide how to allocate internal spacing and in which direction to animate certain actions. 

const (
	Top VerticalAnchorPosition = iota
	Bottom
)

type VisibilityAnimation 

type VisibilityAnimation struct {
	// How long does the animation last
	time.Duration
	State   VisibilityAnimationState
	Started time.Time
}

VisibilityAnimation holds the animation state for animations that transition between a "visible" and "invisible" state for a fixed duration of time.

func (VisibilityAnimation) Animating 

func (v VisibilityAnimation) Animating() bool

Animating() returns whether the animation is either in the process of appearsing or disappearing.

func (*VisibilityAnimation) Appear 

func (v *VisibilityAnimation) Appear(now time.Time)

Appear triggers the animation to begin becoming visible at the provided time. It is a no-op if the animation is already visible.

func (*VisibilityAnimation) Disappear 

func (v *VisibilityAnimation) Disappear(now time.Time)

Disappear triggers the animation to begin becoming invisible at the provided time. It is a no-op if the animation is already invisible.

func (*VisibilityAnimation) Revealed 

func (v *VisibilityAnimation) Revealed(gtx layout.Context) float32

Revealed returns the fraction of the animated entity that should be revealed at the current time in the animation. This fraction is computed with linear interpolation.

Revealed should be invoked during every frame that v.Animating() returns true.

If the animation reaches its end this frame, Revealed will transition it to a non-animating state automatically.

If the animation is in the process of animating, calling Revealed will automatically add an InvalidateOp to the provided layout.Context to ensure that the next frame will be generated promptly.

func (*VisibilityAnimation) String 

func (v *VisibilityAnimation) String(gtx layout.Context) string

func (*VisibilityAnimation) ToggleVisibility 

func (v *VisibilityAnimation) ToggleVisibility(now time.Time)

ToggleVisibility will make an invisible animation begin the process of becoming visible and a visible animation begin the process of disappearing.

func (VisibilityAnimation) Visible 

func (v VisibilityAnimation) Visible() bool

Visible() returns whether any part of the animated entity should be visible during the current animation frame.

type VisibilityAnimationState 

type VisibilityAnimationState int

VisibilityAnimationState represents possible states that a VisibilityAnimation can be in. 

const (
	Visible VisibilityAnimationState = iota
	Disappearing
	Appearing
	Invisible
)

func (VisibilityAnimationState) String 

func (v VisibilityAnimationState) String() string

Source Files

View all Source files

Directories

Path Synopsis

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.