Appendix D from Diagram! 2 documentation

File Format

Why A Text File Format?

Some examples

Document Creation

Document Contents

Textual Specification

Printer Information

Color File

Object Link Information

Sounds

Images

Textual Specification Structure

Comments

Header

Document Parameters

Symbols

Vertices

Lines

Groups


Statement Summary

Statement Details

This section is arranged in alphabetical order by statement name and provides a detailed description of each statement.

attachment

"attachedFileName"

specifies that the symbol has an attachment to attachedFileName. The quotation marks are required. attachedFileName must be an absolute path.Diagram! does not generate files using attachment. It is provided to make attachment creation possible when creating documents by hand.

Valid in Sections: Symbol.

See also: linkedFile

canvasSize

canvasWidth canvasHeight

sets the size of the document canvas to be canvasWidth pages wide and canvasHeight pages tall. canvasWidth and canvasHeight must be positive integers.

Valid in Sections: Document.

colorFile

"colorFileName"

colorFileName is the name of the file within the document wrapper that contains the colors used in the document. It is necessary to specify a color file if you are specifying colors using the colorIndex operator. The quotation marks surrounding the colorFileName are required.

Valid in Sections: Document

See also: colorIndex.

colorIndex

index

specifies the color which is at the index position in the document's color file. index must be a positive integer which is a valid index in the color file specified with the colorFile statement.

This is Diagram! 2's default method for storing colors.

Valid in Sections: Symbol, Line

See also: colorFile, gray, rgbColor.

curved

indicates that a line should be curved.

Valid in Sections: Line.

default

indicates that this entity will be drawn when using the Line mode or Symbol mode.

Valid in Sections: Symbol, Line.

See also: defaultFont, defaultFontSize.

defaultFont

"fontName"

specifies that text created in Text mode should be displayed in the fontName font. The quotation marks are required.

Valid in Sections: Document

See also: defaultFontSize

defaultFontSize

fontSize

specifies the default size of text created in Text mode. fontSize must be a positive value. Floating-point and integer values are both valid.

Valid in Sections: Document

See also: defaultFont

fillColor

colorSpecification

sets the color which will be used to fill the interior of a symbol or the label of a line. colorSpecification is a color specified by using colorIndex, gray, or rgbColor. In a line, fillColor is the background color for the line's label.

Valid in Sections: Symbol, Line.

See also: filled.

filled

indicates that the entity is filled with the color specified by the fillColor operator. In a line, filled indicates that there is a background color for its label.

Valid in Sections: Symbol, Line.

See also: fillColor.

flippedHorizontally

indicates that the entity is flipped across its horizontal axis.

Valid in Sections: Symbol, Group.

See also: flippedVertically.

flippedVertically

indicates that the entity is flipped across its vertical axis.

Valid in Sections: Symbol, Group.

See also: flippedHorizontally.

frameColor

colorSpecification

sets the color which will be used to draw the frame of an entity. colorSpecification is a color specified by using colorIndex, gray, or rgbColor. In a line, frameColor is the color of the line.

Valid in Sections: Symbol, Line

See also: framed.

framed

indicates that the entity is drawn with a frame outlining its boundaries. The color of the frame is specified with the frameColor operator.

Valid in Sections: Symbol

See also: frameColor.

from

entityNumber

specifies the entity at the tail-end of a line. entityNumber is the positive integer specified when the entity was defined.

Valid in Sections: Line.

See also: to.

gray

grayValue

specifies a gray color. grayValue must be a floating-point value between zero and one, where zero represents black and one represents white.

Diagram! 2 does not create documents using gray. It is provided to make color selection easier when creating documents by hand.

Valid in Sections: Symbol, Line.

See also: colorIndex, gray, rgbColor.

gridVisible

specifies that the grid should be displayed.

Valid in Sections: Document

See also: gridSize.

gridSize

gridSpacing

specifies the size of a square of the grid. gridSpacing is a positive value in points.

Valid in Sections: Document

See also: grid.

headType

lineEndType

describes the type of line end which will appear at the terminating point of the line. lineEndType can be one of:

* arrow

* circle

* doubleArrow

* hollowArrow

* solidCircle

Valid in Sections: Line.

