GI.Pango.Structs.FontDescription

The FontDescription structure represents the description of an ideal font. These structures are used both to list what fonts are available on the system and also for specifying the characteristics of a font to load.

Exported types

newtype FontDescription

Memory-managed wrapper type.

Constructors

FontDescription (ManagedPtr FontDescription)

Instances

BoxedObject FontDescription

Defined in GI.Pango.Structs.FontDescription

Methods

boxedType :: FontDescription -> IO GType

noFontDescription :: Maybe FontDescription

A convenience alias for Nothing :: Maybe FontDescription.

Methods

betterMatch

fontDescriptionBetterMatch

Arguments

:: (HasCallStack, MonadIO m)

=> FontDescription

desc: a FontDescription

-> Maybe FontDescription

oldMatch: a FontDescription, or Nothing

-> FontDescription

newMatch: a FontDescription

-> m Bool

Returns: True if newMatch is a better match

Determines if the style attributes of newMatch are a closer match for desc than those of oldMatch are, or if oldMatch is Nothing, determines if newMatch is a match at all. Approximate matching is done for weight and style; other style attributes must match exactly. Style attributes are all attributes other than family and size-related attributes. Approximate matching for style considers PANGO_STYLE_OBLIQUE and PANGO_STYLE_ITALIC as matches, but not as good a match as when the styles are equal.

Note that oldMatch must match desc.

copy

fontDescriptionCopy

Arguments

:: (HasCallStack, MonadIO m)

=> FontDescription

desc: a FontDescription, may be Nothing

-> m (Maybe FontDescription)

Returns: the newly allocated FontDescription, which should be freed with fontDescriptionFree, or Nothing if desc was Nothing.

Make a copy of a FontDescription.

copyStatic

fontDescriptionCopyStatic

Arguments

:: (HasCallStack, MonadIO m)

=> FontDescription

desc: a FontDescription, may be Nothing

-> m (Maybe FontDescription)

Returns: the newly allocated FontDescription, which should be freed with fontDescriptionFree, or Nothing if desc was Nothing.

Like fontDescriptionCopy, but only a shallow copy is made of the family name and other allocated fields. The result can only be used until desc is modified or freed. This is meant to be used when the copy is only needed temporarily.

equal

fontDescriptionEqual

Arguments

:: (HasCallStack, MonadIO m)

=> FontDescription

desc1: a FontDescription

-> FontDescription

desc2: another FontDescription

-> m Bool

Returns: True if the two font descriptions are identical, False otherwise.

Compares two font descriptions for equality. Two font descriptions are considered equal if the fonts they describe are provably identical. This means that their masks do not have to match, as long as other fields are all the same. (Two font descriptions may result in identical fonts being loaded, but still compare False.)

free

fontDescriptionFree

Arguments

:: (HasCallStack, MonadIO m)

=> FontDescription

desc: a FontDescription, may be Nothing

-> m ()

Frees a font description.

fromString

fontDescriptionFromString

Arguments

:: (HasCallStack, MonadIO m)

=> Text

str: string representation of a font description.

-> m FontDescription

Returns: a new FontDescription.

Creates a new font description from a string representation in the form "[FAMILY-LIST] [STYLE-OPTIONS] [SIZE]", where FAMILY-LIST is a comma separated list of families optionally terminated by a comma, STYLE_OPTIONS is a whitespace separated list of words where each word describes one of style, variant, weight, stretch, or gravity, and SIZE is a decimal number (size in points) or optionally followed by the unit modifier "px" for absolute size. Any one of the options may be absent. If FAMILY-LIST is absent, then the family_name field of the resulting font description will be initialized to Nothing. If STYLE-OPTIONS is missing, then all style options will be set to the default values. If SIZE is missing, the size in the resulting font description will be set to 0.

getFamily

fontDescriptionGetFamily

Arguments

:: (HasCallStack, MonadIO m)

=> FontDescription

desc: a FontDescription.

-> m (Maybe Text)

Returns: the family name field for the font description, or Nothing if not previously set. This has the same life-time as the font description itself and should not be freed.

Gets the family name field of a font description. See fontDescriptionSetFamily.

getGravity

fontDescriptionGetGravity

Arguments

:: (HasCallStack, MonadIO m)

=> FontDescription

desc: a FontDescription

-> m Gravity

Returns: the gravity field for the font description. Use fontDescriptionGetSetFields to find out if the field was explicitly set or not.

Gets the gravity field of a font description. See fontDescriptionSetGravity.

Since: 1.16

getSetFields

fontDescriptionGetSetFields

Arguments

:: (HasCallStack, MonadIO m)

=> FontDescription

desc: a FontDescription

-> m [FontMask]

Returns: a bitmask with bits set corresponding to the fields in desc that have been set.

Determines which fields in a font description have been set.

getSize

fontDescriptionGetSize

Arguments

:: (HasCallStack, MonadIO m)

=> FontDescription

desc: a FontDescription

-> m Int32

Returns: the size field for the font description in points or device units. You must call fontDescriptionGetSizeIsAbsolute to find out which is the case. Returns 0 if the size field has not previously been set or it has been set to 0 explicitly. Use fontDescriptionGetSetFields to find out if the field was explicitly set or not.

