gi-pango-1.0.30: Pango bindings

Copyright | Will Thompson and Iñaki García Etxebarria
License | LGPL-2.1
Maintainer | Iñaki García Etxebarria
Safe Haskell | None
Language | Haskell2010

GI.Pango.Structs.AttrList

Contents

- Exported types
- Methods
  - change
  - copy
  - equal
  - filter
  - fromString
  - getAttributes
  - getIterator
  - insert
  - insertBefore
  - new
  - ref
  - splice
  - toString
  - unref
  - update

Description

A `PangoAttrList` represents a list of attributes that apply to a section of text.

The attributes in a `PangoAttrList` are, in general, allowed to overlap in an arbitrary fashion. However, if the attributes are manipulated only through `attrListChange`, the overlap between properties will meet stricter criteria.

Since the `PangoAttrList` structure is stored as a linear list, it is not suitable for storing attributes for large amounts of text. In general, you should not use a single `PangoAttrList` for more than one paragraph of text.

Synopsis

- newtype AttrList = AttrList (ManagedPtr AttrList)
- attrListChange :: (HasCallStack, MonadIO m) => AttrList -> Attribute -> m ()
- attrListCopy :: (HasCallStack, MonadIO m) => Maybe AttrList -> m (Maybe AttrList)
- attrListEqual :: (HasCallStack, MonadIO m) => AttrList -> AttrList -> m Bool
- attrListFilter :: (HasCallStack, MonadIO m) => AttrList -> AttrFilterFunc -> m (Maybe AttrList)
- attrListFromString :: (HasCallStack, MonadIO m) => Text -> m (Maybe AttrList)
- attrListGetAttributes :: (HasCallStack, MonadIO m) => AttrList -> m [Attribute]
- attrListGetIterator :: (HasCallStack, MonadIO m) => AttrList -> m AttrIterator
- attrListInsert :: (HasCallStack, MonadIO m) => AttrList -> Attribute -> m ()
- attrListInsertBefore :: (HasCallStack, MonadIO m) => AttrList -> Attribute -> m ()
- attrListNew :: (HasCallStack, MonadIO m) => m AttrList
- attrListRef :: (HasCallStack, MonadIO m) => Maybe AttrList -> m AttrList
- attrListSplice :: (HasCallStack, MonadIO m) => AttrList -> AttrList -> Int32 -> Int32 -> m ()
- attrListToString :: (HasCallStack, MonadIO m) => AttrList -> m Text
- attrListUnref :: (HasCallStack, MonadIO m) => Maybe AttrList -> m ()
- attrListUpdate :: (HasCallStack, MonadIO m) => AttrList -> Int32 -> Int32 -> Int32 -> m ()

# Exported types

newtype AttrList Source #

Memory-managed wrapper type.

Constructors

AttrList (ManagedPtr AttrList) |

#### Instances

Instances details

Eq AttrList Source # |
Instance details Defined in GI.Pango.Structs.AttrList Methods (==) :: AttrList -> AttrList -> Bool Source # (/=) :: AttrList -> AttrList -> Bool Source #
GBoxed AttrList Source # |
Instance details Defined in GI.Pango.Structs.AttrList
ManagedPtrNewtype AttrList Source # |
Instance details Defined in GI.Pango.Structs.AttrList Methods toManagedPtr :: AttrList -> ManagedPtr AttrList Source #
TypedObject AttrList Source # |
Instance details Defined in GI.Pango.Structs.AttrList Methods glibType :: IO GType Source #
HasParentTypes AttrList Source # |
Instance details Defined in GI.Pango.Structs.AttrList
IsGValue (Maybe AttrList) Source # | Convert `AttrList` to and from `GValue`. See `toGValue` and `fromGValue`.
Instance details Defined in GI.Pango.Structs.AttrList Methods gvalueGType_ :: IO GType Source # gvalueSet_ :: Ptr GValue -> Maybe AttrList -> IO () Source # gvalueGet_ :: Ptr GValue -> IO (Maybe AttrList) Source #
type ParentTypes AttrList Source # |
Instance details Defined in GI.Pango.Structs.AttrList type ParentTypes AttrList = '[] :: [Type]

