The core FlatUI Library that drives the GUI. More...

Detailed Description

The core FlatUI Library that drives the GUI.

Classes
struct	flatui::Margin
	Specifies the margins for a group, in units of virtual resolution. More...

Enumerations
enum	flatui::Event { kEventNone = 0, kEventWentUp = 1, kEventWentDown = 2, kEventIsDown = 4, kEventStartDrag = 8, kEventEndDrag = 16, kEventIsDragging = 32, kEventHover = 64 }
	Event types are returned by most interactive elements. These are flags, because multiple events may occur during one frame, and thus should be tested using a Bitwise operators (`&`, `\|`, etc.). More...

enum	flatui::Alignment { kAlignTop = 1, kAlignLeft = 1, kAlignCenter = 2, kAlignBottom = 3, kAlignRight = 3 }
	Alignment of the groups. More...

enum	flatui::Direction { kDirHorizontal = 4, kDirVertical = 8, kDirOverlay = 12 }
	Direction of the groups. More...

enum	flatui::EditStatus { kEditStatusNone = 0, kEditStatusInEdit = 1, kEditStatusUpdated = 2, kEditStatusFinished = 3, kEditStatusCanceled = 4 }
	Status of Edit widget. More...

enum	flatui::Layout { kLayoutHorizontalTop = kDirHorizontal\| kAlignTop, kLayoutHorizontalCenter = kDirHorizontal\| kAlignCenter, kLayoutHorizontalBottom = kDirHorizontal\| kAlignBottom, kLayoutVerticalLeft = kDirVertical \| kAlignLeft, kLayoutVerticalCenter = kDirVertical \| kAlignCenter, kLayoutVerticalRight = kDirVertical \| kAlignRight, kLayoutOverlay = kDirOverlay \| kAlignCenter }
	Specify how to layout a group. More...

Functions
void	flatui::Run (fplbase::AssetManager &assetman, FontManager &fontman, fplbase::InputSystem &input, motive::MotiveEngine *motive_engine, const std::function< void()> &gui_definition)
	The core function that drives the GUI. More...

void	flatui::Run (fplbase::AssetManager &assetman, FontManager &fontman, fplbase::InputSystem &input, const std::function< void()> &gui_definition)
	A version of the function above that doesn't use a MotiveEngine. With this version of Run(), user will not be able to use the animation features of FlatUI. If a user tries to use FlatUI's animation features with this version of Run(), the program will terminate with an error.

mathfu::vec2i	flatui::VirtualToPhysical (const mathfu::vec2 &v)
	Converts a virtual screen coordinate to a physical value. More...

mathfu::vec2	flatui::PhysicalToVirtual (const mathfu::vec2i &v)
	Converts a physical screen coordinate to a virtual value. More...

float	flatui::GetScale ()
	Get the scaling factor for the virtual resolution. More...

void	flatui::Image (const fplbase::Texture &texture, float ysize, const char *id=kDefaultImageID)
	Render an image as a GUI element. More...

void	flatui::SetImageColor (const mathfu::vec4 &color)
	Set the Images's tint. More...

void	flatui::Label (const char *text, float ysize, HashedId label_id=kNullHash)
	Render a label as a GUI element. More...

void	flatui::Label (const char *text, float ysize, const mathfu::vec2 &size, HashedId label_id=kNullHash)
	Render a multi-line version of a label as a GUI element. More...

void	flatui::Label (const char *text, float ysize, const mathfu::vec2 &label_size, TextAlignment alignment, HashedId label_id=kNullHash)
	Render a multi-line label with a text alignment. More...

void	flatui::HtmlLabel (const char html, float ysize, const mathfu::vec2 &label_size, TextAlignment alignment, const char id)
	Render simple HTML text. More...

void	flatui::SetTextColor (const mathfu::vec4 &color)
	Set the Label's text color. More...

void	flatui::SetTextOuterColor (const mathfu::vec4 &color, float size, const mathfu::vec2 &offset)
	Set the Label's outer color (e.g. drop shadow color). To use the feature, outer SDF generation needs to be enabled by EnableTextSDF() API. With SDF, each glyph image includes a distance to the nearest edge. The API utilizes the feature to render an outer region of a glyph. For more details of SDF, refer a paper from Valve: http://www.valvesoftware.com/publications/2007/SIGGRAPH2007_AlphaTestedMagnification.pdf. More...

void	flatui::EnableTextSDF (bool inner_sdf, bool outer_sdf, float threshold)
	Enable/Disable a signed distance field generation with glyphs. A SDF generation of an inner region and an outer region is done separately and it costs some cycles. So if an application doesn't utilize inner SDF, just enable outer SDF. More...

void	flatui::EnableTextHyphenation (bool enable)
	Enable/Disable the hyphenation in the text label. More...

