libs/gtkmm2/pango/src/glyphstring.hg

   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 Library General Public
   9  * License as published by the Free Software Foundation; either
  10  * version 2 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  * Library General Public License for more details.
  16  *
  17  * You should have received a copy of the GNU Library 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
  31 namespace 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  */
  37 class 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
  43 public:
  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