Windows Forms

Supporting the Tablet PC from Panel - Part IV

Pete Vidler — Sun, 19 Oct 2003 01:15:00 GMT

In a comment on the original post of this series, Kollen Glynn points out that I could specify a bounding rectangle to the Invalidate() call in the Stroke method. Here's the code for that alteration:

    // The event that this method handles is raised whenever
    // a stroke is completed (the pen leaves the surface)
    private void Stroke( object sender,
                         InkCollectorStrokeEventArgs e )
    {
        // Make sure we only invalidate the necessary region
        Rectangle bounds = e.Stroke.GetBoundingBox();

        // GetBoundingBox uses Ink Space coords, so convert
        using( Graphics g = CreateGraphics() )
            InkSpaceToPixel( g, ref bounds );

        // The false here means that we don't refresh the
        // control's children. You might want to use true
        // if you are using InkOverlayAttachMode.InFront
        Invalidate( bounds, false );

        // For some reason, this must come after the call
        // to Invalidate. Otherwise the stroke is not redrawn
        if ( inkMode == InkMode.Highlight )
            e.Stroke.ExtendedProperties.Add( HighlightGuid, inkMode );
    }

I also wrote a helper method to deal with converting a Rectangle from Ink space to pixel space:

    // Convert an Ink Space Rectangle to Pixel Space
    private void InkSpaceToPixel( Graphics g, ref Rectangle rect )
    {
        // Cannot pass a reference of a property,
        // so we need to make copies of each
        Point topLeft = rect.Location;
        Point bottomRight = rect.Location + rect.Size;

        // Convert both temporaries to pixel space
        ink.Renderer.InkSpaceToPixel( g, ref topLeft );
        ink.Renderer.InkSpaceToPixel( g, ref bottomRight );

        // Repackage our new values as a Rectangle
        rect.Location = topLeft;
        rect.Size = ( Size )bottomRight - ( Size )topLeft;
    }

At this point it occurred to me that it would probably be better to only draw those strokes that fall within the clipping rectangle. In order to do this I've changed the painting code quite a lot, moving the actual drawing into two separate methods:

    /// <summary>
    /// Overrides <see cref="Control"/>.OnPaint.
    /// </summary>
    protected override void OnPaint( PaintEventArgs e )
    {
        // Doing all our redrawing here enables us to take
        // full advantage of the automatic double buffering
        base.OnPaint( e );

        // Adjust for any change in the view position
        HandleScroll();

        // Draw all the strokes, clipped appropriately
        DrawInk( e.Graphics, e.ClipRectangle );

        // If you aren't selecting you can go home now :)
        if ( inkMode != InkMode.Select )
            return;

        // Draw all selected ink, regardless of clipping
        DrawSelectedInk( e.Graphics );
    }

The method to draw selected ink strokes uses the same approach as before, except that I no longer bother with the second drawing operation if the stroke is a highlight. This is because the white centre is never visible for selected highlights anyway, so drawing it would be a waste of time.

    // Draw all the selected ink. Does not bother with
    // testing to see if strokes are in the clipping region
    private void DrawSelectedInk( Graphics g )
    {
        Strokes strokes = ink.Selection;
        Renderer render = ink.Renderer;

        // Get the amount to increase size of selected lines
        Point strokeExtra = new Point( 4, 4 );
        render.PixelToInkSpace( g, ref strokeExtra );

        // Redraw the selection strokes as they should look
        for( int i = 0; i < strokes.Count; ++i )
        {
            Stroke stroke = strokes[i];
            DrawingAttributes da = stroke.DrawingAttributes.Clone();

            // Draw the extra thick stroke
            da.IgnorePressure = true;
            da.Width += strokeExtra.X;
            da.Height += strokeExtra.Y;
            render.Draw( g, stroke, da );

            // The second draw doesn't show for highlights
            // so there's no need to bother with it
            ExtendedProperties ep = stroke.ExtendedProperties;
            if ( ep.DoesPropertyExist( HighlightGuid ) )
                continue;

            // Draw the white center
            da.Width -= strokeExtra.X;
            da.Height -= strokeExtra.Y;
            da.Color = Color.White;
            render.Draw( g, stroke, da );
        }
    }

There are quite a few changes to the way I'm drawing normal ink strokes. Firstly, I'm not drawing selected strokes here anymore (since they get drawn afterwards anyway). Secondly, each stroke's bounding box is tested against the clipping rectangle to determine if it should be drawn:

    // Draw all the non-selected ink. Tests each
    // stroke to ensure it should be drawn
    private void DrawInk( Graphics g, Rectangle clip )
    {
        Strokes strokes = ink.Ink.Strokes;
        Strokes selection = ink.Selection;
        Renderer render = ink.Renderer;
        Rectangle bounds;

        // Draw all the non-selected strokes
        for( int i = 0; i < strokes.Count; ++i )
        {
            Stroke stroke = strokes[i];

            // Don't bother drawing the selection here
            if ( selection.Contains( stroke ) )
                continue;

            // Don't bother drawing if it's not needed
            bounds = stroke.GetBoundingBox();
            InkSpaceToPixel( g, ref bounds );
            if ( !clip.IntersectsWith( bounds ) )
                continue;

            // Just draw the damn thing already!
            render.Draw( g, stroke );
        }
    }

I have no idea if this testing against the clipping rectangle actually produces a performance increase or not. It certainly doesn't seem to hurt performance on my machine (which is a laptop, not a tablet), but you should probably try benchmarking or profiling to see if you need this yourself. I don't bother doing this for the selected strokes because there are generally fewer of them, and the testing is much harder (you have to compensate for the extra size).

As always, enjoy and let me know if there are problems with it.