bool	flatui::SetTextFont (const char *font_name)
	Set the Label's font. More...

bool	flatui::SetTextFont (const char *font_names[], int32_t count)
	Set the Label's fonts with a fallback priority. When rendering a text, if a glyph is not found in the first font in the array, the renderer will look up the glyph in the second font and so on. If the glyph is not found in all font files, the glyph won't be rendered on the screen. More...

void	flatui::SetTextLocale (const char *locale)
	Set a locale used for the text rendering. More...

void	flatui::SetTextDirection (const TextLayoutDirection direction)
	Override a text layout direction set by SetTextLocale() API. More...

void	flatui::SetTextLineHeightScale (float scale)
	Set a line height scale used in the text rendering. More...

void	flatui::SetTextKerningScale (float scale)
	Set a kerning scale used in the text rendering. More...

void	flatui::SetTextEllipsis (const char *ellipsis)
	Set an ellipsis string used in label/edit widgets. More...

Event	flatui::Edit (float ysize, const mathfu::vec2 &size, const char id, EditStatus status, std::string *string)
	Renders an edit text box as a GUI element. More...

Event	flatui::Edit (float ysize, const mathfu::vec2 &size, TextAlignment alignment, const char id, EditStatus status, std::string *string)
	Render an edit text box with a text alignment. More...

void	flatui::StartGroup (Layout layout, float spacing=0, const char *id=kDefaultGroupID)
	Create a group of elements with a given layout and intra-element spacing. More...

void	flatui::EndGroup ()
	Clean up the Group element start by `StartGroup()`. More...

void	flatui::SetMargin (const Margin &margin)
	Sets the margin for the current group. More...

Event	flatui::CheckEvent ()
	Check for events from the current group. More...

Event	flatui::CheckEvent (bool check_dragevent_only)
	Check for events from the current group. More...

void	flatui::SetDefaultFocus ()
	Set the default keyboard/gamepad focus to the current element.

void	flatui::ModalGroup ()
	Called inside of a group that that is mean to act like a popup inside of a `kLayoutOverlay`. More...

void	flatui::CapturePointer (const char *element_id)
	Caputre a pointer event. More...

void	flatui::ReleasePointer ()
	Release a pointer capture. More...

ssize_t	flatui::GetCapturedPointerIndex ()
	Get the index of th ecaptured pointer. More...

void	flatui::SetScrollSpeed (float scroll_speed_drag, float scroll_speed_wheel, float scroll_speed_gamepad)
	Set the scroll speed of the drag, mouse wheel, and gamepad operations. More...

void	flatui::SetDragStartThreshold (int drag_start_threshold)
	Set a threshold value for the start of a drag operation. More...

void	flatui::ColorBackground (const mathfu::vec4 &color)
	Set the background color for the group. More...

void	flatui::ImageBackground (const fplbase::Texture &tex)
	Set the background texture for the group. More...

void	flatui::ImageBackgroundNinePatch (const fplbase::Texture &tex, const mathfu::vec4 &patch_info)
	Set the background texture for the group with nine patch settings. More...

void	flatui::StartScroll (const mathfu::vec2 &size, mathfu::vec2 *offset)
	Make the current group into a scrolling group that can display arbitrary sized elements inside a window of "size", scrolled to the current "offset" (which the caller should store somewhere that survives the current frame). More...

void	flatui::EndScroll ()
	Ends the current scrolling group. More...

void	flatui::StartSlider (Direction direction, float scroll_margin, float *value)
	Make the current group into a slider group that can handle basic slider behavior. The group will capture/release the pointer as necessary. More...

void	flatui::EndSlider ()
	Ends the current slider group. More...

void	flatui::CustomElement (const mathfu::vec2 &virtual_size, const char *id, const std::function< void(const mathfu::vec2i &pos, const mathfu::vec2i &size)> renderer)
	Create a custom element with a given size. More...

void	flatui::RenderTexture (const fplbase::Texture &tex, const mathfu::vec2i &pos, const mathfu::vec2i &size)
	Render a Texture to a specific position with a given size. More...

void	flatui::RenderTexture (const fplbase::Texture &tex, const mathfu::vec2i &pos, const mathfu::vec2i &size, const mathfu::vec4 &color)
	Render a Texture to a specific position with a given size and color. More...

void	flatui::RenderTextureNinePatch (const fplbase::Texture &tex, const mathfu::vec4 &patch_info, const mathfu::vec2i &pos, const mathfu::vec2i &size)
	Render a nine-patch texture at a specific position with a given size. More...

void	flatui::SetVirtualResolution (float virtual_resolution)
	Set the virtual resolution of the smallest dimension of the screen (the Y size in landscape mode, or X in portrait). More...

mathfu::vec2	flatui::GetVirtualResolution ()

void	flatui::PositionGroup (Alignment horizontal, Alignment vertical, const mathfu::vec2 &offset)
	Position a group within the screen as a whole. More...

