From 9a073e360dac285c502d509830b5f9fad245f5f2 Mon Sep 17 00:00:00 2001 From: Dipika Bhattacharya Date: Tue, 15 Aug 2023 23:41:10 -0400 Subject: [PATCH] docs(css): Fx117 - new pages for basic shape functions rect() and xywh() (#28565) * new files for rect() and xywh(), wip * wip * fix lint errors * adds examples * fixes Estelle's feedback * adds spaces in syntax to match spec * fixes Estelle's feedback - round 2 * minor edits * fixes feedback --- files/en-us/web/css/basic-shape/index.md | 39 ++++-- .../en-us/web/css/basic-shape/inset/index.md | 5 +- files/en-us/web/css/basic-shape/rect/index.md | 120 ++++++++++++++++++ files/en-us/web/css/basic-shape/xywh/index.md | 105 +++++++++++++++ 4 files changed, 259 insertions(+), 10 deletions(-) create mode 100644 files/en-us/web/css/basic-shape/rect/index.md create mode 100644 files/en-us/web/css/basic-shape/xywh/index.md diff --git a/files/en-us/web/css/basic-shape/index.md b/files/en-us/web/css/basic-shape/index.md index 33e1e81e0d23ef2..0a7ed11b3a9c7eb 100644 --- a/files/en-us/web/css/basic-shape/index.md +++ b/files/en-us/web/css/basic-shape/index.md @@ -30,21 +30,43 @@ The following shapes are supported. All `` values use functional no - : Defines an inset rectangle. ```css - inset( {1,4} [round ]? ) + inset( {1,4} [ round <`border-radius`> ]? ) ``` - When all of the first four arguments are supplied they represent the top, right, bottom and left offsets from the reference box inward that define the positions of the edges of the inset rectangle. These arguments follow the syntax of the margin shorthand, that let you set all four insets with one, two or four values. + When all of the first four arguments are supplied, they represent the top, right, bottom and left offsets from the reference box inward that define the position of the edges of the inset rectangle. These arguments follow the syntax of the {{cssxref("margin")}} shorthand, which lets you set all four insets with one, two, three, or four values. - The optional [``](/en-US/docs/Web/CSS/border-radius) argument(s) define rounded corners for the inset rectangle using the border-radius shorthand syntax. + The optional `round <'border-radius'>` parameter defines rounded corners for the inset rectangle using the same syntax as the CSS [`border-radius`](/en-US/docs/Web/CSS/border-radius) shorthand property. A pair of insets in either dimension that add up to more than the used dimension (such as left and right insets of 75% apiece) define a shape enclosing no area. For this specification, this results in an empty float area. +- `{{cssxref("basic-shape/rect","rect()")}}` + + - : Defines a rectangle using the specified distances from the top and left edges of the reference box. + + ```css + rect( [ | auto ]{4} [ round <`border-radius`> ]? ) + ``` + + You specify four values to create the rectangle. Each of the four values is either a ``, a ``, or the keyword `auto`. When using the `rect()` function, you do not define the width and height of the rectangle. The rectangle's dimensions depend on the size of the reference box and the offset values. + + The optional `round <'border-radius'>` parameter defines rounded corners for the inset rectangle using the same syntax as the CSS [`border-radius`](/en-US/docs/Web/CSS/border-radius) shorthand property. + +- `{{cssxref("basic-shape/xywh","xywh()")}}` + + - : Defines a rectangle using the specified distances from the top and left edges of the reference box and the specified width and height of the rectangle. + + ```css + xywh( {2} {2} [ round <`border-radius`> ]? ) + ``` + + The optional `round <'border-radius'>` parameter defines rounded corners for the inset rectangle using the [`border-radius`](/en-US/docs/Web/CSS/border-radius) shorthand syntax. + - `{{cssxref("basic-shape/circle","circle()")}}` - : Defines a circle using a radius and a position. ```css - circle( []? [at ]? ) + circle( ? [ at ]? ) ``` The `` argument represents _r_, the radius of the circle. Negative values are invalid. A percentage value here is resolved from the used width and height of the reference box as `sqrt(width^2+height^2)/sqrt(2)`. @@ -56,7 +78,7 @@ The following shapes are supported. All `` values use functional no - : Defines an ellipse using two radii and a position. ```css - ellipse( [{2}]? [at ]? ) + ellipse( [ {2} ]? [ at ]? ) ``` The `` arguments represent rx and ry, the x-axis and y-axis radii of the ellipse, in that order. Negative values for either radius are invalid. Percentage values here are resolved against the used width (for the rx value) and the used height (for the ry value) of the reference box. @@ -68,7 +90,7 @@ The following shapes are supported. All `` values use functional no - : Defines a polygon using an SVG {{SVGAttr("fill-rule")}} and a set of vertices. ```css - polygon( [,]? [ ]# ) + polygon( ? [ ]# ) ``` `` represents the {{SVGAttr("fill-rule")}} used to determine the interior of the polygon. Possible values are `nonzero` and `evenodd`. Default value when omitted is `nonzero`. @@ -80,7 +102,7 @@ The following shapes are supported. All `` values use functional no - : Defines a shape using an SVG {{SVGAttr("fill-rule")}} and an SVG [path definition](/en-US/docs/Web/SVG/Attribute/d). ```css - path( [,]? ) + path( [ , ]? ) ``` The optional `` represents the {{SVGAttr("fill-rule")}} used to determine the interior of the path. Possible values are `nonzero` and `evenodd`. Default value when omitted is `nonzero`. @@ -198,5 +220,6 @@ div { ## See also - Properties that use this data type: {{cssxref("clip-path")}}, {{cssxref("shape-outside")}} +- [CSS shapes](/en-US/docs/Web/CSS/CSS_shapes) module +- [Overview of CSS shapes](/en-US/docs/Web/CSS/CSS_shapes/Overview_of_shapes) - [Edit Shape Paths in CSS — Firefox Developer Tools](https://firefox-source-docs.mozilla.org/devtools-user/page_inspector/how_to/edit_css_shapes/index.html) -- [Overview of CSS Shapes](/en-US/docs/Web/CSS/CSS_shapes/Overview_of_shapes) diff --git a/files/en-us/web/css/basic-shape/inset/index.md b/files/en-us/web/css/basic-shape/inset/index.md index 0f96baf6eef3d44..3b9b38043175820 100644 --- a/files/en-us/web/css/basic-shape/inset/index.md +++ b/files/en-us/web/css/basic-shape/inset/index.md @@ -7,7 +7,7 @@ browser-compat: css.types.basic-shape.inset {{CSSRef}} -The **`inset()`** [CSS](/en-US/docs/Web/CSS) function is one of the {{cssxref("<basic-shape>")}} [data types](/en-US/docs/Web/CSS/CSS_Types). It defines an inset rectangle. +The **`inset()`** [CSS](/en-US/docs/Web/CSS) function defines a rectangle at the specified inset distances from each side of the reference box. It is a basic shape function used to define one of the {{cssxref("<basic-shape>")}} [data types](/en-US/docs/Web/CSS/CSS_Types). {{EmbedInteractiveExample("pages/css/function-inset.html")}} @@ -43,4 +43,5 @@ In the example below we have an `inset()` shape used to pull content over the fl ## See also - Properties that use this data type: {{cssxref("clip-path")}}, {{cssxref("shape-outside")}} -- [Guide to Basic Shapes](/en-US/docs/Web/CSS/CSS_shapes/Basic_shapes) +- [CSS shapes](/en-US/docs/Web/CSS/CSS_shapes) module +- [Guide to basic shapes](/en-US/docs/Web/CSS/CSS_shapes/Basic_shapes) diff --git a/files/en-us/web/css/basic-shape/rect/index.md b/files/en-us/web/css/basic-shape/rect/index.md new file mode 100644 index 000000000000000..3fa36aaa83b7eba --- /dev/null +++ b/files/en-us/web/css/basic-shape/rect/index.md @@ -0,0 +1,120 @@ +--- +title: rect() +slug: Web/CSS/basic-shape/rect +page-type: css-function +browser-compat: css.types.basic-shape.rect +--- + +{{CSSRef}} + +The **`rect()`** [CSS](/en-US/docs/Web/CSS) function creates a rectangle at the specified distance from the top and left edges of the containing block. It is a basic shape function of the {{cssxref("<basic-shape>")}} [data type](/en-US/docs/Web/CSS/CSS_Types). You can use the `rect()` function in CSS properties such as {{cssxref("offset-path")}} to create the rectangular path along which an element moves and in {{cssxref("clip-path")}} to define the shape of the clipping region. + +## Syntax + +```css +offset-path: rect(0 1% auto 3% round 0 1px); +clip-path: rect(50px 70px 80% 20%); +``` + +### Values + +The inset rectangle is defined by specifying four offset values, starting with the top edge offset and going clockwise, and an optional `round` keyword with the `border-radius` parameter to add rounded corners to the rectangle. Each offset value can be either a ``, a ``, or the keyword `auto`. + +- `` + + - : Specifies the {{cssxref("<length-percentage>")}} value of the distance of the top, right, bottom, or left edge of the rectangle from the top or left edge of the containing block. The first (top) and third (bottom) values are distances from the top edge of the containing block, and the second (right) and fourth (left) values are distances from the left edge of the containing block. The second (right) and third (bottom) values are clamped by the fourth (left) and second (top) values, respectively, to prevent the bottom edge from crossing over the top edge and right edge from crossing over the left edge. For example, `rect(10px 0 0 20px)` is clamped to `rect(10px 20px 10px 20px)`. + +- `auto` + + - : Makes the edge for which this value is used to coincide with the corresponding edge of the containing block. If `auto` is used for the first (top) or fourth (left) value, the value of `auto` is `0`, and if used for the second (right) or third (bottom) value, the value of `auto` is `100%`. + +- `round <'border-radius'>` + - : Specifies the radius of the rounded corners of the rectangle using the same syntax as the CSS [`border-radius`](/en-US/docs/Web/CSS/border-radius) shorthand property. This parameter is optional. + +## Examples + +### Creating offset-path using rect() + +In this example, the {{cssxref("offset-path")}} property uses the `rect()` function to define the shape of the path on which the element, a red box in this case, moves. Three different scenarios are shown, each using different values for the `rect()` function. The arrow inside the boxes points to the right edge of the box. + +```html +
+ Rectangular path 1 +
→
+
+
+ Rectangular path 2 +
→
+
+
+ Rectangular path 3 +
→
+
+``` + +```css +.container { + position: relative; + display: inline-block; + width: 200px; + height: 200px; + border: 1px solid black; + margin: 15px; + text-align: center; +} + +.path { + width: 40px; + height: 40px; + background-color: red; + position: absolute; + animation: move 10s linear infinite; +} + +.rect-path-1 { + offset-path: rect(50px 150px 200px 50px round 20%); +} + +.rect-path-2 { + offset-path: rect(50px auto 200px 50px round 20%); +} + +.rect-path-3 { + offset-path: rect(50px auto 200px auto); +} + +@keyframes move { + 0% { + offset-distance: 0%; + } + 100% { + offset-distance: 100%; + } +} +``` + +#### Result + +{{EmbedLiveSample("Creating an offset-path using rect", "100%", 400)}} + +- The path 1 rectangle specifies the distances of the four edges (top, right, bottom, and left) from the containing block. The top and bottom values are distances from the top edge of the containing block. The right and left values are distances from the left edge of the containing block. In addition, the corner of the rectangle is rounded at `20%`, making the red box element follow the rounded corners as it moves along this path. Notice how the arrow inside the box follows curve at the rectangular path corners. +- The path 2 rectangle is similar to the path 1 rectangle, except that the right value is `auto`, which is equal to the value `100%`. This causes the right edge of the rectangle to match the right edge of the containing block, creating a wider rectangle than path 1. +- The path 3 rectangle specifies both the left and right edge parameters as `auto` and omits the `round <'border-radius'>` parameter. This creates a rectangle that has the width of the containing block and rectangular corners instead of rounded corners like in path 1 and path 2 rectangles. Notice the movement of the arrow inside this box at the corners. + +## Specifications + +{{Specifications}} + +## Browser compatibility + +{{Compat}} + +## See also + +- [`inset()`](/en-US/docs/Web/CSS/basic-shape#inset) function +- [`xywh()`](/en-US/docs/Web/CSS/basic-shape#xywh) function +- {{cssxref("clip-path")}} property +- {{cssxref("offset-path")}} property +- {{cssxref("<basic-shape>")}} data type +- [CSS shapes](/en-US/docs/Web/CSS/CSS_shapes) module +- [Guide to basic shapes](/en-US/docs/Web/CSS/CSS_shapes/Basic_shapes) diff --git a/files/en-us/web/css/basic-shape/xywh/index.md b/files/en-us/web/css/basic-shape/xywh/index.md new file mode 100644 index 000000000000000..bf565774e0c44d0 --- /dev/null +++ b/files/en-us/web/css/basic-shape/xywh/index.md @@ -0,0 +1,105 @@ +--- +title: xywh() +slug: Web/CSS/basic-shape/xywh +page-type: css-function +browser-compat: css.types.basic-shape.xywh +--- + +{{CSSRef}} + +The **`xywh()`** [CSS](/en-US/docs/Web/CSS) function creates a rectangle using the specified distances from the left (`x`) and top (`y`) edges of the containing block and the specified width (`w`) and height (`h`) of the rectangle. It is a basic shape function of the {{cssxref("<basic-shape>")}} [data type](/en-US/docs/Web/CSS/CSS_Types). You can use the `xywh()` function in CSS properties such as {{cssxref("offset-path")}} to create the rectangular path along which an element moves and in {{cssxref("clip-path")}} to define the shape of the clipping region. + +## Syntax + +```css +offset-path: xywh(0 1% 2px 3% round 0 1px 2% 3px); +clip-path: xywh(1px 2% 3px 4em round 0 1% 2px 3em); +``` + +### Values + +- `` + - : Specifies the {{cssxref("<length-percentage>")}} values for the `x` and `y` coordinates of the rectangle. +- `` + - : Specifies non-negative {{cssxref("<length-percentage>")}} values for the width and height of the rectangle. The minimum value can be zero, and the maximum value has no limit. +- `round <'border-radius'>` + - : Specifies the radius of the rounded corners of the rectangle using the same syntax as the CSS [`border-radius`](/en-US/docs/Web/CSS/border-radius) shorthand property. This parameter is optional. + +## Examples + +### Creating offset-path using xywh() + +In the example below, the {{cssxref("offset-path")}} property uses the `xywh()` function to define the shape of the path on which the element, a magenta box in this case, moves. Two different scenarios are shown, each with different values for the `xywh()` function. The arrow inside the boxes points to the right edge of the box. + +```html +
+ Rectangular path 1 +
→
+
+
+ Rectangular path 2 +
→
+
+``` + +```css +.container { + position: relative; + display: inline-block; + width: 200px; + height: 200px; + border: 1px solid black; + margin: 30px; + text-align: center; +} + +.path { + width: 50px; + height: 50px; + position: absolute; + background-color: magenta; + animation: move 10s linear infinite; +} + +.xywh-path-1 { + offset-path: xywh(20px 20px 100% 100% round 10%); +} + +.xywh-path-2 { + offset-path: xywh(20px 30% 150% 200%); +} + +@keyframes move { + 0% { + offset-distance: 0%; + } + 100% { + offset-distance: 100%; + } +} +``` + +#### Result + +{{EmbedLiveSample("Creating offset-path using xywh", "100%", 600)}} + +- The path 1 rectangle is offset by `20px` from the left and top edges of the containing block. This path rectangle has the same dimension as the containing block, that is, the width is `100%` of the width of the containing block, and the height is `100%` of the height of the containing block. Notice how the arrow inside the box follows the `10%` curve (defined by `round 10%`) at the rectangular path corners. +- As the upper limit of both width and height in `xywh()` is infinity, setting the height to `200%` in the path 2 rectangle makes the generated rectangle twice as tall as the containing block. Notice how the arrow inside the box behaves at the corners when no `round <'border-radius'>` is specified. + +## Specifications + +{{Specifications}} + +## Browser compatibility + +{{Compat}} + +## See also + +- [`inset()`](/en-US/docs/Web/CSS/basic-shape#inset) function +- [`rect()`](/en-US/docs/Web/CSS/basic-shape#rect) function +- {{cssxref("clip-path")}} property +- {{cssxref("offset-path")}} property +- {{cssxref("<basic-shape>")}} data type +- [CSS shapes](/en-US/docs/Web/CSS/CSS_shapes) module +- [Guide to basic shapes](/en-US/docs/Web/CSS/CSS_shapes/Basic_shapes)