1/* 2 * Copyright 2013 Haiku Inc. All rights reserved. 3 * Distributed under the terms of the MIT License. 4 * 5 * Authors: 6 * John Scipione, jscipione@gmail.com 7 * 8 * Corresponds to: 9 * headers/os/interface/Font.h hrev45178 10 * src/kits/interface/Font.cpp hrev45178 11 */ 12 13 14/*! 15 \file Font.h 16 \ingroup interface 17 \ingroup libbe 18 \brief BFont class definition, unicode_block class definition, and 19 font-related struct and enum definitions. 20*/ 21 22 23/*! 24 \var B_CHAR_SPACING 25 26 Position each character without adjustment. Best mode for printing. 27*/ 28 29 30/*! 31 \var B_STRING_SPACING 32 33 Optimizes the position of each character within it's space. Collisions 34 are unlikely but characters may touch each other. Best mode to use when 35 the screen needs to match what appears on the printed page. 36*/ 37 38 39/*! 40 \var B_BITMAP_SPACING 41 42 The widths of the characters are chosen so that they never collide and 43 rarely touch. Best mode for drawing small amounts of text. 44*/ 45 46 47/*! 48 \var B_FIXED_SPACING 49 50 Positions characters at a constant width. Best mode for fixed-width fonts. 51*/ 52 53 54/*! 55 \enum font_direction 56 \ingroup interface 57 58 Determines the direction of the text rendered by the font, 59 left-to-right or right-to-left. 60*/ 61 62 63/*! 64 \var font_direction B_FONT_LEFT_TO_RIGHT 65 66 Left to right. 67*/ 68 69/*! 70 \var font_direction B_FONT_RIGHT_TO_LEFT 71 72 Right to left. 73*/ 74 75 76/*! 77 \var B_DISABLE_ANTIALIASING 78 79 Disable antialiasing. Used by BFont::Flags() and BFont::SetFlags(). 80*/ 81 82 83/*! 84 \var B_FORCE_ANTIALIASING 85 86 Force antialiasing. Used by BFont::Flags() and BFont::SetFlags(). 87*/ 88 89 90/*! 91 \var B_TRUNCATE_END 92 93 Truncate from the end of the string. 94*/ 95 96 97/*! 98 \var B_TRUNCATE_BEGINNING 99 100 Truncate from the beginning of the string. 101*/ 102 103 104/*! 105 \var B_TRUNCATE_MIDDLE 106 107 Truncate from the middle of the string. 108*/ 109 110 111/*! 112 \var B_TRUNCATE_SMART 113 114 Truncate while keeping each string unique. 115*/ 116 117 118/*! 119 \var B_UNICODE_UTF8 120 121 UTF-8 font encoding. 122*/ 123 124 125/*! 126 \var B_ISO_8859_1 127 128 ISO 8859-1 aka Latin 1 "Western European" font encoding. 129*/ 130 131 132/*! 133 \var B_ISO_8859_2 134 135 ISO 8859-2 aka Latin 2 "Eastern European" font encoding. 136*/ 137 138 139/*! 140 \var B_ISO_8859_3 141 142 ISO 8859-3 aka Latin 3 "South European" font encoding. 143*/ 144 145 146/*! 147 \var B_ISO_8859_4 148 149 ISO 8859-4 aka Latin 4 "Northern European" font encoding. 150*/ 151 152 153/*! 154 \var B_ISO_8859_5 155 156 ISO 8859-5 "Latin/Cyrillic" font encoding. 157*/ 158 159 160/*! 161 \var B_ISO_8859_6 162 163 ISO 8859-6 "Latin/Arabic" font encoding. 164*/ 165 166 167/*! 168 \var B_ISO_8859_7 169 170 ISO 8859-7 "Latin/Greek" font encoding. 171*/ 172 173 174/*! 175 \var B_ISO_8859_8 176 177 ISO 8859-8 "Latin/Hebrew" font encoding. 178*/ 179 180 181/*! 182 \var B_ISO_8859_9 183 184 ISO 8859-9 aka Latin 5 "Latin/Turkish" font encoding. 185*/ 186 187 188/*! 189 \var B_ISO_8859_10 190 191 ISO 8859-10 aka Latin 6 "Nordic" font encoding. 192*/ 193 194 195/*! 196 \var B_MACINTOSH_ROMAN 197 198 Macintosh Roman font encoding. 199*/ 200 201 202/*! 203 \var B_HAS_TUNED_FONT 204 205 Flags for get_font_family() and get_font_style() 206*/ 207 208 209/*! 210 \var B_IS_FIXED 211 212 flags for get_font_family() and get_font_style() 213*/ 214 215 216/*! 217 \var B_ITALIC_FACE 218 219 Italic font face flag. 220*/ 221 222 223/*! 224 \var B_UNDERSCORE_FACE 225 226 Underscore font face flag. 227*/ 228 229 230/*! 231 \var B_NEGATIVE_FACE 232 233 Negative font face flag. 234*/ 235 236 237/*! 238 \var B_OUTLINED_FACE 239 240 Outline font face flag. 241*/ 242 243 244/*! 245 \var B_STRIKEOUT_FACE 246 247 Strikeout font face flag. 248*/ 249 250 251/*! 252 \var B_BOLD_FACE 253 254 Bold font face flag. 255*/ 256 257 258/*! 259 \var B_REGULAR_FACE 260 261 Regular font face flag. 262*/ 263 264 265/*! 266 \var B_CONDENSED_FACE 267 268 Condensed font face flag. Not in BeOS 5. 269*/ 270 271 272/*! 273 \var B_LIGHT_FACE 274 275 Light font face flag. Not in BeOS 5. 276*/ 277 278 279/*! 280 \var B_HEAVY_FACE 281 282 Heavy font face flag. Not in BeOS 5. 283*/ 284 285 286/*! 287 \enum font_metric_mode 288 289 Font metric mode, screen or printing. 290*/ 291 292/*! 293 \var font_metric_mode B_SCREEN_METRIC 294 295 Screen font metric mode. 296*/ 297 298/*! 299 \var font_metric_mode B_PRINTING_METRIC 300 301 Printing font metric mode. 302*/ 303 304 305/*! 306 \enum font_file_format 307 \ingroup interface 308 309 Font file format, TrueType™ or PostScript™ Type1. 310 311 \see BFont::FileFormat() 312*/ 313 314/*! 315 \var font_file_format B_TRUETYPE_WINDOWS 316 317 TrueType™ font file format. 318*/ 319 320/*! 321 \var font_file_format B_POSTSCRIPT_TYPE1_WINDOWS 322 323 PostScript™ Type1 font file format. 324*/ 325 326 327/*! 328 \class unicode_block 329 \ingroup interface 330 \ingroup libbe 331 \brief Describes the blocks of Unicode characters supported by a font. 332 333 \see BFont::Blocks() 334*/ 335 336 337/*! 338 \fn unicode_block::unicode_block() 339 \brief Construct a \c unicode_block and set block data to 0. 340 341 You must initialize the block data before before using this object. 342*/ 343 344 345/*! 346 \fn unicode_block::unicode_block(uint64 block2, uint64 block1) 347 \brief Construct a \c unicode_block object and initialize it with the 348 supplied Unicode block range. 349 350 \param block2 End block. 351 \param block1 Begin block. 352*/ 353 354 355/*! 356 \fn bool unicode_block::Includes(const unicode_block& block) const 357 \brief Determines if \a block is a subset of the \c unicode_block object. 358 359 \param block The Unicode block to check. 360 361 \returns Whether or not \a block is a subset of the \c unicode_block 362 object. 363 \retval true \a block is a subset of the current \c unicode_block. 364 \retval false \a block is NOT a subset of the current \c unicode_block. 365*/ 366 367 368/*! 369 \name Assignment operators 370*/ 371 372 373//! @{ 374 375 376/*! 377 \fn unicode_block unicode_block::operator&(const unicode_block& block) const 378 \brief Creates a new \c unicode_block object that is the intersection of 379 \a block and the \c unicode_block object. 380 381 \param block The Unicode block to intersect with. 382 383 \returns The intersection of \a block and the \c unicode_block object. 384*/ 385 386 387/*! 388 \fn unicode_block unicode_block::operator|(const unicode_block& block) const 389 \brief Creates a new \c unicode_block object that is the union of \a block 390 and the \c unicode_block object. 391 392 \param block The Unicode block to form a union with. 393 394 \returns The union of \a block and the \c unicode_block object. 395*/ 396 397 398/*! 399 \fn unicode_block& unicode_block::operator=(const unicode_block& block) 400 \brief Copies \a block data into the left-hand side object. 401 402 \param block The unicode block to copy from. 403 404 \returns A copy of \a block. 405*/ 406 407 408//! @} 409 410 411/*! 412 \name Comparison operators 413*/ 414 415 416//! @{ 417 418 419/*! 420 \fn bool unicode_block::operator==(const unicode_block& block) const 421 \brief Determines if the block object are exactly equal. 422 423 \param block The unicode block to compare against. 424 425 \returns \c true if the block object are exactly equal, \c false 426 otherwise. 427*/ 428 429 430/*! 431 \fn bool unicode_block::operator!=(const unicode_block& block) const 432 \brief Determines if the block object are not equal. 433 434 \param block The unicode block to compare against. 435 436 \returns \c true if the block object are NOT equal, \c false 437 if the block objects are exactly equal. 438*/ 439 440 441//! @} 442 443 444/*! 445 \struct edge_info 446 \ingroup interface 447 \ingroup libbe 448 \brief The distance that a character outline is inset from its escapement 449 boundaries. 450 451 Edge values, like escapements, need to be multiplied by the font size to 452 get the correct value for the font. 453 454 \see BFont::GetEdges() 455*/ 456 457 458/*! 459 \var edge_info::left 460 461 The distance that the character outline is inset from the left 462 escapement boundary. 463*/ 464 465 466/*! 467 \var edge_info::right 468 469 The distance that the character outline is inset from the right 470 escapement boundary. 471*/ 472 473 474/*! 475 \struct font_height 476 \ingroup interface 477 \ingroup libbe 478 \brief The amount of vertical space surrounding a character. 479 480 \see BFont::GetHeight() 481*/ 482 483 484/*! 485 \var font_height::ascent 486 487 The distance characters can ascend above the baseline. 488*/ 489 490 491/*! 492 \var font_height::descent 493 494 The distance characters can descend below the baseline. 495*/ 496 497 498/*! 499 \var font_height::leading 500 501 The distance between lines, descent above to ascent below. 502*/ 503 504 505/*! 506 \struct escapement_delta 507 \ingroup interface 508 \ingroup libbe 509 \brief The amount of horizontal space surrounding a character. 510 511 Escapements need to be multiplied by the font size to get the correct 512 value for the font. 513 514 \see BFont::GetEscapements() 515*/ 516 517 518/*! 519 \var escapement_delta::nonspace 520 521 The amount of space surrounding a character with a visible glyph. 522*/ 523 524 525/*! 526 \var escapement_delta::space 527 528 The amount of space surrounding a whitespace character, for example 529 \c B_TAB and \c B_SPACE. 530*/ 531 532 533/*! 534 \struct font_cache_info 535 \ingroup interface 536 \ingroup libbe 537 \brief Font cache parameters. 538*/ 539 540 541/*! 542 \var font_cache_info::sheared_font_penalty 543 544 Sheared font penalty. 545*/ 546 547 548/*! 549 \var font_cache_info::rotated_font_penalty 550 551 Rotated font penalty. 552*/ 553 554 555/*! 556 \var font_cache_info::oversize_threshold 557 558 Oversize threshold. 559*/ 560 561 562/*! 563 \var font_cache_info::oversize_penalty 564 565 Oversize penalty. 566*/ 567 568/*! 569 \var font_cache_info::cache_size 570 571 Cache size. 572*/ 573 574 575/*! 576 \var font_cache_info::spacing_size_threshold 577 578 Spacing size threshold. 579*/ 580 581 582/*! 583 \struct tuned_font_info 584 \ingroup interface 585 \ingroup libbe 586 \brief Tuning information of fonts used to make it look better when 587 displayed on-screen. 588 589 \see BFont::GetTunedInfo() 590 \see BFont::CountTuned() 591*/ 592 593 594/*! 595 \var tuned_font_info::size 596 597 Font size. 598*/ 599 600 601/*! 602 \var tuned_font_info::shear 603 604 Font shear. 605*/ 606 607 608/*! 609 \var tuned_font_info::rotation 610 611 Font rotation. 612*/ 613 614 615/*! 616 \var tuned_font_info::flags 617 618 Font flags. 619*/ 620 621/*! 622 \var tuned_font_info::face 623 624 Font face. 625*/ 626 627 628/*! 629 \fn int32 count_font_families() 630 \brief Gets the number of installed font families 631 632 \return The number of installed font families 633*/ 634 635 636/*! 637 \fn int32 count_font_styles(font_family family) 638 \brief Gets the number of styles available for a font family. 639 640 \return The number of styles available for a font family. 641*/ 642 643 644/*! 645 \fn status_t get_font_family(int32 index, font_family *_name, 646 uint32 *_flags) 647 \brief Retrieves the family name at the specified index. 648 649 \param index Unique font identifier code. 650 \param _name font_family String to receive the name of the family. 651 \param _flags if non-<tt>NULL</tt>, the values of the flags \c IS_FIXED 652 and \c B_HAS_TUNED_FONT are returned. 653 654 \return A status code, \c B_OK on success or an error code. 655 \retval B_BAD_VALUE \a _name is \c NULL. 656 \retval B_ERROR \a index does not correspond to a font family. 657*/ 658 659 660/*! 661 \fn status_t get_font_style(font_family family, int32 index, 662 font_style *_name, uint32 *_flags) 663 \brief Retrieves the family name at the specified index. 664 665 \param family The font family. 666 \param index Unique font identifier code. 667 \param _name string to receive the name of the family. 668 \param _flags if non-<tt>NULL</tt>, the values of the flags \c IS_FIXED 669 and \c B_HAS_TUNED_FONT are returned 670 671 \return A status code, \c B_OK on success or an error code. 672 \retval B_ERROR \a index does not correspond to a font style. 673*/ 674 675 676/*! 677 \fn status_t get_font_style(font_family family, int32 index, 678 font_style *_name, uint16 *_face, uint32 *_flags) 679 \brief Retrieves the family name at the specified index. 680 681 The face value returned by this function is not very reliable. At the same 682 time, the value returned should be fairly reliable, returning the proper 683 flag for 90%-99% of font names. 684 685 \param family The font family. 686 \param index Unique font identifier code. 687 \param _name String to receive the name of the family. 688 \param _face recipient of font face value, such as \c B_REGULAR_FACE. 689 \param _flags if non-<tt>NULL</tt>, the values of the flags \c IS_FIXED 690 and \c B_HAS_TUNED_FONT are returned. 691 692 \return A status code, \c B_OK on success or an error code. 693 \retval B_ERROR \a index does not correspond to a font style. 694*/ 695 696 697/*! 698 \fn bool update_font_families(bool checkOnly) 699 \brief Updates the font families list. 700 701 \param checkOnly Parameter is ignored. 702 703 \return \c true if the font list has changed, \c false if not. 704*/ 705 706 707/*! 708 \class BFont 709 \ingroup interface 710 \ingroup libbe 711 \brief Represents a typeface including it's family, style and size. 712 713 The Interface Kit provides three prebuilt BFont objects which can be used 714 but not modified. 715 - \c const BFont* \c be_plain_font A plain font used by many controls. 716 - \c const BFont* \c be_bold_font A bold font used by titles. 717 - \c const BFont* \c be_fixed_font A fixed-width font. 718 719 A BFont object does nothing on it's own but is used in combination with 720 a view or control. Here is an example of creating a BFont object from a 721 system font and assigning it to a view: 722 723\code 724 BFont font(be_plain_font); 725 font.SetSize(12.0); 726 font.SetEncoding(B_ISO_8859_1); 727 view->SetFont(&font); 728\endcode 729 730 You may also create a BFont object from a view, modify it and reassign it 731 back to the view like this: 732 733\code 734 BFont font; 735 view->GetFont(&font); 736 font.SetFace(B_ITALIC_FACE); 737 font.SetSpacing(B_CHAR_SPACING); 738 myView->SetFont(&font); 739\endcode 740 741 You can change the way a font renders with the SetFamilyAndStyle(), 742 SetFamilyAndFace(), SetSize(), SetShear(), SetRotation(), 743 SetFalseBoldWidth(), SetSpacing(), SetEncoding(), SetFace(), and 744 SetFlags() methods. 745 746 More information about the space taken up by a font can be determined 747 by querying a BFont object using the following methods: 748 StringWidth(), GetStringWidths() GetEscapements(), GetEdges(), 749 GetHeight(), BoundingBox() GetBoundingBoxesAsGlyphs(), 750 GetBoundingBoxesAsString(), and GetBoundingBoxesForStrings(). 751 752 You can also perform intelligent string truncation with the 753 TruncateString() and GetTruncatedStrings() methods. 754*/ 755 756 757/*! 758 \fn BFont::BFont() 759 \brief Creates a BFont object initialized to \c be_plain_font. 760 761 \see BView::GetFont() 762*/ 763 764 765/*! 766 \fn BFont::BFont(const BFont &font) 767 \brief Creates and initializes a BFont object from another BFont object. 768 769 \param font The BFont object to initialize from. 770*/ 771 772 773/*! 774 \fn BFont::BFont(const BFont *font) 775 \brief Creates and initializes a BFont object from a pointer to a BFont 776 object. 777 778 \param font The pointer to a BFont object to initialize from. 779*/ 780 781 782/*! 783 \fn BFont::BFont(const BFont *font) 784 \brief Creates and initializes a BFont object from a pointer to a BFont 785 object. 786 787 \param font The pointer to a BFont object to initialize from. 788*/ 789 790 791/*! 792 \fn status_t BFont::SetFamilyAndStyle(const font_family family, 793 const font_style style) 794 \brief Sets the font's family and style all at once. 795 796 \param family Font family to set. 797 \param style Font style to set. 798 799 \returns A status code, \c B_OK on success or an error code. 800 \retval B_BAD_VALUE \a family is \c NULL and \a style is \c NULL. 801 \retval B_NAME_NOT_FOUND Family or style do not exist. 802*/ 803 804 805/*! 806 \fn void BFont::SetFamilyAndStyle(uint32 code) 807 \brief Sets the font's family and style from a font identifier. 808 809 \param code Unique font identifier obtained from the server. 810*/ 811 812 813/*! 814 \fn status_t BFont::SetFamilyAndFace(const font_family family, uint16 face) 815 \brief Sets the font's family and face all at once. 816 817 \param family Font family to set. 818 \param face Font face to set. 819 820 \note To comply with the BeBook, this function will only set valid values, 821 i.e. passing a nonexistent family will cause only the face to be set. 822 Additionally, if a particular face does not exist in a family, the 823 closest match will be chosen. 824 825 \returns A status code, \c B_OK on success or an error code. 826 \retval B_ERROR Family does not exists or face has an invalid value. 827*/ 828 829 830/*! 831 \fn void BFont::SetSize(float size) 832 \brief Sets the font size. 833 834 \param size The point size to set the font to. 835*/ 836 837 838/*! 839 \fn void BFont::SetShear(float shear) 840 \brief Sets the angle in degrees relative to the baseline. 841 842 The default shear is 90.0° measured counterclockwise. The shear 843 range is from 45.0° to 135.0°. 844 845 \param shear The shear in degrees to set the font to. 846*/ 847 848 849/*! 850 \fn void BFont::SetRotation(float rotation) 851 \brief Sets the font rotation from the baseline in degrees. 852 853 The default baseline is 0° and rotates counterclockwise. Rotation is not 854 supported by BTextView. 855 856 \param rotation The rotation in degrees to set the font to. 857*/ 858 859 860/*! 861 \fn void BFont::SetFalseBoldWidth(float width) 862 \brief Sets the false bold width. 863 864 \param width The false bold width to set. 865*/ 866 867 868/*! 869 \fn void BFont::SetSpacing(uint8 spacing) 870 \brief Sets how characters are horizontally spaced relative to each other. 871 872 - \c B_CHAR_SPACING Position each character without adjustment. Best mode 873 for printing. Characters may collide or overlap at small font sizes. 874 - \c B_STRING_SPACING Optimizes the position of each character within it's 875 space. Collisions are unlikely but characters may touch each other. 876 Best mode to use when the screen needs to match what appears on the 877 printed page. Adding new characters requires the entire string to 878 be redrawn. 879 - \c B_BITMAP_SPACING The widths of the characters are chosen so that they 880 never collide and rarely touch. Best mode for drawing small amounts 881 of text. Character widths are integral values. Spacing on screen will 882 not match spacing used by \c B_CHAR_SPACING mode for printing. 883 - \c B_FIXED_SPACING Positions characters at a constant width. Must be 884 used with fixed-width fonts otherwise \c B_CHAR_SPACING mode is used. 885 All characters have an identical integral escapement. 886 887 \c B_STRING_SPACING and \c B_BITMAP_SPACING modes are relevant only for 888 font sizes from 7.0pt to 18.0pt, above and below that range 889 \c B_CHAR_SPACING produces nicer results. \c B_CHAR_SPACING is also always 890 used for rotated or sheared text and when antialiasing is disabled. 891 892 \param spacing The spacing mode to set. 893 894 \see BView::DrawString() 895 \see GetEscapements() 896*/ 897 898 899/*! 900 \fn void BFont::SetEncoding(uint8 encoding) 901 \brief Sets the character encoding of the font for example 902 \c B_UNICODE_UTF8 or \c B_ISO_8859_1. 903 904 The following character encodings are supported: 905 - \c B_UNICODE_UTF8 906 - \c B_ISO_8859_1 aka Latin 1 aka "Western European". 907 - \c B_ISO_8859_2 aka Latin 2 aka "Eastern European". 908 - \c B_ISO_8859_3 aka Latin 3 aka "South European". 909 - \c B_ISO_8859_4 aka Latin 4 aka "Northern European". 910 - \c B_ISO_8859_5 aka "Latin/Cyrillic". 911 - \c B_ISO_8859_6 aka "Latin/Arabic". 912 - \c B_ISO_8859_7 aka "Latin/Greek". 913 - \c B_ISO_8859_8 aka "Latin/Hebrew". 914 - \c B_ISO_8859_9 aka Latin 5 aka "Latin/Turkish". 915 - \c B_ISO_8859_10 aka Latin 6 aka "Nordic". 916 - \c B_MACINTOSH_ROMAN 917 918 \param encoding The character encoding to set the font to. 919*/ 920 921 922/*! 923 \fn void BFont::SetFace(uint16 face) 924 \brief Sets the font face according to the flags set by \a face. 925 926 The following font face flags are supported: 927 - \c B_ITALIC_FACE Characters are slanted to the right. 928 - \c B_UNDERSCORE_FACE Characters are underlined. 929 - \c B_NEGATIVE_FACE High and low colors are reversed when drawing 930 characters. 931 - \c B_OUTLINED_FACE Characters are drawn hollowed out. 932 - \c B_STRIKEOUT_FACE A horizontal line is drawn through their middle. 933 - \c B_BOLD_FACE Characters are bold. 934 - \c B_REGULAR_FACE Characters are drawn normally. 935 - \c B_CONDENSED_FACE Characters are drawn condensed. Not in BeOS 5. 936 - \c B_LIGHT_FACE Characters are drawn thiner than normal. Not in BeOS 5. 937 - \c B_HEAVY_FACE Characters are drawn heavier than normal. Not in BeOS 5. 938 939 \param face The bitmap of font face flags to set. 940*/ 941 942 943/*! 944 \fn void BFont::SetFlags(uint32 flags) 945 \brief Sets font flags controlling antialiasing. 946 947 The following flags are supported: 948 - \c B_DISABLE_ANTIALIASING Disable antialiasing. 949 - \c B_FORCE_ANTIALIASING Force antialiasing. 950 951 \param flags The bitmap of flags to set. 952*/ 953 954 955/*! 956 \fn void BFont::GetFamilyAndStyle(font_family *family, 957 font_style *style) const 958 \brief Writes out the name of the font family and/or font style. 959 960 This method may be called with either \a family or \a style set to 961 \c NULL in order to get one or the other. 962 963 \param family A font_family pointer to be filled out. 964 \param style A font_style pointer to be filled out. 965*/ 966 967 968/*! 969 \fn uint32 BFont::FamilyAndStyle() const 970 \brief Gets the code of the font family and style combination. 971 972 \returns The family and style combination encoded as a unique integer. 973 974 \see SetFamilyAndStyle(uint32 code) 975*/ 976 977 978/*! 979 \fn float BFont::Size() const 980 \brief Gets the font size. 981 982 \returns The font size in points. 983 984 \see SetSize() 985*/ 986 987 988/*! 989 \fn float BFont::Shear() const 990 \brief Gets the font shear. 991 992 \returns The font shear as an angle from 45.0° to 135.0°. 993 994 \see SetShear() 995*/ 996 997 998/*! 999 \fn float BFont::Rotation() const 1000 \brief Gets the font rotation. 1001 1002 \returns The font rotation as an angle in degrees. 1003 1004 \see SetRotation() 1005*/ 1006 1007 1008/*! 1009 \fn float BFont::FalseBoldWidth() const 1010 \brief Gets the width of the font as if it were bold. 1011 1012 \returns The font width of the bold font variety. 1013 1014 \see SetFalseBoldWidth() 1015*/ 1016 1017 1018/*! 1019 \fn uint8 BFont::Spacing() const 1020 \brief Gets the spacing constant. 1021 1022 \returns The spacing constant. 1023 1024 \see SetSpacing() 1025*/ 1026 1027 1028/*! 1029 \fn uint8 BFont::Encoding() const 1030 \brief Gets the character encoding constant. 1031 1032 \returns The character encoding constant. 1033 1034 \see SetEncoding() 1035*/ 1036 1037 1038/*! 1039 \fn uint16 BFont::Face() const 1040 \brief Gets the font face flags bitmap. 1041 1042 \returns The font face flags bitmap. 1043 1044 \see SetFace() 1045*/ 1046 1047 1048/*! 1049 \fn uint32 BFont::Flags() const 1050 \brief Gets the antialiasing flags. 1051 1052 \returns The antialiasing flags. 1053 1054 \see SetFlags() 1055*/ 1056 1057 1058/*! 1059 \fn font_direction BFont::Direction() const 1060 \brief Gets the font direction, left-to-right or right-to left. 1061 1062 \returns The font direction. 1063*/ 1064 1065 1066/*! 1067 \fn bool BFont::IsFixed() const 1068 \brief Gets whether or not the font is fixed width. 1069 1070 \returns \c true if the font is fixed width, \c false otherwise. 1071*/ 1072 1073 1074/*! 1075 \fn bool BFont::IsFullAndHalfFixed() const 1076 \brief Returns whether or not the font is fixed-width and contains both 1077 full and half-width characters. 1078 1079 \note This was left unimplemented as of R5. It is a way to work with both 1080 Kanji and Roman characters in the same fixed-width font. 1081*/ 1082 1083 1084/*! 1085 \fn BRect BFont::BoundingBox() const 1086 \brief Gets a BRect that encloses the font text. 1087 1088 \returns A BRect that encloses the font text. 1089*/ 1090 1091 1092/*! 1093 \fn unicode_block BFont::Blocks() const 1094 \brief Gets a \c unicode_block object that identifies the Unicode blocks 1095 supported by this font face and family. 1096 1097 \attention Currently unimplemented, returns an empty \a unicode_block 1098 object. 1099 1100 \returns A \c unicode_block object containing supported Unicode blocks. 1101*/ 1102 1103 1104/*! 1105 \fn font_file_format BFont::FileFormat() const 1106 \brief Gets whether the font is a TrueType™ or PostScript™ Type1 font. 1107 1108 \returns A \c font_file_format struct containing the font file format. 1109*/ 1110 1111 1112/*! 1113 \fn int32 BFont::CountTuned() const 1114 \brief Gets the number of tuned fonts for the font family and style. 1115 1116 \returns The number of tuned fonts. 1117*/ 1118 1119 1120/*! 1121 \fn void BFont::GetTunedInfo(int32 index, tuned_font_info *info) const 1122 \brief Writes information about the tuned font at \a index into \a info. 1123 1124 The index begins at 0 and counts tuned fonts for current font family and 1125 style only. 1126 1127 \param index The index of desired tuned font. 1128 \param info The \a turned_font_info struct to be filled out. 1129*/ 1130 1131 1132/*! 1133 \fn void BFont::TruncateString(BString *inOut, uint32 mode, 1134 float width) const 1135 \brief Truncates \a inOut to be no longer than \a width using the 1136 supplied truncation \a mode. 1137 1138 The following truncation modes are supported: 1139 - \c B_TRUNCATE_BEGINNING Truncate from the beginning of the string. 1140 - \c B_TRUNCATE_MIDDLE Truncate from the middle of the string. 1141 - \c B_TRUNCATE_END Truncate from the end of the string. 1142 - \c B_TRUNCATE_SMART Truncate from anywhere, but do so so that each 1143 string is made unique after being truncated. 1144 1145 \param inOut The BString to truncate. 1146 \param mode Truncation mode to use. 1147 \param width The maximum width to truncate to. 1148*/ 1149 1150 1151/*! 1152 \fn void BFont::GetTruncatedStrings(const char *stringArray[], 1153 int32 numStrings, uint32 mode, float width, 1154 BString resultArray[]) const 1155 \brief Write truncated BString objects to \a resultArray given source 1156 BString objects in \a stringArray. 1157 1158 The following truncation modes are supported: 1159 - \c B_TRUNCATE_BEGINNING Truncate from the beginning of the string. 1160 - \c B_TRUNCATE_MIDDLE Truncate from the middle of the string. 1161 - \c B_TRUNCATE_END Truncate from the end of the string. 1162 - \c B_TRUNCATE_SMART Truncate from anywhere, but do so so that each 1163 string is made unique after being truncated. 1164 1165 \param stringArray The source string array. 1166 \param numStrings The number of strings in \a stringArray. 1167 \param mode Truncation mode to use. 1168 \param width The maximum width to truncate to. 1169 \param resultArray The destination string array. 1170*/ 1171 1172 1173/*! 1174 \fn void BFont::GetTruncatedStrings(const char *stringArray[], 1175 int32 numStrings, uint32 mode, float width, char *resultArray[]) const 1176 \brief Write truncated strings to \a resultArray given source 1177 BString objects in \a stringArray. 1178 1179 \a resultArray is an array of pointers to string buffers which should be 1180 allocated ahead of time and should be at least 3 bytes longer than the 1181 matching input string. The 3 extra bytes provide enough room for the 1182 truncated output given that GetTruncatedStrings() truncates only a 1183 single-byte character from the input string and replaces it with an 1184 ellipsis character (which takes three bytes for the UTF-8 encoding), 1185 and adds a \c NUL-terminator. 1186 1187 The following truncation modes are supported: 1188 - \c B_TRUNCATE_BEGINNING Truncate from the beginning of the string. 1189 - \c B_TRUNCATE_MIDDLE Truncate from the middle of the string. 1190 - \c B_TRUNCATE_END Truncate from the end of the string. 1191 - \c B_TRUNCATE_SMART Truncate from anywhere, but do so so that each 1192 string is made unique after being truncated. 1193 1194 \param stringArray The source string array. 1195 \param numStrings The number of strings in \a stringArray. 1196 \param mode Truncation mode to use. 1197 \param width The maximum width to truncate to. 1198 \param resultArray The destination string array. 1199*/ 1200 1201 1202/*! 1203 \fn float BFont::StringWidth(const char *string) const 1204 \brief Determines the amount of space required to draw \a string in the 1205 current font. 1206 1207 \param string The source string. 1208 1209 \returns The width required to draw the string. 1210*/ 1211 1212 1213/*! 1214 \fn float BFont::StringWidth(const char *string, int32 length) const 1215 \brief Determines the amount of space required to draw \a string in the 1216 current font up to \a length characters. 1217 1218 \param string The source string. 1219 \param length The number of characters in \a string to consider. 1220 1221 \returns The width required to draw the string. 1222*/ 1223 1224 1225/*! 1226 \fn void BFont::GetStringWidths(const char *stringArray[], 1227 const int32 lengthArray[], int32 numStrings, float widthArray[]) const 1228 \brief Determines the amount of space required to draw each string in 1229 \a stringArray and writes the result in \a widthArray. 1230 1231 \param stringArray The source string array. 1232 \param lengthArray The number of characters to consider for each string in 1233 \a stringArray 1234 \param numStrings The number of strings in \a stringArray. 1235 \param widthArray The destination array to put the widths required to draw 1236 each string. 1237*/ 1238 1239 1240/*! 1241 \fn void BFont::GetEscapements(const char charArray[], int32 numChars, 1242 float escapementArray[]) const 1243 \brief Determines the escapements for each char in \a charArray and writes 1244 the result in \a escapementArray. 1245 1246 \param charArray The source character array. 1247 \param numChars The number of characters to consider in \a charArray. 1248 \param escapementArray The destination array to put the escapements. 1249*/ 1250 1251 1252/*! 1253 \fn void BFont::GetEscapements(const char charArray[], int32 numChars, 1254 escapement_delta *delta, float escapementArray[]) const 1255 \brief Determines the escapements for each char in \a charArray and writes 1256 the result in \a escapementArray with consideration to the provided 1257 escapement \a delta. 1258 1259 The escapement_delta structure contains the following values: 1260 - \c nonspace The amount of space surrounding a character with a visible 1261 glyph. 1262 - \c space The amount of space surrounding a whitespace character, for 1263 example \c B_TAB and \c B_SPACE. 1264 1265 \param charArray The source character array. 1266 \param numChars The number of characters to consider in \a charArray. 1267 \param delta The escapement_delta structure to use. 1268 \param escapementArray The destination array to put the escapements. 1269*/ 1270 1271 1272/*! 1273 \fn void BFont::GetEscapements(const char charArray[], int32 numChars, 1274 escapement_delta *delta, BPoint escapementArray[]) const 1275 \brief Determines the escapements for each char in \a charArray and writes 1276 the result in \a escapementArray as an array of BPoint objects 1277 with consideration to the provided escapement \a delta. 1278 1279 The escapement_delta structure contains the following values: 1280 - \c nonspace The amount of space surrounding a character with a visible 1281 glyph. 1282 - \c space The amount of space surrounding a whitespace character, for 1283 example \c B_TAB and \c B_SPACE. 1284 1285 \param charArray The source character array. 1286 \param numChars The number of characters to consider in \a charArray. 1287 \param delta The escapement_delta structure to use. 1288 \param escapementArray The destination array of escapements as BPoint 1289 objects. 1290*/ 1291 1292 1293/*! 1294 \fn void BFont::GetEscapements(const char charArray[], int32 numChars, 1295 escapement_delta *delta, BPoint escapementArray[], 1296 BPoint offsetArray[]) const 1297 \brief Determines the escapements for each char in \a charArray and writes 1298 the result in \a escapementArray as an array of BPoint objects 1299 with consideration to the provided escapement \a delta 1300 and writes offsets to \a offsetArray. 1301 1302 The escapement_delta structure contains the following values: 1303 - \c nonspace The amount of space surrounding a character with a visible 1304 glyph. 1305 - \c space The amount of space surrounding a whitespace character, for 1306 example \c B_TAB and \c B_SPACE. 1307 1308 \param charArray The source character array. 1309 \param numChars The number of characters to consider in \a charArray. 1310 \param delta The escapement_delta structure to use. 1311 \param escapementArray The destination array of escapements as BPoint 1312 objects. 1313 \param offsetArray The destination array of offsets as BPoint objects. 1314*/ 1315 1316 1317/*! 1318 \fn void BFont::GetEdges(const char charArray[], int32 numChars, 1319 edge_info edgeArray[]) const 1320 \brief Determines the edge information for each character in \a charArray 1321 and writes the result in \a edgeArray. 1322 1323 The \c edge_info struct contains the following values: 1324 - \c left The distance that the character outline is inset from the left 1325 escapement boundary. 1326 - \c right The distance that the character outline is inset from the 1327 right escapement boundary. 1328 1329 \param charArray The source character array. 1330 \param numChars The number of characters to consider in \a charArray. 1331 \param edgeArray The destination array of \c edge_info structs. 1332*/ 1333 1334 1335/*! 1336 \fn void BFont::GetHeight(font_height *_height) const 1337 \brief Fills out the \c font_height struct with the amount of vertical 1338 space surrounding a character. 1339 1340 The \c font_height struct contains the following values: 1341 - \c ascent The distance characters can ascend above the baseline. 1342 - \c descent The distance characters can descend below the baseline. 1343 - \c leading The distance between lines, descent above to ascent below. 1344 1345 \param _height The \c font_height struct to fill out. 1346*/ 1347 1348 1349/*! 1350 \fn void BFont::GetBoundingBoxesAsGlyphs(const char charArray[], 1351 int32 numChars, font_metric_mode mode, BRect boundingBoxArray[]) const 1352 \brief Writes an array of BRect objects to \a boundingBoxArray 1353 representing the bounding rectangles of each character in 1354 \a charArray. 1355 1356 Each BRect object corresponds to the glyph of one character. 1357 1358 The \c font_metric_mode should contain one of the following values: 1359 - \c B_SCREEN_METRIC The bounding boxes should use the screen metric. 1360 - \c B_PRINTING_METRIC The bounding boxes should use the print metric. 1361 1362 \param charArray The source character array. 1363 \param numChars The number of characters to consider in \a charArray. 1364 \param mode The \c font_metric_mode to use, screen or printing. 1365 \param boundingBoxArray The destination array of BRect bounding boxes. 1366*/ 1367 1368 1369/*! 1370 \fn void BFont::GetBoundingBoxesAsString(const char charArray[], 1371 int32 numChars, font_metric_mode mode, escapement_delta *delta, 1372 BRect boundingBoxArray[]) const 1373 \brief Writes an array of BRect objects to \a boundingBoxArray 1374 representing the bounding rectangles of each character in 1375 \a charArray with consideration to the provided escapement 1376 \a delta. 1377 1378 Each BRect object corresponds to the glyph of one character. 1379 1380 The \c font_metric_mode should contain one of the following values: 1381 - \c B_SCREEN_METRIC The bounding boxes should use the screen metric. 1382 - \c B_PRINTING_METRIC The bounding boxes should use the print metric. 1383 1384 Escapement deltas are applied as part of the bounding box calculations. 1385 This lets you specify a character spacing is looser or tighter than 1386 normal. 1387 1388 The escapement_delta structure contains the following values: 1389 - \c nonspace The amount of space surrounding a character with a visible 1390 glyph. 1391 - \c space The amount of space surrounding a whitespace character, for 1392 example \c B_TAB and \c B_SPACE. 1393 1394 \param charArray The source character array. 1395 \param numChars The number of characters to consider in \a charArray. 1396 \param mode The \c font_metric_mode to use, screen or printing. 1397 \param delta The escapement_delta structure to use. 1398 \param boundingBoxArray The destination array of BRect bounding boxes. 1399*/ 1400 1401 1402/*! 1403 \fn void BFont::GetBoundingBoxesForStrings(const char *stringArray[], 1404 int32 numStrings, font_metric_mode mode, escapement_delta deltas[], 1405 BRect boundingBoxArray[]) const 1406 \brief Writes an array of BRect objects to \a boundingBoxArray 1407 representing the bounding rectangles of each string in 1408 \a stringArray with consideration to the provided escapement 1409 \a delta. 1410 1411 Each BRect object corresponds to the bounding box of the entire string. 1412 1413 The \c font_metric_mode should contain one of the following values: 1414 - \c B_SCREEN_METRIC The bounding boxes should use the screen metric. 1415 - \c B_PRINTING_METRIC The bounding boxes should use the print metric. 1416 1417 Escapement deltas are applied as part of the bounding box calculations. 1418 This lets you specify a character spacing is looser or tighter than 1419 normal. 1420 1421 The escapement_delta structures should contain the following values: 1422 - \c nonspace The amount of space surrounding a character with a visible 1423 glyph. 1424 - \c space The amount of space surrounding a whitespace character, for 1425 example \c B_TAB and \c B_SPACE. 1426 1427 \param stringArray The source string array. 1428 \param numStrings The number of strings to consider in \a stringArray. 1429 \param mode The \c font_metric_mode to use, screen or printing. 1430 \param deltas The array of escapement_delta structures to use. 1431 \param boundingBoxArray The destination array of BRect bounding boxes. 1432*/ 1433 1434 1435/*! 1436 void BFont::GetGlyphShapes(const char charArray[], int32 numChars, 1437 BShape *glyphShapeArray[]) const 1438 \brief Writes an array of BShape objects to \a glyphShapeArray 1439 representing the glyph shapes of each character in 1440 \a charArray. 1441 1442 Each BShape object corresponds to the glyph of one character. 1443 1444 \param charArray The source character array. 1445 \param numChars The number of characters to consider in \a charArray. 1446 \param glyphShapeArray The destination array of BShape glyphs. 1447*/ 1448 1449 1450/*! 1451 void BFont::GetHasGlyphs(const char charArray[], int32 numChars, 1452 bool hasArray[]) const 1453 \brief Fills out \a hasArray with whether or not each characters in 1454 \a charArray has a glyph for the font. 1455 1456 \c true is written in \a hasArray if the character has a glyph in the 1457 current font and \c false is written in \a hasArray if the character 1458 does NOT have a glyph in the current font. 1459 1460 \param charArray The source character array. 1461 \param numChars The number of characters to consider in \a charArray. 1462 \param hasArray The destination array of booleans. 1463*/ 1464 1465 1466/*! 1467 BFont& BFont::operator=(const BFont &font) 1468 \brief Assignment overload method. 1469 1470 \param font The BFont object to assign from. 1471*/ 1472 1473 1474/*! 1475 bool BFont::operator==(const BFont &font) const 1476 \brief Equality comparison overload method. 1477 1478 \param font The BFont object to compare the current font to. 1479 1480 \returns \c true if the fonts objects are identical, \c false otherwise. 1481*/ 1482 1483 1484/*! 1485 bool BFont::operator!=(const BFont &font) const 1486 \brief Inequality comparison overload method. 1487 1488 \param font The BFont object to compare the current font to. 1489 1490 \returns \c true if the fonts objects are NOT identical, \c true 1491 otherwise. 1492*/ 1493 1494 1495/*! 1496 void BFont::PrintToStream() const 1497 \brief Writes information about the font to \c stdout. 1498 1499 printf("BFont { %s (%d), %s (%d) 0x%x %f/%f %fpt (%f %f %f), %d }\n", 1500 family, fFamilyID, style, fStyleID, fFace, fShear, fRotation, fSize, 1501 fHeight.ascent, fHeight.descent, fHeight.leading, fEncoding); 1502*/ 1503