• ☰  Applications
  ⬆Main applications page

  ---

  FOSS Mixer

  ---

  ⬅Back to front page
• ☰  Examples
  ⬆Main examples page

  ---

  Vesmir, the artificial universe Desktop menu demo Julia set demo Mandelbrot set demo Widgets demo
• ☰  Docs
  ⬆Main documents page

  ---

  Engine function reference

  ---

  🕮Ano script reference ☰Menu resource guide 🎛Widget resource guide

  ---

  X resources file guide

  ---

  🕹Input driver 🖧Remote control

  ---

  🗔Redtools requester library

  ---

  Tutorials
• Download
• License
• Feedback

• Resources
• Definitions
  Background Block Label Lamp Leds Pushbuttons Slideswitch Turnswitch
• Keywords
  Angle Border Color Hue Image Label Light Name Position Size Slide State Steps Sticky Title Trigger Type Value
• Actions
  Buttonpress Buttonrelease Keypress Keyrelease Push Slide Turn
• Custom widgets
• Color chart

Widget resources

Initial widgets for application window can be created by using the widget definition file. Widget definitions compiles to C, and is further compiled and linked as static part of the application. Provided widget definition compiler is written in perl, which handles widget syntax explained below. When widget definitions is compiled, resulting file widget_defs.h is produced. Compatible file can be produced by some other mechanism if provided compiler or widget definition syntax feels discomfortable.

Widget resource compiler expects input file to be UTF-8 encoded, and supports include-directive, so resource file can be divided into several files:

include "the_other_widget_file.w2c"

In addition to widget definition file, widget_*() functions can be used to create and manipulate some of the widget parameters at runtime.

Provided widget set looks a bit like knobs in some old school audio equipment, see widgets example screenshots. Widget graphics can be replaced with some effort, see Custom widgets section at the bottom of this page for details.

Widget set has couple of widget types: background, block, label, lamp, led, pushbutton, turnswitch and slideswitch. Also support for toggleswitch widget exists, but no graphics is provided for it, therefore it is not documented here. There is no support for widgets familiar in other, more general user interface libraries, like scrollable text lists, text input fields, or ordinary rectangular and gray buttons with text in it. User interface can be extended in to that direction, for example, by using Redtools requester library, which is a part of Detroit engine.

Definitions

Widget definition file has widgets listed in top of each other. Before any widget definitions there must be a window definition to tell which window the following widgets are drawn. This value must match to WIDGET_STACK_ID which is passed to window_open() function when window is created in Ano script.

Inside the window block, a set block must be defined. One or more widget can form a set. Visible widget set can be changed by calling widget_change_set() function which takes set number as parameter. Set 0 is a special case, widgets defined under this set are always on window regardless of the currently active set, in other words, they are member of every set.

Widget definition file can also contain header tags to affect widget appearance and set some common defaults. Tags must be commented out and they must start with @. Tags include:

@WIDGET_DEFAULT_COLOR			rgb:#ffffff
					default widget color, for example block

@WIDGET_DEFAULT_HUE			0
					default widget hue value

@WIDGET_DEFAULT_LIGHT			no
					default lamp or led light on state, yes or no

@WIDGET_DEFAULT_STATE			enable
					default widget state, enabled or disabled

@WIDGET_DEFAULT_STICKY			no
					default pushbutton mode, can be yes or no

@WIDGET_DEFAULT_TITLE_CHARSET		UTF-8
					default title charset

@WIDGET_DEFAULT_TITLE_COLOR		rgb:#ffffff
					default title font color

@WIDGET_DEFAULT_TITLE_DPI		96
					default title font DPI

@WIDGET_DEFAULT_TITLE_FONT		path_to_the_font_file
					default title font file

@WIDGET_DEFAULT_TITLE_JUSTIFICATION	center
					default title justification

@WIDGET_DEFAULT_TITLE_POSITION		above
					default title position relative to widget

@WIDGET_DEFAULT_TITLE_SIZE		11
					default title font size in 1/64th points

@WIDGET_DEFAULT_TRIGGER			constant
					default for widget 'trigger' parameter,
					can be one of: constant alias drag, or release
					alias once

@WIDGET_DEFAULT_TYPE			0
					default for widget 'type' parameter

@WIDGET_DEFAULT_VALUE			0
					default for widget 'value' parameter

@WIDGET_USE_BOUNDING_BOXES		no
					if set to yes, draw a bounding box around the
					widget and its shadow, for debug use only to
					help leveling

