TextAttributeControl

class HPS::TextAttributeControl : public HPS::Control 

The HPS::TextAttributeControl class is a smart pointer that is tied to a database object. This object gives you access to all the attributes associated with text, such as font, size, and rotation. Text characteristics such as bold, italic, and underline are also accessed through the HPS::TextAttributeControl.

Default values for the various fields of HPS::TextAttributeControl can be found here.

Public Functions

inline virtual HPS::Type ObjectType() const

This function returns the type the object, as declared (if the object is derived, this does not give the true type of the derived object).

Returns: The declared type of the object in question, which may differ from the true, underlying type.

TextAttributeControl &operator=(TextAttributeControl &&in_that)

The move assignment operator transfers the underlying impl of the rvalue reference to this TextAttributeControl thereby avoiding a copy.

Parameters: in_that – An rvalue reference to a TextAttributeControl to take the impl from.
Returns: A reference to this TextAttributeControl.

TextAttributeControl &operator=(TextAttributeControl const &in_that)

Share the underlying smart-pointer of the TextAttributeControl source.

Parameters: in_that – The TextAttributeControl source of the assignment.
Returns: A reference to this TextAttributeControl.

TextAttributeControl &SetAlignment(Text::Alignment in_align, Text::ReferenceFrame in_ref = Text::ReferenceFrame::WorldAligned, Text::Justification in_justify = Text::Justification::Left)

Sets the alignment for text.

Parameters

in_alignment – The alignment for text.
in_reference_frame – The reference frame for text.
in_justification – The justification for text.

Returns

A reference to this object.

TextAttributeControl &SetBackground(bool in_state)

Sets the background to be used with text.

Parameters: in_state – Whether a background is drawn for text.
Returns: A reference to this object.

TextAttributeControl &SetBackground(bool in_state, char const *in_name)

Sets the background to be used with text.

Parameters

in_state – Whether a background is drawn for text.
in_name – The name of a shape definition.

Returns

A reference to this object.

TextAttributeControl &SetBackground(char const *in_name)

Sets the background to be used with text. The state is implicitly on.

Parameters: in_name – The name of a shape definition.
Returns: A reference to this object.

TextAttributeControl &SetBackgroundMargins(float in_size, Text::MarginUnits in_units = Text::MarginUnits::Percent)

Sets the amount of additional padding around text strings when backgrounds are used.

Parameters

in_size – The size of the margins.
in_units – The units of the size.

Returns

A reference to this object.

TextAttributeControl &SetBackgroundMargins(FloatArray const &in_size, TextMarginUnitsArray const &in_units)

Sets the amount of additional padding around text strings when backgrounds are used. Additional margin values can also be referenced within definitions of background shapes and leader lines.

Parameters

in_size – The size of the margins.
in_units – The units of the size.

Returns

A reference to this object.

TextAttributeControl &SetBackgroundMargins(size_t in_count, float const in_sizes[], HPS::Text::MarginUnits const in_units[])

Sets the amount of additional padding around text strings when backgrounds are used. Additional margin values can also be referenced within definitions of background shapes and leader lines.

Parameters

in_count – The number of elements in each array.
in_sizes – The size of the margins.
in_units – The units of the size.

Returns

A reference to this object.

TextAttributeControl &SetBackgroundStyle(char const *in_name)

Allows specifying a named style to be used in the drawing of text backgrounds. If no style is specified, backgrounds inherit the face and edge attributes from the containing segment.

Parameters: in_name – The name of a style, defined in a portfolio that is accessible.
Returns: A reference to this object.

TextAttributeControl &SetBold(bool in_state)

Sets whether text should be bold. For fonts which do not have a bold variant, this setting will be ignored.

Parameters: in_state – Whether text should be bold.
Returns: A reference to this object.

TextAttributeControl &SetExtraSpace(bool in_state, float in_size = 0.0f, Text::SizeUnits in_units = Text::SizeUnits::ObjectSpace)

Sets the amount of additional space to add between characters in a text string.

Parameters

in_state – Whether to add additional space between characters in a text string.
in_size – The size of the additional space to add between characters.
in_units – The units of the size of the additional space to add between characters.

Returns

A reference to this object.

TextAttributeControl &SetExtraSpace(float in_size, Text::SizeUnits in_units)

Sets the amount of additional space to add between characters in a text string. This function implicitly enables the addition of extra space.

Parameters

in_size – The size of the additional space to add between characters.
in_units – The units of the size of the additional space to add between characters.

Returns

A reference to this object.

TextAttributeControl &SetFont(char const *in_name)