EDIT: Corrected a nasty little error that got the size wrong in InkSpaceToPixel.

Supporting the Tablet PC from Panel - Part III

Pete Vidler — Fri, 17 Oct 2003 23:40:00 GMT

The key problem with the code in my first post is that it renders all strokes the same. Even if they are selected. If you can tolerate this (it doesn't look too bad as you still get the selection frame), then go ahead and use that code.

Sadly, I'm a perfectionist. I searched long and hard for a built in way to get selected strokes drawn properly. Long story short: there isn't one. Fortunately, I stumbled upon a sample chapter from "Building Tablet PC Applications" which has a solution (talk about lucky)! The book looks like it's probably worth the money if you are serious about Tablet PC support, so I would suggest buying it.

Anyway, here's the newly modified OnPaint override (this is very close to the books code, with a few very minor alterations):

    /// <summary>
    /// Overrides <see cref="Control"/>.OnPaint.
    /// </summary>
    protected override void OnPaint( PaintEventArgs e )
    {
        base.OnPaint( e );

        // Adjust for any change in the view position
        HandleScroll();

        // Doing all our redrawing here enables us to take
        // full advantage of the automatic double buffering
        ink.Renderer.Draw( e.Graphics, ink.Ink.Strokes );

        // If you aren't selecting you can go home now :)
        if ( inkMode != InkMode.Select )
            return;

        // Get the amount to increase size of selected lines
        Point strokeExtra = new Point( 4, 4 );
        ink.Renderer.PixelToInkSpace( e.Graphics, ref strokeExtra );

        // Redraw the selection strokes as they should look
        for( int i = 0; i < ink.Selection.Count; ++i )
        {
            // You could use foreach here for simplicity,
            // but for is faster and faster is good here
            Stroke stroke = ink.Selection[i];

            DrawingAttributes da = stroke.DrawingAttributes.Clone();

            // Draw the extra thick stroke
            da.IgnorePressure = true;
            da.Width += strokeExtra.X;
            da.Height += strokeExtra.Y;
            ink.Renderer.Draw( e.Graphics, stroke, da );

            // Draw the white center
            da.Width -= strokeExtra.X;
            da.Height -= strokeExtra.Y;

            // Uncomment these four lines to try something
            // different when the stroke is a highlight. If
            // you use this method, any stroke under the
            // highlight will not be shown, and the white
            // center will not be smoothed:

            //ExtendedProperties ep = stroke.ExtendedProperties;
            //if ( ep.DoesPropertyExist( HighlightGuid ) )
            // da.RasterOperation = RasterOperation.White;
            //else
                da.Color = Color.White;

            ink.Renderer.Draw( e.Graphics, stroke, da );
        }
    }

Notice the code that is commented out. This provides a slightly different method for displaying selected highlights. I recommend you try the code with and without this to see which you prefer (I prefer without). If you look at the very end of that sample chapter, you will find a slightly fancier way of drawing selected strokes that you could also use if you prefer.

By the way, all of this code should work if we derive from UserControl as well. In fact you should be able to inherit from any class that itself inherits from ScrollableControl.

So that concludes my ramblings about the Tablet PC. If you have anything else you want me to write about, please let me know (comments are best -- dodgy email still :) ).

Supporting the Tablet PC from Panel - Part II

Pete Vidler — Fri, 17 Oct 2003 22:36:00 GMT

This time I'll be adding a few more properties to the InkPanel, including a way to change the mode of the Ink and some support for changing colours. As an added bonus, I'll add support for separate highlighting including a way to separate the highlights from the ordinary ink.

Changing the Mode

The InkOverlay object has support for three basic editing modes: Ink, Select and Delete. I also want two more of my own, specifically Highlight and Disabled. In order to achieve this we can add a new enumeration that will be used to specify the mode to set:

/// <summary>
/// Specifies the mode that the <see cref="InkPanel"/>
/// should be set to.
/// </summary>
public enum InkMode
{
    /// <summary>Standard drawing mode.</summary>
    Ink = InkOverlayEditingMode.Ink,
    /// <summary>Deletion mode.</summary>
    Delete = InkOverlayEditingMode.Delete,
    /// <summary>Selection mode.</summary>
    Select = InkOverlayEditingMode.Select,
    /// <summary>Highlighter mode.</summary>
    Highlight,
    /// <summary>
    /// Disable ink support so we can access the
    /// <see cref="InkPanel"/> directly.
    /// </summary>
    Disabled
}

Now that we have a way of representing the mode, we'll be needing a property to control it. The set method has a bit of work to do in order to correctly clean up from the previous mode and set up the new one, but it isn't too complicated. We helped ourselves quite a bit by making the enumeration map directly to InkOverlayEditingMode, so we don't need to mess around converting between the two. Notice that we also include the underlying private variable for the property. You can add this code to the appropriate place in the class yourself, I won't waste space with complete code here.

    /// <summary>
    /// Gets or sets the Ink mode for the <see cref="InkPanel"/>
    /// </summary>
    /// <remarks>
    /// The Ink mode can be set to any value of the
    /// <see cref="InkMode"/> enumeration.
    /// </remarks>
    public InkMode InkMode
    {
        get { return inkMode; }
        set
        {
            // Simplify things later by ensuring it changes
            if ( value == inkMode )
                return;

            ink.Enabled = false;

            // Turn off highlighting
            if ( inkMode == InkMode.Highlight )
                SetHighlightMode( false );
            // Remove the old selection
            else if ( inkMode == InkMode.Select )
                ink.Selection = ink.Ink.CreateStrokes();

            inkMode = value;

            // Deal with the two special cases
            if ( inkMode == InkMode.Disabled )
                return;
            else if ( inkMode == InkMode.Highlight )
            {
                SetHighlightMode( true );
                ink.Enabled = true;
                return;
            }

            // InkMode should map directly onto the EditingMode
            ink.EditingMode = ( InkOverlayEditingMode )inkMode;

            ink.Enabled = true;
        }
    }

    private InkMode inkMode = InkMode.Ink;

