[ library(viewable) | Reference Manual | Alphabetic Index ]

# viewable_expand(++ViewableName, ++DimensionNumber, +ExtraElements)

Expand a dimension of a viewable by adding new elements.

ViewableName
  A string or atom; the name of an existent viewable
DimensionNumber
  An integer: the number of the dimension to be enlarged.
ExtraElements
  A nested list or an array of the right size/dimensions, containing the new viewable elements.

## Description

NOTE:When there are no registered visualisation clients, this predicate succeeds with any arguments, and has no effect.

A viewable which has a flexible dimension (see `viewable_create/3`) may be expanded along that dimension by adding new elements. The dimension must have been declared flexible when the viewable was first created. The ExtraElements argument is of the same format as the Elements argument of `viewable_create/3`.

The number and size of the dimensions of ExtraElements depends on the number and size of dimensions of the viewable being expanded. ExtraElements should have one less dimension than the viewable -- dimension DimensionNumber should be missing. The remaining dimensions should have the same sizes as the corresponding dimensions in the viewable.

For example, a viewable of size 3 x 0 x 0 with all dimensions flexible, can be expanded along dimenson 3 using an ExtraElements argument of []([], [], []) which has size 3 x 0. The viewable would then have size 3 x 0 x 1. It could then be expanded along dimension 1 using `[]` as ExtraElements since `[]` can implicitly have the size 0 x 1. The viewable would then have the size 4 x 0 x 1. Then dimension 2 could be expanded using `[[W],[X],[Y],[Z]]` for ExtraElements as this has size 4 x 1. The final size of the viewable would then be 4 x 1 x 1.

The extra viewable elements must each also conform to the element type specified when the viewable was created.

Note that when the viewable has one dimension, the ExtraElements argument will simply become the new element itself.

`viewable_expand/3` sets the name of the new location (e.g. the column or row name) to its number as a string. For example, adding a third row using `viewable_expand/3` will result in the row being named "3". For more control over the name of the new location use `viewable_expand/4`.

### Fail Conditions

Fails if ViewableName is not the name of an existent viewable, or if the requested dimension of the viewable is not flexible.

### Resatisfiable

no

### Exceptions

(4) instantiation fault
  ViewableName is not a string or atom
(5) type error
  DimensionNumber is not a ground integer
(6) out of range
  DimensionNumber is not positive, or exceeds the viewable's number of dimensions
(1) general error
  ExtraElements is not a regular nested list or array of the correct size/dimensions
(5) type error
  ExtraElements contains elements which do not conform to the element type of the viewable

## Examples

    [Assuming that at least one visualisation client is registered]

           Success:

           viewable_create(v1, [[X, Y, Z], [A, B, C]],
           	               array([flexible, fixed], any)),
           viewable_expand(v1, 1, [R, S, T]).

           lib(fd), fd:([X, Y, Z, R] :: 1..10),
           viewable_create(v1, [X, Y, Z], array([flexible], numeric_bounds)),
           viewable_expand(v1, 1, R).

           viewable_create(v1, []([](X, Y, Z), [](A, B, C)),
           	               array([fixed, flexible], any)),
           viewable_expand(v1, 2, [R, S]).

           viewable_create(v1, [[], [], []],
    		       array([flexible, flexible, flexible], any)),
           viewable_expand(v1, 3, []([], [], [])),
           viewable_expand(v1, 1, []),
           viewable_expand(v1, 2, [[W], [X], [Y], [Z]]),
           viewable_size(v1, Size).
           [gives Size = [4,1,1]]

           viewable_create(v1, [], array([flexible], any)),
           viewable_expand(v1, 1, F),
           viewable_expand(v1, 1, G),
           viewable_size(v1, Size).
           [gives Size = [2]]

           Failure:

           viewable_expand(no, 2, [R, S]).

           viewable_create(v1, [[X, Y, Z], [A, B, C]],
    	               array([fixed, flexible], any)),
           viewable_expand(v1, 1, [R, S, T]).

           viewable_create(v1, [[X, Y, Z], [A, B, C]],
    	               array([flexible, fixed], any)),
           viewable_expand(v1, 2, [R, S]).

           Exceptions raised:

           viewable_create(v1, [[X, Y, Z], [A, B, C]],
    	               array([flexible, fixed], any)),
           viewable_expand(_, 1, [R, S, T]).
           [gives error 4]

           viewable_create(v1, [[X, Y, Z], [A, B, C]],
    	               array([flexible, fixed], any)),
           viewable_expand(v1, _, [R, S, T]).
           [gives error 5]

           viewable_create(v1, [[X, Y, Z], [A, B, C]],
                           array([flexible, fixed], any)),
           viewable_expand(v1, 3, [R, S, T]).
           [gives error 6]

           viewable_create(v1, []([](X, Y, Z), [](A, B, C)),
    	               array([fixed, flexible], any)),
           viewable_expand(v1, 2, _).
           [gives error 1]

           viewable_create(v1, [[X, Y, Z], [A, B, C]],
    	               array([flexible, fixed], any)),
           viewable_expand(v1, 1, [R, S, T, Q]).
           [gives error 1]

           lib(fd), fd:([X, Y, Z] :: 1..10),
           viewable_create(v1, [X, Y, Z], array([flexible], numeric_bounds)),
           viewable_expand(v1, 1, an_atom)
           [gives error 5]

## See Also

viewable_expand / 4, viewable_create / 3, viewable_size / 2, viewable_type / 2