IrisControlsAPI4 Overview

Iris Controls 4 Embedded Library

Iris Controls 4 (IC4) is a flexible application that allows users to operate and monitor Iris Dynamics devices from a Windows PC using over USB. The IC4 embedded library simplifies building GUIs to suit a wide variety of use cases by providing an object-based implementation of the IC4 serial API.

General Description

Iris Controls 4 is a Windows based application that displays a single main window in which a variety of different elements can be placed. The main window contains a grid of 20px by 20px squares. The number of rows and columns is set by the user. Elements are assigned a position using an origin row and column where (0,0) is the top left corner of the main window. They are given a size by assigning a row-span and column-span. For example, an element added with row = 3, column = 3, rowSpan = 2, columnSpan = 4 will occupy rows 3 and 4 between columns 3 and 6. Elements have a minimum size and if they are not assigned adequate row or column spans the elements will not be added.

Device Support

• "Eagle" controllers (ARM Cortex M4)
• "SuperEagle" controllers (Zynq7000)
• "Orca600" embedded motor drives (ARM Cortex M4)

Data Flow

Except for the initial handshake, data transactions are initiated by the device, and a response is sent from the GUI. In other words, the device will update the GUI with data, and will poll the GUI for changes to any of the interactive elements.

Handshaking

IC4 is configured to communicate with a single COM port (i.e. a single USB Serial device connected to the PC). When connection is enabled on IC4 and a valid COM port is selected, IC4 will periodically send a "ping" message and wait for a response. When a device running an IC4 server receives that ping, it will respond with its device ID, the IC4 serial API version, the IC4 server name, and some other information. IC4 responds with an acknowledgement when a compatible API version is detected. A CRC is completed to ensure the handshake's data is not corrupted in transmission. At this point, the handshaking is considered complete and the device is free to start the data flow.

Initial Challenge

Iris Controls periodically sends \x02\x06\r to the device.

Initial Challenge Response

After receiving the initial challenge, the device will transmit \x02\x06 COMMUNICATIONS_PROTOCOL DEVICE_ID IC_SERIAL_API_VERSION SERVER_NAME which includes:

• COMMUNICATIONS_PROTOCOL - The communications protocol in use, half or full duplex.
• DEVICE_ID - The device id located in the config.h file of the device firmware.
• IC_SERIAL_API_VERSION - The version of the Iris Controls Serial API in use.
• SERVER_NAME - The Iris Controls server name.
• TIME_STAMP - A time stamp used in data plotting to record accurate data capture times.
• TIMEOUT_TIMER - The timeout timer duration in ms.

Connection Established

Upon successful reception of the response, Iris Controls will send \x02\x01\r which indicates to the device that it can begin normal communications. At this stage, if in half duplex communication mode, Iris Controls will not transmit again until receiving an end of transmission token from the device.

Iris Controls will also generate (or add to if already generated) a connection log file and record the device parameters as passed in the handshake.

General Operation

The device will issue a stream of serial data, which could include element data updates (e.g. moving sliders), new elements, removing elements, log file entries, etc. Periodically, the device will also issue a "clear to send" token (\x02\x04\r) followed by silence, which indicates to IC4 that it should send a response. The response from IC4 may be an acknowledgement alone, or may contain information about user interaction with relevant GUI elements (e.g. they pressed a button). Even when no interaction is detected since the last message, IC must respond as the device is checking for an active connection as well as monitoring user interaction.

Disconnection

When in half-duplex mode, IC4 must wait until issued a "clear to send" command before sending the "disconnect" command to the device.

Connection Status

The connection status of Iris Controls can be queried by calling any of the following functions.

is_connected();

is_disconnected();

is_timed_out();

New Connection

A new connection can be detected by calling new_connection(); which returns true upon first establishing connection.

This can be used to trigger a setup loop in an application.

Connection Timeout

At handshake, the device transmits the timeout duration. Iris Controls and the device will both run timers of this duration. If the timer on either end expires, a timeout condition will be entered.

Iris Controls Timeout Condition

Iris Controls disables input to all I/O elements (except the console) during a timeout condition. Output elements (e.g. plots, labels, and sliders) remain in place with their last output displayed. Iris Controls adds an opacity mask to help notify the user that a timeout condition has been entered. This state persists until the Connect/Disconnect button in the console is pressed at which time the GUI returns to its boot state.

Device Timeout Condition

The timeout behaviour of a given device varies with different device firmware.

Handling Timeout Conditions

In order to execute any re-connection functions, an application can call restored_connection(); which returns true if the previous connection was interrupted.

The function set_disconnected(); can be called to set the connection status of the device to disconnected.

Disconnected

When the connection state is disconnected, bytes must be received at intervals of no more than 50ms. If an interval greater than 50ms occurs in the middle of a message, the receive buffer is reset to ensure that spurious signals are not stored in the receive buffer between sessions.

Device State

A cyclic redundancy check method has been implemented to check that the device and Iris Controls 4 are synchronous with respect to the state of the various GUI elements being displayed to the user. This check can be user initiated by using the console command crc or the device can initiate it by calling device_state_check();. The result of the CRC is displayed in the console.

Configuration Files

Some devices make use of console commands to setup various parameters within their firmware. Iris Controls can load configuration files which can contain many console commands. These files can be loaded in three ways:

1. The settings dialog via a Windows file browser.
2. The "load" console command.
3. The device requesting it via the API command below.

Once loaded, the commands within the configuration file are sent to the device as console messages one line at a time with a 250ms pause between each one.

Configuration File Format

Iris Controls will ignore all content in a configuration file until it encounters a line containing only START after which every line (except for wait commands) is transmitted through the console. To add a longer delay between console messages, a wait command can be included in the configuration file. Including wait(delay) will cause the delay at that point in the file to be 250 + delay in milliseconds.

API Commands

A connected device may call for a configuration file to be loaded.

Configuration File

Name	Syntax			Notes
	arg	type	argument description
Load Config File	Loads a configuration file with the filename.
load_config_file(filename);	filename	const char *	The file name of the config file (e.g. "config_file.txt")

General GUI Management

Each Iris Controls 4 GUI is a collection of elements that are placed on a grid of rows and columns. Each row/column is 20px tall/wide. At launch, the GUI contains and is only large enough to contain, the console. The device GUI must send a set_grid(rows, columns) command to set the number of rows and columns before placing any further elements.

• Ensure that the number of rows and columns requested will fit on the display in use. The Inject Delay command can be used to smooth GUI view/page change operations.
• Consider whether or not Windows is using other than 100% scaling on the display in use as Windows scaling will cause the fonts used in element labels to change but the size of the element itself will not. This may cause the label of, for example, A Flex Button to overflow its boundaries. If commanded to create a button with an oversized label, Iris Controls 4 will reject that request.
• Limit GUI element quantity to fewer than 9000 elements. Using more elements than this may result in undefined behaviour.

API Commands

General GUI Commands

Name	Syntax			Notes
	arg	type	argument description
Set Grid	Sets the number of rows and columns of the grid
gui_set_grid(rows, columns);	rows	u16	The number of rows to set.	(1)
	columns	u16	The number of columns to set.
Query Max Grid	Sends a query to IrisControls which returns the max allowable number of rows and columns
gui_query_max_grid();
Set Max Grid	Sets the GUI to the maximum valid number of rows and columns
gui_set_max_grid();
Inject Delay	Injects a delay into the serial communications thread in Iris Controls 4
delay(delay_length);	delay_length	u16	The length of the delay in ms.	(2)
Disconnect	Initiates a disconnect
disconnect();
Set Element Default Colour	Sets the default colour of an aspect of the specified Flex Element
set_default_colour(element_type, element_aspect, r, g, b, a);	element_type	u16	The type of Flex Element.	(3)(4)
	element_aspect	u16	The aspect of the element to change (e.g. text colour, or border colour).
	r	u16	The "red" value.
	g	u16	The "green" value.
	b	u16	The "blue" value.
	a	u16	The "alpha" value.
Restore Default Colours	Restores all element colours to their default value.
restore_default_colours();
Assign Keyboard Shortcut	Connects a shortcut keyboard key to a target FlexElement.
assign_keyboard_shortcut(key, target_id);	key	int	The keyboard key that will initiate the shortcut.	(5)
	target_id	u16	The id of the element to be activated when the key is pressed.
Set Main Window Title	Sets the title in the top left corner of the main window of Iris Controls.
set_main_window_title(title);	title	const char*	The new title.	(6)

Notes:

1. The display in use must be large enough to allow for a each row/column to be at least 20px tall/wide.
2. Maximum delay time is 100ms.
3. See table below for allowed element types.
4. See table in Set Colour for available options.
5. See here for a list of permissible key values.
6. There is a 100 character limit.

Element Types

Flex Element	Value
Flex Button	FlexElement::FLEXBUTTON
Flex Slider	FlexElement::FLEXSLIDER
Flex Label	FlexElement::FLEXLABEL
Flex Data	FlexElement::FLEXDATA
Flex Plot	FlexElement::FLEXPLOT

The Console

The Console is the only element visible upon launching IrisControls. It is located at the origin (0,0) and occupies 20 rows and 10 columns. The Console provides user feedback on IrisControls and motor operations as well as handling the USB connection. Upon establishing the USB connection, the console can be moved and/or resized.