Gets the size field of a font description. See fontDescriptionSetSize.

getSizeIsAbsolute

fontDescriptionGetSizeIsAbsolute

Arguments

:: (HasCallStack, MonadIO m)

=> FontDescription

desc: a FontDescription

-> m Bool

Returns: whether the size for the font description is in points or device units. Use fontDescriptionGetSetFields to find out if the size field of the font description was explicitly set or not.

Determines whether the size of the font is in points (not absolute) or device units (absolute). See fontDescriptionSetSize and fontDescriptionSetAbsoluteSize.

Since: 1.8

getStretch

fontDescriptionGetStretch

Arguments

:: (HasCallStack, MonadIO m)

=> FontDescription

desc: a FontDescription.

-> m Stretch

Returns: the stretch field for the font description. Use fontDescriptionGetSetFields to find out if the field was explicitly set or not.

Gets the stretch field of a font description. See fontDescriptionSetStretch.

getStyle

fontDescriptionGetStyle

Arguments

:: (HasCallStack, MonadIO m)

=> FontDescription

desc: a FontDescription

-> m Style

Returns: the style field for the font description. Use fontDescriptionGetSetFields to find out if the field was explicitly set or not.

Gets the style field of a FontDescription. See fontDescriptionSetStyle.

getVariant

fontDescriptionGetVariant

Arguments

:: (HasCallStack, MonadIO m)

=> FontDescription

desc: a FontDescription.

-> m Variant

Returns: the variant field for the font description. Use fontDescriptionGetSetFields to find out if the field was explicitly set or not.

Gets the variant field of a FontDescription. See fontDescriptionSetVariant.

getVariations

fontDescriptionGetVariations

Arguments

:: (HasCallStack, MonadIO m)

=> FontDescription

desc: a FontDescription

-> m (Maybe Text)

Returns: the varitions field for the font description, or Nothing if not previously set. This has the same life-time as the font description itself and should not be freed.

Gets the variations field of a font description. See fontDescriptionSetVariations.

Since: 1.42

getWeight

fontDescriptionGetWeight

Arguments

:: (HasCallStack, MonadIO m)

=> FontDescription

desc: a FontDescription

-> m Weight

Returns: the weight field for the font description. Use fontDescriptionGetSetFields to find out if the field was explicitly set or not.

Gets the weight field of a font description. See fontDescriptionSetWeight.

hash

fontDescriptionHash

Arguments

:: (HasCallStack, MonadIO m)

=> FontDescription

desc: a FontDescription

-> m Word32

Returns: the hash value.

Computes a hash of a FontDescription structure suitable to be used, for example, as an argument to g_hash_table_new(). The hash value is independent of desc->mask.

merge

fontDescriptionMerge

Arguments

:: (HasCallStack, MonadIO m)

=> FontDescription

desc: a FontDescription

-> Maybe FontDescription

descToMerge: the FontDescription to merge from, or Nothing

-> Bool

replaceExisting: if True, replace fields in desc with the corresponding values from descToMerge, even if they are already exist.

-> m ()

Merges the fields that are set in descToMerge into the fields in desc. If replaceExisting is False, only fields in desc that are not already set are affected. If True, then fields that are already set will be replaced as well.

If descToMerge is Nothing, this function performs nothing.

mergeStatic

fontDescriptionMergeStatic

Arguments

:: (HasCallStack, MonadIO m)

=> FontDescription

desc: a FontDescription

-> FontDescription

descToMerge: the FontDescription to merge from

-> Bool

replaceExisting: if True, replace fields in desc with the corresponding values from descToMerge, even if they are already exist.

-> m ()

Like fontDescriptionMerge, but only a shallow copy is made of the family name and other allocated fields. desc can only be used until descToMerge is modified or freed. This is meant to be used when the merged font description is only needed temporarily.

new

fontDescriptionNew

Arguments

:: (HasCallStack, MonadIO m)

=> m FontDescription

Returns: the newly allocated FontDescription, which should be freed using fontDescriptionFree.

Creates a new font description structure with all fields unset.

setAbsoluteSize

fontDescriptionSetAbsoluteSize

Arguments

:: (HasCallStack, MonadIO m)

=> FontDescription

desc: a FontDescription

-> Double

size: the new size, in Pango units. There are SCALE Pango units in one device unit. For an output backend where a device unit is a pixel, a size value of 10 * PANGO_SCALE gives a 10 pixel font.

-> m ()

Sets the size field of a font description, in device units. This is mutually exclusive with fontDescriptionSetSize which sets the font size in points.

Since: 1.8

setFamily

fontDescriptionSetFamily

Arguments

:: (HasCallStack, MonadIO m)

=> FontDescription

desc: a FontDescription.

-> Text

family: a string representing the family name.

-> m ()

Sets the family name field of a font description. The family name represents a family of related font styles, and will resolve to a particular FontFamily. In some uses of FontDescription, it is also possible to use a comma separated list of family names for this field.

setFamilyStatic

fontDescriptionSetFamilyStatic

Arguments

:: (HasCallStack, MonadIO m)

=> FontDescription