Widget example, this is Vesmir example program widget definition:

;
; @WIDGET_USE_BOUNDING_BOXES no
;

window "1" {
	set "0" {
		widget "background" {
			name		"background"
			state		enable

			image		"examples/datafiles/background.tga"
		}

		widget "label" {
			name		"help"
			state		enable

			position	x = 20, y = 580

			label		"LMB + mouse to move view, wheel to zoom, enter to select, backspace to previous view", \
					charset = UTF-8, size = 8, \
					color = rgb:#ffffff, \
					justification = left
		}

		widget "pushbutton_2"
			name		"render_object"
			state		enable
			type		3

			position	x = 40, y = 100

			title		"Render object", \
					charset = UTF-8, size = 10, \
					color = rgb:#ffffff, \
					justification = center, \
					position = above, x = 0, y = -10

			sticky		no

			action		push = cb_push_renderobject
		}

		widget "pushbutton_2" {
			name		"print_object"
			state		enable
			type		3

			position	x = 160, y = 100

			title		"Print object", \
					charset = UTF-8, size = 10, \
					color = rgb:#ffffff, \
					justification = center, \
					position = above, x = 0, y = -10

			sticky		no

			action		push = cb_push_printobject
		}

		widget "pushbutton_2" {
			name		"save_object"
			state		enable
			type		3

			position	x = 280, y = 100

			title		"Save object", \
					charset = UTF-8, size = 10, \
					color = rgb:#ffffff, \
					justification = center, \
					position = above, x = 0, y = -10

			sticky		no

			action		push = cb_push_saveobject
		}

		widget "pushbutton_2" {
			name		"view_reset"
			state		enable
			type		1

			position	x = 440, y = 100

			title		"View reset", \
					charset = UTF-8, size = 10, \
					color = rgb:#ffffff, \
					justification = center, \
					position = above, x = 0, y = -10

			sticky		no

			action		push = cb_push_viewreset
		}

		widget "pushbutton_2" {
			name		"time_reset"
			state		enable
			type		1

			position	x = 560, y = 100

			title		"Time reset", \
					charset = UTF-8, size = 10, \
					color = rgb:#ffffff, \
					justification = center, \
					position = above, x = 0, y = -10

			sticky		no

			action		push = cb_push_timereset
		}

		widget "turnswitch" {
			name		"time_warp"
			state		enable
			type		1

			position	x = 670, y = 60

			angle		min = 5, max = 355
			steps		start = 2, total = 1000

			title		"Time warp", \
					charset = UTF-8, size = 10, \
					color = rgb:#ffffff, \
					justification = center, \
					position = above, x = 0, y = -5

			trigger		constant

			action		turn = cb_turn_timewarp
		}
	}
}

Background

Background widget sets the window background. Background can be either solid color, a translucent color or an image file. If image file is too large for the window it will be cropped, too small file will be tiled to fill the whole window. If color is used instead of an image, alpha value can be used to adjust background widget translucency. Alpha value of zero makes completely transparent background, and alpha value of 255 makes completely opaque color.

Example:

widget "background" {
	name		"my_background"
	state		enable

; This color definition is 100% opaque (alpha is 0xff)
;	color		"rgba:0x804020ff"
; This color definition is 100% transparent (alpha is zero)
;	color		"rgba:#80402000"
	image		"@/path/background.tga"

	hue		0.0
	value		0.0
}

Block

Block window makes rectangular object filled either single color or image file. If image file is too large for the block size it will be cropped, too small file will be tiled to fill the whole block.

Example:

widget "block" {
	name		"my_block"
	state		enable

	position	x = 100, y = 100
	size		width = 400, height = 20

;	color		"rgb:ee4422"
	image		"@/path/block.tga"

	border		color = rgb:#ff00ff, thickness = 2

	action		keypress = cb_key_press
}

Label

Label widget makes a single line of text.

Example:

widget "label" {
	name		"my_label"
	state		enable

	position	x = 100, y = 100

	label		"This is label", \
			charset = UTF-8, font = , size = 16, dpi = 0, \
			color = rgb:#aa8844, \
			justification = left
}

Lamp

Lamp widget is just like any lamp, usually indicating something when it lights. Lamp has six subtypes, explained in type section below. Lamp can be set on and off by widget_step_set() function.

Example:

widget "lamp" {
	name		"my_lamp"
	state		enable
	type		1

	position	x = 100, y = 100

	title		"This is lamp", \
			charset = UTF-8, font = , size = 11, dpi = 0, \
			color = rgb:#aa8844, \
			justification = center, position = left, x = 20, y = 0

	light		no

	hue		0.0
}

Led_1, Led_2, Led_3

Led is like a lamp, but smaller, and usually indicates that some minor function is turned on. Led has three types; type 1 round shaped led, type 2 is horizontal rectangle, and type 3 is vertical rectangle. Each type has six subtypes, explained in type section below. Led can be set on and off by widget_step_set() function.

Example:

widget "led_1" {
	name		"my_led"
	state		enable
	type		1

	position	x = 100, y = 100

	title		"This is led", \
			charset = UTF-8, font = , size = 9, dpi = 0, \
			color = rgb:#aa8844, \
			justification = center, position = below, x = 0, y = 0

	light		no

	hue		0.0
}

Pushbutton_1, Pushbutton_2, Pushbutton_3

Pushbutton widget is the one to push to get something done. Pushbutton has three types; type 1 is small square button, type 2 is also a square but a bit bigger, and type 3 is shaped as horizontal rectangle. Each type has six subtypes, explained in type section below.

Example:

widget "pushbutton_1" {
	name		"my_pushbutton"
	state		enable
	type		1

	position	x = 100, y = 100

	title		"This is pushbutton", \
			charset = UTF-8, font = , size = 11, dpi = 0, \
			color = rgb:#aa8844, \
			justification = center, position = above, x = 0, y = 10

	sticky		yes

	hue		0.0

	action		push = cb_push, \
			keypress = cb_key_press, \
			buttonpress = cb_btn_press, \
			buttonrelease = cb_btn_release
}

Slideswitch

Slideswitch widget works like a slider in mixing table. Slideswitch has six subtypes, explained in type section below.

Example:

widget "slideswitch" {
	name		"my_slideswitch"
	state		enable
	type		1

	position	x = 100, y = 100

	slide		length = 150, start = 1, total = 100

	title		"This is slideswitch", \
			charset = UTF-8, font = , size = 11, dpi = 0, \
			color = rgb:#aa8844, \
			justification = center, position = above, x = 0, y = 0

;	trigger		release
	trigger		constant

	hue		0.0

	action		slide = cb_slide, \
			buttonpress = cb_btn_press, \
			buttonrelease = cb_btn_release
}

Turnswitch

Turnswitch widget is round-shaped knob which can be turned back and forth, like volume knob in audio amplifier. Turnswitch has six subtypes, explained in type section below.

Example:

widget "turnswitch" {
	name		"my_turnswitch"
	state		enable
	type		1

	position	x = 100, y = 100

	angle		min = 45, max = 315
	steps		start = 1, total = 100

	title		"This is turnswitch", \
			charset = UTF-8, font = , size = 11, dpi = 0, \
			color = rgb:#aa8844, \
			justification = center, position = above, x = 0, y = 0

;	trigger		release
	trigger		constant

	hue		0.0

	action		turn = cb_turn, \
			buttonpress = cb_btn_press, \
			buttonrelease = cb_btn_release
}

Keywords

Angle

Range of the widget. For example, volume knob's minimum range is around 45 and maximum usually around 315 degrees. Needed attributes:

• min, minimum allowed angle in degrees, minimum allowed value is 0
• max, maximum allowed angle in degrees, maximum allowed value is 359

Needed by: turnswitch.

Border

Border color, its alpha channel value (transparency) and thickness to draw around the widget. Set alpha channel value to zero not to draw border. Needed attributes:

• color, border color in rgba:#rrggbbaa (red, green, blue, alpha) format
• thickness, border thickness in pixels

Needed by: block.

Color

Widget color and alpha channel value (transparency). Color definition must be double quoted. Format is:

• rgba:#rrggbbaa

The pound sign # in front of rgba (red, green, blue, alpha) value is optional, it can be replaced with 0x or leave out completely, so valid format also includes:

• rgba:0xrrggbbaa
• rgba:rrggbbaa

Also, individual color components can be dropped out too:

• rgb:rrggbb, rgb (red, green, blue) color without alpha value
• r:rr, only red color component
• rb:rrbb, red and blue color components

Color definition supports X11 named colors in addition to above. For example, if color value is banana, it maps to rgb value of 0xe3cf57 (red: 0xe3, green: 0xcf, blue: 0x57). All possible color names are listed in color chart, and possibly system rgb.txt file, which usually located at <X11_root>/lib/X11/rgb.txt or somewhere nearby.

