GUI COLOR: a colour picker dialog and a swatch

Typedefs
typedef void(*	N_GUI_COLOR_FN) (const float rgba[4], void *user_data)
	called each time the picked colour changes.

Functions
void	n_gui_color_picker_close (N_GUI_COLOR_PICKER *picker)
	Close the picker.
void	n_gui_color_picker_free (N_GUI_COLOR_PICKER **picker)
	Close the picker's window and free the handle.
int	n_gui_color_picker_get (const N_GUI_COLOR_PICKER *picker, float rgba[4])
	The colour the picker holds now.
int	n_gui_color_picker_is_open (const N_GUI_COLOR_PICKER *picker)
	Whether the picker is open.
N_GUI_COLOR_PICKER *	n_gui_color_picker_new (N_GUI_CTX *ctx, const char *title, float scale)
	Build a colour picker window in ctx, closed.
void	n_gui_color_picker_open (N_GUI_COLOR_PICKER *picker, const char *what, const float rgba[4], N_GUI_COLOR_FN on_change, void *user_data)
	Open the picker on a colour, centred on the display.
int	n_gui_color_picker_slider (const N_GUI_COLOR_PICKER *picker, int channel)
	The slider for one channel, for a caller or a test that drives it.
int	n_gui_color_picker_window (const N_GUI_COLOR_PICKER *picker)
	The picker's window id, for a caller that walks its windows or sets their flags.
void	n_gui_color_to_hex (const float rgba[4], char *out, size_t len)
	Write a colour as #RRGGBBAA, each channel clamped to 0..1 and rounded to the nearest of 255 steps.
void	n_gui_draw_color_swatch (float x, float y, float w, float h, const float rgba[4])
	Draw a colour as a swatch, over a checkerboard so its alpha shows, with a thin dark border.
ALLEGRO_MOUSE_CURSOR *	n_gui_eyedropper_cursor (float scale)
	Make a pipette mouse cursor, for a tool that picks a colour from an image.

Detailed Description

Typedef Documentation

N_GUI_COLOR_FN

typedef void(* N_GUI_COLOR_FN) (const float rgba[4], void *user_data)

called each time the picked colour changes.

Parameters

rgba	the colour now: red, green, blue, alpha, 0 to 1
user_data	what was handed to n_gui_color_picker_open()

Definition at line 73 of file n_gui_color.h.

Function Documentation

n_gui_color_picker_close()

void n_gui_color_picker_close

(

N_GUI_COLOR_PICKER *

picker

)

Close the picker.

The colour stays as it was last changed, and on_change is forgotten. The title bar's close button does the same.

Parameters

picker

the picker. NULL is a no-op.

Definition at line 337 of file n_gui_color.c.

References N_GUI_COLOR_PICKER::ctx, n_gui_close_window(), n_gui_mark_dirty(), N_GUI_COLOR_PICKER::on_change, N_GUI_COLOR_PICKER::user_data, and N_GUI_COLOR_PICKER::window.

Referenced by _n_gui_color_on_close_button(), _n_gui_color_on_close_window(), main(), and n_gui_color_picker_free().

Here is the call graph for this function:

Here is the caller graph for this function:

n_gui_color_picker_free()

void n_gui_color_picker_free

(

N_GUI_COLOR_PICKER **

picker

)

Close the picker's window and free the handle.

The window and its widgets stay in the context, closed, until n_gui_destroy_ctx(); nothing in them points at the handle once it is closed. Call it while the context is still alive.

Parameters

picker

address of the handle; set to NULL. NULL, or a pointer to NULL, is a no-op.

Definition at line 369 of file n_gui_color.c.

References Free, n_gui_color_picker_close(), and n_gui_window_set_close_callback().

Referenced by main().

Here is the call graph for this function:

Here is the caller graph for this function:

n_gui_color_picker_get()

int n_gui_color_picker_get	(	const N_GUI_COLOR_PICKER *	picker,
		float	rgba[4] )

The colour the picker holds now.

Parameters

picker	the picker. Must not be NULL.
rgba	receives red, green, blue, alpha, 0 to 1. Must not be NULL.

Returns

TRUE, or FALSE on a NULL argument.

