- The new message box should be capable of rendering itself in C1 Visual Styles (including the buttons)
- It should offer the ability to add a custom Icon.
- It should offer the ability to add custom buttons.
- It should provide a means of displaying images as well as text in the message (I particularly wanted the ability to take a snapshot of a FlexGrid at the time of an error and have it displayed in the message text).
- If links to external sources (web pages, help documents) are contained within the message then it should be possible to follow them.
- It should be possible to have the message box close automatically.
- It should be possible to display additional information to the end user, at their choosing.
There’s nothing new about extending message boxes, a quick search through the Code Project will soon turn up a number of articles, so I make no claim to originality. However I hope that this has managed to add a little extra to those (if nothing else it definitely gives you the opportunity to have a visually styled message box). It was important to try and keep as much of the basic functionality of the standard message box as possible, so you’ll find that it makes use of standard message box enumerations for the icon and buttons. The rest of the functionality is achieved through the simple setting of properties.
The majority of extended message boxes make use of the Rich Text Box so that more varied text can be displayed, but it is a nightmare to try and resize a dialog dynamically according to the textual content of a Rich Text Box. Bernardo Castilho had suggested to me a while ago that the C1SuperLabel would probably do the job (particularly in the light of basic requirement number four) but I was dubious about the resizing issue. As it turns out I was wrong and he was right (again!).
Unlike a number of the examples I had looked at (and indeed the first couple of attempts I had made at getting this right) there is no basic form from which we work. Everything is done dynamically depending upon the type of message box that is instantiated and the various properties that have been set for it. The message box does have a dependency upon three C1 Assemblies (C1.Win.C1Ribbon, C1.Win.C1Input and C1.Win.C1SuperTooltip) so for that reason it is supplied as a standalone project which it is suggested that you simply add as a project to your own application and then reference it (as is done in the supplied example).
The VtlMessageBox (that’s its name by the way) should provide you with good intellisense support within the visual studio IDE but to aid your understanding its properties and constructors are documented below.
Using the VtlMessageBox
All of the files to make the VtlMessageBox function can be found in the folder VtlMessageBox in the demo project, simply copy those files to your project and you’re off.
NB: Because of the fact that this references C1 components you need to make sure that your project contains correct License entries for the C1 Button and the C1 Super Label
Dim myBox as New VTLMessageBox() if you just want a message box based on a standard windows form or
Dim myBox as New VtlMessageBox(VisualStyle) if you want one to be rendered in a visual style.
Then just set the properties you want from the following:
|MessageText||This is the text to appear in the message box. The C1 Super label actually uses HTML as its text source so if you want to have line breaks use <br> instead of environment.NewLine.|
|MessageTextColour||Allows you to specify the text colour of the message. Aimed primarily at providing a lighter text colour for dark visual styles. It will be ignored if there is any colour formatting contained in the html supplied to the superlabel .|
|Caption||The caption to appear in the message box|
|Icon||The standard message box Icon that you wish to use|
|CustomIcon||An Icon of your own choosing|
|MoreText||The additional text to appear at the bottom of the message box if the end user requests to see it. By adding text to this property the VTLMessageBox will automatically create a More Text button.|
|MoreTextColour||Designed to work in exactly the same fashion as MessageTextColour|
|MessageBoxPosition||The position where you would like the message box to open. If nothing is set it will use windows default position.|
|SecondsToAutoClose||The number of seconds to elapse before the message box will automatically close. This should be entered as the actual seconds you wish it to wait NOT milliseconds|
|AutoCloseResult||The result that will be returned by the VtlMessageBox if it is allowed to close automatically|
|DisplaySecondsToAutoClose||If set to true this will display a countdown of the seconds to AutoClose in the caption of the VTLMessageBox.|
|EndUserDecissionText||The text to appear next to a check box giving the end user the ability to decide to have his or her choice remembered. For example ‘Don’t Show This Message Again’|
There are also five events you can subscribe to:
This adds the standard MessageBox buttons to the VtlMessageBox
This adds a custom button to the VtlMessageBox. The Text Parameter is the text to appear on the button (you can add an accelerator key if you so wish). The Value parameter is the value that will be returned by the button if clicked (as a string). The order in which you add custom buttons will be the order in which they are displayed (from left to right). If you intend to have a mixture of custom and standard buttons then you should add the custom buttons first.
This adds an image to the message text area. It takes two parameters, the name of the image and the image itself. You can add as many images to the message area as you like. These images are then referenced in the text that you enter in the MessageText property. For example the following piece of codes takes an image of a range of flex grid cells and adds it to the More text area of a VtlMessageBox using the corresponding event for the more text area.
msg = New VtlMessageBox.VtlMessageBox(VisualStyle)
Dim range As CellRange = flex1.GetCellRange(0, 0, 4, 4)
Dim img As Image = flex1.CreateImage(range)
.MessageText = "You can only add Integers to the grid. Click more to get some additional help"
.MoreText = "This is what your grid looks like <br><br><img src ='res://gridImage'><br>"
.Caption = "You have made an Error"
.Icon = MessageBoxIcon.Error
txtResult.Text = .Show()
This adds an image to the more text area of the Vtl Message Box. It functions in exactly the same way as the method as the AddImageToMessageText() method.
Called when you wish to display the VtlMessageBox. It returns a result as a string type.
As an added little extra you can double click anywhere on the VtlMessageBox and the textual content of the two super labels will be copied to the clipboard.
Still To Do
I have yet to fully implement the saving of an end users response. This is ostensibly because the way in which this has traditionally been done is to write to the registry (and then edit the registry manually if you wish to change things later). In these days of strict UAC control this is not such good practice so I am veering towards implementing this with xml. To be effective though, it also needs an easy way for the end user to change their decisions.
That is essentially all there is to it, the supplied sample should give you a pretty clear idea of what it can do and how it should be configured to produce the message box that you want. If you think that there are other things that this should do then please feel free to comment. I can’t promise that I’ll be in a position to implement them but as and when Changes are made this blog will be updated.