-
-
Notifications
You must be signed in to change notification settings - Fork 2
Fluid GUI API
The GUI API provides a number of functions to perform common tasks like colour conversion and simplifying interaction with the scene graph.
It can be loaded with the line:
require 'gui'When the GUI API is initialised for the first time, it will construct a set of constants that are particular to the user's environment. Some values may be adjustable by the user directly, while others may be inherited by the user's choice of theme.
To give you a direct insight into the variables in the gui table, the following is cut straight from the API code:
gui.fonts = {
-- Use percentages for scalable sizes, where 100% is equivalent to the value of gui.interface.fontSize
default = { face='Noto Sans,Source Sans Pro', size='100%' },
window = { face='Noto Sans,Source Sans Pro', size='100%' }, -- For text that is not inside a widget
button = { face='Noto Sans,Source Sans Pro', size='100%' }, -- Text inside buttons
icon = { face='Noto Sans,Source Sans Pro', size='100%' }, -- Text at the bottom of icons
menu = { face='Noto Sans,Source Sans Pro', size='100%' }, -- Menu item text
titlebar = { face='Noto Sans', size='100%' }, -- Window titlebar text
small = { face='Tiny', size='60%' }, -- Recommended text for small sizes
large = { face='Noto Sans,Source Sans Pro', size='130%' }, -- Recommended text for headers
widget = { face='Noto Sans,Source Sans Pro', size='100%' }, -- Text inside widgets (e.g. combobox)
label = { face='Noto Sans,Source Sans Pro::bold', size='100%' } -- Text for labels and outside widgets
}
gui.style = {
-- All colour values are fills, so gradient and pattern references are also permitted for 'colours'.
page = {
bkgd = gui.palette.bkgd, -- Background for hosting text & paper-based layouts
stroke = gui.palette.prime, -- Border stroke for any area surrounding 'bkgd'
strokeFocus = gui.palette.contrast, -- Stroke to use when 'border' has the user's focus
strokeWidth = 2,
text = gui.palette.text, -- Default colour for text drawn over 'bkgd'
icon = nil, -- Default icon theme for icons drawn over 'bkgd'
textHighlight = gui.palette.altText, -- Colour for 'text' during user hover
textHighlightBkgd = gui.palette.prime, -- Background fill for 'text' during user hover
iconHighlight = nil, -- Recommended icon theme when highlighted
textSelect = gui.palette.altText, -- Colour for 'text' when selected
textSelectBkgd = gui.palette.contrast, -- Background fill for 'text' when selected
iconSelect = nil -- Recommended icon theme when selected
},
widget = {
text = gui.palette.altText,
bkgd = gui.palette.prime,
stroke = 'rgb(255,255,255,60)',
strokeFocus = 'rgb(255,255,255,160)',
strokeDisabled = 'rgb(255,255,255,60)',
strokeWidth = 2,
width = 160, -- Default width for common widgets (px)
gap = 6, -- Recommended gap between widgets (px)
margin = 6 -- Recommended internal margin for widgets (px)
},
window = {
bkgd = gui.palette.neutral,
text = 'rgb(0,0,0)' -- Colour for text that is drawn directly to the window
},
button = {
bkgd = gui.palette.invBkgd, -- Default background
bkgdActive = gui.palette.contrast -- Background when temporarily clicked (depressed)
},
menubar = {
bkgd = gui.palette.invBkgd,
text = gui.palette.altText,
highlight = gui.palette.contrast
},
menu = {
bkgd = gui.palette.bkgd,
border = 'rgb(200,200,200)' -- Stroke for menu border
},
desktop = {
bkgd = 'rgb(160,160,160)'
}
}
gui.iconThemes = {
default = { first={ r=90,g=90,b=90 }, last={ r=70,g=70,b=110 } },
carbon = { first={ r=90,g=90,b=90 }, last={ r=70,g=70,b=110 } },
yellow = { first={ r=0xec,g=0xef,b=0x9e }, last={ r=0xd6,g=0x87,b=0x10 }, stroke={ r=60, g=30, b=30, a=90 } },
orange = { first={ r=0xFD,g=0xC8,b=0x30 }, last={ r=0xF3,g=0x73,b=0x35 } },
blue = { first={ r=0x4b,g=0x6c,b=0xb7 }, last={ r=0x18,g=0x28,b=0x48 } },
ocean = { first={ r=0xA8,g=0xC0,b=0xFF }, last={ r=0x3F,g=0x2B,b=0x96 } },
green = { first={ r=0x7e,g=0x9d,b=0x13 }, last={ r=0x00,g=0x65,b=0x32 } },
red = { first={ r=0xf5,g=0xaf,b=0x19 }, last={ r=0xf1,g=0x27,b=0x11 } },
indigo = { first={ r=0xad,g=0x53,b=0x89 }, last={ r=0x3c,g=0x10,b=0x53 } },
rose = { first={ r=0xff,g=0xc3,b=0xa0 }, last={ r=0xFF,g=0xAF,b=0xBD } },
pink = { first={ r=0xff,g=0xdd,b=0xe1 }, last={ r=0xee,g=0x9c,b=0xa7 } },
grey = { first={ r=100,g=100,b=100 }, last={ r=70,g=70,b=70 } },
pearl = { first={ r=250,g=249,b=248 }, last={ r=210,g=211,b=212 } }
}
gui.applyFill(Vector, Fill)
Apply Fill to every fill attribute for Vector, its siblings and children, except in cases where the fill is already set to none. If a vector has a stroke defined, that is also changed to match Fill.
Info = gui.createIcon(Scene, Path, Size, Theme, [Name])
Build an icon sourced from Path, styled with the given Theme, and register it as a VectorPattern under Name. The Size is applied to the VectorPattern's PageWidth and PageHeight values, and affects the size of the pre-rendered bitmap cache. If Name is not given, the Path is used to name the pattern.
The generated pattern can be used as a fill, i.e. url(#Name). The pattern can be used in two ways: As a fill in a VectorRectangle, which is akin to a cached bitmap (fast); or applied to a VectorViewport for live rendering (higher quality transforms).
If the function succeeds, a table is returned that contains values for name, theme, size, path and fill. Use fill to set the Fill vector field wherever the icon is to be used.
This function is designed to throw an exception if an error occurs.
gui.forVector(Vector, Function)
Call Function for each vector in a tree under the provided Vector.
The synopsis for Function is Function(Vector) where Vector is a direct obj reference to the new vector that has been discovered.
LineSpacing, Height = gui.getFontHeight({ face='Face', size=PointSize })
Returns the line spacing and height values for a given font, which is identified by face and size values.
gui.pixel(Value)
Reads a style value such as 60pt and returns it as a number of pixel units. Supported units are px, in, mm, pt and dp.
gui.simpleGradient(Scene, Name, Colours, X1, Y1, X2, Y2, [Units], [IgnoreClashes])
Generate a simple linear gradient fill for vectors belonging to Scene. The fill will start at (X1,Y1) and stop at (X2,Y2). The Units will default to boundingbox if not set to userspace. The resulting fill can be referenced as url(#Name).
The Colours table must consist of at least two RGB table entries, for instance { { r=176,g=178,b=183,a=255 }, { r=212,g=211,b=215,a=255 } }. The colour stops will be evenly distributed through the gradient if there are more than two.
RGB = gui.hsvToRGB(HSV)
Convert an HSV table to RGB.
RGB = gui.interpolateRGB(RGB1, RGB2, [Ratio])
Interpolate two RGB colours, returning a new RGB table. Ratio is a value between 0.0 and 1.0 that determines the strength of RGB2 over RGB1.
HSV = gui.interpolateHSV(HSV1, HSV2, [Ratio])
Interpolate two HSV colours, returning a new HSV table. Ratio is a value between 0.0 and 1.0 that determines the strength of RGB2 over RGB1.
svgColour = gui.rgbToSVG(RGB)
Convert an RGB table to a SVG colour string in the format rgb(r,g,b,a).
gui.strToRGB(Value)
Convert an RGB string to an RGB table. Value can be in the format #RRGGBBAA
V = gui.rgbValue(RGB)
Returns the light value of an RGB colour (i.e. the V in HSV)
HSV = gui.rgbToHSV(RGB)
Convert an RGB table to HSV table.