void	flatui::UseExistingProjection (const mathfu::vec2i &canvas_size)
	By default, FlatUI sets up a projection matrix for all the rendering that covers the entire screen (as given by `Renderer::window_size()`. You can call to this function instead, to use whatever projection is in place before `Run()` is called (which may be a 2D or 3D projection). More...

void	flatui::ApplyCustomTransform (const mathfu::mat4 &imvp)
	If you're rendering the UI at a location that does not correspond to the display's pixels (e.g. in 3D), this call allows you to set your a custom transform that corresponds to the inverse of your model-view- projection matrix. FlatUI will then transform all incoming (screen-space) pointer events with this, such that they are mapped to coordinates that match what was passed to UseExistingProjection. Important that the UI was rendered with object space coordinates ranging from (0,0) to canvas_size as well. Call this at the start of your UI. For an example of how to use this, see flatuisample_3d.cpp. More...

mathfu::vec2	flatui::GroupPosition ()

mathfu::vec2	flatui::GroupSize ()

bool	flatui::IsLastEventPointerType ()

Variables
const char *const	flatui::kDefaultGroupID = "__group_id__"
	A sentinel value for group IDs.

const char *const	flatui::kDefaultImageID = "__image_id__"
	A sentinel value for image IDs.

const float	flatui::FLATUI_DEFAULT_VIRTUAL_RESOLUTION = 1000.0f
	The default virtual resolution, if none is set.

Enumeration Type Documentation

enum flatui::Alignment

Alignment of the groups.

Note: : kAlignTop and kAlignLeft(as well as kAlignBottom and kAlignRight) are intended to be aliases of one another, as they both express the same thing on their respective axis.

Enumerations:

kAlignTop or kAlignLeft (1) - Align along the top (or left, depending on the axis).
kAlignCenter (2) - Align along the center of the axis.
kAlignBottom or kAlignRight (3) - Align along the bottom (or right, depending on the axis).

enum flatui::Direction

Direction of the groups.

Enumerations:

kDirHorizontal (4) - The direction of the group is horizontal (x-axis).
kDirVertical (8) - The direction of the group is vertical (y-axis).
kDirOverlay (12) - The group of elements are placed on top of one another (along the z-axis).

enum flatui::EditStatus

Status of Edit widget.

Enumerations:

kEditStatusNone - The widget is not editing.
kEditStatusInEdit - The widget is in edit.
kEditStatusUpdated - The widget is in edit and contents has been updated in the current update cycle.
kEditStatusFinished - The widget finished editing with an updated contents.
kEditStatusCanceled - The edit is canceled by the user pressing esc.

enum flatui::Event

Event types are returned by most interactive elements. These are flags, because multiple events may occur during one frame, and thus should be tested using a Bitwise operators (&, |, etc.).

For example, it is not uncommon for the value to be kEventWentDown | kEventWentUp (or 3), if the click/touch was quicker than the current frametime.

You can then check if a specific event occured using the Bitwise AND (&) operator. For instance, given an Event my_event, you could check if the kEventWentDown Event happened in that frame with if((my_event & kEventWentDown) != 0).

Enumerations:

kEventNone (0) - No Event occured in the frame. (This is also returned by all elements during the layout pass.
kEventWentUp (1) - Pointing device (or button) was released this frame, while over this element. (This only triggers if the element was also the one to receive the corresponding kEventWentDown.
kEventWentDown (2) - Pointing device is currently being held down on top of this element. You're not guaranteed to also receive a kEventWentUp, as the pointing device may have moved to another element (or no element) before the frame ends.
kEventIsDown (4) - Pointing device is currently being held down on top of this element. You're not guaranteed to receive this event between kEventWentDown and a kEventWentUp. That occurs only if the event spans multiple frames. This only triggers for the element that the corresponding kEventWentDown fired on.
kEventStartDrag (8) - Pointing device started dragging this frame while over this element. The element is expected to call CapturePointer() to receive the drag event continuously, even if the pointer goes off of the element.
kEventEndDrag (16) - Pointing device finished dragging in this frame.
kEventIsDragging (32) - Pointing device is currently in dragging mode.
kEventHover (64) - Pointing device is currently over the element, but not pressed. This event does NOT occur on touch screen devices. It only occurs for devices that use a mouse (or a gamepad that emulates a mouse when selecting). As such, it is good to show a subtle form of highlighting upon this event. However, the UI should not rely on it to function.

For example, a typical drag operation would receive the following events in this sequence: kEventWentDown –> kEventIsDown (until the pointer motion exceeds a threshold) –> kEventStartDrag –> kEventIsDragging –> kEventEndDrag.

enum flatui::Layout

Specify how to layout a group.

Elements can be positioned either horizontally or vertically. The elements can be aligned on either side, or centered.

For example, kLayoutHorizontalTop indicates that the elements are layed out from left-to-right, with items of uneven height being aligned from the top.

In this example, we have three elements: A with a height of 3, B with a height of 1, and C with a height of 2. So we lay the elements out from left to right in the order A->B->C, and we align them along the top.

That layout would look like this:

A B C

A C

A

Enumerations:

kLayoutHorizontalTop (5) - Lay out the elements horizontally, aligning elements of uneven height along the top.
kLayoutHorizontalCenter (6) - Lay out the elements horizontally, aligning elements of uneven height along the center.
kLayoutHotizontalBottom (7) - Lay out the elements horizontally, aligning elements of uneven height along the bottom.
kLayoutVerticalLeft (9) - Lay out the elements vertically, aligning elements of uneven width along the left.
kLayoutVerticalCenter (10) - Lay out the elements vertically, aligning elements of uneven width along the center.
kLayoutVerticalRight (11) - Lay out the elements vertically, aligning the elements of uneven width along the right.
kLayoutOverlay (14) - Lay out the elements on top of one another, from the center.

Function Documentation

void flatui::ApplyCustomTransform ( const mathfu::mat4 & imvp )

If you're rendering the UI at a location that does not correspond to the display's pixels (e.g. in 3D), this call allows you to set your a custom transform that corresponds to the inverse of your model-view- projection matrix. FlatUI will then transform all incoming (screen-space) pointer events with this, such that they are mapped to coordinates that match what was passed to UseExistingProjection. Important that the UI was rendered with object space coordinates ranging from (0,0) to canvas_size as well. Call this at the start of your UI. For an example of how to use this, see flatuisample_3d.cpp.

Parameters

[in] imvp The inverse model-view-projection matrix.

void flatui::CapturePointer ( const char * element_id )

Caputre a pointer event.

After an API call, the element with element_id will exclusively receive pointer events until ReleasePointer() is called. This API is used mainly for a drag operation, when an element wants to receive events continuously.

Note: This function is specific to a group, and should be called after StartGroup() and before any elements.

Parameters

[in] element_id A C-string in UTF-8 format that contains the ID of the element that should capture all pointer events.

Event flatui::CheckEvent ( )

Check for events from the current group.

Calling CheckEvent() marks the current element as an "interactive" element. Each interactive elements needs to have a unique ID in order to properly to receive a keyboard/gamepad focus.

IDs for Labels and Images are derived from hashing its contents. The user can also specify IDs for CustomElement and Edit elements as an argument.

If multiple interactive elements have the same ID, a keyboard/gamepad focus navigation will not work as expected (e.g. a focus jump to other elements that share the same ID while naviating with a gamepad).

Note: This function is specific to a group, and should be called after StartGroup() and before any elements.

Returns: Returns the Event type for the group.

Event flatui::CheckEvent ( bool check_dragevent_only )

Check for events from the current group.

Parameters

[in] check_dragevent_only A bool to check if only a drag event occurred (ignore button events). If an element is not interested in button events, then this flag should be set by the caller because elements can only receive the WENT_UP event if it is the same element that received the corresponding WENT_DOWN event.

Note: This function is specific to a group, and should be called after StartGroup() and before any elements.

Returns: Returns the Event type for the group.

void flatui::ColorBackground ( const mathfu::vec4 & color )

Set the background color for the group.

Parameters

[in] color A vec4 representing the background color that should be set in RGBA.

Note: This function is specific to a group, and should be called after StartGroup() and before any elements.

void flatui::CustomElement	(	const mathfu::vec2 &	virtual_size,
		const char *	id,
		const std::function< void(const mathfu::vec2i &pos, const mathfu::vec2i &size)>	renderer
	)

Create a custom element with a given size.

Parameters

[in]	virtual_size	The size of the element in virtual screen coordinates.
[in]	id	A C-string in UTF-8 format corresponding to the unique ID for the CustomElement.
[in]	renderer	The function that is invoked during the render pass to render the element.

Event flatui::Edit	(	float	ysize,
		const mathfu::vec2 &	size,
		const char *	id,
		EditStatus *	status,
		std::string *	string
	)

Renders an edit text box as a GUI element.

Parameters

[in]	ysize	A float containing the vertical size in virtual resolution.
[in]	size	A mathfu::vec2 reference to the size of the edit box in virtual resolution. A `0` for `size.x` indicates an auto expanding text box. A `0` for `size.y` indicates a single line label.
[in]	id	A C-string in UTF-8 format to uniquely idenitfy this edit box.
	in/out]	status A pointer to a EditStatus that indicates the status of Edit widget. Can be nullptr if the caller doesn't require the information.
	in/out]	string A pointer to a C-string in UTF-8 format that should be used as the Label for the edit box.

Returns: Returns the Event type for the Edit widget.

Event flatui::Edit	(	float	ysize,
		const mathfu::vec2 &	size,
		TextAlignment	alignment,
		const char *	id,
		EditStatus *	status,
		std::string *	string
	)

Render an edit text box with a text alignment.

Parameters

[in]	ysize	A float containing the vertical size in virtual resolution.
[in]	size	A mathfu::vec2 reference to the size of the edit box in virtual resolution. A `0` for `size.x` indicates an auto expanding text box. A `0` for `size.y` indicates a single line label.
[in]	alignment	An alignment of the text in the edit box.
[in]	id	A C-string in UTF-8 format to uniquely idenitfy this edit box.
	in/out]	status A pointer to a EditStatus that indicates the status of Edit widget. Can be nullptr if the caller doesn't require the information.
	in/out]	string A pointer to a C-string in UTF-8 format that should be used as the Label for the edit box.

