1/* $Id: glyphstring.hg,v 1.2 2006/05/30 17:14:21 murrayc Exp $ */
2
3/* glyphstring.h
4 *
5 * Copyright (C) 1998-1999 The gtkmm Development Team
6 *
7 * This library is free software; you can redistribute it and/or
8 * modify it under the terms of the GNU Lesser General Public
9 * License as published by the Free Software Foundation; either
10 * version 2.1 of the License, or (at your option) any later version.
11 *
12 * This library is distributed in the hope that it will be useful,
13 * but WITHOUT ANY WARRANTY; without even the implied warranty of
14 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
15 * Lesser General Public License for more details.
16 *
17 * You should have received a copy of the GNU Lesser General Public
18 * License along with this library; if not, write to the Free
19 * Software Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
20 */
21
22#include <pangomm/font.h>
23#include <pangomm/glyph.h>
24#include <pangomm/item.h>
25#include <cairomm/context.h>
26#include <pango/pango-glyph.h>
27#include <pango/pango-item.h> //For PangoAnalysis.
28
29_DEFS(pangomm,pango)
30
31namespace Pango
32{
33
34/** A Pango::GlyphString is used to store strings of glyphs with geometry and visual attribute information.
35 * It can be measured or drawn to the screen.
36 */
37class GlyphString
38{
39  _CLASS_BOXEDTYPE(GlyphString, PangoGlyphString, pango_glyph_string_new, pango_glyph_string_copy, pango_glyph_string_free)
40  _IGNORE(pango_glyph_string_free, pango_glyph_string_copy, pango_glyph_string_copy_static, pango_glyph_string_equal)
41  _IGNORE(pango_glyph_string_index_to_x, pango_glyph_string_x_to_index, pango_glyph_string_get_logical_widths)
42
43public:
44  /** Construct a string of glyphs from a string of characters.
45   * Given a segment of text and the corresponding Pango::Analysis structure
46   * returned from Pango::Context::itemize(), convert the characters into glyphs.
47   * You may also pass in only a sub-string of the item.
48   * @param text The text to process. You must pass the same string into those member functions expecting a const Glib::ustring&.
49   * @param analysis The analysis information return from Pango::Context::itemize().
50   */
51  GlyphString(const Glib::ustring& text, const Analysis& analysis);
52
53  _WRAP_METHOD(void set_size (int new_len), pango_glyph_string_set_size)
54
55  _WRAP_METHOD(void get_extents(const Glib::RefPtr<const Font>& font, Rectangle& ink_rect, Rectangle& logical_rect) const, pango_glyph_string_extents)
56  _WRAP_METHOD(void get_extents(int start, int end, const Glib::RefPtr<const Font>& font, Rectangle& ink_rect, Rectangle& logical_rect) const, pango_glyph_string_extents_range)
57
58  _WRAP_METHOD(int get_width() const, pango_glyph_string_get_width)
59
60  /** Computes the extents of the glyph string as drawn.
61   * @param font A Pango::Font.
62   * @return The extents of the glyph string as drawn.
63   */
64  Rectangle get_ink_extents(const Glib::RefPtr<const Font>& font) const;
65
66  /** Computes the extents of a sub-portion of the glyph string as drawn.
67   * @param start The start index.
68   * @param end The end index.
69   * @param font A Panog::Font
70   * @return The extents of the sub-portion of the glyph string as drawn.
71   */
72  Rectangle get_ink_extents(int start, int end, const Glib::RefPtr<const Font>& font) const;
73
74  /** Computes the logical extents of a sub-portion of the glyph string.
75   * @param font A Pango::Font.
76   * @return The logical extents of the glyph string.
77   */
78  Rectangle get_logical_extents(const Glib::RefPtr<const Font>& font) const;
79
80  /** Computes the logical extents of a sub-portion of the glyph string.
81   * @param start The start index.
82   * @param end The end index.
83   * @param font A Pango::Font.
84   * @return The logical extents of the sub-portion of the glyph string.
85   */
86  Rectangle get_logical_extents(int start, int end, const Glib::RefPtr<const Font>& font) const;
87
88  /** Determine the screen width corresponding to each character.
89   * When multiple characters compose a single cluster, the width of the entire cluster
90   * is divided equally among the characters.
91   * @param text The text corresponding to the glyphs.
92   * @param embedding_level The embedding level of the string.
93   * @return An array of integers representing the resulting character widths.
94   */
95  Glib::ArrayHandle<int> get_logical_widths(const Glib::ustring& text, int embedding_level) const;
96
97  /** Converts from character position to x position.
98   * (X position is measured from the left edge of the run). Character positions are computed by dividing up each cluster into equal portions.
99   * @param text The text corresponding to the glyphs.
100   * @param analysis The analysis information return from Pango::Context::itemize().
101   * @param index The byte index within text.
102   * @param trailing Whether we should compute the result for the beginning or end of the character.
103   * @return The x position.
104   */
105  int index_to_x(const Glib::ustring& text, const Analysis& analysis, int index, bool trailing) const;
106
107  /** Convert from x offset to character position.
108   * Character positions are computed by dividing up each cluster into equal portions.
109   * In scripts where positioning within a cluster is not allowed (such as Thai),
110   * the returned value may not be a valid cursor position; the caller must combine the
111   * result with the logical attributes for the text to compute the valid cursor position.
112   * @param text The text corresponding to the glyphs.
113   * @param analysis The analysis information return from Pango::Context::itemize().
114   * @param x_pos The x offset (in thousands of a device unit).
115   * @param index The location to store calculated byte index within.
116   * @param trailing The location to store a boolean indicating whether the user clicked on the leading or trailing edge of the character.
117   */
118  void x_to_index(const Glib::ustring& text, const Analysis& analysis, int x_pos, int& index, bool& trailing) const;
119
120  /** Gharacter positions are computed by dividing up each cluster into equal portions.
121   * @return An array of Pango::GlyphInfo objects.
122   */
123  Glib::ArrayHandle<GlyphInfo> get_glyphs() const;
124
125  //TODO:
126  //void        pango_cairo_glyph_string_path   (cairo_t *cr,
127  //                                         PangoFont *font,
128  //                                         PangoGlyphString *glyphs);
129};
130
131} //namespace Pango
132