Constructor

The Console is automatically constructed by the GUI.

API Commands

Console Commands

Name	Syntax			Notes
	arg	type	argument description
Hide	Hides the Console
console.hide();
Show	Reveals the Console
console.show();
Move	Moves the Console to a new position
console.move(row, column);	row	u16	The new row.	(1)
	column	u16	The new column.
Resize	Resizes the Console
console.resize(rowSpan, columnSpan);	rowSpan	u16	The new row span.
	columnSpan	u16	The new column span.
Set Colour	Sets the colour of the specified aspect of the Console.
console.set_colour(config, r, g, b, a);	config	Console::COLOUR_SET_FLAG	A flag to indicated which aspect of the Console to colour.
	r	u16	The "red" value.
	g	u16	The "green" value.
	b	u16	The "blue" value.
	a	u16	The "alpha" value.
Reset to Default Colours	Resets any colour changes that were made.
console.reset_default_colours();

GUI Page

The GUI Page class is used to group elements into pages or views. They help simplify changing pages by reducing the source code and the serial connection bandwidth required to accomplish this. A call of a GUI Pages's show or hide method will show or hide all child elements of that GUI Page.

NOTE: You can assign a GUI page to an element when making that element's add call. Doing so means there is no need to use the GUI_Page::add_element method defined below.

Constructor

No arguments need to be passed in a GUI Page constructor.

Example:

GUI_Page gui_page();

API Commands

Instance Methods

Name	Syntax			Notes
	arg	type	argument description
Add a GUI Page	Adds the GUI page.			(1)
gui_page.add();
Remove a GUI Page	Removes the GUI page.
gui_page.remove();
Add element to GUI Page	Adds a Flex Element to the GUI Page.
gui_page.add_element(flex_element);	flex_element	FlexElement*	A pointer to the Flex Element to add.
Remove element from GUI Page	Removes a Flex Element from the GUI Page.
gui_page.remove_element(flex_element);	flex_element	FlexElement*	A pointer to the Flex Element to remove.
Show GUI Page	Shows all child elements of the GUI Page.
gui_page.show();
Hide GUI Page	Hides all child elements of the GUI Page.
gui_page.hide();

1. This must be called before adding any element that has gui_page as a parent.

Flex Element

Inherited by Flex Button, Flex Slider, Flex Label, Flex Data, and Flex Plot.

Constructor

There is no need to construct Flex Elements directly.

API Commands

The following API commands are common to all Flex Elements.

Instance Methods

Name	Syntax			Notes
	arg	type	argument description
Show Element	Reveals the element
flexelement.show();
Hide Element	Hides the element
flexelement.hide();
Move Element	Moves the element
flexelement.move(row, column);	row	u16	The new row.	(1)
	column	u16	The new column.
Resize Element	Resizes the element
flexelement.resize(rowSpan, columnSpan);	rowSpan	u16	The new row span.
	columnSpan	u16	The new column span.
Rename Element	Changes the visible label of the element
flexelement.rename(name);	name	string	The new name.
Delete Element	Deletes the element
flexelement.remove();
Disable/Enable Element	Disables/Enables the element
flexelement.disable(status);	status	bool	True = disable, False = enable
Set Colour	Sets the colour of the Flex Element
flexelement.set_colour(config, r, g, b, a);	config	COLOUR_SET_FLAG	A flag to indicated which aspect of the element to colour.	(2)
	r	u16	The "red" value.
	g	u16	The "green" value.
	b	u16	The "blue" value.
	a	u16	The "alpha" value.
Set Font Size	Sets the font size of the selected sub-element of the element.
set_font_size(sub_element, font_size);	sub_element	FlexElement::SUBELEMENT_TYPE	The sub-element to be altered (e.g. Label, Values, Units...)
	font_size	u16	The new point size of the font.

1. The new position must be valid (i.e. not already occupied by a non-hidden element and not wholly or partially out of bounds). If the position is not valid the element will stay in its original position. Hidden elements can be moved on top of other elements but must remain in bounds.
2. See the configuration table below.

Static Methods

Name	Syntax			Notes
	arg	type	argument description
Reset All Default Colours	Resets all element default colours.
FlexElement::reset_all_default_colours();

Colour Change API

Flex Button

Description	Config Value
Changes colour of the button's default text.	FlexButton::TEXT
Changes colour of the button's default background.	FlexButton::BACKGROUND
Changes colour of the button's default border.	FlexButton::BORDER
Changes colour of the button's checked text.	FlexButton::CHECKED_TEXT
Changes colour of the button's checked background.	FlexButton::CHECKED_BACKGROUND
Changes colour of the button's checked border.	FlexButton::CHECKED_BORDER
Changes colour of the button's pressed text.	FlexButton::PRESSED_TEXT
Changes colour of the button's pressed background.	FlexButton::PRESSED_BACKGROUND
Changes colour of the button's pressed border.	FlexButton::PRESSED_BORDER
Changes colour of the button's hover text.	FlexButton::HOVER_TEXT
Changes colour of the button's hover background while unchecked.	FlexButton::HOVER_BACKGROUND_NORMAL
Changes colour of the button's hover background while checked.	FlexButton::HOVER_BACKGROUND_CHECKED
Changes colour of the button's hover border.	FlexButton::HOVER_BORDER
Changes colour of the button's text while disabled.	FlexButton::DISABLED_TEXT
Changes colour of the button's background while unchecked and disabled.	FlexButton::DISABLED_BACKGROUND_NORMAL
Changes colour of the button's background while checked and disabled.	FlexButton::DISABLED_BACKGROUND_CHECKED
Changes colour of the button's border while disabled.	FlexButton::DISABLED_BORDER

Flex Slider

Description	Config Value
Changes colour of the label's text.	FlexSlider::LABEL_TEXT
Changes colour of the label's background.	FlexSlider::LABEL_BACKGROUND
Changes colour of the slider's background.	FlexSlider::SLIDER_BACKGROUND
Changes colour of the slider's groove left of the handle.	FlexSlider::SLIDER_SUBPAGE
Changes colour of the slider's groove right of the handle.	FlexSlider::SLIDER_ADDPAGE
Changes colour of the slider's handle.	FlexSlider::HANDLE_COLOUR
Changes colour of the slider's handle while the mouse is hovering over it.	FlexSlider::HANDLE_HOVER
Changes colour of the slider's handle while it is pressed by the mouse.	FlexSlider::HANDLE_PRESSED
Changes colour of the slider's handle when it is disabled (output only).	FlexSlider::HANDLE_DISABLED
Changes colour of the value's text.	FlexSlider::VALUE_TEXT
Changes colour of the value's background.	FlexSlider::VALUE_BACKGROUND
Changes colour of the units' text.	FlexSlider::UNITS_TEXT
Changes colour of the units' background.	FlexSlider::UNITS_BACKGROUND

Flex Label

Description	Config Value
Changes the text colour.	FlexLabel::TEXT
Changes the background colour.	FlexLabel::BACKGROUND

Flex Data

Description	Config Value
Changes the label's text colour.	FlexData::LABEL_TEXT
Changes the label's background colour.	FlexData::LABEL_BACKGROUND
Changes the value's text colour.	FlexData::VALUE_TEXT
Changes the value's background colour.	FlexData::VALUE_BACKGROUND
Changes the units' text colour.	FlexData::UNITS_TEXT
Changes the units' background colour.	FlexData::UNITS_BACKGROUND

Flex Plot

Description	Config Value
Changes colour of all text including the legend, graph name, and tick labels.	FlexPlot::TEXT
Changes the background colour of the plot and legend.	FlexPlot::BACKGROUND
Changes the colour of the frame and tick marks.	FlexPlot::FRAME
Changes the colour of button text.	FlexPlot::BUTTON_TEXT
Changes the background colour of buttons.	FlexPlot::BUTTON_BACKGROUND
Changes the border colour of buttons.	FlexPlot::BUTTON_BORDER
Changes the text colour of buttons while checked.	FlexPlot::BUTTON_CHECKED_TEXT
Changes the background colour of buttons while checked.	FlexPlot::BUTTON_CHECKED_BACKGROUND
Changes the border colour of buttons while checked.	FlexPlot::BUTTON_CHECKED_BORDER
Changes the text colour of buttons while pressed.	FlexPlot::BUTTON_PRESSED_TEXT
Changes the background colour of buttons while pressed.	FlexPlot::BUTTON_PRESSED_BACKGROUND
Changes the border colour of buttons while pressed.	FlexPlot::BUTTON_PRESSED_BORDER
Changes the text colour of buttons while being hovered.	FlexPlot::BUTTON_HOVER_TEXT
Changes the background colour of unchecked buttons while being hovered.	FlexPlot::BUTTON_HOVER_BACKGROUND_NORMAL
Changes the background colour of checked buttons while being hovered.	FlexPlot::BUTTON_HOVER_BACKGROUND_CHECKED
Changes the border colour of buttons while being hovered.	FlexPlot::BUTTON_HOVER_BORDER
Changes the text colour of comboboxes.	FlexPlot::COMBOBOX_TEXT_COLOUR
Changes the background colour of comboboxes.	FlexPlot::COMBOBOX_BACKGROUND_COLOUR
Changes the border colour of comboboxes.	FlexPlot::COMBOBOX_BORDER_COLOUR
Changes the background colour of checked comboboxes.	FlexPlot::COMBOBOX_CHECKED_BACKGROUND
Changes the border colour of comboboxes while being hovered.	FlexPlot::COMBOBOX_HOVER_BORDER
Changes the colour of the grid pattern on the plot.	FlexPlot::GRID