That's it for the simple stuff, now on to something more fun.

Changing the Pen Colour

Before we can look into changing the pen colour, we need to decide on a highlighting strategy. Since I wanted to keep highlights separate from normal ink, I have chosen to add an ExtendedProperty to each highlight and test for it when changing colours.

It turns out that changing the pen colour is even easier than setting the mode. The only hassle here is to make sure we don't change the colour of any highlights by mistake. To do this we can loop through all the strokes in the selection and test each one for the property that we set on highlights (which I'll detail in the next section):

    /// <summary>
    /// Gets or sets the color to use for normal inking.
    /// </summary>
    /// <remarks>
    /// If we are in selection mode and this property is set,
    /// then any normal ink strokes that are selected will be
    /// changed to this color.
    /// </remarks>
    public Color InkColor
    {
        get { return inkColor; }
        set
        {
            inkColor = value;

            // Don't bother with highlights, they are separate
            if ( inkMode == InkMode.Highlight )
                return;

            ink.Enabled = false;
            ink.DefaultDrawingAttributes.Color = inkColor;

            // Change the color for every selected ink stroke
            if ( inkMode == InkMode.Select )
            {
                foreach( Stroke stroke in ink.Selection )
                {
                    ExtendedProperties ep;
                    ep = stroke.ExtendedProperties;

                    // Don't change highlights
                    if ( !ep.DoesPropertyExist( HighlightGuid ) )
                        stroke.DrawingAttributes.Color = inkColor;
                }
            }
            ink.Enabled = true;
        }
    }

    private Color inkColor = Color.Black;

Setting the colour of the highlights is almost exactly the same. The only real difference is that we test for the presence of the ExtendedProperty, not it's absence:

    /// <summary>
    /// Gets or sets the color to use for highlighting.
    /// </summary>
    /// <remarks>
    /// If we are in selection mode and this property is set,
    /// then any highlights that are selected will be changed
    /// to this color.
    /// </remarks>
    public Color HighlightColor
    {
        get { return highlightColor; }
        set
        {
            highlightColor = value;

            ink.Enabled = false;
            if ( inkMode == InkMode.Select )
            {
                // Change the color of any selected highlights
                foreach( Stroke stroke in ink.Selection )
                {
                    ExtendedProperties ep;
                    ep = stroke.ExtendedProperties;

                    if ( ep.DoesPropertyExist( HighlightGuid ) )
                        stroke.DrawingAttributes.Color = value;
                }
            }

            // Don't go any further if we aren't highlighting
            if ( inkMode != InkMode.Highlight )
            {
                ink.Enabled = true;
                return;
            }

            SetHighlightMode( false );
            SetHighlightMode( true );
            ink.Enabled = true;
        }
    }

    private Color highlightColor = Color.Yellow;

Highlighting

In order to make highlighting work properly, we'll be needing to implement the SetHighlightMode method used earlier. There are a number of different options that this method must set, all of them based around the DefaultDrawingAttributes class. You can look them up in the SDK documentation if you want a better idea of what they all do. I borrowed the approach for this highlighting from here.

    // Setup the highlighting mode to mimic Journal
    private void SetHighlightMode( bool highlighting )
    {
        DrawingAttributes da = ink.DefaultDrawingAttributes;

        if ( highlighting )
        {
            // Ensure we aren't erasing or selecting
            ink.EditingMode = InkOverlayEditingMode.Ink;

            // Save the old values to go back to later
            oldPenTip = da.PenTip;
            oldWidth = da.Width;
            oldHeight = da.Height;
            oldRast = da.RasterOperation;

            // Set our highlighting values
            da.PenTip = PenTip.Rectangle;
            da.Width = 250;
            da.Height = 400;
            da.Color = highlightColor;
            da.RasterOperation = RasterOperation.MaskPen;
        }
        else
        {
            // Reset the old values, or defaults if
            // there aren't any values stored
            da.Color = inkColor;
            da.RasterOperation = oldRast;
            da.Height = oldHeight;
            da.Width = oldWidth;
            da.PenTip = oldPenTip;
        }
    }

    private RasterOperation oldRast = RasterOperation.CopyPen;
    private float oldWidth = 53;
    private float oldHeight = 1;
    private PenTip oldPenTip = PenTip.Ball;

Now all we need to do is apply the ExtendedProperty to highlight strokes in the Stroke method. For some reason, this property must be changed after we have called Invalidate or the stroke does not get redrawn (on my system):

    // The event that this method handles is raised whenever
    // a stroke is completed (the pen leaves the surface)
    private void Stroke( object sender,
                         InkCollectorStrokeEventArgs e )
    {
        // Redraw the ink so it is smoothed immediately,
        // not on the first update as is the default
        Invalidate();

        // For some reason, this must come after the call
        // to Invalidate. Otherwise the stroke is not redrawn
        if ( inkMode == InkMode.Highlight )
            e.Stroke.ExtendedProperties.Add( HighlightGuid, inkMode );
    }

We'll be needing a GUID for the ExtendedProperty. You can generate your own with the uuidgen command line utility.

private Guid HighlightGuid = new Guid( "your-GUID-here" );

Conclusion

Well, that's it. Hopefully I've not forgotten anything and I hope you enjoy it. Next time I'll post about getting the selection to display properly (it doesn't when you draw the strokes yourself).

Supporting the Tablet PC from Panel