See also: tailType.

imageFile

"imageFileName"

specifies that the entity is associated with an image. imageFileName must be the name of an imageable file or archived NXImage object in the document wrapper. Quotation marks around the imageFileName are required.

When imageFile is used in a Symbol, the image appears within the bounds of the Symbol and is cropped to the Symbol's shape.

When Diagram! saves a document which used the imageFile statement, the image is stored as an archived NXImage object with the name "ImageXX". The "XX" in the file name is the entity number of the Symbol where the imageFile statement appears. At this point, the originally specified image file is never referenced.

For example, suppose your document has a symbol which has an entity number of 10 and uses the statement:

imageFile "nextlogin.tiff"

When the document is saved, the image information will be archived to the file "Image1". Any further changes you make to the file "nextlogin.tiff" will not be reflected in your Diagram! document since Diagram! is displaying the image data in the file "Image1"

A symbol can specify only one of imageFile or linkedImage to display an image within its bounds.

Valid in Sections: Symbol

See also: linkedImage.

labelOffset

offset

offset is a floating-point value between -50.0 and 50.0 which determines the distance away from a line its label will appear. offset is in points and a value of 0.0 will center the label on the line.

For example, if labelOffset appeared in a horizontal line, an offset of 5 would move the label above the line by 5 points.

Valid in Sections: Line.

See also: labelPosition.

labelPosition

position

position is a floating-point value between 0.0 and 1.0 which determines where a label will appear along its line. For example, a position of 0.5 would place the label at the midpoint of the line.

Valid in Sections: Line.

See also: labelOffset.

labelWidth

width

width is a positive, floating-point value, representing the width of a line's label in points. The height of the label is computed based on this width.

Valid in Sections: Line.

lineType

type

sets the type of line that will be drawn. In Symbols, this sets the type of line that will be drawn for the symbol frame. If no lineType is specified, the line will be drawn solid. Valid values for type are:

* dot

* dash

* dotDash

Valid in Sections: Symbol, Line.

layer

layerNumber

specifies the front-to-back ordering of entities. If no layer information is provided, the default is to place all symbols on the canvas, then vertices, lines, and finally groups.

When Diagram! writes documents, each entity is assigned a layerNumber.

Valid in Sections: Symbol, Vertex, Line, Group.

linkedFile

specifies that the entity has an attachment to a file.

Valid in Sections: Symbol

See also: linkedImage.

linkedImage

specifies that the entity is using an object link for its image data. Unlike an image specified with imageFile, no name is provided for the image data; the location of the image data is managed by the NXDataLinkManager.

A symbol can specify only one of imageFile or linkedImage to display an image within its bounds.

Valid in Sections: Symbol

See also: imageFile.

location

x y

x and y are floating-point numbers which represent the upper-left corner of an entity in points.

Valid in Sections: Symbol, Vertex, Group.

See also: size.

locked

specifies that an entity can no longer be moved on the canvas.

Valid in Sections: Symbol, Line, Group, Vertex.

originalSize

originalWidth originalHeight

specifies the original size of the entity to be originalWidth points wide and originalHeight points tall. originalWidth and originalHeight are positive, floating-point numbers.

The original size of a symbol is only meaningful when the symbol has an image. The original size is the size of the image when the image was added to the symbol.

Valid in Sections: Symbol.

See also: location, size.

palette

indicates that a document is a palette. The presence of palette is the only difference between ".diagram2" and ".dpalette2" documents.

Valid in Sections: Document

printInfoFile

"printInfoFileName"

printInfoFileName is the file name of the archived PrintInfo object in the document wrapper. The quotations around the file name are required. You can create documents without specifying a printInfoFile.

Valid in Sections: Document

rgbColor

red green blue

specifies a color by combining the red, green, and blue components. The components must be floating-point values between 0 and 1 inclusive.

Diagram! 2 will not create documents using rgbColor. It is provided to make color selection easier when creating documents by hand.

Valid in Sections: Symbol, Line.

See also: colorIndex, gray, rgbColor.

rotationAngle

angle

sets the angle of rotation of the entity to angle degrees. angle should be a number in the range of 0 to 359.99. Integer and floating-point values are accepted for angle.

