The Usage Guide

RoundedBox is not very complicated server control but sometimes you will need some help on how to use it appropriately. Here it is.

Warning!

RoundedBox requires ASP.NET 2.0. Version 1.x is not supported.

Step-by-step guide

Download RoundedBox and place BorBer.WebControls.RoundedBox.dll into Bin folder of your web application.
Register RoundedBox so that ASP.NET runtime recognizes <bb:RoundedBox> server tag. You can use either @Register directive or slight modification of the Web.config file; simply add following line into system.web > pages > controls section:
```
<add tagPrefix="bb"
     namespace="BorBer.WebControls"
     assembly= "BorBer.WebControls.RoundedBox"
/>
```
For details, see MSDN Documentation.
Now, you're ready to use RoundedBox. Try if everything works and put the following line into your ASPX page:

<bb:RoundedBox ID="test" runat="server" BackColor="SteelBlue"> Test box </bb:RoundedBox>

Also make sure that the <head> element has runat="server" attribute (this is required in the NoImages method). Try to visit your page with a browser and you should see your first rounded box created by RoundedBox :)

Now little troubleshooting; if there is some error, check if
- you run ASP.NET 2.0; older versions are not supported
- the RoundedBox control is correctly registered for a given page (see step 2)
- downloaded file is not corrupted - this is very unlikely but honestly, now it's difficult to say what went wrong because RoundedBox has been thoroughly tested and should work with no problems
You can add RoundedBox into your toolbox. In Visual Studio, right-click the toolbar, select "Choose items" and pick "RoundedBox".

So far, things were easy. Now it will require little more invention - you will have to choose a rendering method which best suits your needs:

Method	Usage
	Advantages	Disadvantages
NoImages	Rounded corners are generated using JavaScript and CSS. Use this method in simple scenarios.
	· No need to prepare images · Easy implementation	· JavaScript dependency · Low customization options
PreparedImages	Rounded corners are based on beforehand prepared images. This method is the most flexible one.
	· Maximal flexibility	· Quite hard implementation · Images need to be prepared manually
GenerateImages	Images are dynamically generated on the server. It is an interesting compromise between NoImages' easyness and PreparedImages' flexibility
	· Easy implementation	· Limited customization options

Fill the selected method into the Method property.