Pete Vidler — Thu, 16 Oct 2003 21:35:00 GMT

Note: This has been rewritten to follow a much better approach that I found shortly after first posting.

I recently had the opportunity to watch The .NET Show's latest installment, all about programming for the Tablet PC on .NET. The ease with which they added Ink support to an application in the show inspired me to try it for myself. I started by checking the internet for samples (as you do :) ), and found the Tablet PC Developer website.

On that website there are a large number of samples available, from serializing Ink to adding Ink support to a scrollable picturebox. One in particular caught my eye: "Smoothing Ink". Basically, the author suggests you use DrawingAttributes.FitToCurve for smoothing and some Win32 interop to get a double buffered effect. This technique seems to be necessary if you are trying to draw to a bitmap object, but is overkill if you just want to draw to a control.

I've decided to take a different approach. I've inherited from Panel and used the .NET Framework's built in support for double buffering (quite easy with InkOverlay's AutoRedraw property set to false). Originally I had a great deal of trouble supporting the Panel's built in scrolling, but soon after posting I found a better way. Every time the control is painted I simply check to see if the scroll position has moved and update the InkOverlay accordingly, which is much better than detecting the scrolling as I was doing originally. Here's the code:

using System;
using System.Drawing;
using System.Windows.Forms;

using Microsoft.Ink;

/// <summary>
/// Represents a standard <see cref="Panel"/> with Ink
/// functionality.
/// </summary>
/// <remarks>
/// Probably requires the Tablet PC SDK to compile. Almost
/// certainly requires either Windows XP Tablet edition or
/// the redistributable runtime (you have this if you did
/// Windows Update and installed the Journal Viewer) in
/// order to run correctly.
/// </remarks>
public class InkPanel : Panel
{
    /// <summary>
    /// Initializes a new instance of the <see cref="InkPanel"/>
    /// class.
    /// </summary>
    public InkPanel()
    {
        // Make sure we are double buffering or ink flickers
        SetStyle( ControlStyles.AllPaintingInWmPaint, true );
        SetStyle( ControlStyles.DoubleBuffer, true );
        SetStyle( ControlStyles.UserPaint, true );
        SetStyle( ControlStyles.ResizeRedraw, true );
        UpdateStyles();

        ink = new InkOverlay( Handle );
        ink.Stroke += new InkCollectorStrokeEventHandler( Stroke );

        // Setting this property to true enables smoothing
        ink.DefaultDrawingAttributes.FitToCurve = true;

        // Setting this property to false means we have to do
        // all redrawing of the ink ourselves in OnPaint
        ink.AutoRedraw = false;
        ink.Enabled = true;
    }

    /// <summary>
    /// Overrides <see cref="Control"/>.Dispose.
    /// </summary>
    protected override void Dispose( bool disposing )
    {
        // InkOverlay is managed, so only dispose if necessary
        if ( disposing )
            ink.Dispose();
    }

    /// <summary>
    /// Overrides <see cref="Control"/>.OnPaint.
    /// </summary>
    protected override void OnPaint( PaintEventArgs e )
    {
        base.OnPaint( e );

        // Adjust for any change in the view position
        HandleScroll();

        // Doing all our redrawing here enables us to take
        // full advantage of the automatic double buffering
        ink.Renderer.Draw( e.Graphics, ink.Ink.Strokes );
    }

    // Deal with any scrolling messages
    private void HandleScroll()
    {
        // We can be called without actually having scrolled
        if ( oldScrollPos == AutoScrollPosition )
            return;

        // These get altered, so take copies
        Point oldPos = oldScrollPos;
        Point newPos = AutoScrollPosition;

        using( Graphics g = CreateGraphics() )
        {
            // Transform pixels to more useful units
            ink.Renderer.PixelToInkSpace( g, ref oldPos );
            ink.Renderer.PixelToInkSpace( g, ref newPos );

            // Move the ink to match the new scroll position.
            // Notice that newPos and oldPos are negative, so
            // this order is required to get the right result
            ink.Renderer.Move( newPos.X - oldPos.X,
                               newPos.Y - oldPos.Y );
        }

        // Must update our old position
        oldScrollPos = AutoScrollPosition;
    }

    // The event that this method handles is raised whenever
    // a stroke is completed (the pen leaves the surface)
    private void Stroke( object sender,
                         InkCollectorStrokeEventArgs e )
    {
        // Redraw the ink so it is smoothed immediately,
        // not on the first update as is the default
        Invalidate();
    }

    // This would have been called "inkOverlay" but it takes
    // up too much horizontal space to be posted on a weblog
    private InkOverlay ink;

    // Store our old position to determine when view changes
    private Point oldScrollPos;
}

Notice that we no longer need the WndProc or OnMouseWheel overrides, because the new approach is to detect any scrolling directly from OnPaint. This is a much nicer method because it accounts for any change in AutoScrollPosition, not just scrolling by the user.

My next post will add some properties to the InkPanel allowing the editing mode to be changed.

EDIT: Major change in the approach used.

Extending RichTextBox - Part III

Pete Vidler — Thu, 16 Oct 2003 00:33:00 GMT

As promised earlier, I've added the ability to change the background colour of the text. I've also made one or two minor changes to the rest of the code, which I'll detail at the end.

Background Colour

Changing the background colour is a simple matter. It works in exactly the same way as changing the underline style, by setting the character format. Since we're dealing with Color here, we need to be using System.Drawing. Then it's just a matter of sending the correct message:

+ Code to set the background colour for a selected region.