Console

Description	Config Value
Changes the colour of the title text.	CONSOLE::TITLE_TEXT
Changes the colour of the title background.	CONSOLE::TITLE_BACKGROUND
Changes the colour of the output field text.	CONSOLE::OUTPUT_TEXT
Changes the colour of the output field background.	CONSOLE::OUTPUT_BACKGROUND
Changes the colour of the input field text.	CONSOLE::INPUT_TEXT
Changes the colour of the input field background.	CONSOLE::INPUT_BACKGROUND
Changes the colour of the control button text (Settings Dialog button, Info button, and Clear button).	CONSOLE::CONTROL_BUTTON_TEXT
Changes the colour of the control button background (Settings Dialog button, Info button, and Clear button).	CONSOLE::CONTROL_BUTTON_BACKGROUND
Changes the colour of the control button border (Settings Dialog button, Info button, and Clear button).	CONSOLE::CONTROL_BUTTON_BORDER
Changes the colour of the control button text while being pressed (Settings Dialog button, Info button, and Clear button).	CONSOLE::CONTROL_BUTTON_PRESSED_TEXT
Changes the colour of the control button background while being pressed (Settings Dialog button, Info button, and Clear button).	CONSOLE::CONTROL_BUTTON_PRESSED_BACKGROUND
Changes the colour of the control button border while being pressed (Settings Dialog button, Info button, and Clear button).	CONSOLE::CONTROL_BUTTON_PRESSED_BORDER
Changes the colour of the control button text while being hovered (Settings Dialog button, Info button, and Clear button).	CONSOLE::CONTROL_BUTTON_HOVER_TEXT
Changes the colour of the control button background while being hovered (Settings Dialog button, Info button, and Clear button).	CONSOLE::CONTROL_BUTTON_HOVER_BACKGROUND
Changes the colour of the control button border while being hovered (Settings Dialog button, Info button, and Clear button).	CONSOLE::CONTROL_BUTTON_HOVER_BORDER
Changes the colour of the connect button text.	CONSOLE::CONNECT_BUTTON_TEXT
Changes the colour of the connect button background.	CONSOLE::CONNECT_BUTTON_BACKGROUND
Changes the colour of the connect button border.	CONSOLE::CONNECT_BUTTON_BORDER
Changes the colour of the connect button text when the button is checked.	CONSOLE::CONNECT_BUTTON_CHECKED_TEXT
Changes the colour of the connect button background when the button is checked.	CONSOLE::CONNECT_BUTTON_CHECKED_BACKGROUND
Changes the colour of the connect button border when the button is checked.	CONSOLE::CONNECT_BUTTON_CHECKED_BORDER
Changes the colour of the connect button text when the button is pressed.	CONSOLE::CONNECT_BUTTON_PRESSED_TEXT
Changes the colour of the connect button background when the button is pressed.	CONSOLE::CONNECT_BUTTON_PRESSED_BACKGROUND
Changes the colour of the connect button border when the button is pressed.	CONSOLE::CONNECT_BUTTON_PRESSED_BORDER
Changes the colour of the connect button text when the button is hovered.	CONSOLE::CONNECT_BUTTON_HOVER_TEXT
Changes the colour of the connect button background when the button is hovered and not checked.	CONSOLE::CONNECT_BUTTON_HOVER_BACKGROUND_NORMAL
Changes the colour of the connect button background when the button is hovered and checked.	CONSOLE::CONNECT_BUTTON_HOVER_BACKGROUND_CHECKED
Changes the colour of the connect button border when the button is hovered.	CONSOLE::CONNECT_BUTTON_HOVER_BORDER
Changes the colour of the COM select menu text.	CONSOLE::COM_SELECT_TEXT_COLOUR
Changes the colour of the traffic display's plain text.	CONSOLE::TRAFFIC_PLAIN_TEXT
Changes the colour of the traffic display's up text and plot.	CONSOLE::TRAFFIC_UP
Changes the colour of the traffic display's down text and plot.	CONSOLE::TRAFFIC_DOWN
Changes the colour of the traffic display's fps text and plot.	CONSOLE::TRAFFIC_FPS
Changes the colour of the traffic display's background.	CONSOLE::TRAFFIC_BACKGROUND

User Interaction with Elements

Users will interact with GUI elements in many ways including clicking a button or dragging a slider to a new value. In order to improve GUI frame efficiency, the GUI's run loop can query whether or not an element has been updated since the last time it was checked. If it has not, the GUI need not check each individual element for updates.

It is also possible to query individual elements to see if they have been updated since the last check.

Flex Elements

Name	Syntax			Notes
	argument description
Check For Element Updates	Returns true when any element has changed since the last check.
check_for_element_updates();
Check For Element Click Updates	Returns true when any element has been pressed or toggled since the last check.
is_button_updated();
Check For Value Updates	Returns true when any element has had a change in value since the last check.
is_value_updated();
Check Element For Value Updates	Returns true when the element has had a change in value since the last check.
flex_element.new_value_received();	flex_element	IO_thing	The element to be queried for changes.	(1)

1. All FlexElements with values are IO_things.

Special Character Parsing

Iris Controls can parse keywords into special symbols. For example, when naming an element or setting the units of a slider, the following keywords will be parsed as symbols:

Keyword Parsing

Keyword	Parses To
*deg*	°
*degC*	°C
*alpha*	α
*c*	©
*mu*	µ
*ohm*	Ω

Flex Button

Inherits: Flex Element

Flex Buttons are push buttons that the user can press or toggle. Toggling a button is like checking a box, the button has two states: toggled and not toggled.

Constructor

No arguments need to be passed in a Flex Button constructor.

Example:

FlexButton flexbutton();

API Commands

Instance Methods

Name	Syntax			Notes
	arg	type	argument description
Add Flex Button	Adds a new Flex Button
flexbutton.add(name, initValue, row, column, rowSpan, columnSpan); or flexbutton.add(parent, name, initValue, row, column, rowSpan, columnSpan);	parent	GUI_Page*	A pointer to the parent GUI Page.
	name	const char*	The name and display text of the button.
	initValue	int	The initial value of the button. 1 = toggled, 0 = not toggled, -1 = not toggleable.
	row	u16	The row the button is to be placed in.
	column	u16	The column the button is to be placed in.
	rowSpan	u16	The number of rows the button will span.
	columnSpan	u16	The number of columns the button will span.
Set Toggle	Changes the button's toggled state
flexbutton.set_toggle(status);	status	int	1 = toggled, 0 = not toggled
Reset Colours	Resets this instance's colours to defaults.
flexbutton.reset_this_flexbutton_default_colours();

Static Methods

Name	Syntax			Notes
	arg	type	argument description
Set Default Colour	Sets the Default Colour of an Aspect of the Element
FlexButton::set_default_colour(flag, r, g, b, a);	flag	FlexButton::COLOUR_SET_FLAG	The aspect of the element to change.	(1)
	r	u16	The "red" value.
	g	u16	The "green" value.
	b	u16	The "blue" value.
	a	u16	The "alpha" value.
Reset All FlexButton Default Colours	Resets all FlexButton default colours.
FlexButton::reset_all_flexbutton_default_colours();

1. See table for allowed element aspects.

Feedback

Users can interact with Flex Buttons in two ways: pressing and toggling. There are three ways to check the state of a Flex Button.

Flex Buttons

Name	Syntax			Notes
	arg	type	argument description
Get	Returns the current value of the button. A toggled button's value is 1. An un-toggled button's value is 0.
flexbutton.get();
Pressed	Returns true (1) if the button was pressed since the last time this function was called. Returns false (0) otherwise.
flexbutton.pressed();
Toggled	Returns true (1) if the button was toggled since the last time this function was called. Returns false (0) otherwise.
flexbutton.toggled();

Flex Slider

Inherits: Flex Element

Flex Sliders are objects made up of a label, a horizontal slider, and an input/output text box. They can be created as either input/output devices or strictly output ones. As input devices, users can drag the slider with a mouse, or type a value into the text box. Either method of entry will update the other and report the new value over the USB connection.

Denominators

Principles

A denominator can be applied to the output value of the Flex Slider in order to accomplish a unit conversion. In essence, all values sent to the slider will be divided by the denominator while all values coming from the slider will be multiplied by the denominator.

For example, if you wish to display a frequency value that is expressed in Hz, a denominator of 1000 can be applied to an output slider to display frequency in kHz. flexslider.update(1000); will display on the slider as 1. In this case, when adding the slider, use "kHz" for the units field.

Building the Slider

When choosing minimum and maximum values for a slider with a denominator, choose values that have already had the denominator applied. For example, if a slider with denominator 1000 should accept values between -20,000 and +20,000, the apparent minimum and maximum values will be -20,000/1000 = -20 and 20,000/1000 = 20 respectively.

The initial value and all subsequent updates will have the denominated applied to them, so to see an initial value of 10, the initial value should be 10,000 when using a denominator of 1000.

Transfer of Data

