AlbumEasy - Commands

This section contains a list of the commands that may be included in an album definition text file.

Note: All measurements are specified in mm.

Note: Commands that output text require that the user specify a font. Available fonts are listed here.

Comments:

In order to document an album definition text file it may contain comments which are ignored by AlbumEasy.
The # character is used to demarcate a comment. AlbumEasy will ignore all text in a line containing a # character starting from the # until the end of the line.

The following commands control the appearance of all pages in the album. These should be placed at the beginning of each album text file:

ALBUM_PAGES_SIZE (width height)
Set the width and height of the album page
eg ALBUM_PAGES_SIZE (215.9 279.4) for US Letter size (8.5 x 11)
or
ALBUM_PAGES_SIZE (210.0 297.0) for A4 paper
ALBUM_PAGES_MARGINS (left right top bottom)
Set the page margins
eg ALBUM_PAGES_MARGINS (25.0 12.0 15.0 15.0). Will leave a wider left margin to allow for punch holes
ALBUM_PAGES_MARGINSE (left right top bottom)
Optional margin command to set different margins for even numbered pages.
ALBUM_PAGES_BORDER (outer inner spacing)
Optional command to place a double line border around the page, just inside the margins.
eg ALBUM_PAGES_BORDER (0.5 0.1 1.0). Draw the outer border 0.5mm thick, the inner border 0.1mm thick, with a 1mm space between borders.
NOTE: This command incorrectly calculates the border spacing, so it should only be used for compatibility with existing album data files. For new albums consider using the ALBUM_PAGES_BORDER3 command instead.
ALBUM_PAGES_BORDER3 (outer inner1 inner2 spacing)
Optional command to place a single, double or triple line border around the page just inside the margins. NOTE: This command supersedes the ALBUM_PAGES_BORDER command.
eg ALBUM_PAGES_BORDER3 (0.1 0.5 0.1 1.0). Draw an outer border 0.1mm thick, an inner border 0.5mm thick, and a second inner border 0.1mm thick with a 1mm space between borders.
To draw a double or single line border set the unused widths to 0.0. e.g a double border with the outer border 0.5mm thick, the inner border 0.1mm thick and a 1mm space between borders:
ALBUM_PAGES_BORDER3 (0.5 0.1 0.0 1.0)
ALBUM_PAGES_TITLE (Font Fontsize Title)
Place a title on all pages in the album.
eg ALBUM_PAGES_TITLE (TB 16 "Transvaal"). Use Times Roman Bold 16 point to place Transvaal on every page.
ALBUM_PAGES_SPACING (horizontal vertical)
Set the horizontal and vertical spacing for elements on a page.
Horizontal spacing controls the distance that text and stamps will be separated from the left and right border.
Vertical spacing controls the space between rows of stamps, or blocks of text. eg ALBUM_PAGES_SPACING (6.0 6.0). Will set the horizontal and vertical spacing to 6 mm.
ALBUM_STAMP_IMG_SETTING (horizontal vertical stretch)
Optional command that affects the placement of images inside stamp boxes.
The horizonal and vertical values are the width of the border between the stamp frame and the image. The stretch parameter which can have a value of true or false only effects images that are smaller than the stamp drawing area. When stretch is set to true the images will be stretched to fill the box, if it is false then images will be drawn actual size centred within the stamp box.
eg
ALBUM_STAMP_IMG_SETTING (3.0 3.0 false) or
ALBUM_STAMP_IMG_SETTING (2.0 2.0 true)
Note, the default settings which is the equivalent of ALBUM_STAMP_IMG_SETTING (2.0 2.0 false) will be used if this command is not given.
The album file Images.txt which can be found in the AlbumEasy examples directory illustrates the usage of this command.

The following commands apply to individual pages:

PAGE_START
Start a new page. NB There must always be at least one PAGE_START to indicate the first page.
PAGE_START_VAR (horizontal vertical)
Start a new page, overriding the ALBUM_PAGES_SPACING for this page only
See here for an example example.
PAGE_TEXT (Font Fontsize Text)
Place a paragraph of text on the page. The paragraph is left justified, and formatted to fit between the margins of the page, separated at each side by the horizontal value specified in ALBUM_PAGES_SPACING.
eg PAGE_TEXT (HN 10 "Descriptive text"). Place the text using a Helvetica Normal 10 point font.
PAGE_TEXT_CENTRE (Font Fontsize Text)
Place text on the page, and centre it.
eg PAGE_TEXT_CENTRE (HB 10 "A heading"). Place the text using a Helvetica Bold 10 point font.
PAGE_TEXT_VSPACE (Font Fontsize Text Vspace)
PAGE_TEXT_CENTRE_VSPACE (Font Fontsize Text Vspace)
These commands perform the identical function to the PAGE_TEXT and PAGE_TEXT_CENTRE commands above, however the amount of blank space output after the paragraph of text is controlled by means of the Vspace parameter.
eg PAGE_TEXT_VSPACE (HN 10 "Descriptive text" 0.5). Places the text using a Helvetica Normal 10 point font with 0.5mm of blank space after the text.
This is useful for example to output a paragraph of text where each line does not have the same font.
See here for an example example.
ROW_START_ES (Font Fontsize border)
Start a row of stamps with equal spacing
The stamps are spaced evenly across the page with equal spacing between the stamps as well as the margins.
Font and Fontsize specify the font that will be used for any text under or inside the stamp frame. Border specifies the thickness of the line used to draw the stamp frame.
eg ROW_START_ES (HN 6 0.1). Use 6 point Helvetica Normal font, with a 0.1mm border for the stamp frames.
ROW_START_JS (Font Fontsize border)
Start a row of stamps with justifed spacing
The left edge of the leftmost stamp at the left margin, the right edge of the rightmost stamp at the right margin, with equal spacing between the stamps
ROW_START_FS (Font Fontsize border spacing)
Start a row of stamps with fixed spacing
Stamps are placed with fixed spacing between them, with the row centred between the margins. eg ROW_START_FS (HN 6 0.1 6.0). Use a 6 point Helvetica font, with a 0.1mm border for the stamp frames. stamps are spaced 6.0mm apart.
ROW_ALIGN_TOP
ROW_ALIGN_MIDDLE
ROW_ALIGN_BOTTOM
These commands control the vertical alignment of stamps in a row. Stamps will aligned by either the top or bottom edges or the middle according to command. The alignment will be applied to all subsequent rows until the next ROW_ALIGN_ command. ROW_ALIGN_TOP is the default.
See here for examples.
STAMP_ADD (width height txt0 txt1 txt2 txtBL txtBC txtBR)
Add a stamp
The stamp frame is drawn using the specified width and height. Each stamp can have up to 6 text items:
txt0, txt1, and txt2 are rows of text to be placed inside the frame. txtBL, txtBC, and txtBR are three text items placed below the frame.
eg STAMP_ADD (50.0 28.0 "1 1/2d" "chestnut" "tete-beche pair" "sg 5a" "" "sacc 4b") will draw a frame 50mm wide, by 28mm high. With three rows of text inside, and two text item underneath. NB All text items must be specified even if not used.
eg STAMP_ADD (50.0 28.0 "" "" "" "" "" "") will draw the frame with no text.
STAMP_ADDX (width height txt0 txt1 txt2 txtBL txtBC txtBR txt1BL txt1BC txt1BR)
Identical to the previous command, but allows for a second row of three text items under the frame. NB All text items must be specified even if not used. eg STAMP_ADDX (50.0 28.0 "" "" "" "" "" "" "" "" "")
STAMP_ADD_BLANK (width height)
Add a blank stamp with no frame or text. This is useful for leaving a gap within a row. See here for an example.
STAMP_ADD_TRIANGLE (width height txt0 txt1 txt2 txtBL txtBC txtBR)
Add a triangle shaped stamp. Parameters are identical to the STAMP_ADD command above.
STAMP_ADD_TRIANGLE_INV (width height txt0 txt1 txt2 txtBL txtBC txtBR)
Add an inverted triangle shaped stamp. Parameters are identical to the STAMP_ADD command above.
STAMP_ADD_DIAMOND (width height txt0 txt1 txt2 txtBL txtBC txtBR)
Add a diamond shaped stamp. Parameters are identical to the STAMP_ADD command above.
STAMP_ADD_IMG (width height image txtBL txtBC txtBR)
Add a stamp containing an image
The stamp frame is drawn using the specified width and height. The image is the name of the image file to be drawn within the stamp frame. Currently AlbumEasy only supports PNG and JPEG formatted image files.
The image file must be specified relative to the location of the album text file.
e.g if the image file is called admiral.png and located in the same directory as the album file, it can be specified as "admiral.png" however if it is located in for example a subdirectory called images, then the subdirectory name must be included "images/admiral.png"
Also, like the STAMP_ADD command, each stamp can have up to 3 text items (txtBL txtBC txtBR) drawn below the frame:
eg STAMP_ADD_IMG (50.0 28.0 "admiral.png" "sg 5a" "" "sacc 4b") will draw a frame 50mm wide, by 28mm high containing the image admiral.png. Two text items will be drawn underneath the frame. NB All text items must be specified even if not used.
eg STAMP_ADD_IMG (50.0 28.0 "admiral.png" "" "" "") will draw the stamp with no text underneath.