/// <summary>
/// Gets or sets the background color to apply to the
/// current selection or insertion point.
/// </summary>
/// <remarks>
/// If the selection contains more than one background
/// color, then this property will indicate it by
/// returning Color.Empty.
/// </remarks>
public Color SelectionBackColor
{
    get
    {
        CHARFORMAT fmt = new CHARFORMAT();
        fmt.cbSize = Marshal.SizeOf( fmt );
        
        // Get the background color.
        SendMessage( new HandleRef( this, Handle ), EM_GETCHARFORMAT,
                     SCF_SELECTION, ref fmt );
        
        // Default to Color.Empty as there could be
        // several colors present in this selection.
        if ( ( fmt.dwMask & CFM_BACKCOLOR ) == 0 )
            return Color.Empty;
        
        // Deal with the weird Windows color format.
        int backCol = fmt.crBackColor;
        Color ret = ColorTranslator.FromWin32( backCol );
        
        return ret;
    }
    
    set
    {
        CHARFORMAT fmt = new CHARFORMAT();
        fmt.cbSize = Marshal.SizeOf( fmt );
        fmt.dwMask = CFM_BACKCOLOR;
        
        // Deal with the weird Windows color format.
        fmt.crBackColor = ColorTranslator.ToWin32( value );
        
        // Set the background color.
        SendMessage( new HandleRef( this, Handle ), EM_SETCHARFORMAT,
                     SCF_SELECTION, ref fmt );
    }
}

And there's one more constant to add:

private const int CFM_BACKCOLOR = 67108864;

That should now enable us to change the background colour of the text. Simple, wasn't it?

Alterations

Notice in the middle of the get method above, we return Color.Empty by default. This is because that return value is used when more than one colour is selected (like in Word when you select across several fonts and the font selection combobox goes blank). A similar approach can be taken in the alignment and underline properties presented previously.

All you have to do is add an entry to the relevant enumeration called "None" (or whatever), probably equal to zero, and return it in the appropriate get method where it says "Default to <whatever>".

Conclusion

That's it for AdvRichTextBox. If anyone is actually reading this and wants me to add more functionality (or post complete source), just leave a comment or send me an email.

Extending RichTextBox - Part II

Pete Vidler — Wed, 15 Oct 2003 14:19:00 GMT

Microsoft Word and Visual Studio have one very cool feature in common -- squiggly underlining of errors. As of richedit 3.0 (distributed with Windows 2000 and higher, possibly also with ME) we can get these in the RichTextBox. Actually, we can get a lot more underline styles than that...

Underlining

Once again we are going to have to communicate with the underlying richedit control. This time we need to set the character format, so we'll need to add some extra stuff to our class:

+ Code to interface with the Win32 CHARFORMAT2 structure.

private const int CFM_UNDERLINETYPE = 8388608;
private const int EM_SETCHARFORMAT = 1092;
private const int EM_GETCHARFORMAT = 1082;

[StructLayout( LayoutKind.Sequential )]
private struct CHARFORMAT
{
    public int cbSize;
    public uint dwMask;
    public uint dwEffects;
    public int yHeight;
    public int yOffset;
    public int crTextColor;
    public byte bCharSet;
    public byte bPitchAndFamily;
    [MarshalAs( UnmanagedType.ByValArray, SizeConst = 32 )]
    public char[] szFaceName;
    
    // CHARFORMAT2 from here onwards.
    public short wWeight;
    public short sSpacing;
    public int crBackColor;
    public int LCID;
    public uint dwReserved;
    public short sStyle;
    public short wKerning;
    public byte bUnderlineType;
    public byte bAnimation;
    public byte bRevAuthor;
}

[DllImport( "user32", CharSet = CharSet.Auto )]
private static extern int SendMessage( HandleRef hWnd, int msg,
                                       int wParam, ref CHARFORMAT lp );

Underline Style

The underline style and colour are both set with the same message, so we must be careful to preserve the colour while changing the underline style. We'll use a property again so that we remain consistent with the original RichTextBox:

+ Code to set the underline style.

/// <summary>
/// Gets or sets the underline style to apply to the
/// current selection or insertion point.
/// </summary>
/// <remarks>
/// Underline styles can be set to any value of the
/// <see cref="UnderlineStyle"/> enumeration.
/// </remarks>
public UnderlineStyle SelectionUnderlineStyle
{
    get
    {
        CHARFORMAT fmt = new CHARFORMAT();
        fmt.cbSize = Marshal.SizeOf( fmt );
        
        // Get the underline style.
        SendMessage( new HandleRef( this, Handle ), EM_GETCHARFORMAT,
                     SCF_SELECTION, ref fmt );
        
        // Default to no underline.
        if ( ( fmt.dwMask & CFM_UNDERLINETYPE ) == 0 )
            return UnderlineStyle.None;
        
        byte style = ( byte )( fmt.bUnderlineType & 0x0F );
        
        return ( UnderlineStyle )style;
    }
    
    set
    {
        // Ensure we don't alter the color by accident.
        UnderlineColor color = SelectionUnderlineColor;
        
        // Ensure we don't show it if it shouldn't be shown.
        if ( value == UnderlineStyle.None )
            color = UnderlineColor.Black;
        
        CHARFORMAT fmt = new CHARFORMAT();
        fmt.cbSize = Marshal.SizeOf( fmt );
        fmt.dwMask = CFM_UNDERLINETYPE;
        fmt.bUnderlineType = ( byte )( ( byte )value | ( byte )color );
        
        // Set the underline type.
        SendMessage( new HandleRef( this, Handle ), EM_SETCHARFORMAT,
                     SCF_SELECTION, ref fmt );
    }
}

Once again, this has not been fully tested so you use it at your own risk. Let me know if there are any problems, etc. The UnderlineStyle enumeration is also fairly straightforward:

+ UnderlineStyle enumeration.

