From 51bbb53b303be5068eace3743934b1aee9414192 Mon Sep 17 00:00:00 2001 From: MoreThanOneAnimal Date: Sun, 20 Nov 2016 01:01:39 -0800 Subject: [PATCH 1/3] Add references to gears.color in documentation. --- lib/awful/prompt.lua | 1 + lib/gears/wallpaper.lua | 3 +++ lib/wibox/drawable.lua | 2 ++ lib/wibox/widget/graph.lua | 6 ++++-- lib/wibox/widget/progressbar.lua | 4 ++++ 5 files changed, 14 insertions(+), 2 deletions(-) diff --git a/lib/awful/prompt.lua b/lib/awful/prompt.lua index 1d7ceabda..ead326aec 100644 --- a/lib/awful/prompt.lua +++ b/lib/awful/prompt.lua @@ -287,6 +287,7 @@ end -- @param[opt] keypressed_callback The callback function to call -- with mod table, key and command as arguments when a key was pressed. -- [**DEPRECATED**] +-- @see gears.color function prompt.run(args, textbox, exe_callback, completion_callback, history_path, history_max, done_callback, changed_callback, keypressed_callback) diff --git a/lib/gears/wallpaper.lua b/lib/gears/wallpaper.lua index 5fc9e09d3..70ecf482a 100644 --- a/lib/gears/wallpaper.lua +++ b/lib/gears/wallpaper.lua @@ -88,6 +88,7 @@ end --- Set the current wallpaper. -- @param pattern The wallpaper that should be set. This can be a cairo surface, -- a description for gears.color or a cairo pattern. +-- @see gears.color function wallpaper.set(pattern) if cairo.Surface:is_type_of(pattern) then pattern = cairo.Pattern.create_for_surface(pattern) @@ -107,6 +108,7 @@ end -- all screens are set. -- @param background The background color that should be used. Gets handled via -- gears.color. The default is black. +-- @see gears.color function wallpaper.centered(surf, s, background) local geom, cr = wallpaper.prepare_context(s) surf = surface.load_uncached(surf) @@ -188,6 +190,7 @@ end -- all screens are set. -- @param background The background color that should be used. Gets handled via -- gears.color. The default is black. +-- @see gears.color function wallpaper.fit(surf, s, background) local geom, cr = wallpaper.prepare_context(s) surf = surface.load_uncached(surf) diff --git a/lib/wibox/drawable.lua b/lib/wibox/drawable.lua index 6e8c37744..268c3282b 100644 --- a/lib/wibox/drawable.lua +++ b/lib/wibox/drawable.lua @@ -216,6 +216,7 @@ end --- Set the background of the drawable -- @param c The background to use. This must either be a cairo pattern object, -- nil or a string that gears.color() understands. +-- @see gears.color function drawable:set_bg(c) c = c or "#000000" local t = type(c) @@ -263,6 +264,7 @@ end --- Set the foreground of the drawable -- @param c The foreground to use. This must either be a cairo pattern object, -- nil or a string that gears.color() understands. +-- @see gears.color function drawable:set_fg(c) c = c or "#FFFFFF" if type(c) == "string" or type(c) == "table" then diff --git a/lib/wibox/widget/graph.lua b/lib/wibox/widget/graph.lua index b78688da9..0d5f4cd62 100644 --- a/lib/wibox/widget/graph.lua +++ b/lib/wibox/widget/graph.lua @@ -31,18 +31,20 @@ local graph = { mt = {} } -- If the value is nil, no border will be drawn. -- -- @property border_color --- @tparam geats.color border_color The border color to set. +-- @tparam gears.color border_color The border color to set. +-- @see gears.color --- Set the graph foreground color. -- -- @property color -- @tparam color color The graph color. --- @see gears.color.create_pattern +-- @see gears.color --- Set the graph background color. -- -- @property background_color -- @tparam gears.color background_color The graph background color. +-- @see gears.color --- Set the maximum value the graph should handle. -- If "scale" is also set, the graph never scales up below this value, but it diff --git a/lib/wibox/widget/progressbar.lua b/lib/wibox/widget/progressbar.lua index 2725ace13..10db82a37 100644 --- a/lib/wibox/widget/progressbar.lua +++ b/lib/wibox/widget/progressbar.lua @@ -36,6 +36,7 @@ local progressbar = { mt = {} } -- -- @property border_color -- @tparam gears.color color The border color to set. +-- @see gears.color --- The progressbar border width. -- @property border_width @@ -45,6 +46,7 @@ local progressbar = { mt = {} } -- -- @property bar_border_color -- @tparam gears.color color The border color to set. +-- @see gears.color --- The progressbar inner border width. -- @property bar_border_width @@ -53,11 +55,13 @@ local progressbar = { mt = {} } -- -- @property color -- @tparam gears.color color The progressbar color. +-- @see gears.color --- The progressbar background color. -- -- @property background_color -- @tparam gears.color color The progressbar background color. +-- @see gears.color --- The progressbar inner shape. -- From 495e579fdbd1efb95c1b469ea563fdb7ba096318 Mon Sep 17 00:00:00 2001 From: MoreThanOneAnimal Date: Sun, 20 Nov 2016 00:40:56 -0800 Subject: [PATCH 2/3] parse_color function refactoring: - simplified parsing logic, - return nil for incorrect input, - update tests and doc. --- lib/gears/color.lua | 63 +++++++++++++++++++-------------------- spec/gears/color_spec.lua | 20 +++++++++++++ 2 files changed, 51 insertions(+), 32 deletions(-) diff --git a/lib/gears/color.lua b/lib/gears/color.lua index c8c1f2ba8..bf8664b2c 100644 --- a/lib/gears/color.lua +++ b/lib/gears/color.lua @@ -22,51 +22,50 @@ local pattern_cache --- Parse a HTML-color. -- This function can parse colors like `#rrggbb` and `#rrggbbaa` and also `red`. --- Thanks to #lua for this. :) +-- Max 4 chars per channel. Thanks to #lua for this. :) -- -- @param col The color to parse --- @return 4 values which each are in the range [0, 1]. +-- @return 4 values representing color in RGBA format (each of them in [0, 1] +-- range) or nil if input is incorrect. -- @usage -- This will return 0, 1, 0, 1 -- gears.color.parse_color("#00ff00ff") function color.parse_color(col) local rgb = {} - -- Is it a HTML-style color? if string.match(col, "^#%x+$") then - -- Get all hex chars - for char in string.gmatch(col, "[^#]") do - table.insert(rgb, tonumber(char, 16) / 0xf) + local hex_str = col:sub(2, #col) + local channels + if #hex_str % 3 == 0 then + channels = 3 + elseif #hex_str % 4 == 0 then + channels = 4 + else + return nil end - -- Merge consecutive values until we have at most four groups (rgba) - local factor = 0xf - while #rgb > 4 do - local merged = {} - local key, value = next(rgb, nil) - local next_factor = (factor + 1)*(factor + 1) - 1 - while key do - local key2, value2 = next(rgb, key) - local v1, v2 = value * factor, value2 * factor - local new = v1 * (factor + 1) + v2 - table.insert(merged, new / next_factor) - key, value = next(rgb, key2) - end - rgb = merged - factor = next_factor + local chars_per_channel = #hex_str / channels + if chars_per_channel > 4 then + return nil + end + local dividor = 0x10^chars_per_channel - 1 + for idx=1,#hex_str,chars_per_channel do + local channel_val = tonumber(hex_str:sub(idx,idx+chars_per_channel-1), 16) + table.insert(rgb, channel_val / dividor) + end + if channels == 3 then + table.insert(rgb, 1) end else - -- Let's ask Pango for its opinion (but this doesn't support alpha!) local c = Pango.Color() - if c:parse(col) then - rgb = { - c.red / 0xffff, - c.green / 0xffff, - c.blue / 0xffff, - } + if not c:parse(col) then + return nil end + rgb = { + c.red / 0xffff, + c.green / 0xffff, + c.blue / 0xffff, + 1.0 + } end - -- Add missing groups (missing alpha) - while #rgb < 4 do - table.insert(rgb, 1) - end + assert(#rgb == 4, col) return unpack(rgb) end diff --git a/spec/gears/color_spec.lua b/spec/gears/color_spec.lua index 47b157ca5..2ac33eab8 100644 --- a/spec/gears/color_spec.lua +++ b/spec/gears/color_spec.lua @@ -42,6 +42,26 @@ describe("gears.color", function() test(0x7f, 0xff, 0x00, 0xff, "chartreuse") end) + describe("invalid input", function() + local function test_nil(input) + local output = color.parse_color(input) + assert.is_nil(output) + end + + it("nonexisting color", function() + test_nil("elephant") + end) + + it("invalid format", function() + test_nil('#f0f0f') + end) + + it("too long", function() + test_nil("#00000fffff00000fffff") + end) + end) + + describe("different lengths", function() local function gray(e, e_a, input) local o_r, o_g, o_b, o_a, unused = color.parse_color(input) From 6558164e534a736ebb5f4bfbddd6fa0b93a30374 Mon Sep 17 00:00:00 2001 From: MoreThanOneAnimal Date: Mon, 21 Nov 2016 22:41:29 -0800 Subject: [PATCH 3/3] Create artificial gears.color documentation. Point from parse_color function to gears.color in documentation. Fix minor issues (typos, indentation) in docs. --- lib/gears/color.lua | 55 +++++++++++++++++++++++++-------------------- 1 file changed, 31 insertions(+), 24 deletions(-) diff --git a/lib/gears/color.lua b/lib/gears/color.lua index bf8664b2c..f0197c13b 100644 --- a/lib/gears/color.lua +++ b/lib/gears/color.lua @@ -20,13 +20,38 @@ local surface = require("gears.surface") local color = { mt = {} } local pattern_cache +--- Create a pattern from a given string. +-- This function can create solid, linear, radial and png patterns. In general, +-- patterns are specified as strings formatted as "type:arguments". "arguments" +-- is specific to the pattern being used. For example, one can use +-- "radial:50,50,10:55,55,30:0,#ff0000:0.5,#00ff00:1,#0000ff". +-- Alternatively, patterns can be specified via tables. In this case, the +-- table's 'type' member specifies the type. For example: +-- { +-- type = "radial", +-- from = { 50, 50, 10 }, +-- to = { 55, 55, 30 }, +-- stops = { { 0, "#ff0000" }, { 0.5, "#00ff00" }, { 1, "#0000ff" } } +-- } +-- Any argument that cannot be understood is passed to @{create_solid_pattern}. +-- +-- Please note that you MUST NOT modify the returned pattern, for example by +-- calling :set_matrix() on it, because this function uses a cache and your +-- changes could thus have unintended side effects. Use @{create_pattern_uncached} +-- if you need to modify the returned pattern. +-- @see create_pattern_uncached, create_solid_pattern, create_png_pattern, +-- create_linear_pattern, create_radial_pattern +-- @tparam string col The string describing the pattern. +-- @return a cairo pattern object +-- @function gears.color + --- Parse a HTML-color. -- This function can parse colors like `#rrggbb` and `#rrggbbaa` and also `red`. --- Max 4 chars per channel. Thanks to #lua for this. :) +-- Max 4 chars per channel. -- -- @param col The color to parse --- @return 4 values representing color in RGBA format (each of them in [0, 1] --- range) or nil if input is incorrect. +-- @treturn table 4 values representing color in RGBA format (each of them in +-- [0, 1] range) or nil if input is incorrect. -- @usage -- This will return 0, 1, 0, 1 -- gears.color.parse_color("#00ff00ff") function color.parse_color(col) @@ -45,7 +70,7 @@ function color.parse_color(col) if chars_per_channel > 4 then return nil end - local dividor = 0x10^chars_per_channel - 1 + local dividor = (0x10 ^ chars_per_channel) - 1 for idx=1,#hex_str,chars_per_channel do local channel_val = tonumber(hex_str:sub(idx,idx+chars_per_channel-1), 16) table.insert(rgb, channel_val / dividor) @@ -233,27 +258,9 @@ function color.create_pattern_uncached(col) return color.create_solid_pattern(col) end ---- Create a pattern from a given string. --- This function can create solid, linear, radial and png patterns. In general, --- patterns are specified as strings formatted as"type:arguments". "arguments" --- is specific to the pattern used. For example, one can use --- "radial:50,50,10:55,55,30:0,#ff0000:0.5,#00ff00:1,#0000ff" --- Alternatively, patterns can be specified via tables. In this case, the --- table's 'type' member specifies the type. For example: --- { type = "radial", from = { 50, 50, 10 }, to = { 55, 55, 30 }, --- stops = { { 0, "#ff0000" }, { 0.5, "#00ff00" }, { 1, "#0000ff" } } } --- Any argument that cannot be understood is passed to @{create_solid_pattern}. --- --- Please note that you MUST NOT modify the returned pattern, for example by --- calling :set_matrix() on it, because this function uses a cache and your --- changes could thus have unintended side effects. Use @{create_pattern_uncached} --- if you need to modify the returned pattern. --- @see create_pattern_uncached, create_solid_pattern, create_png_pattern, --- create_linear_pattern, create_radial_pattern --- @param col The string describing the pattern. --- @return a cairo pattern object +--- Create a pattern from a given string, same as `gears.color`. +-- @see gears.color function color.create_pattern(col) - -- If it already is a cairo pattern, just leave it as that if cairo.Pattern:is_type_of(col) then return col end