Namespace for FlatUI library. More...

Classes
struct	AnimCurveDescription
	Describes a curve's typical shape. More...

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

struct	FontFamily
	A class holding font family information. The class provides various ways to support fonts such as a font collection (multiple fonts in a file), referencing a font by a famly name etc. More...

class	FontBufferParameters
	This class that includes font buffer parameters. It is used as a key in the unordered_map to look up FontBuffer. More...

struct	LinkInfo
	HTML link href, and the location of the link text in FontBuffer. More...

class	FontMetrics
	This class has additional properties for font metrics. More...

struct	FontVertex
	This struct holds all the font vertex data. More...

class	FontBufferAttributes
	A structure holding attribute information of texts in a FontBuffer. More...

class	FontBufferContext
	Temporary buffers used while generating FontBuffer. Word boundary information. This information is used only with a typography layout with a justification. More...

struct	GlyphInfo
	This struct holds the glyph information that is used when re-creating a FontBuffer. More...

class	FontBuffer
	this is used with the texture atlas rendering. More...

class	FontManager
	FontManager manages font rendering with OpenGL utilizing freetype and harfbuzz as a glyph rendering and layout back end. More...

struct	ScriptInfo
	This struct holds the script information used for a text layout. More...

class	FontShader
	Helper class to handle shaders for a font rendering. The class keeps a reference to a shader, and a location of uniforms with a fixed names. A caller is responsive not to call set_* APIs that specified shader doesn't support. More...

Enumerations
enum	AnimType { kAnimEaseInEaseOut, kAnimSpring, kAnimTypeCount }
	Anim type describes the algorithm used to animate a UI element. More...

enum	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	Alignment { kAlignTop = 1, kAlignLeft = 1, kAlignCenter = 2, kAlignBottom = 3, kAlignRight = 3 }
	Alignment of the groups. More...

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

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

enum	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...

enum	ButtonProperty { kButtonPropertyDisabled = 1, kButtonPropertyImageLeft = 2, kButtonPropertyImageRight = 4 }
	Specifies the button properties used in common widgets. More...

enum	TextLayoutDirection { kTextLayoutDirectionLTR = 0, kTextLayoutDirectionRTL = 1, kTextLayoutDirectionTTB = 2 }
	Specify how to layout texts. Default value is TextLayoutDirectionLTR.

enum	TextAlignment { kTextAlignmentLeft = 0, kTextAlignmentRight = 1, kTextAlignmentCenter = 2, kTextAlignmentJustify = 4, kTextAlignmentLeftJustify = kTextAlignmentJustify, kTextAlignmentRightJustify = kTextAlignmentJustify \| kTextAlignmentRight, kTextAlignmentCenterJustify = kTextAlignmentJustify \| kTextAlignmentCenter }
	Alignment of the text. More...

enum	FontBufferStatus { kFontBufferStatusReady = 0, kFontBufferStatusNeedReconstruct = 1, kFontBufferStatusNeedCacheUpdate = 2 }
	A status of FontBuffer correspoinding current glyph cache contents. Enumerations: More...

enum	EllipsisMode { kEllipsisModeTruncateCharacter = 0, kEllipsisModeTruncateWord = 1 }
	A flag controlling appending behavior of the ellipsis. Enumerations: More...

Functions
void	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	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	VirtualToPhysical (const mathfu::vec2 &v)
	Converts a virtual screen coordinate to a physical value. More...

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

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

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

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

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

void	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	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	HtmlLabel (const char html, float ysize, const mathfu::vec2 &label_size, TextAlignment alignment, const char id)
	Render simple HTML text. More...

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

void	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	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	EnableTextHyphenation (bool enable)
	Enable/Disable the hyphenation in the text label. More...

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

bool	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	SetTextLocale (const char *locale)
	Set a locale used for the text rendering. More...

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

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

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

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

Event	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	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	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	EndGroup ()
	Clean up the Group element start by `StartGroup()`. More...

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

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

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

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

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

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

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

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

