Graphics Entities description of the graphics entities data structures

## Description

In Scilab, graphics window and the drawing it contains are represented by hierarchical entities. The hierarchy top level is the `Figure`. Each `Figure` defines at least one child of type `Axes`. Each `Axes` entity contains a set of leaf entities which are the basic graphics objects like `Polylines`, `Rectangles`, `Arcs`, `Segs`,... It can also contain an `Compound` type which is recursive set of entities. The main interest of the graphic mode is to make property change easier. This graphics' mode provides a set of high-level graphing routines (see set, get) used to control objects' properties such as data, coordinates and scaling, color and appearances without requiring to replay the initial graphics commands.

Graphics entities are associated to Scilab variables of type `handle`. The handle is an unique identifier which is associated to each instance of a created graphical entity. Using this handle, it will be possible to reach entities' properties through `set` and `get` routines. The handles are also used to manipulate graphics objects, to move them, to make copies or delete them.

Console, root, mouse:

  With its menus, the console may be considered as a special graphic windows. Its menus and some graphical meta options may be addressed through its handle as returned by `c=get(0)`. See Console properties for details.

  The root object is a virtual graphical object used to get the computer screen properties. Its handle is the same as the console's one: `r=get(0)`, but the screen properties can be addressed only in read-only mode. See Root properties for details.

  On Windows, some additional screen, windowing and mouse parameters may be retrieved through the getsystemmetrics function.

Figure:

  The `Figure` entity is the top level of the graphics entities hierarchy. This entity defines the parameters for the figure itself as well as the parameters' default values for the children creation. The figure children are the `Axes` entities.

  The handle on the current figure (the figure used where the drawing are sent) may be got using `get("current_figure")` and it may be set using `set("current_figure",h)`, where `h` is either a handle on a figure or a `figure_id`. In this last case if the figure does not already exists, it is created.

  See figure properties for details.

Axes:

  The `Axes` entity is the second level of the graphics entities hierarchy. This entity defines the parameters for the change of coordinates and the axes drawing as well as the parameters' default values for its children creation. See axes properties for details. The handle on the current `Axes` may be got using `get("current_axes")`.

Compound:

  The `Compound` entity is just a vector of children and with a single property (visibility property). It is used to glue a set of entities together.

  See glue, unglue and Compound properties functions.

Axis:

  The `Axis` entity is a leaf of the graphics entities hierarchy. This entity defines the parameters for axis scaling and appearance.

  See axis properties for details.

Polyline:

  The `Polyline` entity is a leaf of the graphics entities hierarchy. It defines 2D and 3D polylines and polylines extensions drawing properties.

  See polyline properties for details.

Arc:

  The `Arc` entity is a leaf of the graphics entities hierarchy. This entity defines the parameters for ellipses and part of ellipses.

  See arc properties for details.

Rectangle:

  The `Rectangle` entity is a leaf of the graphics entities hierarchy. This entity defines the parameters for rectangles and filled rectangles.

  See rectangle properties for details.

Surface:

  The `Surface` entity is a leaf of the graphics entities hierarchy. It has subtypes `Fac3d` or `Plot3d`. This entity defines the parameters for 3d surface plots.

  See surface properties for details.

Fec:

  The `Fec` entity is a leaf of the graphics entities hierarchy. It represents 2D finite elements plots.

  See fec properties for details.

Grayplot:

  The `Grayplot` entity is a leaf of the graphics entities hierarchy. It represents 2D plots of surface using colors and images.

  See grayplot properties for details.

Matplot:

  The `Matplot` entity is a leaf of the graphics entities hierarchy. It represents 2D plots using integer matrices.

  See Matplot properties for details.

Segs:

  The `Segs` entity is a leaf of the graphics entities hierarchy. This entity defines the parameters for a set of colored segments or colored arrows.

  See segs properties for details.

Champ:

  The `Champ` entity is a leaf of the graphics entities hierarchy. This entity defines the parameters for a 2D vector field.

  See champ properties for details.

Text:

  The `Text` entity is a leaf of the graphics entities hierarchy. This entity defines the parameters for string drawing.

  See text properties for details.

Label:

  The `Label` entity is a child of the `Axes` graphics entity. This entity defines the parameters for the 3 x, y and z labels and title drawn on a graphics window.

  See Label entity properties for details.

Legend:

  The `Legend` entity is a leaf of the graphics entities hierarchy. This entity defines the parameters for legends drawn below `plot2dx` graphs. This entity requires further developments.

  See Legend entity properties for details.

Light:

  Lights in scilab approximates real world lighting where the appearance of a surface is given by interactions between light rays and the material properties of the surface. Because simulate real world lighting is complex and computationally expensive, one uses a simplified model.

  See light entity properties for details.

### Other entities

Interactive components (uicontrol)

  Scilab allows to create graphical interactive components like sliders, spinners, editable tables, editable texts on graphics, checkboxes, groups of radio buttons, listboxes, popup menus, push buttons, etc. These objects are direct children of the figure where they are defined. Their properties can be set and tuned through their handles as for any other graphical objects. Please see uicontrol properties for details.

UI menus

  uimenu() allows to add and manage some menus on the menu bar of any graphical figure. `uimenu()` returns a handle through which the contents and properties of the created menu can be addressed. Please see uimenus properties for details.

## Examples

    //Play this example line per line

    // Creates a figure in entity mode, gets its handle, displays its properties
    f = scf()
    a = f.children // the handle on the Axes child
    x = (1:10)';  plot2d(x,[x.^2 x.^1.5])
    e = a.children //Compound of 2 polylines

    p1 = e.children(1)  //the last drawn polyline properties
    p1.foreground = 5;  // change the polyline color
    e.children.thickness = 5; // change the thickness of the two polylines

    delete(e.children(2))

    move(e.children,[0,30]) //translate the polyline

    a.axes_bounds = [0 0 0.5 0.5];

    subplot(222) //create a new Axes entity
    plot(1:10);
    a1 = f.children(1);  // get its handle
    copy(e.children,a1); // copy the polyline of the first plot in the new Axes
    a1.data_bounds = [1 0;10 100]; //change the Axes bounds

    scf(10); // create a new figure with figure_id=10
    plot3d() // the drawing are sent to figure 10
    scf(f);  // makes the previous figure the current one
    plot2d(x,x^3)  //the drawing are sent to the initial figure

## See also

- set
- get
- move
- delete
- ged
- object editor
- plot
- surf
- getsystemmetrics
- setlookandfeel