Sets the font to use for text. This must either be a builtin font or a font Visualize can locate in the directories specified by World::SetFontDirectories. If the requested font cannot be found, the stroked font will be used.

See: World::SetFontDirectories

Parameters: in_name – UTF8-encoded font name to use for text.
Returns: A reference to this TextKey.

TextAttributeControl &SetGreeking(bool in_state, float in_size = 0.0f, Text::GreekingUnits in_units = Text::GreekingUnits::ObjectSpace, Text::GreekingMode in_mode = Text::GreekingMode::Lines)

Sets the greeking settings to use for text.

Parameters

in_state – Whether greeking is enabled for text.
in_size – The size below which to draw a simple symbol in place of a character.
in_units – The units of the size below which to draw a simple glyph in place of a character.
in_mode – The type of symbol to draw for characters which are smaller than the greeking size.

Returns

A reference to this object.

TextAttributeControl &SetGreeking(float in_size, Text::GreekingUnits in_units = Text::GreekingUnits::ObjectSpace, Text::GreekingMode in_mode = Text::GreekingMode::Lines)

Sets the greeking settings to use for text. This function implicitly enables text greeking.

Parameters

in_size – The size below which to draw a simple symbol in place of a character.
in_units – The units of the size below which to draw a simple glyph in place of a character.
in_mode – The type of symbol to draw for characters which are smaller than the greeking size.

Returns

A reference to this object.

TextAttributeControl &SetItalic(bool in_state)

Sets whether text should be italic. For fonts which do not have an italic variant, this setting will be ignored.

Parameters: in_state – Whether text should be italic.
Returns: A reference to this object.

TextAttributeControl &SetLineSpacing(float in_multiplier)

Sets the line spacing multiplier for text. This is a multiple of the font size that will be used to determine spacing between lines in multi-line text string.

Parameters: in_multiplier – The line spacing multiplier for text.
Returns: A reference to this object.

TextAttributeControl &SetOverline(bool in_state)

Sets whether an overline should be drawn over text.

Parameters: in_state – Whether an overline should be drawn over text.
Returns: A reference to this object.

TextAttributeControl &SetPath(Vector const &in_path)

Sets the path for text. This setting controls the vector along which text strings will be displayed.

Parameters: in_path – The path for text.
Returns: A reference to this object.

TextAttributeControl &SetPreference(float in_cutoff, Text::SizeUnits in_units, Text::Preference in_smaller, Text::Preference in_larger)

Sets the preference for text. This setting controls which font type is used for text for “large” and “small” sizes and the cutoff at which this distinction is made.

Parameters

in_cutoff – The font size below which the smaller preference is used and above which the larger preference is used.
in_units – The units for the font size below which the smaller preference is used and above which the larger preference is used.
in_smaller – The font type preference for strings below the cutoff size.
in_larger – The font type preference for strings above the cutoff size.

Returns

A reference to this object.

TextAttributeControl &SetPreference(Text::Preference in_pref)

Sets the font type preference for text. This function implicitly sets the same font type for all text sizes.

Parameters: in_preference – The font type preference for text.
Returns: A reference to this object.

TextAttributeControl &SetRenderer(Text::Renderer in_rend)

Sets the renderer for text.

Parameters: in_renderer – The renderer for text.
Returns: A reference to this object.

TextAttributeControl &SetRotation(float in_angle)

Sets the angle characters should be rotated within text strings. This function implicitly sets a rotation state of Text::Rotation::Rotate.

Parameters: in_angle – The angle in degrees to rotate each character within text strings.
Returns: A reference to this object.

TextAttributeControl &SetRotation(Text::Rotation in_state, float in_angle = 0.0f)

Sets the angle characters should be rotated within text strings.

Parameters

in_state – Whether and how to rotate the characters within text string.
in_angle – The angle in degrees to rotate each character within text strings. This is only relevant if in_state is Text::Rotation::Rotate.

Returns

A reference to this object.

TextAttributeControl &SetSize(float in_size, Text::SizeUnits in_units)

Sets the font size to use for text.

Parameters

in_size – The size for text.
in_units – The units of the size for text.

Returns

A reference to this object.

TextAttributeControl &SetSizeTolerance(bool in_state, float in_size = 50.0f, Text::SizeToleranceUnits in_units = Text::SizeToleranceUnits::Percent)

Sets the size tolerance settings to use for text. These settings control how to render text strings which request a size not available for a bitmap font. If a size tolerance is specified and enabled, Visualize will use the nearest smaller size for the bitmap font within the tolerance in place of the requested size. If a size tolerance is not enabled, Visualize will attempt to scale up the nearest bitmap font size to the requested size. This setting has no effect for True Type or Open Type fonts.