When updating a slider by calling flexslider.update(value);, the value displayed will always be value/denominator.

When retrieving a slider's data by calling flexslider.get(); the value returned will be the slider's apparent value times the denominator.

For example, a slider with denominator 1000 has flexslider.update(2000); called. It will show as 2. If flexslider.get(); is called for that same slider, it will return 2000.

Constructor

No arguments need to be passed in a Flex Slider constructor.

Example:

FlexSlider flexslider();

API Commands

Instance Methods

Name	Syntax			Notes
	arg	type	argument description
Add Flex Slider	Adds a new Flex Slider
flexslider.add(name, row, column, rowSpan, columnSpan, min, max, initValue, denominator, config); or flexslider.add(parent, name, row, column, rowSpan, columnSpan, min, max, initValue, denominator, config); or flexslider.add(name, row, column, rowSpan, columnSpan, min, max, initValue, denominator); or flexslider.add(parent, name, row, column, rowSpan, columnSpan, min, max, initValue, denominator);	parent	GUI_Page*	A pointer to the parent GUI Page.	(1)
	name	const char*	The name and visible label of the slider.
	row	u16	The row the slider is to be placed in.
	column	u16	The row the slider is to be placed in.
	rowSpan	u16	The number of rows the slider will span.
	columnSpan	u16	The number of columns the slider will span.
	min	int / double	The minimum value the slider can display.
	max	int / double	The maximum value the slider can display.
	initValue	int / double	The initial value the slider will hold.
	denominator	u16	The factor by which values are divided before being displayed (e.g. if denominator = 100 then flexslider.update(1000); displays 10.)
	config	u16	A configuration flag. See the configuration section below. (optional)
Add Flex Slider	Adds a new Flex Slider With Units
flexslider.add(name, row, column, rowSpan, columnSpan, min, max, initValue, denominator, units, config); or flexslider.add(parent, name, row, column, rowSpan, columnSpan, min, max, initValue, denominator, units, config); or flexslider.add(name, row, column, rowSpan, columnSpan, min, max, initValue, denominator, units); or flexslider.add(parent, name, row, column, rowSpan, columnSpan, min, max, initValue, denominator, units);	parent	GUI_Page*	A pointer to the parent GUI Page.	(1)
	name	const char*	The name and visible label of the slider.
	row	u16	The row the slider is to be placed in.
	column	u16	The row the slider is to be placed in.
	rowSpan	u16	The number of rows the slider will span.
	columnSpan	u16	The number of columns the slider will span.
	min	int / double	The minimum value the slider can display.
	max	int / double	The maximum value the slider can display.
	initValue	int / double	The initial value the slider will hold.
	denominator	u16	The factor by which values are divided before being displayed (e.g. if denominator = 100 then flexslider.update(1000); displays 10.)
	units	string	Display name of the units field. Must not contain whitespaces; underscores are converted to whitespace.
	config	u16	A configuration flag. See the configuration section below. (optional)
Re-Configure Flex Slider	Re-Configure Flex Slider
flexslider.config(configuration);	configuration	u16	The new configuration flag.
Update Flex Slider	Sets the slider to a new value
flexslider.update(int value); flexslider.update(u16 value); flexslider.update(u32 value); flexslider.update(s32 value); flexslider.update(float value);	value	int u16 u32 s32 float	The new value of the slider.
Set Slider Range	Sets the minimum and maximum values the slider can display
flexslider.set_range(min, max);	min	s32	The minimum value the slider can display.	(2)
	max	s32	The maximum value the slider can display.
Reset Colours	Resets this instance's colours to defaults.
flexslider.reset_this_flexslider_default_colours();

1. Note: min, maximum, and initValue may be all integers or all doubles but no combination of types is accepted.
2. Sliders may be updated with values outside their range. In this case, the written value will reflect the actual value while the slider handle remains at its minimum/maximum limit.

Static Methods

Name	Syntax			Notes
	arg	type	argument description
Set Default Colour	Sets the Default Colour of an Aspect of the Element
FlexSlider::set_default_colour(flag, r, g, b, a);	flag	FlexSlider::COLOUR_SET_FLAG	The aspect of the element to change.	(1)
	r	u16	The "red" value.
	g	u16	The "green" value.
	b	u16	The "blue" value.
	a	u16	The "alpha" value.
Reset All FlexSlider Default Colours	Resets all FlexSlider default colours.
FlexSlider::reset_all_flexslider_default_colours();

1. See table for allowed element aspects.

Configuration

Flex Sliders have a variety of configuration options.

Configuration

Configuration Element	Description	Config Value
Input	Allows the Flex Slider to be used as an input device. (1)	FlexSlider::ALLOW_INPUT
Not Tracking	Prevents the slider from sending updates as it is dragged. If this is selected, it only update the device when the user stops dragging with the mouse. It will not update when using the keyboard or mouse wheel to adjust the slider value.	FlexSlider::NOT_TRACKING
Units Field	Adds a text field to the right of the slider's value that can display units or other useful data.	FlexSlider::UNITS
Frame	Draws a frame around the value box.	FlexSlider::FRAME
Digits of Precision	Sets the number of decimal places for the slider where X is an int between 1 and 7.	FlexSlider::PRECISION_X
Mirrored	Horizontally mirrors the slider.	FlexSlider::MIRRORED
Size of Value	Sets the number of digits the value can hold where X is an int (1-8, 10, 12, 14, 18, 22, 26, 30, or 34). The default is 7 digits.	FlexSlider::DIGITS_X
Binary Numerical System	Sets the numerical system to binary. Output is shown in binary format.	FlexSlider::BINARY
Hexadecimal Numerical System	Sets the numerical system to hexadecimal. Output is shown in hexadecimal format.	FlexSlider::HEXADECIMAL
Unsigned Decimal System	Sets the numerical system to unsigned decimal. Output is cast as an unsigned integer.	FlexSlider::UNSIGNED_DECIMAL
Value Field Alignment Decimal System	Sets the numerical system to unsigned decimal. Output is cast as an unsigned integer.	FlexSlider::UNSIGNED_DECIMAL
Align Value Left	Aligns the value characters left.	FlexSlider::VALUE_ALIGN_LEFT
Align Value Center	Aligns the value characters center.	FlexSlider::VALUE_ALIGN_CENTER
Align Value Right	Aligns the value characters right.	FlexSlider::VALUE_ALIGN_RIGHT

Example: To make the slider an input element with a frame around the value box use config = 1 + 8 = 9 or config = FlexSlider::INPUT + FlexSlider::FRAME

1. When a FlexSlider is NOT an input slider, the handle cannot be dragged. To make colour changes to this type of slider use disabled flags like the FlexSlider::HANDLE_DISABLED flag.

Feedback

Flex Sliders will send any changed values to the device as soon as those changes are made. To retrieve the new value, call one of the following functions:

Flex Sliders

Name	Syntax			Notes
	arg	type	argument description
Get Integer Value	Returns the integer value of the slider.			(1)
flexslider.get();
Get Float Value	Returns the float value of the slider.
flexslider.get_f();
Pressed	Returns true (1) if the element was clicked since the last time this function was called. Returns false (0) otherwise.
flexslider.pressed();

1. The integer value is the float value multiplied by the total factor which is the multiple of 10 required to express the float value as an int without losing any data.

Numerical Systems

By default, Flex Sliders use the decimal system to express their value in the text field. If user input is enabled, the text field will only accept integers between -999999 and 999999. Any other character will cause the entry to be rejected.

If the config option FlexSlider::BINARY or FlexSlider::HEXADECIMAL or FlexSlider::UNSIGNED_DECIMAL is used, the value of the slider will always be expressed in the chosen numerical system. If user input is enabled, the text field will accept entries in any of the formats (decimal, binary, or hexadecimal). The entered figure will be translated into the chosen numerical system. For example, if the hexadecimal numerical system is set, and the user enters 100, the text field will display 0x64. If the user enters 0b100, the text field will display 0x4.

To input a value in binary format, the following syntax must be used: 0b[number] where number is a value in binary.

To input a value in hexadecimal format, the following syntax must be used: 0x[number] where number is a value in hexadecimal.

Basic Flex Slider

Inherits: Flex Element

Basic Flex Sliders are objects made up of a label, a horizontal slider, and an input/output text box. They can be created as either input/output devices or strictly output ones. As input devices, users can drag the slider with a mouse, or type a value into the text box. Either method of entry will update the other and report the new value over the USB connection.

Constructor

No arguments need to be passed in a Basic Flex Slider constructor.

Example:

Basic_FlexSlider flexslider();

API Commands

Instance Methods

Name	Syntax			Notes
	arg	type	argument description
Add Flex Slider	Adds a new Flex Slider
flexslider.add(name, row, column, rowSpan, columnSpan, min, max, initValue, denominator, config); or flexslider.add(parent, name, row, column, rowSpan, columnSpan, min, max, initValue, denominator, config); or flexslider.add(name, row, column, rowSpan, columnSpan, min, max, initValue, denominator); or flexslider.add(parent, name, row, column, rowSpan, columnSpan, min, max, initValue, denominator);	parent	GUI_Page*	A pointer to the parent GUI Page.
	name	const char*	The name and visible label of the slider.
	row	u16	The row the slider is to be placed in.
	column	u16	The row the slider is to be placed in.
	rowSpan	u16	The number of rows the slider will span.
	columnSpan	u16	The number of columns the slider will span.
	min	int	The minimum value the slider can display.
	max	int	The maximum value the slider can display.
	initValue	int	The initial value the slider will hold.
	denominator	u16	The factor by which values are divided before being displayed (e.g. if denominator = 100 then flexslider.update(1000); displays 10.)
	config	u16	A configuration flag. See the configuration section below. (optional)
