2
// Generated by gtkmmproc -- DO NOT MODIFY!
3
#ifndef _PANGOMM_LAYOUT_H
4
#define _PANGOMM_LAYOUT_H
12
* Copyright(C) 1998-1999 The gtkmm Development Team
14
* This library is free software; you can redistribute it and/or
15
* modify it under the terms of the GNU Library General Public
16
* License as published by the Free Software Foundation; either
17
* version 2 of the License, or(at your option) any later version.
19
* This library is distributed in the hope that it will be useful,
20
* but WITHOUT ANY WARRANTY; without even the implied warranty of
21
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
22
* Library General Public License for more details.
24
* You should have received a copy of the GNU Library General Public
25
* License along with this library; if not, write to the Free
26
* Software Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
30
#include <glibmm/object.h>
31
#include <glibmm/slisthandle.h>
32
#include <pangomm/font.h>
33
#include <pangomm/fontdescription.h>
34
#include <pangomm/context.h>
35
#include <pangomm/attrlist.h>
36
#include <pangomm/tabarray.h>
37
#include <pangomm/layoutline.h>
38
#include <pangomm/layoutiter.h>
39
#include <pango/pango-layout.h>
42
#ifndef DOXYGEN_SHOULD_SKIP_THIS
43
typedef struct _PangoLayout PangoLayout;
44
typedef struct _PangoLayoutClass PangoLayoutClass;
45
#endif /* DOXYGEN_SHOULD_SKIP_THIS */
49
{ class Layout_Class; } // namespace Pango
54
/** @addtogroup pangommEnums Enums and Flags */
57
* @ingroup pangommEnums
69
#ifndef DOXYGEN_SHOULD_SKIP_THIS
74
class Value<Pango::Alignment> : public Glib::Value_Enum<Pango::Alignment>
77
static GType value_type() G_GNUC_CONST;
81
#endif /* DOXYGEN_SHOULD_SKIP_THIS */
88
* @ingroup pangommEnums
100
#ifndef DOXYGEN_SHOULD_SKIP_THIS
105
class Value<Pango::WrapMode> : public Glib::Value_Enum<Pango::WrapMode>
108
static GType value_type() G_GNUC_CONST;
112
#endif /* DOXYGEN_SHOULD_SKIP_THIS */
119
* @ingroup pangommEnums
132
#ifndef DOXYGEN_SHOULD_SKIP_THIS
137
class Value<Pango::EllipsizeMode> : public Glib::Value_Enum<Pango::EllipsizeMode>
140
static GType value_type() G_GNUC_CONST;
144
#endif /* DOXYGEN_SHOULD_SKIP_THIS */
151
/** A Pango::Layout represents an entire paragraph of text.
152
* It is initialized with a Pango::Context, UTF-8 string and set of attributes for that string.
153
* Once that is done, the set of formatted lines can be extracted from the object,
154
* the layout can be rendered, and conversion between logical character positions
155
* within the layout's text, and the physical position of the resulting glyphs can be made.
158
class Layout : public Glib::Object
161
#ifndef DOXYGEN_SHOULD_SKIP_THIS
164
typedef Layout CppObjectType;
165
typedef Layout_Class CppClassType;
166
typedef PangoLayout BaseObjectType;
167
typedef PangoLayoutClass BaseClassType;
169
private: friend class Layout_Class;
170
static CppClassType layout_class_;
174
Layout(const Layout&);
175
Layout& operator=(const Layout&);
178
explicit Layout(const Glib::ConstructParams& construct_params);
179
explicit Layout(PangoLayout* castitem);
181
#endif /* DOXYGEN_SHOULD_SKIP_THIS */
186
#ifndef DOXYGEN_SHOULD_SKIP_THIS
187
static GType get_type() G_GNUC_CONST;
188
static GType get_base_type() G_GNUC_CONST;
191
///Provides access to the underlying C GObject.
192
PangoLayout* gobj() { return reinterpret_cast<PangoLayout*>(gobject_); }
194
///Provides access to the underlying C GObject.
195
const PangoLayout* gobj() const { return reinterpret_cast<PangoLayout*>(gobject_); }
197
///Provides access to the underlying C instance. The caller is responsible for unrefing it. Use when directly setting fields in structs.
198
PangoLayout* gobj_copy();
204
explicit Layout(const Glib::RefPtr<Context>& context);
208
static Glib::RefPtr<Layout> create(const Glib::RefPtr<Context>& context);
211
/** Does a deep copy-by-value of the @a src layout. The attribute list,
212
* tab array, and text from the original layout are all copied by
214
* @return A new Pango::Layout identical to @a src .
216
Glib::RefPtr<Layout> copy();
218
/** Retrieves the Pango::Context used for this layout.
219
* @return The Pango::Context for the layout. This does not
220
* have an additional refcount added, so if you want to keep
221
* a copy of this around, you must reference it yourself.
223
Glib::RefPtr<Context> get_context() const;
225
/** Sets the text attributes for a layout object.
226
* @param attrs A Pango::AttrList.
228
void set_attributes(AttrList& attrs);
230
/** Gets the attribute list for the layout, if any.
231
* @return A Pango::AttrList.
233
AttrList get_attributes() const;
235
/** Set the text of the layout.
236
* @param text The text for the layout.
238
void set_text(const Glib::ustring& text);
241
/** Gets the text in the layout. The returned text should not
242
* be freed or modified.
243
* @return The text in the @a layout .
245
Glib::ustring get_text() const;
247
/** Sets the layout text and attribute list from marked-up text (see markup format).
248
* Replaces the current text and attribute list.
249
* @param markup Some marked-up text.
251
void set_markup(const Glib::ustring& markup);
253
/** Sets the layout text and attribute list from marked-up text (see markup format).
254
* Replaces the current text and attribute list.
256
* If @a accel_marker is nonzero, the given character will mark the character following
257
* it as an accelerator. For example, the accel marker might be an ampersand or
258
* underscore. All characters marked as an accelerator will receive a
259
* Pango::UNDERLINE_LOW attribute, and the first character so marked will be returned
260
* in @a accel_char. Two @a accel_marker characters following each other produce a
261
* single literal @a accel_marker character.
262
* @param markup Some marked-up text.
263
* @param accel_marker Marker for accelerators in the text.
264
* @param accel_char Return location for any located accelerators.
266
void set_markup(const Glib::ustring& markup, gunichar accel_marker, gunichar& accel_char);
269
/** Set the default font description for the layout. If no font
270
* description is set on the layout, the font description from
271
* the layout's context is used.
272
* @param desc The new pango font description.
274
void set_font_description(const FontDescription& desc);
275
void unset_font_description();
278
/** Sets the width to which the lines of the Pango::Layout should be wrapped.
279
* @param width The desired width, or -1 to indicate that no wrapping should be
282
void set_width(int width);
284
/** Gets the width to which the lines of the Pango::Layout should be wrapped.
287
int get_width() const;
289
/** Sets the wrap mode; the wrap mode only has an effect if a width
290
* is set on the layout with pango_layout_set_width(). To turn off wrapping,
291
* set the width to -1.
292
* @param wrap The wrap mode.
294
void set_wrap(WrapMode wrap);
296
/** Gets the wrap mode for the layout.
297
* @return Active wrap mode.
299
WrapMode get_wrap() const;
301
/** Sets the width in pango units to indent each paragraph. A negative value
302
* of @a indent will produce a hanging indent. That is, the first line will
303
* have the full width, and subsequent lines will be indented by the
304
* absolute value of @a indent .
305
* @param indent The amount by which to indentset.
307
void set_indent(int indent);
309
/** Gets the paragraph indent width in pango units. A negative value
310
* indicates a hanging indent.
311
* @return The indent.
313
int get_indent() const;
315
/** Sets the amount of spacing between the lines of the layout.
316
* @param spacing The amount of spacing.
318
void set_spacing(int spacing);
320
/** Gets the amount of spacing between the lines of the layout.
321
* @return The spacing (in Pango::GlyphUnit).
323
int get_spacing() const;
325
/** Sets whether or not each complete line should be stretched to
326
* fill the entire width of the layout. This stretching is typically
327
* done by adding whitespace, but for some scripts (such as Arabic),
328
* the justification is done by extending the characters.
330
* Note that as of Pango-1.4, this functionality is not yet implemented.
331
* @param justify Whether the lines in the layout should be justified.
333
void set_justify(bool justify = true);
335
/** Gets whether or not each complete line should be stretched to
336
* fill the entire width of the layout.
337
* @return The justify.
339
bool get_justify() const;
342
/** Gets whether to calculate the bidirectional base direction
343
* for the layout according to the contents of the layout.
344
* See pango_layout_set_auto_dir().
345
* @return If <tt>true</tt>, the bidirectional base direction
346
* is computed from the layout's contents.
348
bool get_auto_dir() const;
350
/** Sets whether to calculate the bidirectional base direction
351
* for the layout according to the contents of the layout;
352
* when this flag is on (the default), then paragraphs in
353
* @a layout that begin with strong right-to-left characters
354
* (Arabic and Hebrew principally), will have right-to-left
355
* layout, paragraphs with letters from other scripts will
356
* have left-to-right layout. Paragraphs with only neutral
357
* characters get their direction from the surrounding paragraphs.
359
* When <tt>false</tt>, the choice between left-to-right and
360
* right-to-left layout is done by according to the base direction
361
* of the layout's Pango::Context. (See pango_context_set_base_dir()).
363
* When the auto-computed direction or a paragraph differs from the
364
* base direction of the context, then the interpretation of
365
* Pango::ALIGN_LEFT and Pango::ALIGN_RIGHT are swapped.
366
* @param auto_dir If <tt>true</tt>, compute the bidirectional base direction
367
* from the layout's contents.
369
void set_auto_dir(bool auto_dir = true);
372
/** Sets the alignment for the layout (how partial lines are
373
* positioned within the horizontal space available.)
374
* @param alignment The new alignment.
376
void set_alignment(Alignment alignment);
378
/** Sets the alignment for the layout (how partial lines are
379
* positioned within the horizontal space available.)
380
* @return The alignment value.
382
Alignment get_alignment() const;
385
/** Sets the tabs to use for @a layout , overriding the default tabs
386
* (by default, tabs are every 8 spaces). If @a tabs is <tt>0</tt>, the default
387
* tabs are reinstated. @a tabs is copied into the layout; you must
388
* free your copy of @a tabs yourself.
389
* @param tabs A Pango::TabArray.
391
void set_tabs(TabArray& tabs);
393
/** Get the current Pango::TabArray used by this layout. If no
394
* Pango::TabArray has been set, then the default tabs are in use
395
* and an invalid instance is returned. Default tabs are every 8 spaces.
396
* @return A copy of the tabs for this layout.
398
TabArray get_tabs() const;
401
/** If @a setting is <tt>true</tt>, do not treat newlines and similar characters
402
* as paragraph separators; instead, keep all text in a single paragraph,
403
* and display a glyph for paragraph separator characters. Used when
404
* you want to allow editing of newlines on a single text line.
405
* @param setting New setting.
407
void set_single_paragraph_mode(bool setting = true);
409
/** Obtains the value set by pango_layout_set_single_paragraph_mode().
410
* @return <tt>true</tt> if the layout does not break paragraphs at
411
* paragraph separator characters.
413
bool get_single_paragraph_mode() const;
416
/** Sets the type of ellipsization being performed for @a layout .
417
* Depending on the ellipsization mode @a ellipsize text is
418
* removed from the start, middle, or end of lines so they
419
* fit within the width of layout set with pango_layout_set_width().
421
* If the layout contains characters such as newlines that
422
* force it to be layed out in multiple lines, then each line
423
* is ellipsized separately.
426
* @param ellipsize The new ellipsization mode for @a layout .
428
void set_ellipsize(EllipsizeMode ellipsize);
430
/** Gets the type of ellipsization being performed for @a layout .
431
* See pango_layout_set_ellipsize()
432
* @return The current ellipsization mode for @a layout
436
EllipsizeMode get_ellipsize() const;
439
/** Forces recomputation of any state in the Pango::Layout that
440
* might depend on the layout's context. This function should
441
* be called if you make changes to the context subsequent
442
* to creating the layout.
444
void context_changed();
446
/** Retrieve an array of logical attributes for each character in the layout.
447
* @return An array of logical attributes.
449
Glib::ArrayHandle<LogAttr> get_log_attrs() const;
451
/** Convert from an index within the layout to the onscreen position corresponding to the grapheme at that index, which is represented as rectangle.
452
* Note that @a x in the returned rectangle is always the leading edge of the grapheme
453
* and @a x + @a width the trailing edge of the grapheme.
454
* If the directionality of the grapheme is right-to-left, then @a width will be negative.
455
* @param index Byte index within layout.
456
* @return The position of the grapheme.
458
Rectangle index_to_pos(int index) const;
461
/** Given an index within a layout, determines the positions that of the
462
* strong and weak cursors if the insertion point is at that
463
* index. The position of each cursor is stored as a zero-width
464
* rectangle. The strong cursor location is the location where
465
* characters of the directionality equal to the base direction of the
466
* layout are inserted. The weak cursor location is the location
467
* where characters of the directionality opposite to the base
468
* direction of the layout are inserted.
469
* @param index The byte index of the cursor.
470
* @param strong_pos Location to store the strong cursor position (may be <tt>0</tt>).
471
* @param weak_pos Location to store the weak cursor position (may be <tt>0</tt>).
473
void get_cursor_pos(int index, Rectangle& strong_pos, Rectangle& weak_pos) const;
475
/** Given an index within the layout, determine the positions that of the strong cursors if the insertion point is at that index.
476
* @param index The byte index of the cursor.
477
* @return The strong cursor position.
479
Rectangle get_cursor_strong_pos(int index) const;
481
/** Given an index within the layout, determine the positions that of the weak cursors if the insertion point is at that index.
482
* @param index The byte index of the cursor.
483
* @return The weak cursor position.
485
Rectangle get_cursor_weak_pos(int index) const;
488
/** Computes a new cursor position from an old position and
489
* a count of positions to move visually. If @a count is positive,
490
* then the new strong cursor position will be one position
491
* to the right of the old cursor position. If @a count is position
492
* then the new strong cursor position will be one position
493
* to the left of the old cursor position.
495
* In the presence of bidirection text, the correspondence
496
* between logical and visual order will depend on the direction
497
* of the current run, and there may be jumps when the cursor
498
* is moved off of the end of a run.
500
* Motion here is in cursor positions, not in characters, so a
501
* single call to pango_layout_move_cursor_visually() may move the
502
* cursor over multiple characters when multiple characters combine
503
* to form a single grapheme.
504
* @param strong Whether the moving cursor is the strong cursor or the
505
* weak cursor. The strong cursor is the cursor corresponding
506
* to text insertion in the base direction for the layout.
507
* @param old_index The byte index of the grapheme for the old index.
508
* @param old_trailing If 0, the cursor was at the trailing edge of the
509
* grapheme indicated by @a old_index , if > 0, the cursor
510
* was at the leading edge.
511
* @param direction Direction to move cursor. A negative
512
* value indicates motion to the left.
513
* @param new_index Location to store the new cursor byte index. A value of -1
514
* indicates that the cursor has been moved off the beginning
515
* of the layout. A value of G_MAXINT indicates that
516
* the cursor has been moved off the end of the layout.
517
* @param new_trailing Number of characters to move forward from the location returned
518
* for @a new_index to get the position where the cursor should
519
* be displayed. This allows distinguishing the position at
520
* the beginning of one line from the position at the end
521
* of the preceding line. @a new_index is always on the line
522
* where the cursor should be displayed.
524
void move_cursor_visually(bool strong,
525
int old_index, int old_trailing, int direction,
526
int& new_index, int& new_trailing) const;
529
/** Converts from X and Y position within a layout to the byte
530
* index to the character at that logical position. If the
531
* Y position is not inside the layout, the closest position is chosen
532
* (the position will be clamped inside the layout). If the
533
* X position is not within the layout, then the start or the
534
* end of the line is chosen as described for pango_layout_x_to_index().
535
* If either the X or Y positions were not inside the layout, then the
536
* function returns <tt>false</tt>; on an exact hit, it returns <tt>true</tt>.
537
* @param x The X offset (in Pango::GlyphUnit)
538
* from the left edge of the layout.
539
* @param y The Y offset (in Pango::GlyphUnit)
540
* from the top edge of the layout.
541
* @param index Location to store calculated byte index.
542
* @param trailing Location to store a integer indicating where
543
* in the grapheme the user clicked. It will either
544
* be zero, or the number of characters in the
545
* grapheme. 0 represents the trailing edge of the grapheme.
546
* @return <tt>true</tt> if the coordinates were inside text.
548
bool xy_to_index(int x, int y, int& index, int& trailing) const;
551
/** Compute the logical and ink extents of @a layout . Logical extents
552
* are usually what you want for positioning things. The extents
553
* are given in layout coordinates; layout coordinates begin at the
554
* top left corner of the layout.
555
* @param ink_rect Rectangle used to store the extents of the layout as drawn.
556
* @param logical_rect Rectangle used to store the logical extents of the layout.
558
void get_extents(Rectangle& ink_rect, Rectangle& logical_rect) const;
560
/** Compute the ink extents of layout.
561
* @return The extents of the layout as drawn.
563
Rectangle get_ink_extents() const;
565
/** Compute the logical extents of layout.
566
* @return The logical extents of the layout.
568
Rectangle get_logical_extents() const;
571
/** Compute the logical and ink extents of @a layout in device units.
572
* See pango_layout_get_extents(); this function just calls
573
* pango_layout_get_extents() and then converts the extents to
574
* pixels using the Pango::SCALE factor.
575
* @param ink_rect Rectangle used to store the extents of the layout as drawn.
576
* @param logical_rect Rectangle used to store the logical extents of the
579
void get_pixel_extents(Rectangle& ink_rect, Rectangle& logical_rect) const;
581
/** Compute the ink extents of the layout in device units.
582
* @return The extents of the layout as drawn.
584
Rectangle get_pixel_ink_extents() const;
586
/** Compute the logical extents of the layout in device units.
587
* @return The logical extents of the layout.
589
Rectangle get_pixel_logical_extents() const;
592
/** Determines the logical width and height of a Pango::Layout
593
* in Pango units. (device units divided by Pango::SCALE). This
594
* is simply a convenience function around pango_layout_get_extents().
595
* @param width Location to store the logical width, or <tt>0</tt>.
596
* @param height Location to store the logical height, or <tt>0</tt>.
598
void get_size(int& width, int& height) const;
600
/** Determines the logical width and height of a Pango::Layout
601
* in device units. (pango_layout_get_size() returns the width
602
* and height in thousandths of a device unit.) This
603
* is simply a convenience function around pango_layout_get_extents().
604
* @param width Location to store the logical width, or <tt>0</tt>.
605
* @param height Location to store the logical height, or <tt>0</tt>.
607
void get_pixel_size(int& width, int& height) const;
610
/** Retrieves the count of lines for the @a layout .
611
* @return The line count.
613
int get_line_count() const;
616
/** Retrieves a particular line from a Pango::Layout.
617
* @param line The index of a line, which must be between 0 and
618
* <tt>pango_layout_get_line_count(layout) - 1</tt>, inclusive.
619
* @return The requested Pango::LayoutLine, or <tt>0</tt> if the
620
* index is out of range. This layout line can
621
* be ref'ed and retained, but will become invalid
622
* if changes are made to the Pango::Layout.
624
Glib::RefPtr<LayoutLine> get_line(int line);
626
/** Retrieves a particular line from a Pango::Layout.
627
* @param line The index of a line, which must be between 0 and
628
* <tt>pango_layout_get_line_count(layout) - 1</tt>, inclusive.
629
* @return The requested Pango::LayoutLine, or <tt>0</tt> if the
630
* index is out of range. This layout line can
631
* be ref'ed and retained, but will become invalid
632
* if changes are made to the Pango::Layout.
634
Glib::RefPtr<const LayoutLine> get_line(int line) const;
637
/** Returns the lines of the @a layout as a list.
638
* @return A G::SList containing the lines in the layout. This
639
* points to internal data of the Pango::Layout and must be used with
640
* care. It will become invalid on any change to the layout's
641
* text or properties.
643
SListHandle_LayoutLine get_lines();
645
/** Returns the lines of the @a layout as a list.
646
* @return A G::SList containing the lines in the layout. This
647
* points to internal data of the Pango::Layout and must be used with
648
* care. It will become invalid on any change to the layout's
649
* text or properties.
651
SListHandle_ConstLayoutLine get_lines() const;
653
/** Gets an iterator to iterate over the visual extents of the layout.
654
* @param iter Location to store the iterator.
656
void get_iter(LayoutIter& iter);
662
//C++ methods used to invoke GTK+ virtual functions:
665
//GTK+ Virtual Functions (override these to change behaviour):
667
//Default Signal Handlers::
672
} /* namespace Pango */
677
/** @relates Pango::Layout
678
* @param object The C instance
679
* @param take_copy False if the result should take ownership of the C instance. True if it should take a new copy or ref.
680
* @result A C++ instance that wraps this C instance.
682
Glib::RefPtr<Pango::Layout> wrap(PangoLayout* object, bool take_copy = false);
686
#endif /* _PANGOMM_LAYOUT_H */
added
removed
libs/gtkmm2/pango/pangomm/layout.h
