[MOD 0.15+] Color Picker 0.4.4 - Reworked mod settings

[Mooncat]

Type: Library Mod
Name: Color Picker
Description: Adds a color picker GUI that can be used by other mods. But this mod itself doesn't do anything alone.
License: GNU LGPLv3
Version: 0.4.4
Release: 2017-08-10
Tested-With-Factorio-Version: 0.15.33
Category: Utility
Tags: color, color picker, library, player, locomotive, cargo wagon, fluid wagon, train stop
Download-Url: https://mods.factorio.com/mods/Mooncat/color-picker
Website: viewtopic.php?f=97&t=30657

License

GNU LESSER GENERAL PUBLIC LICENSE
Version 3, 29 June 2007

Copyright (C) 2007 Free Software Foundation, Inc. <http://fsf.org/>

Everyone is permitted to copy and distribute verbatim copies of this license document, but changing it is not allowed.

This version of the GNU Lesser General Public License incorporates the terms and conditions of version 3 of the GNU General Public License, supplemented by the additional permissions listed below.

0. Additional Definitions.
As used herein, “this License” refers to version 3 of the GNU Lesser General Public License, and the “GNU GPL” refers to version 3 of the GNU General Public License.

“The Library” refers to a covered work governed by this License, other than an Application or a Combined Work as defined below.

An “Application” is any work that makes use of an interface provided by the Library, but which is not otherwise based on the Library. Defining a subclass of a class defined by the Library is deemed a mode of using an interface provided by the Library.

A “Combined Work” is a work produced by combining or linking an Application with the Library. The particular version of the Library with which the Combined Work was made is also called the “Linked Version”.

The “Minimal Corresponding Source” for a Combined Work means the Corresponding Source for the Combined Work, excluding any source code for portions of the Combined Work that, considered in isolation, are based on the Application, and not on the Linked Version.

The “Corresponding Application Code” for a Combined Work means the object code and/or source code for the Application, including any data and utility programs needed for reproducing the Combined Work from the Application, but excluding the System Libraries of the Combined Work.

1. Exception to Section 3 of the GNU GPL.
You may convey a covered work under sections 3 and 4 of this License without being bound by section 3 of the GNU GPL.

2. Conveying Modified Versions.
If you modify a copy of the Library, and, in your modifications, a facility refers to a function or data to be supplied by an Application that uses the facility (other than as an argument passed when the facility is invoked), then you may convey a copy of the modified version:

a) under this License, provided that you make a good faith effort to ensure that, in the event an Application does not supply the function or data, the facility still operates, and performs whatever part of its purpose remains meaningful, or
b) under the GNU GPL, with none of the additional permissions of this License applicable to that copy.
3. Object Code Incorporating Material from Library Header Files.
The object code form of an Application may incorporate material from a header file that is part of the Library. You may convey such object code under terms of your choice, provided that, if the incorporated material is not limited to numerical parameters, data structure layouts and accessors, or small macros, inline functions and templates (ten or fewer lines in length), you do both of the following:

a) Give prominent notice with each copy of the object code that the Library is used in it and that the Library and its use are covered by this License.
b) Accompany the object code with a copy of the GNU GPL and this license document.
4. Combined Works.
You may convey a Combined Work under terms of your choice that, taken together, effectively do not restrict modification of the portions of the Library contained in the Combined Work and reverse engineering for debugging such modifications, if you also do each of the following:

a) Give prominent notice with each copy of the Combined Work that the Library is used in it and that the Library and its use are covered by this License.
b) Accompany the Combined Work with a copy of the GNU GPL and this license document.
c) For a Combined Work that displays copyright notices during execution, include the copyright notice for the Library among these notices, as well as a reference directing the user to the copies of the GNU GPL and this license document.
d) Do one of the following:
0) Convey the Minimal Corresponding Source under the terms of this License, and the Corresponding Application Code in a form suitable for, and under terms that permit, the user to recombine or relink the Application with a modified version of the Linked Version to produce a modified Combined Work, in the manner specified by section 6 of the GNU GPL for conveying Corresponding Source.
1) Use a suitable shared library mechanism for linking with the Library. A suitable mechanism is one that (a) uses at run time a copy of the Library already present on the user's computer system, and (b) will operate properly with a modified version of the Library that is interface-compatible with the Linked Version.
e) Provide Installation Information, but only if you would otherwise be required to provide such information under section 6 of the GNU GPL, and only to the extent that such information is necessary to install and execute a modified version of the Combined Work produced by recombining or relinking the Application with a modified version of the Linked Version. (If you use option 4d0, the Installation Information must accompany the Minimal Corresponding Source and Corresponding Application Code. If you use option 4d1, you must provide the Installation Information in the manner specified by section 6 of the GNU GPL for conveying Corresponding Source.)
5. Combined Libraries.
You may place library facilities that are a work based on the Library side by side in a single library together with other library facilities that are not Applications and are not covered by this License, and convey such a combined library under terms of your choice, if you do both of the following:

a) Accompany the combined library with a copy of the same work based on the Library, uncombined with any other library facilities, conveyed under the terms of this License.
b) Give prominent notice with the combined library that part of it is a work based on the Library, and explaining where to find the accompanying uncombined form of the same work.
6. Revised Versions of the GNU Lesser General Public License.
The Free Software Foundation may publish revised and/or new versions of the GNU Lesser General Public License from time to time. Such new versions will be similar in spirit to the present version, but may differ in detail to address new problems or concerns.

Each version is given a distinguishing version number. If the Library as you received it specifies that a certain numbered version of the GNU Lesser General Public License “or any later version” applies to it, you have the option of following the terms and conditions either of that published version or of any later version published by the Free Software Foundation. If the Library as you received it does not specify a version number of the GNU Lesser General Public License, you may choose any version of the GNU Lesser General Public License ever published by the Free Software Foundation.

If the Library as you received it specifies that a proxy can decide whether future versions of the GNU Lesser General Public License shall apply, that proxy's public statement of acceptance of any version is permanent authorization for you to choose that version for the Library.

Long description

This mod adds a color picker GUI for you to easily change your player color. You can also use the color picker GUI to change the color of the selected train stop, locomotive or cargo wagon.
It also provides API for other mods to access the color picker GUI. For example, it can used for changing the text color of the sticky note in Picker Extended.

ColorPicker.jpg (51.87 KiB) Viewed 11689 times

Note: since v0.4.0 of this mod, it has combined the functionalities of the following mods, so you can safely remove them from your mod list:
- Color Picker - Player
- Color Picker - Wagon
- Color Picker - Locomotive
- Color Picker - Train Stop

Runtime mod settings are added for you to disable them.

In v0.4.0+, you can now also save the colors as color presets. Each player can store 24 presets in maximum.
You can also given them names by Alt+Click the preset buttons.


Since v0.4.1+, this mod adds support to fluid wagons. It is done by adding color masks to the vanilla fluid wagon.


For modders, this mod provides the following public function to add the same set of color masks to other fluid wagon entities during data-final-fixes. It will be useful if your fluid wagons look exactly the same as the vanilla one:
[quote]color_picker_data_functions.add_color_mask_to_fluid_wagon(fluid_wagon_data, reset_color)
[quote]Parameters
• fluid_wagon_data :: table: The table of your fluid wagon entity data. For example, this mod adds the color masks to the vanilla fluid wagon by providing data.raw["fluid-wagon"]["fluid-wagon"].
• reset_color :: boolean: Whether the default entity color will be reset to (0, 0, 0, 0), such that the default color will be the same as before after the color mask is added. It is needed for the vanilla fluid wagon because its default color was not white but yellowish, which was obvious in game after the color mask is added.
[/quote][/quote]
Note: you will need to add dependency to this mod before calling this function.

Also, this mod makes wagons pastable from/to locomotives and train stops, so you can copy-and-paste the colors between them without worrying about their entity types.