Add Flex Slider	Adds a new Flex Slider With Units
flexslider.add(name, row, column, rowSpan, columnSpan, min, max, initValue, denominator, units, config); or flexslider.add(name, row, column, rowSpan, columnSpan, min, max, initValue, denominator, units);	name	string	The name and visible label of the slider.
	row	u16	The row the slider is to be placed in.
	column	u16	The row the slider is to be placed in.
	rowSpan	u16	The number of rows the slider will span.
	columnSpan	u16	The number of columns the slider will span.
	min	int	The minimum value the slider can display.
	max	int	The maximum value the slider can display.
	initValue	int	The initial value the slider will hold.
	denominator	u16	The factor by which values are divided before being displayed (e.g. if denominator = 100 then flexslider.update(1000); displays 10.)
	units	string	Display name of the units field. Must not contain whitespaces; underscores are converted to whitespace.
	config	u16	A configuration flag. See the configuration section below. (optional)
Re-Configure Flex Slider	Re-Configure Flex Slider
flexslider.config(configuration);	configuration	u16	The new configuration flag.
Update Flex Slider	Sets the slider to a new value
flexslider.update(int value); flexslider.update(u16 value); flexslider.update(u32 value); flexslider.update(s32 value);	value	int u16 u32 s32 float	The new value of the slider.
Set Slider Range	Sets the minimum and maximum values the slider can display
flexslider.set_range(min, max);	min	s32	The minimum value the slider can display.	(1)
	max	s32	The maximum value the slider can display.
Reset Colours	Resets this instance's colours to defaults.
flexslider.reset_this_flexslider_default_colours();

1. Sliders may be updated with values outside their range. In this case, the written value will reflect the actual value while the slider handle remains at its minimum/maximum limit.

Static Methods

Name	Syntax			Notes
	arg	type	argument description
Set Default Colour	Sets the Default Colour of an Aspect of the Element
FlexSlider::set_default_colour(flag, r, g, b, a);	flag	FlexSlider::COLOUR_SET_FLAG	The aspect of the element to change.	(1)
	r	u16	The "red" value.
	g	u16	The "green" value.
	b	u16	The "blue" value.
	a	u16	The "alpha" value.

1. See table for allowed element aspects.

Configuration

Flex Sliders have a variety of configuration options.

Configuration

Configuration Element	Description	Config Value
Input	Allows the Flex Slider to be used as an input device. (1)	FlexSlider::ALLOW_INPUT
Not Tracking	Prevents the slider from sending updates as it is dragged. If this is selected, it only update the device when the user stops dragging with the mouse. It will not update when using the keyboard or mouse wheel to adjust the slider value.	FlexSlider::NOT_TRACKING
Units Field	Adds a text field to the right of the slider's value that can display units or other useful data.	FlexSlider::UNITS
Frame	Draws a frame around the value box.	FlexSlider::FRAME
Digits of Precision	Sets the number of decimal places for the slider where X is an int between 1 and 7.	FlexSlider::PRECISION_X
Mirrored	Horizontally mirrors the slider.	FlexSlider::MIRRORED
Size of Value	Sets the number of digits the value can hold where X is an int (1-8, 10, 12, 14, 18, 22, 26, 30, or 34). The default is 7 digits.	FlexSlider::DIGITS_X
Binary Numerical System	Sets the numerical system to binary. Output is shown in binary format.	FlexSlider::BINARY
Hexadecimal Numerical System	Sets the numerical system to hexadecimal. Output is shown in hexadecimal format.	FlexSlider::HEXADECIMAL
Unsigned Decimal System	Sets the numerical system to unsigned decimal. Output is cast as an unsigned integer.	FlexSlider::UNSIGNED_DECIMAL
Value Field Alignment Decimal System	Sets the numerical system to unsigned decimal. Output is cast as an unsigned integer.	FlexSlider::UNSIGNED_DECIMAL
Align Value Left	Aligns the value characters left.	FlexSlider::VALUE_ALIGN_LEFT
Align Value Center	Aligns the value characters center.	FlexSlider::VALUE_ALIGN_CENTER
Align Value Right	Aligns the value characters right.	FlexSlider::VALUE_ALIGN_RIGHT

Example: To make the slider an input element with a frame around the value box use config = 1 + 8 = 9 or config = FlexSlider::INPUT + FlexSlider::FRAME

1. When a FlexSlider is NOT an input slider, the handle cannot be dragged. To make colour changes to this type of slider use disabled flags like the FlexSlider::HANDLE_DISABLED flag.

Feedback

Flex Sliders will send any changed values to the device as soon as those changes are made. To retrieve the new value, call one of the following functions:

Flex Sliders

Name	Syntax			Notes
	arg	type	argument description
Get Integer Value	Returns the integer value of the slider.			(1)
flexslider.get();
Pressed	Returns true (1) if the element was clicked since the last time this function was called. Returns false (0) otherwise.
flexslider.pressed();

Numerical Systems

By default, Flex Sliders use the decimal system to express their value in the text field. If user input is enabled, the text field will only accept integers between -999999 and 999999. Any other character will cause the entry to be rejected.

If the config option FlexSlider::BINARY or FlexSlider::HEXADECIMAL or FlexSlider::UNSIGNED_DECIMAL is used, the value of the slider will always be expressed in the chosen numerical system. If user input is enabled, the text field will accept entries in any of the formats (decimal, binary, or hexadecimal). The entered figure will be translated into the chosen numerical system. For example, if the hexadecimal numerical system is set, and the user enters 100, the text field will display 0x64. If the user enters 0b100, the text field will display 0x4.

To input a value in binary format, the following syntax must be used: 0b[number] where number is a value in binary.

To input a value in hexadecimal format, the following syntax must be used: 0x[number] where number is a value in hexadecimal.

Flex Label

Inherits: Flex Element

Flex Labels are simple text fields. They are output only elements.

Constructor

The Flex Label constructor takes no arguments.

Example: FlexLabel flexlabel();

API Commands

Instance Methods

Name	Syntax			Notes
	arg	type	argument description
Add Flex Label	Adds a new Flex Label
flexlabel.add(name, row, column, rowSpan, columnSpan, config); or flexlabel.add(parent, name, row, column, rowSpan, columnSpan, config); or flexlabel.add(name, row, column, rowSpan, columnSpan); or flexlabel.add(parent, name, row, column, rowSpan, columnSpan);	parent	GUI_Page*	A pointer to the parent GUI Page.
	name	const char*	The name and visible text of the label.
	row	u16	The row the label is to be placed in.
	column	u16	The column the label is to be placed in.
	rowSpan	u16	The number of rows the label will span.
	columnSpan	u16	The number of columns the label will span.
	config	u16	A configuration flag. See the configuration section below. (optional)
Re-Configure Flex Label	Re-Configure Flex Label
flexlabel.config(config);	config	u16	The new configuration flag. See the configuration section below.
Reset Colours	Resets this instance's colours to defaults.
flexlabel.reset_this_flexlabel_default_colours();

Static Methods

Name	Syntax			Notes
	arg	type	argument description
Set Default Colour	Sets the Default Colour of an Aaspect of the Element
FlexLabel::set_default_colour(flag, r, g, b, a);	flag	FlexLabel::COLOUR_SET_FLAG	The aspect of the element to change.	(1)
	r	u16	The "red" value.
	g	u16	The "green" value.
	b	u16	The "blue" value.
	a	u16	The "alpha" value.
Reset All FlexLabel Default Colours	Resets all FlexLabel default colours.
FlexLabel::reset_all_flexlabel_default_colours();

1. See table for allowed element aspects.

Configuration

Flex Label elements have a variety of configuration options.

Configuration

Configuration Element	Description	Config Value
		Name	Decimal
Align Center	Sets the text alignment of the label.	FlexLabel::ALIGN_CENTER	1
Align Right	Sets the text alignment of the label.	FlexLabel::ALIGN_RIGHT	2

Clickable Flex Label

Inherits: Flex Element

Clickable Flex Labels are Flex Labels that report user clicks to the device.

Constructor

The Clickable Flex Label constructor takes no arguments.

Example: C_FlexLabel flexlabel();

API Commands

Instance Methods

Name	Syntax			Notes
	arg	type	argument description
Add Flex Label	Adds a new Flex Label
flexlabel.add(name, row, column, rowSpan, columnSpan, config); or flexlabel.add(parent, name, row, column, rowSpan, columnSpan, config); or flexlabel.add(name, row, column, rowSpan, columnSpan); or flexlabel.add(parent, name, row, column, rowSpan, columnSpan);	parent	GUI_Page*	A pointer to the parent GUI Page.
	name	const char*	The name and visible text of the label.
	row	u16	The row the label is to be placed in.
	column	u16	The column the label is to be placed in.
	rowSpan	u16	The number of rows the label will span.
	columnSpan	u16	The number of columns the label will span.
	config	u16	A configuration flag. See the configuration section below. (optional)