Set the other properties. You will find the complete list of applicable attributes in the Reference section but for your convenience, here are some quick guidelines.
- Commonly used properties
  No matter what method is used, you will probably want to set one or more of these commonly used properties:
  - Width, Height and other standard WebControl properties such as Font, ForeColor etc.
  - BackColor - sets the filling color of the box
  - UnderlayColor - sets the color of the surface on which the RoundedBox will sit (e.g. page's color or the color of the parent div)
  - border properties - standard BorderColor, BorderStyle and BorderWidth properties; note that not all methods supports everything - for example JavaScript implementation in NoImages method does not understand the concept of border width
  - padding properties (Padding, PaddingTop, PaddingRight etc. properties) - they set padding of the box; you should use this proprietary property instead of CSS "padding: ..." because RoundedBox intelligently calculates default padding when you use images so this server-side Padding properties will give better and more appropriate results
- NoImages method
  Using CornersToRound property, you can choose which corners should be rounded. Another useful property is OutputDir which sets ASP.NET path where emitted JavaScript and CSS files will be stored.
- PreparedImages method
  Using this method, you must understand how RoundedBox finds images. There are two main approaches:
  1. First, you can specify each path to every single image separately. Then use Image-Top, Image-TopRight etc. properties
  2. Second (and mostly preferred) way is to specify where the images are and how are they named. By default, RoundedBox seeks top left image on the path "~/topleft.png" but all chunks of this path are completely customizable so if your images are in "rounded" directory, use prefix "rb_" and "-" as a separator (e.g. "~/rounded/rb_top-left.png"), you should set
    Image-Directory="~/rounded"
    Image-FilePrefix="rb_"
    Image-Separator="-"
    and RoundedBox will successfully find them.
  Now you understand how to tell RoundedBox where to find images but you must set one more important property: Image-Mode. If you prepared 8 images, one for each corner and one for each edge, use CornersAndEdges mode. If you have 4 images, one for each corner, use Corners mode. Use the third TopMiddleBottom mode if you have one big image for top part of the box, one repeating image for the middle part and finally one for the bottom part. This mode is most flexible but also most bandwidth-intensive. But it's your choice.
- GenerateImages method
  You will want to set RadiusX and RadiusY properties. Be aware that they are in pixels (Int32) and not in the Unit type. In this method, you can also use the CornersToRound property which allows you to define which corners should be rounded.

Reference

Following table contains the reference documentation of all applicable properties. The table sorting roughly respects the properties importance.

Property	Comments
Method	Type: RoundMethod enumeration (with NoImages, PreparedImages and GenerateImages options) Default value: NoImages Chooses the rendering method.
Width Height	Type: Unit Default value: Empty Inherited from WebControl. Sets the width and height of the box.
BackColor	Type: Color Inherited from WebControl. Sets the background color of the box.
RadiusX, RadiusY	Type: Int32 (not Unit!) Specifies the corners radius. Used by GenerateImages method.
Padding, PaddingTop, PaddingRight, PaddingBottom, PaddingLeft	Type: Padding is string, the others are of type Unit Padding property uses CSS syntax, which means that it can be supplied with one to four values: one value: sets padding for all sides two values: the first one is for top and bottom sides, the second one for right and left sides three values: first is top, second is right and left, third is bottom four values: one for each side, clockwise starting with top When selected method uses images, RoundedBox tries to compute default padding based on image dimensions. This is the reason why the user should always use these properties instead of standard CSS "padding" style rules. For details, see features page.
UnderlayColor	Type: Color Sets the color of the surface on which the RoundedBox sits (e.g. the color of the page or of the parent div). When the surface uses some wild patterns, leave this property empty, rounded corners then will use transparency if possible. But when you know the surface color in advance, it's a good idea to set it because auto-aliasing will be used which produces somewhat better visual results.
BorderColor, BorderStyle, BorderWidth	Inherited from WebControl. RoundedBox will try to translate standard border into rounded corners border. Not applicable when using PreparedImages method.
CornersToRound	Type: string Default value: "all" Specifies which corners should be rounded. Applicable in NoImages and GenerateImages method. Allowed values are "all", "top", "bottom", "tl", "tr", "bl", "br" or some combination of those.
OutputDir	Type: string Default value: "~" Accepts any valid ASP.NET path. All emitted files (generated images, JS, CSS files) will be stored in this location. This is the way to prevent your top level web directory to be contaminated by many many server-generated files. Regarding the trailing slash ("first/example" vs. "second/example/"), RoundedBox will accept both alternatives but the first one is preferred.
another standard properties	... as for example Font, ForeColor and other properties inherited from WebControl.
Image	Type: RoundedImages class Composite property containing information about images to create rounded corners efect. It will be used in PreparedImages method. See Image-subproperties.
Image-Mode	Type: ImageMode enumeration (with Corners, CornersAndEdges and TopMiddleBottom options) Corners - there are only images for corners prepared CornersAndEdges - there are 8 images, one for each corner and one for each edge; edge images are automatically repeated in the right direction (using repeat-x and repeat-y CSS properties) TopMiddleBottom - one image for top region, one for the middle one (it will repeat vertically) and one for the bottom area There is no default value so you will get an error if you don't specify one.
Image-Top, Image-TopRight, Image-Right, Image-Bottom, Image-BottomRight, Image-Bottom, Image-BottomLeft, Left, TopLeft, Middle	Type: string Each property sets the full path to one image. Any valid ASP.NET path is accepted. Generally, it's more convenient to specify file names indirectly, see other Image-* properties below.
Image-Directory	Type: string Default value: "~" Any valid ASP.NET path is accepted. Specifies directory name where rounded corners images reside. Can be used together with Image-Top, Image-TopRight etc. properties - in that case, the path to image is computed as `Image-Directory + "/" + Image-Top`. Regarding the trailing slash ("first/example" vs. "second/example/"), RoundedBox will accept both alternatives but the first one is preferred.
Image-FilePrefix	Type: string Default value: empty string When RoundedBox searches for images, FilePrefix property specifies how the filenames begin. If they are named rounded_top.png, rounded_topleft.png etc., this property should be set to "rounded_". Empty string is a default value.
Image-Separator	Type: string Default value: empty string When RoundedBox searches for images, Separator specifies any string between vertical and horizontal portion of the filenames. If your files are named "prefix_vertical-horizontal.png", Separator should be se to "-". Empty string is a default value.
Image-FileExtension	Type: string Default value: "png" When RoundedBox searches for images, FileExtension specifies files extension. Defaults to "png"
Image-NameForTop, Image-NameForRight, Image-NameForBottom, Image-NameForLeft, Image-NameForMiddle	Type: string Default values: "top", "right", "bottom", "left" and "middle" When RoundedBox searches for images, these properties specify the naming conventions for file names. By default, RoundedBox expects something like "topleft.png". If your file is named e.g. "upperleft.png", you should set NameForTop to "upper". To save you some typing, you should care in mind that RoundedBox expects "top", "right", "bottom", "left" and "middle" by default so it is a good idea to create filenames that uses this convention.
Image - summary example	By default, RoundedBox seeks top left image on the path "~/topleft.png". If the images are in "rounded" directory, start with "rb_" and are separated by hyphen (e.g. "~/rounded/rb_top-left.png"), the properties should be set to Image-Directory="~/rounded" Image-FilePrefix="rb_" Image-Separator="-" All other properties fit with their default values. So it's a good idea to create images that containt "top", "left" etc. in their names.

How to round any ASP.NET server control

RoundedBox can be used to round any visible ASP.NET server control (yes, really!). Here's the procedure:

The trick uses ASP.NET themes and skins, new feature of the 2.0 release. If you don't know what is this all about, visit ASP.NET Quickstart Tutorials, topic Applying Styles, Themes, and Skins. I'll wait. ... OK, so now, create a skin and register it with the webpage (using Theme or StyleSheetTheme properties of the @Page directive, or however).
In this theme, define RoundedBox with desired properties. While Visual Studio skin editor does not support IntelliSense, the most convenient way is to design RoundedBox in some ASPX page and then copy the whole markup to the skin file and remove the ID property (don't forget this!). Also define a SkinID property (set it to whatever you want).
Find the control that should be rounded (e.g. <asp:Panel> and set RoundedBoxSkinID property to the SkinID that you defined in the previous step.
Now the only line of code you will ever need to write when using RoundedBox: in the Page_Load method (or wherever, but before page's rendering phase) call the static method RoundedBox.RoundControls(this.Page)

Prepared rounded box settings from skin file will then be applied to every ASP.NET server control containing the appropriate RoundedBoxSkinID property. If the RoundedBoxSkinID is present but the value is an empty string, skin file is searched for RoundedBox definition without SkinID property set.

Now, you're the RoundedBox expert!