Functions and Directives

Function GraSegSave() Foundation

Save a graphic segment to disk

Syntax
GraSegSave( [oPS],  <cFileName>, <nSegId>   ) --> <lSuccess>
GraSegSave( [oPS], @<aSegBuf>,  [<aSegIds>] ) --> <lSuccess>
Parameters
<oPS>
The argument <oPS> specifies the presentation space the graphic segment is defined in. 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 save the segment into. Parameter <nSegId> must be used when a graphic segment is to be saved to a file.
<nSegId>
The parameter <nSegId> is a numeric value which identifies the segment to be saved to a file. Each graphic segment receives a numeric code as the return value of the function GraSegOpen(). This value is used for <nSegId>.
@<aSegBuf>
If an array is passed in parameter <aSegBuf>, GraSegSave() assigns the segment buffer of each segment to an element of the array. Each segment buffer is returned as a character string and can later be used to reload the graphic segment using the function GraSegLoad(). If parameter <aSegBuf>is used, segments are saved to memory instead of to a file. Parameter <aSegBuf> must be passed by reference and cannot be used along with <nSegId>.
@[<aSegIds>]
If parameter <aSegBuf> is used, an array can be passed in <aSegIds>. Each array element contains the numeric identifier of a segment to save. If several graphic segments are defined in a presentation space using function GraSegOpen(), parameter <aSegIds> may be used to save only a subset of the segments. Parameter <aSegIds> is optional. If it is NIL, all graphic segments defined in the presentation space are saved.
Return

The function returns the logical value .T. (true) if the segment is saved. Otherwise, .F. (false) is returned.

Description

Function GraSegSave() saves graphic segments, so they can later be reloaded using GraSegLoad() function. GraSegSave() can be operated in two modes; in single segment-mode, the graphic segment specified in <nSegId> is saved to a file. In this mode, only one segment can be saved at a time. If used in array mode, any number of segments can be saved to memory with GraSegSave(). In this mode, a buffer with segment data is returned in parameter <aSegBuf> for each segment saved. In the array mode, the application has full control over the way in which graphic segments are stored. Segments may be kept in memory or saved to disk using the file API. See the function FOpen() for further information.

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 need be.

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.