From 538198776b61b8e36e9e01e968404738b390ec46 Mon Sep 17 00:00:00 2001 From: the_fiddler Date: Thu, 12 Feb 2009 23:10:09 +0000 Subject: [PATCH] Moved TextExtents to OpenTK.Graphics. Added documentation to all public classes and interfaces. --- Source/Utilities/Graphics/ITextPrinter.cs | 112 +++++++++++++++++- .../Graphics/{Text => }/TextExtents.cs | 44 ++++--- Source/Utilities/Graphics/TextPrinter.cs | 90 +++++++++++++- Source/Utilities/Graphics/TextQuality.cs | 7 ++ 4 files changed, 235 insertions(+), 18 deletions(-) rename Source/Utilities/Graphics/{Text => }/TextExtents.cs (74%) diff --git a/Source/Utilities/Graphics/ITextPrinter.cs b/Source/Utilities/Graphics/ITextPrinter.cs index 85375e6b..4f72e74a 100644 --- a/Source/Utilities/Graphics/ITextPrinter.cs +++ b/Source/Utilities/Graphics/ITextPrinter.cs @@ -17,19 +17,125 @@ namespace OpenTK.Graphics /// public interface ITextPrinter : IDisposable { - void Begin(); - void End(); + #region Print + + /// + /// Prints text using the specified color and layout options. + /// + /// The System.String to print. + /// The System.Drawing.Font that will be used to print text. + /// The System.Drawing.Color that will be used to print text. void Print(string text, Font font, Color color); + + /// + /// Prints text using the specified color and layout options. + /// + /// The System.String to print. + /// The System.Drawing.Font that will be used to print text. + /// The System.Drawing.Color that will be used to print text. + /// The System.Drawing.Rectangle that defines the bounds for text layout. void Print(string text, Font font, Color color, RectangleF rect); + + /// + /// Prints text using the specified color and layout options. + /// + /// The System.String to print. + /// The System.Drawing.Font that will be used to print text. + /// The System.Drawing.Color that will be used to print text. + /// The System.Drawing.Rectangle that defines the bounds for text layout. + /// The OpenTK.Graphics.TextPrinterOptions that will be used to print text. void Print(string text, Font font, Color color, RectangleF rect, TextPrinterOptions options); + + /// + /// Prints text using the specified color and layout options. + /// + /// The System.String to print. + /// The System.Drawing.Font that will be used to print text. + /// The System.Drawing.Color that will be used to print text. + /// The System.Drawing.Rectangle that defines the bounds for text layout. + /// The OpenTK.Graphics.TextPrinterOptions that will be used to print text. + /// The OpenTK.Graphics.TextAlignment that will be used to print text. void Print(string text, Font font, Color color, RectangleF rect, TextPrinterOptions options, TextAlignment alignment); + + /// + /// Prints text using the specified color and layout options. + /// + /// The System.String to print. + /// The System.Drawing.Font that will be used to print text. + /// The System.Drawing.Color that will be used to print text. + /// The System.Drawing.Rectangle that defines the bounds for text layout. + /// The OpenTK.Graphics.TextPrinterOptions that will be used to print text. + /// The OpenTK.Graphics.TextAlignment that will be used to print text. + /// The OpenTK.Graphics.TextDirection that will be used to print text. void Print(string text, Font font, Color color, RectangleF rect, TextPrinterOptions options, TextAlignment alignment, TextDirection direction); + + #endregion + + #region Measure + + /// + /// Measures text using the specified layout options. + /// + /// The System.String to measure. + /// The System.Drawing.Font that will be used to measure text. + /// The System.Drawing.Rectangle that defines the bounds for text layout. + /// An OpenTK.Graphics.TextExtents instance that contains the results of the measurement. TextExtents Measure(string text, Font font); + + /// + /// Measures text using the specified layout options. + /// + /// The System.String to measure. + /// The System.Drawing.Font that will be used to measure text. + /// The System.Drawing.Rectangle that defines the bounds for text layout. + /// The OpenTK.Graphics.TextPrinterOptions that will be used to measure text. + /// An OpenTK.Graphics.TextExtents instance that contains the results of the measurement. TextExtents Measure(string text, Font font, RectangleF rect); + + /// + /// Measures text using the specified layout options. + /// + /// The System.String to measure. + /// The System.Drawing.Font that will be used to measure text. + /// The System.Drawing.Rectangle that defines the bounds for text layout. + /// The OpenTK.Graphics.TextPrinterOptions that will be used to measure text. + /// The OpenTK.Graphics.TextAlignment that will be used to measure text. + /// An OpenTK.Graphics.TextExtents instance that contains the results of the measurement. TextExtents Measure(string text, Font font, RectangleF rect, TextPrinterOptions options); + + /// + /// Measures text using the specified layout options. + /// + /// The System.String to measure. + /// The System.Drawing.Font that will be used to measure text. + /// The System.Drawing.Rectangle that defines the bounds for text layout. + /// The OpenTK.Graphics.TextPrinterOptions that will be used to measure text. + /// The OpenTK.Graphics.TextAlignment that will be used to measure text. + /// An OpenTK.Graphics.TextExtents instance that contains the results of the measurement. TextExtents Measure(string text, Font font, RectangleF rect, TextPrinterOptions options, TextAlignment alignment); + + /// + /// Measures text using the specified layout options. + /// + /// The System.String to measure. + /// The System.Drawing.Font that will be used to measure text. + /// The System.Drawing.Rectangle that defines the bounds for text layout. + /// The OpenTK.Graphics.TextPrinterOptions that will be used to measure text. + /// The OpenTK.Graphics.TextAlignment that will be used to measure text. + /// The OpenTK.Graphics.TextDirection that will be used to measure text. + /// An OpenTK.Graphics.TextExtents instance that contains the results of the measurement. TextExtents Measure(string text, Font font, RectangleF rect, TextPrinterOptions options, TextAlignment alignment, TextDirection direction); + #endregion + + #region Obsolete + + [Obsolete] + void Begin(); + + [Obsolete] + void End(); + [Obsolete("Use TextPrinter.Print instead")] void Draw(TextHandle handle); @@ -38,5 +144,7 @@ namespace OpenTK.Graphics [Obsolete("Use TextPrinter.Print instead")] void Prepare(string text, TextureFont font, out TextHandle handle); + + #endregion } } diff --git a/Source/Utilities/Graphics/Text/TextExtents.cs b/Source/Utilities/Graphics/TextExtents.cs similarity index 74% rename from Source/Utilities/Graphics/Text/TextExtents.cs rename to Source/Utilities/Graphics/TextExtents.cs index 03a923a2..6362f42f 100644 --- a/Source/Utilities/Graphics/Text/TextExtents.cs +++ b/Source/Utilities/Graphics/TextExtents.cs @@ -30,9 +30,11 @@ using System.Collections.Generic; using System.Text; using System.Drawing; -namespace OpenTK.Graphics.Text +namespace OpenTK.Graphics { - // Holds layout information about a TextBlock. + /// + /// Holds the results of a text measurement. + /// public class TextExtents : IDisposable { #region Fields @@ -54,39 +56,42 @@ namespace OpenTK.Graphics.Text #region Public Members + /// + /// Gets the bounding box of the measured text. + /// public RectangleF BoundingBox { get { return text_extents; } internal set { text_extents = value; } } + /// + /// Gets the extents of each glyph in the measured text. + /// + /// The index of the glyph. + /// The extents of the specified glyph. public RectangleF this[int i] { get { return glyph_extents[i]; } internal set { glyph_extents[i] = value; } } + /// + /// Gets the extents of each glyph in the measured text. + /// public IEnumerable GlyphExtents { - get - { - return (IEnumerable)glyph_extents; - } + get { return (IEnumerable)glyph_extents; } } + /// + /// Gets the number of the measured glyphs. + /// public int Count { get { return glyph_extents.Count; } } - public TextExtents Clone() - { - TextExtents extents = new TextExtents(); - extents.glyph_extents.AddRange(GlyphExtents); - extents.BoundingBox = BoundingBox; - return extents; - } - #endregion #region Internal Members @@ -107,10 +112,21 @@ namespace OpenTK.Graphics.Text glyph_extents.Clear(); } + internal TextExtents Clone() + { + TextExtents extents = new TextExtents(); + extents.glyph_extents.AddRange(GlyphExtents); + extents.BoundingBox = BoundingBox; + return extents; + } + #endregion #region IDisposable Members + /// + /// Frees the resources consumed by this TextExtents instance. + /// public virtual void Dispose() { } diff --git a/Source/Utilities/Graphics/TextPrinter.cs b/Source/Utilities/Graphics/TextPrinter.cs index 6f46c6db..a96757d0 100644 --- a/Source/Utilities/Graphics/TextPrinter.cs +++ b/Source/Utilities/Graphics/TextPrinter.cs @@ -41,11 +41,15 @@ namespace OpenTK.Graphics #region Constructors /// - /// Constructs a new TextPrinter object. + /// Constructs a new TextPrinter instance. /// public TextPrinter() : this(null, null, TextQuality.Default) { } + /// + /// Constructs a new TextPrinter instance with the specified TextQuality level. + /// + /// The desired TextQuality of this TextPrinter. public TextPrinter(TextQuality quality) : this(null, null, quality) { } @@ -62,26 +66,66 @@ namespace OpenTK.Graphics #region Print + /// + /// Prints text using the specified color and layout options. + /// + /// The System.String to print. + /// The System.Drawing.Font that will be used to print text. + /// The System.Drawing.Color that will be used to print text. public void Print(string text, Font font, Color color) { Print(text, font, color, RectangleF.Empty, TextPrinterOptions.Default, TextAlignment.Near, TextDirection.LeftToRight); } + /// + /// Prints text using the specified color and layout options. + /// + /// The System.String to print. + /// The System.Drawing.Font that will be used to print text. + /// The System.Drawing.Color that will be used to print text. + /// The System.Drawing.Rectangle that defines the bounds for text layout. public void Print(string text, Font font, Color color, RectangleF rect) { Print(text, font, color, rect, TextPrinterOptions.Default, TextAlignment.Near, TextDirection.LeftToRight); } + /// + /// Prints text using the specified color and layout options. + /// + /// The System.String to print. + /// The System.Drawing.Font that will be used to print text. + /// The System.Drawing.Color that will be used to print text. + /// The System.Drawing.Rectangle that defines the bounds for text layout. + /// The OpenTK.Graphics.TextPrinterOptions that will be used to print text. public void Print(string text, Font font, Color color, RectangleF rect, TextPrinterOptions options) { Print(text, font, color, rect, options, TextAlignment.Near, TextDirection.LeftToRight); } + /// + /// Prints text using the specified color and layout options. + /// + /// The System.String to print. + /// The System.Drawing.Font that will be used to print text. + /// The System.Drawing.Color that will be used to print text. + /// The System.Drawing.Rectangle that defines the bounds for text layout. + /// The OpenTK.Graphics.TextPrinterOptions that will be used to print text. + /// The OpenTK.Graphics.TextAlignment that will be used to print text. public void Print(string text, Font font, Color color, RectangleF rect, TextPrinterOptions options, TextAlignment alignment) { Print(text, font, color, rect, options, alignment, TextDirection.LeftToRight); } + /// + /// Prints text using the specified color and layout options. + /// + /// The System.String to print. + /// The System.Drawing.Font that will be used to print text. + /// The System.Drawing.Color that will be used to print text. + /// The System.Drawing.Rectangle that defines the bounds for text layout. + /// The OpenTK.Graphics.TextPrinterOptions that will be used to print text. + /// The OpenTK.Graphics.TextAlignment that will be used to print text. + /// The OpenTK.Graphics.TextDirection that will be used to print text. public void Print(string text, Font font, Color color, RectangleF rect, TextPrinterOptions options, TextAlignment alignment, TextDirection direction) { if (disposed) @@ -97,27 +141,66 @@ namespace OpenTK.Graphics #region Measure + /// + /// Measures text using the specified layout options. + /// + /// The System.String to measure. + /// The System.Drawing.Font that will be used to measure text. + /// An OpenTK.Graphics.TextExtents instance that contains the results of the measurement. public TextExtents Measure(string text, Font font) { return Measure(text, font, RectangleF.Empty, TextPrinterOptions.Default, TextAlignment.Near, TextDirection.LeftToRight); } + /// + /// Measures text using the specified layout options. + /// + /// The System.String to measure. + /// The System.Drawing.Font that will be used to measure text. + /// The System.Drawing.Rectangle that defines the bounds for text layout. + /// An OpenTK.Graphics.TextExtents instance that contains the results of the measurement. public TextExtents Measure(string text, Font font, RectangleF rect) { return Measure(text, font, rect, TextPrinterOptions.Default, TextAlignment.Near, TextDirection.LeftToRight); } + /// + /// Measures text using the specified layout options. + /// + /// The System.String to measure. + /// The System.Drawing.Font that will be used to measure text. + /// The System.Drawing.Rectangle that defines the bounds for text layout. + /// The OpenTK.Graphics.TextPrinterOptions that will be used to measure text. + /// An OpenTK.Graphics.TextExtents instance that contains the results of the measurement. public TextExtents Measure(string text, Font font, RectangleF rect, TextPrinterOptions options) { return Measure(text, font, rect, options, TextAlignment.Near, TextDirection.LeftToRight); } - + /// + /// Measures text using the specified layout options. + /// + /// The System.String to measure. + /// The System.Drawing.Font that will be used to measure text. + /// The System.Drawing.Rectangle that defines the bounds for text layout. + /// The OpenTK.Graphics.TextPrinterOptions that will be used to measure text. + /// The OpenTK.Graphics.TextAlignment that will be used to measure text. + /// An OpenTK.Graphics.TextExtents instance that contains the results of the measurement. public TextExtents Measure(string text, Font font, RectangleF rect, TextPrinterOptions options, TextAlignment alignment) { return Measure(text, font, rect, options, alignment, TextDirection.LeftToRight); } + /// + /// Measures text using the specified layout options. + /// + /// The System.String to measure. + /// The System.Drawing.Font that will be used to measure text. + /// The System.Drawing.Rectangle that defines the bounds for text layout. + /// The OpenTK.Graphics.TextPrinterOptions that will be used to measure text. + /// The OpenTK.Graphics.TextAlignment that will be used to measure text. + /// The OpenTK.Graphics.TextDirection that will be used to measure text. + /// An OpenTK.Graphics.TextExtents instance that contains the results of the measurement. public TextExtents Measure(string text, Font font, RectangleF rect, TextPrinterOptions options, TextAlignment alignment, TextDirection direction) { if (disposed) @@ -260,6 +343,9 @@ namespace OpenTK.Graphics #region IDisposable Members + /// + /// Frees the resources consumed by this TextPrinter object. + /// public void Dispose() { if (!disposed) diff --git a/Source/Utilities/Graphics/TextQuality.cs b/Source/Utilities/Graphics/TextQuality.cs index 3a659fcb..67275d1c 100644 --- a/Source/Utilities/Graphics/TextQuality.cs +++ b/Source/Utilities/Graphics/TextQuality.cs @@ -4,11 +4,18 @@ using System.Text; namespace OpenTK.Graphics { + /// + /// Defines available quality levels for text printing. + /// public enum TextQuality { + /// Use the default quality, as specified by the operating system. Default = 0, + /// Use fast, low quality text (typically non-antialiased) . Low, + /// Use medium quality text (typically grayscale antialiased). Medium, + /// Use slow, high quality text (typically subpixel antialiased). High } }