# Methods

### Click to display all available methods, including inherited ones

Expand

#### Methods

change, copy, equal, filter, insert, insertBefore, ref, splice, toString, unref, update.

#### Getters

getAttributes, getIterator.

#### Setters

None.

## change

attrListChange Source #

Arguments

:: (HasCallStack, MonadIO m) |
=> AttrList | `list`: a `PangoAttrList`
-> Attribute | `attr`: the attribute to insert
-> m () |

Insert the given attribute into the `PangoAttrList`.

It will replace any attributes of the same type on that segment and be merged with any adjoining attributes that are identical.

This function is slower than `attrListInsert` for creating an attribute list in order (potentially much slower for large lists). However, `attrListInsert` is not suitable for continually changing a set of attributes since it never removes or combines existing attributes.

## copy

attrListCopy Source #

Arguments

:: (HasCallStack, MonadIO m) |
=> Maybe AttrList | `list`: a `PangoAttrList`
-> m (Maybe AttrList) | Returns: the newly allocated `PangoAttrList`, with a reference count of one, which should be freed with `attrListUnref`. Returns `Nothing` if `list` was `Nothing`.

Copy `list` and return an identical new list.

## equal

attrListEqual Source #

Arguments

:: (HasCallStack, MonadIO m) |
=> AttrList | `list`: a `PangoAttrList`
-> AttrList | `otherList`: the other `PangoAttrList`
-> m Bool | Returns: `True` if the lists are equal, `False` if they aren't

Checks whether `list` and `otherList` contain the same attributes and whether those attributes apply to the same ranges.

Beware that this will return wrong values if any list contains duplicates.

Since: 1.46

## filter

attrListFilter Source #

Arguments

:: (HasCallStack, MonadIO m) |
=> AttrList | `list`: a `PangoAttrList`
-> AttrFilterFunc | `func`: callback function; returns `True` if an attribute should be filtered out
-> m (Maybe AttrList) | Returns: the new `PangoAttrList` or `Nothing` if no attributes of the given types were found

Given a `PangoAttrList` and callback function, removes any elements of `list` for which `func` returns `True` and inserts them into a new list.

Since: 1.2

## fromString

attrListFromString Source #

Arguments

:: (HasCallStack, MonadIO m) |
=> Text | `text`: a string
-> m (Maybe AttrList) | Returns: a new `PangoAttrList`

Deserializes a `PangoAttrList` from a string.

This is the counterpart to `attrListToString`. See that functions for details about the format.

Since: 1.50

## getAttributes

attrListGetAttributes Source #

Arguments

:: (HasCallStack, MonadIO m) |
=> AttrList | `list`: a `PangoAttrList`
-> m [Attribute] | Returns: a list of all attributes in `list`. To free this value, call `attributeDestroy` on each value and `g_slist_free()` on the list.

Gets a list of all attributes in `list`.

Since: 1.44

## getIterator

attrListGetIterator Source #

Arguments

:: (HasCallStack, MonadIO m) |
=> AttrList | `list`: a `PangoAttrList`
-> m AttrIterator | Returns: the newly allocated `PangoAttrIterator`, which should be freed with `attrIteratorDestroy`

Create a iterator initialized to the beginning of the list.

`list` must not be modified until this iterator is freed.

## insert

attrListInsert Source #

Arguments

:: (HasCallStack, MonadIO m) |
=> AttrList | `list`: a `PangoAttrList`
-> Attribute | `attr`: the attribute to insert
-> m () |

Insert the given attribute into the `PangoAttrList`.

It will be inserted after all other attributes with a matching `startIndex`.

## insertBefore

attrListInsertBefore Source #

Arguments

:: (HasCallStack, MonadIO m) |
=> AttrList | `list`: a `PangoAttrList`
-> Attribute | `attr`: the attribute to insert
-> m () |