Returns: Returns the Event type for the Edit widget.

void flatui::EnableTextHyphenation ( bool enable )

Enable/Disable the hyphenation in the text label.

Parameters

[in] enable A flag indicate hyphenation state.

void flatui::EnableTextSDF	(	bool	inner_sdf,
		bool	outer_sdf,
		float	threshold
	)

Enable/Disable a signed distance field generation with glyphs. A SDF generation of an inner region and an outer region is done separately and it costs some cycles. So if an application doesn't utilize inner SDF, just enable outer SDF.

Parameters

[in]	inner_sdf	set true to enable a distance field generation for an inner region of a glyph. false to disable it.
[in]	outer_sdf	set true to enable a distance field generation for an outer region of a glyph. false to disable it.
[in]	threshold	Threshold value used in the SDF glyph rendering. The value controls a threshold if a pixel nearby a glyph edge is considered inside a glyph or not. Typical value range is around 8.0f/255.0f ~ 24.0f/255f and it varies by font face. As the speficied value get bigger, rendered glyph images become bold. Default value is 16.0f/255.0f.

void flatui::EndGroup ( )

Clean up the Group element start by StartGroup().

Note: StartGroup() and EndGroup() calls must be matched. They may, however, be nested to create more complex layouts.

void flatui::EndScroll ( )