Definition at line 351 of file n_gui_color.c.

References __n_assert, and N_GUI_COLOR_PICKER::rgba.

Referenced by main().

Here is the caller graph for this function:

n_gui_color_picker_is_open()

int n_gui_color_picker_is_open

(

const N_GUI_COLOR_PICKER *

picker

)

Whether the picker is open.

Parameters

picker

the picker. NULL gives 0.

Returns

1 when its window is open, 0 otherwise.

Definition at line 346 of file n_gui_color.c.

References N_GUI_COLOR_PICKER::ctx, n_gui_window_is_open(), and N_GUI_COLOR_PICKER::window.

Referenced by main().

Here is the call graph for this function:

Here is the caller graph for this function:

n_gui_color_picker_new()

N_GUI_COLOR_PICKER * n_gui_color_picker_new	(	N_GUI_CTX *	ctx,
		const char *	title,
		float	scale )

Build a colour picker window in ctx, closed.

The window is a popup (N_GUI_ZORDER_POPUP) with a close button in its title bar. Its widgets belong to ctx like any others; the returned handle only remembers their ids and the colour being edited.

Parameters

ctx	GUI context. Must not be NULL.
title	window title. NULL gives "Colour".
scale	multiplies every size, for a caller that sizes its dialogs by a display scale. Zero or less is taken as 1.

Returns

a new picker owned by the caller, to release with n_gui_color_picker_free() before n_gui_destroy_ctx(), or NULL when a widget could not be created.

Definition at line 234 of file n_gui_color.c.

References __n_assert, _n_gui_color_channels, _n_gui_color_draw_swatch(), _n_gui_color_on_close_button(), _n_gui_color_on_close_window(), _n_gui_color_on_slider(), N_GUI_COLOR_PICKER::btn_close, N_GUI_COLOR_PICKER::ctx, Free, N_GUI_COLOR_PICKER::lbl, N_GUI_COLOR_PICKER::lbl_what, LOG_ERR, Malloc, n_gui_add_button(), n_gui_add_custom(), n_gui_add_label(), n_gui_add_slider(), n_gui_add_window(), N_GUI_ALIGN_LEFT, n_gui_close_window(), N_GUI_COLOR_BTN_W, N_GUI_COLOR_LABEL, N_GUI_COLOR_PAD, N_GUI_COLOR_ROW, N_GUI_COLOR_SWATCH, N_GUI_COLOR_W, n_gui_get_window(), n_gui_set_widget_tooltip(), N_GUI_SHAPE_ROUNDED, n_gui_slider_set_step(), n_gui_slider_set_value_visible(), N_GUI_SLIDER_VALUE, N_GUI_WIN_BTN_CLOSE, n_gui_window_set_close_callback(), n_gui_window_set_flags(), n_gui_window_set_rect(), n_gui_window_set_zorder(), N_GUI_ZORDER_POPUP, n_log, N_GUI_COLOR_PICKER::rgba, row(), N_GUI_COLOR_PICKER::sl, N_GUI_COLOR_PICKER::swatch, N_GUI_WINDOW::titlebar_h, and N_GUI_COLOR_PICKER::window.

Referenced by main().

Here is the call graph for this function:

Here is the caller graph for this function:

n_gui_color_picker_open()

void n_gui_color_picker_open	(	N_GUI_COLOR_PICKER *	picker,
		const char *	what,
		const float	rgba[4],
		N_GUI_COLOR_FN	on_change,
		void *	user_data )

Open the picker on a colour, centred on the display.

Replaces whatever the picker was editing, and whom it told, with rgba and on_change. Setting the sliders to rgba does not call on_change: only the user's changes do.

Parameters

picker	the picker. Must not be NULL.
what	what the colour is, shown over the swatch, such as "Watermark: Colour". May be NULL.
rgba	the colour to start from, clamped to 0..1. Must not be NULL.
on_change	called on every change. May be NULL.
user_data	handed back to on_change.

Definition at line 298 of file n_gui_color.c.