Parameters

in_state – Whether a size tolerance is enabled for text.
in_size – The size for the tolerance.
in_units – The units of the size for the tolerance.

Returns

A reference to this object.

TextAttributeControl &SetSizeTolerance(float in_size, Text::SizeToleranceUnits in_units)

Sets the size tolerance settings to use for text. These settings control how to render text strings which request a size not available for a bitmap font. If a size tolerance is specified and enabled, Visualize will use the nearest smaller size for the bitmap font within the tolerance in place of the requested size. If a size tolerance is not enabled, Visualize will attempt to scale up the nearest bitmap font size to the requested size. This setting has no effect for True Type or Open Type fonts. This function implicitly enables a size tolerance.

Parameters

in_size – The size for the tolerance.
in_units – The units of the size for the tolerance.

Returns

A reference to this object.

TextAttributeControl &SetSlant(float in_angle)

Sets the slant angle for text. This determines how far the characters in the string are sheared to the left (negative angle) or right (positive angle) relative to the perpendicular.

Parameters: in_angle – The angle in degrees to slant text. This value must be in the range [-75.0f,+75.0f].
Returns: A reference to this object.

TextAttributeControl &SetSpacing(float in_multiplier)

Sets the spacing multiplier for text. This setting controls the spacing between adjacent characters within a string. A value of 0.0f would result in all characters being drawn on top of each other, a value of 1.0f would be the standard spacing between characters, a value of 2.0f would insert twice as much space as would normally be between two characters, and so on.

Parameters: in_multiplier – The spacing multiplier for text.
Returns: A reference to this object.

TextAttributeControl &SetStrikethrough(bool in_state)

Sets whether a strikethrough should be drawn through text.

Parameters: in_state – Whether a strikethrough should be drawn through text.
Returns: A reference to this object.

TextAttributeControl &SetTransform(Text::Transform in_trans)

Sets the transform behavior for text.

Parameters: in_transform – The transform behavior for text.
Returns: A reference to this object.

TextAttributeControl &SetUnderline(bool in_state)

Sets whether an underline should be drawn under text.

Parameters: in_state – Whether an underline should be drawn under text.
Returns: A reference to this object.

bool ShowAlignment(Text::Alignment &out_align, Text::ReferenceFrame &out_ref, Text::Justification &out_justify) const

Shows the alignment for text.

Parameters

out_alignment – The alignment for text.
out_reference_frame – The reference frame for text.
out_justification – The justification for text.

Returns

true if an alignment was set, false otherwise.

bool ShowBackground(bool &out_state, UTF8 &out_name) const

Shows the background to be used with text.

Parameters

out_state – Whether a background is drawn for text.
out_name – The name of a shape definition.

Returns

true if a spacing multiplier was set, false otherwise.

bool ShowBackgroundMargins(FloatArray &out_size, TextMarginUnitsArray &out_units) const

Shows the amount of additional padding around text strings when backgrounds are used.

Parameters

out_size – The size of the margins.
out_units – The units of the sizes.

Returns

true if a spacing multiplier was set, false otherwise.

bool ShowBackgroundStyle(UTF8 &out_name) const

Shows the named style to be used in the drawing of text backgrounds.

Parameters: out_name – The name of a style, defined in a portfolio that is accessible.
Returns: true if a spacing multiplier was set, false otherwise.

bool ShowBold(bool &out_state) const

Shows whether text should be bold.

Parameters: out_state – Whether text should be bold.
Returns: true if a bold setting was set, false otherwise.

bool ShowExtraSpace(bool &out_state, float &out_size, Text::SizeUnits &out_units) const

Shows the amount of additional space to add between characters in a text string.

Parameters

out_state – Whether to add additional space between characters in a text string.
out_size – The size of the additional space to add between characters.
out_units – The units of the size of the additional space to add between characters.

Returns

true if an extra space setting was set, false otherwise.

bool ShowFont(UTF8 &out_name) const

Shows the font to use for text.

Parameters: out_name – UTF8-encoded font name to use for text.
Returns: true if a font was set, false otherwise.

bool ShowGreeking(bool &out_state, float &out_size, Text::GreekingUnits &out_units, Text::GreekingMode &out_mode) const

Shows the greeking settings to use for text.

Parameters

out_state – Whether greeking is enabled for text.
out_size – The size below which to draw a simple symbol in place of a character.
out_units – The units of the size below which to draw a simple glyph in place of a character.
out_mode – The type of symbol to draw for characters which are smaller than the greeking size.