Ends the current scrolling group.

Note: Call EndScroll() right before EndGroup().

void flatui::EndSlider ( )

Ends the current slider group.

Note: Call EndSlider() right before EndGroup().

ssize_t flatui::GetCapturedPointerIndex ( )

Get the index of th ecaptured pointer.

This should be used in conjunction with CheckEvent() to determine whether a drag operation is in progress.

Note: This function is specific to a group, and should be called after StartGroup() and before any elements.

Returns: Returns the index of the pointer as a ssize_t. Otherwise it returns -1 if no pointer was captured.

float flatui::GetScale ( )

Get the scaling factor for the virtual resolution.

Returns: Returns a float representing the scaling factor.

mathfu::vec2 flatui::GetVirtualResolution ( )

Returns: Returns the virtual resolution of the screen.

mathfu::vec2 flatui::GroupPosition ( )

Returns: Returns the position of the current group in virtual coordinates.

This is the top/left location of the group. When used in conjunction with GroupSize(), this can be used t ocalculate the extents of the group.

mathfu::vec2 flatui::GroupSize ( )

Returns: Returns the current group's size in virtual coordinates. This function is useful to implement UI that requires other element's sizes, such as a scroll bar.

void flatui::HtmlLabel	(	const char *	html,
		float	ysize,
		const mathfu::vec2 &	label_size,
		TextAlignment	alignment,
		const char *	id
	)

Render simple HTML text.

Parameters

[in]	html	A C-string in UTF-8 format to be parsed as HTML and then displayed. Note that we support only a simple subset of HTML at the moment, including anchor tags, paragraphs, headers, and breaks.
[in]	ysize	A float containing the vertical size in virtual resolution.
[in]	label_size	The max size of the label in virtual resolution. A `0` for `size.y` indicates no height restriction. The API renders the whole text in the label in this case.
[in]	alignment	A text alignment in the label.
[in]	id	An id of the label.

void flatui::Image	(	const fplbase::Texture &	texture,
		float	ysize,
		const char *	id = `kDefaultImageID`
	)

Render an image as a GUI element.

Parameters

[in]	texture	A Texture corresponding to the image that should be rendered.
[in]	ysize	A float containing the vertical size in virtual resolution.
[in]	id	An id to uniquely identify the image.

Note: The x-size will be derived automatically based on the image dimensions.

void flatui::ImageBackground ( const fplbase::Texture & tex )

Set the background texture for the group.

Note: This function is specific to a group, and should be called after StartGroup() and before any elements.

Parameters

[in] tex The Texture to be set as the background for the group.

void flatui::ImageBackgroundNinePatch	(	const fplbase::Texture &	tex,
		const mathfu::vec4 &	patch_info
	)

