/*

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

Example:

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

else

put tXScale into tYScale

end if

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

Example:

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

end if

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

Example:

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`

syntax.

*/

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

end if

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

Example:

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

Example:

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

end if

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

Example:

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

Example:

variable tNativeTheme as String

put getNativeThemeName() into tNativeTheme

if tNativeTheme is "android" then

-- Draw Android themed UI

else

-- Draw iOS themed UI

end if

Description:

Returns the name of the current theme that should be used when the theme is

"native".

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"

else

return "Android"

end if

end handler

constant kMacPlaceholderSvgIcon is "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"

constant kIosPlaceholderSvgIcon is "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"

constant kAndroidPlaceholderSvgIcon is "M493 615Q509 615 520.5 603.5 532 592 532 576 532 560 520.5 548.5 509 537 493 537 477 537 466 548.5 455 560 455 576 455 592 466 603.5 477 615 493 615ZM915 615Q931 615 942 603.5 953 592 953 576 953 560 942 548.5 931 537 915 537 899 537 887.5 548.5 876 560 876 576 876 592 887.5 603.5 899 615 915 615ZM103 799Q145 799 175 829 205 859 205 901L205 1331Q205 1374 175.5 1404 146 1434 103 1434 60 1434 30 1404 0 1374 0 1331L0 901Q0 859 30 829 60 799 103 799ZM1163 818L1163 1484Q1163 1530 1131 1562 1099 1594 1054 1594L979 1594 979 1821Q979 1864 949 1894 919 1924 876 1924 833 1924 803 1894 773 1864 773 1821L773 1594 635 1594 635 1821Q635 1864 605 1894 575 1924 532 1924 490 1924 460 1894 430 1864 430 1821L429 1594 355 1594Q309 1594 277 1562 245 1530 245 1484L245 818 1163 818ZM931 413Q1038 468 1102 566.5 1166 665 1166 782L241 782Q241 665 305 566.5 369 468 477 413L406 282Q399 269 411 262 424 256 431 268L503 400Q598 358 704 358 810 358 905 400L977 268Q984 256 997 262 1009 269 1002 282ZM1408 901L1408 1331Q1408 1374 1378 1404 1348 1434 1305 1434 1263 1434 1233 1404 1203 1374 1203 1331L1203 901Q1203 858 1233 828.5 1263 799 1305 799 1348 799 1378 828.5 1408 858 1408 901Z"

/**

Summary: Returns a placeholder icon for a given operating system

Parameters:

pOS (enum): The operating system.

- "mac"

- "ios"

- "android"

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 "mac" then

return kMacPlaceholderSvgIcon

else if pOS is "ios" then

return kIosPlaceholderSvgIcon

else if pOS is "android" then

return kAndroidPlaceholderSvgIcon

else

throw "no placeholder icon for" && pOS && "operating system"

end if

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

end if

if pColor is nothing then

put color [0.25, 0.25, 0.25] into pColor

end if

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

end module