Supported by: block and background.

Hue

Adjust the hue value of the widget in HSV color space. This can, for example, use to finetune green lamp to look a bit more or less green. Hue value is measured in degrees on HSV color wheel where range starts from 0 (no adjust) to 359, where actual widget color stands at 0 degree position. Keep temperance in mind when setting hue values, as widget graphics are cached by hue value for faster drawing, which can take a considerably amount of memory.

Supported by: background, lamp, led_*, pushbutton_*, slideswitch, turnswitch.

Image

Image to use to fill the widget. If image file is too large for the widget it will be cropped, too small file will be tiled to fill the whole widget. Supported file formats for images are BMP and TGA, unpacked true color, alpha channel recommended for transparency. If this strings starts with @, it is substituted with application installation prefix, so if image is /where/ever/app/is/installed/share/images/someimage.tga, that can be written to widget definition as @/share/images/someimage.tga. Using this trick is recommended, because paths will work even if installation prefix changes.

Supported by: background and block.

Label

Label for the widget. Label string to be displayed must be defined as a first attribute in double quotes. Other needed attributes:

• charset, charset to use with this label, leave out for default
• color, label color as explained in color keyword section, leave out for default
• dpi, label dots per inch value, leave out or use 0 for default
• font, font file for this label, leave out for default
• justification, label justification, either left, right or center, or leave out for default
• size, label string size in 1/64th points, leave out for default

Additional attributes for title keyword:

• position, label string position relative to widget position, either above, below, left or right, or leave out for default
• x, label string horizontal finetune offset relative to widget coordinates
• y, label string vertical finetune offset relative to widget coordinates

Needed by: label, lamp, led_*, pushbutton_*, slideswitch, turnswitch.

Light

Either yes, enable, true or 1 if the light is on initially, or no, disable, false or 0 if not.

Needed by: lamp and led_*.

Name

Unique name or other identifier of the widget. Keep as short as possible. This must be supplied to almost all widget_*() functions.

Needed by: all.

Position

Widget position in pixels from upper left corner of the container window. Needed attributes:

• x, position in pixels from left edge of the container window
• y, position in pixels from top edge of the container window

Needed by: all except background.

Size

Widget dimensions in pixels. Needed attributes:

• width, width in pixels
• height, height in pixels

Needed by: block.

Slide

Slideswitch slider attributes. Attributes include:

• length, length of the slide in pixels, either horizontally or vertically, depending on slider type
• start, initial step for slider, starts counting from 0
• total, total steps within length of the slider

Needed by: slideswitch.

State

Initial state of the widget, either enable, true or 1 if the widget is initially enabled, or disable, false or 0 if not.

Needed by: all.

Steps

• start, initial step for the widget, starts counting from 0
• total, total steps between minimum and maximum angles, for example, volume knob may have 100 steps or so, while on/off knob has only two

Needed by: turnswitch.

Sticky

Makes button sticky. Sticky buttons keeps its position pressed until pressed again. Unsticky buttons pops back to off state when released. Can be either yes, enable, true or 1 if the button is sticky, or no, disable, false or 0 if not.

Needed by: pushbutton.

Title

See label.

Trigger

Set the callback function trigger mode, can be either constant alias drag or release alias once. Constant/drag means callback is called continuously while widget is being turn, release mode triggers callback only once when widget is released.

Needed by: slideswitch, turnswitch.

Type

Subtype of the widgets.

lamp and led_* subtypes are:

• 0, red light
• 1, orange light
• 2, white (blueish) light if lamp, yellow if led
• 3, green light
• 4, blue light
• 5, purple light

pushbutton_* subtypes are:

• 0, red button
• 1, yellow button
• 2, white button
• 3, green button
• 4, blue button
• 5, purple button

slideswitch subtypes are:

• 0, horizontal knob, looks like common mixing console slider
• 1, vertical version of the above
• 2, horizontal knob, like a thin slider usually seen in equalizers
• 3, vertical version of the above
• 4, horizontal round shaped slider
• 5, vertical version of the above

turnswitch subtypes are:

• 0, large chicken head knob
• 1, small chicken head knob
• 2, large flat-top knob
• 3, small flat-top knob
• 4, large seven-star knob
• 5, small seven-star knob

Needed by: lamp, led_*, pushbutton_*, slideswitch, turnswitch.

Value

