[Contents] [TitleIndex] [WordIndex

Handle representation in Scilab

Printing handle in the console

Handle printing is done by the macro %h_p found in the %h_p.sci file.

Save / Load for handles

Saving / loading for handles is quite simple in Scilab and are located in the %h_save and %h_load macros. Saving is just a dumping of all properties inside a binary file. Loading read these values to recreate handles. The major drawback of this technique is that data must be writen by save and read by load in the exact same order. Moreover, keeping backward compatibility is really tedious.

The current Scilab version is writen in the saved file. When loading we use the is_higher_than macro which check if the loading version is strictly newer than the one which wrote the file. This is really tedious since there are more and more tests using is_higher_than is the code. One test is normally added each time a graphic property is added.

The current version is not taken from Scilab, but actuallyy define in the %h_save.sci file. This is the version vectors define with 4 values [major minor update wtf] which should be updated at least each time a new Scilab version is released. For example when Scilab 5.1.5 version is released the verion vector must be [5 1 5 0]. All new properties added between Scilab 5.1.4 and 5.1.5 must be loaded by testing is_higher_than([5 1 4 0]).

Handle storage in the stack

Handles are represented by a long int in the Scilab stack. To retrieve this long int it's first needed to get the stack pointer of the value. The stack pointer is obtained by using the GetRhsVar and CreateVar with the GRAPHICAL_HANDLE_DATATYPE type. Once the stack pointer has been retrieved, the long value is obtained by using the hstk function with the stack pointer.

Convertion from handles to sciPointObj

Although handles are stored as long in the stack there is much more informations inside. This information is stored for every handle in the sciPointObj structure. To get this sciPointObj structure from the long, the sciGetPointerFromHandle function is used. The mapping is done using a hashMap.

To retrieve a handle value from a sciPointObj, the sciGetHandle function is used.

The sciPointObj structure

The objects properties are stored in a C strutrure called sciPointObj found in the ObjectStructure.h file. This structure contains the data common to all graphical objects are stored plus an opaque pointer. Among the common data, we can find the kind of handle (Figure, polylines, uicontrol,...), its relationship (parent, chidren, see The Graphic Hierarchy) and the object renderer (see Handle Rendering for more details).

The opaque pointer, called pfeatures points on the object specific data. It is actually a pointer on one of the sci*** stucrures found in the file. For example, if the object is a figure, it's opaque pointer points on a sciFigure instance. To easily access the structure, use the p***_FEATURES macros which cast the pfeatures to the right type. However, creation, destruction and access to graphical objects properties should be done (if possible) using the dedicated functions (see Creation/Destruction of handles and Modifying handle properties).

When having a sciPointObj, to know its kind and how to access its inner data, its entity type must be used. The entity type is located in the SciPointObj structure and is accessed using sciGetEntityType function. The entity type is an enum sciEntityType containing all the handle types (SCI_FIGURE, SCI_POLYLINE, ...).

Here is the correspondance between entity type and Scilab handle name:

Scilab handle type

C entity type

Type of pfeatures

Figure

SCI_FIGURE

sciFigure

Axes

SCI_SUBWIN

sciSubWindow

Text

SCI_TEXT

sciText

Legend

SCI_LEGEND

sciLegend

Arc

SCI_ARC

sciArc

Polyline

SCI_POLYLINE

sciPolyline

Segs

SCI_SEGS

sciSegs

Champ

SCI_SEGS

sciSegs

Grayplot

SCI_GRAYPLOT

sciGrayplot

Matplot

SCI_GRAYPLOT

sciGrayplot

Rectangle

SCI_RECTANGLE

sciRectangle

Plot3d

SCI_SURFACE

sciSurface

Fac3d

SCI_SURFACE

sciSurface

Axis

SCI_AXES

sciAxes

Compound

SCI_AGREG

sciAgreg

Label

SCI_LABEL

sciLabel

uicontrol

SCI_UICONTROL

sciUicontrol

uimenu

SCI_UIMENU

sciUimenu

Waitbar

SCI_WAITBAR

sciWaitbar

Progressionbar

SCi_PREGRESSIONBAR

sciProgressionbar


2022-09-08 09:27