docs/tmpl/layout.sgml

   1 <!-- ##### SECTION Title ##### -->
   2 Layout Objects
   3
   4 <!-- ##### SECTION Short_Description ##### -->
   5 High-level layout driver objects
   6
   7 <!-- ##### SECTION Long_Description ##### -->
   8 <para>
   9 While complete access to the layout capabilities of Pango is provided
  10 using the detailed interfaces for itemization and shaping, using
  11 that functionality directly involves writing a fairly large amount
  12 of code. The objects and functions in this section provide a
  13 high-level driver for formatting entire paragraphs of text
  14 at once.
  15 </para>
  16
  17 <!-- ##### SECTION See_Also ##### -->
  18 <para>
  19
  20 </para>
  21
  22 <!-- ##### SECTION Stability_Level ##### -->
  23
  24
  25 <!-- ##### STRUCT PangoLayout ##### -->
  26 <para>
  27 The #PangoLayout structure represents an entire paragraph
  28 of text. It is initialized with a #PangoContext, UTF-8 string
  29 and set of attributes for that string. Once that is done, the
  30 set of formatted lines can be extracted from the object,
  31 the layout can be rendered, and conversion between logical
  32 character positions within the layout's text, and the physical
  33 position of the resulting glyphs can be made.
  34 </para>
  35
  36 <para>
  37 There are also a number of parameters to adjust the formatting
  38 of a #PangoLayout, which are illustrated in <xref linkend="parameters"/>.
  39 It is possible, as well, to ignore the 2-D setup, and simply
  40 treat the results of a #PangoLayout as a list of lines.
  41 </para>
  42
  43 <figure id="parameters">
  44 <title>Adjustable parameters for a PangoLayout</title>
  45 <graphic fileref="layout.gif" format="GIF"></graphic>
  46 </figure>
  47
  48 <para>
  49 The #PangoLayout structure is opaque, and has no user-visible
  50 fields.
  51 </para>
  52
  53
  54 <!-- ##### STRUCT PangoLayoutIter ##### -->
  55 <para>
  56 A #PangoLayoutIter structure can be used to
  57 iterate over the visual extents of a #PangoLayout.
  58 </para>
  59 <para>
  60 The #PangoLayoutIter structure is opaque, and
  61 has no user-visible fields.
  62 </para>
  63
  64
  65 <!-- ##### FUNCTION pango_layout_new ##### -->
  66 <para>
  67
  68 </para>
  69
  70 @context:
  71 @Returns:
  72
  73
  74 <!-- ##### FUNCTION pango_layout_copy ##### -->
  75 <para>
  76
  77 </para>
  78
  79 @src:
  80 @Returns:
  81
  82
  83 <!-- ##### FUNCTION pango_layout_get_context ##### -->
  84 <para>
  85
  86 </para>
  87
  88 @layout:
  89 @Returns:
  90
  91
  92 <!-- ##### FUNCTION pango_layout_context_changed ##### -->
  93 <para>
  94
  95 </para>
  96
  97 @layout:
  98
  99
 100 <!-- ##### FUNCTION pango_layout_set_text ##### -->
 101 <para>
 102
 103 </para>
 104
 105 @layout:
 106 @text:
 107 @length:
 108
 109
 110 <!-- ##### FUNCTION pango_layout_get_text ##### -->
 111 <para>
 112
 113 </para>
 114
 115 @layout:
 116 @Returns:
 117
 118
 119 <!-- ##### FUNCTION pango_layout_set_markup ##### -->
 120 <para>
 121
 122 </para>
 123
 124 @layout:
 125 @markup:
 126 @length:
 127
 128
 129 <!-- ##### FUNCTION pango_layout_set_markup_with_accel ##### -->
 130 <para>
 131
 132 </para>
 133
 134 @layout:
 135 @markup:
 136 @length:
 137 @accel_marker:
 138 @accel_char:
 139
 140
 141 <!-- ##### FUNCTION pango_layout_set_attributes ##### -->
 142 <para>
 143
 144 </para>
 145
 146 @layout:
 147 @attrs:
 148
 149
 150 <!-- ##### FUNCTION pango_layout_get_attributes ##### -->
 151 <para>
 152
 153 </para>
 154
 155 @layout:
 156 @Returns:
 157
 158
 159 <!-- ##### FUNCTION pango_layout_set_font_description ##### -->
 160 <para>
 161
 162 </para>
 163
 164 @layout:
 165 @desc:
 166
 167
 168 <!-- ##### FUNCTION pango_layout_get_font_description ##### -->
 169 <para>
 170
 171 </para>
 172
 173 @layout:
 174 @Returns:
 175
 176
 177 <!-- ##### FUNCTION pango_layout_set_width ##### -->
 178 <para>
 179
 180 </para>
 181
 182 @layout:
 183 @width:
 184
 185
 186 <!-- ##### FUNCTION pango_layout_get_width ##### -->
 187 <para>
 188
 189 </para>
 190
 191 @layout:
 192 @Returns:
 193
 194
 195 <!-- ##### FUNCTION pango_layout_set_height ##### -->
 196 <para>
 197
 198 </para>
 199
 200 @layout:
 201 @height:
 202
 203
 204 <!-- ##### FUNCTION pango_layout_get_height ##### -->
 205 <para>
 206
 207 </para>
 208
 209 @layout:
 210 @Returns:
 211
 212
 213 <!-- ##### FUNCTION pango_layout_set_wrap ##### -->
 214 <para>
 215
 216 </para>
 217
 218 @layout:
 219 @wrap:
 220
 221
 222 <!-- ##### FUNCTION pango_layout_get_wrap ##### -->
 223 <para>
 224
 225 </para>
 226
 227 @layout:
 228 @Returns:
 229
 230
 231 <!-- ##### FUNCTION pango_layout_is_wrapped ##### -->
 232 <para>
 233
 234 </para>
 235
 236 @layout:
 237 @Returns:
 238
 239
 240 <!-- ##### ENUM PangoWrapMode ##### -->
 241 <para>
 242 A #PangoWrapMode describes how to wrap the lines of a #PangoLayout to the desired width.
 243 </para>
 244
 245 @PANGO_WRAP_WORD: wrap lines at word boundaries.
 246 @PANGO_WRAP_CHAR: wrap lines at character boundaries.
 247 @PANGO_WRAP_WORD_CHAR: wrap lines at word boundaries, but fall back to character boundaries if there is not
 248 enough space for a full word.
 249
 250 <!-- ##### MACRO PANGO_TYPE_WRAP_MODE ##### -->
 251 <para>
 252 The #GObject type for #PangoWrapMode.
 253 </para>
 254
 255
 256
 257 <!-- ##### FUNCTION pango_layout_set_ellipsize ##### -->
 258 <para>
 259
 260 </para>
 261
 262 @layout:
 263 @ellipsize:
 264
 265
 266 <!-- ##### FUNCTION pango_layout_get_ellipsize ##### -->
 267 <para>
 268
 269 </para>
 270
 271 @layout:
 272 @Returns:
 273
 274
 275 <!-- ##### FUNCTION pango_layout_is_ellipsized ##### -->
 276 <para>
 277
 278 </para>
 279
 280 @layout:
 281 @Returns:
 282
 283
 284 <!-- ##### ENUM PangoEllipsizeMode ##### -->
 285 <para>
 286
 287 </para>
 288
 289 @PANGO_ELLIPSIZE_NONE:
 290 @PANGO_ELLIPSIZE_START:
 291 @PANGO_ELLIPSIZE_MIDDLE:
 292 @PANGO_ELLIPSIZE_END:
 293
 294 <!-- ##### MACRO PANGO_TYPE_ELLIPSIZE_MODE ##### -->
 295 <para>
 296 The #GObject type for #PangoEllipsizeMode.
 297 </para>
 298
 299
 300
 301 <!-- ##### FUNCTION pango_layout_set_indent ##### -->
 302 <para>
 303
 304 </para>
 305
 306 @layout:
 307 @indent:
 308
 309
 310 <!-- ##### FUNCTION pango_layout_get_indent ##### -->
 311 <para>
 312
 313 </para>
 314
 315 @layout:
 316 @Returns:
 317
 318
 319 <!-- ##### FUNCTION pango_layout_get_spacing ##### -->
 320 <para>
 321
 322 </para>
 323
 324 @layout:
 325 @Returns:
 326
 327
 328 <!-- ##### FUNCTION pango_layout_set_spacing ##### -->
 329 <para>
 330
 331 </para>
 332
 333 @layout:
 334 @spacing:
 335
 336
 337 <!-- ##### FUNCTION pango_layout_set_justify ##### -->
 338 <para>
 339
 340 </para>
 341
 342 @layout:
 343 @justify:
 344
 345
 346 <!-- ##### FUNCTION pango_layout_get_justify ##### -->
 347 <para>
 348
 349 </para>
 350
 351 @layout:
 352 @Returns:
 353
 354
 355 <!-- ##### FUNCTION pango_layout_set_auto_dir ##### -->
 356 <para>
 357
 358 </para>
 359
 360 @layout:
 361 @auto_dir:
 362
 363
 364 <!-- ##### FUNCTION pango_layout_get_auto_dir ##### -->
 365 <para>
 366
 367 </para>
 368
 369 @layout:
 370 @Returns:
 371
 372
 373 <!-- ##### FUNCTION pango_layout_set_alignment ##### -->
 374 <para>
 375
 376 </para>
 377
 378 @layout:
 379 @alignment:
 380
 381
 382 <!-- ##### FUNCTION pango_layout_get_alignment ##### -->
 383 <para>
 384
 385 </para>
 386
 387 @layout:
 388 @Returns:
 389
 390
 391 <!-- ##### FUNCTION pango_layout_set_tabs ##### -->
 392 <para>
 393
 394 </para>
 395
 396 @layout:
 397 @tabs:
 398
 399
 400 <!-- ##### FUNCTION pango_layout_get_tabs ##### -->
 401 <para>
 402
 403 </para>
 404
 405 @layout:
 406 @Returns:
 407
 408
 409 <!-- ##### FUNCTION pango_layout_set_single_paragraph_mode ##### -->
 410 <para>
 411
 412 </para>
 413
 414 @layout:
 415 @setting:
 416
 417
 418 <!-- ##### FUNCTION pango_layout_get_single_paragraph_mode ##### -->
 419 <para>
 420
 421 </para>
 422
 423 @layout:
 424 @Returns:
 425
 426
 427 <!-- ##### ENUM PangoAlignment ##### -->
 428 <para>
 429 A #PangoAlignment describes how to align the lines of a #PangoLayout within the
 430 available space. If the #PangoLayout is set to justify
 431 using pango_layout_set_justify(), this only has effect for partial lines.
 432 </para>
 433
 434 @PANGO_ALIGN_LEFT: Put all available space on the right
 435 @PANGO_ALIGN_CENTER: Center the line within the available space
 436 @PANGO_ALIGN_RIGHT: Put all available space on the left
 437
 438 <!-- ##### MACRO PANGO_TYPE_ALIGNMENT ##### -->
 439 <para>
 440 The #GObject type for #PangoAlignment.
 441 </para>
 442
 443
 444
 445 <!-- ##### FUNCTION pango_layout_get_unknown_glyphs_count ##### -->
 446 <para>
 447
 448 </para>
 449
 450 @layout:
 451 @Returns:
 452
 453
 454 <!-- ##### FUNCTION pango_layout_get_log_attrs ##### -->
 455 <para>
 456
 457 </para>
 458
 459 @layout:
 460 @attrs:
 461 @n_attrs:
 462
 463
 464 <!-- ##### FUNCTION pango_layout_index_to_pos ##### -->
 465 <para>
 466
 467 </para>
 468
 469 @layout:
 470 @index_:
 471 @pos:
 472
 473
 474 <!-- ##### FUNCTION pango_layout_index_to_line_x ##### -->
 475 <para>
 476
 477 </para>
 478
 479 @layout:
 480 @index_:
 481 @trailing:
 482 @line:
 483 @x_pos:
 484
 485
 486 <!-- ##### FUNCTION pango_layout_xy_to_index ##### -->
 487 <para>
 488
 489 </para>
 490
 491 @layout:
 492 @x:
 493 @y:
 494 @index_:
 495 @trailing:
 496 @Returns:
 497
 498
 499 <!-- ##### FUNCTION pango_layout_get_cursor_pos ##### -->
 500 <para>
 501
 502 </para>
 503
 504 @layout:
 505 @index_:
 506 @strong_pos:
 507 @weak_pos:
 508
 509
 510 <!-- ##### FUNCTION pango_layout_move_cursor_visually ##### -->
 511 <para>
 512
 513 </para>
 514
 515 @layout:
 516 @strong:
 517 @old_index:
 518 @old_trailing:
 519 @direction:
 520 @new_index:
 521 @new_trailing:
 522
 523
 524 <!-- ##### FUNCTION pango_layout_get_extents ##### -->
 525 <para>
 526
 527 </para>
 528
 529 @layout:
 530 @ink_rect:
 531 @logical_rect:
 532
 533
 534 <!-- ##### FUNCTION pango_layout_get_pixel_extents ##### -->
 535 <para>
 536
 537 </para>
 538
 539 @layout:
 540 @ink_rect:
 541 @logical_rect:
 542
 543
 544 <!-- ##### FUNCTION pango_layout_get_size ##### -->
 545 <para>
 546
 547 </para>
 548
 549 @layout:
 550 @width:
 551 @height:
 552
 553
 554 <!-- ##### FUNCTION pango_layout_get_pixel_size ##### -->
 555 <para>
 556
 557 </para>
 558
 559 @layout:
 560 @width:
 561 @height:
 562
 563
 564 <!-- ##### FUNCTION pango_layout_get_baseline ##### -->
 565 <para>
 566
 567 </para>
 568
 569 @layout:
 570 @Returns:
 571
 572
 573 <!-- ##### FUNCTION pango_layout_get_line_count ##### -->
 574 <para>
 575
 576 </para>
 577
 578 @layout:
 579 @Returns:
 580
 581
 582 <!-- ##### FUNCTION pango_layout_get_line ##### -->
 583 <para>
 584
 585 </para>
 586
 587 @layout:
 588 @line:
 589 @Returns:
 590
 591
 592 <!-- ##### FUNCTION pango_layout_get_line_readonly ##### -->
 593 <para>
 594
 595 </para>
 596
 597 @layout:
 598 @line:
 599 @Returns:
 600
 601
 602 <!-- ##### FUNCTION pango_layout_get_lines ##### -->
 603 <para>
 604
 605 </para>
 606
 607 @layout:
 608 @Returns:
 609
 610
 611 <!-- ##### FUNCTION pango_layout_get_lines_readonly ##### -->
 612 <para>
 613
 614 </para>
 615
 616 @layout:
 617 @Returns:
 618
 619
 620 <!-- ##### FUNCTION pango_layout_get_iter ##### -->
 621 <para>
 622
 623 </para>
 624
 625 @layout:
 626 @Returns:
 627
 628
 629 <!-- ##### FUNCTION pango_layout_iter_copy ##### -->
 630 <para>
 631
 632 </para>
 633
 634 @iter:
 635 @Returns:
 636
 637
 638 <!-- ##### FUNCTION pango_layout_iter_free ##### -->
 639 <para>
 640
 641 </para>
 642
 643 @iter:
 644
 645
 646 <!-- ##### FUNCTION pango_layout_iter_next_run ##### -->
 647 <para>
 648
 649 </para>
 650
 651 @iter:
 652 @Returns:
 653
 654
 655 <!-- ##### FUNCTION pango_layout_iter_next_char ##### -->
 656 <para>
 657
 658 </para>
 659
 660 @iter:
 661 @Returns:
 662
 663
 664 <!-- ##### FUNCTION pango_layout_iter_next_cluster ##### -->
 665 <para>
 666
 667 </para>
 668
 669 @iter:
 670 @Returns:
 671
 672
 673 <!-- ##### FUNCTION pango_layout_iter_next_line ##### -->
 674 <para>
 675
 676 </para>
 677
 678 @iter:
 679 @Returns:
 680
 681
 682 <!-- ##### FUNCTION pango_layout_iter_at_last_line ##### -->
 683 <para>
 684
 685 </para>
 686
 687 @iter:
 688 @Returns:
 689
 690
 691 <!-- ##### FUNCTION pango_layout_iter_get_index ##### -->
 692 <para>
 693
 694 </para>
 695
 696 @iter:
 697 @Returns:
 698
 699
 700 <!-- ##### FUNCTION pango_layout_iter_get_baseline ##### -->
 701 <para>
 702
 703 </para>
 704
 705 @iter:
 706 @Returns:
 707
 708
 709 <!-- ##### FUNCTION pango_layout_iter_get_run ##### -->
 710 <para>
 711
 712 </para>
 713
 714 @iter:
 715 @Returns:
 716
 717
 718 <!-- ##### FUNCTION pango_layout_iter_get_run_readonly ##### -->
 719 <para>
 720
 721 </para>
 722
 723 @iter:
 724 @Returns:
 725
 726
 727 <!-- ##### FUNCTION pango_layout_iter_get_line ##### -->
 728 <para>
 729
 730 </para>
 731
 732 @iter:
 733 @Returns:
 734
 735
 736 <!-- ##### FUNCTION pango_layout_iter_get_line_readonly ##### -->
 737 <para>
 738
 739 </para>
 740
 741 @iter:
 742 @Returns:
 743
 744
 745 <!-- ##### FUNCTION pango_layout_iter_get_layout ##### -->
 746 <para>
 747
 748 </para>
 749
 750 @iter:
 751 @Returns:
 752
 753
 754 <!-- ##### FUNCTION pango_layout_iter_get_char_extents ##### -->
 755 <para>
 756
 757 </para>
 758
 759 @iter:
 760 @logical_rect:
 761
 762
 763 <!-- ##### FUNCTION pango_layout_iter_get_cluster_extents ##### -->
 764 <para>
 765
 766 </para>
 767
 768 @iter:
 769 @ink_rect:
 770 @logical_rect:
 771
 772
 773 <!-- ##### FUNCTION pango_layout_iter_get_run_extents ##### -->
 774 <para>
 775
 776 </para>
 777
 778 @iter:
 779 @ink_rect:
 780 @logical_rect:
 781
 782
 783 <!-- ##### FUNCTION pango_layout_iter_get_line_yrange ##### -->
 784 <para>
 785
 786 </para>
 787
 788 @iter:
 789 @y0_:
 790 @y1_:
 791
 792
 793 <!-- ##### FUNCTION pango_layout_iter_get_line_extents ##### -->
 794 <para>
 795
 796 </para>
 797
 798 @iter:
 799 @ink_rect:
 800 @logical_rect:
 801
 802
 803 <!-- ##### FUNCTION pango_layout_iter_get_layout_extents ##### -->
 804 <para>
 805
 806 </para>
 807
 808 @iter:
 809 @ink_rect:
 810 @logical_rect:
 811
 812
 813 <!-- ##### STRUCT PangoLayoutLine ##### -->
 814 <para>
 815 The #PangoLayoutLine structure represents one of the lines resulting
 816 from laying out a paragraph via #PangoLayout. #PangoLayoutLine
 817 structures are obtained by calling pango_layout_get_line() and
 818 are only valid until the text, attributes, or settings of the
 819 parent #PangoLayout are modified.
 820 </para>
 821 <para>
 822 Routines for rendering PangoLayout objects are provided in
 823 code specific to each rendering system.
 824 </para>
 825
 826 @layout: the parent layout for this line
 827 @start_index: the start of the line as byte index into @layout->text
 828 @length: the length of the line in bytes
 829 @runs: a list containing the runs of the line in visual order
 830 @is_paragraph_start: %TRUE if this is the first line of the paragraph
 831 @resolved_dir: the resolved #PangoDirection of the line
 832
 833 <!-- ##### TYPEDEF PangoLayoutRun ##### -->
 834 <para>
 835 The #PangoLayoutRun structure represents a single run within
 836 a #PangoLayoutLine; it is simply an alternate name for
 837 #PangoGlyphItem.
 838 See the #PangoGlyphItem docs for details on the fields.
 839 </para>
 840
 841
 842 <!-- ##### FUNCTION pango_layout_line_ref ##### -->
 843 <para>
 844
 845 </para>
 846
 847 @line:
 848 @Returns:
 849
 850
 851 <!-- ##### FUNCTION pango_layout_line_unref ##### -->
 852 <para>
 853
 854 </para>
 855
 856 @line:
 857
 858
 859 <!-- ##### FUNCTION pango_layout_line_get_extents ##### -->
 860 <para>
 861
 862 </para>
 863
 864 @line:
 865 @ink_rect:
 866 @logical_rect:
 867
 868
 869 <!-- ##### FUNCTION pango_layout_line_get_pixel_extents ##### -->
 870 <para>
 871
 872 </para>
 873
 874 @layout_line:
 875 @ink_rect:
 876 @logical_rect:
 877
 878
 879 <!-- ##### FUNCTION pango_layout_line_index_to_x ##### -->
 880 <para>
 881
 882 </para>
 883
 884 @line:
 885 @index_:
 886 @trailing:
 887 @x_pos:
 888
 889
 890 <!-- ##### FUNCTION pango_layout_line_x_to_index ##### -->
 891 <para>
 892
 893 </para>
 894
 895 @line:
 896 @x_pos:
 897 @index_:
 898 @trailing:
 899 @Returns:
 900
 901
 902 <!-- ##### FUNCTION pango_layout_line_get_x_ranges ##### -->
 903 <para>
 904
 905 </para>
 906
 907 @line:
 908 @start_index:
 909 @end_index:
 910 @ranges:
 911 @n_ranges:
 912
 913