From bb70ae9eafa44ca87075b328a9c08eb9455b7f87 Mon Sep 17 00:00:00 2001
From: Frans de Jonge <fransdejonge@gmail.com>
Date: Wed, 26 Apr 2017 16:21:36 +0200
Subject: [PATCH] Dev docs: some widgets

---
 .../ui/widget/container/alphacontainer.lua    | 23 ++++++++++---
 .../ui/widget/container/bottomcontainer.lua   |  9 ++---
 .../ui/widget/container/centercontainer.lua   |  7 ++--
 .../ui/widget/container/framecontainer.lua    | 24 ++++++++++---
 .../ui/widget/container/leftcontainer.lua     |  7 ++--
 .../ui/widget/container/rightcontainer.lua    |  7 ++--
 frontend/ui/widget/container/topcontainer.lua |  7 ++--
 .../widget/container/underlinecontainer.lua   | 15 ++++----
 frontend/ui/widget/iconbutton.lua             |  7 ++--
 frontend/ui/widget/imageviewer.lua            | 34 +++++++++----------
 frontend/ui/widget/linkbox.lua                | 10 +++---
 11 files changed, 94 insertions(+), 56 deletions(-)

diff --git a/frontend/ui/widget/container/alphacontainer.lua b/frontend/ui/widget/container/alphacontainer.lua
index 52ececcda..7c8a92556 100644
--- a/frontend/ui/widget/container/alphacontainer.lua
+++ b/frontend/ui/widget/container/alphacontainer.lua
@@ -1,10 +1,25 @@
-local WidgetContainer = require("ui/widget/container/widgetcontainer")
-local BlitBuffer = require("ffi/blitbuffer")
-
---[[
+--[[--
 AlphaContainer will paint its content (1 widget) onto lower levels using
 a transparency (0..1)
+
+Example:
+
+    local alpha
+    alpha = AlphaContainer:new{
+        alpha = 0.7,
+
+        FrameContainer:new{
+            background = Blitbuffer.COLOR_WHITE,
+            bordersize = 1,
+            margin = 0,
+            padding = 1
+        }
+    }
 --]]
+
+local BlitBuffer = require("ffi/blitbuffer")
+local WidgetContainer = require("ui/widget/container/widgetcontainer")
+
 local AlphaContainer = WidgetContainer:new{
     alpha = 1,
     -- we cache a blitbuffer object for re-use here:
diff --git a/frontend/ui/widget/container/bottomcontainer.lua b/frontend/ui/widget/container/bottomcontainer.lua
index 9bc4fede9..4ea2ee300 100644
--- a/frontend/ui/widget/container/bottomcontainer.lua
+++ b/frontend/ui/widget/container/bottomcontainer.lua
@@ -1,10 +1,11 @@
-local WidgetContainer = require("ui/widget/container/widgetcontainer")
-local Geom = require("ui/geometry")
-
---[[
+--[[--
 BottomContainer contains its content (1 widget) at the bottom of its own
 dimensions
 --]]
+
+local Geom = require("ui/geometry")
+local WidgetContainer = require("ui/widget/container/widgetcontainer")
+
 local BottomContainer = WidgetContainer:new()
 
 function BottomContainer:paintTo(bb, x, y)
diff --git a/frontend/ui/widget/container/centercontainer.lua b/frontend/ui/widget/container/centercontainer.lua
index 2b080b5f5..17fa887fb 100644
--- a/frontend/ui/widget/container/centercontainer.lua
+++ b/frontend/ui/widget/container/centercontainer.lua
@@ -1,8 +1,9 @@
-local WidgetContainer = require("ui/widget/container/widgetcontainer")
-
---[[
+--[[--
 CenterContainer centers its content (1 widget) within its own dimensions
 --]]
+
+local WidgetContainer = require("ui/widget/container/widgetcontainer")
+
 local CenterContainer = WidgetContainer:new()
 
 function CenterContainer:paintTo(bb, x, y)
diff --git a/frontend/ui/widget/container/framecontainer.lua b/frontend/ui/widget/container/framecontainer.lua
index 9e8540795..0a024429c 100644
--- a/frontend/ui/widget/container/framecontainer.lua
+++ b/frontend/ui/widget/container/framecontainer.lua
@@ -1,11 +1,27 @@
+--[[--
+A FrameContainer is some graphics content (1 widget) that is surrounded by a
+frame
+
+Example:
+
+    local frame
+    frame = FrameContainer:new{
+        radius = 8,
+        bordersize = 3,
+        padding = 0,
+        margin = 0,
+        background = Blitbuffer.COLOR_WHITE,
+        VerticalGroup:new{
+            -- etc
+        }
+    }
+
+--]]
+
 local WidgetContainer = require("ui/widget/container/widgetcontainer")
 local Geom = require("ui/geometry")
 local Blitbuffer = require("ffi/blitbuffer")
 
---[[
-A FrameContainer is some graphics content (1 widget) that is surrounded by a
-frame
---]]
 local FrameContainer = WidgetContainer:new{
     background = nil,
     color = Blitbuffer.COLOR_BLACK,
diff --git a/frontend/ui/widget/container/leftcontainer.lua b/frontend/ui/widget/container/leftcontainer.lua
index 8f4ac1e73..661201fed 100644
--- a/frontend/ui/widget/container/leftcontainer.lua
+++ b/frontend/ui/widget/container/leftcontainer.lua
@@ -1,8 +1,9 @@
-local WidgetContainer = require("ui/widget/container/widgetcontainer")
-
---[[
+--[[--
 LeftContainer aligns its content (1 widget) at the left of its own dimensions
 --]]
+
+local WidgetContainer = require("ui/widget/container/widgetcontainer")
+
 local LeftContainer = WidgetContainer:new()
 
 function LeftContainer:paintTo(bb, x, y)
diff --git a/frontend/ui/widget/container/rightcontainer.lua b/frontend/ui/widget/container/rightcontainer.lua
index b92948264..516d1d053 100644
--- a/frontend/ui/widget/container/rightcontainer.lua
+++ b/frontend/ui/widget/container/rightcontainer.lua
@@ -1,8 +1,9 @@
-local WidgetContainer = require("ui/widget/container/widgetcontainer")
-
---[[
+--[[--
 RightContainer aligns its content (1 widget) at the right of its own dimensions
 --]]
+
+local WidgetContainer = require("ui/widget/container/widgetcontainer")
+
 local RightContainer = WidgetContainer:new()
 
 function RightContainer:paintTo(bb, x, y)
diff --git a/frontend/ui/widget/container/topcontainer.lua b/frontend/ui/widget/container/topcontainer.lua
index 04177effb..ce5eab51c 100644
--- a/frontend/ui/widget/container/topcontainer.lua
+++ b/frontend/ui/widget/container/topcontainer.lua
@@ -1,8 +1,9 @@
-local WidgetContainer = require("ui/widget/container/widgetcontainer")
-
---[[
+--[[--
 TopContainer contains its content (1 widget) at the top of its own dimensions
 --]]
+
+local WidgetContainer = require("ui/widget/container/widgetcontainer")
+
 local TopContainer = WidgetContainer:new()
 
 return TopContainer
diff --git a/frontend/ui/widget/container/underlinecontainer.lua b/frontend/ui/widget/container/underlinecontainer.lua
index b806ad618..bb12abeb0 100644
--- a/frontend/ui/widget/container/underlinecontainer.lua
+++ b/frontend/ui/widget/container/underlinecontainer.lua
@@ -1,12 +1,13 @@
-local WidgetContainer = require("ui/widget/container/widgetcontainer")
-local Geom = require("ui/geometry")
-local Blitbuffer = require("ffi/blitbuffer")
-
---[[
-an UnderlineContainer is a WidgetContainer that is able to paint
-a line under its child node
+--[[--
+An UnderlineContainer is a WidgetContainer that is able to paint
+a line under its child node.
 --]]
 
+
+local Blitbuffer = require("ffi/blitbuffer")
+local Geom = require("ui/geometry")
+local WidgetContainer = require("ui/widget/container/widgetcontainer")
+
 local UnderlineContainer = WidgetContainer:new{
     linesize = 2,
     padding = 1,
diff --git a/frontend/ui/widget/iconbutton.lua b/frontend/ui/widget/iconbutton.lua
index cce03e925..b972b34ed 100644
--- a/frontend/ui/widget/iconbutton.lua
+++ b/frontend/ui/widget/iconbutton.lua
@@ -1,11 +1,12 @@
+--[[--
+Button with a big icon image! Designed for touch devices.
+--]]
+
 local InputContainer = require("ui/widget/container/inputcontainer")
 local ImageWidget = require("ui/widget/imagewidget")
 local GestureRange = require("ui/gesturerange")
 local UIManager = require("ui/uimanager")
 
---[[
-Button with a big icon image! Designed for touch device
---]]
 local IconButton = InputContainer:new{
     icon_file = "resources/info-confirm.png",
     dimen = nil,
diff --git a/frontend/ui/widget/imageviewer.lua b/frontend/ui/widget/imageviewer.lua
index 53fc62000..e08ad8564 100644
--- a/frontend/ui/widget/imageviewer.lua
+++ b/frontend/ui/widget/imageviewer.lua
@@ -1,28 +1,28 @@
-local InputContainer = require("ui/widget/container/inputcontainer")
-local WidgetContainer = require("ui/widget/container/widgetcontainer")
-local FrameContainer = require("ui/widget/container/framecontainer")
+--[[--
+ImageViewer displays an image with some simple manipulation options.
+]]
+
+local Blitbuffer = require("ffi/blitbuffer")
+local ButtonTable = require("ui/widget/buttontable")
 local CenterContainer = require("ui/widget/container/centercontainer")
-local VerticalGroup = require("ui/widget/verticalgroup")
-local OverlapGroup = require("ui/widget/overlapgroup")
 local CloseButton = require("ui/widget/closebutton")
-local ButtonTable = require("ui/widget/buttontable")
-local TextWidget = require("ui/widget/textwidget")
-local LineWidget = require("ui/widget/linewidget")
-local ImageWidget = require("ui/widget/imagewidget")
-local GestureRange = require("ui/gesturerange")
-local UIManager = require("ui/uimanager")
-local Screen = require("device").screen
 local Device = require("device")
 local Geom = require("ui/geometry")
+local GestureRange = require("ui/gesturerange")
 local Font = require("ui/font")
+local FrameContainer = require("ui/widget/container/framecontainer")
+local ImageWidget = require("ui/widget/imagewidget")
+local InputContainer = require("ui/widget/container/inputcontainer")
+local LineWidget = require("ui/widget/linewidget")
+local OverlapGroup = require("ui/widget/overlapgroup")
+local TextWidget = require("ui/widget/textwidget")
+local VerticalGroup = require("ui/widget/verticalgroup")
+local WidgetContainer = require("ui/widget/container/widgetcontainer")
+local UIManager = require("ui/uimanager")
+local Screen = Device.screen
 local logger = require("logger")
 local _ = require("gettext")
-local Blitbuffer = require("ffi/blitbuffer")
-
 
---[[
-Display image with some simple manipulation options
-]]
 local ImageViewer = InputContainer:new{
     -- Allow for providing same different input types as ImageWidget :
     -- a path to a file
diff --git a/frontend/ui/widget/linkbox.lua b/frontend/ui/widget/linkbox.lua
index 3dec77834..9710cf3a4 100644
--- a/frontend/ui/widget/linkbox.lua
+++ b/frontend/ui/widget/linkbox.lua
@@ -1,10 +1,10 @@
-local InputContainer = require("ui/widget/container/inputcontainer")
+local Blitbuffer = require("ffi/blitbuffer")
+local Device = require("device")
+local Geom = require("ui/geometry")
 local GestureRange = require("ui/gesturerange")
+local InputContainer = require("ui/widget/container/inputcontainer")
 local UIManager = require("ui/uimanager")
-local Screen = require("device").screen
-local Geom = require("ui/geometry")
-local Device = require("device")
-local Blitbuffer = require("ffi/blitbuffer")
+local Screen = Device.screen
 
 local LinkBox = InputContainer:new{
     box = nil,