1/* $Id: layout.hg,v 1.9 2006/06/08 20:39:39 murrayc Exp $ */ 2 3/* layout.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 23#include <glibmm/object.h> 24#include <glibmm/slisthandle.h> 25#include <pangomm/font.h> 26#include <pangomm/fontdescription.h> 27#include <pangomm/context.h> 28#include <pangomm/attrlist.h> 29#include <pangomm/tabarray.h> 30#include <pangomm/layoutline.h> 31#include <pangomm/layoutiter.h> 32#include <pango/pango-layout.h> 33 34_DEFS(pangomm,pango) 35_PINCLUDE(glibmm/private/object_p.h) 36 37namespace Pango 38{ 39 40_CC_INCLUDE(pango/pango-enum-types.h) 41_WRAP_ENUM(Alignment, PangoAlignment) 42_WRAP_ENUM(WrapMode, PangoWrapMode) 43_WRAP_ENUM(EllipsizeMode, PangoEllipsizeMode) 44 45/** A Pango::Layout represents an entire paragraph of text. 46 * It is initialized with a Pango::Context, UTF-8 string and set of attributes for that string. 47 * Once that is done, the set of formatted lines can be extracted from the object, 48 * the layout can be rendered, and conversion between logical character positions 49 * within the layout's text, and the physical position of the resulting glyphs can be made. 50 */ 51class Layout : public Glib::Object 52{ 53 _CLASS_GOBJECT(Layout, PangoLayout, PANGO_LAYOUT, Glib::Object, GObject) 54 _IGNORE(pango_layout_set_text, pango_layout_set_markup, pango_layout_set_markup_with_accel, pango_layout_get_log_attrs, pango_layout_get_iter) 55 56protected: 57 explicit Layout(const Glib::RefPtr<Context>& context); 58 59public: 60 _WRAP_CREATE(const Glib::RefPtr<Context>& context) 61 62 /** Creates a layout object set up to match the current transformation 63 * and target surface of the Cairo context. This layout can then be 64 * used for text measurement with functions like 65 * get_size() or drawing with methods like show_in_cairo_contet(). 66 * If you change the transformation or target surface for @a context, 67 * you need to call update_from_cairo_context() 68 * 69 * This is the most convenient way to use Cairo with Pango. 70 * However it is slightly inefficient since it creates a separate 71 * Pango Context object for each layout. This might matter in an 72 * application that is laying out large amounts of text. 73 * 74 * @param context A Cairo context. 75 * @result The newly created Pango Layout. 76 */ 77 static Glib::RefPtr<Layout> create(const Cairo::RefPtr<Cairo::Context>& context); 78 79 /** Updates the private Pango Context of a Pango Layout created with 80 * create(const Cairo::RefPtr<Cairo::Context>&) to match the current transformation 81 * and target surface of a Cairo Context. 82 * 83 * @param context A Cairo context. 84 */ 85 void update_from_cairo_context(const Cairo::RefPtr<Cairo::Context>& context); 86 87 88 _WRAP_METHOD(Glib::RefPtr<Layout> copy(), pango_layout_copy) 89 _WRAP_METHOD(Glib::RefPtr<Context> get_context() const, pango_layout_get_context, refreturn) 90 _WRAP_METHOD(void set_attributes(AttrList& attrs), pango_layout_set_attributes) 91 _WRAP_METHOD(AttrList get_attributes() const, pango_layout_get_attributes) 92 93 /** Set the text of the layout. 94 * @param text The text for the layout. 95 */ 96 void set_text(const Glib::ustring& text); 97 98 _WRAP_METHOD(Glib::ustring get_text() const, pango_layout_get_text) 99 100 _WRAP_METHOD(int get_character_count() const, pango_layout_get_character_count) 101 102 /** Sets the layout text and attribute list from marked-up text (see markup format). 103 * Replaces the current text and attribute list. 104 * @param markup Some marked-up text. 105 */ 106 void set_markup(const Glib::ustring& markup); 107 108 /** Sets the layout text and attribute list from marked-up text (see markup format). 109 * Replaces the current text and attribute list. 110 * 111 * If @a accel_marker is nonzero, the given character will mark the character following 112 * it as an accelerator. For example, the accel marker might be an ampersand or 113 * underscore. All characters marked as an accelerator will receive a 114 * Pango::UNDERLINE_LOW attribute, and the first character so marked will be returned 115 * in @a accel_char. Two @a accel_marker characters following each other produce a 116 * single literal @a accel_marker character. 117 * @param markup Some marked-up text. 118 * @param accel_marker Marker for accelerators in the text. 119 * @param accel_char Return location for any located accelerators. 120 */ 121 void set_markup(const Glib::ustring& markup, gunichar accel_marker, gunichar& accel_char); 122 123 _WRAP_METHOD(void set_font_description(const FontDescription& desc), pango_layout_set_font_description) 124 void unset_font_description(); 125 126 _WRAP_METHOD(FontDescription get_font_description() const, pango_layout_get_font_description) 127 128 _WRAP_METHOD(void set_width(int width), pango_layout_set_width) 129 _WRAP_METHOD(int get_width() const, pango_layout_get_width) 130 _WRAP_METHOD(void set_height(int height), pango_layout_set_height) 131 _WRAP_METHOD(int get_height() const, pango_layout_get_height) 132 _WRAP_METHOD(void set_wrap(WrapMode wrap), pango_layout_set_wrap) 133 _WRAP_METHOD(WrapMode get_wrap() const, pango_layout_get_wrap) 134 _WRAP_METHOD(bool is_wrapped() const, pango_layout_is_wrapped) 135 _WRAP_METHOD(void set_indent(int indent), pango_layout_set_indent) 136 _WRAP_METHOD(int get_indent() const, pango_layout_get_indent) 137 _WRAP_METHOD(void set_spacing(int spacing), pango_layout_set_spacing) 138 _WRAP_METHOD(int get_spacing() const, pango_layout_get_spacing) 139 _WRAP_METHOD(void set_justify(bool justify = true), pango_layout_set_justify) 140 _WRAP_METHOD(bool get_justify() const, pango_layout_get_justify) 141 142 _WRAP_METHOD(bool get_auto_dir() const, pango_layout_get_auto_dir) 143 _WRAP_METHOD(void set_auto_dir(bool auto_dir = true), pango_layout_set_auto_dir) 144 145 _WRAP_METHOD(void set_alignment(Alignment alignment), pango_layout_set_alignment) 146 _WRAP_METHOD(Alignment get_alignment() const, pango_layout_get_alignment) 147 148 _WRAP_METHOD(void set_tabs(TabArray& tabs), pango_layout_set_tabs) 149 _WRAP_METHOD(TabArray get_tabs() const, pango_layout_get_tabs) 150 151 _WRAP_METHOD(void set_single_paragraph_mode(bool setting = true), pango_layout_set_single_paragraph_mode) 152 _WRAP_METHOD(bool get_single_paragraph_mode() const, pango_layout_get_single_paragraph_mode) 153 154 _WRAP_METHOD(void set_ellipsize(EllipsizeMode ellipsize), pango_layout_set_ellipsize) 155 _WRAP_METHOD(EllipsizeMode get_ellipsize() const, pango_layout_get_ellipsize) 156 157 _WRAP_METHOD(bool is_ellipsized() const, pango_layout_is_ellipsized) 158 _WRAP_METHOD(int get_unknown_glyphs_count() const, pango_layout_get_unknown_glyphs_count) 159 160 _WRAP_METHOD(void context_changed(), pango_layout_context_changed) 161 162 _WRAP_METHOD(guint get_serial() const, pango_layout_get_serial) 163 164 /** Retrieve an array of logical attributes for each character in the layout. 165 * @return An array of logical attributes. 166 */ 167 Glib::ArrayHandle<LogAttr> get_log_attrs() const; 168 169 /** Convert from an index within the layout to the onscreen position corresponding to the grapheme at that index, which is represented as rectangle. 170 * Note that @a x in the returned rectangle is always the leading edge of the grapheme 171 * and @a x + @a width the trailing edge of the grapheme. 172 * If the directionality of the grapheme is right-to-left, then @a width will be negative. 173 * @param index Byte index within layout. 174 * @return The position of the grapheme. 175 */ 176 Rectangle index_to_pos(int index) const; 177 _IGNORE(pango_layout_index_to_pos) 178 179 _WRAP_METHOD(void index_to_line_x(int index_, bool trailing, int& line, int& x_pos) const, pango_layout_index_to_line_x) 180 181 _WRAP_METHOD(void get_cursor_pos(int index, Rectangle& strong_pos, Rectangle& weak_pos) const, pango_layout_get_cursor_pos) 182 183 /** Given an index within the layout, determine the positions that of the strong cursors if the insertion point is at that index. 184 * @param index The byte index of the cursor. 185 * @return The strong cursor position. 186 */ 187 Rectangle get_cursor_strong_pos(int index) const; 188 189 /** Given an index within the layout, determine the positions that of the weak cursors if the insertion point is at that index. 190 * @param index The byte index of the cursor. 191 * @return The weak cursor position. 192 */ 193 Rectangle get_cursor_weak_pos(int index) const; 194 195 _WRAP_METHOD(void move_cursor_visually(bool strong, 196 int old_index, int old_trailing, int direction, 197 int& new_index, int& new_trailing) const, pango_layout_move_cursor_visually) 198 199 _WRAP_METHOD(bool xy_to_index(int x, int y, int& index, int& trailing) const, pango_layout_xy_to_index) 200 201 _WRAP_METHOD(void get_extents(Rectangle& ink_rect, Rectangle& logical_rect) const, pango_layout_get_extents) 202 203 /** Compute the ink extents of layout. 204 * @return The extents of the layout as drawn. 205 */ 206 Rectangle get_ink_extents() const; 207 208 /** Compute the logical extents of layout. 209 * @return The logical extents of the layout. 210 */ 211 Rectangle get_logical_extents() const; 212 213 _WRAP_METHOD(void get_pixel_extents(Rectangle& ink_rect, Rectangle& logical_rect) const, pango_layout_get_pixel_extents) 214 215 /** Compute the ink extents of the layout in device units. 216 * @return The extents of the layout as drawn. 217 */ 218 Rectangle get_pixel_ink_extents() const; 219 220 /** Compute the logical extents of the layout in device units. 221 * @return The logical extents of the layout. 222 */ 223 Rectangle get_pixel_logical_extents() const; 224 225 _WRAP_METHOD(void get_size(int& width, int& height) const, pango_layout_get_size) 226 _WRAP_METHOD(void get_pixel_size(int& width, int& height) const, pango_layout_get_pixel_size) 227 228 _WRAP_METHOD(int get_baseline() const, pango_layout_get_baseline) 229 230 _WRAP_METHOD(int get_line_count() const, pango_layout_get_line_count) 231 232 //Note that the const version uses a different (faster) C function: 233 _WRAP_METHOD(Glib::RefPtr<LayoutLine> get_line(int line), pango_layout_get_line, refreturn) 234 _WRAP_METHOD(Glib::RefPtr<const LayoutLine> get_line(int line) const, pango_layout_get_line_readonly, refreturn) 235 236 //Note that the const version uses a different (faster) C function: 237 _WRAP_METHOD(SListHandle_LayoutLine get_lines(), pango_layout_get_lines) 238 _WRAP_METHOD(SListHandle_ConstLayoutLine get_lines() const, pango_layout_get_lines_readonly) 239 240_DEPRECATE_IFDEF_START 241 /** Gets an iterator to iterate over the visual extents of the layout. 242 * @param iter Location to store the iterator. 243 * 244 * @deprecated Use the get_iter() that returns the LayoutIter instead of 245 * using an output parameter. 246 */ 247 void get_iter(LayoutIter& iter); 248_DEPRECATE_IFDEF_END 249 250 /** Gets an iterator to iterate over the visual extents of the layout. 251 * @result The iterator. 252 * 253 * @newin{2,28} 254 */ 255 LayoutIter get_iter(); 256 257 258 /** Adds the text in this LayoutLine to the current path in the 259 * specified Cairo @a context. The origin of the glyphs (the left edge 260 * of the line) will be at the current point of the cairo context. 261 * 262 * @param context A Cairo context. 263 */ 264 void add_to_cairo_context(const Cairo::RefPtr<Cairo::Context>& context); 265 266 /** Draws a Layout in the specified Cairo @a context. The top-left 267 * corner of the Layout will be drawn at the current point of the 268 * cairo context. 269 * 270 * @param context A Cairo context. 271 * 272 * @newin{2,16} 273 */ 274 void show_in_cairo_context(const Cairo::RefPtr<Cairo::Context>& context); 275}; 276 277} /* namespace Pango */ 278 279