Returns

true if greeking settings were set, false otherwise.

bool ShowItalic(bool &out_state) const

Shows whether text should be italic.

Parameters: out_state – Whether text should be italic.
Returns: true if an italic setting was set, false otherwise.

bool ShowLineSpacing(float &out_multiplier) const

Shows the line spacing multiplier for text.

Parameters: out_multiplier – The line spacing multiplier for text.
Returns: true if a line space multiplier was set, false otherwise.

bool ShowOverline(bool &out_state) const

Shows whether an overline should be drawn over text.

Parameters: out_state – Whether an overline should be drawn over text.
Returns: true if an overline setting was set, false otherwise.

bool ShowPath(Vector &out_path) const

Shows the path for text.

Parameters: out_path – The path for text.
Returns: true if a path was set, false otherwise.

bool ShowPreference(float &out_cutoff, Text::SizeUnits &out_units, Text::Preference &out_smaller, Text::Preference &out_larger) const

Shows the preference for text.

Parameters

out_cutoff – The font size below which the smaller preference is used and above which the larger preference is used.
out_units – The units for the font size below which the smaller preference is used and above which the larger preference is used.
out_smaller – The font type preference for strings below the cutoff size.
out_larger – The font type preference for strings above the cutoff size.

Returns

true if a preference was set, false otherwise.

bool ShowRenderer(Text::Renderer &out_rend) const

Shows the renderer for text.

Parameters: in_renderer – The renderer for text.
Returns: true if a renderer was set, false otherwise.

bool ShowRotation(Text::Rotation &out_rot, float &out_angle) const

Shows the angle characters should be rotated within text strings.

Parameters

out_rot – Whether to rotate the characters within text strings, and if so, what the angle should be measured with repect to.
out_angle – The angle in degrees to rotate each character within text strings.

Returns

true if a rotation setting was set, false otherwise.

bool ShowSize(float &out_size, Text::SizeUnits &out_units) const

Shows the font size to use for text.

Parameters

out_size – The size for text.
out_units – The units of the size for text.

Returns

true if a size was set, false otherwise.

bool ShowSizeTolerance(bool &out_state, float &out_size, Text::SizeToleranceUnits &out_units) const

Shows the size tolerance settings to use for text.

Parameters

out_state – Whether a size tolerance is enabled for text.
out_size – The size for the tolerance.
out_units – The units of the size for the tolerance.

Returns

true if a size tolerance was set, false otherwise.

bool ShowSlant(float &out_angle) const

Shows the slant angle for text.

Parameters: out_angle – The angle in degrees to slant text.
Returns: true if a slang angle was set, false otherwise.

bool ShowSpacing(float &out_multiplier) const

Shows the spacing multiplier for text.

Parameters: out_multiplier – The spacing multiplier for text.
Returns: true if a spacing multiplier was set, false otherwise.

bool ShowStrikethrough(bool &out_state) const

Shows whether a strikethrough should be drawn through text.

Parameters: out_state – Whether a strikethrough should be drawn through text.
Returns: true if a strikethrough setting was set, false otherwise.

bool ShowTransform(Text::Transform &out_trans) const

Shows the transform state for text.

Parameters: out_transform – The transform state for text.
Returns: true if a transform state was set, false otherwise.

bool ShowUnderline(bool &out_state) const

Shows whether an underline should be drawn under text.

Parameters: out_state – Whether an underline should be drawn under text.
Returns: true if an underline setting was set, false otherwise.

explicit TextAttributeControl(SegmentKey &in_seg): Initializes a control tied to the segment in_seg.

TextAttributeControl(TextAttributeControl &&in_that)

The move constructor creates a TextAttributeControl by transferring the underlying impl of the rvalue reference to this TextAttributeControl thereby avoiding a copy and allocation.

Parameters: in_that – An rvalue reference to a TextAttributeControl to take the impl from.

TextAttributeControl(TextAttributeControl const &in_that): Initializes a control tied to the same object as in_that.

TextAttributeControl &UnsetAlignment()

Removes the alignment setting. If the control is attached to a WindowKey this function restores the default value of this setting as specified by TextAttributeKit::GetDefault().

Returns: A reference to this object.

TextAttributeControl &UnsetBackground()

Removes the background setting. If the control is attached to a WindowKey this function restores the default value of this setting as specified by TextAttributeKit::GetDefault().

Returns: A reference to this object.

TextAttributeControl &UnsetBackgroundMargins()

