Xfce Foundation Classes
Main Page | Index | Namespace List | Alphabetical List | Class List | File List

# Xfc::Pango::LayoutLine Class Reference

A PangoLayoutLine C++ wrapper class. More...

`#include <xfc/pango/layout.hh>`

Inheritance diagram for Xfc::Pango::LayoutLine:

List of all members.

## Public Member Functions

Constructors

- LayoutLine (PangoLayoutLine *layout_line)
    Construct a new LayoutLine from an existing PangoLayoutLine.
- LayoutLine (const LayoutLine &src)
    Copy constructor.
- ~LayoutLine ()
    Destructor.
- LayoutLine & operator= (const LayoutLine &src)
    Assignment operator.

Accessors

- PangoLayoutLine * pango_layout_line () const
    Get a pointer to the PangoLayoutLine structure.
- operator PangoLayoutLine * () const
    Conversion operator; safely converts a LayoutLine to a PangoLayoutLine pointer.
- int start_index () const
    Returns the start of line as byte index into the text of the parent layout.
- int length () const
    Returns the length of line in bytes.
- bool is_paragraph_start () const
    Determines whether this is the first line of a paragraph.
- std::vector< std::pair< int,
  int > > get_x_ranges (int start_index, int end_index) const
    Get a list of visual ranges corresponding to a given logical range.
- void get_extents (Rectangle *ink_rect, Rectangle *logical_rect) const
    Compute the logical and ink extents of a layout line.
- void get_pixel_extents (Rectangle *ink_rect, Rectangle *logical_rect) const
    Compute the logical and ink extents of a layout line.
- Pointer< Gdk::Region > get_clip_region (int x_origin, int y_origin, const std::vector< std::pair< int, int > > &index_ranges) const
    Obtains a clip region which contains the areas where the given ranges of text would be drawn.

Methods

- bool x_to_index (int x_pos, int *index, int *trailing)
    Convert from x offset to the byte index of the corresponding character within the text of the layout.
- int index_to_x (int index, bool trailing)
    Converts an index within a line to a X position.

## Detailed Description

A PangoLayoutLine C++ wrapper class.

LayoutLine represents one of the lines resulting from laying out a paragraph via Layout. LayoutLine objects are obtained by calling Pango::Layout::get_line() and are only valid until the text, attributes, or settings of the parent Layout are modified.

Routines for rendering Layout objects are provided in code specific to each rendering system.

## Constructor & Destructor Documentation

Xfc::Pango::LayoutLine::LayoutLine | ( | PangoLayoutLine * | layout_line | ) | `[explicit]`

Construct a new LayoutLine from an existing PangoLayoutLine.

Parameters:

  | layout_line | A pointer to a PangoLayoutLine.

Xfc::Pango::LayoutLine::LayoutLine | ( | const LayoutLine & | src | ) |

Copy constructor.

Parameters:

  | src | The source LayoutLine.

## Member Function Documentation

Pointer<Gdk::Region> Xfc::Pango::LayoutLine::get_clip_region | ( | int | x_origin,
|  | int | y_origin,
|  | const std::vector< std::pair< int, int > > & | index_ranges
| ) | const

Obtains a clip region which contains the areas where the given ranges of text would be drawn.

Parameters:

  | x_origin | The X pixel where you intend to draw the layout line with this clip.
  | y_origin | The baseline pixel where you intend to draw the layout line with this clip.
  | index_ranges | A reference to a vector of int/int pairs that holds the index ranges. The first value of each pair is the start index and the second value is the end index.

Returns:
  A smart pointer to a new clip region containing the given ranges.

x_origin and y_origin are the same position you would pass to Gdk::Drawable::draw_layout_line(). index_ranges is a vector that should contain ranges of bytes in the layout's text as an int/int pair. The clip region will include space to the left or right of the line (to the layout bounding box) if you have indexes above or below the indexes contained inside the line. This is to draw the selection all the way to the side of the layout. However, the clip region is in line coordinates, not layout coordinates.

See Pango::Layout::get_clip_region() for an example of how to create a vector of pair.

void Xfc::Pango::LayoutLine::get_extents | ( | Rectangle * | ink_rect,
|  | Rectangle * | logical_rect
| ) | const