void	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	SetDragStartThreshold (int drag_start_threshold)
	Set a threshold value for the start of a drag operation. More...

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

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

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

void	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	EndScroll ()
	Ends the current scrolling group. More...

void	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	EndSlider ()
	Ends the current slider group. More...

void	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	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	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	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	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	GetVirtualResolution ()

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

void	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	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	GroupPosition ()

mathfu::vec2	GroupSize ()

bool	IsLastEventPointerType ()

void	SetGlobalListener (const std::function< void(HashedId id, Event event)> &callback)
	Set a global listener callback that receives all events to all interactive elements (useful for logging/debugging/analytics etc, NOT intended for normal event handling). Does not affect events in the rest of the API. Gets called for all events except None, you must do your own filtering. Call this function as the first thing inside of Run(). Callback never fires outside of Run(). Use HashId() to compare against ids of elements you may be interested in.

const FlatUIVersion *	GetFlatUIVersion ()

void	SetDepthTest (bool enable)
	Enables depth testing, when needed for rendering a UI in 3D. More...

double	AnimationTimeRemaining (HashedId id)
	Returns the time remaining for an animation. More...

double	AnimationTimeRemaining (const char *id)
	Returns the time remaining for an animation. More...

int	NumActiveSprites (HashedId id)
	This function returns the current number of sprites animating on screen. More...

int	NumActiveSprites (const char *id)
	This function returns the current number of sprites animating on screen. More...

SequenceId	AddSprite (const char *group_id, const std::function< bool(SequenceId seq)> &draw)
	This function adds a sprite, which will be drawn and then forgotten after it is finished firing. More...

void	DrawSprites (const char *group_id)
	Draws all the sprites created with 'group_id' in AddSprite(). More...

template<typename T >
T	Animatable (HashedId id, const T &starting_value)
	This function creates a new Motivator if it doesn't already exist and returns the current value of it. More...

template<typename T >
T	Animatable (const char *id, const T &starting_value)
	This function creates a new animation if it doesn't already exist and returns the current value of it. More...

template<typename T >
void	StartAnimation (HashedId id, const T &target_value, const T &target_velocity, const AnimCurveDescription &description)
	This function sets the target value and velocity to which an animation, that is identified by id, animates. More...

template<typename T >
void	StartAnimation (const char *id, const T &target_value, const T &target_velocity, const AnimCurveDescription &description)
	This function sets the target value and velocity to which an animation, that is identified by id, animates. More...

ButtonProperty	operator\| (ButtonProperty a, ButtonProperty b)
	The bitwise OR operator for ButtonProperties. More...

ButtonProperty	operator\|= (ButtonProperty &a, const ButtonProperty &b)
	The bitwise OR assignment operator for ButtonProperties. More...

void	SetHoverClickColor (const mathfu::vec4 &hover_color, const mathfu::vec4 &click_color)
	Some of the widgets provide user feedback by rendering a transparent background color to signal that the user is hovering over or clicking/touching/interacting with the widget. More...

Event	TextButton (const char *text, float size, const Margin &margin)
	A simple button showing clickable text. More...

Event	ImageButton (const fplbase::Texture &texture, float size, const Margin &margin, const char *id)
	A simple button showing a clickable image. More...

Event	ToggleImageButton (const fplbase::Texture &up_texture, const fplbase::Texture &down_texture, float size, const Margin &margin, const char *id)
	A button showing a different image when clicked or not. More...

Event	TextButton (const fplbase::Texture &texture, const Margin &texture_margin, const char *text, float size, const Margin &margin, const ButtonProperty property)
	A simple button showing clickable text with an image shown beside it. More...

Event	CheckBox (const fplbase::Texture &texture_checked, const fplbase::Texture &texture_unchecked, const char label, float size, const Margin &margin, bool is_checked)
	A checkbox with a label next to it. More...

Event	Slider (const fplbase::Texture &tex_bar, const fplbase::Texture &tex_knob, const mathfu::vec2 &size, float bar_height, const char id, float slider_value)
	A clider to change a numeric value. More...