Here is the document about the API:

[quote]Dependency
Before you can use the functionalities of this mod, you will need to add dependency to this mod in your mod's info.json. Depends on your need, it can be either optional or non-optional.
[quote]Non-optional Dependency

Code: Select all

"dependencies" : ["color-picker >= 0.4.0"]

[/quote]
[quote]Optional Dependency

Code: Select all

"dependencies" : ["? color-picker >= 0.4.0"]

[/quote][/quote]

[quote]Interface
To access the functions or events in this mod, you need to use remote.call, with the interface name "color-picker".
Note: if you used optional dependency, i.e. it is possible that users don't have Color Picker installed when running your mod, you will need to check whether the color-picker interface exists before accessing it:

Code: Select all

if remote.interfaces["color-picker"] then
    -- The interface exists.
end

[/quote]

[quote]Functions

• add_instance{parent=..., container_name=..., title_caption=..., color=..., hex_color=..., support_alpha=..., show_ok_button=...} → LuaGuiElement
• set_color(color_picker_container, color)
• set_hex_color(color_picker_container, hex_color)
• get_color(color_picker_container) → Color
• get_hex_color(color_picker_container) → string

[quote]add_instance{parent=..., container_name=..., title_caption=..., color=..., hex_color=..., support_alpha=..., show_ok_button=...} → LuaGuiElement
  Adds a color picker under a GUI element. If there is already a GUI element with the same name as container_name, nothing will be done.
[quote]Parameters
Table with the following fields:
• parent :: LuaGuiElement: The GUI element where the color picker will be added to.
• container_name :: string: The GUI element name of the color picker container. For example, this can be (your mod name) + "_color-picker".
• title_caption :: string or LocalisedString (optional): Title of the color picker. If not provided, localised "Color" will be used.
• color :: Color (optional): The color this color picker is representing. The value of "a" will be ignored if provided.
• hex_color :: string (optional): The hexadecimal color this color picker is representing (e.g. "FF0000FF", or "FF0000" if alpha is not supported). It is used only if "color" is not provided. If both "color" and it are not provided, the color white will be used. * Require version 0.2.0+
• support_alpha :: boolean (optional): Whether the alpha channel is supported. It is false by default. If alpha is not supported, the alpha value of the provided color will be ignored, and the returned color in the events will not contain alpha. * Require version 0.4.0+
• show_ok_button :: boolean (optional): Whether an OK button should be shown at the bottom. Default is false. To provide maximum freedom, the button will not do anything, but the on_ok_button_clicked event will be called when it is clicked. It is up to you to do anything with it. For example, you can simply destroy the container, i.e. close the color picker. See the example implementation of such event.
• result_caption :: string or LocalisedString (optional): Caption of the result. If not provided, localised "@@@ Result Color @@@" will be used. * Deprecated since v0.4.0[/quote]
[quote]Returns
The GUI element of the color picker container if it is successfully created.[/quote]
[quote]Example
Add a color picker under the left GUI of player with the name "my-mod_color-picker". Set its initial color to be the player's color. Then change its left padding to 8.

Code: Select all

local color_picker = remote.call("color-picker", "add_instance",
{
	parent = player.gui.left,
	container_name = "my-mod_color-picker",
	title_caption = "Pick your color",
	color = player.color,
	show_ok_button = true
})
color_picker.style.left_padding = 8

[/quote]
[quote]Example
To check whether a color picker exists in the left GUI.

Code: Select all

if player.gui.left["my-mod_color-picker"] then
	-- There is a color picker.
end

[/quote][/quote]

[quote]set_color(color_picker_container, color)
  Sets the current color represented by the color picker of the given container.
[quote]Parameters
• color_picker_container :: LuaGuiElement: The element of color picker container.
• color :: Color : The desired color. If the color picker does not support alpha, the value of "a" will be ignored.[/quote]
[quote]Example
Set the color to red.

Code: Select all

remote.call("color-picker", "set_color", color_picker, {r = 1, g = 0, b = 0})