/// <summary>
/// Specifies the style of underline that should be
/// applied to the text.
/// </summary>
public enum UnderlineStyle
{
    /// <summary>
    /// No underlining.
    /// </summary>
    None = 0,
    
    /// <summary>
    /// Standard underlining across all words.
    /// </summary>
    Normal = 1,
    
    /// <summary>
    /// Standard underlining broken between words.
    /// </summary>
    Word = 2,
    
    /// <summary>
    /// Double line underlining.
    /// </summary>
    Double = 3,
    
    /// <summary>
    /// Dotted underlining.
    /// </summary>
    Dotted = 4,
    
    /// <summary>
    /// Dashed underlining.
    /// </summary>
    Dash = 5,
    
    /// <summary>
    /// Dash-dot ("-.-.") underlining.
    /// </summary>
    DashDot = 6,
    
    /// <summary>
    /// Dash-dot-dot ("-..-..") underlining.
    /// </summary>
    DashDotDot = 7,
    
    /// <summary>
    /// Wave underlining (like spelling mistakes in MS Word).
    /// </summary>
    Wave = 8,
    
    /// <summary>
    /// Extra thick standard underlining.
    /// </summary>
    Thick = 9,
    
    /// <summary>
    /// Extra thin standard underlining.
    /// </summary>
    HairLine = 10,
    
    /// <summary>
    /// Double thickness wave underlining.
    /// </summary>
    DoubleWave = 11,
    
    /// <summary>
    /// Thick wave underlining.
    /// </summary>
    HeavyWave = 12,
    
    /// <summary>
    /// Extra long dash underlining.
    /// </summary>
    LongDash = 13
}

Note that some of these styles may not display correctly. This is a common problem with the richedit control, often you will apply some formatting only to find that it will not display at all. The formatting is usually stored though, so cutting and pasting into Word will show the text correctly.

Underline Colour

We can also change the underline colour. Notice how the set method of underline colour retrieves the underline style in order to maintain consistency.

+ Code to set the underline colour.

/// <summary>
/// Gets or sets the underline color to apply to the
/// current selection or insertion point.
/// </summary>
/// <remarks>
/// Underline colors can be set to any value of the
/// <see cref="UnderlineColor"/> enumeration.
/// </remarks>
public UnderlineColor SelectionUnderlineColor
{
    get
    {
        CHARFORMAT fmt = new CHARFORMAT();
        fmt.cbSize = Marshal.SizeOf( fmt );
        
        // Get the underline color.
        SendMessage( new HandleRef( this, Handle ), EM_GETCHARFORMAT,
                     SCF_SELECTION, ref fmt );
        
        // Default to black.
        if ( ( fmt.dwMask & CFM_UNDERLINETYPE ) == 0 )
            return UnderlineColor.Black;
        
        byte style = ( byte )( fmt.bUnderlineType & 0xF0 );
        
        return ( UnderlineColor )style;
    }
    
    set
    {
        // Ensure we don't alter the style.
        UnderlineStyle style = SelectionUnderlineStyle;
        
        // Ensure we don't show it if it shouldn't be shown.
        if ( style == UnderlineStyle.None )
            value = UnderlineColor.Black;
        
        CHARFORMAT fmt = new CHARFORMAT();
        fmt.cbSize = Marshal.SizeOf( fmt );
        fmt.dwMask = CFM_UNDERLINETYPE;
        fmt.bUnderlineType = ( byte )( ( byte )style | ( byte )value );
        
        // Set the underline color.
        SendMessage( new HandleRef( this, Handle ), EM_SETCHARFORMAT,
                     SCF_SELECTION, ref fmt );
    }
}

Unfortunately there are not many colours available to this property. They are defined by the UnderlineColor enumeration:

+ UnderlineColor enumeration.

/// <summary>
/// Specifies the color of underline that should be
/// applied to the text.
/// </summary>
/// <remarks>
/// I named these colors by their appearance, so some
/// of them might not be what you expect. Please email
/// me if you feel one should be changed.
/// </remarks>
public enum UnderlineColor
{
    /// <summary>Black.</summary>
    Black = 0x00,
    
    /// <summary>Blue.</summary>
    Blue = 0x10,
    
    /// <summary>Cyan.</summary>
    Cyan = 0x20,
    
    /// <summary>Lime green.</summary>
    LimeGreen = 0x30,
    
    /// <summary>Magenta.</summary>
    Magenta = 0x40,
    
    /// <summary>Red.</summary>
    Red = 0x50,
    
    /// <summary>Yellow.</summary>
    Yellow = 0x60,
    
    /// <summary>White.</summary>
    White = 0x70,
    
    /// <summary>DarkBlue.</summary>
    DarkBlue = 0x80,
    
    /// <summary>DarkCyan.</summary>
    DarkCyan = 0x90,
    
    /// <summary>Green.</summary>
    Green = 0xA0,
    
    /// <summary>Dark magenta.</summary>
    DarkMagenta = 0xB0,
    
    /// <summary>Brown.</summary>
    Brown = 0xC0,
    
    /// <summary>Olive green.</summary>
    OliveGreen = 0xD0,
    
    /// <summary>Dark gray.</summary>
    DarkGray = 0xE0,
    
    /// <summary>Gray.</summary>
    Gray = 0xF0
}

If you set the underline colour to anything other than black it will not serialise correctly. I don't know if this is by design or not. Any text with a non-black underline that is cut and pasted into Word (or any other application) will lose it's underlining all together. I don't know if the underline is still stored in the actual rich text or not when this happens.

Conclusion

Well that's it for part two. In my next post in this series I will cover setting the background colour.

Extending RichTextBox