Event	ScrollBar (const fplbase::Texture &tex_background, const fplbase::Texture &tex_foreground, const mathfu::vec2 &size, float bar_size, const char id, float scroll_value)
	A scrollbar to indicate position in a scroll view. More...

void	EventBackground (Event event)
	Sets a background color of the widget based on the event status. More...

Variables
static const int	kMaxDimensions = 4

static const int	kSecondsToMotiveTime = 10000

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

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

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

const int32_t	kFreeTypeUnit = 64
	Constant to convert FreeType unit to pixel unit. More...

const float	kLineHeightDefault = 1.2f
	Default value for a line height factor. More...

const float	kKerningScaleDefault = 1.0f
	Default value for a kerning scale factor. More...

const mathfu::vec2i	kCaretPositionInvalid = mathfu::vec2i(-1, -1)
	A sentinel value representing an invalid caret position.

const int32_t	kIndexInvalid = -1

const uint32_t	kDefaultColor = 0xffffffff

const int32_t	kVerticesPerGlyph = 4

const int32_t	kIndicesPerGlyph = 6
	The number of vertices/indices per a glyph entry.

const int32_t	kGlyphCacheWidth = 1024
	The default size of the glyph cache width.

const int32_t	kGlyphCacheHeight = 1024
	The default size of the glyph cache height.

const int32_t	kGlyphCacheMaxSlices = 4
	The default size of the max glyph cache slices. The number of cache slices grows up to the value.

const char *const	kDefaultLanguage = "en"
	The default language used for a line break.

const char *const	kSystemFont = ".SystemFont"
	A constant to spefify loading a system font. Used with OpenFont() and SelectFont() API Currently the system font is supported on iOS/macOS and Android only.

static const HashedId	kSystemFontId = HashId(kSystemFont)

Detailed Description

Namespace for FlatUI library.

Enumeration Type Documentation

enum flatui::AnimType

Anim type describes the algorithm used to animate a UI element.

All algorithms maintain the current value and velocity, so any animation can be smoothly interrupted by another animation, even if they are of different types.

Enumerations:

kAnimEaseInEaseOut (0) - Smoothly curve towards the target value (i.e. ease-in) and smoothly stop at the target value (i.e. ease-out). The smoothness of the in and out is determined by the bias in AnimCurveDescription. | target + ********* | ******* | **** | **** | *** | *** | ** | *** | ** | ** | ** | bias 0.15 ** | ** | * | ** | ** | * | ** | *** start +***
kAnimSpring (1) - Oscillate about the target value, with each peak having amplitude of the previous peak * bias. So, if bias < 1, the amplitude dampens down and eventually the curve reaches the target. If bias > 1, the amplitude grows with each oscillation. If bias = 1, then the amplitude remains the same for every oscillation. Note that true spring motion follows a sine curve, but a sine curve does not move aggressively enough for convincing motion, so internally we follow a quadratic curve instead.

Function Documentation

SequenceId flatui::AddSprite	(	const char *	group_id,
		const std::function< bool(SequenceId seq)> &	draw
	)

This function adds a sprite, which will be drawn and then forgotten after it is finished firing.

A sprite would be a UI element that gets drawn onto the screen with a limited lifespan. For this usage, the sprite could be, for example, an image or text. This makes it useful for situations where the user would want a temporary animation. For example, in a game, a sprite could be points that appear and drift off screen when a user earns points for a turn. The returned SequenceId is so that the application can recalculate the hash assigned to a specific sprite using its id and sequence number. An example of how to pass in a lambda for the draw parameter can be found in the FlatUI animation demo.

Parameters

[in]	group_id	A C-string in UTF-8 format that uniquely identifies an animation type.
[in]	draw	A function that tells the program how to draw the sprite associated with id.

Returns: Returns the SequenceId assigned to the sprite associated with id.

template<typename T >

T flatui::Animatable	(	HashedId	id,
		const T &	starting_value
	)