[/quote][/quote]

[quote]set_hex_color(color_picker_container, hex_color)
  Sets the current hexadecimal color represented by the color picker of the given container.
  * Require version 0.2.0+
[quote]Parameters
• color_picker_container :: LuaGuiElement: The element of color picker container.
• hex_color :: string : The hexadecimal representation of desired color. If the color picker supports alpha, the provided string should contain exactly 8 characters; otherwise, it should contain exactly 6 characters.[/quote]
[quote]Example
Set the color to red.

Code: Select all

remote.call("color-picker", "set_hex_color", color_picker, "FF0000")

[/quote][/quote]

[quote]get_color(color_picker_container) → Color
  Gets the current color represented by the color picker of the given container.
  * Require version 0.1.1+
[quote]Parameters
• color_picker_container :: LuaGuiElement: The element of color picker container.[/quote]
[quote]Returns
The color represented by the color picker. If the color picker does not support alpha, it will not contain the "a" value.[/quote]
[quote]Example
Get the color and store in c.

Code: Select all

local c = remote.call("color-picker", "get_color", color_picker)

[/quote][/quote]

[quote]get_hex_color(color_picker_container) → string
  Gets the current hexadecimal color represented by the color picker of the given container.
  * Require version 0.2.0+
[quote]Parameters
• color_picker_container :: LuaGuiElement: The element of color picker container.[/quote]
[quote]Returns
The hexadecimal color represented by the color picker. If the color picker supports alpha, it will contain 8 characters; otherwise, it will contain 6 characters.[/quote]
[quote]Example
Get the hexadecimal color and store in hex_c.

Code: Select all

local hex_c = remote.call("color-picker", "get_hex_color", color_picker)

[/quote][/quote]
[/quote]

[quote]Events

• on_color_updated
• on_ok_button_clicked

[quote]on_color_updated
  Called when the color of a color picker is changed by player.
[quote]Contains
• name :: uint: Identifier of the event.
• tick :: uint: Tick the event was generated.
• container :: LuaGuiElement: The GUI element of the color picker's container.
• color :: Color: The updated color represented by the color picker. If the color picker does not support alpha, it will not contain the "a" value.
• hex_color :: string: The hexadecimal representation of color. If the color picker supports alpha, it will contain 8 characters; otherwise, it will contain 6 characters. * Require version 0.2.0+
• player_index :: uint: The index of the player who did the change.[/quote]
[quote]Example
Change the player color when the color of color picker is changed.

Code: Select all

script.on_event(remote.call("color-picker", "on_color_updated"), function(event)
	if event.container.name == "my-mod_color-picker" then
		game.players[event.player_index].color = event.color
	end
end)

[/quote][/quote]

[quote]on_ok_button_clicked
  Called when the OK button of a color picker is clicked by player.
[quote]Contains
• name :: uint: Identifier of the event.
• tick :: uint: Tick the event was generated.
• container :: LuaGuiElement: The GUI element of the color picker's container.
• color :: Color : The updated color represented by the color picker. If the color picker does not support alpha, it will not contain the "a" value.
• hex_color :: string: The hexadecimal representation of color. If the color picker supports alpha, it will contain 8 characters; otherwise, it will contain 6 characters. * Require version 0.2.1+
• player_index :: uint: The index of the player who clicked the button.[/quote]
[quote]Example
Dismiss the color picker when the OK button is clicked.

Code: Select all

script.on_event(remote.call("color-picker", "on_ok_button_clicked"), function(event)
	if event.container.name == "my-mod_color-picker" then
		event.container.destroy()
	end
end)

[/quote][/quote][/quote]

[quote]Styles
This mod also creates some GUI styles that you can use in your mod.

• small_color_picker_panel_button_style

[quote]small_color_picker_panel_button_style
  The style for small color picker panel button. It is mostly used for the button for opening color picker.
  Width: 20
  Height: 20
  
[/quote][/quote]

Version history

Version 0.4.4 (Aug 10, 2017):

