
viewable_create(?ViewableName, +Elements, ++Type)

   Create a viewable, specifying type.

Arguments
   ViewableName        A string or atom; the name of the new viewable.
   Elements            A list nested to at least a depth equal to the number of dimensions, or an array with sufficient dimensions (as created for example by dim/2).
   Type                A ground term which is a valid viewable type. 

Type
   library(viewable)

Description


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

	This predicate creates a new viewble by specifying its name,
	elements and type.  At present the type must be of the form
	array(FixityList, ElementType) where  FixityList is a list
	with an atom fixed or flexible specifying
	the fixity for each dimension. The fixity denotes whether the
	dimension's size is fixed or may vary during the time when the
	viewable is existent. ElementType is a term which
	specifies the type of the constituent viewable elements.  Currently
	there are two supported element types: any
	which includes any ECLiPSe termnumeric_bounds
	which includes any ground number, integer fd
	variables, ic variables and range
	variables (including eplex and ria
	variables). 

	Visualisation clients, if there are any, are notified of the new
	viewable when it is created. On backtracking over a call to
	viewable_create/3, the viewable is destroyed, and
	visualisation clients are also notified of this. 

	ViewableName is a global handle which can be used to
	access the viewable while it is existent. If ViewableName
	is a variable, it is instantiated to an atom. The atom is unique in
	the sense that no two existent viewables will share the same name
	at any point during the lifetime of the ECLiPSe engine.

        The number of dimensions is specified by the length of
        FixityList in Type. Elements is a nested
        list or array. The depth of nesting is usually at least the number
        of dimensions specified in FixityList. However, dimensions
        with an initial size of 0 are also allowed, and these can
        implicitly contain an arbitrary number of further dimensions, also
        assumed to be of initial size 0. So for example an
        Elements argument of [[],[],[]] or
        []([],[],[]) can be used with a FixityList of
        [fixed, flexible], giving an initial size of 3 x 0, or
        used with a FixityList of [fixed, flexible,
        flexible, flexible], giving an initial size of 3 x 0 x 0 x
        0. Be sure to make any initially empty dimensions flexible!
        Elements must also be regular: each inner list / array at
        the same level of nesting must be the same length, down to the
        level equal to the number of dimensions.

        viewable_create/3 sets location names (e.g. row/column
        names) to "1", "2", etc. For more control over location names use 
        viewable_create/4.

Resatisfiable
   no

Exceptions
     4 --- ViewableName is not an atom, string or free variable.
     1 --- ViewableName is the name of an existent viewable.
     1 --- Elements is not a regular nested list or array with enough dimensions.
     1 --- Type is not a ground valid type.
     5 --- One of the viewable elements violates the element type.

Examples
   

[Assuming that at least one visualisation client is registered] 

       Success:

       viewable_create(viewable1, [X, Y, Z], array([fixed], any)).

       lib(fd), fd:([X, Y, Z]::1..10), 
       viewable_create(viewable1, [X, Y, Z], array([fixed], numeric_bounds)).

       viewable_create(viewable1, [3.2, 5.00__5.01, 7], 
                       array([fixed], numeric_bounds)).

       viewable_create("viewable1", [](X, Y, Z), array([flexible], any)).

       viewable_create(m, [], array([flexible], any)).

       viewable_create(var23, [[],[],[]], array([fixed, flexible], any)).

       viewable_create(var315, []([]([](R, T, [E, X, Y]), 
                                     [](W, T, grok(D))), 
				  []([](A, B, C),
				     [](R, E, W))), 
		       array([fixed, flexible, flexible], any)).

       viewable_create(m,[[],[],[]],array([fixed, flexible, flexible],any)).
       [Note: the initial size of this viewable would be 3 x 0 x 0]
 

       Exceptions raised:

       viewable_create(2, [x,y,z], array([fixed], any)).
       [gives error 4] 

       viewable_create(v1, [x,y,z], array([fixed], any)), 
       viewable_create(v1, [x,y,z], array([fixed], any)).
       [gives error 1] 

       viewable_create(v1, _, array([fixed], any)).
       [gives error 1] 

       viewable_create(v1, [x,y,g], array([fixed, fixed], any)).
       [gives error 1] 

       viewable_create(v1, [x,y,x], array([], any)).
       [gives error 1] 

       viewable_create(v1, [x,y,x], slorg([fixed], any)).
       [gives error 1] 

       viewable_create(v1, [x,y,x], nurg).
       [gives error 1] 

       viewable_create(v1, [x,y,x], numeric_bounds).
       [gives error 5] 
				    

See Also
   viewable_create / 2, viewable_create / 4, viewable_expand / 3