This function creates a new Motivator if it doesn't already exist and returns the current value of it.

Warning: This function only works if you have passed in a MotiveEngine to Run().

Parameters

[in]	id	A HashedId that uniquely identifies an animation.
[in]	starting_value	An array of length dimensions that contains the value we want our curve to begin at.

Returns: Returns a value of type T.

template<typename T >

T flatui::Animatable	(	const char *	id,
		const T &	starting_value
	)

This function creates a new animation if it doesn't already exist and returns the current value of it.

Warning: This function only works if you have passed in a MotiveEngine to Run().

Parameters

[in]	id	A C-string in UTF-8 format that uniquely identifies an animation.
[in]	starting_value	An array of length dimensions that contains the value we want our curve to begin at.

Returns: Returns a value of type T.

double flatui::AnimationTimeRemaining ( HashedId id )

Returns the time remaining for an animation.

Parameters

[in] A HashedId that uniquely identifies an animation.

Returns: Returns a double representing the time remaining.

double flatui::AnimationTimeRemaining ( const char * id )

inline

Returns the time remaining for an animation.

Parameters

[in] id A C-string in UTF-8 format that uniquely identifies an animation.

Returns: Returns a double representing the time remaining.

void flatui::DrawSprites ( const char * group_id )

Draws all the sprites created with 'group_id' in AddSprite().

Parameters

[in] group_id A C-string in UTF-8 format that uniquely identifies an animation type.

int flatui::NumActiveSprites ( HashedId id )

This function returns the current number of sprites animating on screen.

Parameters

[in] id A HashedId that identifies an animation type.

Returns: Returns the size_t associated with the size of the sprites vector.

int flatui::NumActiveSprites ( const char * id )

inline

This function returns the current number of sprites animating on screen.

Parameters

[in] id A C-string in UTF-8 format that identifies an animation type.

Returns: Returns the size_t associated with the size of the sprites vector.

void flatui::SetDepthTest ( bool enable )

Enables depth testing, when needed for rendering a UI in 3D.

For example, a simple FlatUI::Label() could be rendered, with appropriate depth, on entities in the world to display the game's score as an overlay.

Warning: This approach only works for 'simple' UIs, because more complex UIs require overlapping UI elements. Depending on the precision of the z-buffer, elements will be susceptible to z-fighting. That is, when the rectangles around UI elements overlap, flickering will occur.

template<typename T >

void flatui::StartAnimation	(	HashedId	id,
		const T &	target_value,
		const T &	target_velocity,
		const AnimCurveDescription &	description
	)

This function sets the target value and velocity to which an animation, that is identified by id, animates.

It also creates a new animation if it doesn't already exist.

Parameters

[in]	id	A HashedId that uniquely identifies an animation.
[in]	target_value	An array of length dimensions that contains the value we want our curve to end at.
[in]	target_velocity	An array of length dimensions that contains the velocity we want our curve to end at. A velocity of 0.0f would mean our curve would end with a flatter ease-out curve. A large velocity would give our curve a steeper ease-out. If the curve is overdetermined, the desired end velocities might not be achieved.
[in]	description	A description of the curve's typical shape.

template<typename T >

void flatui::StartAnimation	(	const char *	id,
		const T &	target_value,
		const T &	target_velocity,
		const AnimCurveDescription &	description
	)

This function sets the target value and velocity to which an animation, that is identified by id, animates.

It also creates a new animation if it doesn't already exist.

Parameters

[in]	id	A C-string in UTF-8 format that uniquely identifies an animation.
[in]	target_value	An array of length dimensions that contains the value we want our curve to end at.
[in]	target_velocity	An array of length dimensions that contains the velocity we want our curve to end at. A velocity of 0.0f would mean our curve would end with a flatter ease-out curve. A large velocity would give our curve a steeper ease-out. If the curve is overdetermined, the desired end velocities might not be achieved.
[in]	description	A description of the curve's typical shape.

Classes

Enumerations

Functions

Variables

Detailed Description

Enumeration Type Documentation

Function Documentation