• You will be notified to uninstall the old Color Picker sub-mods if any of them is detected..
• The mod settings under "Map" have been switched to "Per player".
• Now changing the colors of train stops, locomotives, cargo wagons and fluid wagons using the color picker or via copy-and-pasting requires the permission to set entity color.

Version 0.4.3 (Jul 16, 2017):

• The player color button is now shown correctly when loading a save that had Color Picker older than v0.4.0.
  • If the button is not shown and you have saved the game with Color Picker v0.4.0+, please turn off Mod settings > Map > Enable player color picker, apply, and then turn it on again.

Version 0.4.2 (Jul 16, 2017):

• Removed the blue default color preset. Added the colors of coal, stone, iron, copper and uranium as default presets.
• Added default names for the default color presets.
• Updated the tooltip format of the color preset buttons.
• Updated the style of the hex color textfield for invalid value, to match the style from vanilla.
• Improved the presentation of transparent color:
  • For the result color block, the top-left part of the block shows transparency while the bottom-right part remains opaque.
  • For the color presets, when a preset button is hovered, its color becomes opaque.
• Fixed the bug that the alpha channel is hidden after the color picker for train stop, locomotive, cargo wagon or fluid wagon is re-opened by clicking the button on the left side.

Version 0.4.1 (Jul 13, 2017):

• Added color mask for fluid wagon.
  • Added public function for modders to add the same set of color masks to other fluid wagon entities.
• Added color picker support for fluid wagon.
• Added mod settings to disable the above features.
• Reworked the "Make color pastable between cargo wagon and others" to "Make color pastable between wagon and others".
  • It now also applies on fluid wagons.
• Fixed error when loading a save that contains older version of Color Picker.

Version 0.4.0 (Jul 12, 2017):

• Changed the mod license from CC BY-NC 4.0 to GNU LGPLv3.
• Added Chinese mod name and description for Factorio 0.15.24+.
• Combined the following mods, you can delete them if you have installed them before:
  • Color Picker - Player
  • Color Picker - Train Stop
  • Color Picker - Locomotive
  • Color Picker - Wagon
• The color picker for the above entities will be opened by default instead of collapsed when the entity is selected.
  • It will also keep being opened when you select another entity that supports color picker.
• Added runtime mod settings to disable the above color pickers.
• Added the ability to copy-and-paste the color from a locomotive or train stop to cargo wagons or the other way around. It can be disabled with the new startup mod setting.
• Added support for the alpha channel.
  • Added "support_alpha" optional parameter for the "add_instance" method. It is false by default.
  • The alpha channel is supported for player color, train stop color, locomotive color and cargo wagon color.
• The "result_caption" of the "add_instance" method is deprecated.
• Added the ability to store color presets. By default, the default locomotive color, player color and a blue color are defined as presets.
  • You can add your own presets by clicking the last button in the presets table. 24 presets can be stored for each player at most.
  • You can name the presets by alt-clicking the preset buttons.
  • You can quickly remove presets by shift-clicking the preset buttons.
  • Due to technical limitation, presets cannot be saved across different games. This may be solved in the future.
• Known issue: because the UI has been reworked, existing color picker UIs from the old saves may not work properly. Please close and reopen them.

Version 0.3.0 (May 1, 2017):

• Updated for Factorio 0.15.
• The events raised from this mod now also contains "tick" (Tick the event was generated) and "name" (ID of the event).

Version 0.2.1 (Sep 16, 2016):

• Added "hex_color" parameter for the "on_ok_button_clicked" event.
• Fixed bad UI alignment in different window sizes.

Version 0.2.0 (Sep 15, 2016):

• Added French locale (Thanks binbinhfr)
• Added sounds for the buttons and color palettes when they are left-clicked.
• Better visualization. The result label is center-aligned if the OK button is not presented.
• Added hexadecimal representation of the color.
• Added "hex_color" optional parameter for the "add_instance" method.
• Added "hex_color" parameter for the "on_color_changed" event.
• Added remote.call("color-picker", "set_hex_color", LuaGuiElement, string)
• Added remote.call("color-picker", "get_hex_color", LuaGuiElement)