Insert the given attribute into the `PangoAttrList`.

It will be inserted before all other attributes with a matching `startIndex`.

## new

attrListNew Source #

Arguments

:: (HasCallStack, MonadIO m) |
=> m AttrList | Returns: the newly allocated `PangoAttrList`, which should be freed with `attrListUnref`

Create a new empty attribute list with a reference count of one.

## ref

attrListRef Source #

Arguments

:: (HasCallStack, MonadIO m) |
=> Maybe AttrList | `list`: a `PangoAttrList`
-> m AttrList | Returns: The attribute list passed in

Increase the reference count of the given attribute list by one.

Since: 1.10

## splice

attrListSplice Source #

Arguments

:: (HasCallStack, MonadIO m) |
=> AttrList | `list`: a `PangoAttrList`
-> AttrList | `other`: another `PangoAttrList`
-> Int32 | `pos`: the position in `list` at which to insert `other`
-> Int32 | `len`: the length of the spliced segment. (Note that this must be specified since the attributes in `other` may only be present at some subsection of this range)
-> m () |

This function opens up a hole in `list`, fills it in with attributes from the left, and then merges `other` on top of the hole.

This operation is equivalent to stretching every attribute that applies at position `pos` in `list` by an amount `len`, and then calling `attrListChange` with a copy of each attribute in `other` in sequence (offset in position by `pos`, and limited in length to `len`).

This operation proves useful for, for instance, inserting a pre-edit string in the middle of an edit buffer.

For backwards compatibility, the function behaves differently when `len` is 0. In this case, the attributes from `other` are not imited to `len`, and are just overlayed on top of `list`.

This mode is useful for merging two lists of attributes together.

## toString

attrListToString Source #

Arguments

:: (HasCallStack, MonadIO m) |
=> AttrList | `list`: a `PangoAttrList`
-> m Text | Returns: a newly allocated string

Serializes a `PangoAttrList` to a string.

In the resulting string, serialized attributes are separated by newlines or commas. Individual attributes are serialized to a string of the form

START END
  TYPE VALUE

Where START and END are the indices (with -1 being accepted in place of MAXUINT), TYPE is the nickname of the attribute value type, e.g. _weight_ or _stretch_, and the value is serialized according to its type:

Optionally, START and END can be omitted to indicate unlimited extent.

- enum values as nick or numeric value
- boolean values as _true_ or _false_
- integers and floats as numbers
- strings as string, optionally quoted
- font features as quoted string
- PangoLanguage as string
- PangoFontDescription as serialized by `fontDescriptionToString`, quoted
- PangoColor as serialized by `colorToString`

Examples:

0 10 foreground red, 5 15 weight bold, 0 200 font-desc "Sans 10"

0 -1 weight 700 0 100 family Times

weight bold

To parse the returned value, use `attrListFromString`.

Note that shape attributes can not be serialized.

Since: 1.50

## unref

attrListUnref Source #

Arguments

:: (HasCallStack, MonadIO m) |
=> Maybe AttrList | `list`: a `PangoAttrList`
-> m () |

Decrease the reference count of the given attribute list by one.

If the result is zero, free the attribute list and the attributes it contains.

## update

attrListUpdate Source #

Arguments

:: (HasCallStack, MonadIO m) |
=> AttrList | `list`: a `PangoAttrList`
-> Int32 | `pos`: the position of the change
-> Int32 | `remove`: the number of removed bytes
-> Int32 | `add`: the number of added bytes
-> m () |

Update indices of attributes in `list` for a change in the text they refer to.

The change that this function applies is removing `remove` bytes at position `pos` and inserting `add` bytes instead.

Attributes that fall entirely in the (`pos`, `pos` + `remove`) range are removed.

Attributes that start or end inside the (`pos`, `pos` + `remove`) range are shortened to reflect the removal.

Attributes start and end positions are updated if they are behind `pos` + `remove`.

Since: 1.44