Re-Configure Flex Label	Re-Configure Flex Label
flexlabel.config(config);	config	u16	The new configuration flag. See the configuration section below.
Reset Colours	Resets this instance's colours to defaults.
flexlabel.reset_this_flexlabel_default_colours();

Static Methods

Name	Syntax			Notes
	arg	type	argument description
Set Default Colour	Sets the Default Colour of an Aaspect of the Element
FlexLabel::set_default_colour(flag, r, g, b, a);	flag	FlexLabel::COLOUR_SET_FLAG	The aspect of the element to change.	(1)
	r	u16	The "red" value.
	g	u16	The "green" value.
	b	u16	The "blue" value.
	a	u16	The "alpha" value.

1. See table for allowed element aspects.

Configuration

Flex Label elements have a variety of configuration options.

Configuration

Configuration Element	Description	Config Value
		Name	Decimal
Align Center	Sets the text alignment of the label.	FlexLabel::ALIGN_CENTER	1
Align Right	Sets the text alignment of the label.	FlexLabel::ALIGN_RIGHT	2

Feedback

Clickable Flex Label

Name	Syntax			Notes
	arg	type	argument description
Pressed	Returns true (1) if the element was clicked since the last time this function was called. Returns false (0) otherwise.
flexlabel.pressed();

Flex Data

Inherits: Flex Element

The Flex Data element consists of a label and a data field. The data field accepts/displays numerical data and can be configured to be an input/output or output only. The colour of the text in the Flex Data is configurable.

Denominators

Principles

A denominator can be applied to the output value of the Flex Data in order to accomplish a unit conversion. In essence, all values sent to the element will be divided by the denominator while all values coming from the element will be multiplied by the denominator.

For example, if you wish to display a frequency value that is expressed in Hz, a denominator of 1000 can be applied to display frequency in kHz. flexdata.update(1000); will display on the Flex Data as 1. In this case, when adding the element, use "kHz" for the units field.

Building the Slider

The initial value and all subsequent updates will have the denominator applied to them so to see an initial value of 10 with a denominator of 100, use initial value 10,000.

Transfer of Data

When updating a Flex Data by calling flexdata.update(value);, the value displayed will always be value/denominator.

When retrieving data by calling flexdata.get(); the value returned will be the element's apparent value times the denominator.

For example, a Flex Data with denominator 1000 has flexdata.update(2000); called. It will show as 2. If flexdata.get(); is called for that same element, it will return 2000.

Constructor

No arguments need to be passed in a Flex Data constructor.

Example:

FlexData flexdata();

API Commands

Instance Methods

Name	Syntax			Notes
	arg	type	argument description
Add Flex Data	Adds a new Flex Data
flexdata.add(name, row, column, rowSpan, columnSpan, initValue, denominator, config); or flexdata.add(parent, name, row, column, rowSpan, columnSpan, initValue, denominator, config); or flexdata.add(name, row, column, rowSpan, columnSpan, initValue, denominator); or flexdata.add(parent, name, row, column, rowSpan, columnSpan, initValue, denominator);	parent	GUI_Page*	A pointer to the parent GUI Page.
	name	const char*	The name and visible label of the element.
	row	u16	The row the element is to be placed in.
	column	u16	The row the element is to be placed in.
	rowSpan	u16	The number of rows the element will span.
	columnSpan	u16	The number of columns the element will span.
	initValue	float	The initial value the element will hold.
	denominator	u16	The factor by which to multiply the value of the Data to get a whole number. (e.g. for two digits of precision, denominator = 100)
	config	u16	A configuration flag. See the configuration section below. (optional)
Add Flex Data	Adds a new Flex Data With Units
flexdata.add(name, row, column, rowSpan, columnSpan, initValue, denominator, units, config); or flexdata.add(parent, name, row, column, rowSpan, columnSpan, initValue, denominator, units, config); or flexdata.add(name, row, column, rowSpan, columnSpan, initValue, denominator, units); or flexdata.add(parent, name, row, column, rowSpan, columnSpan, initValue, denominator, units);	parent	GUI_Page*	A pointer to the parent GUI Page.
	name	const char*	The name and visible label of the element.
	row	u16	The row the element is to be placed in.
	column	u16	The row the element is to be placed in.
	rowSpan	u16	The number of rows the element will span.
	columnSpan	u16	The number of columns the element will span.
	initValue	float	The initial value the element will hold.
	denominator	u16	The factor by which to multiply the value of the Data to get a whole number. (e.g. for two digits of precision, denominator = 100)
	units	string	Display name of the units field. Must not contain whitespaces; underscores are converted to whitespace.
	config	u16	A configuration flag. See the configuration section below. (optional)
Re-Configure Flex Data	Re-Configure Flex Data
flexdata.config(configuration);	configuration	u16	The new configuration flag.
Update Flex Data	Sets the Data to a new value.
flexdata.update(int value); flexdata.update(u16 value); flexdata.update(u32 value); flexdata.update(s32 value); flexdata.update(float value);	value	int u16 u32 s32 float	The new value of the slider.
Reset Colours	Resets this instance's colours to defaults.
flexdata.reset_this_flexdata_default_colours();

Static Methods

Name	Syntax			Notes
	arg	type	argument description
Set Default Colour	Sets the Default Colour of an Aspect of the Element
FlexData::set_default_colour(flag, r, g, b, a);	flag	FlexData::COLOUR_SET_FLAG	The aspect of the element to change.	(1)
	r	u16	The "red" value.
	g	u16	The "green" value.
	b	u16	The "blue" value.
	a	u16	The "alpha" value.
Reset All FlexData Default Colours	Resets all FlexData default colours.
FlexData::reset_all_flexdata_default_colours();

1. See table for allowed element aspects.

Configuration

Flex Data elements have a variety of configuration options.

Configuration

Configuration Element	Description	Config Value
Input	Allows the Flex Data to be used as an input element.	FlexData::ALLOW_INPUT
Frame	Draws a frame around the value box.	FlexData::FRAME
Units Field	Adds a text field to the right of the element's value that can display units or other useful data.	FlexData::UNITS
Digits of Precision	Sets the number of decimal places for the element where X is an int between 1 and 7.	FlexData::PRECISION_X
Mirrored	Horizontally mirrors the element.	FlexData::MIRRORED
Size of Value	Sets the number of digits the value can hold where X is an int (1-8, 10, 12, 14, 18, 22, 26, 30, or 34). The default is 7 digits.	FlexData::DIGITS_X
Binary Numerical System	Sets the numerical system to binary. Output is shown in binary format.	FlexData::BINARY
Hexadecimal Numerical System	Sets the numerical system to hexadecimal. Output is shown in hexadecimal format.	FlexData::HEXADECIMAL
Unsigned Decimal System	Sets the numerical system to unsigned decimal. Output is cast as an unsigned integer.	FlexData::UNSIGNED_DECIMAL
Align Label Left	Aligns the label characters left.	FlexData::LABEL_ALIGN_LEFT
Align Label Center	Aligns the label characters center.	FlexData::LABEL_ALIGN_CENTER
Align Label Right	Aligns the label characters right.	FlexData::LABEL_ALIGN_RIGHT
Align Value Left	Aligns the value characters left.	FlexData::VALUE_ALIGN_LEFT
Align Value Center	Aligns the value characters center.	FlexData::VALUE_ALIGN_CENTER
Align Value Right	Aligns the value characters right.	FlexData::VALUE_ALIGN_RIGHT
Align Units Left	Aligns the units characters left.	FlexData::UNITS_ALIGN_LEFT
Align Units Center	Aligns the units characters center.	FlexData::UNITS_ALIGN_CENTER
Align Units Right	Aligns the units characters right.	FlexData::UNITS_ALIGN_RIGHT

Example: To make the element an input element with a frame around the value box use config = 1 + 2 = 3 or config = FlexData::INPUT + FlexData::FRAME

Feedback

Flex Data

Name	Syntax			Notes
	arg	type	argument description
Get Integer Value	Returns the integer value of the Data.			(1)
flexdata.get();
Get Float Value	Returns the float value of the Data.
flexdata.get_f();
Pressed	Returns true (1) if the element was clicked since the last time this function was called. Returns false (0) otherwise.
flexdata.pressed();

1. The integer value is the float value multiplied by the total factor which is the multiple of 10 required to express the float value as an int without losing any data.

Numerical Systems

By default, Flex Datas use the decimal system to express their value in the text field. If user input is enabled, the text field will only accept integers between -999999 and 999999. Any other character will cause the entry to be rejected.

If the config option FlexData::BINARY or FlexData::HEXADECIMAL or FlexData::UNSIGNED_DECIMAL is used, the value of the Flex Data will always be expressed in the chosen numerical system. If user input is enabled, the text field will accept entries in any of the formats (decimal, binary, or hexadecimal). The entered figure will be translated into the chosen numerical system. For example, if the hexadecimal numerical system is set, and the user enters 100, the text field will display 0x64. If the user enters 0b100, the text field will display 0x4.

To input a value in binary format, the following syntax must be used: 0b[number] where number is a value in binary.

To input a value in hexadecimal format, the following syntax must be used: 0x[number] where number is a value in hexadecimal.

Basic Flex Data

Inherits: Flex Element