Pete Vidler — Tue, 14 Oct 2003 22:02:00 GMT

For a while now I've been toying with the idea of writing a C# editor (almost an IDE, but with only the features that I need). Clearly the hardest part of this task would be getting some form of edit control working.. the obvious choice for which is the RichTextBox. Anyone who has tried using RichTextBox in this situation will know that it has a number of flaws, the most serious being that it's rather slow when trying to colourise the text.

I've long since given up on using RichTextBox for a code editor, but while I was investigating its use I came across a number of ways to improve it's functionality. I'll present these here in a series of posts on the subject.. first up is how to speed up the control's updating, as well as adding one little extra formatting option.

Faster Updating

There are articles on this subject on the internet. The standard method seems to be to send a WM_SETREDRAW message to prevent the control from being redrawn while updating. I had this implemented and running nicely when I came across another article showing that an extra speed increase can be gained by sending EM_SETEVENTMASK to prevent the control from handling events. Here's the code:

+ Code to help speed up RichTextBox updating.

/// <summary>
/// Maintains performance while updating.
/// </summary>
/// <remarks>
/// <para>
/// It is recommended to call this method before doing
/// any major updates that you do not wish the user to
/// see. Remember to call EndUpdate when you are finished
/// with the update. Nested calls are supported.
/// </para>
/// <para>
/// Calling this method will prevent redrawing. It will
/// also setup the event mask of the underlying richedit
/// control so that no events are sent.
/// </para>
/// </remarks>
public void BeginUpdate()
{
    // Deal with nested calls.
    ++updating;
    
    if ( updating > 1 )
        return;
    
    // Prevent the control from raising any events.
    oldEventMask = SendMessage( new HandleRef( this, Handle ),
                                EM_SETEVENTMASK, 0, 0 );
    
    // Prevent the control from redrawing itself.
    SendMessage( new HandleRef( this, Handle ),
                 WM_SETREDRAW, 0, 0 );
}

/// <summary>
/// Resumes drawing and event handling.
/// </summary>
/// <remarks>
/// This method should be called every time a call is made
/// made to BeginUpdate. It resets the event mask to it's
/// original value and enables redrawing of the control.
/// </remarks>
public void EndUpdate()
{
    // Deal with nested calls.
    --updating;
    
    if ( updating > 0 )
        return;
    
    // Allow the control to redraw itself.
    SendMessage( new HandleRef( this, Handle ),
                 WM_SETREDRAW, 1, 0 );
    
    // Allow the control to raise event messages.
    SendMessage( new HandleRef( this, Handle ),
                 EM_SETEVENTMASK, 0, oldEventMask );
}

Although I'm using HandleRef here, I have absolutely no idea if this is the correct usage (or even if it's needed). Full code will be at the end of this posting. I have not fully tested these methods so I have no idea what the performance gains might be (if there are any). If anyone wants to try benchmarking, please let me know the results.

Justification

It always bothered me that the SelectionAlignment property of RichTextBox does not allow fully justified text. Especially since I know it's possible with the richedit control that RichTextBox wraps. Here's some code that will replace SelectionAlignment with something a little nicer for those that are writing word processors in C#:

+ Code to allow justified text in the RichTextBox.

/// <summary>
/// Gets or sets the alignment to apply to the current
/// selection or insertion point.
/// </summary>
/// <remarks>
/// Replaces the SelectionAlignment from
/// <see cref="RichTextBox"/>.
/// </remarks>
public new TextAlign SelectionAlignment
{
    get
    {
        PARAFORMAT fmt = new PARAFORMAT();
        fmt.cbSize = Marshal.SizeOf( fmt );
        
        // Get the alignment.
        SendMessage( new HandleRef( this, Handle ),
                     EM_GETPARAFORMAT,
                     SCF_SELECTION, ref fmt );
        
        // Default to Left align.
        if ( ( fmt.dwMask & PFM_ALIGNMENT ) == 0 )
            return TextAlign.Left;
        
        return ( TextAlign )fmt.wAlignment;
    }
    
    set
    {
        PARAFORMAT fmt = new PARAFORMAT();
        fmt.cbSize = Marshal.SizeOf( fmt );
        fmt.dwMask = PFM_ALIGNMENT;
        fmt.wAlignment = ( short )value;
        
        // Set the alignment.
        SendMessage( new HandleRef( this, Handle ),
                     EM_SETPARAFORMAT,
                     SCF_SELECTION, ref fmt );
    }
}

The TextAlign enumeration contains Left, Right, Center and Justify. Again, this is mostly untested -- it should work on any machine with the richedit 2.0 common control (I believe), but I offer no guarantees.

Code

Here's the full code for the AdvRichTextBox control (plus the TextAlign enumeration):

+ Full AdvRichTextBox code.

using System;
using System.Windows.Forms;
using System.Runtime.InteropServices;

/// <summary>
/// Represents a standard <see cref="RichTextBox"/> with some
/// minor added functionality.
/// </summary>
/// <remarks>
/// AdvRichTextBox provides methods to maintain performance
/// while it is being updated. Additional formatting features
/// have also been added.
/// </remarks>
public class AdvRichTextBox : RichTextBox
{
    /// <summary>
    /// Maintains performance while updating.
    /// </summary>
    /// <remarks>
    /// <para>
    /// It is recommended to call this method before doing
    /// any major updates that you do not wish the user to
    /// see. Remember to call EndUpdate when you are finished
    /// with the update. Nested calls are supported.
    /// </para>
    /// <para>
    /// Calling this method will prevent redrawing. It will
    /// also setup the event mask of the underlying richedit
    /// control so that no events are sent.
    /// </para>
    /// </remarks>
    public void BeginUpdate()
    {
        // Deal with nested calls.
        ++updating;
        
        if ( updating > 1 )
            return;
        
        // Prevent the control from raising any events.
        oldEventMask = SendMessage( new HandleRef( this, Handle ),
                                    EM_SETEVENTMASK, 0, 0 );
        
        // Prevent the control from redrawing itself.
        SendMessage( new HandleRef( this, Handle ),
                     WM_SETREDRAW, 0, 0 );
    }
    