Set the background texture for the group with nine patch settings.

In the patch_info, the user can define nine patch settings as vec4(x0, y0, x1, y1), where (x0, y0) corresponds to the top-left corner of the stretchable area in UV coordinates and (x1, y1) corresponds to the bottom-right corner of stretchable area in UV coordinates.

The coordinates are in UV value in the texture (0.0 ~ 1.0).

For more information for nine patch, refer http://developer.android.com/guide/topics/graphics/2d-graphics.html#nine-patch

Note: This function is specific to a group, and should be called after StartGroup() and before any elements.

Parameters

[in]	tex	The Texture of the background image that should be rendered.
[in]	patch_info	The nine-patch settings for the corners of the stretchable area in UV coordinates.

bool flatui::IsLastEventPointerType ( )

Returns: Returns true if the last click event was a touch screen or mouse event. Otherwise, it returns false (e.g. from a gamepad or keyboard).

void flatui::Label	(	const char *	text,
		float	ysize,
		HashedId	label_id = `kNullHash`
	)

Render a label as a GUI element.

Parameters

[in]	text	A C-string in UTF-8 format to be displayed as the label.
[in]	ysize	A float containing the vertical size in virtual resolution.
[in]	label_id	A HashedId that defaults to null. If it is null, the text will be hashed and used as label_id.

Note: The x-size will be derived automatically based on the text length.

void flatui::Label	(	const char *	text,
		float	ysize,
		const mathfu::vec2 &	size,
		HashedId	label_id = `kNullHash`
	)

Render a multi-line version of a label as a GUI element.

Parameters

[in]	text	A C-string in UTF-8 format to be displayed as the label.
[in]	ysize	A float containing the vertical size in virtual resolution.
[in]	size	The max size of the label in virtual resolution. A `0` for `size.y` indicates no height restriction. The API renders the whole text in the label in this case.
[in]	label_id	A HashedId that defaults to null. If it is null, the text will be hashed and used as label_id.

void flatui::Label	(	const char *	text,
		float	ysize,
		const mathfu::vec2 &	label_size,
		TextAlignment	alignment,
		HashedId	label_id = `kNullHash`
	)

Render a multi-line label with a text alignment.

Parameters

[in]	text	A C-string in UTF-8 format to be displayed as the label.
[in]	ysize	A float containing the vertical size in virtual resolution.
[in]	alignment	A text alignment in the label.
[in]	size	The max size of the label in virtual resolution. A `0` for `size.y` indicates no height restriction. The API renders the whole text in the label in this case.
[in]	label_id	A HashedId that defaults to null. If it is null, the text will be hashed and used as label_id.

void flatui::ModalGroup ( )

Called inside of a group that that is mean to act like a popup inside of a kLayoutOverlay.

It will cause all interactive elements in the groups that precede it to not respond to input.

Note: This function is specific to a group, and should be called after StartGroup() and before any elements.

mathfu::vec2 flatui::PhysicalToVirtual ( const mathfu::vec2i & v )

Converts a physical screen coordinate to a virtual value.

Parameters

[in] v A mathfu::vec2i vector representing a phsyical screen coordinate.

Returns: Returns a mathfu::vec2 containing the virtual value.

void flatui::PositionGroup	(	Alignment	horizontal,
		Alignment	vertical,
		const mathfu::vec2 &	offset
	)

Position a group within the screen as a whole.

