1 /* 2 * This file is part of gtkD. 3 * 4 * gtkD is free software; you can redistribute it and/or modify 5 * it under the terms of the GNU Lesser General Public License 6 * as published by the Free Software Foundation; either version 3 7 * of the License, or (at your option) any later version, with 8 * some exceptions, please read the COPYING file. 9 * 10 * gtkD is distributed in the hope that it will be useful, 11 * but WITHOUT ANY WARRANTY; without even the implied warranty of 12 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 13 * GNU Lesser General Public License for more details. 14 * 15 * You should have received a copy of the GNU Lesser General Public License 16 * along with gtkD; if not, write to the Free Software 17 * Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110, USA 18 */ 19 20 // generated automatically - do not change 21 // find conversion definition on APILookup.txt 22 // implement new conversion functionalities on the wrap.utils pakage 23 24 25 module pango.PgLayout; 26 27 private import glib.ConstructionException; 28 private import glib.ListSG; 29 private import glib.Str; 30 private import gobject.ObjectG; 31 private import gtkc.pango; 32 public import gtkc.pangotypes; 33 private import pango.PgAttributeList; 34 private import pango.PgContext; 35 private import pango.PgFontDescription; 36 private import pango.PgLayoutIter; 37 private import pango.PgLayoutLine; 38 private import pango.PgTabArray; 39 40 41 /** 42 * The #PangoLayout structure represents an entire paragraph 43 * of text. It is initialized with a #PangoContext, UTF-8 string 44 * and set of attributes for that string. Once that is done, the 45 * set of formatted lines can be extracted from the object, 46 * the layout can be rendered, and conversion between logical 47 * character positions within the layout's text, and the physical 48 * position of the resulting glyphs can be made. 49 * 50 * There are also a number of parameters to adjust the formatting 51 * of a #PangoLayout, which are illustrated in <xref linkend="parameters"/>. 52 * It is possible, as well, to ignore the 2-D setup, and simply 53 * treat the results of a #PangoLayout as a list of lines. 54 * 55 * <figure id="parameters"> 56 * <title>Adjustable parameters for a PangoLayout</title> 57 * <graphic fileref="layout.gif" format="GIF"></graphic> 58 * </figure> 59 * 60 * The #PangoLayout structure is opaque, and has no user-visible 61 * fields. 62 */ 63 public class PgLayout : ObjectG 64 { 65 /** the main Gtk struct */ 66 protected PangoLayout* pangoLayout; 67 68 /** Get the main Gtk struct */ 69 public PangoLayout* getPgLayoutStruct() 70 { 71 return pangoLayout; 72 } 73 74 /** the main Gtk struct as a void* */ 75 protected override void* getStruct() 76 { 77 return cast(void*)pangoLayout; 78 } 79 80 protected override void setStruct(GObject* obj) 81 { 82 pangoLayout = cast(PangoLayout*)obj; 83 super.setStruct(obj); 84 } 85 86 /** 87 * Sets our main struct and passes it to the parent class. 88 */ 89 public this (PangoLayout* pangoLayout, bool ownedRef = false) 90 { 91 this.pangoLayout = pangoLayout; 92 super(cast(GObject*)pangoLayout, ownedRef); 93 } 94 95 /** 96 */ 97 98 public static GType getType() 99 { 100 return pango_layout_get_type(); 101 } 102 103 /** 104 * Create a new #PangoLayout object with attributes initialized to 105 * default values for a particular #PangoContext. 106 * 107 * Params: 108 * context = a #PangoContext 109 * 110 * Return: the newly allocated #PangoLayout, with a reference 111 * count of one, which should be freed with 112 * g_object_unref(). 113 * 114 * Throws: ConstructionException GTK+ fails to create the object. 115 */ 116 public this(PgContext context) 117 { 118 auto p = pango_layout_new((context is null) ? null : context.getPgContextStruct()); 119 120 if(p is null) 121 { 122 throw new ConstructionException("null returned by new"); 123 } 124 125 this(cast(PangoLayout*) p, true); 126 } 127 128 /** 129 * Forces recomputation of any state in the #PangoLayout that 130 * might depend on the layout's context. This function should 131 * be called if you make changes to the context subsequent 132 * to creating the layout. 133 */ 134 public void contextChanged() 135 { 136 pango_layout_context_changed(pangoLayout); 137 } 138 139 /** 140 * Does a deep copy-by-value of the @src layout. The attribute list, 141 * tab array, and text from the original layout are all copied by 142 * value. 143 * 144 * Return: the newly allocated #PangoLayout, 145 * with a reference count of one, which should be freed 146 * with g_object_unref(). 147 */ 148 public PgLayout copy() 149 { 150 auto p = pango_layout_copy(pangoLayout); 151 152 if(p is null) 153 { 154 return null; 155 } 156 157 return ObjectG.getDObject!(PgLayout)(cast(PangoLayout*) p, true); 158 } 159 160 /** 161 * Gets the alignment for the layout: how partial lines are 162 * positioned within the horizontal space available. 163 * 164 * Return: the alignment. 165 */ 166 public PangoAlignment getAlignment() 167 { 168 return pango_layout_get_alignment(pangoLayout); 169 } 170 171 /** 172 * Gets the attribute list for the layout, if any. 173 * 174 * Return: a #PangoAttrList. 175 */ 176 public PgAttributeList getAttributes() 177 { 178 auto p = pango_layout_get_attributes(pangoLayout); 179 180 if(p is null) 181 { 182 return null; 183 } 184 185 return ObjectG.getDObject!(PgAttributeList)(cast(PangoAttrList*) p); 186 } 187 188 /** 189 * Gets whether to calculate the bidirectional base direction 190 * for the layout according to the contents of the layout. 191 * See pango_layout_set_auto_dir(). 192 * 193 * Return: %TRUE if the bidirectional base direction 194 * is computed from the layout's contents, %FALSE otherwise. 195 * 196 * Since: 1.4 197 */ 198 public bool getAutoDir() 199 { 200 return pango_layout_get_auto_dir(pangoLayout) != 0; 201 } 202 203 /** 204 * Gets the Y position of baseline of the first line in @layout. 205 * 206 * Return: baseline of first line, from top of @layout. 207 * 208 * Since: 1.22 209 */ 210 public int getBaseline() 211 { 212 return pango_layout_get_baseline(pangoLayout); 213 } 214 215 /** 216 * Returns the number of Unicode characters in the 217 * the text of @layout. 218 * 219 * Return: the number of Unicode characters 220 * in the text of @layout 221 * 222 * Since: 1.30 223 */ 224 public int getCharacterCount() 225 { 226 return pango_layout_get_character_count(pangoLayout); 227 } 228 229 /** 230 * Retrieves the #PangoContext used for this layout. 231 * 232 * Return: the #PangoContext for the layout. 233 * This does not have an additional refcount added, so if you want to 234 * keep a copy of this around, you must reference it yourself. 235 */ 236 public PgContext getContext() 237 { 238 auto p = pango_layout_get_context(pangoLayout); 239 240 if(p is null) 241 { 242 return null; 243 } 244 245 return ObjectG.getDObject!(PgContext)(cast(PangoContext*) p); 246 } 247 248 /** 249 * Given an index within a layout, determines the positions that of the 250 * strong and weak cursors if the insertion point is at that 251 * index. The position of each cursor is stored as a zero-width 252 * rectangle. The strong cursor location is the location where 253 * characters of the directionality equal to the base direction of the 254 * layout are inserted. The weak cursor location is the location 255 * where characters of the directionality opposite to the base 256 * direction of the layout are inserted. 257 * 258 * Params: 259 * index = the byte index of the cursor 260 * strongPos = location to store the strong cursor position 261 * (may be %NULL) 262 * weakPos = location to store the weak cursor position (may be %NULL) 263 */ 264 public void getCursorPos(int index, out PangoRectangle strongPos, out PangoRectangle weakPos) 265 { 266 pango_layout_get_cursor_pos(pangoLayout, index, &strongPos, &weakPos); 267 } 268 269 /** 270 * Gets the type of ellipsization being performed for @layout. 271 * See pango_layout_set_ellipsize() 272 * 273 * Return: the current ellipsization mode for @layout. 274 * 275 * Use pango_layout_is_ellipsized() to query whether any paragraphs 276 * were actually ellipsized. 277 * 278 * Since: 1.6 279 */ 280 public PangoEllipsizeMode getEllipsize() 281 { 282 return pango_layout_get_ellipsize(pangoLayout); 283 } 284 285 /** 286 * Computes the logical and ink extents of @layout. Logical extents 287 * are usually what you want for positioning things. Note that both extents 288 * may have non-zero x and y. You may want to use those to offset where you 289 * render the layout. Not doing that is a very typical bug that shows up as 290 * right-to-left layouts not being correctly positioned in a layout with 291 * a set width. 292 * 293 * The extents are given in layout coordinates and in Pango units; layout 294 * coordinates begin at the top left corner of the layout. 295 * 296 * Params: 297 * inkRect = rectangle used to store the extents of the 298 * layout as drawn or %NULL to indicate that the result is 299 * not needed. 300 * logicalRect = rectangle used to store the logical 301 * extents of the layout or %NULL to indicate that the 302 * result is not needed. 303 */ 304 public void getExtents(out PangoRectangle inkRect, out PangoRectangle logicalRect) 305 { 306 pango_layout_get_extents(pangoLayout, &inkRect, &logicalRect); 307 } 308 309 /** 310 * Gets the font description for the layout, if any. 311 * 312 * Return: a pointer to the layout's font 313 * description, or %NULL if the font description from the layout's 314 * context is inherited. This value is owned by the layout and must 315 * not be modified or freed. 316 * 317 * Since: 1.8 318 */ 319 public PgFontDescription getFontDescription() 320 { 321 auto p = pango_layout_get_font_description(pangoLayout); 322 323 if(p is null) 324 { 325 return null; 326 } 327 328 return ObjectG.getDObject!(PgFontDescription)(cast(PangoFontDescription*) p); 329 } 330 331 /** 332 * Gets the height of layout used for ellipsization. See 333 * pango_layout_set_height() for details. 334 * 335 * Return: the height, in Pango units if positive, or 336 * number of lines if negative. 337 * 338 * Since: 1.20 339 */ 340 public int getHeight() 341 { 342 return pango_layout_get_height(pangoLayout); 343 } 344 345 /** 346 * Gets the paragraph indent width in Pango units. A negative value 347 * indicates a hanging indentation. 348 * 349 * Return: the indent in Pango units. 350 */ 351 public int getIndent() 352 { 353 return pango_layout_get_indent(pangoLayout); 354 } 355 356 /** 357 * Returns an iterator to iterate over the visual extents of the layout. 358 * 359 * Return: the new #PangoLayoutIter that should be freed using 360 * pango_layout_iter_free(). 361 */ 362 public PgLayoutIter getIter() 363 { 364 auto p = pango_layout_get_iter(pangoLayout); 365 366 if(p is null) 367 { 368 return null; 369 } 370 371 return ObjectG.getDObject!(PgLayoutIter)(cast(PangoLayoutIter*) p); 372 } 373 374 /** 375 * Gets whether each complete line should be stretched to fill the entire 376 * width of the layout. 377 * 378 * Return: the justify. 379 */ 380 public bool getJustify() 381 { 382 return pango_layout_get_justify(pangoLayout) != 0; 383 } 384 385 /** 386 * Retrieves a particular line from a #PangoLayout. 387 * 388 * Use the faster pango_layout_get_line_readonly() if you do not plan 389 * to modify the contents of the line (glyphs, glyph widths, etc.). 390 * 391 * Params: 392 * line = the index of a line, which must be between 0 and 393 * <literal>pango_layout_get_line_count(layout) - 1</literal>, inclusive. 394 * 395 * Return: the requested 396 * #PangoLayoutLine, or %NULL if the index is out of 397 * range. This layout line can be ref'ed and retained, 398 * but will become invalid if changes are made to the 399 * #PangoLayout. 400 */ 401 public PgLayoutLine getLine(int line) 402 { 403 auto p = pango_layout_get_line(pangoLayout, line); 404 405 if(p is null) 406 { 407 return null; 408 } 409 410 return ObjectG.getDObject!(PgLayoutLine)(cast(PangoLayoutLine*) p); 411 } 412 413 /** 414 * Retrieves the count of lines for the @layout. 415 * 416 * Return: the line count. 417 */ 418 public int getLineCount() 419 { 420 return pango_layout_get_line_count(pangoLayout); 421 } 422 423 /** 424 * Retrieves a particular line from a #PangoLayout. 425 * 426 * This is a faster alternative to pango_layout_get_line(), 427 * but the user is not expected 428 * to modify the contents of the line (glyphs, glyph widths, etc.). 429 * 430 * Params: 431 * line = the index of a line, which must be between 0 and 432 * <literal>pango_layout_get_line_count(layout) - 1</literal>, inclusive. 433 * 434 * Return: the requested 435 * #PangoLayoutLine, or %NULL if the index is out of 436 * range. This layout line can be ref'ed and retained, 437 * but will become invalid if changes are made to the 438 * #PangoLayout. No changes should be made to the line. 439 * 440 * Since: 1.16 441 */ 442 public PgLayoutLine getLineReadonly(int line) 443 { 444 auto p = pango_layout_get_line_readonly(pangoLayout, line); 445 446 if(p is null) 447 { 448 return null; 449 } 450 451 return ObjectG.getDObject!(PgLayoutLine)(cast(PangoLayoutLine*) p); 452 } 453 454 /** 455 * Returns the lines of the @layout as a list. 456 * 457 * Use the faster pango_layout_get_lines_readonly() if you do not plan 458 * to modify the contents of the lines (glyphs, glyph widths, etc.). 459 * 460 * Return: a #GSList containing 461 * the lines in the layout. This points to internal data of the #PangoLayout 462 * and must be used with care. It will become invalid on any change to the layout's 463 * text or properties. 464 */ 465 public ListSG getLines() 466 { 467 auto p = pango_layout_get_lines(pangoLayout); 468 469 if(p is null) 470 { 471 return null; 472 } 473 474 return new ListSG(cast(GSList*) p); 475 } 476 477 /** 478 * Returns the lines of the @layout as a list. 479 * 480 * This is a faster alternative to pango_layout_get_lines(), 481 * but the user is not expected 482 * to modify the contents of the lines (glyphs, glyph widths, etc.). 483 * 484 * Return: a #GSList containing 485 * the lines in the layout. This points to internal data of the #PangoLayout and 486 * must be used with care. It will become invalid on any change to the layout's 487 * text or properties. No changes should be made to the lines. 488 * 489 * Since: 1.16 490 */ 491 public ListSG getLinesReadonly() 492 { 493 auto p = pango_layout_get_lines_readonly(pangoLayout); 494 495 if(p is null) 496 { 497 return null; 498 } 499 500 return new ListSG(cast(GSList*) p); 501 } 502 503 /** 504 * Retrieves an array of logical attributes for each character in 505 * the @layout. 506 * 507 * Params: 508 * attrs = location to store a pointer to an array of logical attributes 509 * This value must be freed with g_free(). 510 * nAttrs = location to store the number of the attributes in the 511 * array. (The stored value will be one more than the total number 512 * of characters in the layout, since there need to be attributes 513 * corresponding to both the position before the first character 514 * and the position after the last character.) 515 */ 516 public void getLogAttrs(out PangoLogAttr[] attrs) 517 { 518 PangoLogAttr* outattrs = null; 519 int nAttrs; 520 521 pango_layout_get_log_attrs(pangoLayout, &outattrs, &nAttrs); 522 523 attrs = outattrs[0 .. nAttrs]; 524 } 525 526 /** 527 * Retrieves an array of logical attributes for each character in 528 * the @layout. 529 * 530 * This is a faster alternative to pango_layout_get_log_attrs(). 531 * The returned array is part of @layout and must not be modified. 532 * Modifying the layout will invalidate the returned array. 533 * 534 * The number of attributes returned in @n_attrs will be one more 535 * than the total number of characters in the layout, since there 536 * need to be attributes corresponding to both the position before 537 * the first character and the position after the last character. 538 * 539 * Return: an array of logical attributes 540 * 541 * Since: 1.30 542 */ 543 public PangoLogAttr[] getLogAttrsReadonly() 544 { 545 int nAttrs; 546 547 auto p = pango_layout_get_log_attrs_readonly(pangoLayout, &nAttrs); 548 549 return p[0 .. nAttrs]; 550 } 551 552 /** 553 * Computes the logical and ink extents of @layout in device units. 554 * This function just calls pango_layout_get_extents() followed by 555 * two pango_extents_to_pixels() calls, rounding @ink_rect and @logical_rect 556 * such that the rounded rectangles fully contain the unrounded one (that is, 557 * passes them as first argument to pango_extents_to_pixels()). 558 * 559 * Params: 560 * inkRect = rectangle used to store the extents of the 561 * layout as drawn or %NULL to indicate that the result is 562 * not needed. 563 * logicalRect = rectangle used to store the logical 564 * extents of the layout or %NULL to indicate that the 565 * result is not needed. 566 */ 567 public void getPixelExtents(out PangoRectangle inkRect, out PangoRectangle logicalRect) 568 { 569 pango_layout_get_pixel_extents(pangoLayout, &inkRect, &logicalRect); 570 } 571 572 /** 573 * Determines the logical width and height of a #PangoLayout 574 * in device units. (pango_layout_get_size() returns the width 575 * and height scaled by %PANGO_SCALE.) This 576 * is simply a convenience function around 577 * pango_layout_get_pixel_extents(). 578 * 579 * Params: 580 * width = location to store the logical width, or %NULL 581 * height = location to store the logical height, or %NULL 582 */ 583 public void getPixelSize(out int width, out int height) 584 { 585 pango_layout_get_pixel_size(pangoLayout, &width, &height); 586 } 587 588 /** 589 * Returns the current serial number of @layout. The serial number is 590 * initialized to an small number larger than zero when a new layout 591 * is created and is increased whenever the layout is changed using any 592 * of the setter functions, or the #PangoContext it uses has changed. 593 * The serial may wrap, but will never have the value 0. Since it 594 * can wrap, never compare it with "less than", always use "not equals". 595 * 596 * This can be used to automatically detect changes to a #PangoLayout, and 597 * is useful for example to decide whether a layout needs redrawing. 598 * To force the serial to be increased, use pango_layout_context_changed(). 599 * 600 * Return: The current serial number of @layout. 601 * 602 * Since: 1.32.4 603 */ 604 public uint getSerial() 605 { 606 return pango_layout_get_serial(pangoLayout); 607 } 608 609 /** 610 * Obtains the value set by pango_layout_set_single_paragraph_mode(). 611 * 612 * Return: %TRUE if the layout does not break paragraphs at 613 * paragraph separator characters, %FALSE otherwise. 614 */ 615 public bool getSingleParagraphMode() 616 { 617 return pango_layout_get_single_paragraph_mode(pangoLayout) != 0; 618 } 619 620 /** 621 * Determines the logical width and height of a #PangoLayout 622 * in Pango units (device units scaled by %PANGO_SCALE). This 623 * is simply a convenience function around pango_layout_get_extents(). 624 * 625 * Params: 626 * width = location to store the logical width, or %NULL 627 * height = location to store the logical height, or %NULL 628 */ 629 public void getSize(out int width, out int height) 630 { 631 pango_layout_get_size(pangoLayout, &width, &height); 632 } 633 634 /** 635 * Gets the amount of spacing between the lines of the layout. 636 * 637 * Return: the spacing in Pango units. 638 */ 639 public int getSpacing() 640 { 641 return pango_layout_get_spacing(pangoLayout); 642 } 643 644 /** 645 * Gets the current #PangoTabArray used by this layout. If no 646 * #PangoTabArray has been set, then the default tabs are in use 647 * and %NULL is returned. Default tabs are every 8 spaces. 648 * The return value should be freed with pango_tab_array_free(). 649 * 650 * Return: a copy of the tabs for this layout, or 651 * %NULL. 652 */ 653 public PgTabArray getTabs() 654 { 655 auto p = pango_layout_get_tabs(pangoLayout); 656 657 if(p is null) 658 { 659 return null; 660 } 661 662 return ObjectG.getDObject!(PgTabArray)(cast(PangoTabArray*) p); 663 } 664 665 /** 666 * Gets the text in the layout. The returned text should not 667 * be freed or modified. 668 * 669 * Return: the text in the @layout. 670 */ 671 public string getText() 672 { 673 return Str.toString(pango_layout_get_text(pangoLayout)); 674 } 675 676 /** 677 * Counts the number unknown glyphs in @layout. That is, zero if 678 * glyphs for all characters in the layout text were found, or more 679 * than zero otherwise. 680 * 681 * This function can be used to determine if there are any fonts 682 * available to render all characters in a certain string, or when 683 * used in combination with %PANGO_ATTR_FALLBACK, to check if a 684 * certain font supports all the characters in the string. 685 * 686 * Return: The number of unknown glyphs in @layout. 687 * 688 * Since: 1.16 689 */ 690 public int getUnknownGlyphsCount() 691 { 692 return pango_layout_get_unknown_glyphs_count(pangoLayout); 693 } 694 695 /** 696 * Gets the width to which the lines of the #PangoLayout should wrap. 697 * 698 * Return: the width in Pango units, or -1 if no width set. 699 */ 700 public int getWidth() 701 { 702 return pango_layout_get_width(pangoLayout); 703 } 704 705 /** 706 * Gets the wrap mode for the layout. 707 * 708 * Use pango_layout_is_wrapped() to query whether any paragraphs 709 * were actually wrapped. 710 * 711 * Return: active wrap mode. 712 */ 713 public PangoWrapMode getWrap() 714 { 715 return pango_layout_get_wrap(pangoLayout); 716 } 717 718 /** 719 * Converts from byte @index_ within the @layout to line and X position. 720 * (X position is measured from the left edge of the line) 721 * 722 * Params: 723 * index = the byte index of a grapheme within the layout. 724 * trailing = an integer indicating the edge of the grapheme to retrieve the 725 * position of. If > 0, the trailing edge of the grapheme, if 0, 726 * the leading of the grapheme. 727 * line = location to store resulting line index. (which will 728 * between 0 and pango_layout_get_line_count(layout) - 1), or %NULL 729 * xPos = location to store resulting position within line 730 * (%PANGO_SCALE units per device unit), or %NULL 731 */ 732 public void indexToLineX(int index, bool trailing, out int line, out int xPos) 733 { 734 pango_layout_index_to_line_x(pangoLayout, index, trailing, &line, &xPos); 735 } 736 737 /** 738 * Converts from an index within a #PangoLayout to the onscreen position 739 * corresponding to the grapheme at that index, which is represented 740 * as rectangle. Note that <literal>pos->x</literal> is always the leading 741 * edge of the grapheme and <literal>pos->x + pos->width</literal> the trailing 742 * edge of the grapheme. If the directionality of the grapheme is right-to-left, 743 * then <literal>pos->width</literal> will be negative. 744 * 745 * Params: 746 * index = byte index within @layout 747 * pos = rectangle in which to store the position of the grapheme 748 */ 749 public void indexToPos(int index, out PangoRectangle pos) 750 { 751 pango_layout_index_to_pos(pangoLayout, index, &pos); 752 } 753 754 /** 755 * Queries whether the layout had to ellipsize any paragraphs. 756 * 757 * This returns %TRUE if the ellipsization mode for @layout 758 * is not %PANGO_ELLIPSIZE_NONE, a positive width is set on @layout, 759 * and there are paragraphs exceeding that width that have to be 760 * ellipsized. 761 * 762 * Return: %TRUE if any paragraphs had to be ellipsized, %FALSE 763 * otherwise. 764 * 765 * Since: 1.16 766 */ 767 public bool isEllipsized() 768 { 769 return pango_layout_is_ellipsized(pangoLayout) != 0; 770 } 771 772 /** 773 * Queries whether the layout had to wrap any paragraphs. 774 * 775 * This returns %TRUE if a positive width is set on @layout, 776 * ellipsization mode of @layout is set to %PANGO_ELLIPSIZE_NONE, 777 * and there are paragraphs exceeding the layout width that have 778 * to be wrapped. 779 * 780 * Return: %TRUE if any paragraphs had to be wrapped, %FALSE 781 * otherwise. 782 * 783 * Since: 1.16 784 */ 785 public bool isWrapped() 786 { 787 return pango_layout_is_wrapped(pangoLayout) != 0; 788 } 789 790 /** 791 * Computes a new cursor position from an old position and 792 * a count of positions to move visually. If @direction is positive, 793 * then the new strong cursor position will be one position 794 * to the right of the old cursor position. If @direction is negative, 795 * then the new strong cursor position will be one position 796 * to the left of the old cursor position. 797 * 798 * In the presence of bidirectional text, the correspondence 799 * between logical and visual order will depend on the direction 800 * of the current run, and there may be jumps when the cursor 801 * is moved off of the end of a run. 802 * 803 * Motion here is in cursor positions, not in characters, so a 804 * single call to pango_layout_move_cursor_visually() may move the 805 * cursor over multiple characters when multiple characters combine 806 * to form a single grapheme. 807 * 808 * Params: 809 * strong = whether the moving cursor is the strong cursor or the 810 * weak cursor. The strong cursor is the cursor corresponding 811 * to text insertion in the base direction for the layout. 812 * oldIndex = the byte index of the grapheme for the old index 813 * oldTrailing = if 0, the cursor was at the leading edge of the 814 * grapheme indicated by @old_index, if > 0, the cursor 815 * was at the trailing edge. 816 * direction = direction to move cursor. A negative 817 * value indicates motion to the left. 818 * newIndex = location to store the new cursor byte index. A value of -1 819 * indicates that the cursor has been moved off the beginning 820 * of the layout. A value of %G_MAXINT indicates that 821 * the cursor has been moved off the end of the layout. 822 * newTrailing = number of characters to move forward from the 823 * location returned for @new_index to get the position 824 * where the cursor should be displayed. This allows 825 * distinguishing the position at the beginning of one 826 * line from the position at the end of the preceding 827 * line. @new_index is always on the line where the 828 * cursor should be displayed. 829 */ 830 public void moveCursorVisually(bool strong, int oldIndex, int oldTrailing, int direction, out int newIndex, out int newTrailing) 831 { 832 pango_layout_move_cursor_visually(pangoLayout, strong, oldIndex, oldTrailing, direction, &newIndex, &newTrailing); 833 } 834 835 /** 836 * Sets the alignment for the layout: how partial lines are 837 * positioned within the horizontal space available. 838 * 839 * Params: 840 * alignment = the alignment 841 */ 842 public void setAlignment(PangoAlignment alignment) 843 { 844 pango_layout_set_alignment(pangoLayout, alignment); 845 } 846 847 /** 848 * Sets the text attributes for a layout object. 849 * References @attrs, so the caller can unref its reference. 850 * 851 * Params: 852 * attrs = a #PangoAttrList, can be %NULL 853 */ 854 public void setAttributes(PgAttributeList attrs) 855 { 856 pango_layout_set_attributes(pangoLayout, (attrs is null) ? null : attrs.getPgAttributeListStruct()); 857 } 858 859 /** 860 * Sets whether to calculate the bidirectional base direction 861 * for the layout according to the contents of the layout; 862 * when this flag is on (the default), then paragraphs in 863 * @layout that begin with strong right-to-left characters 864 * (Arabic and Hebrew principally), will have right-to-left 865 * layout, paragraphs with letters from other scripts will 866 * have left-to-right layout. Paragraphs with only neutral 867 * characters get their direction from the surrounding paragraphs. 868 * 869 * When %FALSE, the choice between left-to-right and 870 * right-to-left layout is done according to the base direction 871 * of the layout's #PangoContext. (See pango_context_set_base_dir()). 872 * 873 * When the auto-computed direction of a paragraph differs from the 874 * base direction of the context, the interpretation of 875 * %PANGO_ALIGN_LEFT and %PANGO_ALIGN_RIGHT are swapped. 876 * 877 * Params: 878 * autoDir = if %TRUE, compute the bidirectional base direction 879 * from the layout's contents. 880 * 881 * Since: 1.4 882 */ 883 public void setAutoDir(bool autoDir) 884 { 885 pango_layout_set_auto_dir(pangoLayout, autoDir); 886 } 887 888 /** 889 * Sets the type of ellipsization being performed for @layout. 890 * Depending on the ellipsization mode @ellipsize text is 891 * removed from the start, middle, or end of text so they 892 * fit within the width and height of layout set with 893 * pango_layout_set_width() and pango_layout_set_height(). 894 * 895 * If the layout contains characters such as newlines that 896 * force it to be layed out in multiple paragraphs, then whether 897 * each paragraph is ellipsized separately or the entire layout 898 * is ellipsized as a whole depends on the set height of the layout. 899 * See pango_layout_set_height() for details. 900 * 901 * Params: 902 * ellipsize = the new ellipsization mode for @layout 903 * 904 * Since: 1.6 905 */ 906 public void setEllipsize(PangoEllipsizeMode ellipsize) 907 { 908 pango_layout_set_ellipsize(pangoLayout, ellipsize); 909 } 910 911 /** 912 * Sets the default font description for the layout. If no font 913 * description is set on the layout, the font description from 914 * the layout's context is used. 915 * 916 * Params: 917 * desc = the new #PangoFontDescription, or %NULL to unset the 918 * current font description 919 */ 920 public void setFontDescription(PgFontDescription desc) 921 { 922 pango_layout_set_font_description(pangoLayout, (desc is null) ? null : desc.getPgFontDescriptionStruct()); 923 } 924 925 /** 926 * Sets the height to which the #PangoLayout should be ellipsized at. There 927 * are two different behaviors, based on whether @height is positive or 928 * negative. 929 * 930 * If @height is positive, it will be the maximum height of the layout. Only 931 * lines would be shown that would fit, and if there is any text omitted, 932 * an ellipsis added. At least one line is included in each paragraph regardless 933 * of how small the height value is. A value of zero will render exactly one 934 * line for the entire layout. 935 * 936 * If @height is negative, it will be the (negative of) maximum number of lines per 937 * paragraph. That is, the total number of lines shown may well be more than 938 * this value if the layout contains multiple paragraphs of text. 939 * The default value of -1 means that first line of each paragraph is ellipsized. 940 * This behvaior may be changed in the future to act per layout instead of per 941 * paragraph. File a bug against pango at <ulink 942 * url="http://bugzilla.gnome.org/">http://bugzilla.gnome.org/</ulink> if your 943 * code relies on this behavior. 944 * 945 * Height setting only has effect if a positive width is set on 946 * @layout and ellipsization mode of @layout is not %PANGO_ELLIPSIZE_NONE. 947 * The behavior is undefined if a height other than -1 is set and 948 * ellipsization mode is set to %PANGO_ELLIPSIZE_NONE, and may change in the 949 * future. 950 * 951 * Params: 952 * height = the desired height of the layout in Pango units if positive, 953 * or desired number of lines if negative. 954 * 955 * Since: 1.20 956 */ 957 public void setHeight(int height) 958 { 959 pango_layout_set_height(pangoLayout, height); 960 } 961 962 /** 963 * Sets the width in Pango units to indent each paragraph. A negative value 964 * of @indent will produce a hanging indentation. That is, the first line will 965 * have the full width, and subsequent lines will be indented by the 966 * absolute value of @indent. 967 * 968 * The indent setting is ignored if layout alignment is set to 969 * %PANGO_ALIGN_CENTER. 970 * 971 * Params: 972 * indent = the amount by which to indent. 973 */ 974 public void setIndent(int indent) 975 { 976 pango_layout_set_indent(pangoLayout, indent); 977 } 978 979 /** 980 * Sets whether each complete line should be stretched to 981 * fill the entire width of the layout. This stretching is typically 982 * done by adding whitespace, but for some scripts (such as Arabic), 983 * the justification may be done in more complex ways, like extending 984 * the characters. 985 * 986 * Note that this setting is not implemented and so is ignored in Pango 987 * older than 1.18. 988 * 989 * Params: 990 * justify = whether the lines in the layout should be justified. 991 */ 992 public void setJustify(bool justify) 993 { 994 pango_layout_set_justify(pangoLayout, justify); 995 } 996 997 /** 998 * Same as pango_layout_set_markup_with_accel(), but 999 * the markup text isn't scanned for accelerators. 1000 * 1001 * Params: 1002 * markup = marked-up text 1003 * length = length of marked-up text in bytes, or -1 if @markup is 1004 * null-terminated 1005 */ 1006 public void setMarkup(string markup, int length) 1007 { 1008 pango_layout_set_markup(pangoLayout, Str.toStringz(markup), length); 1009 } 1010 1011 /** 1012 * Sets the layout text and attribute list from marked-up text (see 1013 * <link linkend="PangoMarkupFormat">markup format</link>). Replaces 1014 * the current text and attribute list. 1015 * 1016 * If @accel_marker is nonzero, the given character will mark the 1017 * character following it as an accelerator. For example, @accel_marker 1018 * might be an ampersand or underscore. All characters marked 1019 * as an accelerator will receive a %PANGO_UNDERLINE_LOW attribute, 1020 * and the first character so marked will be returned in @accel_char. 1021 * Two @accel_marker characters following each other produce a single 1022 * literal @accel_marker character. 1023 * 1024 * Params: 1025 * markup = marked-up text 1026 * (see <link linkend="PangoMarkupFormat">markup format</link>) 1027 * length = length of marked-up text in bytes, or -1 if @markup is 1028 * null-terminated 1029 * accelMarker = marker for accelerators in the text 1030 * accelChar = return location 1031 * for first located accelerator, or %NULL 1032 */ 1033 public void setMarkupWithAccel(string markup, int length, dchar accelMarker, out dchar accelChar) 1034 { 1035 pango_layout_set_markup_with_accel(pangoLayout, Str.toStringz(markup), length, accelMarker, &accelChar); 1036 } 1037 1038 /** 1039 * If @setting is %TRUE, do not treat newlines and similar characters 1040 * as paragraph separators; instead, keep all text in a single paragraph, 1041 * and display a glyph for paragraph separator characters. Used when 1042 * you want to allow editing of newlines on a single text line. 1043 * 1044 * Params: 1045 * setting = new setting 1046 */ 1047 public void setSingleParagraphMode(bool setting) 1048 { 1049 pango_layout_set_single_paragraph_mode(pangoLayout, setting); 1050 } 1051 1052 /** 1053 * Sets the amount of spacing in Pango unit between the lines of the 1054 * layout. 1055 * 1056 * Params: 1057 * spacing = the amount of spacing 1058 */ 1059 public void setSpacing(int spacing) 1060 { 1061 pango_layout_set_spacing(pangoLayout, spacing); 1062 } 1063 1064 /** 1065 * Sets the tabs to use for @layout, overriding the default tabs 1066 * (by default, tabs are every 8 spaces). If @tabs is %NULL, the default 1067 * tabs are reinstated. @tabs is copied into the layout; you must 1068 * free your copy of @tabs yourself. 1069 * 1070 * Params: 1071 * tabs = a #PangoTabArray, or %NULL 1072 */ 1073 public void setTabs(PgTabArray tabs) 1074 { 1075 pango_layout_set_tabs(pangoLayout, (tabs is null) ? null : tabs.getPgTabArrayStruct()); 1076 } 1077 1078 /** 1079 * Sets the text of the layout. 1080 * 1081 * Note that if you have used 1082 * pango_layout_set_markup() or pango_layout_set_markup_with_accel() on 1083 * @layout before, you may want to call pango_layout_set_attributes() to clear 1084 * the attributes set on the layout from the markup as this function does not 1085 * clear attributes. 1086 * 1087 * Params: 1088 * text = a valid UTF-8 string 1089 * length = maximum length of @text, in bytes. -1 indicates that 1090 * the string is nul-terminated and the length should be 1091 * calculated. The text will also be truncated on 1092 * encountering a nul-termination even when @length is 1093 * positive. 1094 */ 1095 public void setText(string text) 1096 { 1097 pango_layout_set_text(pangoLayout, Str.toStringz(text), cast(int)text.length); 1098 } 1099 1100 /** 1101 * Sets the width to which the lines of the #PangoLayout should wrap or 1102 * ellipsized. The default value is -1: no width set. 1103 * 1104 * Params: 1105 * width = the desired width in Pango units, or -1 to indicate that no 1106 * wrapping or ellipsization should be performed. 1107 */ 1108 public void setWidth(int width) 1109 { 1110 pango_layout_set_width(pangoLayout, width); 1111 } 1112 1113 /** 1114 * Sets the wrap mode; the wrap mode only has effect if a width 1115 * is set on the layout with pango_layout_set_width(). 1116 * To turn off wrapping, set the width to -1. 1117 * 1118 * Params: 1119 * wrap = the wrap mode 1120 */ 1121 public void setWrap(PangoWrapMode wrap) 1122 { 1123 pango_layout_set_wrap(pangoLayout, wrap); 1124 } 1125 1126 /** 1127 * Converts from X and Y position within a layout to the byte 1128 * index to the character at that logical position. If the 1129 * Y position is not inside the layout, the closest position is chosen 1130 * (the position will be clamped inside the layout). If the 1131 * X position is not within the layout, then the start or the 1132 * end of the line is chosen as described for pango_layout_xy_to_index(). 1133 * If either the X or Y positions were not inside the layout, then the 1134 * function returns %FALSE; on an exact hit, it returns %TRUE. 1135 * 1136 * Params: 1137 * x = the X offset (in Pango units) 1138 * from the left edge of the layout. 1139 * y = the Y offset (in Pango units) 1140 * from the top edge of the layout 1141 * index = location to store calculated byte index 1142 * trailing = location to store a integer indicating where 1143 * in the grapheme the user clicked. It will either 1144 * be zero, or the number of characters in the 1145 * grapheme. 0 represents the leading edge of the grapheme. 1146 * 1147 * Return: %TRUE if the coordinates were inside text, %FALSE otherwise. 1148 */ 1149 public bool xyToIndex(int x, int y, out int index, out int trailing) 1150 { 1151 return pango_layout_xy_to_index(pangoLayout, x, y, &index, &trailing) != 0; 1152 } 1153 }