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.
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.
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.
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:
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.
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:
#!DG_TEXTThis line can also contain version information in the following format: #!DG_TEXT-Version-versionNumber When documents are saved by Diagram! 2, versionNumber is "2".
See the Statement Summary section below for descriptions of statements which are valid in this section.
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.
symbol 3 shape "Circle" location 100 100 size 100 100 framed shadowed end
Each vertex definition has this form:
vertex entityNumber statements endSee 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.
vertex 4 endThis 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 endLines
Each line definition has this form:
line entityNumber statements endSee 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.
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
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.
group 11 5 6 7 8 9 10 end
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
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.
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.
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.
indicates that a line should be curved.
Valid in Sections: Line.
indicates that this entity will be drawn when using the Line mode or Symbol mode.
Valid in Sections: Symbol, Line.
See also: defaultFont, defaultFontSize.
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
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
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.
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.
indicates that the entity is flipped across its horizontal axis.
Valid in Sections: Symbol, Group.
See also: flippedVertically.
indicates that the entity is flipped across its vertical axis.
Valid in Sections: Symbol, Group.
See also: flippedHorizontally.
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.
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.
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.
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.
specifies that the grid should be displayed.
Valid in Sections: Document
See also: gridSize.
specifies the size of a square of the grid. gridSpacing is a positive value in points.
Valid in Sections: Document
See also: grid.
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.
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.
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.
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.
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.
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.
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.
specifies that the entity has an attachment to a file.
Valid in Sections: Symbol
See also: 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.
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.
specifies that an entity can no longer be moved on the canvas.
Valid in Sections: Symbol, Line, Group, Vertex.
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.
indicates that a document is a palette. The presence of palette is the only difference between ".diagram2" and ".dpalette2" documents.
Valid in Sections: Document
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
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.
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.
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.
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
indicates that a shadow is drawn using the color specified with the shadowColor operator.
Valid in Sections: Symbol
See also: shadowColor.
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
indicates that rulers will be visible when the document is loaded.
Valid in Sections: Document
See also: showTools.
indicates that a button ribbon will be displayed when the document is loaded.
Valid in Sections: Document
See also: showRulers.
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.
indicates that the grid snap should be on.
Valid in Sections: Document.
See also: gridVisible, gridSize.
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.
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.
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.
specifies where text should appear in an entity. Possible values of place are:
top
middle
bottom
Valid in Sections: Symbol.
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.
specifies the location of the canvas within the window. viewX and viewY are specified in points.
Valid in Sections: Document
specifies the size of the view in the document window. viewWidth and viewHeight are positive, floating-point numbers.
Valid in Sections: Document
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
windowX and windowY are positive, floating-point values which specify the location of the window.
Valid in Sections: Document
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
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 endSyntax Summary This section describes the formal grammar for the Diagram!2 file format. It is intended for readers familiar with formal language specifications.