Valid in Sections: Symbol, Group.

rtfText

rtf-string

sets the text of the entity to the specified RTF text. No quotation marks surround the RTF. All font, ruler and special character information is preserved.

Valid in Sections: Symbol, Line

See also: text.

shadowColor

color-specification

specifies the color used to draw the shadow of an entity. colorSpecification is a color specified by using colorIndex, gray, or rgbColor.

Valid in Sections: Symbol

See also: shadowed

shadowed

indicates that a shadow is drawn using the color specified with the shadowColor operator.

Valid in Sections: Symbol

See also: shadowColor.

shape

"shapeName"

specifies the shape of the entity. The quotation marks are required and the shapeName must be the name of one of the available shapes. If shapeName is not recognized, a Rectangle will be used.

Possible values for shapeName are:

* Circle

* Cylinder

* Diamond

* Hexagon

* Horizontal Arrow

* Horizontal Triangle

* Parallel Lines

* Parallelogram

* Rectangle

* Rounded Rectangle

* Vertical Arrow

* Vertical Triangle

Valid in Sections: Symbol

showRulers

indicates that rulers will be visible when the document is loaded.

Valid in Sections: Document

See also: showTools.

showTools

indicates that a button ribbon will be displayed when the document is loaded.

Valid in Sections: Document

See also: showRulers.

size

width height

specifies the size of the entity to be width points wide and height points tall. width and height are positive, floating-point numbers.

Valid in Sections: Symbol, Group.

See also: location, originalSize.

snapToGrid

indicates that the grid snap should be on.

Valid in Sections: Document.

See also: gridVisible, gridSize.

soundFile

"soundFileName"

specifies that the entity has an attached sound. The quotation marks around soundFileName are required. soundFileName should be the name of a sound file in the document wrapper.

When Diagram! saves a document which used the soundFile statement, the sound is stored as a sound file with the name "SoundXX.snd". The "XX" in the file name is the entity number of the Symbol where the soundFile statement appears. At this point, the originally specified sound file is never referenced.

For example, suppose your document has a symbol which has an entity number of 10 and uses the statement:

soundFile "Bonk.snd"

When the document is saved, the sound information will be saved to the file "Sound10.snd". Any further changes you make to the file "Bonk.snd" will not be reflected in your Diagram! document since Diagram! will play the sound data in the file "Sound10.snd"

Valid in Sections: Symbol.

tailType lineEndType

describes the type of line end which will appear at the originating point of the line. See the description of headType above for a list of valid values for line-end-type.

Valid in Sections: Line.

See also: headType.

text

"string"

sets the text of the entity to string. The quotations surrounding string are required. Only normal text characters can be entered this way. If any special characters or fonts are required, rtfText should be used. Quotation marks may be inserted into the string by escaping them with a backslash(\) character. For example, 'text "\"quoted string\""' would specify that double quotes should surround the text, "quoted string" in the symbol.

Documents saved by Diagram! will never use text. It is provided as a convenience operator to users creating their own documents.

Valid in Sections: Symbol, Line

See also: rtfText.

textPlacement

place

specifies where text should appear in an entity. Possible values of place are:

top

middle

bottom

Valid in Sections: Symbol.

to

entityNumber

used to specify the entity at the termination point of a line. The entityNumber is the integer specified when the entity was defined.

Valid in Sections: Line.

See also: from.

viewOrigin

viewX viewY

specifies the location of the canvas within the window. viewX and viewY are specified in points.

Valid in Sections: Document

viewSize

viewWidth viewHeight

specifies the size of the view in the document window. viewWidth and viewHeight are positive, floating-point numbers.

Valid in Sections: Document

visibleOrigin

visibleX visibleY

specifies the origin of the visible region of the document. When the canvas is larger than the window, only a portion is visible on the screen. This operator sets the origin of that visible space. visibleX and visibleY are positive, floating-point values.

Valid in Sections: Document

windowOrigin

windowX windowY

windowX and windowY are positive, floating-point values which specify the location of the window.

Valid in Sections: Document

zoom

zoomPercentage

zoomPercentage is a floating-point value. If the zoom operator is not present, a zoom value of 100% is used. zoomPercentage should be a number in the range 0.10 to 16.