desc: a FontDescription

-> Text

family: a string representing the family name.

-> m ()

Like fontDescriptionSetFamily, except that no copy of family is made. The caller must make sure that the string passed in stays around until desc has been freed or the name is set again. This function can be used if family is a static string such as a C string literal, or if desc is only needed temporarily.

setGravity

fontDescriptionSetGravity

Arguments

:: (HasCallStack, MonadIO m)

=> FontDescription

desc: a FontDescription

-> Gravity

gravity: the gravity for the font description.

-> m ()

Sets the gravity field of a font description. The gravity field specifies how the glyphs should be rotated. If gravity is GravityAuto, this actually unsets the gravity mask on the font description.

This function is seldom useful to the user. Gravity should normally be set on a Context.

Since: 1.16

setSize

fontDescriptionSetSize

Arguments

:: (HasCallStack, MonadIO m)

=> FontDescription

desc: a FontDescription

-> Int32

size: the size of the font in points, scaled by PANGO_SCALE. (That is, a size value of 10 * PANGO_SCALE is a 10 point font. The conversion factor between points and device units depends on system configuration and the output device. For screen display, a logical DPI of 96 is common, in which case a 10 point font corresponds to a 10 * (96 / 72) = 13.3 pixel font. Use fontDescriptionSetAbsoluteSize if you need a particular size in device units.

-> m ()

Sets the size field of a font description in fractional points. This is mutually exclusive with fontDescriptionSetAbsoluteSize.

setStretch

fontDescriptionSetStretch

Arguments

:: (HasCallStack, MonadIO m)

=> FontDescription

desc: a FontDescription

-> Stretch

stretch: the stretch for the font description

-> m ()

Sets the stretch field of a font description. The stretch field specifies how narrow or wide the font should be.

setStyle

fontDescriptionSetStyle

Arguments

:: (HasCallStack, MonadIO m)

=> FontDescription

desc: a FontDescription

-> Style

style: the style for the font description

-> m ()

Sets the style field of a FontDescription. The Style enumeration describes whether the font is slanted and the manner in which it is slanted; it can be either PANGO_STYLE_NORMAL, PANGO_STYLE_ITALIC, or PANGO_STYLE_OBLIQUE. Most fonts will either have a italic style or an oblique style, but not both, and font matching in Pango will match italic specifications with oblique fonts and vice-versa if an exact match is not found.

setVariant

fontDescriptionSetVariant

Arguments

:: (HasCallStack, MonadIO m)

=> FontDescription

desc: a FontDescription

-> Variant

variant: the variant type for the font description.

-> m ()

Sets the variant field of a font description. The Variant can either be VariantNormal or VariantSmallCaps.

setVariations

fontDescriptionSetVariations

Arguments

:: (HasCallStack, MonadIO m)

=> FontDescription

desc: a FontDescription.

-> Text

-> m ()

Sets the variations field of a font description. OpenType font variations allow to select a font instance by specifying values for a number of axes, such as width or weight.

The format of the variations string is AXIS1=VALUE,AXIS2=VALUE..., with each AXIS a 4 character tag that identifies a font axis, and each VALUE a floating point number. Unknown axes are ignored, and values are clamped to their allowed range.

Pango does not currently have a way to find supported axes of a font. Both harfbuzz or freetype have API for this.

Since: 1.42

setVariationsStatic

fontDescriptionSetVariationsStatic

Arguments

:: (HasCallStack, MonadIO m)

=> FontDescription

desc: a FontDescription

-> Text

-> m ()

Like fontDescriptionSetVariations, except that no copy of variations is made. The caller must make sure that the string passed in stays around until desc has been freed or the name is set again. This function can be used if variations is a static string such as a C string literal, or if desc is only needed temporarily.

Since: 1.42

setWeight

fontDescriptionSetWeight

Arguments

:: (HasCallStack, MonadIO m)

=> FontDescription

desc: a FontDescription

-> Weight

weight: the weight for the font description.

-> m ()

Sets the weight field of a font description. The weight field specifies how bold or light the font should be. In addition to the values of the Weight enumeration, other intermediate numeric values are possible.

toFilename

fontDescriptionToFilename

Arguments

:: (HasCallStack, MonadIO m)

=> FontDescription

desc: a FontDescription

-> m Text

Returns: a new string that must be freed with free.

Creates a filename representation of a font description. The filename is identical to the result from calling fontDescriptionToString, but with underscores instead of characters that are untypical in filenames, and in lower case only.

toString

fontDescriptionToString

Arguments

:: (HasCallStack, MonadIO m)

=> FontDescription

desc: a FontDescription

-> m Text

Returns: a new string that must be freed with free.

Creates a string representation of a font description. See fontDescriptionFromString for a description of the format of the string representation. The family list in the string description will only have a terminating comma if the last word of the list is a valid style option.

unsetFields

fontDescriptionUnsetFields

Arguments

:: (HasCallStack, MonadIO m)

=> FontDescription

desc: a FontDescription

-> [FontMask]

toUnset: bitmask of fields in the desc to unset.

-> m ()

Unsets some of the fields in a FontDescription. The unset fields will get back to their default values.