The Basic Flex Data element consists of a label and a data field. The data field accepts/displays numerical data and can be configured to be an input/output or output only. The colour of the text in the Basic Flex Data is configurable.

Constructor

No arguments need to be passed in a Basic Flex Data constructor.

Example:

Basic_FlexData flexdata();

API Commands

TITLE

Name	Syntax			Notes
	arg	type	argument description
Add Flex Data	Adds a new Flex Data
flexdata.add(name, row, column, rowSpan, columnSpan, initValue, config); or flexdata.add(parent, name, row, column, rowSpan, columnSpan, initValue, config); or flexdata.add(name, row, column, rowSpan, columnSpan, initValue); or flexdata.add(parent, name, row, column, rowSpan, columnSpan, initValue);	parent	GUI_Page*	A pointer to the parent GUI Page.
	name	const char*	The name and visible label of the element.
	row	u16	The row the element is to be placed in.
	column	u16	The row the element is to be placed in.
	rowSpan	u16	The number of rows the element will span.
	columnSpan	u16	The number of columns the element will span.
	initValue	int	The initial value the element will hold.
	config	u16	A configuration flag. See the configuration section below. (optional)
Add Flex Data	Adds a new Flex Data With Units
flexdata.add(name, row, column, rowSpan, columnSpan, initValue, units, config); or flexdata.add(parent, name, row, column, rowSpan, columnSpan, initValue, units, config); or flexdata.add(name, row, column, rowSpan, columnSpan, initValue, units); or flexdata.add(parent, name, row, column, rowSpan, columnSpan, initValue, units);	parent	GUI_Page*	A pointer to the parent GUI Page.
	name	const char*	The name and visible label of the element.
	row	u16	The row the element is to be placed in.
	column	u16	The row the element is to be placed in.
	rowSpan	u16	The number of rows the element will span.
	columnSpan	u16	The number of columns the element will span.
	initValue	int	The initial value the element will hold.
	units	string	Display name of the units field. Must not contain whitespaces; underscores are converted to whitespace.
	config	u16	A configuration flag. See the configuration section below. (optional)
Re-Configure Flex Data	Re-Configure Flex Data
flexdata.config(configuration);	configuration	u16	The new configuration flag.
Update Flex Data	Sets the Data to a new value.
flexdata.update(int value); flexdata.update(u16 value); flexdata.update(u32 value); flexdata.update(s32 value);	value	int u16 u32 s32	The new value of the slider.
Reset Colours	Resets this instance's colours to defaults.
flexdata.reset_this_flexdata_default_colours();

Static Methods

Name	Syntax			Notes
	arg	type	argument description
Set Default Colour	Sets the Default Colour of an Aspect of the Element
FlexData::set_default_colour(flag, r, g, b, a);	flag	FlexData::COLOUR_SET_FLAG	The aspect of the element to change.	(1)
	r	u16	The "red" value.
	g	u16	The "green" value.
	b	u16	The "blue" value.
	a	u16	The "alpha" value.

1. See table for allowed element aspects.

Configuration

Flex Data elements have a variety of configuration options.

Configuration

Configuration Element	Description	Config Value
Input	Allows the Flex Data to be used as an input element.	FlexData::ALLOW_INPUT
Frame	Draws a frame around the value box.	FlexData::FRAME
Units Field	Adds a text field to the right of the element's value that can display units or other useful data.	FlexData::UNITS
Digits of Precision	Sets the number of decimal places for the element where X is an int between 1 and 7.	FlexData::PRECISION_X
Mirrored	Horizontally mirrors the element.	FlexData::MIRRORED
Size of Value	Sets the number of digits the value can hold where X is an int (1-8, 10, 12, 14, 18, 22, 26, 30, or 34). The default is 7 digits.	FlexData::DIGITS_X
Binary Numerical System	Sets the numerical system to binary. Output is shown in binary format.	FlexData::BINARY
Hexadecimal Numerical System	Sets the numerical system to hexadecimal. Output is shown in hexadecimal format.	FlexData::HEXADECIMAL
Unsigned Decimal System	Sets the numerical system to unsigned decimal. Output is cast as an unsigned integer.	FlexData::UNSIGNED_DECIMAL
Align Label Left	Aligns the label characters left.	FlexData::LABEL_ALIGN_LEFT
Align Label Center	Aligns the label characters center.	FlexData::LABEL_ALIGN_CENTER
Align Label Right	Aligns the label characters right.	FlexData::LABEL_ALIGN_RIGHT
Align Value Left	Aligns the value characters left.	FlexData::VALUE_ALIGN_LEFT
Align Value Center	Aligns the value characters center.	FlexData::VALUE_ALIGN_CENTER
Align Value Right	Aligns the value characters right.	FlexData::VALUE_ALIGN_RIGHT
Align Units Left	Aligns the units characters left.	FlexData::UNITS_ALIGN_LEFT
Align Units Center	Aligns the units characters center.	FlexData::UNITS_ALIGN_CENTER
Align Units Right	Aligns the units characters right.	FlexData::UNITS_ALIGN_RIGHT

Example: To make the element an input element with a frame around the value box use config = 1 + 2 = 3 or config = FlexData::INPUT + FlexData::FRAME

Feedback

Flex Data

Name	Syntax			Notes
	arg	type	argument description
Get Integer Value	Returns the integer value of the Data.			(1)
flexdata.get();
Pressed	Returns true (1) if the element was clicked since the last time this function was called. Returns false (0) otherwise.
flexdata.pressed();

Numerical Systems

By default, Flex Datas use the decimal system to express their value in the text field. If user input is enabled, the text field will only accept integers between -999999 and 999999. Any other character will cause the entry to be rejected.

If the config option FlexData::BINARY or FlexData::HEXADECIMAL or FlexData::UNSIGNED_DECIMAL is used, the value of the Flex Data will always be expressed in the chosen numerical system. If user input is enabled, the text field will accept entries in any of the formats (decimal, binary, or hexadecimal). The entered figure will be translated into the chosen numerical system. For example, if the hexadecimal numerical system is set, and the user enters 100, the text field will display 0x64. If the user enters 0b100, the text field will display 0x4.

To input a value in binary format, the following syntax must be used: 0b[number] where number is a value in binary.

To input a value in hexadecimal format, the following syntax must be used: 0x[number] where number is a value in hexadecimal.

Plotting

IrisControls4 supports real-time plotting of data. In order to display data, a Flex Plot must first be added to the main window. Once displayed, data points can be saved as a text file by the user. If Iris Controls unexpectedly loses connection with the motor due to a crash or otherwise, all datasets are automatically saved to data files.

Flex Plot

Inherits: Flex Element

The Flex Plot is the element that displays the data contained within datasets. It could be thought of as a blank piece of graphing paper. Flex Plots are Flex Elements and therefore can be moved, resized, hidden, shown, renamed, and deleted. Deleting a Flex Plot will cause any Datasets assigned that that Flex Plot to be unassigned. By default, Flex Plots have a grey background but there is an API to change that colour. Flex Plots can be configured to "walk" as new data is added, and the x-axis can be configured to display time in a clear readable format.

Constructor

FlexPlot flexplot();

API Commands

Instance Methods

Name	Syntax			Notes
	arg	type	argument description
Add Flex Plot	Adds the main plot element to the window
flexplot.add(name, row, column, rowSpan, columnSpan, min, max, config); or flexplot.add(parent, name, row, column, rowSpan, columnSpan, min, max, config); or flexplot.add(name, row, column, rowSpan, columnSpan, min, max); or flexplot.add(parent, name, row, column, rowSpan, columnSpan, min, max);	parent	GUI_Page*	A pointer to the parent GUI Page.	(1)
	name	const char*	The name of the plot.
	row	u16	The row the plot element is to be placed in.
	column	u16	The column the plot element is to be placed in.
	rowSpan	u16	The number of rows the plot element will span.
	columnSpan	u16	The number of columns the plot element will span.
	min	float	Sets the lower bound of the range for the primary y-axis.
	max	float	Sets the upper bound of the range for the primary y-axis.
	config	u16	The configuration value. See configuration section below. (optional)
Config Plot I/O	Configures the available I/O elements for plotting.
flexplot.config(config);	config	u16	The configuration value. See configuration section below.
Set Primary Range	Sets the range of the y-axis for the Flex Plot
flexplot.setRange(min, max);	min	float	The lower bound of the range.
	max	float	The upper bound of the range.
Set Secondary Range	Sets the range of the secondary (right) y-axis for the Flex Plot
flexplot.set_secondary_range(min, max);	min	float	The lower bound of the range.
	max	float	The upper bound of the range.
Set Domain	Sets the domain of the x-axis of the Flex Plot
flexplot.setDomain(min, max);	min	float	The lower bound of the domain.
	max	float	The upper bound of the domain.
Set Walking Domain	Sets the domain of the x-axis of the Flex Plot for walking plots
flexplot.setDomain(domain);	domain	int	The size of the domain in the x-axis units. For time plots, the units are seconds.
Set Max Number of Visible Datapoints	Sets the maximum number of datapoints that will be displayed on the plot without user intervention
flexplot.setVisibleDatapoints(datapoints);	datapoints	u16	The max number of datapoints to display.	(2)
Set Axes Labels	Sets the axes labels of the Flex Plot to that of the Dataset specified
flexplot.setAxesLabels(&dataset)	dataset	Dataset*	The Dataset from which the labels are to be used.
Reset Colours	Resets this instance's colours to defaults.
flexplot.reset_this_flexplot_default_colours();