References __n_assert, _n_gui_color_clamp(), _n_gui_color_set_label(), N_GUI_COLOR_PICKER::ctx, N_GUI_CTX::display_h, N_GUI_CTX::display_w, N_GUI_WINDOW::h, N_GUI_COLOR_PICKER::lbl_what, n_gui_get_window(), n_gui_label_set_text(), n_gui_mark_dirty(), n_gui_open_window(), n_gui_raise_window(), n_gui_slider_set_value(), n_gui_window_set_rect_axes(), N_GUI_COLOR_PICKER::on_change, on_change(), N_GUI_COLOR_PICKER::rgba, N_GUI_COLOR_PICKER::sl, N_GUI_COLOR_PICKER::syncing, N_GUI_COLOR_PICKER::user_data, N_GUI_WINDOW::w, and N_GUI_COLOR_PICKER::window.

Referenced by main().

Here is the call graph for this function:

Here is the caller graph for this function:

n_gui_color_picker_slider()

int n_gui_color_picker_slider	(	const N_GUI_COLOR_PICKER *	picker,
		int	channel )

The slider for one channel, for a caller or a test that drives it.

Parameters

picker	the picker.
channel	0 red, 1 green, 2 blue, 3 alpha.

Returns

the slider's widget id, or -1 for a NULL picker or a channel out of range.

Definition at line 364 of file n_gui_color.c.

References N_GUI_COLOR_PICKER::sl.

Referenced by main().

Here is the caller graph for this function:

n_gui_color_picker_window()

int n_gui_color_picker_window

(

const N_GUI_COLOR_PICKER *

picker

)

The picker's window id, for a caller that walks its windows or sets their flags.

Parameters

picker

the picker.

Returns

the window id, or -1 for a NULL picker.

Definition at line 360 of file n_gui_color.c.

References N_GUI_COLOR_PICKER::window.

Referenced by main().

Here is the caller graph for this function:

n_gui_color_to_hex()

void n_gui_color_to_hex	(	const float	rgba[4],
		char *	out,
		size_t	len )

Write a colour as #RRGGBBAA, each channel clamped to 0..1 and rounded to the nearest of 255 steps.

Parameters

rgba	the colour. NULL writes an empty string.
out	receives the text. Must not be NULL.
len	room in out; 10 bytes holds all of it. Zero writes nothing.

Definition at line 172 of file n_gui_color.c.

References _n_gui_color_clamp().

Referenced by main().

Here is the call graph for this function:

Here is the caller graph for this function:

n_gui_draw_color_swatch()

void n_gui_draw_color_swatch	(	float	x,
		float	y,
		float	w,
		float	h,
		const float	rgba[4] )

Draw a colour as a swatch, over a checkerboard so its alpha shows, with a thin dark border.

Draws on the current target with the current transform and blender, which is expected to be Allegro's default premultiplied one.

Parameters

x	left edge.
y	top edge.
w	width. Nothing is drawn when zero or less.
h	height. Nothing is drawn when zero or less.
rgba	the colour, straight alpha. Must not be NULL.

Definition at line 146 of file n_gui_color.c.

References _n_gui_color_clamp(), grey(), N_GUI_COLOR_CHECK, and row().

Referenced by _n_gui_color_draw_swatch(), and swatch_centre().

Here is the call graph for this function:

Here is the caller graph for this function:

n_gui_eyedropper_cursor()

ALLEGRO_MOUSE_CURSOR * n_gui_eyedropper_cursor

(

float

scale

)

Make a pipette mouse cursor, for a tool that picks a colour from an image.

Allegro's system cursors have no pipette, and a crosshair says "point at something" without saying "a colour will be taken from it". Drawn with primitives rather than read from a file, so there is nothing to ship: a pale glass tube with a dark rubber bulb, outlined in black and white so it shows on a dark photograph and on a light one. The hot spot is the tip, at the bottom left, which is the pixel the colour is read from.

Needs a display to exist, as al_create_mouse_cursor() does. Show it with n_gui_set_cursor(); release it with al_destroy_mouse_cursor(), after setting another cursor, never while it is showing.

Parameters

scale

the interface scale; the cursor is 32 pixels at 1.0, and never under 16.

Returns

the cursor, or NULL when Allegro could not make one.

Definition at line 92 of file n_gui_color.c.

References LOG_ERR, and n_log.