livecode/extensions/modules/widget-utils/widget-utils.lcb at develop · livecode/livecode

This repository was archived by the owner on Aug 31, 2021. It is now read-only.
388 lines (300 loc) · 20.5 KB
Copyright (C) 2015 LiveCode Ltd.
This file is part of LiveCode.
LiveCode is free software; you can redistribute it and/or modify it under
the terms of the GNU General Public License v3 as published by the Free
Software Foundation.
LiveCode is distributed in the hope that it will be useful, but WITHOUT ANY
WARRANTY; without even the implied warranty of MERCHANTABILITY or
FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
for more details.
You should have received a copy of the GNU General Public License
along with LiveCode.  If not see <http://www.gnu.org/licenses/>.  */
A library of utility handlers for functions commonly needed by widgets.
module com.livecode.library.widgetutils
use com.livecode.canvas
use com.livecode.engine
metadata version is "1.0.0"
metadata author is "LiveCode"
metadata title is "Widget Utilities"
Summary: Scales and translates a path to fit within a rectangle
Parameters:
pTargetRect: The rectangle to fit the path within
xPath: The path to transform
use com.livecode.library.iconsvg
public handler OnPaint() returns nothing
	-- get the 'shopping cart' icon from the icon library
	variable tPathString as String
 	put iconSVGPathFromName("shopping cart") into tPathString
	-- create the path
	variable tPath as Path
	put path tPathString into tPath
	-- scale the path to fit within the bounds of the widget
	constrainPathToRect(my bounds, tPath)
	-- fill the path
	fill tPath on this canvas
end handler
Description:
Scales and transforms <xPath> so that it fits within <pTargetRect> whilst maintaining its
aspect ratio.
public handler constrainPathToRect(in pTargetRect as Rectangle, inout xPath as Path)
	// Scale the icon
	variable tBounds
	put the bounding box of xPath into tBounds
	// Scale appropriately
	variable tXScale as Real
	variable tYScale as Real
	put the width of pTargetRect / the width of tBounds into tXScale
	put the height of pTargetRect / the height of tBounds into tYScale
	if tXScale > tYScale then
		put tYScale into tXScale
		put tXScale into tYScale
    scale xPath by [tXScale, tYScale]
	variable tXTranslate as Real
	variable tYTranslate as Real
    put the bounding box of xPath into tBounds
	put the left of pTargetRect - the left of tBounds into tXTranslate
	put the top of pTargetRect - the top of tBounds into tYTranslate
    variable tXDiff as Real
    variable tYDiff as Real
    put the width of pTargetRect - the width of tBounds into tXDiff
    put the height of pTargetRect - the height of tBounds into tYDiff
	// align center
	divide tXDiff by 2
	divide tYDiff by 2
	translate xPath by [tXTranslate + tXDiff, tYTranslate + tYDiff]
end handler
Summary: Formats an integer as a string
Parameters:
pNumber: The integer to format
log 5 formatted as string 			-- logs 5.000000
log intToString(5)						 -- logs 5
Description:
<intToString> formats an integer as a string, removing the decimal place and any zeros
thereafter.
public handler intToString(in pNumber as Number) returns String
	variable tFormatted as String
	put pNumber formatted as string into tFormatted
	variable tDotIndex as Number
	put the index of "." in tFormatted into tDotIndex
	if tDotIndex is 0 then
		return tFormatted
	return char 1 to tDotIndex - 1 of tFormatted
end handler 
Summary: Removes any superfluous zeros and decimal places.
Parameters:
pString: The string to remove zeros from
log stripZeros("5.0000000")			-- logs 5
log stripZeros("5.432100")			-- logs 5.4321
Description:
Use <stripZeros> to remove any superfluous zeros and decimal places from <pString>
which have been added by the 
`tNumber formatted as string`
public handler stripZeros(in pString as String) returns String
   if "." is in pString then
		repeat while ((the last char of pString) is in ".0")
	      if the last char of pString is "." then
	         delete the last char of pString
	         exit repeat
	      else
	         delete the last char of pString
	      end if
	   end repeat
   return pString
end handler
private handler colorComponentToString(in pComponent as Number)
	return intToString(the rounded of (pComponent * 255))	
end handler
Summary: Converts a color to a string representing the color
Parameters:
pColor: A value of type com.livecode.canvas.Color
pIncludeAlpha: Whether to include the alpha value in the string or not
property widgetColor 	get getColor
metadata widgetColor.editor is "com.livecode.pi.colorwithalpha"
private variable mColor as Color
public handler OnSave(out rProperties as Array)
	put colorToString(mColor, true) into rProperties["color with alpha"]
end handler
public handler getColor() returns String
	-- the editor used for the widgetColor property expects the alpha value to be included
	return colorToString(mColor, true)