Adjust color value of the widget in HSV color space. Color value is measured in degrees on HSV color wheel where range starts from 0 (no adjust) to 359, where actual widget color stands at 0 degree position.

Needed by: background

Actions

Most widgets can have Ano script callback functions attached to them for certain events. Each action event is explained below.

Buttonpress

Generic callback function to call when button is pressed on widget. Callback function must have six parameters as shown below. Each parameter is initialized as explained in XButtonEvent(3).

Supported by: all, including background.

Example:

callback cb_btn_press (_x, _y, _x_root, _y_root, _state, _button) {
	dump	_x
	dump	_y
	dump	_x_root
	dump	_y_root
	dump	_state
	dump	_button
}

Buttonrelease

Generic callback function to call when button is released on widget. Callback function must have six parameters as shown below. Each parameter is initialized as explained in XButtonEvent(3).

Supported by: all, including background.

Example:

callback cb_btn_release (_x, _y, _x_root, _y_root, _state, _button) {
	dump	_x
	dump	_y
	dump	_x_root
	dump	_y_root
	dump	_state
	dump	_button
}

Keypress

Generic callback function to call when key is pressed on widget. Callback function must have seven parameters as shown below. Each parameter is initialized as explained in XKeyEvent(3). The last parameter, key, is printable character of which key was pressed.

Supported by: all, including background.

Example:

callback cb_key_press (_x, _y, _x_root, _y_root, _state, _keycode, _key) {
	dump	_x
	dump	_y
	dump	_x_root
	dump	_y_root
	dump	_state
	dump	_keycode
	dump	_key
}

Keyrelease

Generic callback function to call when key is released on widget. Callback function must have seven parameters as shown below. Each parameter is initialized as explained in XKeyEvent(3). The last parameter, key, is printable character of which key was released.

Supported by: all, including background.

Example:

callback cb_key_release (_x, _y, _x_root, _y_root, _state, _keycode, _key) {
	dump	_x
	dump	_y
	dump	_x_root
	dump	_y_root
	dump	_state
	dump	_keycode
	dump	_key
}

Push

Pushbutton callback function to call when button is pushed. Callback function must have six parameters as shown below. Each parameter is initialized with current widget state.

Needed by: pushbutton_*

Example:

callback cb_push (_widget_name, _widget_id, _min, _max, _steps, _step) {
	dump	_widget_name
	dump	_widget_id
	dump	_min
	dump	_max
	dump	_steps
	dump	_step
}

Slide

Slideswitch callback function to call when switch is moved. Callback function must have six parameters as shown below. Each parameter is initialized with current widget state.

Needed by: slideswitch

Example:

callback cb_slide (_widget_name, _widget_id, _min, _length, _steps, _step) {
	dump	_widget_name
	dump	_widget_id
	dump	_min
	dump	_length
	dump	_steps
	dump	_step
}

Turn

Turnswitch callback function to call when switch is turned. Callback function must have six parameters as shown below. Each parameter is initialized with current widget state.

Needed by: turnswitch

Example:

callback cb_turn (_widget_name, _widget_id, _min, _max, _steps, _step) {
	dump	_widget_name
	dump	_widget_id
	dump	_min
	dump	_max
	dump	_steps
	dump	_step
}

Custom widgets

Every moving widget is made of image frames. Moving means that widget has more than one state, or user can turn it or press it in a way that widget image changes. For that we need image frames, one frame per widget state or step. For example, lamp has two images, on and off. Same with leds, they can be on and off, nothing more. Turnswitch is different, it can have hundreds of states, depending how many steps there is between min and max angles. Provided turnswitch widget contains 360 frames, one per angle. If memory is a concern, less frames may be better. It does not really matter how many frames turnswitch or any other widget has, engine has capability to automatically display a frame that best suits to current angle of the widget. Lamps and leds of course needs two frames in order them to work.

As said, to create own widget, we need a bunch of images which forms the animation. A good starting point is to have every frame in its own image file, any empty borders cropped off and resized to final resolution, like 64x64 pixels. Any areas meant to be transparent must have alpha value of zero. There is tools available for packing widget frames together to create properly formatted widget pack useable by the engine. Tools and some scripts for the job is located in engine/tools directory. Further details and instructions can be found in this tutorial.

Color chart

Color table supported by widget resource compiler. Color name can be used in place of RGB (Red, Green, Blue) value to get the color in preview column.

Copyright © 2024, Jani Salonen <salojan at goto10 piste co>. Piste is finnish word and means dot. All rights reserved.