PrevCurrent Data File Format  Next

Name

attachment — An arbitrary file attachment

Synopsis

Content Model 
attachment ::= (#PCDATA,
                tag*,
                (container|textdata|script|attachment|
                 tri|link|snappeadata|
                 angles|surfaces|hypersurfaces|
                 filtercomb|filterprop|filtertrivial|
                 anon|anonref)*)
Attributes
NameType
encodingCDATA (required)
filenameCDATA (required)
idCDATA
labelCDATA

Added in Regina 7.0

Description

This represents an attachment packet, one of the many types of packet that together form the packet tree that a user sees when they open a Regina data file.

An attachment packet stores a single file attachment. The contents of the attachment are encoded in a printable format, using the encoding specified by the encoding attribute (see below). The encoded data is contained in the character data that appears before the first child XML element.

Whitespace and line breaks within the encoded data are not relevant, and can be ignored.

In Regina 6.0.1 and earlier, only PDF documents could be stored as file attachments (and this packet type was called a PDF packet instead). Since Regina 7.0, any type of file attachment can be stored.

There are several child XML elements that are common to all packet types. The tag elements represent an arbitrary set of string “tags” that users can attach to a packet to help organise their data. The remaining child elements list all of Regina's packet types (container, textdata, etc.), and these represent the immediate children of this packet in the packet tree.

Parents

The following elements can contain any packet element (including this): angles, anon, anonref, attachment, container, filtercomb, filterprop, filtertrivial, hypersurfaces, link, regina, script, snappeadata, surfaces, textdata, tri. This list includes all packet types, as well as the top-level element regina.

Children

Element attachment has no children that are specific to attachment packets.

The following children can occur in all packet elements: angles, anon, anonref, attachment, container, filtercomb, filterprop, filtertrivial, hypersurfaces, link, script, snappeadata, surfaces, tag, textdata, tri. This list includes all packet types, as well as the tag element for tagging individual packets.

Attributes

The following attributes are specific to attachment packets:

encoding

Specifies how the contents of the file attachment are encoded in printable format. Possible values are base64 (indicating a base64 encoding with printable character set A-Za-z0-9+/), or null (indicating that the attachment is empty, i.e., a zero-byte file).

filename

The filename associated with this attachment. Typically this would be a filename only, with no directory prefixes.

User interfaces should use this filename to deduce the file type, and in particular to choose an appropriate external viewer if required.

This filename should be treated as a hint only. User interfaces are not required to use it, and indeed they will have to change it if the filename is empty or invalid for the current platform.

The following attributes are common to all packet types:

id

A unique identifier for this packet. Packets are not required to have IDs, but when they are present they must be distinct (i.e., no packets in the same file may share the same ID). IDs do not need to be human-readable, must not contain leading or trailing whitespace, and must not be empty strings. Currently, IDs are built from base 64 hashes of the underlying C++ pointers.

The purpose of these packet IDs is to allow other packets to reference this packet (for instance, so that a script packet can store references to its variables).

IDs are not required to stay the same across subsequent loads and saves of the same file. In other words, if you load a file and save it again, the packet IDs are allowed to change.

label

The name given by the user to this particular packet within the overall packet tree.

PrevContentsNext
anonref Up code