end handler
log colorToString(color [0.4,0.4,0.4,0.4])			-- logs "102,102,102,102"
Description:
Use the <colorToString> handler when logging colors, returning them to LiveCode script 
via a property getter, or serialising them in the widget's stored properties array for saving.
public handler colorToString(in pColor as Color, in pIncludeAlpha as Boolean) returns String
	variable tComponents as List
	variable tString as String
	put [] into tComponents
	push colorComponentToString(the red of pColor) onto tComponents
	push colorComponentToString(the green of pColor) onto tComponents
	push colorComponentToString(the blue of pColor) onto tComponents
	if pIncludeAlpha then
		push colorComponentToString(the alpha of pColor) onto tComponents
	combine tComponents with "," into tString
	return tString
end handler
private handler stringToColorComponent(in pComponent as String)
	return (pComponent parsed as number) / 255
end handler
Summary: Converts a string to a color
Parameters:
pString: A comma delimited string representing a color in RGB / RGBA format
property widgetColor 	get getColor	set setColor
metadata widgetColor.editor is "com.livecode.pi.colorwithalpha"
private variable mColor as Color
public handler OnLoad(in pProperties as Array)
	setColor(pProperties["color"])
end handler
public handler setColor(in pColor as String)
	put stringToColor(pColor) into mColor
	redraw all
end handler
Description:
Use the <stringToColor> handler when receiving colors from LiveCode script 
via a property setter, or from the widget's stored properties array when loading.
public handler stringToColor(in pString as String) returns Color
	variable tComponentList as List
	split pString by "," into tComponentList
	variable tColor as List
	put [] into tColor
	variable tColorComponent as String
	repeat for each element tColorComponent in tComponentList
		push stringToColorComponent(tColorComponent) onto tColor
	end repeat
	return color tColor
end handler
Summary: Get the canonical name of the current "native" mobile theme
	variable tNativeTheme as String
	put getNativeThemeName() into tNativeTheme
	if tNativeTheme is "android" then
		-- Draw Android themed UI
		-- Draw iOS themed UI
Description:
Returns the name of the current theme that should be used when the theme is
Currently, this will return either "iOS" or "Android".
public handler getNativeThemeName() returns String
	variable tOS as String
	put the operating system into tOS
	if tOS is in ["ios","mac"] then
		return "iOS"
		return "Android"