Compute the logical and ink extents of a layout line.

Parameters:

  | ink_rect | The rectangle used to store the extents of the glyph string as drawn, or null to indicate that the result is not needed.
  | logical_rect | The rectangle used to store the logical extents of the glyph string, or null to indicate that the result is not needed.

See the documentation for Pango::Font::get_glyph_extents() for details about the interpretation of the rectangles.

void Xfc::Pango::LayoutLine::get_pixel_extents | ( | Rectangle * | ink_rect,
|  | Rectangle * | logical_rect
| ) | const

Compute the logical and ink extents of a layout line.

Parameters:

  | ink_rect | The rectangle used to store the extents of the glyph string as drawn, or null to indicate that the result is not needed.
  | logical_rect | The rectangle used to store the logical extents of the glyph string, or null to indicate that the result is not needed.

See the documentation for Pango::Font::get_glyph_extents() for details about the interpretation of the rectangles. The returned rectangles are in device units, as opposed to get_extents(), which returns the extents in GlyphUnits.

std::vector<std::pair<int, int> > Xfc::Pango::LayoutLine::get_x_ranges | ( | int | start_index,
|  | int | end_index
| ) | const

Get a list of visual ranges corresponding to a given logical range.

Parameters:

  | start_index | The starting byte index of the logical range.
  | end_index | The end byte index of the logical range.

Returns:
  A vector of int/int pairs (see example below).

If start_index is less than the start index for the line, then the first range will extend all the way to the leading edge of the layout. Otherwise it will start at the leading edge of the first character. If end_index is greater than the end index for the line, then the last range will extend all the way to the trailing edge of the layout. Otherwise, it will end at the trailing edge of the last character.

This list is not necessarily minimal - there may be consecutive ranges which are adjacent. The ranges will be sorted from left to right. The ranges are with respect to the left edge of the entire layout, not with respect to the line.

The return value is not as strange as it looks. A std::pair is a container that stores 2 values, and vector you already know, so the return value is a vector of int/int pairs. In a std::pair the first value is called first and the second value is called second. In the returned vector each pair is a range. In each pair the first value is the start of the range and the second value is the width of the range. The coordinates are relative to the layout and are in GlyphUnits. To access the values returned in the pairs you would do something like this:

                 std::vector<std::pair<int, int> > ranges = get_x_ranges(start_index, end_index);

                 for (int i = 0; i < ranges.size(); i++)
                 {
                    int start_of_range = ranges[i].first;
                    int width_of_range = ranges[i].second;
                    ...
                 }

Note the space between the two >s; >> is the right shift operator.

int Xfc::Pango::LayoutLine::index_to_x | ( | int | index,
|  | bool | trailing
| ) |

Converts an index within a line to a X position.

Parameters:

  | index | The byte offset of a grapheme within the layout.
  | trailing | Whether to compute the result for the leading or trailing edge of the grapheme.

Returns:
  The x_offset (in GlyphUnits).

bool Xfc::Pango::LayoutLine::is_paragraph_start | ( |  | ) | const

Determines whether this is the first line of a paragraph.

Returns:
  true if this is the first line of a paragraph.

LayoutLine& Xfc::Pango::LayoutLine::operator= | ( | const LayoutLine & | src | ) |

Assignment operator.

Parameters:

  | src | The source LayoutLine.

bool Xfc::Pango::LayoutLine::x_to_index | ( | int | x_pos,
|  | int * | index,
|  | int * | trailing
| ) |

Convert from x offset to the byte index of the corresponding character within the text of the layout.

Parameters:

  | x_pos | The x offset (in GlyphUnits) from the left edge of the line.
  | index | The location to store the calculated byte offset for the grapheme in which the user clicked.
  | trailing | The location to store a integer indicating where in the grapheme the user clicked.

Returns:
  false if x_pos was outside the line, true if inside.

If x_pos is outside the line, the start or end of the line will be stored at index. trailing will either be zero, or the number of characters in the grapheme. 0 represents the trailing edge of the cluster.

The documentation for this class was generated from the following file:

- pango/layout.hh

Xfce Foundation Classes

Copyright © 2004-2005 The XFC Development Team | XFC 4.3