DialogForm - An Extended WinForms Class

• Download demo - 59.59 KB
• Download source - 56.27 KB

Introduction

I'm starting my first article on CodeProject with a boring theme: Dialog boxes. We all know the annoying job to design dialog boxes (positioning, anchoring, aligning the appropriate buttons while heading for an continuous GUI design). For this reason, I've implemented the DialogForm class which should help us to make this task a little bit easier.

The concept behind is to create and handle the standard dialog box buttons programmatically and save the time dealing with button positioning or forgotten ShowInTaskBar flags.

Benefits

• Automatic setting of the FORM properties (ShowInTaskBar, MinimizeBox, MaximizeBox, AcceptButton, CancelButton, KeyPreview) for dialog box requirements
• Automatic positioning, anchoring, aligning and tab ordering for standard buttons
• Automatic 'DialogBoxResult' mapping for standard dialog box buttons
• A configurable dialog box header with header text, description text and a background image
• A configurable dialog box footer providing various predefined dialog box button types
• Deriving your own dialog boxes from the DialogForm class ensures a continuous GUI design

Simplifying a task mostly ends up in losing flexibility. This is valid for this implementation too, but for a team of developers, it's easier to achieve a continuous GUI design. So here are some constraints:

• The commonly used dialog box buttons (Ok, Cancel, Close, Yes, No, Next, Back, Finish, Reset) are predefined, additionally two 'customisable' buttons
• This implementation may not meet language dependant dialog box requirements (for example Eastern or Arabic languages)
• Currently, there is no algorithm to compute an appropriate MinimumSize for sizeable dialogs (means that we have to set the MinimumSize property to ensure footer overlaps header on very small dialogs)

Using the Code

Reference the DialogForm assembly in your project.

Instead of deriving your dialogs from System.Windows.Forms, derive it from Dialog.DialogForm, for example:

public partial class DerivedDialogForm : Dialog.DialogForm
{
    public DerivedDialogForm()
    {
        InitializeComponent();
    }
}

You are now able to set the DialogForm properties according to your requirements.

Description of public DialogForm properties

• public ButtonsType Buttons: Specify the buttons to display.
  Hint: This may be a combined enumeration value. For customized buttons, use this property programmatically. Example:
  C#

  public partial class DerivedDialogForm : Dialog.DialogForm
   {
     public DerivedDialogForm()
     {
       InitializeComponent();
       // This creates a Reset Button and 2 customized buttons
       Buttons = ButtonsType.Reset | ButtonsType.Customized1 | ButtonsType.Customized2;
       // aligning the reset Button to the left
       SetButtonLeftAligned(ButtonsType.Reset);
       // rename the button text to "default"
       SetButtonText(ButtonsType.Reset, "Default");
       // rename the 1. customized button text to "import"
       SetButtonText(ButtonsType.Customized1, "&Import");
       // rename the 2. customized button text to "export"
       SetButtonText(ButtonsType.Customized2, "&Export");
     }
   }
  

• public string HeaderText Set the header text string
• public Image HeaderImage Set the header background image
• public string DescriptionText Set the header description string
• public bool DisabledButtons Set this to true to achieve initially disabled buttons
• public bool ShowFooter Enables/disables the dialog header
• public bool ShowHeader Enables/disables the dialog footer

Description of public DialogForm methods:

• bool IsButtonEnabled(ButtonsType buttonType) Gets a value indicating if a button is enabled.
• void SetButtonState(ButtonsType buttonType, bool enabled) Sets the specified button to the specified enabling state.
• void SetButtonText(ButtonsType buttonType, string text) Sets the specified button to the specified text.
• void SetButtonLeftAligned Sets the specified button to be left aligned.

Description of public DialogForm events:

• public event EventHandler ButtonClicked Button clicked event.
  Hint: The sender contains the clicked Button and its Tag property contains the Dialog.DialogForm.ButtonsType value to identify which button is clicked, receiver example:
  C#

  void dlg_ButtonClicked(object sender, EventArgs e)
  {
      Console.WriteLine(string.Format("Button {0} clicked"
        , (DialogForm.ButtonsType)(((Button)sender).Tag))
        );
  }

Possible extensions to do on the DialogForm:

• An algorithm detecting the MinimumSize property from derived sizeable dialogs would be useful!
• Expose more properties of the DialogForm (colors, fonts, ...)
• I know there is a good article out here on CodeProject concerning a Windows Forms wizard implementation, but on request, I could do another article implementing a Windows Forms wizard on this DialogForm base class.

Points of Interest

• For sure, you want to modify the dialog header drawing code, so do this in DialogForm.PanelHeader.OnPaint(...)
• There is a fixed button order, to change this, you may edit the DialogForm.InitializeButtons() method according to your preferences.
• The set of predefined Buttons is the following enumeration (Don't forget to adjust the DialogForm.InitializeButtons() method after modifying this enumeration).
  C#

  /// <summary>
  /// Predefined button types.
  /// 
  /// Any combination is allowed.
  /// </summary>
  [Flags]
  public enum ButtonsType
  {
    Ok=0x01,
    Cancel=0x02,
    Close = 0x04,
    Yes = 0x08,
    No = 0x10,
    Back = 0x20,
    Next = 0x40,
    Finish = 0x80,
    Reset = 0x100,
    Default = 0x200,
    Customized1 = 0x400,
    Customized2 = 0x800,
    /// <summary>Standard ok/cancel button set </summary>
    OkCancel = Ok | Cancel,
    /// <summary>Standard yes/no button set</summary>
    YesNo = Yes | No,
    /// <summary>Standard wizard button set </summary>
    Wizard = Back | Next | Finish | Cancel,
  }

History

• 01/16/2011 Initial release