From c258d2fa0e72c357147f9198554dc070ff7b95df Mon Sep 17 00:00:00 2001 From: John Scipione Date: Sat, 19 Jan 2013 01:23:44 -0500 Subject: [PATCH] Fill out BFont member docs --- docs/user/interface/Font.dox | 920 ++++++++++++++++++++++++++++++++--- 1 file changed, 864 insertions(+), 56 deletions(-) diff --git a/docs/user/interface/Font.dox b/docs/user/interface/Font.dox index ddb3a10ce3..8af8252184 100644 --- a/docs/user/interface/Font.dox +++ b/docs/user/interface/Font.dox @@ -12,7 +12,8 @@ /*! \file Font.h - \brief BFont class definition and support structs and enums. + \brief BFont class definition, unicode_block class definition, and + font-related struct and enum definitions. */ @@ -26,31 +27,35 @@ /*! \var B_CHAR_SPACING - Character spacing + Position each character without adjustment. Best mode for printing. */ /*! \var B_STRING_SPACING - String spacing + Optimizes the position of each character within it's space. Collisions + are unlikely but characters may touch each other. Best mode to use when + the screen needs to match what appears on the printed page. */ /*! \var B_BITMAP_SPACING - Bitmap spacing + The widths of the characters are chosen so that they never collide and + rarely touch. Best mode for drawing small amounts of text. */ /*! \var B_FIXED_SPACING - Fixed width spacing + Positions characters at a constant width. Best mode for fixed-width fonts. */ /*! \enum font_direction - Determines the direction of the font left-to-right or right-to-left. + Determines the direction of the text rendered by the font, + left-to-right or right-to-left. */ /*! @@ -66,13 +71,13 @@ /*! \var B_DISABLE_ANTIALIASING - Disable antialiasing. + Disable antialiasing. Used by BFont::Flags() and BFont::SetFlags(). */ /*! \var B_FORCE_ANTIALIASING - Force antialiasing. + Force antialiasing. Used by BFont::Flags() and BFont::SetFlags(). */ @@ -84,19 +89,19 @@ /*! \var B_TRUNCATE_BEGINNING - Truncate at beginning of the string. + Truncate from the beginning of the string. */ /*! \var B_TRUNCATE_MIDDLE - Truncate in the middle of the string. + Truncate from the middle of the string. */ /*! \var B_TRUNCATE_SMART - Perform a smart truncation of the string. + Truncate while keeping each string unique. */ @@ -108,26 +113,25 @@ /*! \var B_ISO_8859_1 - ISO 8859-1 aka Latin 1 font encoding. + ISO 8859-1 aka Latin 1 "Western European" font encoding. */ /*! \var B_ISO_8859_2 - ISO 8859-2 aka Latin 2 font encoding. It is generally intended for Eastern - European languages that are written in the Latin script. + ISO 8859-2 aka Latin 2 "Eastern European" font encoding. */ /*! \var B_ISO_8859_3 - ISO 8859-3 "South European" font encoding. + ISO 8859-3 aka Latin 3 "South European" font encoding. */ /*! \var B_ISO_8859_4 - ISO 8859-4 "North European" font encoding. + ISO 8859-4 aka Latin 4 "Northern European" font encoding. */ @@ -157,13 +161,13 @@ /*! \var B_ISO_8859_9 - ISO 8859-9 "Latin/Turkish" font encoding. + ISO 8859-9 aka Latin 5 "Latin/Turkish" font encoding. */ /*! \var B_ISO_8859_10 - ISO 8859-10 font encoding. + ISO 8859-10 aka Latin 6 "Nordic" font encoding. */ @@ -263,41 +267,210 @@ /*! \enum font_file_format - Font file format, truetype or type1. + Font file format, TrueType™ or PostScript™ Type1. + + \see BFont::FileFormat() */ /*! \var font_file_format B_TRUETYPE_WINDOWS - Truetype font file format. + TrueType™ font file format. */ /*! \var font_file_format B_POSTSCRIPT_TYPE1_WINDOWS - Type1 font file format. + PostScript™ Type1 font file format. */ /*! \class unicode_block - \brief Unicode block class. + \brief Provides the blocks of unicode characters supported by a font. + + \see BFont::Blocks() */ +/*! + \fn unicode_block::unicode_block() + \brief Construct a \c unicode_block and set block data to 0LL. + + You must initialize the block data before before using this object. +*/ + + +/*! + \fn unicode_block::unicode_block(uint64 block2, uint64 block1) + \brief Construct a \c unicode_block object and initialize it with the + supplied Unicode block range. + + \param block2 End block. + \param block1 Begin block. +*/ + + +/*! + \fn bool unicode_block::Includes(const unicode_block& block) const + \brief Determines if \a block is a subset of the \c unicode_block object. + + \param block The Unicode block to compare. + + \returns Whether or not \a block is a subset of the \c unicode_block + object. + \retval true \a block is a subset. + \retval false \a block is NOT a subset. +*/ + + +/*! + \name Assignment operators +*/ + + +//! @{ + + +/*! + \fn unicode_block unicode_block::operator&(const unicode_block& block) const + \brief Creates a new \c unicode_block object that is the intersection of + \a block and the \c unicode_block object. + + \param block The Unicode block to intersect with. + + \returns The intersection of \a block and the \c unicode_block object. +*/ + + +/*! + \fn unicode_block unicode_block::operator|(const unicode_block& block) const + \brief Creates a new \c unicode_block object that is the union of \a block + and the \c unicode_block object. + + \param block The Unicode block to form a union with. + + \returns The union of \a block and the \c unicode_block object. +*/ + + +/*! + \fn unicode_block& unicode_block::operator=(const unicode_block& block) + \brief Copies \a block data into the left-hand side object. + + \param block The unicode block to copy from. + + \returns A copy of \a block. +*/ + + +//! @} + + +/*! + \name Comparison operators +*/ + + +//! @{ + + +/*! + \fn bool unicode_block::operator==(const unicode_block& block) const + \brief Determines if the block object are exactly equal. + + \param block The unicode block to compare against. + + \returns \c true if the block object are exactly equal, \c false + otherwise. +*/ + + +/*! + \fn bool unicode_block::operator!=(const unicode_block& block) const + \brief Determines if the block object are not equal. + + \param block The unicode block to compare against. + + \returns \c true if the block object are NOT equal, \c false + if the block objects are exactly equal. +*/ + + +//! @} + + /*! \struct edge_info - \brief Edge info parameters: left or right. Both \c float type. + \brief The distance that a character outline is inset from its escapement + boundaries. + + Edge values, like escapements, need to be multiplied by the font size to + get the correct value for the font. + + \see BFont::GetEdges() +*/ + + +/*! + \var edge_info::left + \brief The distance that the character outline is inset from the left + escapement boundary. +*/ + + +/*! + \var edge_info::right + \brief The distance that the character outline is inset from the right + escapement boundary. */ /*! \struct font_height - \brief Font height parameters: ascent, descent or leading. All \c float type. + \brief The amount of vertical space surrounding a character. + + \see BFont::GetHeight() +*/ + + +/*! + \var font_height::ascent + \brief The distance characters can ascend above the baseline. +*/ + + +/*! + \var font_height::descent + \brief The distance characters can descend below the baseline. +*/ + + +/*! + \var font_height::leading + \brief The distance between lines, descent above to ascent below. */ /*! \struct escapement_delta - \brief Escapement delta parameters: nonspace or space. Both \c float type. + \brief The amount of horizontal space surrounding a character. + + Escapements need to be multiplied by the font size to get the correct + value for the font. + + \see BFont::GetEscapements() +*/ + + +/*! + \var escapement_delta::nonspace + \brief The amount of space surrounding a character with a visible glyph. +*/ + + +/*! + \var escapement_delta::space + \brief The amount of space surrounding a whitespace character, for example + \c B_TAB and \c B_SPACE. */ @@ -308,72 +481,76 @@ /*! - \var font_cache_info sheared_font_penalty - Sheared font penalty. Type \c int32. + \var font_cache_info::sheared_font_penalty + \brief Sheared font penalty. */ /*! - \var font_cache_info rotated_font_penalty - Rotated font penalty. Type \c int32. + \var font_cache_info::rotated_font_penalty + \brief Rotated font penalty. */ /*! - \var font_cache_info oversize_threshold - Oversize threshold. Type \c float. + \var font_cache_info::oversize_threshold + \brief Oversize threshold. */ /*! - \var font_cache_info oversize_penalty - Oversize penalty. Type \c int32. + \var font_cache_info::oversize_penalty + \brief Oversize penalty. */ /*! - \var font_cache_info cache_size - Cache size. Type \c int32. + \var font_cache_info::cache_size + \brief Cache size. */ /*! - \var font_cache_info spacing_size_threshold - Spacing size threshold. Type \c float. + \var font_cache_info::spacing_size_threshold + \brief Spacing size threshold. */ /*! \struct tuned_font_info - \brief Tuned font information. + \brief Tuning information of fonts used to make it look better when + displayed on-screen. + + \see BFont::GetTunedInfo() + \see BFont::CountTuned() */ /*! - \var tuned_font_info size - Font size. Type \c float. + \var tuned_font_info::size + \brief Font size. */ /*! - \var tuned_font_info shear - Font shear. Type \c float. + \var tuned_font_info::shear + \brief Font shear. */ /*! - \var tuned_font_info rotation - Font rotation. Type \c float. + \var tuned_font_info::rotation + \brief Font rotation. */ /*! - \var tuned_font_info flags - Font flags. Type \c uint32. + \var tuned_font_info::flags + \brief Font flags. */ /*! - \var tuned_font_info face - Font face. Type \c uint16. + \var tuned_font_info::face + \brief Font face. */ @@ -476,7 +653,7 @@ \class BFont \ingroup interface \ingroup libbe - \brief A class representing a typeface including the family, style and size. + \brief Represents a typeface including it's family, style and size. */ @@ -529,7 +706,7 @@ /*! - \fn void BFont::SetFamilyAndStyle(uint32 fontcode) + \fn void BFont::SetFamilyAndStyle(uint32 code) \brief Sets the font's family and style from a font identifier. \param code Unique font identifier obtained from the server. @@ -555,7 +732,7 @@ /*! \fn void BFont::SetSize(float size) - \brief Set the font size. + \brief Sets the font size. \param size The point size to set the font to. */ @@ -563,34 +740,222 @@ /*! \fn void BFont::SetShear(float shear) - \brief Set the angle in degrees relative to the baseline. + \brief Sets the angle in degrees relative to the baseline. The default shear is 90.0° measured counterclockwise. The shear range is from 45.0° to 135.0°. - \param size The shear in degrees to set the font to. + \param shear The shear in degrees to set the font to. */ /*! \fn void BFont::SetRotation(float rotation) - \brief Set the font rotation from the baseline in degrees. + \brief Sets the font rotation from the baseline in degrees. The default baseline is 0° and rotates counterclockwise. Rotation is not supported by BTextView. - \param size The rotation in degrees to set the font to. + \param rotation The rotation in degrees to set the font to. */ /*! \fn void BFont::SetFalseBoldWidth(float width) - \brief Set the false bold width. + \brief Sets the false bold width. \param width The false bold width to set. */ +/*! + \fn void BFont::SetSpacing(uint8 spacing) + \brief Sets how characters are horizontally spaced relative to each other. + + - \c B_CHAR_SPACING Position each character without adjustment. Best mode + for printing. Characters may collide or overlap at small font sizes. + - \c B_STRING_SPACING Optimizes the position of each character within it's + space. Collisions are unlikely but characters may touch each other. + Best mode to use when the screen needs to match what appears on the + printed page. Adding new characters requires the entire string to + be redrawn. + - \c B_BITMAP_SPACING The widths of the characters are chosen so that they + never collide and rarely touch. Best mode for drawing small amounts + of text. Character widths are integral values. Spacing on screen will + not match spacing used by \c B_CHAR_SPACING mode for printing. + - \c B_FIXED_SPACING Positions characters at a constant width. Must be + used with fixed-width fonts otherwise \c B_CHAR_SPACING mode is used. + All characters have an identical integral escapement. + + \c B_STRING_SPACING and \c B_BITMAP_SPACING modes are relevant only for + font sizes from 7.0pt to 18.0pt, above and below that range + \c B_CHAR_SPACING produces nicer results. \c B_CHAR_SPACING is also always + used for rotated or sheared text and when antialiasing is disabled. + + \param spacing The spacing mode to set. + + \see BView::DrawString() + \see GetEscapements() +*/ + + +/*! + \fn void BFont::SetEncoding(uint8 encoding) + \brief Sets the character encoding of the font. + + The following character encodings are supported: + - \c B_UNICODE_UTF8 + - \c B_ISO_8859_1 aka Latin 1 aka "Western European". + - \c B_ISO_8859_2 aka Latin 2 aka "Eastern European". + - \c B_ISO_8859_3 aka Latin 3 aka "South European". + - \c B_ISO_8859_4 aka Latin 4 aka "Northern European". + - \c B_ISO_8859_5 aka "Latin/Cyrillic". + - \c B_ISO_8859_6 aka "Latin/Arabic". + - \c B_ISO_8859_7 aka "Latin/Greek". + - \c B_ISO_8859_8 aka "Latin/Hebrew". + - \c B_ISO_8859_9 aka Latin 5 aka "Latin/Turkish". + - \c B_ISO_8859_10 aka Latin 6 aka "Nordic". + - \c B_MACINTOSH_ROMAN + + \param encoding The character encoding to set. +*/ + + +/*! + \fn void BFont::SetFace(uint16 face) + \brief Sets the font face according to the flags set by \a face. + + The following font face flags are supported: + - \c B_ITALIC_FACE Characters are slanted to the right. + - \c B_UNDERSCORE_FACE Characters are underlined. + - \c B_NEGATIVE_FACE High and low colors are reversed when drawing + characters. + - \c B_OUTLINED_FACE Characters are drawn hollowed out. + - \c B_STRIKEOUT_FACE A horizontal line is drawn through their middle. + - \c B_BOLD_FACE Characters are bold. + - \c B_REGULAR_FACE Characters are drawn normally. + - \c B_CONDENSED_FACE Characters are drawn squished together. Not in + BeOS 5. + - \c B_LIGHT_FACE Characters are drawn thiner than normal. Not in BeOS 5. + - \c B_HEAVY_FACE Characters are drawn heavier than normal. Not in BeOS 5. + + \param face The mask of font face flags to set. +*/ + + +/*! + \fn void BFont::SetFlags(uint32 flags) + \brief Sets font flags controlling antialiasing. + + The following flags are supported: + - B_DISABLE_ANTIALIASING Disable antialiasing. + - B_FORCE_ANTIALIASING Force antialiasing. + + \param flags The mask of flags to set. +*/ + + +/*! + \fn void BFont::GetFamilyAndStyle(font_family *family, + font_style *style) const + \brief Writes out the name of the font family and/or font style. + + This method may be called with either \a family or \a style set to + \c NULL in order to get one or the other. + + \param family A font_family pointer to be filled out. + \param style A font_style pointer to be filled out. +*/ + + +/*! + \fn uint32 BFont::FamilyAndStyle() const + \brief Gets the code of the font family and style combination. + + \returns The family and style combination encoded as a unique integer. +*/ + + +/*! + \fn float BFont::Size() const + \brief Gets the font size. + + \returns The font size in points. +*/ + + +/*! + \fn float BFont::Size() const + \brief Gets the font shear. + + \returns The font shear as an angle from 45.0° to 135.0°. +*/ + + +/*! + \fn float BFont::Rotation() const + \brief Gets the font rotation. + + \returns The font rotation as an angle in degrees. +*/ + + +/*! + \fn float BFont::FalseBoldWidth() const + \brief Gets the width of the font as if it were bold. + + \returns The font width of the bold font variety. +*/ + + +/*! + \fn uint8 BFont::Spacing() const + \brief Gets the spacing constant. + + \returns The spacing constant. +*/ + + +/*! + \fn uint8 BFont::Encoding() const + \brief Gets the character encoding constant. + + \returns The character encoding constant. +*/ + + +/*! + \fn uint16 BFont::Face() const + \brief Gets the font face flags mask. + + \returns The font face flags mask. +*/ + + +/*! + \fn uint32 BFont::Flags() const + \brief Gets the antialiasing flags. + + \returns The antialiasing flags. +*/ + + +/*! + \fn font_direction BFont::Direction() const + \brief Gets the font direction, left-to-right or right-to left. + + \returns The font direction. +*/ + + +/*! + \fn bool BFont::IsFixed() const + \brief Gets whether or not the font is fixed width. + + \returns \c true if the font is fixed width, \c false otherwise. +*/ + + /*! \fn bool BFont::IsFullAndHalfFixed() const \brief Returns whether or not the font is fixed-width and contains both @@ -600,3 +965,446 @@ Kanji and Roman characters in the same fixed-width font. */ + +/*! + \fn BRect BFont::BoundingBox() const + \brief Gets a BRect that encloses the font text. + + \returns A BRect that encloses the font text. +*/ + + +/*! + \fn unicode_block BFont::Blocks() const + \brief Gets a \c unicode_block object identifying the Unicode blocks + supported by the font. + + \attention Currently unimplemented, returns an empty \a unicode_block + object. + + \returns A \c unicode_block object. +*/ + + +/*! + \fn font_file_format BFont::FileFormat() const + \brief Gets whether the font is TrueType™ or Type1 font. + + \returns A \c font_file_format struct containing the font file format. +*/ + + +/*! + \fn int32 BFont::CountTuned() const + \brief Gets the number of tuned fonts for the font family and style. + + \returns The number of tuned fonts. +*/ + + +/*! + \fn void BFont::GetTunedInfo(int32 index, tuned_font_info *info) const + \brief Writes information about the tuned font at \a index into \a info. + + The index begins at 0 and counts tuned fonts for current font family and + style only. + + \param index The index of desired tuned font. + \param info The \a turned_font_info struct to fill out. +*/ + + +/*! + \fn void BFont::TruncateString(BString *inOut, uint32 mode, + float width) const + \brief Truncates \a inOut to be no longer than \a width using the + supplied truncation \a mode. + + The following truncation modes are supported: + - \c B_TRUNCATE_BEGINNING Truncate from the beginning of the string. + - \c B_TRUNCATE_MIDDLE Truncate from the middle of the string. + - \c B_TRUNCATE_END Truncate from the end of the string. + - \c B_TRUNCATE_SMART Truncate from anywhere, but do so so that each + string is made unique after being truncated. + + \param inOut The BString to truncate. + \param mode Truncation mode to use. + \param width The maximum width to truncate to. +*/ + + +/*! + \fn void BFont::GetTruncatedStrings(const char *stringArray[], + int32 numStrings, uint32 mode, float width, + BString resultArray[]) const + \brief Write truncated BString objects to \a resultArray given source + BString objects in \a stringArray. + + The following truncation modes are supported: + - \c B_TRUNCATE_BEGINNING Truncate from the beginning of the string. + - \c B_TRUNCATE_MIDDLE Truncate from the middle of the string. + - \c B_TRUNCATE_END Truncate from the end of the string. + - \c B_TRUNCATE_SMART Truncate from anywhere, but do so so that each + string is made unique after being truncated. + + \param stringArray The source string array. + \param numStrings The number of strings in \a stringArray. + \param mode Truncation mode to use. + \param width The maximum width to truncate to. + \param resultArray The destination string array. +*/ + + +/*! + \fn void BFont::GetTruncatedStrings(const char *stringArray[], + int32 numStrings, uint32 mode, float width, char *resultArray[]) const + \brief Write truncated strings to \a resultArray given source + BString objects in \a stringArray. + + \a resultArray is an array of pointers to string buffers which should be + allocated ahead of time and should be at least 3 bytes longer than the + matching input string. The 3 extra bytes provide enough room for the + truncated output given that GetTruncatedStrings() truncates only a + single-byte character from the input string and replaces it with an + ellipsis character (which takes three bytes for the UTF-8 encoding), + and adds a \c NUL-terminator. + + The following truncation modes are supported: + - \c B_TRUNCATE_BEGINNING Truncate from the beginning of the string. + - \c B_TRUNCATE_MIDDLE Truncate from the middle of the string. + - \c B_TRUNCATE_END Truncate from the end of the string. + - \c B_TRUNCATE_SMART Truncate from anywhere, but do so so that each + string is made unique after being truncated. + + \param stringArray The source string array. + \param numStrings The number of strings in \a stringArray. + \param mode Truncation mode to use. + \param width The maximum width to truncate to. + \param resultArray The destination string array. +*/ + + +/*! + \fn float BFont::StringWidth(const char *string) const + \brief Determines the amount of space required to draw \a string in the + current font. + + \param string The source string. + + \returns The width required to draw the string. +*/ + + +/*! + \fn float BFont::StringWidth(const char *string, int32 length) const + \brief Determines the amount of space required to draw \a string in the + current font up to \a length characters. + + \param string The source string. + \param length The number of characters in \a string to consider. + + \returns The width required to draw the string. +*/ + + +/*! + \fn void BFont::GetStringWidths(const char *stringArray[], + const int32 lengthArray[], int32 numStrings, float widthArray[]) const + \brief Determines the amount of space required to draw each string in + \a stringArray and writes the result in \a widthArray. + + \param stringArray The source string array. + \param lengthArray The number of characters to consider for each string in + \a stringArray + \param numStrings The number of strings in \a stringArray. + \param widthArray The destination array to put the widths required to draw + each string. +*/ + + +/*! + \fn void BFont::GetEscapements(const char charArray[], int32 numChars, + float escapementArray[]) const + \brief Determines the escapements for each char in \a charArray and writes + the result in \a escapementArray. + + \param charArray The source character array. + \param numChars The number of characters to consider in \a charArray. + \param escapementArray The destination array to put the escapements. +*/ + + +/*! + \fn void BFont::GetEscapements(const char charArray[], int32 numChars, + escapement_delta *delta, float escapementArray[]) const + \brief Determines the escapements for each char in \a charArray and writes + the result in \a escapementArray with consideration to the provided + escapement \a delta. + + The \c escapement_delta structure contains the following values: + - \c nonspace The amount of space surrounding a character with a visible + glyph. + - \c space The amount of space surrounding a whitespace character, for + example \c B_TAB and \c B_SPACE. + + \param charArray The source character array. + \param numChars The number of characters to consider in \a charArray. + \param delta The \c escapement_delta structure to use. + \param escapementArray The destination array to put the escapements. +*/ + + +/*! + \fn void BFont::GetEscapements(const char charArray[], int32 numChars, + escapement_delta *delta, BPoint escapementArray[]) const + \brief Determines the escapements for each char in \a charArray and writes + the result in \a escapementArray as an array of BPoint objects + with consideration to the provided escapement \a delta. + + The \c escapement_delta structure contains the following values: + - \c nonspace The amount of space surrounding a character with a visible + glyph. + - \c space The amount of space surrounding a whitespace character, for + example \c B_TAB and \c B_SPACE. + + \param charArray The source character array. + \param numChars The number of characters to consider in \a charArray. + \param delta The \c escapement_delta structure to use. + \param escapementArray The destination array of escapements as BPoint + objects. +*/ + + +/*! + \fn void BFont::GetEscapements(const char charArray[], int32 numChars, + escapement_delta *delta, BPoint escapementArray[], + BPoint offsetArray[]) const + \brief Determines the escapements for each char in \a charArray and writes + the result in \a escapementArray as an array of BPoint objects + with consideration to the provided escapement \a delta + and writes offsets to \a offsetArray. + + The \c escapement_delta structure contains the following values: + - \c nonspace The amount of space surrounding a character with a visible + glyph. + - \c space The amount of space surrounding a whitespace character, for + example \c B_TAB and \c B_SPACE. + + \param charArray The source character array. + \param numChars The number of characters to consider in \a charArray. + \param delta The \c escapement_delta structure to use. + \param escapementArray The destination array of escapements as BPoint + objects. + \param offsetArray The destination array of offsets as BPoint objects. +*/ + + +/*! + \fn void BFont::GetEdges(const char charArray[], int32 numChars, + edge_info edgeArray[]) const + \brief Determines the edge information for each character in \a charArray + and writes the result in \a edgeArray. + + The \c edge_info struct contains the following values: + - \c left The distance that the character outline is inset from the left + escapement boundary. + - \c right The distance that the character outline is inset from the + right escapement boundary. + + \param charArray The source character array. + \param numChars The number of characters to consider in \a charArray. + \param edgeArray The destination array of \c edge_info structs. +*/ + + +/*! + \fn void BFont::GetHeight(font_height *_height) const + \brief Fills out the \c font_height struct with the amount of vertical + space surrounding a character. + + The \c font_height struct contains the following values: + - \c ascent The distance characters can ascend above the baseline. + - \c descent The distance characters can descend below the baseline. + - \c leading The distance between lines, descent above to ascent below. + + \param _height The \c font_height struct to fill out. +*/ + + +/*! + \fn void BFont::GetBoundingBoxesAsGlyphs(const char charArray[], + int32 numChars, font_metric_mode mode, BRect boundingBoxArray[]) const + \brief Writes an array of BRect objects to \a boundingBoxArray + representing the bounding rectangles of each character in + \a charArray. + + Each BRect object corresponds to the glyph of one character. + + The \c font_metric_mode should contain one of the following values: + - \c B_SCREEN_METRIC The bounding boxes should use the screen metric. + - \c B_PRINTING_METRIC The bounding boxes should use the print metric. + + \param charArray The source character array. + \param numChars The number of characters to consider in \a charArray. + \param mode The \c font_metric_mode to use, screen or printing. + \param boundingBoxArray The destination array of BRect bounding boxes. +*/ + + +/*! + \fn void BFont::GetBoundingBoxesAsString(const char charArray[], + int32 numChars, font_metric_mode mode, escapement_delta *delta, + BRect boundingBoxArray[]) const + \brief Writes an array of BRect objects to \a boundingBoxArray + representing the bounding rectangles of each character in + \a charArray with consideration to the provided escapement + \a delta. + + Each BRect object corresponds to the glyph of one character. + + The \c font_metric_mode should contain one of the following values: + - \c B_SCREEN_METRIC The bounding boxes should use the screen metric. + - \c B_PRINTING_METRIC The bounding boxes should use the print metric. + + The \c escapement_delta structure contains the following values: + - \c nonspace The amount of space surrounding a character with a visible + glyph. + - \c space The amount of space surrounding a whitespace character, for + example \c B_TAB and \c B_SPACE. + + \param charArray The source character array. + \param numChars The number of characters to consider in \a charArray. + \param mode The \c font_metric_mode to use, screen or printing. + \param delta The \c escapement_delta structure to use. + \param boundingBoxArray The destination array of BRect bounding boxes. +*/ + + +/*! + \fn void BFont::_GetBoundingBoxes(const char charArray[], int32 numChars, + font_metric_mode mode, bool string_escapement, escapement_delta *delta, + BRect boundingBoxArray[], bool asString) const + \brief Writes an array of BRect objects to \a boundingBoxArray + representing the bounding rectangles of each character in + \a charArray with consideration to the provided escapement + \a delta and \a string_escapement. + + Each BRect object corresponds to the glyph of one character. + + The \c font_metric_mode should contain one of the following values: + - \c B_SCREEN_METRIC The bounding boxes should use the screen metric. + - \c B_PRINTING_METRIC The bounding boxes should use the print metric. + + The \c escapement_delta structure contains the following values: + - \c nonspace The amount of space surrounding a character with a visible + glyph. + - \c space The amount of space surrounding a whitespace character, for + example \c B_TAB and \c B_SPACE. + + \param charArray The source character array. + \param numChars The number of characters to consider in \a charArray. + \param mode The \c font_metric_mode to use, screen or printing. + \param string_escapement ??? + \param delta The \c escapement_delta structure to use. + \param boundingBoxArray The destination array of BRect bounding boxes. + \param asString ??? +*/ + + +/*! + \fn void BFont::GetBoundingBoxesForStrings(const char *stringArray[], + int32 numStrings, font_metric_mode mode, escapement_delta deltas[], + BRect boundingBoxArray[]) const + \brief Writes an array of BRect objects to \a boundingBoxArray + representing the bounding rectangles of each string in + \a stringArray with consideration to the provided escapement + \a delta. + + Each BRect object corresponds to the bounding box of the entire string. + + The \c font_metric_mode should contain one of the following values: + - \c B_SCREEN_METRIC The bounding boxes should use the screen metric. + - \c B_PRINTING_METRIC The bounding boxes should use the print metric. + + The \c escapement_delta structure contains the following values: + - \c nonspace The amount of space surrounding a character with a visible + glyph. + - \c space The amount of space surrounding a whitespace character, for + example \c B_TAB and \c B_SPACE. + + \param stringArray The source string array. + \param numStrings The number of strings to consider in \a stringArray. + \param mode The \c font_metric_mode to use, screen or printing. + \param deltas The array of \c escapement_delta structures to use. + \param boundingBoxArray The destination array of BRect bounding boxes. +*/ + + +/*! + void BFont::GetGlyphShapes(const char charArray[], int32 numChars, + BShape *glyphShapeArray[]) const + \brief Writes an array of BShape objects to \a glyphShapeArray + representing the glyph shapes of each character in + \a charArray. + + Each BShape object corresponds to the glyph of one character. + + \param charArray The source character array. + \param numChars The number of characters to consider in \a charArray. + \param glyphShapeArray The destination array of BShape glyphs. +*/ + + +/*! + void BFont::GetHasGlyphs(const char charArray[], int32 numChars, + bool hasArray[]) const + \brief Fills out \a hasArray with whether or not each characters in + \a charArray has a glyph for the font. + + \c true is written in \a hasArray if the character has a glyph in the + current font and \c false is written in \a hasArray if the character + does NOT have a glyph in the current font. + + \param charArray The source character array. + \param numChars The number of characters to consider in \a charArray. + \param hasArray The destination array of booleans. +*/ + + +/*! + BFont& BFont::operator=(const BFont &font) + \brief Assignment overload method. + + \param font The BFont object to assign from. +*/ + + +/*! + bool BFont::operator==(const BFont &font) const + \brief Equality comparison overload method. + + \param font The BFont object to compare the current font to. + + \returns \c true if the fonts objects are identical, \c false otherwise. +*/ + + +/*! + bool BFont::operator!=(const BFont &font) const + \brief Inequality comparison overload method. + + \param font The BFont object to compare the current font to. + + \returns \c true if the fonts objects are NOT identical, \c true + otherwise. +*/ + + +/*! + void BFont::PrintToStream() const + \brief Writes information about the font to \c stdout. + + printf("BFont { %s (%d), %s (%d) 0x%x %f/%f %fpt (%f %f %f), %d }\n", + family, fFamilyID, style, fStyleID, fFace, fShear, fRotation, fSize, + fHeight.ascent, fHeight.descent, fHeight.leading, fEncoding); +*/