Version 0.1.1 (Aug 31, 2016):

• Updated for Factorio 0.14.
• Added remote.call("color-picker", "get_color", LuaGuiElement)

Version 0.1.0 (Aug 8, 2016): The first version.

Known issues

• It is not possible to get the color of train stops, locomotives and cargo wagons before changing their colors, so when you select any of them, the color picker will show the white color even though the actual color is not white.
• The built-in coloring scrollbars of locomotive and train stop do not sync with the color picker.
• Existing color picker GUIs from version before 0.4.0 will not work properly when upgrading to v0.4.0+. Please close and reopen them.

[Nexela]

Digging into this now!

Typo: Along should be alone.

Code: Select all

This is a library mod which doesn't do anything along. 

[Mooncat]

Digging into this now!

Typo: Along should be alone.

Code: Select all

This is a library mod which doesn't do anything along. 

Aw, a careless typo. xD Thanks!
Edit: I just posted the github link.

[Mooncat]

Happy to announce that Nexela's Circuit Alerter has been released! Feel free to try his mods.
Added link to the mod in description.

As for this mod, I will study on adding a hex color textfield under the RGB bars, so players can copy the hex color and paste on another color picker easily.

[aubergine18]

For working with hex colours, there's a useful util function "color()" in __core__/prototypes/style.lua -- it does a good job of parsing hex rgba colours in to factorio color objects.

[Mooncat]

For working with hex colours, there's a useful util function "color()" in __core__/prototypes/style.lua -- it does a good job of parsing hex rgba colours in to factorio color objects.

Thanks for the info.

[Mooncat]

Released a small update for this mod:
- Updated for Factorio 0.14.
- Added get_color remote method, in contrast to the set_color method.

[Mooncat]

Version 0.2.0 is released!
Happy to announce that binbinhfr's Stick Notes has added support to this mod. If you have this mod installed, you can use the color picker to change font color on the notes.
binbinhfr has also provided the French locale. Thanks a lot!

This version also introduces hexadecimal color representation. If you want to share the color across multiple color pickers, now you can copy the hex value and paste on the other color pickers.
For modders, the hex-color-related parameters and functions are also ready to use.

[Mooncat]

Released version 0.2.1, mainly for fixing bad UI alignment in different Factorio window sizes.

[aubergine18]

Could progress bars be used to indicate colors - eg. a 20x20 px progress bar, with the color defined by percentage?

[Mooncat]

Could progress bars be used to indicate colors - eg. a 20x20 px progress bar, with the color defined by percentage?

But I believe progress bars cannot be dragged?

[aubergine18]

I was thinking more from a display perspective - possibly trying to overlap them to create a custom RGB display.

[Mooncat]

Progress bars under the existing discrete bars? Or you mean the result color?

[aubergine18]

Result color. The progress bar with smooth color gradient can be used to display specific color. Alternatively see if there's any filled square characters in the default font and that could be used instead via font color.

[Mooncat]

hm... I have never used progress bar, so I don't know what does smooth color gradient mean.
But I know the alternative will work. I have tried the unicode black square with default font, but it wasn't shown. Now I think the current version allows us to use custom font? If so, I will make a font with just a black square.

[Mooncat]

Updated for Factorio 0.15.

Will work on the proper result color display, and also color presets!

[Adventurer]

Could you update your naming scheme so all your color related mods begin with the word 'Color' so they're grouped together?

[Mooncat]

Could you update your naming scheme so all your color related mods begin with the word 'Color' so they're grouped together?

I can change the mod names (not IDs) to start with "Color Picker -". But I need some more time. Please bare with me.

[Mooncat]

Finished changing the mod names. They should be grouped nicely now.

Mod Grouping.png (33.2 KiB) Viewed 12712 times

[Philip017]

looks interesting how about a version that works on lamps?