    /// <summary>
    /// Resumes drawing and event handling.
    /// </summary>
    /// <remarks>
    /// This method should be called every time a call is made
    /// made to BeginUpdate. It resets the event mask to it's
    /// original value and enables redrawing of the control.
    /// </remarks>
    public void EndUpdate()
    {
        // Deal with nested calls.
        --updating;
        
        if ( updating > 0 )
            return;
        
        // Allow the control to redraw itself.
        SendMessage( new HandleRef( this, Handle ),
                     WM_SETREDRAW, 1, 0 );
        
        // Allow the control to raise event messages.
        SendMessage( new HandleRef( this, Handle ),
                     EM_SETEVENTMASK, 0, oldEventMask );
    }
    
    /// <summary>
    /// Gets or sets the alignment to apply to the current
    /// selection or insertion point.
    /// </summary>
    /// <remarks>
    /// Replaces the SelectionAlignment from
    /// <see cref="RichTextBox"/>.
    /// </remarks>
    public new TextAlign SelectionAlignment
    {
        get
        {
            PARAFORMAT fmt = new PARAFORMAT();
            fmt.cbSize = Marshal.SizeOf( fmt );
            
            // Get the alignment.
            SendMessage( new HandleRef( this, Handle ),
                         EM_GETPARAFORMAT,
                         SCF_SELECTION, ref fmt );
            
            // Default to Left align.
            if ( ( fmt.dwMask & PFM_ALIGNMENT ) == 0 )
                return TextAlign.Left;
            
            return ( TextAlign )fmt.wAlignment;
        }
        
        set
        {
            PARAFORMAT fmt = new PARAFORMAT();
            fmt.cbSize = Marshal.SizeOf( fmt );
            fmt.dwMask = PFM_ALIGNMENT;
            fmt.wAlignment = ( short )value;
            
            // Set the alignment.
            SendMessage( new HandleRef( this, Handle ),
                         EM_SETPARAFORMAT,
                         SCF_SELECTION, ref fmt );
        }
    }
    
    /// <summary>
    /// This member overrides
    /// <see cref="Control"/>.OnHandleCreated.
    /// </summary>
    protected override void OnHandleCreated( EventArgs e )
    {
        base.OnHandleCreated( e );
        
        // Enable support for justification.
        SendMessage( new HandleRef( this, Handle ),
                     EM_SETTYPOGRAPHYOPTIONS,
                     TO_ADVANCEDTYPOGRAPHY,
                     TO_ADVANCEDTYPOGRAPHY );
    }
    
    private int updating = 0;
    private int oldEventMask = 0;
    
    // Constants from the Platform SDK.
    private const int EM_SETEVENTMASK = 1073;
    private const int EM_GETPARAFORMAT = 1085;
    private const int EM_SETPARAFORMAT = 1095;
    private const int EM_SETTYPOGRAPHYOPTIONS = 1226;
    private const int WM_SETREDRAW = 11;
    private const int TO_ADVANCEDTYPOGRAPHY = 1;
    private const int PFM_ALIGNMENT = 8;
    private const int SCF_SELECTION = 1;
    
    // It makes no difference if we use PARAFORMAT or
    // PARAFORMAT2 here, so I have opted for PARAFORMAT2.
    [StructLayout( LayoutKind.Sequential )]
    private struct PARAFORMAT
    {
        public int cbSize;
        public uint dwMask;
        public short wNumbering;
        public short wReserved;
        public int dxStartIndent;
        public int dxRightIndent;
        public int dxOffset;
        public short wAlignment;
        public short cTabCount;
        [MarshalAs( UnmanagedType.ByValArray, SizeConst = 32 )]
        public int[] rgxTabs;
        
        // PARAFORMAT2 from here onwards.
        public int dySpaceBefore;
        public int dySpaceAfter;
        public int dyLineSpacing;
        public short sStyle;
        public byte bLineSpacingRule;
        public byte bOutlineLevel;
        public short wShadingWeight;
        public short wShadingStyle;
        public short wNumberingStart;
        public short wNumberingStyle;
        public short wNumberingTab;
        public short wBorderSpace;
        public short wBorderWidth;
        public short wBorders;
    }
    
    [DllImport( "user32", CharSet = CharSet.Auto )]
    private static extern int SendMessage( HandleRef hWnd,
                                           int msg,
                                           int wParam,
                                           int lParam );
    
    [DllImport( "user32", CharSet = CharSet.Auto )]
    private static extern int SendMessage( HandleRef hWnd,
                                           int msg,
                                           int wParam,
                                           ref PARAFORMAT lp );
}

/// <summary>
/// Specifies how text in a <see cref="AdvRichTextBox"/> is
/// horizontally aligned.
/// </summary>
public enum TextAlign
{
    /// <summary>
    /// The text is aligned to the left.
    /// </summary>
    Left = 1,
    
    /// <summary>
    /// The text is aligned to the right.
    /// </summary>
    Right = 2,
    
    /// <summary>
    /// The text is aligned in the center.
    /// </summary>
    Center = 3,
    
    /// <summary>
    /// The text is justified.
    /// </summary>
    Justify = 4
}

Conclusion

I'll add to this code in future posts and if anyone has any comments or suggestions (or even requests), feel free to ask them. Hope you found this useful.