Functions and Directives Functions and Directives

Function GraSegLoad() Foundation

Load a graphic segment from disk

Syntax
GraSegLoad( [oPS], <cFileName>, [<nMode>] ) --> nSegId
GraSegLoad( [oPS], <aSegBuf>,   [<nMode>] ) --> aSegIds
Parameters
<oPS>
The argument <oPS> specifies the presentation space the graphic segment is loaded into. If the current window is an XbpCrt window, <oPS> is optional. If it is NIL, the return value of SetAppWindow():presSpace() is used. In all other cases <oPS> is not optional. It must be created using XbpPresSpace():create(). A "Micro PS" cannot be used for this function.
<cFileName>
<cFileName> is a character string with the name of the file to load the segment from.
<aSegBuf>
An array of segment buffers as returned by function GraSegSave() must be passed in the parameter <aSegBuf>. Each element in the array contains a buffer with data sufficient to load/initialize a segment.
<nMode>
The parameter <nMode> specifies one of the two #define constants GRA_SEG_MODIFIABLE or GRA_SEG_NIL. The default value is GRA_SEG_MODIFIABLE, which indicates that a segment can later be changed. If GRA_SEG_NIL is specified, the segment cannot be changed and it is also not registered for the function GraSegFind(). A segment receives the segment ID 0 in the mode GRA_SEG_NIL and can only be displayed when no segment ID is specified to GraSegDraw().
Return

If an individual segment is loaded using GraSegLoad(), the function returns a numeric value by which the graphic segment is later identified. If an array is passed in parameter <aSegBuf>, return is an array of the same size as <aSegBuf>. Each element of the return array contains the identifier of the corresponding graphical segment. If the constant GRA_SEG_NIL is used for <nMode>, the value 0 is returned for each segment loaded.

Description

The function GraSegLoad() loads graphic segments from disk. The function can be operated in two modes. In single segment-mode, the file to load the graphic segment from is specified in parameter <cFileName>. In this mode, only one graphic segment can be loaded at a time. If used in array mode, GraSegLoad() can be used to load several segments simultaneously. For that, an array with segment data must be passed in parameter <aSegBuf>. In this mode, the segments are loaded from memory instead of from a file, allowing the application to take full control over the way graphic segments are stored.

Saving graphic segments is accomplished by using the function GraSegSave(). Saving and loading allows the reuse of existing segments without having to reexecute the graphical primitives which define the image. In a print preview application, for example, this mechanism can be used to save the segments which contain the pages already prepared, and to reload them later as needed.

Feedback

If you see anything in the documentation that is not correct, does not match your experience with the particular feature or requires further clarification, please use this form to report a documentation issue.