Removes the background margin setting. If the control is attached to a WindowKey this function restores the default value of this setting as specified by TextAttributeKit::GetDefault().

Returns: A reference to this object.

TextAttributeControl &UnsetBackgroundStyle()

Removes the background style setting. If the control is attached to a WindowKey this function restores the default value of this setting as specified by TextAttributeKit::GetDefault().

Returns: A reference to this object.

TextAttributeControl &UnsetBold()

Removes the bold setting. If the control is attached to a WindowKey this function restores the default value of this setting as specified by TextAttributeKit::GetDefault().

Returns: A reference to this object.

TextAttributeControl &UnsetEverything()

Removes all settings from this object. If the control is attached to a WindowKey this function restores the default settings of this control as specified by TextAttributeKit::GetDefault().

Returns: A reference to this object.

TextAttributeControl &UnsetExtraSpace()

Removes the extra space setting. If the control is attached to a WindowKey this function restores the default value of this setting as specified by TextAttributeKit::GetDefault().

Returns: A reference to this object.

TextAttributeControl &UnsetFont()

Removes the font setting. If the control is attached to a WindowKey this function restores the default value of this setting as specified by TextAttributeKit::GetDefault().

Returns: A reference to this object.

TextAttributeControl &UnsetGreeking()

Removes the greeking setting. If the control is attached to a WindowKey this function restores the default value of this setting as specified by TextAttributeKit::GetDefault().

Returns: A reference to this object.

TextAttributeControl &UnsetItalic()

Removes the italic setting. If the control is attached to a WindowKey this function restores the default value of this setting as specified by TextAttributeKit::GetDefault().

Returns: A reference to this object.

TextAttributeControl &UnsetLineSpacing()

Removes the line spacing setting. If the control is attached to a WindowKey this function restores the default value of this setting as specified by TextAttributeKit::GetDefault().

Returns: A reference to this object.

TextAttributeControl &UnsetOverline()

Removes the overline setting. If the control is attached to a WindowKey this function restores the default value of this setting as specified by TextAttributeKit::GetDefault().

Returns: A reference to this object.

TextAttributeControl &UnsetPath()

Removes the path setting. If the control is attached to a WindowKey this function restores the default value of this setting as specified by TextAttributeKit::GetDefault().

Returns: A reference to this object.

TextAttributeControl &UnsetPreference()

Removes the preference setting. If the control is attached to a WindowKey this function restores the default value of this setting as specified by TextAttributeKit::GetDefault().

Returns: A reference to this object.

TextAttributeControl &UnsetRenderer()

Removes the renderer setting. If the control is attached to a WindowKey this function restores the default value of this setting as specified by TextAttributeKit::GetDefault().

Returns: A reference to this object.

TextAttributeControl &UnsetRotation()

Removes the rotation setting. If the control is attached to a WindowKey this function restores the default value of this setting as specified by TextAttributeKit::GetDefault().

Returns: A reference to this object.

TextAttributeControl &UnsetSize()

Removes the size setting. If the control is attached to a WindowKey this function restores the default value of this setting as specified by TextAttributeKit::GetDefault().

Returns: A reference to this object.

TextAttributeControl &UnsetSizeTolerance()

Removes the size tolerance setting. If the control is attached to a WindowKey this function restores the default value of this setting as specified by TextAttributeKit::GetDefault().

Returns: A reference to this object.

TextAttributeControl &UnsetSlant()

Removes the slant setting. If the control is attached to a WindowKey this function restores the default value of this setting as specified by TextAttributeKit::GetDefault().

Returns: A reference to this object.

TextAttributeControl &UnsetSpacing()

Removes the spacing setting. If the control is attached to a WindowKey this function restores the default value of this setting as specified by TextAttributeKit::GetDefault().

Returns: A reference to this object.

TextAttributeControl &UnsetStrikethrough()

Removes the strikethrough setting. If the control is attached to a WindowKey this function restores the default value of this setting as specified by TextAttributeKit::GetDefault().

Returns: A reference to this object.

TextAttributeControl &UnsetTransform()

Removes the transform setting. If the control is attached to a WindowKey this function restores the default value of this setting as specified by TextAttributeKit::GetDefault().

Returns: A reference to this object.

TextAttributeControl &UnsetUnderline()

Removes the underline setting. If the control is attached to a WindowKey this function restores the default value of this setting as specified by TextAttributeKit::GetDefault().

Returns: A reference to this object.

~TextAttributeControl(): Releases a reference to the database object this control is tied to.

Public Static Attributes

static const HPS::Type staticType = HPS::Type::TextAttributeControl