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_NUMBER (Font Fontsize Position [Start] [Text Before] [Text After])
-
Place a page number into the footer of the page.
Position can be one of:
L - left
R - right
C - centre
LR - left on odd pages, right on even pages
RL - right on odd pages, left on even pages
e.g ALBUM_PAGES_NUMBER (HN 10 C) Will place the page number centred in the footer using a 10 point Helvetica font.
An optional [Start] parameter can be used to set the starting page number
e.g ALBUM_PAGES_NUMBER (HN 10 C 7) The pages are numbered from 7 onwards
Optional [Text Before] and [Text After] parameters can be used to output text before and/or after the page number.
e.g ALBUM_PAGES_NUMBER (HN 10 C 1 "Page " " of $PAGES$")
(Note: $PAGES$ will be substituted by the actual total number of pages when the album is generated).
Resulting in for example:
Page 1 of 32
- ALBUM_PAGES_DATE (Font Fontsize Position Format [Separator] [Text Before] [Text After])
-
Place the date that the PDF file was generated into the footer of the page.
Position can be one of:
L - left
R - right
C - centre
LR - left on odd pages, right on even pages
RL - right on odd pages, left on even pages
Format can be one of:
YMD - year, month, day
DMY - day, month, year
MDY - month, day, year
e.g ALBUM_PAGES_DATE(HN 10 R YMD) Will place the date 20170113 in the footer on the right hand side using a 10 point Helvetica font.
An optional [Separator] parameter can be used to split the date fields
e.g ALBUM_PAGES_DATE(HN 10 R YMD "-") will output the date as 2017-01-13
Optional [Text Before] and [Text After] parameters can be used to output text before and/or after the date.
e.g ALBUM_PAGES_DATE(HN 10 R YMD "-" "Created: " )
- 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_RIGHT (Font Fontsize Text)
-
Place text on the page right justified.
eg PAGE_TEXT_RIGHT (HN 10 "This text appears on the right"). Place the text using a Helvetica 10 point font.
- PAGE_TEXT_VSPACE (Font Fontsize Text Vspace)
- PAGE_TEXT_CENTRE_VSPACE (Font Fontsize Text Vspace)
- PAGE_TEXT_RIGHT_VSPACE (Font Fontsize Text Vspace)
-
These commands perform the identical function to the PAGE_TEXT, PAGE_TEXT_RIGHT 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.
- PAGE_RULE_H (line spacing)
- PAGE_RULE_H (line spacing margin)
-
Draw a horizontal rule line that extends from the left to right margins.
Spacing is the amount of blank space before the line, this is in addition to the vertical space set by the ALBUM_PAGES_SPACING command
eg if the vertical spacing is set to 6mm then:
PAGE_RULE_H (0.5 10.0) will draw a 0.5mm horizontal line 16mm below the current element.
Note, spacing can take a negative value so if the vertical spacing is set to 6mm then:
PAGE_RULE_H (0.5 -6.0) will draw a 0.5mm horizontal line immediately below the current element.
This command accepts an optional third "margin" parameter that offsets the start and end of the line away from the margins.
eg PAGE_RULE_H (1.0 10.0 5.0). Will draw a 1mm horizontal line indented 5mm in from the left margin and ending 5mm from the right margin.
- 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_BOXES_SIZE_ADJUST (adjust)
-
This command is used to increase or decrease the box sizes of all succeeding stamps.
A positive value increases stamp sizes, a negative value will decrease stamp size.
e.g a 20x25mm stamp added after a STAMP_BOXES_SIZE_ADJUST(2.0) command would actually be drawn as 22 x 27mm.
Similarly, the same stamp after a STAMP_BOXES_SIZE_ADJUST(-1.5) command would be drawn as 18.5 x 23.5mm
The primary purpose of this command is to facilitate the sharing of albums.
If for example someone creates an album with the intention of using mounts requiring a 2mm border all round, then the stamp boxes would be sized
4mm larger than the stamps. For someone else to use the same album without mounts, rather than edit the album to adjust the size of
each and every stamp, they could simply add an STAMP_BOXES_SIZE_ADJUST(-4.0) command to the beginning of the
album to ensure that all boxes are drawn actual size.
- 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 [NO_FRAME])
-
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 optional NO_FRAME parameter will draw the stamp without a frame
eg STAMP_ADD_IMG (50.0 28.0 "admiral.png" "sg 5a" "" "sacc 4b" NO_FRAME)
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 [NO_FRAME])
-
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" "" "" "" "" "" "")
or without a frame
eg STAMP_ADDX_IMG (50.0 28.0 "admiral.png" "" "" "" "" "" "" NO_FRAME)
- STAMP_HEADING (Font Fontsize Text [offset])
- STAMP_HEADING_VA (Font Fontsize Text [offset])
-
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.
- STAMP_HEADING_PADDING (padding)
-
This command is used to adjust the space between the stamp heading and the stampbox.
The padding value, which may be negative or positive, is added to the default spacing. e.g:
STAMP_HEADING_PADDING (6.0)
or
STAMP_HEADING_PADDING (-3.0)
A positive value will increase the spacing, a negative value will reduce it
 |
Colour commands: |
Commands for setting the colours of various elements on a page. These all take a single parameter which is the colour name.
For a full list of available colours please refer to the table found on the Colours Page.
Note: AlbumEasy accepts both the American and International spellings of colour.
e.g : ALBUM_COLOUR_PAGE_BORDER and ALBUM_COLOR_PAGE_BORDER
- COLOUR_ALBUM_BORDER (colour) (or COLOR_ALBUM_BORDER)
- COLOUR_ALBUM_FOOTER (colour) (or COLOR_ALBUM_FOOTER)
- COLOUR_ALBUM_TITLE (colour) (or COLOR_ALBUM_TITLE)
-
These three commands set the colour of the page borders, footer text and title text for the whole album. e.g.
COLOUR_ALBUM_TITLE(blue)
COLOUR_ALBUM_BORDER(red)
COLOR_ALBUM_FOOTER(green)
- COLOUR_PAGE_RULE_H (colour) (or COLOR_PAGE_RULE_H)
- COLOUR_PAGE_TEXT (colour) (or COLOR_PAGE_TEXT)
-
These two commands set the colour of succeeding horizonal rule lines and for all text on the page except for titles and stamp text. e.g.
COLOR_PAGE_RULE_H(seagreen)
COLOUR_PAGE_TEXT(crimson)
- COLOUR_STAMP_BORDER (colour) (or COLOR_STAMP_BORDER)
- COLOUR_STAMP_HEADING (colour) (or COLOR_STAMP_HEADING)
- COLOUR_STAMP_TEXT (colour) (or COLOR_STAMP_TEXT)
-
Commands to set the colour of all succeeding stamp box borders, stamp heading text and the text inside and under stamp boxes. e.g.
COLOUR_STAMP_BORDER(royalblue)
COLOUR_STAMP_HEADING(chartreuse)
COLOUR_STAMP_TEXT(fuchsia)
 |
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." )