Note: This should be called as the first thing in any top level groups (either your root group, or the children of your root, if the root is kLayoutOverlay.

Parameters

[in]	horizontal	The alignment for the x-axis of the group (defaults to `left`).
[in]	vertical	The alignment for the y-axis of the group (defaults to `top`).
[in]	offset	A vec2 that allows you to displace elements from the given alignment.

void flatui::ReleasePointer ( )

Release a pointer capture.

Note: This function is specific to a group, and should be called after StartGroup() and before any elements.

void flatui::RenderTexture	(	const fplbase::Texture &	tex,
		const mathfu::vec2i &	pos,
		const mathfu::vec2i &	size
	)

Render a Texture to a specific position with a given size.

Note: This is usually called in CustomElement()'s callback function.

Parameters

[in]	tex	The Texture to render.
[in]	pos	The position that `tex` should be rendered at, in physical screen coordinates.
[in]	size	The size that `tex` should be rendered at, in physical screen coordinates.

void flatui::RenderTexture	(	const fplbase::Texture &	tex,
		const mathfu::vec2i &	pos,
		const mathfu::vec2i &	size,
		const mathfu::vec4 &	color
	)

Render a Texture to a specific position with a given size and color.

Note: This is usually called in CustomElement()'s callback function.

Parameters

[in]	tex	The Texture to render.
[in]	pos	The position that `tex` should be rendered at, in physical screen coordinates.
[in]	size	The size that `tex` should be rendered at, in physical screen coordinates.
[in]	color	A vec4 representing the color of the texture that should be rendered in RGBA.

void flatui::RenderTextureNinePatch	(	const fplbase::Texture &	tex,
		const mathfu::vec4 &	patch_info,
		const mathfu::vec2i &	pos,
		const mathfu::vec2i &	size
	)

Render a nine-patch texture at a specific position with a given size.

Note: This is usually used in CustomElement()'s callback function.

In the patch_info, the user can define nine patch settings as vec4(x0, y0, x1, y1), where (x0, y0) corresponds to the top-left corner of the stretchable area in UV coordinates and (x1, y1) corresponds to the bottom-right corner of stretchable area in UV coordinates.

The coordinates are in UV value in the texture (0.0 ~ 1.0).

For more information for nine patch, refer http://developer.android.com/guide/topics/graphics/2d-graphics.html#nine-patch

Parameters

[in]	tex	The Texture to render.
[in]	patch_info	The nine-patch settings for the corners of the stretchable area in UV coordinates.
[in]	pos	The position that `tex` should be rendered at, in physical screen coordinates.
[in]	size	The size that `tex` should be rendered at, in physical screen coordinates.

void flatui::Run	(	fplbase::AssetManager &	assetman,
		FontManager &	fontman,
		fplbase::InputSystem &	input,
		motive::MotiveEngine *	motive_engine,
		const std::function< void()> &	gui_definition
	)

The core function that drives the GUI.

While FlatUI i sbeing initialized, it will implicitly load the shaders used in the API below via AssetManager (shaders/color.glslv, shaders/color.glslf, shaders/font.glslv, shaders/font.glslf, shaders/textured.glslv, and shaders/textured.glslf).

Parameters

[in,out]	assetman	The AssetManager you want to use textures from.
[in]	fontman	The FontManager to be used by the GUI.
[in]	input	The InputSystem to be used by the GUI.
[in]	motive_engine	A pointer to the MotiveEngine to be used by the GUI for animation purpose.
[in]	gui_definition	A function that defines all GUI elements using the GUI element construction functions. (It will be run twice, once for the layout, and once for rendering & events.)

void flatui::SetDragStartThreshold ( int drag_start_threshold )

Set a threshold value for the start of a drag operation.

The default value is kDragStartThresholdDefault.

Parameters

[in] drag_start_threshold An int determining the new threshold value for the start of a drag operation.

Note: This function is specific to a group, and should be called after StartGroup() and before any elements.

void flatui::SetImageColor ( const mathfu::vec4 & color )

Set the Images's tint.

Parameters

[in] color The RGBA values that get multiplied into the image RGBAs. a value of mathfu::kOnes4f draws the image without change.

Note: By animating the alpha component, images can be faded out. Or, you can apply a particular hue to an image using the RGB components.

void flatui::SetMargin ( const Margin & margin )

Sets the margin for the current group.

Note: This function is specific to a group, and should be called after StartGroup() and before any elements.

Parameters

[in] margin The Margin to set for the group.

void flatui::SetScrollSpeed	(	float	scroll_speed_drag,
		float	scroll_speed_wheel,
		float	scroll_speed_gamepad
	)

Set the scroll speed of the drag, mouse wheel, and gamepad operations.

The defaults are kScrollSpeedDragDefault, kScrollSpeedWheelDefault, and kScrollSpeedGamepadDefault.

Parameters

[in]	scroll_speed_drag	A float determining the new scroll speed for dragging.
[in]	scroll_speed_wheel	A float determining the new scroll speed for the mouse scroll wheel.
[in]	scroll_speed_gamepad	A float determining the new scroll speed for a gamepad.

Note: This function is specific to a group, and should be called after StartGroup() and before any elements.

void flatui::SetTextColor ( const mathfu::vec4 & color )

Set the Label's text color.

Parameters

[in] color A vec4 representing the RGBA values that the text color should be set to.

void flatui::SetTextDirection ( const TextLayoutDirection direction )

Override a text layout direction set by SetTextLocale() API.

Parameters

[in] direction TextLayoutDirection specifying text layout direction.

void flatui::SetTextEllipsis ( const char * ellipsis )

Set an ellipsis string used in label/edit widgets.

Parameters

[in] ellipsis A C-string specifying characters used as an ellipsis. Can be multiple characters, typically '...'. When a string in a widget doesn't fit to the given size, the string is truncated to fit the ellipsis string appended at the end.

bool flatui::SetTextFont ( const char * font_name )

Set the Label's font.

Parameters

[in] font_name A C-string corresponding to the name of the font that should be set.

Returns: Returns true if the font file is succeffully opened.

bool flatui::SetTextFont	(	const char *	font_names[],
		int32_t	count
	)

Set the Label's fonts with a fallback priority. When rendering a text, if a glyph is not found in the first font in the array, the renderer will look up the glyph in the second font and so on. If the glyph is not found in all font files, the glyph won't be rendered on the screen.

Parameters

[in]	font_names	An array of C-string corresponding to the name of the font. Font names in the array are stored in a priority order.
[in]	count	A count of font names in the array.

Returns: Returns true if the font files are succeffully opened.

void flatui::SetTextKerningScale ( float scale )

Set a kerning scale used in the text rendering.

Parameters

[in] scale A kerning scale value applied kerning values. The default value is kKerningScale(1.0f).

void flatui::SetTextLineHeightScale ( float scale )

Set a line height scale used in the text rendering.

Parameters

[in] scale A line height value. The value is multiplied to the font height and determines a space between lines. The default value is kLineHeightDefault(1.2f).

void flatui::SetTextLocale ( const char * locale )

Set a locale used for the text rendering.

Parameters

[in] locale A C-string corresponding to the of the language defined in ISO 639 and country code defined in ISO 3166 connected by '-'. (e.g. 'en-US'). The API sets language, script and layout direction used for following text renderings.

void flatui::SetTextOuterColor	(	const mathfu::vec4 &	color,
		float	size,
		const mathfu::vec2 &	offset
	)

Set the Label's outer color (e.g. drop shadow color). To use the feature, outer SDF generation needs to be enabled by EnableTextSDF() API. With SDF, each glyph image includes a distance to the nearest edge. The API utilizes the feature to render an outer region of a glyph. For more details of SDF, refer a paper from Valve: http://www.valvesoftware.com/publications/2007/SIGGRAPH2007_AlphaTestedMagnification.pdf.

Parameters

[in]	color	A vec4 representing the RGBA values that the outer color should be set to.
[in]	size	A float value that changes the size of outer color region in pixels. Typical value range is around 64.0f/255.0f but varies by font face. As the value get bigger, the shadow region gets spread out.
[in]	offset	A vec2 value that controls a position of the outer color region in pixels.

void flatui::SetVirtualResolution ( float virtual_resolution )

Set the virtual resolution of the smallest dimension of the screen (the Y size in landscape mode, or X in portrait).

All dimensions specified elsewhere (in floats) are relative to this value.

The default value, if this function is not called, is FLATUI_DEFAULT_VIRTUAL_RESOLUTION.

If you wish to use native pixels, call this with min(screen_x, screen_y).

Note: This should be called as the first thing in your GUI definition.

Parameters

[in] virtual_resolution A float representing the virtual resolution of the smallest dimension of the screen.

void flatui::StartGroup	(	Layout	layout,
		float	spacing = `0`,
		const char *	id = `kDefaultGroupID`
	)

Create a group of elements with a given layout and intra-element spacing.

Note: StartGroup() and EndGroup() calls must be matched. They may, however, be nested to create more complex layouts.

Parameters

[in]	layout	The Layout to be used by the group.
[in]	spacing	A float corresponding to the intra-element spacing for the group.
[in]	id	A C-string in UTF-8 format to uniquely identify this group.

void flatui::StartScroll	(	const mathfu::vec2 &	size,
		mathfu::vec2 *	offset
	)

Make the current group into a scrolling group that can display arbitrary sized elements inside a window of "size", scrolled to the current "offset" (which the caller should store somewhere that survives the current frame).

Parameters

[in]	size	A vec2 corresponding to the size of the window that the elements should be displayed in.
[out]	offset	A vec2 that captures the value of the current scroll location.

Note: Call StartScroll() right after StartGroup().

void flatui::StartSlider	(	Direction	direction,
		float	scroll_margin,
		float *	value
	)

Make the current group into a slider group that can handle basic slider behavior. The group will capture/release the pointer as necessary.

Parameters

[in]	direction	Sets the horizontal or vertical scroll direction.
[in]	scroll_margin	Sets the margin around the scroll bar.
[out]	value	Captures the float output of the slider value.

Note: Call StartSlider() right after StartGroup().

void flatui::UseExistingProjection ( const mathfu::vec2i & canvas_size )

By default, FlatUI sets up a projection matrix for all the rendering that covers the entire screen (as given by Renderer::window_size(). You can call to this function instead, to use whatever projection is in place before Run() is called (which may be a 2D or 3D projection).

Parameters

[in] canvas_size Specifies the new canvas size for the UI to live inside of.

mathfu::vec2i flatui::VirtualToPhysical ( const mathfu::vec2 & v )

Converts a virtual screen coordinate to a physical value.

Parameters

[in] v A mathfu::vec2 vector representing a virtual screen coordinate.

Returns: Returns a mathfu::vec2i containing the physical value.

Detailed Description

Classes

Enumerations

Functions

Variables

Enumeration Type Documentation

Function Documentation