The album file Images.txt which can be found in the AlbumEasy examples directory illustrates the usage of this command.
NOTE: the optional ALBUM_STAMP_IMG_SETTING command may be used to adjust the placement of the image within the stamp frame.
STAMP_ADDX_IMG (width height image txtBL txtBC txtBR txt1BL txt1BC txt1BR)
Identical to the previous command, but allows for a second row of three text items under the frame. NB All text items must be specified even if not used. eg STAMP_ADDX_IMG (50.0 28.0 "admiral.png" "" "" "" "" "" "")
STAMP_HEADING (Font Fontsize Text)
STAMP_HEADING_VA (Font Fontsize Text)
These commands are used to attach a heading to a stamp. These commands must follow immediately after one of the STAMP_ADD commands.
eg To add a heading to a stamp:
STAMP_ADD (28.0 32.0 "" "" "" "" "" "")
STAMP_HEADING(HN 12 "Heading Text")

Multi-line headings can be placed by means of the line break character "\n" eg
STAMP_HEADING(HN 12 "Heading Text Line 1\nLine 2")

The STAMP_HEADING_VA command aligns the headings in a row of stamps vertically, whereas the STAMP_HEADING command aligns the heading with the stamp. See here for the difference between the two commands.

The commands can optionally take a fourth "offset" parameter which can be used to shift the heading horizontally. eg:
STAMP_HEADING(HB 12 "Heading" 34.0)
See here for an example.

For further examples of the how these commands may be used, please see the StampHeadings.txt and SteinerExample.txt example album files.

Text continuation and special characters:

For convenience, text placed using the PAGE_TEXT and PAGE_TEXT_CENTRE may be continued over multiple lines. e.g:
    PAGE_TEXT (HN 10 "This is all "\
                     "one "\
                     "line of text")

Note the use of the \ character to indicate line continuation.

The following characters have a special meaning within a text string:
\n Start a new line
\" Insert a " character
\\ Insert a \ character

eg. To place two lines of text centred on the page
PAGE_TEXT_CENTRE (HS 12 "First line of text \n Second Line.");

Custom fonts:

ALBUM_DEFINE_FONT (fontId "fontName" Encoding)
This command assigns an external font to a user defined fontId. A maximum of 12 external fonts may be assigned per album.
fontId: Is used to identify the font and can be any unique name that is between 2 and 8 characters long.
"fontname" (which must include the quotes): This can be chosen from the available fonts listed in the Available Fonts Dialogue Box, this lists each font along with the code pages supported by the font.
Encoding: This is optional, if given it must be one of the listed code pages for the font. If left blank the default Latin 1 character set will be use.
For example to add three fonts:
    ALBUM_DEFINE_FONT(PENGUIN "Penguin Attack")
    ALBUM_DEFINE_FONT(CYRILLIC "DejaVu Sans" CP1251)
    ALBUM_DEFINE_FONT(HEBREW "DejaVu Sans" CP1255)
The first of which the user has chosen to identify as PENGUIN refers to a font called Penguin Attack using the default character set.
The second which the user chose to identify as CYRILLIC will load the DejaVu Sans font using the Cyrillic character set.
The third which the user has chosen to call HEBREW also refers to the DejaVu Sans font but using the Hebrew character set.
Then to output text using the Penguin Attack font in 16 points.
    PAGE_TEXT (PENGUIN 16 "This is text using the Penguin Attack font." )