end handler
constant kWidgetUtilsPlaceholderIcons is { \
	"mac": "M14.926,0.656H1.067C0.478,0.656,0,1.137,0,1.73v9.844c0,0.594,0.478,1.074,1.067,1.074h5.316 c0,0-0.934,2.149-3.493,2.149v0.537h1.88h4.568h3.493v-0.537c-2.631,0-3.226-2.149-3.226-2.149h5.32 c0.588,0,1.065-0.48,1.065-1.074V1.73C15.992,1.137,15.514,0.656,14.926,0.656z M7.996,12.427c-0.331,0-0.599-0.268-0.599-0.599 c0-0.33,0.268-0.598,0.599-0.598c0.33,0,0.599,0.268,0.599,0.598C8.594,12.159,8.326,12.427,7.996,12.427z M14.849,10.906H1.143 V1.798H14.85L14.849,10.906L14.849,10.906zM6.824,9.133c0.393-0.016,0.542-0.255,1.017-0.255c0.476,0,0.609,0.255,1.024,0.247 C9.288,9.117,9.556,8.74,9.814,8.363c0.3-0.438,0.423-0.862,0.431-0.883c-0.01-0.005-0.824-0.317-0.833-1.255 c-0.008-0.786,0.642-1.163,0.67-1.182C9.718,4.51,9.149,4.437,8.947,4.429C8.465,4.38,8.005,4.713,7.759,4.713 c-0.244,0-0.623-0.277-1.023-0.27C6.209,4.451,5.724,4.75,5.452,5.221c-0.547,0.95-0.14,2.356,0.393,3.127 C6.105,8.725,6.416,9.148,6.824,9.133z M8.953,2.928c-0.312,0.013-0.689,0.208-0.914,0.47c-0.2,0.233-0.376,0.604-0.329,0.96 c0.349,0.027,0.704-0.177,0.921-0.439C8.847,3.656,8.993,3.292,8.953,2.928z", \
	"ios": "M4.621 6.965c0 1.368-.833 2.38-2.262 2.38-1.19 0-2.083-1.012-2.083-2.38 0-1.31.952-2.381 2.202-2.381 1.31 0 2.143 1.071 2.143 2.381zM1.327 78.5V23.78H3.57V78.5H1.327zM78.174 39.512c0 27.588-15.315 40.129-32.079 40.129-17.125 0-30.993-13.565-30.993-38.988C15.102 14.549 29.453.526 47.301.526 64.787.524 78.174 14.318 78.174 39.512zm-60.799.57C17.375 61 27.513 77.25 46.201 77.25c18.818 0 29.611-16.75 29.611-37.406 0-19.155-8.648-36.636-28.382-36.636S17.375 19.667 17.375 40.082zM86.406 72.571c3.763 2.508 10.258 4.93 15.844 4.93 10.602 0 20.031-7.417 20.031-18.334 0-10.131-6.281-15.417-16.945-19.958-9.544-4.064-18.125-8.475-18.125-19.305 0-11.285 8.891-19.267 20.975-19.267 6.498 0 11.4 1.824 13.68 3.42l-.906 1.968c-1.938-1.367-7.176-3.109-12.874-3.109-12.771 0-18.334 9.65-18.334 16.754 0 9.812 7.606 13.093 17.41 17.767 11.399 5.585 17.44 10.51 17.44 21.227 0 11.514-8.207 20.86-22.799 20.86-6.043 0-12.996-2.051-16.416-4.674l1.019-2.279z", \
Summary: Returns a placeholder icon for a given operating system
Parameters:
pOS (enum): The operating system.
- "android"
- "windows"
- "emscripten"
Description: Use <placeholderIcon> to fetch an SVG icon that can be
used as the placeholder image for a widget that is native to, and
therefore only available on, a given operating system.
public handler placeholderIcon(in pOS as String) returns String
    if pOS is not among the keys of kWidgetUtilsPlaceholderIcons then
        throw "no placeholder icon for" && pOS && "operating system"
	return kWidgetUtilsPlaceholderIcons[pOS]
end handler
Summary: Paint a placeholder image using an SVG icon and name
Parameters:
pCanvas: The canvas on which to draw the placeholder
pBounds: The rectangle in which to draw the placeholder on the canvas
pSVGIcon: The placeholder icon to use
pLabel: The label to use
pFont: A font to draw the label with. If none specified, Arial 14pt is used.
pColor: A color to draw the label with. If none specified, #404040 is used
Description:
Use the <paintPlaceHolder> image handler to draw a placeholder on the 
given canvas when, for example, the widget shouldn't be displayed as 
active in browse mode, or is not available on the current platform.
constant kBorderWidth is 5
public handler paintPlaceholderImage(in pCanvas as Canvas, in pBounds as Rectangle, \
    in pSVGIcon as String, in pLabel as String, in pFont as optional Font, \
    in pColor as optional Color)
    save state of pCanvas
	// Draw placeholder image - the browser icon
	variable tFillPaint as Paint
	variable tStrokePaint as Paint
	put solid paint with color [0.875, 0.875, 0.875] into tFillPaint
	put solid paint with color [0.75, 0.75, 0.75] into tStrokePaint
	set the paint of pCanvas to tFillPaint
	fill rectangle path of pBounds on this canvas
	set the paint of this canvas to tStrokePaint
	set the stroke width of this canvas to kBorderWidth
	set the join style of this canvas to "bevel"
	stroke rectangle path of expandRectangle(pBounds, -kBorderWidth / 2) on this canvas
	variable tPath as Path
	put path pSVGIcon into tPath
	constrainPathToRect(expandRectangle(pBounds, -2 * kBorderWidth), tPath)
	fill tPath on this canvas
	// Draw the control name
	put solid paint with color [1, 1, 1] into tFillPaint
    if pFont is nothing then
       put font "Arial" at size 14 into pFont
    if pColor is nothing then
       put color [0.25, 0.25, 0.25] into pColor
	put solid paint with pColor into tStrokePaint
	variable tTextBounds as Rectangle
	put the image bounds of text pLabel on pCanvas into tTextBounds
	translate pCanvas by [ the width of pBounds / 2, the height of pBounds / 2]
	translate pCanvas by [ -(the width of tTextBounds / 2), the height of tTextBounds / 2]
	set the paint of pCanvas to tFillPaint
	fill rounded rectangle path of expandRectangle(tTextBounds, kBorderWidth) with radius 5 on pCanvas
	set the paint of pCanvas to tStrokePaint
	fill text pLabel at point [0, 0] on pCanvas
	restore state of pCanvas
end handler
private handler expandRectangle(in pRect as Rectangle, in pExp as Number) returns Rectangle
	return rectangle [ the left of pRect - pExp, the top of pRect - pExp, the right of pRect + pExp, the bottom of pRect + pExp]
end handler
Navigation Menu

Uh oh!

Uh oh!

FilesExpand file tree

widget-utils.lcb

Latest commit

History

widget-utils.lcb

File metadata and controls
