Functions | |
void | Set_Metafile (const char *list) |
void | QSet_Metafile (const char *segment, const char *list) |
void | UnSet_Metafile (void) |
void | UnSet_One_Metafile (const char *which) |
void | QUnSet_Metafile (const char *segment) |
void | QUnSet_One_Metafile (const char *segment, const char *which) |
void Set_Metafile | ( | const char * | list | ) |
Defines a correspondence between a branch of the segment tree and a disk file.
list | - A quoted string or a string variable containing a list of the desired metafile attributes. |
Metafiles can be read and written manually with Read_Metafile() and Write_Metafile() . Or Set_Metafile() can be used to set up an automatic continuing relationship between a metafile and a segment. Set_Metafile() is also useful when you want to set up trees of metafiles---please see the "submetafile" discussion below.
List defines a list of details of how a metafile is to be used for a given segment. The list is of the form "specification, specification,...", where each specification may be "item" or "item = value", or "no item". Extra blanks and uppercase versus lowercase do not matter. You can specify as few or as many items in the list as you want; the items not mentioned remain unaffected.
The possible list items are as follows:
[no] read
When "read" is turned on, it indicates that it is appropriate to read the graphics information out of a disk file and into this segment.
[no] write
When "write" is turned on, it indicates that the complete contents of the segment should be written out to a disk file. Note that a segment's "contents" consist of the attributes, geometry, styles, includes, and subsegments, all the subsegments' attributes, geometry, styles, includes, and subsegments, and so forth.
If any part of the contents is subsequently changed and "write" is still in effect, the disk file will be updated. If "read" and "write" are turned on at the same time, the "read" will happen first, and a "write" will happen later if, and as, your program makes changes to the segment or its subsegments.
[no] name =`string'
Specifies a disk file name to use. If a file type is not included, ".hmf" is appended. If "name" is not specified at all, or if it is cancelled with "no name", HOOPS will pick a file name that's as close as possible, given the constraints of the operating system at hand, to the segment's name. In particular, if the segment name is 8 characters or fewer, and contains only letters and digits, HOOPS should be able to use it without change as the file name.
[no] directory =`string'
If "name" does not include an explicit directory specification, or if "name" is not specified at all, then "directory" specifies a disk directory to use, in the syntax of the local operating system. If "directory" is not specified, then the value of the environment variable "HOOPS_METAFILES" is used. If there is no such variable, the current directory is used.
[no] comment =`string'
When the metafile is written out, the "comment", if any has been set, will be included. When a metafile is read back in, the "comment" will be loaded and can be retrieved with Show_Metafile() . If the "string" has any special characters in it, you can enclose it in single (') or double (") quote marks.
[no] original name =`string'
A metafile is defined as the contents of a segment. The name of the "metafiled" segment, if it is of interest, is preserved in the "original name" field. When the metafile is written out, the "original name" will be set to the full pathname of the top-level segment. When a metafile is read back in, the "original name" will be loaded and can be retrieved with Show_Metafile() or Show_One_Metafile() .
[no] follow cross-references
When a "style" or "include" specification is encountered when writing a metafile, normally the name of the referenced segment, in another part of the segment tree, is written out. If "follow cross-references" is in effect, then the referenced segment(s) will also be written out too in their entirety (but at most once per metafile). If a number of metafiles all reference and describe the same style or include segment, only the first one read in will create the segment. Subsequent metafiles will skip ahead when they see that their referenced segment already exists.
[no] overwrite
HOOPS normally tries hard to avoid overwriting existing metafiles---it will create new version numbers, make variations on the file name, or in general do whatever it takes. If you specify "overwrite", you're telling the system that it has permission to trash any existing metafile of the same name.
[no] save state [=(option, option, ...)]
Metafiles normally record the contents of a segment and do not record "system-wide" information such as color name definitions. Turning on "save state" causes all the existing color names, defined textures, alias names, fonts, and open segment names to be dumped out to the metafile, along with the contents of the segment. If suboptions are specified, only those specified will be restored. Available suboptions are: "aliases", "color names", "fonts", "textures", and "open items". This option affects only the write operation. Note: This information will be read back in only if "restore state" has also been turned on (along with "read") by the receiving program.
A fairly complete system snapshot can be created by asking for "write, follow cross-references, use color names, save state" on "? Picture".
[no] restore state [=(option, option, ...)]
Turning on "restore state" causes all the existing color names, alias names, and open segment names to be read from the metafile, along with the contents of the segment. This option affects only the read operation. Note: This information will only be available in the metafile for reading if "save state" had also been turned on (along with "write") by the writing program.
[no] use color names
To be safe, the system normally writes out colors in terms of the raw color space coordinates. "Use color names" says that it's okay to use the names of the colors---"red", "light green", etc.---for writing out color attributes. Use "save state" to also write out all the color name definitions.
As mentioned earlier, the contents of a segment, as sent to a metafile, normally include all of the segment's inner segments. However, there is one special exception: a "metafiled" segment can have inner segments that also have metafile attributes. In that case, what the system creates on disk is a metafile that refers appropriately to the other metafiles.
The way the submetafiles work is that when the system is writing a metafile, and encounters a subsegment down in the tree that has a metafile attribute, it writes out the subsegment's name and the metafile details, then skips over the rest of that subsegment. When the system is reading a metafile and encounters a subsegment with the metafile attribute, it sets the attribute and the "read" ends up naturally recurring on itself.
The reading of a metafile occurs the instant you set the "read" option on. The writing of a new or changed metafile occurs at the next Update_Display(), Get_Selection(), Pause(), etc. The system will also check and rewrite the metafile, if necessary, at the moment you ask it to turn off or discard a "write" option.
If you want to pack a number of branches of the segment tree all into one metafile, one technique is to create a temporary segment, "include" all the segments you want into it, then turn on "follow cross-references" and tell the system to write the whole database out.
"Driver" and "Driver Options" attributes are never included by the system in a metafile.
If you're using a renumbered key (or the "User Value" attribute) to store a pointer to a chunk of memory, and you write that to a metafile, the pointer value probably isn't going to be useful when the metafile is read back in. A better technique is to convert the information pointed to into a string, and store the string as a "User Option".
I/O errors are reported back via the normal HOOPS error-handling mechanism.
The Metafile attribute itself can't be used as Style---it must be set explicitly on a segment.
void QSet_Metafile | ( | const char * | segment, | |
const char * | list | |||
) |
Similar to Set_Metafile(), but operates on a given segment rather than the currently open one.
segment | - Name of the segment(s) to be changed. | |
list | - A quoted string or a string variable containing a list of the desired metafile attributes. |
void UnSet_Metafile | ( | void | ) |
Removes all settings established by a previous call to Set_Metafile().
void UnSet_One_Metafile | ( | const char * | which | ) |
Removes a given setting established by a previous call to Set_Metafile(), rather than all settings.
which | - An individual Metafile option whose value is to be dis carded. |
void QUnSet_Metafile | ( | const char * | segment | ) |
Removes all settings established by a previous call Set_Metafile(), but operates on a given segment rather than the currently open one.
segment | - Name of the segment(s) to be changed. |
void QUnSet_One_Metafile | ( | const char * | segment, | |
const char * | which | |||
) |
Removes a given setting established by a previous call to Set_Metafile(), but operates on a given segment rather than the currently open one.
segment | - Name of the segment(s) to be changed. | |
which | - An individual Metafile option whose value is to be dis carded. |