From 0f67aa51ceacf7331be4d3f053bed9fae113e222 Mon Sep 17 00:00:00 2001 From: Kevin Harrison Date: Fri, 14 Dec 2018 15:10:58 -0500 Subject: [PATCH] Update for v2.1 --- Documentation.md | 280 ++++++++++++++++++++++++----------------------- 1 file changed, 144 insertions(+), 136 deletions(-) diff --git a/Documentation.md b/Documentation.md index ecfdde3..454620b 100644 --- a/Documentation.md +++ b/Documentation.md @@ -274,9 +274,9 @@ End a group. Remember to call this whenever the group is open. ### Trees #### open = ui:treePush('node'/'tab', title) -#### open = ui:treePush('node'/'tab', title, image) -#### open = ui:treePush('node'/'tab', title, image, 'collapsed'/'expanded') -Start a tree. The resulting item is either a `'node'` or a `'tab'`, with the idea being that nodes are a level below tabs. Optionally specify an image (default is none) or a starting state (default is `'collapsed'`). +#### open = ui:treePush('node'/'tab', title, [image](#images)) +#### open = ui:treePush('node'/'tab', title, [image](#images), 'collapsed'/'expanded') +Start a tree. The resulting item is either a `'node'` or a `'tab'`, with the idea being that nodes are a level below tabs. Optionally specify an [image](#images) (default is none) or a starting state (default is `'collapsed'`). Return `true` if the item is expanded, and `false` if it is collapsed. @@ -308,9 +308,9 @@ Set up a context menu of the given size and trigger bounds. Also takes window [f Return `true` if the context menu is open, and `false` otherwise. #### activated = ui:contextualItem(text) -#### activated = ui:contextualItem(text, [symbol](#symbols)/image) -#### activated = ui:contextualItem(text, [symbol](#symbols)/image, [align](#alignment)) -Add an item to a context menu. Optionally specify a [symbol](#symbols) type, image, and/or [alignment](#alignment). +#### activated = ui:contextualItem(text, [symbol](#symbols)/[image](#images)) +#### activated = ui:contextualItem(text, [symbol](#symbols)/[image](#images), [align](#alignment)) +Add an item to a context menu. Optionally specify a [symbol](#symbols) type, [image](#images), and/or [alignment](#alignment). Return `true` if the item is activated, and `false` otherwise. @@ -345,18 +345,18 @@ Start a menu bar. Menu bars stay at the top of a window even when scrolling. Cal #### ui:menubarEnd() Ends a menu bar. Always call this at the end of a menu bar started with `ui:menubarBegin`. -#### open = ui:menuBegin(title, [symbol](#symbols)/image, width, height) -#### open = ui:menuBegin(title, [symbol](#symbols)/image, width, height, [align](#alignment)) -Start a menu of the given title and size. Optionally specify a [symbol](#symbols), image, and/or [alignment](#alignment). +#### open = ui:menuBegin(title, [symbol](#symbols)/[image](#images), width, height) +#### open = ui:menuBegin(title, [symbol](#symbols)/[image](#images), width, height, [align](#alignment)) +Start a menu of the given title and size. Optionally specify a [symbol](#symbols), [image](#images), and/or [alignment](#alignment). Return `true` if the menu is open, and `false` otherwise. Be sure to call `ui:menuEnd` when ending open menus. #### activated = ui:menuItem(title) -#### activated = ui:menuItem(title, [symbol](#symbols)/image) -#### activated = ui:menuItem(title, [symbol](#symbols)/image, [align](#alignment)) -Add a menu item to the current menu. Optionally specify a [symbol](#symbols), image, and/or [alignment](#alignment). +#### activated = ui:menuItem(title, [symbol](#symbols)/[image](#images)) +#### activated = ui:menuItem(title, [symbol](#symbols)/[image](#images), [align](#alignment)) +Add a menu item to the current menu. Optionally specify a [symbol](#symbols), [image](#images), and/or [alignment](#alignment). Return `true` if the menu item is activated, and `false` otherwise. @@ -373,15 +373,15 @@ End the current menu. Always call this at the end of any open menu. #### ui:label(text, [align](#alignment)/'wrap', [color](#colors)) Show a text string. Optionally specify an [alignment](#alignment) and/or [color](#colors). -#### ui:image(img) -Show an image. +#### ui:image([image](#images)) +Show an [image](#images). See [LÖVE Image](https://love2d.org/wiki/Image). #### activated = ui:button(title) -#### activated = ui:button(title, [symbol](#symbols)/image) +#### activated = ui:button(title, [symbol](#symbols)/[image](#images)) #### activated = ui:button(nil, [color](#colors)) -Add a button with a title and/or a [color](#colors), [symbol](#symbols), or image. +Add a button with a title and/or a [color](#colors), [symbol](#symbols), or [image](#images). Return `true` if activated, and `false` otherwise. @@ -407,12 +407,12 @@ Add a radio button with the given name and/or title. The title is displayed to t If called with a string `selection`, the function returns the new `selection`, which should be the `name` of a radio button. If called with a table that has a string field `value`, the `value` gets updated and the function returns `true` on selection change and `false` otherwise. #### selected = ui:selectable(text, selected) -#### selected = ui:selectable(text, image, selected) -#### selected = ui:selectable(text, image, [align](#alignment), selected) +#### selected = ui:selectable(text, [image](#images), selected) +#### selected = ui:selectable(text, [image](#images), [align](#alignment), selected) #### changed = ui:selectable(text, valueTable) -#### changed = ui:selectable(text, image, valueTable) -#### changed = ui:selectable(text, image, [align](#alignment), valueTable) -Add a selectable item with the given text and/or image and [alignment](#alignment). +#### changed = ui:selectable(text, [image](#images), valueTable) +#### changed = ui:selectable(text, [image](#images), [align](#alignment), valueTable) +Add a selectable item with the given text and/or [image](#images) and [alignment](#alignment). If given a boolean `selected`, return the new state of `selected`. If given a table with a boolean field named `value` instead, the field gets updated and the function returns `true` on a change and `false` otherwise. @@ -460,17 +460,17 @@ Add a drop-down combobox widget. `items` should be an array of strings. `itemHei If a number `index` is specified, then the function returns the new selected `index`. If a table with a number field `value` is given instead, then the field gets updated with the currently selected index and the function returns `true` on change and `false` otherwise. #### open = ui:comboboxBegin(text) -#### open = ui:comboboxBegin(text, [color](#colors)/[symbol](#symbols)/image) -#### open = ui:comboboxBegin(text, [color](#colors)/[symbol](#symbols)/image, width) -#### open = ui:comboboxBegin(text, [color](#colors)/[symbol](#symbols)/image, width, height) -Start a combobox widget. This form gives complete control over the drop-down list (it's treated like a new window). [Color](#colors)/[symbol](#symbols)/image defaults to none, while width and height default to sensible values based on widget bounds. +#### open = ui:comboboxBegin(text, [color](#colors)/[symbol](#symbols)/[image](#images)) +#### open = ui:comboboxBegin(text, [color](#colors)/[symbol](#symbols)/[image](#images), width) +#### open = ui:comboboxBegin(text, [color](#colors)/[symbol](#symbols)/[image](#images), width, height) +Start a combobox widget. This form gives complete control over the drop-down list (it's treated like a new window). [Color](#colors)/[symbol](#symbols)/[image](#images) defaults to none, while width and height default to sensible values based on widget bounds. Remember to call `ui:comboboxEnd` if the combobox is open. #### activated = ui:comboboxItem(text) -#### activated = ui:comboboxItem(text, [symbol](#symbols)/image) -#### activated = ui:comboboxItem(text, [symbol](#symbols)/image, [align](#alignment)) -Add a combobox item, optionally specifying a [symbol](#symbols), image, and/or [alignment](#alignment). +#### activated = ui:comboboxItem(text, [symbol](#symbols)/[image](#images)) +#### activated = ui:comboboxItem(text, [symbol](#symbols)/[image](#images), [align](#alignment)) +Add a combobox item, optionally specifying a [symbol](#symbols), [image](#images), and/or [alignment](#alignment). Return `true` if the item is activated, and `false` otherwise. @@ -578,7 +578,7 @@ Draw a gradient rectangle with the given screen coordinates, size, and corner co Set the scissor area to the given screen coordinates and size. #### ui:image(img, x, y, width, height) -Draw the given image at the given screen bounds. +Draw the given [image](#images) at the given screen bounds. See [LÖVE Image](https://love2d.org/wiki/Image). @@ -587,6 +587,14 @@ Draw the given string at the given screen bounds. *** +## Images + +Any function that accepts a [LÖVE Image](https://love2d.org/wiki/Image) as an argument also accepts a two-item array `{Image, Quad}` where `Quad` is a [LÖVE Quad](https://love2d.org/wiki/Quad) determining what part of the image to draw. + +See [skin.lua](https://github.com/keharriso/love-nuklear/blob/master/example/skin.lua) for an example of both methods. + +*** + ## Input #### hovered = ui:inputWasHovered(x, y, width, height) @@ -710,9 +718,9 @@ local style = { ['padding'] = {x = number, y = number} }, ['button'] = { - ['normal'] = color or Image, - ['hover'] = color or Image, - ['active'] = color or Image, + ['normal'] = color or Image or {Image, Quad}, + ['hover'] = color or Image or {Image, Quad}, + ['active'] = color or Image or {Image, Quad}, ['border color'] = color, ['text background'] = color, ['text normal'] = color, @@ -726,9 +734,9 @@ local style = { ['touch padding'] = {x = number, y = number} }, ['contextual button'] = { - ['normal'] = color or Image, - ['hover'] = color or Image, - ['active'] = color or Image, + ['normal'] = color or Image or {Image, Quad}, + ['hover'] = color or Image or {Image, Quad}, + ['active'] = color or Image or {Image, Quad}, ['border color'] = color, ['text background'] = color, ['text normal'] = color, @@ -742,9 +750,9 @@ local style = { ['touch padding'] = {x = number, y = number} }, ['menu button'] = { - ['normal'] = color or Image, - ['hover'] = color or Image, - ['active'] = color or Image, + ['normal'] = color or Image or {Image, Quad}, + ['hover'] = color or Image or {Image, Quad}, + ['active'] = color or Image or {Image, Quad}, ['border color'] = color, ['text background'] = color, ['text normal'] = color, @@ -758,12 +766,12 @@ local style = { ['touch padding'] = {x = number, y = number} }, ['option'] = { - ['normal'] = color or Image, - ['hover'] = color or Image, - ['active'] = color or Image, + ['normal'] = color or Image or {Image, Quad}, + ['hover'] = color or Image or {Image, Quad}, + ['active'] = color or Image or {Image, Quad}, ['border color'] = color, - ['cursor normal'] = color or Image, - ['cursor hover'] = color or Image, + ['cursor normal'] = color or Image or {Image, Quad}, + ['cursor hover'] = color or Image or {Image, Quad}, ['text normal'] = color, ['text hover'] = color, ['text active'] = color, @@ -775,12 +783,12 @@ local style = { ['border'] = number }, ['checkbox'] = { - ['normal'] = color or Image, - ['hover'] = color or Image, - ['active'] = color or Image, + ['normal'] = color or Image or {Image, Quad}, + ['hover'] = color or Image or {Image, Quad}, + ['active'] = color or Image or {Image, Quad}, ['border color'] = color, - ['cursor normal'] = color or Image, - ['cursor hover'] = color or Image, + ['cursor normal'] = color or Image or {Image, Quad}, + ['cursor hover'] = color or Image or {Image, Quad}, ['text normal'] = color, ['text hover'] = color, ['text active'] = color, @@ -792,12 +800,12 @@ local style = { ['border'] = number }, ['selectable'] = { - ['normal'] = color or Image, - ['hover'] = color or Image, - ['pressed'] = color or Image, - ['normal active'] = color or Image, - ['hover active'] = color or Image, - ['pressed active'] = color or Image, + ['normal'] = color or Image or {Image, Quad}, + ['hover'] = color or Image or {Image, Quad}, + ['pressed'] = color or Image or {Image, Quad}, + ['normal active'] = color or Image or {Image, Quad}, + ['hover active'] = color or Image or {Image, Quad}, + ['pressed active'] = color or Image or {Image, Quad}, ['text normal'] = color, ['text hover'] = color, ['text pressed'] = color, @@ -812,16 +820,16 @@ local style = { ['image padding'] = {x = number, y = number} }, ['slider'] = { - ['normal'] = color or Image, - ['hover'] = color or Image, - ['active'] = color or Image, + ['normal'] = color or Image or {Image, Quad}, + ['hover'] = color or Image or {Image, Quad}, + ['active'] = color or Image or {Image, Quad}, ['border color'] = color, ['bar normal'] = color, ['bar active'] = color, ['bar filled'] = color, - ['cursor normal'] = color or Image, - ['cursor hover'] = color or Image, - ['cursor active'] = color or Image, + ['cursor normal'] = color or Image or {Image, Quad}, + ['cursor hover'] = color or Image or {Image, Quad}, + ['cursor active'] = color or Image or {Image, Quad}, ['border'] = number, ['rounding'] = number, ['bar height'] = number, @@ -830,13 +838,13 @@ local style = { ['cursor size'] = {x = number, y = number} }, ['progress'] = { - ['normal'] = color or Image, - ['hover'] = color or Image, - ['active'] = color or Image, + ['normal'] = color or Image or {Image, Quad}, + ['hover'] = color or Image or {Image, Quad}, + ['active'] = color or Image or {Image, Quad}, ['border color'] = color, - ['cursor normal'] = color or Image, - ['cursor hover'] = color or Image, - ['cursor active'] = color or Image, + ['cursor normal'] = color or Image or {Image, Quad}, + ['cursor hover'] = color or Image or {Image, Quad}, + ['cursor active'] = color or Image or {Image, Quad}, ['cursor border color'] = color, ['rounding'] = number, ['border'] = number, @@ -845,9 +853,9 @@ local style = { ['padding'] = {x = number, y = number} }, ['property'] = { - ['normal'] = color or Image, - ['hover'] = color or Image, - ['active'] = color or Image, + ['normal'] = color or Image or {Image, Quad}, + ['hover'] = color or Image or {Image, Quad}, + ['active'] = color or Image or {Image, Quad}, ['border color'] = color, ['label normal'] = color, ['label hover'] = color, @@ -856,18 +864,18 @@ local style = { ['rounding'] = number, ['padding'] = {x = number, y = number}, ['edit'] = { - ['normal'] = color or Image, - ['hover'] = color or Image, - ['active'] = color or Image, + ['normal'] = color or Image or {Image, Quad}, + ['hover'] = color or Image or {Image, Quad}, + ['active'] = color or Image or {Image, Quad}, ['border color'] = color, ['scrollbar'] = { - ['normal'] = color or Image, - ['hover'] = color or Image, - ['active'] = color or Image, + ['normal'] = color or Image or {Image, Quad}, + ['hover'] = color or Image or {Image, Quad}, + ['active'] = color or Image or {Image, Quad}, ['border color'] = color, - ['cursor normal'] = color or Image, - ['cursor hover'] = color or Image, - ['cursor active'] = color or Image, + ['cursor normal'] = color or Image or {Image, Quad}, + ['cursor hover'] = color or Image or {Image, Quad}, + ['cursor active'] = color or Image or {Image, Quad}, ['cursor border color'] = color, ['border'] = number, ['rounding'] = number, @@ -894,9 +902,9 @@ local style = { ['row padding'] = number }, ['inc button'] = { - ['normal'] = color or Image, - ['hover'] = color or Image, - ['active'] = color or Image, + ['normal'] = color or Image or {Image, Quad}, + ['hover'] = color or Image or {Image, Quad}, + ['active'] = color or Image or {Image, Quad}, ['border color'] = color, ['text background'] = color, ['text normal'] = color, @@ -910,9 +918,9 @@ local style = { ['touch padding'] = {x = number, y = number} }, ['dec button'] = { - ['normal'] = color or Image, - ['hover'] = color or Image, - ['active'] = color or Image, + ['normal'] = color or Image or {Image, Quad}, + ['hover'] = color or Image or {Image, Quad}, + ['active'] = color or Image or {Image, Quad}, ['border color'] = color, ['text background'] = color, ['text normal'] = color, @@ -927,18 +935,18 @@ local style = { } }, ['edit'] = { - ['normal'] = color or Image, - ['hover'] = color or Image, - ['active'] = color or Image, + ['normal'] = color or Image or {Image, Quad}, + ['hover'] = color or Image or {Image, Quad}, + ['active'] = color or Image or {Image, Quad}, ['border color'] = color, ['scrollbar'] = { - ['normal'] = color or Image, - ['hover'] = color or Image, - ['active'] = color or Image, + ['normal'] = color or Image or {Image, Quad}, + ['hover'] = color or Image or {Image, Quad}, + ['active'] = color or Image or {Image, Quad}, ['border color'] = color, - ['cursor normal'] = color or Image, - ['cursor hover'] = color or Image, - ['cursor active'] = color or Image, + ['cursor normal'] = color or Image or {Image, Quad}, + ['cursor hover'] = color or Image or {Image, Quad}, + ['cursor active'] = color or Image or {Image, Quad}, ['cursor border color'] = color, ['border'] = number, ['rounding'] = number, @@ -965,7 +973,7 @@ local style = { ['row padding'] = number }, ['chart'] = { - ['background'] = color or Image, + ['background'] = color or Image or {Image, Quad}, ['border color'] = color, ['selected color'] = color, ['color'] = color, @@ -974,13 +982,13 @@ local style = { ['padding'] = {x = number, y = number} }, ['scrollh'] = { - ['normal'] = color or Image, - ['hover'] = color or Image, - ['active'] = color or Image, + ['normal'] = color or Image or {Image, Quad}, + ['hover'] = color or Image or {Image, Quad}, + ['active'] = color or Image or {Image, Quad}, ['border color'] = color, - ['cursor normal'] = color or Image, - ['cursor hover'] = color or Image, - ['cursor active'] = color or Image, + ['cursor normal'] = color or Image or {Image, Quad}, + ['cursor hover'] = color or Image or {Image, Quad}, + ['cursor active'] = color or Image or {Image, Quad}, ['cursor border color'] = color, ['border'] = number, ['rounding'] = number, @@ -989,13 +997,13 @@ local style = { ['padding'] = {x = number, y = number} }, ['scrollv'] = { - ['normal'] = color or Image, - ['hover'] = color or Image, - ['active'] = color or Image, + ['normal'] = color or Image or {Image, Quad}, + ['hover'] = color or Image or {Image, Quad}, + ['active'] = color or Image or {Image, Quad}, ['border color'] = color, - ['cursor normal'] = color or Image, - ['cursor hover'] = color or Image, - ['cursor active'] = color or Image, + ['cursor normal'] = color or Image or {Image, Quad}, + ['cursor hover'] = color or Image or {Image, Quad}, + ['cursor active'] = color or Image or {Image, Quad}, ['cursor border color'] = color, ['border'] = number, ['rounding'] = number, @@ -1004,13 +1012,13 @@ local style = { ['padding'] = {x = number, y = number} }, ['tab'] = { - ['background'] = color or Image, + ['background'] = color or Image or {Image, Quad}, ['border color'] = color, ['text'] = color, ['tab maximize button'] = { - ['normal'] = color or Image, - ['hover'] = color or Image, - ['active'] = color or Image, + ['normal'] = color or Image or {Image, Quad}, + ['hover'] = color or Image or {Image, Quad}, + ['active'] = color or Image or {Image, Quad}, ['border color'] = color, ['text background'] = color, ['text normal'] = color, @@ -1024,9 +1032,9 @@ local style = { ['touch padding'] = {x = number, y = number} }, ['tab minimize button'] = { - ['normal'] = color or Image, - ['hover'] = color or Image, - ['active'] = color or Image, + ['normal'] = color or Image or {Image, Quad}, + ['hover'] = color or Image or {Image, Quad}, + ['active'] = color or Image or {Image, Quad}, ['border color'] = color, ['text background'] = color, ['text normal'] = color, @@ -1040,9 +1048,9 @@ local style = { ['touch padding'] = {x = number, y = number} }, ['node maximize button'] = { - ['normal'] = color or Image, - ['hover'] = color or Image, - ['active'] = color or Image, + ['normal'] = color or Image or {Image, Quad}, + ['hover'] = color or Image or {Image, Quad}, + ['active'] = color or Image or {Image, Quad}, ['border color'] = color, ['text background'] = color, ['text normal'] = color, @@ -1056,9 +1064,9 @@ local style = { ['touch padding'] = {x = number, y = number} }, ['node minimize button'] = { - ['normal'] = color or Image, - ['hover'] = color or Image, - ['active'] = color or Image, + ['normal'] = color or Image or {Image, Quad}, + ['hover'] = color or Image or {Image, Quad}, + ['active'] = color or Image or {Image, Quad}, ['border color'] = color, ['text background'] = color, ['text normal'] = color, @@ -1078,9 +1086,9 @@ local style = { ['spacing'] = {x = number, y = number} }, ['combo'] = { - ['normal'] = color or Image, - ['hover'] = color or Image, - ['active'] = color or Image, + ['normal'] = color or Image or {Image, Quad}, + ['hover'] = color or Image or {Image, Quad}, + ['active'] = color or Image or {Image, Quad}, ['border color'] = color, ['label normal'] = color, ['label hover'] = color, @@ -1089,9 +1097,9 @@ local style = { ['symbol hover'] = color, ['symbol active'] = color, ['button'] = { - ['normal'] = color or Image, - ['hover'] = color or Image, - ['active'] = color or Image, + ['normal'] = color or Image or {Image, Quad}, + ['hover'] = color or Image or {Image, Quad}, + ['active'] = color or Image or {Image, Quad}, ['border color'] = color, ['text background'] = color, ['text normal'] = color, @@ -1112,13 +1120,13 @@ local style = { }, ['window'] = { ['header'] = { - ['normal'] = color or Image, - ['hover'] = color or Image, - ['active'] = color or Image, + ['normal'] = color or Image or {Image, Quad}, + ['hover'] = color or Image or {Image, Quad}, + ['active'] = color or Image or {Image, Quad}, ['close button'] = { - ['normal'] = color or Image, - ['hover'] = color or Image, - ['active'] = color or Image, + ['normal'] = color or Image or {Image, Quad}, + ['hover'] = color or Image or {Image, Quad}, + ['active'] = color or Image or {Image, Quad}, ['border color'] = color, ['text background'] = color, ['text normal'] = color, @@ -1132,9 +1140,9 @@ local style = { ['touch padding'] = {x = number, y = number} }, ['minimize button'] = { - ['normal'] = color or Image, - ['hover'] = color or Image, - ['active'] = color or Image, + ['normal'] = color or Image or {Image, Quad}, + ['hover'] = color or Image or {Image, Quad}, + ['active'] = color or Image or {Image, Quad}, ['border color'] = color, ['text background'] = color, ['text normal'] = color, @@ -1155,7 +1163,7 @@ local style = { ['spacing'] = {x = number, y = number}, }, - ['fixed background'] = color or Image, + ['fixed background'] = color or Image or {Image, Quad}, ['background'] = color, ['border color'] = color, ['popup border color'] = color, @@ -1164,7 +1172,7 @@ local style = { ['menu border color'] = color, ['group border color'] = color, ['tooltip border color'] = color, - ['scaler'] = color or Image, + ['scaler'] = color or Image or {Image, Quad}, ['border'] = number, ['combo border'] = number, ['contextual border'] = number,