Converters

Converters are pairs of serialization and deserialization functions used to convert color values to text and text to color values.

Writing your own converter

If provided text-to-color and color-to-text conversions are not enough, and you need a custom color input/output format, you will have to write a custom converter. Converter is basically a pair of functions: one function transforms color object into a line of text, and another function parses a line of text and reports the level of confidence that the provided text can be parsed into a valid color.

Creating initialization script

Create an empty file named /home/foobar/.config/gpick/user_init.lua where foobar is your user name. Open this file with your favorite text editor.

Simple converter

Converters are declared by calling addConverter on gpick with three or four arguments. Passing only three arguments will define a converter that can only convert color to text and does not have deserialization support. The arguments are as follows:

• Name. Used to keep track of converter and associated options.
• Label. Displayed to the user in selection widgets and converter setup dialog.
• Serialize callback function, which should format color data in colorObject and return a text.
• Deserialize callback function, which should try parse a string of text specified in text parameter and set color data in colorObject parameter. This function should also return positive number between 0 and 1 when parsing succeeds (higher number represents higher parsing confidence), and -1 if parsing failed.

Code example:

local gpick = require('gpick') --import gpick library
local color = require('gpick/color') --import color library
local round = require('helpers').round --import round function from helpers library
local serialize = function(colorObject) --declare serialize function
    local c = colorObject:getColor() --get color values
    return string.format('#%02X%02X%02X - %s', round(c:red() * 255), round(c:green() * 255), round(c:blue() * 255), colorObject:getName()) --format to hex color code and color name
end
local deserialize = function(text, colorObject) --declare deserialize function
    local findStart, findEnd, red, green, blue = string.find(text, '#([%x][%x])([%x][%x])([%x][%x])[^%x]?') --find hex color code pattern in text
    if findStart ~= nil then
        colorObject:setColor(color:new(tonumber(red, 16) / 255, tonumber(green, 16) / 255, tonumber(blue, 16) / 255)) --set color values
        --return 1 when text is exactly matched as hex color code, otherwise return value less than 1
        return 1 - (math.atan(findStart - 1) / math.pi) - (math.atan(string.len(text) - findEnd) / math.pi)
    else
        return -1 --no hex color code found
    end
end
gpick:addConverter('custom', 'Custom', serialize, deserialize) --register custom converter

Using custom converter

Restart Gpick to load updated user_init.lua file. Open converter setup dialog by activating Edit->Edit Converters... menu item. Your new custom converter should be in the bottom of the list. Activate Copy checkbox if converter should be available in copy menus. Activate Edit/Paste checkbox if converter should be used in edit dialogs and when pasting colors from other applications.

Converter list can be reordered by dragging and dropping converters. First converter with active Copy option is used as default when copying colors to other applications.