The Graphic Hierarchy
All the handles are stored inside a tree called the graphic hierarchy. The ancestor of the hierarchy is a Figure object which is visually represented by a graphic tab, scrollbars and canvas. All the descendants of the parent figure are the objects drawn inside the Tab.
Here is a little scheme of the hierarchy.
There are some specificities about handles.
- Direct children of the figure can be only axes (also called subwin), uicontrol or uimenu. All other objects (polylines, surfaces, ...) must be located under an axes/subwin or a compound object.
- Axes/subwin, uicontrol or uimenu can only be children of a Figure.
- Labels objects can not be created from Scilab. When an axes/subwin object is created, it automatically has 4 labels children representing the title and the labels for X, Y and Z coordinate axes. Labels are also automatically destroyed with the axes/subwin object. The labels can be accessed from the axes/subwin children and also directly from the axes/subwin object. It stores direct pointers on the labels.
- Axes/subwin can have only one children of type legend.
Note to Developers: Note that inside Scilab source code, the terminology is somewhat confusing. What is referred to as axes above is represented by the SCI_SUBWIN entity type. The entity type SCI_AXES actually refers to coordinate axes. Thus, for developers a plotting area within a figure is 'subwin' and the coordinate axis are 'axes'. For the user, a plotting area within a figure is 'axes'. 'Axes' is used within the code for both subwin and coordinate axes at certain places.
To navigate in the hierachy, the sciRelationShip structure located in the sciPointObj one is used. It contains the pointer to the parent of the object and the list of its children. The list is for now coded by hand, but might be rewritten using a standard container.
However, to navigate in the hierachy, it is recommended to use the sciGetParent, sciGetSons and sciGetLastSon functions.
The relationship also contains the list of selected objects between its children. This list is however only used for subwin objects now. The handle long value is also located here.
When a graphic object is created, some of its values are given by its parent subwindow. For example when creating a polyline with plot(1:10), the thickness of the curve will be the one of the parent axes. The herited values are the ones related to lines, fill mode, marks and clipping.
However, there is no such inheritance for figure and axes objects. Their defaults values are actually stored in two others graphical objects. These objects are located in the InitObject.h file. They don't have any graphical representation (thus no drawer). They can be accessed from Scilab using the gdf and gda routines and from C code using getDefaultFigure and getDefaultAxes functions.
The default axes also contains its four labels, making the number of default objects to 6. Knowing if an object is a default one is sometime needed (for example to know if the handle should be rendered or not). The isFigureModel, isAxesModel and isModelObject are desgined for such need.
The default objects are created when the graphic module is loaded and destroy once it is released. Their properties can be modified as any other objects and it is highly recommanded to use the sciGet/sciSet functions to perform this. Some objects such as figures have some of their data stored in their Java counterpart (such as figure size), however default objects don't have any drawer. For default figures, the java properties are stored in the pModelData field of the sciFigure structure. This field is normally null for normal objects.
We are considering adding default objects for every Scilab objects. It's probably a good idea and would avoid to use the values inheritance which is not that obbvious. Howevzer, we should take care of user needs and be sure that default objects are not too complicated for users.
The getCurrentFigure, getCurrentAxes and getCurrentEntity functions are the equivalent of the gcf, gca and gce routines in Scilab. They are the entry points to the graphic hierachy. They always refers to the lastly created graphical objects. Consequenlty, each time a handle is created, destroyed or moved in the hierachy, the current entities must be modified. The functions used to set and get current objects are located in the currentObjectsManagement.h file.