Regions

Regions are CSS properties that you use to set bounds. Currently, Dashboard specifies only one type of region, a control region. Specifiying a control region means that if a user attempts to drag a widget from within a specified region, the drag will not occur and the widget will not move.

Regions come in two shapes: rectangles and circles. Any combination of these shapes is allowed, letting you create complex control regions for use with odd shapes.

Once you have defined a region within a style element, you need to wrap an element within your markup with that style. For instance, a control region definition may look like this:

.control-circle-example {
    ...
    -apple-dashboard-region: dashboard-region(control circle 5px 5px 5px 5px);
    ...
}

Now that you’ve defined a style, you need to apply it to an element:

<div class=”control-circle-example”><img src=”foo.png”></div>

Properties

The following property is defined for use when specifying regions within a widget.

-apple-dashboard-region

Specifies the property to be defined.

-apple-dashboard-region:

This property tells Dashboard that you are about to specify a region. Without any parameters, this property does nothing. As parameters to this method, you need to specify regions using the dashboard-region parameter.

Parameters

The following parameters are defined for use when specifying regions within a widget.

dashboard-region

Specifies the type and bounds of a region.

dashboard-region(label, geometry-type)
dashboard-region(label, geometry-type, offset-top, offset-right, offset-bottom, offset-left)

This parameter function is used in conjunction with the -apple-dashboard-region property. It specifies a region’s bounds and type, in function form. Table 2-1 shows the values expected by the dashboard-region parameter.

Table 2-1  dashboard-region() parameters

Parameter

Description

label

Required; specifies the type of region being defined; control is the only used value.

geometry-type

Required; specifies the shape of the region, either circle or rectangle.

offset-top

Optional; specifies the offset from the top of the wrapped area from where the defined region should begin, in pixels. Negative values not allowed.

offset-right

Optional; specifies the offset from the right of the wrapped area from where the defined region should begin, in pixels. Negative values not allowed.

offset-bottom

Optional; specifies the offset from the bottom of the wrapped area from where the defined region should begin, in pixels. Negative values not allowed.

offset-left

Optional; specifies the offset from the left of the wrapped area from where the defined region should begin, in pixels. Negative values not allowed.

If you specify circle for the geometry-type parameter, the control region created is centered in between the specified offsets (or the edges of the region, if no offsets are provided). Of the circle region’s width and height (which ideally should be equal), the resulting control region’s diameter is the smaller value.

When using the offset parameters, you either provide values for all four offsets or none of them. Note that if you do not specify values for the offset parameters, a default value of 0 is used for each of them.

You can chain multiple dashboard-region parameters together in one apple-dashboard-region property declaration, allowing you to create complex-shaped regions:

.equals-button-example {
    ...
    -apple-dashboard-region:
        dashboard-region(control circle 0px 0px 80px 0px)
        dashboard-region(control rectangle 10px 0px 10px 0px)
        dashboard-region(control circle 80px 0px 0px 0px);
    ...
}

Some elements have control regions assigned to them by default:

  • button

  • input

  • select

  • textarea

Whenever you use one of these elements you do not need to manually specify a control region them. The region specified on these elements extend to their edges:

 button, input, select, textarea {
    -apple-dashboard-region:dashboard-region(control rectangle);
}

none

Removes any regions on an element.

none

Setting the -apple-dashboard-region property to none removes any region applied to an element.



Copyright © 2004, 2009 Apple Inc. All Rights Reserved. Terms of Use | Privacy Policy | Updated: 2009-02-04