# Instructions

## Navigation

- Getting the source
- Using CurvyCorners the new way — using CSS
- Using CurvyCorners manually
- Upgrading from version 1.x
- CurvyCorners options and settings
- Further information

## Getting the source

To check out the latest stable version:
  `svn co http://curvycorners.googlecode.com/svn/tags/2.0.x/stable [mydir]`
To check out the latest (bleeding-edge) revision:
  `svn co http://curvycorners.googlecode.com/svn/trunk [mydir]`
To browse the versions:
  http://code.google.com/p/curvycorners/source/browse/#svn/tags
To browse the latest revision:
  http://code.google.com/p/curvycorners/source/browse/#svn/trunk

You can also download the latest version of CurvyCorners from the downloads section.

Some earlier versions are also available from the Google Code Downloads page.

## Using CurvyCorners the new way — using CSS

As from 2.0.x, CurvyCorners allows you to put rounded corners on your page elements using CSS. At present, there are two proprietary CSS syntaxes, one for Mozilla/Firefox and one for the Webkit browsers, Safari and Google Chrome.

All you need to do is to put the appropriate rounded corner styles into the appropriate rules, and CurvyCorners will automatically draw corners for the affected boxes, whilst leaving it to the newer browsers to draw them using their native methods.

### Example

Suppose that you have a DIV in your page with class rounded. You want all four corners rounded, with a radius of one and a half ems. The following CSS will accomplish this:

.rounded {
-moz-border-radius:3ex;
-webkit-border-radius:3ex;
}

If you want (say) only the top left and bottom right corners rounded, then you can do it like this:

.rounded {
-moz-border-radius-topleft:3ex;
-moz-border-radius-bottomright:3ex;
-webkit-border-top-left-radius:3ex;
-webkit-border-bottom-right-radius:3ex;
}

(Note that the CSS3 proposed syntax is similar to the Webkit version, but of course without the "-webkit-" prefix. Internally, CurvyCorners looks for the Webkit syntax and ignores the Mozilla version.)

### CSS Selector Limitations

Because of the need for the mechanism to operate across all browsers, the CSS selector syntax supported is necessarily limited. This sets out what is supported:

- a selector-list, where a selector-list is either a single selector or a single selector followed by a comma and an optional space, followed by a selector-list.
- A single selector may be either a simple-selector or a simple-selector followed by a space followed by another simple-selector.
- A simple-selector may be either an ID of the form `#myID`, or a tag-class-selector.
- A tag-class-selector may be any one of:
  1. a tag name (e.g. `div`);
  2. a class name preceded by a dot (e.g. `.myClass`); or
  3. a tag name followed by a dot followed by a class name (e.g. `div.myClass`).

The following are examples of supported selectors:

- .myclass
- #mydiv frameset.myclass
- form.rounded frameset,div.rounded

Warning: because CurvyCorners appends extra DIVs to the boxes you wish to round, the following selector will reliably not work:

`#myBox div`

This is because the style will be applied not just to the top-level DIVs within the element whose ID is `myBox`, but also to the DIVs inserted by CurvyCorners.

The following selectors may not work as expected:

- div #mybox
- div.rounded #mybox

Because an ID identifies a page element uniquely, qualifying it with an enclosing scope may cause the selector to fail (e.g. if #mybox is a top-level DIV, or if it is not located within a DIV of class rounded). However, CurvyCorners assumes that the element is to be referenced anyway and will apply the appropriate rounding styles.

### Dynamic HTML

CurvyCorners now has limited support for dynamic HTML. In particular, you may change the contents of a box and have the box re-sized (re-drawn) to fit. However, because of the technique CurvyCorners uses to draw the corners, this cannot happen automatically. Instead, you must do the following:

1. Specify the corners using the new CSS style and not the old onload-function style;
2. Give the box elements to be re-drawn the (additional) special class-name `curvyRedraw`; and
3. in your JavaScript, explicitly call the function `curvyCorners.redraw()`.

`curvyCorners.redraw()` takes no parameters and returns no usable value.

If you need to change some attributes or styling of the redrawable elements, this should not be done directly through the DOM. Instead, having identified the DOM object (e.g. with `document.getElementById()`), call

`curvyCorners.adjust(DOMObj, propertyName, newValue);`

where:

DOMObj
  is the element object with className `curvyRedraw` that needs to be changed;
propertyName
  is the name of the property without a leading dot; if it is a style property, it should be expressed as `'style.property'`.
newValue
  is the new value, e.g. `'none'`.

`curvyCorners.adjust()` must take all three parameters described above. It returns no useful value.

An extensive example of this technique is contained in demo 5.

#### Handling window resize events

curvyCorners supports redrawing curved boxes in response to a change in the browser window size. If you wish to take advantage of this, you can add an event handler to trigger a redraw. However, some DOM changes will fire spurious window resize events in some browsers. These can happen in the midst of DOM changes (including those that curvyCorners itself makes whilst redrawing). Therefore, do not make your handler call `curvyCorners.redraw()` directly. Instead, set your resize handler function to call `curvyCorners.handleWinResize()`.

Next, if you find that some of your code is triggering window resize events (which will cause a noticeable delay!), surround the code with:

curvyCorners.setWinResize(false); // block redraw on resize // ... your DOM-manipulating code here curvyCorners.setWinResize(true); // re-enable redraws on window resize

An example of this technique is contained in demo 5.

#### Delaying the CurvyCorners startup code

If it is planned to add a number of elements to the page after it has loaded, and if these elements are to have rounded corners, it can be advantageous to delay the running of the startup code. This can be done as follows:

1. Before the script tag that includes curvycorners.js, add the following in the <head> section of your page:

   <script type="text/javascript">
   var curvyCornersNoAutoScan = true;
   </script>

2. After your script to add the elements has run, invoke the startup code with the following statement:

   curvyCorners.init();

If you specify in CSS the ID of an element with rounded corners that is not yet added to the page, CurvyCorners will warn of the problem by using alert(). To suppress this message, include the following script in your page before including the CurvyCorners script:

<script type="text/javascript">
var curvyCornersVerbose = false;
</script>

### Hidden Boxes

CurvyCorners supports the styling of boxes that are not currently displayed, i.e. which have the style `display:none`. In such cases, it may be necessary for CurvyCorners temporarily to display the box, and this may cause a brief flicker as the page is loaded.

### Other limitations

- If you wish to invoke curvyCorners in a browser that supports rounded corners natively, e.g. Firefox, Chrome or Safari, you must use the manual method described below.
- If you wish to use dynamic features (e.g. resizing) on a box rounded by curvyCorners, you must use the CSS style of specifying the corners, not the old manual style.
- In some circumstances, a browser may not compute a display width for a box that you wish to style with rounded corners. This may either be because the box is not currently displayed, or because of a peculiarity in the browser. In this circumstance, CurvyCorners will output an error message and continue; but it will not be able to apply corners to the box in question. It may be possible to correct this by applying a width or min-width style to the affected box element. You can suppress the display of the error message by including the following in the <head> section of the page before the script tag that includes the CurvyCorners script:

  <script type="text/javascript">
  var curvyCornersVerbose = false;
  </script>

- In Opera v9.x, unrecognized styles (including rounded corner styles) are not included in the DOM tree. CurvyCorners can detect them only if it has access to the CSS text. If the stylesheet is included using a `<link href="mystyle.css" rel="stylesheet"/>` element, or using an `@import` rule, Opera won't be able to access it. It has access only if the style is included in the HTML page itself. We hope to address this limitation soon.
- Boxes styled by CurvyCorners cannot be resized dynamically except by using the technique described above.
- If a box styled by CurvyCorners has borders, then for best results, the border width must be the same on both sides adjacent to a round corner.
- When rounding a bordered box, the border style must always be `solid`: other styles are not supported.
- Elliptical radii (e.g. `border-radius:1em 2em;`) are not supported. The first dimension will be understood as the only dimension.
- If a box has an image background, and the two top or bottom radii are of different non-zero values, the box will not render correctly. Your top and bottom corner radii must be either equal, or one of them must be zero (square).
- <img> elements cannot be rounded using curvyCorners. Instead, use a <div> element and set the image as the background-image of the <div>.
- In legacy browsers, when using image backgrounds, the lower part of the box may be out by 1 pixel. We are investigating this issue, which seems unpredictable and may be an artifact of certain ancient rendering engines.

## Using CurvyCorners manually

The following instructions will round the corners of a DIV element with a 20 pixel radius.

Once you have downloaded the file, copy it to your site. Then copy the code below and paste it into the head section of your web page. If you saved the file anywhere other than the root of the site, amend the src location below.

<script type="text/JavaScript" src="curvycorners.js"></script>

Next create a DIV element. If you already have a DIV whose corners you want to round then all you need to do is give the DIV an ID.

<DIV id="myDiv"></DIV>

CurvyCorners will automatically pick up style information from the DIV element. So for example if you give the DIV a 2px black border in a stylesheet, then the borders will be automatically added to the rounded corners.

Next we need to add some JavaScript to load when the web page loads. In the HEAD section of your webpage add the following:

<script type="text/JavaScript">
window.onload = function() {
var settings = {
tl: { radius: 20 },
tr: { radius: 20 },
bl: { radius: 20 },
br: { radius: 20 },
antiAlias: true
}
var divObj = document.getElementById("myDiv");
curvyCorners(settings, divObj);
}
</script>

That's it, run your script to give it a try.

### Breaking it down

I don't have the time to write a full API so this part will try and go into as much detail as possible.

#### The Settings

The first part of the previous example creates a variable called settings; you can change this to any variable name you want. You will need to use this variable later on in the script. This variable holds all the settings needed for the curvyCorners object to work.

Each line of the settings object is a particular setting: for example the first line `tl: { radius: 20 },` tells the script that you want the top right corner of your box to have a 20 pixel corner radius.

The next three lines set the radii for the other three corners. So for example if you wanted the corner radii to be 20, 40, 60 and 80 from top left to bottom right, your settings object would look something like the example below.

var settings = {
tl: { radius: 20 },
tr: { radius: 40 },
bl: { radius: 60 },
br: { radius: 80 },
antiAlias: true
}

(Note that if you are using borders or a background image, you should be mindful of the limitations documented above.)

What about square corners? Say you did not want the top right and bottom left corners to be rounded at all and remain square: in this case, either specify a zero radius, or omit the corner specification entirely. See example below.

var settings = {
tl: { radius: 20 },
tr: { radius: 0 },
// bl: { radius: 0 },
br: { radius: 80 },
antiAlias: true
}

##### Anti-Aliasing?

Changing the value of antiAlias from `true` to `false` will toggle the anti-aliasing. Turning off anti-aliasing will reduce the smoothness of the corners but will greatly reduce the rendering time required to draw the corners.

#### Specifying which boxes to round

The are two different ways of specifying which DIVs (or other HTML boxes) you want the script to round. The first method is to pass one or more objects when creating a new instance of the curvyCorners object.

##### Using DOM objects

var divObj = document.getElementById("myDiv");
curvyCorners(settings, divObj);

Let's break the code above down. The first line uses the DOM's `document.getElementById()` method to return an object reference to myDiv called divObj. Change myDiv to the ID of the DIV element that you want to round.

The next line calls the curvyCorners function. The first param is the settings object we created earlier. The second param must be an object reference to the DIV you want to round. We retrieved this on the first line of the above code sample.

Note: You can pass more than one object when calling the curvyCorners function. To supply additional objects just follow the API info below. Each additional object passed will have the same corner settings applied, as supplied in the first parameter. If you need additional DIVs rounded with different settings, then you will need to call the curvyCorners function once for each different setting, followed by the objects to which you wish to apply those settings.

curvyCorners(settingsObj, DOMObj1[, DOMObj2[, DOMObj3[, . . . [, DOMObjN]]]]);

##### Using CSS Selectors

The other way to specify which boxes you want to apply rounded corners to, is to supply a CSS selector string as the second parameter insted of the DOM object as described above. Any block elements that have that class applied will have their corners rounded. See example below.

curvyCorners(settings, ".myClassName");
...
<div id="myDiv" class="myClassName">
</div>

(Note that unlike older versions of CurvyCorners, from version 2.0.x you must put a dot in front of the class name.)

Instead of a simple class name, you can use a tag name qualified by a class name, e.g. `div.myClassName` — this will affect DIV elements but not other elements with myClassName as their class.

You can also use an ID prefixed with a hash, like this: `#myDiv`

Finally, you can restrict the range of elements by separating two simple selectors with a space, e.g. `#myDiv div.rounded`. This will apply rounded corners only to those DIVs with class name rounded that are contained within the DIV with ID myDiv.

For further details on CSS selectors, see CSS Selector Limitations above.

## Upgrading from version 1.x

If you have pages that work with CurvyCorners v1.x, and would like to upgrade them to work with v2.0.x, you have two routes: retain the explicit style, or migrate to the CSS style.

### Upgrading using the explicit style

The changes are these:

1. If class names are passed to the curvyCorners() function, they must be prefixed with a dot.
2. The autoPad member of the settings object is no longer supported (it is always `true` in 2.x).
3. Corners that are to be rendered square should either be specified with a zero radius, or omitted entirely. They should not be specified as `false`.
4. The `applyCornersToAll()` function is now deprecated and will be removed in a future release. It is no longer necessary to create a curvyCorners object: simply call the curvyCorners function as before.

The following example shows the changes you should make. Things that you should delete are shown like this; things you should insert are shown like this.

<script type="text/JavaScript">
window.onload = function() {
var settings = {
tl: { radius: 20 },
tr: { radius: 20 },
bl: false,
br: { radius: 20 },
antiAlias: true,
autoPad: false
}
var cornersObj = new curvyCorners(settings, ".myClassName");
cornersObj.applyCornersToAll();
}
</script>

### Upgrading using the implicit style

To use the new CSS style, first place appropriate CSS directives in the <style> element of the <head> section of your page. To replicate the example immediately above, do this:

.myClassName {
-webkit-border-radius:20px;
-moz-border-radius:20px;
}

Then, entirely delete the `window.onload` function (or that part of it relating to CurvyCorners).

## CurvyCorners options and settings

If CurvyCorners detects an error that prevents onward execution, it throws an object of type Error.

If CurvyCorners detects an error that does not prevent onward execution, it issues an alert. To suppress alerts in production pages, include the following script in the <head> section of your page before the script tag that includes the CurvyCorners script:

<script type="text/javascript">
var curvyCornersVerbose = false;
</script>

To delay or prevent execution of the CurvyCorners startup code, set curvyCornersNoAutoScan `true` in the same way: see the explanation above.

## Further information

If you need more information then just checkout the script's source, it's well commented.

If you find a bug in CurvyCorners, please use the issue tracking system at Google Code. Please check first that the bug has not already been fixed in the latest version. When providing sample pages for us to investigate, please use the uncompressed version of the script, curvycorners.src.js. (It is not possible to debug using the script in its compressed form.)

If you have any questions, comments or ideas, then please use the forum by clicking the forum tab above.

Have fun!