[Contents] [TitleIndex] [WordIndex

Handle creation and destruction

Handle creation

Every handle creation is done inside the BuildObjects.c file. To create a new handle only a call to one af the Construct*** functions is requested. There is one function for each kind of functions. These functions allocate the handle, put it in the hierachy and set its default values. Normally, its needed to specify the handle parent and some of its values.

If some additional properties need to be set just use the set/get functions (see Modifying handle properties).

There are examples of handle construction inside the sciCall.c file.

The BuildObjects.c file contains some other useful functions. Actually, the createFullFigure should be used rather than createFigure to create a new figure. createFullFigure creates the figure handle but also the needed axes and show the window on the screen.

Note that the handle drawer is not created in the construction functions but only when needed.

The ConstructCompoundSeq might be used instead of ConstructCompound in some cases (it avoids creating the handle array).

The allocateText and allocatePolyline should be used with caution. There were created to be able to create handles which are not added in the hierarchy. This allows to manipulate graphic objects which are not actually seen by the user. This is for example used for the Legend object which needs to display some little lines (polylines) and text (text objects) and been enclosed by a rectangle (polyline object). Instead of creating new OpenGL routines to display the legend, it is actually made of several graphical objects and the user can only manipulate them as a whole.

Handle destruction

Handle destruction is located inside the DestroyObjects.c file. Destroying a handle is pretty easy, it's only required to called the sciDelGraphicObj on the object. This function first destroy all the sons of the object and then object itself using one of the Destroy*** functions.

When a handle is destroyed, it is removed from the hierachy and all its allocated data are freed (including its drawer).

The DestroyObjects.c contains also some other useful functions.

sciUnCompound is used instead of DestroyCompound to avoid destruction of a compound's children. The compound object is destroyed but its children are relocated below the compound parent.

The deallocatePolyline and deallocateText functions must be only used to destroy objects allocated with allocatePolyline and allocateText.

Examples of handle destruction can be found in the sci_delete function.

2022-09-08 09:26