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

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

Create a viewable, specifying both type and location names.

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) or a graph structure.
Type
  A ground term which is a valid viewable type.
LocNamesList
  A list of lists of strings (location names) or a list of semantic markup terms from graph structures.

## Description

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

This predicate works exactly the same as `viewable_create/3` except that you have the added ability to set location names (e.g. row/column names) for arrays and to indicate which elements of the edge info structure should be attached to edge labels for graphs.

For array type viewables the LocNamesList argument should be a list as long as the number of dimensions in the viewable. The ith element LocNames of LocNamesList should be a list whose length is equal to the size of the ith dimension of the new viewable. The jth element of LocNames should be a ground string and this will become the name of the jth location of the ith dimension.

For graph type viewables the LocNamesList argument should be a list of the following form.

    [
     node_property([0->[name(NodeInfoName), label]]),
     edge_property([Index->[name(EdgeInfoName), label]])
    ]

Where `NodeInfoName` is a meaningful name for the information to be displayed at the nodes in the graph. eg. If the graph represented a computer network, the nodes may show individual machine names. In such a case, `"machine name"` would be a likely candidate for the NodeInfoName argument. Similarly `EdgeInfoName` refers to the information associated with edge labels.

The `Index` argument specifies which part of the edge info field should be shown on edges. 0:The whole edge info structure. N:The Nth argument of the edge info structure. [...,I,J,K]:The Kth argument of the Jth argument of the Ith argument... of the edge info structure. See below for examples.

For a more detailed description of creating viewables, refer to the documentation for `viewable_create/3`.

### 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.
(5) type error
  LocNamesList is not a correctly-sized list of correctly-sized lists of strings.

## Examples

                To create a 2 x 3 viewable, you could do:

                viewable_create(v1, [[A,B,C], [D,E,F]],
                                array([fixed, fixed], any),
                                [["foo", "bar"], ["tom", "dick", "harry"]]).

                This would have two rows (named "foo" and "bar") each
    	    with three columns (named "tom", "dick" and
    	    "harry").

                To create a graph viewable where node names are attached
                to node labels and edge info fields are attached to edge
                lables (ie info(1,foo(A)), info(2,foo(B)) and
                info(3,foo(C)) as per viewable_create/3).

                lib(graph_algorithms),
                make_graph_symbolic([](n1,n2,n3),
                                    [edge(n1,n2,info(1,foo(A)),
                                     edge(n2,n3,info(2,foo(B)),
                                     edge(n1,n3,info(3,foo(C))], Graph),
                viewable_create(v2, Graph, graph(fixed),
                                [node_property([0->[name('node names'), label]]),
                                 edge_property([0->[name('edge info'), label]])
                                ]).

                To create a graph where the edges are labelled with the
                second argument of the edge info structure. (ie with the
                structures foo(A), foo(B) and foo(C))

                lib(graph_algorithms),
                make_graph_symbolic([](n1,n2,n3),
                                    [edge(n1,n2,info(1,foo(A)),
                                     edge(n2,n3,info(2,foo(B)),
                                     edge(n1,n3,info(3,foo(C))], Graph),
                viewable_create(v2, Graph, graph(fixed),
                                [node_property([0->[name('node names'), label]]),
                                 edge_property([2->[name('edge info'), label]])
                                ]).

                To create a graph where the edges are labelled with the
                first argument of the nested structure at the second
                argument of the edge info structure. (ie with the
                variables A, B and C)

                lib(graph_algorithms),
                make_graph_symbolic([](n1,n2,n3),
                                    [edge(n1,n2,info(1,foo(A)),
                                     edge(n2,n3,info(2,foo(B)),
                                     edge(n1,n3,info(3,foo(C))], Graph),
                viewable_create(v2, Graph, graph(fixed),
                                [node_property([0->[name('node names'), label]]),
                                 edge_property([[2,1]->[name('edge info'), label]])
                                ]).

## See Also

viewable_create / 2, viewable_create / 3, viewable_expand / 4, graph_algorithms : make_graph / 3