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

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

Create a viewable, specifying type.
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, an array with sufficient dimensions (as created for example by dim/2) or graph structure.
Type
A ground term which is a valid viewable type.

Description

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

This predicate creates a new viewable by specifying its name, elements and type. At present the type must be of the form array(FixityList, ElementType) or graph(fixed) where 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.

For array types, 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) instantiation fault
ViewableName is not an atom, string or free variable.
(1) general error
ViewableName is the name of an existent viewable.
(1) general error
Elements is not a regular nested list or array with enough dimensions.
(1) general error
Type is not a ground valid type.
(5) type error
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]

       lib(graph_algorithms),
       make_graph(3,[e(1,2,e1), e(2,3,e2), e(1,3,e3)], Graph),
       viewable_create(m, Graph, graph(fixed)).
       [Note: the node will be labelled with the numbers '1', '2' and '3',
       the edges labelled 'e1', 'e2' and 'e3']
       
       lib(graph_algorithms),
       make_graph_symbolic([](n1,n2,n3),[edge(n1,n2,e1), edge(n2,n3,e2), edge(n1,n3,e3)], Graph),
       viewable_create(m, Graph, graph(fixed)).
       [Note: the node will be labelled with the strings 'n1', 'n2' and 'n3',
       the edges labelled 'e1', 'e2' and 'e3']

       lib(eplex_with_ic),
       eplex_instance(my_instance),
       my_instance: eplex_solver_setup(min(X)),
       viewable_create(eplex,[X,Y],array([fixed],changeable(my_instance,numeric_bounds))),
       viewable_create(ic,[X,Y],array([fixed],numeric_bounds)),
       my_instance: (X+Y >= 3),
       my_instance: (X-2*Y =:= 0),
       my_instance: eplex_solve(Cost).       
       [Note: this creates two viewables, one showing the solution as
        assigned by eplex, the other showing the ic bounds]

       lib(s_eplex),
       eplex_instance(my_instance),
       my_instance: eplex_solver_setup(min(X)),
       viewable_create(eplex,[X,Y],array([fixed],changeable(my_instance,numeric_bounds))),
       my_instance: (X+Y >= 3),
       my_instance: (X-2*Y =:= 0),
       my_instance: eplex_solve(Cost).       
       [Note: this creates a single viewable using the standalone eplex
        library and shows how to visualise the bounds stored in the external
        solver]


       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, graph_algorithms : make_graph / 3