1. The minimum size of the main plot element is 6x6 rows/columns.
2. All datapoints (up to the maximum dataset size) are retained, they simply won't be visible unless the user uses mouse control to zoom and/or pan.

Static Methods

Name	Syntax			Notes
	arg	type	argument description
Set Default Colour	Sets the Default Colour of an Aspect of the Element
FlexPlot::set_default_colour(flag, r, g, b, a);	flag	FlexPlot::COLOUR_SET_FLAG	The aspect of the element to change.	(1)
	r	u16	The "red" value.
	g	u16	The "green" value.
	b	u16	The "blue" value.
	a	u16	The "alpha" value.
Reset All FlexPlot Default Colours	Resets all FlexPlot default colours.
FlexPlot::reset_all_flexplot_default_colours();

1. See table for allowed element aspects.

Configuration

Configuration

Configuration Element	Description	Config Value
		Name	Decimal
Legend	A legend to show which plot line is from which Dataset.	FlexPlot::LEGEND	1
Legend Toggle Button	A push button that toggles the plot's legend on and off.	FlexPlot::LEGEND_BUTTON	2
Mouse Control Toggle Button	A push button that enables/disables mouse control. When enabled the user can drag the plot and use the mousewheel to zoom. When disabled, the plot automatically adjusts zoom to show all visible data.	FlexPlot::MOUSE_BUTTON	4
Save Data Button	A push button that saves all data points from all visible datasets to a text file.	FlexPlot::SAVE_DATA_BUTTON	8
Dataset Select Menu	A drop down menu that allows the user to select which datasets are displayed.	FlexPlot::DATASET_SELECT_MENU	16
Axis Label Select Menu	A drop down menu that allows the user to select which dataset's axes labels are displayed.	FlexPlot::AXES_LABEL_MENU	32
Time Plot	Assigns the x-axis of the Flex Plot to display time.	FlexPlot::TIMEPLOT	64
Walking Plot	Assigns the Flex Plot as a walking plot.	FlexPlot::WALKING	128
Plot Label	Prints the Flex Plot's label above the plot.	FlexPlot::NAME_LABEL	256

Example: To include the Save Data Button and the Dataset Select Menu config = 8 + 16 = 24 or config = FlexPlot::SAVE_DATA_BUTTON + FlexPlot::DATASET_SELECT_MENU

Datasets

Datasets are containers for pairs of data points. Each Dataset is assigned to a FlexPlot upon which it can be displayed. Datasets are limited in the number of pairs of data they can contain. When a Dataset reaches its maximum size, the Dataset will function as a FIFO register. The limit is defined in the FlexPlot.h header file and is typically set to 100,000. The data contained in a Dataset can be saved to a text file (if it is currently visisble on its assigned FlexPlot) by clicking the Save Data button (if enabled by that FlexPlot's configuration). The colour of the plot line of a Dataset is automatically assigned but there is an API to select different colours. By default, plotted data points are marked with a cross and are connected by straight lines. Both these behaviours are adjustable using the configuration flag.

Constructor

Dataset dataset();

API Commands

DataSets

Name	Syntax			Notes
	arg	type	argument description
Add Dataset	Adds a new Dataset
dataset.add(flexplot, name, x_label, y_label, config);	flexplot	FlexPlot*	The Flex Plot this Dataset will be initially assigned to.
	name	string	The name of the Dataset. This will appear in the legend and on save files.
	x_label	string	The label of the x-axis data.
	y_label	string	The label of the y-axis data.
	config	u16	The configuration flag of the dataset.
Set Maximum Dataset Size	Sets the maximum number of data points Iris Controls will save in the Dataset before deleting old data as new data is added. (Default is 100,000)
dataset.set_max_data_points(number_of_datapoints);	number_of_datapoints	u32	The maximum number of data points (pairs of x and y values).
Remove Dataset	Deletes the Dataset and all its data
dataset.remove();
Hide Dataset	Hides the Dataset's plot.
dataset.hide();
Show Dataset	Reveals the Dataset's plot
dataset.show();
Add Data	Adds data points to the Dataset
dataset.add_data(int xData, int yData); dataset.add_data(u16 xData, u16 yData); dataset.add_data(u32 xData, u32 yData); dataset.add_data(s32 xData, s32 yData); dataset.add_data(float xData, float yData);	xData	int u16 u32 s32 float	The x value.
	yData	int u16 u32 s32 float	The y value.
Add Data	Adds data points to the Dataset
dataset.add_data(int dataPairs, int xData[] int yData[]); dataset.add_data(int dataPairs, int xData[] int yData[]);	dataPairs	int	The size of the xData and yData arrays.
	xData[]	int float	An array of x values.
	yData[]	int float	An array of y values.
Purge Dataset	Purges the Dataset of all data.
dataset.purge()
Assign Dataset	Assigns the Dataset to a Flex Plot
dataset.assign(FlexPlot* flexplot);	flexplot	FlexPlot*	The Flex Plot the Dataset is to be assigned to.	(1)
Un-Assign Dataset	Disassociates the Dataset from all Flex Plots
dataset.unassign();
Set Colour	Sets the colour of the Dataset
dataset.setColour(r, g, b, a);	r	u16	The "red" value.
	g	u16	The "green" value.
	b	u16	The "blue" value.
	a	u16	The "alpha" value.

1. If the Dataset is already assigned to a Flex Plot, it will automatically be un-assigned before being re-assigned to the Flex Plot specified in this command.

Configuration

Configuration

Configuration Element	Description	Config Value
		Name	Decimal
Timeplot	If set, the Dataset expects all data point x-values to be a time in microseconds since device boot. Iris Controls converts each value to local time.	Dataset::TIMEPLOT	1
Secondary y-Axis	If set, the Dataset will use the secondary (right side) y-Axis.	Dataset::SECONDARY_Y_AXIS	2
Scatter Plot	If set, the Dataset will not connect data points with lines when plotted.	Dataset::SCATTER_PLOT	4
Data Point Shape: Circle*	Data points will be marked by a circle.	Dataset::CIRCLE	8
Data Point Shape: Diamond*	Data points will be marked by a circle.	Dataset::DIAMOND	16
Data Point Shape: None*	Data points will not be marked.	Dataset::NONE	24

Example: To make the Dataset a timeplot on the secondary y-axis use config = Dataset::TIMEPLOT + Dataset::SECONDARY_Y_AXIS

• Up to ONE shape configuration can be selected per Dataset. The points are marked by a cross if none of these options are selected.

Logging

Iris Controls 4 can create and maintain data logging files. To access this, log.h must be included in the GUI application.

Constructor

DataLog datalog(name);

API Commands

DataSets

Name	Syntax			Notes
	arg	type	argument description
Add DataLog	Adds a new DataLog
datalog.add();
Write to DataLog	Writes a string to the DataLog
datalog.write(data);	data	string	The data to be written.

Automatic Logging

Iris Controls automatically generates some log files in the Logs folder.

Error Log

Any time an application function encounters an error, that error will be written to this log. Each new session of Iris Controls 4 generates a new log file to prevent runaway file sizes, but the previous session's log is also retained.

/Logs/Error Log.txt

Connection Log

This log records connection parameters on every successful connection and some disconnection information. Each new session of Iris Controls 4 generates a new log file to prevent runaway file sizes, but the previous session's log is also retained.

/Logs/Connection Log.txt

Serial Log

This log records raw serial communication data for use in troubleshooting.

/Logs/Serial Log.txt

IC4 Serial API

See this page for the IC4 serial API.

Development GUI

Iris Controls 4 Development GUI

Legacy Elements

The legacy elements are three frames (input, output, and button) that were used in older GUIs. Support for these has been retained to make IrisControls4 backwards compatible. Legacy frames are a fixed size.

Constructor

There is no constructor.

API Commands

Legacy Frames

Name	Syntax			Notes
	arg	type	argument description
Add Legacy Frames	Adds all three frames.			(1)
add_legacy_frames(row, column);
Remove Legacy Frames	gendescription
remove_legacy_frames();
Add Input Frame	Adds the Input Frame.
add_input_frame(row, column);	row	u16	The row the frame is to be placed in.	(2)
	column	u16	The column the frame is to be placed in.
Add Output Frame	Adds the Output Frame.
add_output_frame(row, column);	row	u16	The row the frame is to be placed in.	(2)
	column	u16	The column the frame is to be placed in.
Add Button Frame	Adds the Button Frame.
add_button_frame(row, column);	row	u16	The row the frame is to be placed in.	(3)
	column	u16	The column the frame is to be placed in.
Remove Input Frame	Removes the Input Frame
remove_input_frame();
Remove Output Frame	Removes the Output Frame
remove_output_frame();
Remove Button Frame	Removes the Button Frame
remove_button_frame();

1. The frames are added in this orientation:
   [ INPUT ][ OUTPUT ]
   [ BUTTON FRAME ]
2. This frame has a rowSpan of 30 rows and a columnSpan of 30 columns.
3. This frame has a rowSpan of 10 rows and a columnSpan of 50 columns.