## `plot::Group` -- a group of graphical primitives

#### Introduction

`plot::Group``(object1, object2...)` groups the graphical primitives `object1`, `object2`... into a single graphical primitives.

#### Creating Elements

`plot::Group(object1 <, object2...> <, option1, option2...>)`

#### Parameters

`object1, object2` | - | either two- or three-dimensional graphical primitives, i.e., objects of type `"graphprim"` of the same dimension
`option1, option2, ...` | - | plot option(s) of the form `OptionName = value`

#### Related Domains

`plot::Scene`, `RGB`

#### Related Functions

`plot`, `plot2d`, `plot3d`, `plot::copy`

#### Details

- Objects generated by `plot::Group` represent groups of graphical primitives that can be displayed via the call `plot(...)`, or used with other graphical primitives of the `plot` library.
- The given graphical primitives must either be two-dimensional or three-dimensional, otherwise an error message is issued.
- Note that the call `plot::Group(`object1`)` returns an object of the domain `plot::Group`, i.e., a group can consists of only one graphical primitive.
- An object of `plot::Group` has type `"graphprim"`, i.e., if `o` is such an object, then the result of `type(o)` is the string `"graphprim"`.
- The plot options `option1`, `option2`... must be valid plot options for two- and three-dimensional graphical primitives, respectively. Available options and their default values can be found on the corresponding help pages for the objects `object1`, `object2`....

  The plot options `option1`, `option2`... are passed to each graphical primitive `object_i`. This means, a plot option should be a valid plot option for every given graphical primitive `object_i`! If an invalid option is given for some primitives of the group, then a warning message is issued, and the setting of this option has no effect on the corresponding graphical primitives.

- A so-called attribute of a graphical primitive is a named entry of the object which can be accessed via the slot operator `::`.

  Each attribute has the property ``read'', i.e., the value of an attribute `attr` of a graphical primitive `o` can be read with `o::attr`. If the attribute also has the ``write'' property, then the value of the attribute can be changed with `o::attr := new_value`.

  The following attributes are available for a group of graphical objects:

  attribute | values | properties
  `dimension` | The dimension of the group, that is the dimension of the graphical primitives `object1`, `object2`... where the dimension of `object1`, `object2`... must be equal. This attribute exists in order to have an efficient access to the dimension of a group primitive. Because not every graphical primitive has this attribute, one should call the method `"dimension"` (see below) instead in order to determine the dimension of graphical primitives. | read
  `objects` | A list of the graphical primitives of the group. A graphical primitive is an object of type `"graphprim"`. The initial value is the list `[object1, object2...]` of the parameters `object1`, `object2`... | read/write
  `plotdata` | List of the plot data of the group primitive in a `plot2d` and `plot3d` conforming syntax, respectively. The value of this attribute can be read if the method `"getPlotdata"` (see below) was called before. The initial value is the empty list `[]`. | read

  See the examples of the help page of `plot::Scene` about working with attributes.

#### Operands

The operands of an object of `plot::Group` are the parameters `object1`, `object2`... (in that order).

#### Important Operations

Operands of a group primitive can be accessed either using the system function `op`, the index operator `[ ]`, or using the attribute `objects` described above. For example, if `group` is such an object, then the calls `op(group,1)`, `group[1]` and `group::objects[1]` return the first graphical object `object1` of the group.

Via `group[i] := g` or `group::objects[i] := g`, the ith object of the group is replaced by the graphical primitive `g` (which must be an object of type `"graphprim"`).

See the methods `"op"`, `"_index"`, `"set_index"` and `"slot"` below.

Use the slot operator `::` to get or set plot options of the grouped graphical primitives. For example, if `group` is such an object, then `group::Color := RGB::Red` changes the color of each graphical primitive of `group` to red.

#### Result of Evaluation

Evaluating an object of type `plot::Group` returns itself.

#### Function Call

Calling an object of `plot::Group` as a function yields the object itself, regardless of the arguments. The arguments are not evaluated.

#### Method _index: indexed access to the operands of a group primitive

- `_index(dom group, positive integer i)`
- - Returns the `i`th graphical primitive of `group`. If `i` is greater than the number of graphical primitive of `group`, then `FAIL` is returned.
  - This method overloads the system function `_index`, i.e., one may use it in the form `function[i]`, or in functional notation `_index(group, i)`.

#### Method dimension: dimension of a group primitive

- `dimension(dom group)`
- - Returns the value of the attribute `dimension`, i.e., the integer 2 or 3 (see the table of attributes above).

#### Method getPlotdata: create the plot data of a group primitive

- `getPlotdata(dom group)`
- - Returns a list of inner lists, where each inner list is a plot description of a graphical primitive of `group` in a `plot2d` and `plot3d` conforming syntax, respectively, i.e., an inner list has the form `[Mode = ..., ...]`.

    For example, with `s := plot::Group::getPlotdata(group)` the call `plot2d(op(s))` and `plot3d(op(s))`, respectively, gives a plot of `group`.

  - The result is stored as the value of the attribute `plotdata` of `group`.
  - This method is called from `plot::Scene` to build the plot data of the graphical scene.

#### Method nops: number of operands of a group primitive