Valid in Sections: Document

Examples

The Smallest Document

The smallest, valid Diagram! document is a one-page canvas with no entities on it. To create such a document (named "tiny.diagram2"):

1. make a folder called "tiny.diagram2".

2. inside the new folder, create a file called "DiagramText" with the text, "#!DG_TEXT"

The Prairie Chicken

This example contains three symbols, one line and one group. It's not very aesthetic, but demonstrates many of the features of the file format:

#!DG_TEXT
#
# Document Section
#
showTools                       # display the Button Ribbon
gridVisible                     # display a grid with the default 9-pt size
#
# Symbol Section
#
# This first symbol will not display on the canvas. However, if you use 
# Symbol mode, a Vertical Triangle with a purple shadow will be created.
symbol 1
default                 	# this will be the
				# symbol drawn when in
				# symbol mode.
size 20 100
shape "Vertical Triangle"
filled				# fill with white
framed				# frame with black
shadowed			# turn on the shadow
shadowColor rgbColor 1 0 1	# use purple for shadow
end
			
symbol 2
size 100 100
	location 50 100
text "Mickey \"Steamboat Willie\" Mouse"	
# note the use of the backslash to insert quotation marks
fillColor gray 0.333		# set a light gray
filled				# turn on the fill
textPlacement middle		# center the text in the symbol
end

symbol 3
shape "Diamond"	
size 300 300
location 150 250
rotationAngle 15
attachment "/tmp/console.log"		# create a link
text "Click the link marker to view the system console"
framed
fillColor rgbColor 0 1 1	# set the fill color to cyan.
filled
textPlacement bottom		# place the text at the bottom of the symbol
end
			
# For the full effect, issue the following commands in this directory before
# opening this document:
# ln -s /NextLibrary/References/Webster-Dictionary/pictures/prairiechicken.tiff
# ln -s /NextLibrary/Sounds/Rooster.snd
symbol 7
shape "Circle" # the size will be derived from the size of the image
location 280 15
imageFile "prairiechicken.tiff"
soundFile "Rooster.snd"
framed
shadowed
end
			
#
# Vertex Section
#

vertex 4
end
			
vertex 5
end
			
#
# Line Section
#
			
line 6
from 2 to 3			# the objects at the ends of the line
4 5				# the vertices the line passes through
headType arrow
text "Console"	# line label
labelPosition 0.25
end
				
#
# Group Section
#

group 8 
2 3				# size and location will be determined
    				# by the size of objects 2 and 3
end

Syntax Summary This section describes the formal grammar for the Diagram!2 file format. It is intended for readers familiar with formal language specifications.

Document:
DocumentSettings Symbols Vertices Lines Groups
DocumentSettings:
DocumentSetting:
CanvasSizeStatement:
ColorFileStatement:
DefaultFontStatement:
DefaultFontSizeStatement:
GridSizeStatement:
PrintinfoFileStatement:
ViewOriginStatement:
ViewSizeStatement:
VisibleOriginStatement:
WindowOriginStatement:
ZoomStatement:
Symbols:
Symbol:
SymbolAttributes:
SymbolAttribute:
AttachmentStatement:
FillColorStatement:
FrameColorStatement:
ImageFileStatement:
LayerStatement:
LineTypeStatement:
LineType:
LineWidthStatement:
LocationStatement:
OriginalSize
RotationAngleStatement:
RtfTextStatement:
ShadowColorStatement:
ShapeStatement:
SizeStatement:
SoundFileStatement:
SymbolStyleStatement:
TextPlacementStatement:
TextPosition:
TextStatement:
ColorSpecification:
Vertices:
VertexAttributes:
VertexAttribute:
Vertex:
Lines:
Line:
LineAttributes:
LineAttribute:
FromStatement:
HeadTypeStatement:
LabelOffsetStatement:
LabelPositionStatement:
LabelWidthStatement:
TailTypeStatement:
ToStatement:
UniqueIdStatement:
Groups:
Group:
GroupAttributes:
GroupAttribute:
RtfGroup:
RtfSource:
RtfSourceAtom:
RtfString:
RtfStringAtom:
Number:
Integer:
Float:
QuotedString:
Comment: