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

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

Resatisfiable

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