Frequently Asked Questions Frequently Asked QuestionsQ:
What is the Diagram file format?A:
From Appendix D, in the manual:This appendix describes the format of ".diagram2" and ".dpalette2" documents. It is intended for developers and power users.
Developers will find this appendix useful for creating programs which read and process information from a Diagram! document, or for creating new Diagram! documents from existing information.
Power users may find it interesting to know how they may edit their documents via tools such as Edit, the Workspace and the Color Panel--without using Diagram!
Many of you asked us how to read Diagram! files. You wanted to be able to read the information contained in a Diagram! drawing and pass that data to other programs. Similarly, you wanted to be able to create Diagram! drawings from data from other programs. We've listened to your requests and provided a small language which should make document creation and reading much simpler.
By using the information supplied below as well as the UNIX tools lex and yacc, you can create your own program which reads Diagram! documents and takes actions based on the contents.
Some examples
Often it is easiest to display some data as drawings. With the new text file format, you can write scripts or applications to display data as a Diagram! document.
Examples
All Diagram! 2 documents have the extension ".diagram2" or ".dpalette2". Both drawing and palette documents have the same structure.
Diagram! 2 documents are document wrappers-directories that contain files which together comprise the document. To see the component files of a Diagram! 2 document, select it in a Workspace file viewer and choose the Open as Folder command from the Workspace Manager's File menu.
Each wrapper can contain a number of files: a textual specification, printer information, color file, object link information, and any number of sound and image files. The only file which must be in the document wrapper is the textual specification.
Please note that when Diagram! opens and saves a document which you've created by hand, the document contents will have changed. When you save over a hand-generated document, Diagram! writes its textual specification in standard Diagram! format- your comments in the textual specification will be lost, colors will be placed in a color table, and images and sounds will be written in standardized file names.
The required text file, "DiagramText" describes the document. The size and shapes of symbols, and locations of vertices and lines are described textually. The textual specification is described in detail below.
Elements such as page size, color, sounds, images and object links do not lend themselves to textual descriptions and are stored in separate files in the document wrapper.
Diagram! stores information about your page size and canvas size in a subclass of NeXT's PrintInfo object. This object is archived to a file called "PrintInfo" in the document wrapper.
Diagram! stores the colors used in a given document in a file called "Colors.clr." This file is an archived NXColorList object.
This file can also be opened by using the Colors panel of any application. Power users may wish to substitute alternate color files for their documents to globally change the look of their document.
To modify the color list of your document follow these steps:
1. Bring up the Colors panel of any application.
2. Click the PANTONE button to select the custom color list view.
3. Select Open from the List pop-up menu.
4. Select the path to your document.
You will not see the document name in the Open panel.
5. Once you have selected the correct folder, you must type the name of your document and press OK.
You should now see the file "Colors.clr" listed in the Open panel. Select it and click the OK button.
All the colors used in your document are now displayed in the Colors panel. You can now use the Color pop-up list to add, remove and rename colors in the list. The names of the colors are very important. When you add a new color, you should change the name of the color to the name of the color you wish to replace. You should never delete a color without providing a replacement. Doing so will make your document unreadable.
After your modifications are complete, you must copy the new color list into your document. When you edit a color list in the Colors panel, the color list is copied into a Colors folder in your Library folder. Use the Workspace Manager to copy the Colors.clr file from your Library/Colors folder into your document.
The file "NXLinkData.linkdb" will exist when a Diagram! document has object links in the form of either an attachment or linked image. This file is managed by the NXDataLinkManager object and should not be modified or removed.
Sounds are stored in standard NeXT sound file format. The sounds attached to your document can be played by the Workspace Manager and manipulated just like any other ".snd" file.
Image files within the document wrapper will be in one of two formats. Currently, Diagram! allows you to add images to documents by including any imageable document type in a Diagram! document. However, when Diagram! saves the document, it will save the image data as an archived NXImage object.
The following conventions are used in this specification:
There are six distinct sections to the DiagramText file format. Any section may be omitted except the Header Section. The sections must appear in the following order:
1. Header
2. Document Parameters
3. Symbols
4. Vertices
5. Lines
6. Groups
Comments can exist anywhere in a document. Comments are started with a # character, which may occur anywhere on a line, and run until the end of line. The header line described above is also a comment.
The first line of a Diagram! document must contain these characters:
#!DG_TEXT
This line can also contain version information in the following format:
#!DG_TEXT-Version -versionNumber
When documents are saved by Diagram! 2, versionNumber is "2".
The document parameters section sets attributes for the entire document. The canvas size, window size, zoom, color file, printInfo file, grid, ruler, and tools are specified here.
See the Statement Summary section below for descriptions of statements which are valid in this section.
The symbols section contains the definition of each symbol appearing in the document.
Each symbol definition has this form:
symbol entityNumber statements end
entityNumber is an integer which must be unique across all entities in the document. This integer is used to refer to entities within the document. In particular, lines and groups use this number to refer to entities they use.
The statements of a symbol definition specify its attributes, style, position and layer.
Example:
The symbol defined below is a circle with a radius of 50 points which will have an outline and a shadow. The outline and shadow will appear in the default colors. See the Statement Summary section below for descriptions of each statement.
symbol 3
shape "Circle"
location 100 100
size 100 100
framed
shadowed
end
The vertices section contains the definition of each vertex appearing in the document.
Each vertex definition has this form:
vertex entityNumber statements end
See the Symbols section above for a description of entityNumber.
The statements of a vertex definition specify its location and layer. The statements of a vertex can also be empty when the vertex is being used in a line which is attached at both ends to an entity.
Examples:
This vertex has an empty statements section. See the Lines description below for more information about empty vertices.
vertex 4
end
This is a vertex which is 150 points from the left and top margins. See the Statement Summary section below for descriptions of the "location" statement.
vertex 5
location 150 150
end
The lines section contains the definitions for all lines appearing in the document.
Each line definition has this form:
line entityNumber statements end
See the Symbols section above for a description of entityNumber.
The of a line definition specify its start and end points, style attributes, layer, label, and position of the label.
Example:
This example describes the drawing pictured in this figure:
Notice that the line definition specifies that the line starts at symbol 5 and ends at symbol 6. The line also passes through vertices 7, 8, and 9.
At least two vertices are required for each line. A line's first and last vertices are assumed to be connected to the objects specified in the from and to statements and are allowed to be empty.
See the Statement Summary section below for descriptions of each statement.
#!DG_TEXT
symbol 5
framed
location 100 100
size 100 50
end
symbol 6
shape "Rounded Rectangle"
framed
location 100 300
size 100 50
end
vertex 7
end
vertex 8
location 200 200
end
vertex 9
end
line 10
from 5
to 6
# list all vertices the line passes through
7
8
9
end
The groups section contains the definitions for all groups appearing in the document.
Each group definition has this form:
group entityNumber statements end
See the Symbols section above for a description of entityNumber.
The statements of a group definition specify its position, layer, and its components entityNumber's.
Example:
To group all elements from the line example above you could create the following group:
group 11
5 6 7 8 9 10
end
This statement summary provides a reference for statements. The statements are divided into categories:
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:
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:
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:
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
This section describes the formal grammar for the Diagram!2 file format. It is intended for readers familiar with formal language specifications.
DocumentSettings DocumentSetting
ColorFileStatement
DefaultFontStatement
DefaultFontSizeStatement
GridSizeStatement
PrintinfoFileStatement
ViewOriginStatement
ViewSizeStatement
VisibleOriginStatement
WindowOriginStatement
ZoomStatement
gridVisible
palette
showRulers
showTools
snapToGrid
Symbol
Symbols Symbol
SymbolAttributes SymbolAttribute
FillColorStatement
FrameColorStatement
ImageFileStatement
LayerStatement
LineTypeStatement
LineWidthStatement
LocationStatement
OriginalSizeStatement
RotationAngleStatement
RtfTextStatement
ShadowColorStatement
ShapeStatement
SizeStatement
SoundFileStatement
SymbolStyleStatement
TextPlacementStatement
TextStatement
default
flippedHorizontally
flippedVertically
linkedFile
linkedImage
locked
dot
dotDash
framed
shadowed
middle
top
gray Float
rgbColor Number Number Number
Vertex
Vertices Vertex
VertexAttributes VertexAttribute
LayerStatement
LocationStatement
default
locked
Line
Lines Line
LineAttributes LineAttribute
FrameColorStatement
FromStatement
HeadTypeStatement
LabelOffsetStatement
LabelPositionStatement
LabelWidthStatement
LayerStatement
LineTypeStatement
LineWidthStatement
RotationAngleStatement
RtfTextStatement
TailTypeStatement
TextStatement
ToStatement
UniqueIdStatement
curved
default
locked
headType circle
headType doubleArrow
headType hollowArrow
headType solidCircle
tailType circle
tailType doubleArrow
tailType hollowArrow
tailType solidCircle
Group
Groups Group
GroupAttributes GroupAttribute
LocationStatement
RotationAngleStatement
SizeStatement
UniqueIdStatement
flippedHorizontally
flippedVertically
locked
RtfSource RtfSourceAtom
RtfGroup
RtfString RtfStringAtom
RTF_STRING
Float