- `nops(dom group)`
- - Returns the number of graphical primitives of `group`.
  - This method overloads the system function `nops`, i.e., one may use it in the form `nops(group)`.

#### Method op: extract operands of a group primitive

- `op(dom group, positive integer i)`
- - Returns the `i`th graphical primitive of `group`. If `i` is greater than the number of graphical primitives of `group`, then `FAIL` is returned.
  - This method overloads the system function `op`, i.e., one may use it in the form `op(group, i)`.

#### Method set_index: set operands of a group primitive

- `set_index(dom group, positive integer i, graphprim object)`
- - Replaces the `i`th graphical primitive of `group` by the graphical primitive `object`.
  - If `i` is greater than the number of graphical primitives of `group`, or if `object` is not of type `"graphprim"`, then a warning message is issued. In this case the call of this method has no effect on the object `group`.

#### Method slot: read attributes, and write attributes and plot options

- `slot(dom group, string slotname)`
- - Reads the value of the slot `slotname` of `group`. `slotname` must be the name of an attribute of a group primitive (see the table of attributes above), otherwise an error message is issued.
  - This method overloads the system function `slot`, i.e., one may use it in the form `group::slotname_id` (here, `slotname_id` must be the identifier corresponding to the string `slotname`), or in functional notation `slot(group, slotname)`.
- `slot(dom group, string slotname, any val)`
- - If `slotname` is an attribute of a group primitive, then this method changes the value of this attribute to `val` (see the table above for the attributes of a group primitive).

    Otherwise the slot `slotname` of each primitive of the group is changed to the value `val`. If `slotname` is an invalid attribute or plot option of some primitives of the group, then a warning message is issued that the change is ignored for the corresponding primitive.

  - This method overloads the system function `slot`, i.e., one may use it in the form `group::slotname_id := val` (here, `slotname_id` must be the identifier corresponding to the string `slotname`), or in functional notation `slot(group, slotname, val)`.

#### Method copy: create a copy of a group primitive

- `copy(dom group)`
- - Returns a copy of the object `group`.
  - This method is called from the function `plot::copy`. See its help page for details.

#### Method expose: expose the definition of a group

- `expose(dom group)`
- - This method returns a sequence of the graphical primitives of `group`.
  - This method overloads the system function `expose`, i.e., one may use it in the form `expose(group)`.

#### Method modify: modify a copy of a group primitive

- `modify(dom group, equation(s) Name1 = value1...)`
- - Creates a copy of the object `group` and changes the slots `Name1`... of this copy to the new values `value1`...
  - The identifiers `Name1`... must be names of attributes of a group primitive or plot options of graphical primitives of `group`. Otherwise a warning message is issued, and the slot remains unchanged. Also, if one of the values `value1`... is not an admissible value for the corresponding attribute or plot option, respectively, the change of the slot is ignored.

    See the tables of available attributes above.

  - This method is called from the function `plot::modify`.

#### Method print: printing a group primitive

- `print(dom group)`
- - This method returns an unevaluated expression of the form `plot::Group()`. It is used to print objects of `plot::Group` to the screen.
  - Call `expose(group)` to expose the graphical primitives of the group.
  - See the system function `print` for details.

#### Example 1

We create a group consisting of a graph of function and two vertical dashed lines from some points on the x-axis to the corresponding points on the graph:

    >> g := plot::Group(
         plot::Function2d(4 - x^2, x = -2..2),
         plot::line([-1, 0], [-1, 3], LineStyle = DashedLines),
         plot::line([1, 0], [1, 3], LineStyle = DashedLines)
       )

                                   plot::Group()

To plot the object in a graphical scene, enter:

    >> plot(g)

Plot options can either be specified as additional arguments to the call `plot::Group(...)`, or set via the slot operator `::` as follows:

    >> g::Color := RGB::Blue: plot(g)

If a plot option is invalid for some primitives of the group, then a warning message is issued. For example, the plot option Grid only exists for graphs of functions but not for polygons (the two lines here), and thus specifying this option only has an effect on the first primitive of the group `g`:

    >> g::Grid := [200]:

          Warning: unknown option name 'Grid'; assignment ignored [plot:\
          :Polygon::slot]
          Warning: unknown option name 'Grid'; assignment ignored [plot:\
          :Polygon::slot]

#### Example 2

This example illustrates how primitives of the group can be extracted and manipulated seperately. We take the group of the previous example:

    >> g := plot::Group(
         plot::Function2d(4 - x^2, x = -2..2),
         plot::line([-1, 0], [-1, 3], LineStyle = DashedLines),
         plot::line([1, 0], [1, 3], LineStyle = DashedLines)
       )

                                   plot::Group()

With `expose` one can see the definition of the group `g` and the definition of its graphical primitives:

    >> expose(g)

                                          2
          plot::Group(plot::Function2d(- x  + 4, x = -2..2),

             plot::Polygon(plot::Point(-1, 0), plot::Point(-1, 3)),

             plot::Polygon(plot::Point(1, 0), plot::Point(1, 3)))

In order to change the color of the graph, which is the first graphical primitive of the group into blue, we enter:

    >> (g[1])::Color := RGB::Blue: plot(g)

#### Changes

- new function

Do you have questions or comments?
Copyright © SciFace Software GmbH & Co. KG 2000