BMML File Format Specification

Quick Overview

Here's a sample BMML containing a single Callout control:

<mockup version="1.0" skin="sketch" measuredW="941" measuredH="169" mockupW="36" mockupH="40">
  <controls>
    <control controlID="1" controlTypeID="com.balsamiq.mockups::CallOut" x="644" y="129" w="-1" h="-1" 
             measuredW="36" measuredH="40" zOrder="1" locked="false" isInGroup="-1">
      <controlProperties>
        <text>Hello!</text>
        <backgroundAlpha>0.25</backgroundAlpha>
        <color>65280</color>
      </controlProperties>
    </control>
  </controls>
</mockup>

As you can see, the top-level tag is a 'mockup' tag. Within it, there's a 'controls' tag, which includes a list of 'control' elements, one for each control in the mockup. Each control elements can include an optional 'controlProperties' element, with different children depending on the type of element.

We will see below what all the attributes mean in details.

back to top

The Mockup Tag

Here's the DTD snippet for the mockup tag:

<!ELEMENT mockup ( controls? ) >
<!ATTLIST mockup measuredW NMTOKEN #REQUIRED >
<!ATTLIST mockup measuredH NMTOKEN #REQUIRED >
<!ATTLIST mockup mockupW NMTOKEN #REQUIRED >
<!ATTLIST mockup mockupH NMTOKEN #REQUIRED >
<!ATTLIST mockup skin NMTOKEN #REQUIRED >
<!ATTLIST mockup version NMTOKEN #REQUIRED >

<!ELEMENT controls ( control? ) >

A 'mockup' tag includes a 'controls' tag, described below.

measuredW and measuredH are the dimensions, in pixels, of the mockup, including the top-left white space around it.

mockupW and mockupH (added on 9/14/2009) are the dimensions of the mockup without any space around it. In other words, this would be the size of the PNG if you exported it.

The skin tag is not used right now, and is always "sketch".

The version tag is for the version of the BMML specification, which is 1.0 so far.

The controls tag is simple, it doesn't have any attributes and just contains a list of 'control' tags.

back to top

The Control Tags

Here's the DTD snippet for the control tag:

<!ELEMENT control ( controlProperties? ) >
<!ATTLIST control controlID NMTOKEN #REQUIRED >
<!ATTLIST control controlTypeID NMTOKEN #REQUIRED >
<!ATTLIST control w NMTOKEN #FIXED "-1" >
<!ATTLIST control h NMTOKEN #FIXED "-1" >
<!ATTLIST control measuredH NMTOKEN #REQUIRED >
<!ATTLIST control measuredW NMTOKEN #REQUIRED >
<!ATTLIST control x NMTOKEN #REQUIRED >
<!ATTLIST control y NMTOKEN #REQUIRED >
<!ATTLIST control zOrder NMTOKEN #REQUIRED >
<!ATTLIST control isInGroup NMTOKEN #FIXED "-1" >
<!ATTLIST control locked NMTOKEN #FIXED "false" >

The control tag can contain a controlProperties tag, described below.

controlID is always unique for this list of controls and identifies this control's instance in the mockup

controlTypeID is the control type (listed below).

w and h represent the size in pixels of the control. A value of -1 means that you should look at measuredW or measuredH instead.

measuredW and measuredH represent the size in pixels of the control, when shown in its 'natural state', i.e. it's the preferred dimension of the control as dictated by the control itself. For instance, for a Label control, measuredW would be large enough to show the whole text with no cropping.

x and y represent the position in pixels of the control, relative to the top-left corner of the canvas.

zOrder represents the layer ordering of this control. Values are unique and sequential within the current list of controls.

isInGroup tells you if a control is part of a group (-1 means "no", otherwise it uses the controlID of the group)

locked tells is a flag that tells you...you guessed it!

back to top

The ControlProperties Tag

The controlProperties tag contains a child for each property that can be modified for a control (using the property inspector).

Here's a list of the different control properties and where they are used:

• alternateRowColor, rowHeight, hasHeader, vLines, hLines: used for Lists and Data Grids controls
• backgroundAlpha (0..1): the transparency of the background
• bgPattern (one of 'allWhite', 'allBlack', 'topOnly', 'topBlueBottom', 'topBlackBottom'), topBar (bool): used by the iPhone control
• bold, italic, underline, align, size: used by any control with text in it
• borderStyle ('none' or 'square'): used by all controls which can show a border or not
• close, minimize, maximize, dragger, topheight, bottomheight: used by the Dialog / Window control
• color (int): the color of the text or the background of a component, depending on the control type
• customData (String): added on 10/21/2009, see here for details
• customID (String): added on 10/21/2009, see here for details
• direction ('left', 'center', 'right', 'bottom', 'top'): used by Arrows, Tabs, Curly Braces, Pointy Button etc
• href: used by all controls that can have a single link to other controls, like Button, Canvas, etc. Mockups saved before 9/14/2009 only contain the file name to link to, i.e. foo.bmml with no path. Mockups saved after 9/14/2009 contain a string of this form: <name>&bm;<viewURL>&bm;<loadURL>&bm;<editURL>. The last 3 values are all the same for Mockups for Desktop but are different in the plugin versions.
• hrefs: like href, but used by controls that link to multiple files, like the Accordion, Link Bar, etc. It's a comma-separated list of strings formatted the same way as a single href string (see previous bullet).
• icon: a string composed of both iconID of the icon to use for this control and its size, like this "iconID|48". There are over 150 icons, each with a unique ID. The sizes are either 16, 24, 32 or 48.
• indeterminate (bool) and scrollbarValue (0-100): used for Progress Bar controls
• labelPosition ('bottom' or 'right'): used in the Icon and Label control
• leftArrow (bool), rightArrow (bool), curvature (-1, 0, 1): used by the Arrow controls
• map (string): added on 9/14/2009: an escaped image map for the linked areas of the mockups, following the same format as the HTML map tag.
• onOffState ('on' or 'off'): used by the Switch control
• orientation ('portrait' or 'landscape'): used by the iPhone, iPhone control
• position ('left' or 'right'): used by Vertical Tab Bar
• selectedIndex (-1 for none): the selected item in a list
• src and filter: used by the Image control. src is either a relative path (for images loaded from disk) or an http url. filter is a flag, true if the image should be sketched
• state ('up', 'selected,', 'focused', 'disabled', 'disabledSelected'): the state of the control
• tabHPosition and tabVPosition: used by the Tab Bar controls
• tooltipDirection (NW, N, NE, E, SE, S, SW, W): used by the tooltip control
• value: the value of a scrollbar, from 0 to 100
• verticalScrollbar (bool) and value (0-100): whether the control has a scrollbar or not, and its value (0 means "top", 100 means "all the way down")

back to top

Control Type IDs and Icon IDs

All the control type IDs start with the "com.balsamiq.mockups::" prefix. Here's the full list of the control type IDs supported as of today (case sensitive): Accordion, Alert, Arrow, BarChart, BreadCrumbs, BrowserWindow, Button, ButtonBar, Calendar, CallOut, Canvas, CheckBox, CheckBoxGroup, ColorPicker, ColumnChart, ComboBox, CoverFlow, DataGrid, DateChooser, FieldSet, FormattingToolbar, HCurly, HelpButton, HorizontalScrollBar, HRule, HSlider, HSplitter, Icon, IconLabel, Image, iPhone, iPhoneKeyboard, iPhoneMenu, iPhonePicker, Label, LineChart, Link, LinkBar, List, Map, MediaControls, Menu, MenuBar, ModalScreen, MultilineButton, NumericStepper, Paragraph, PieChart, PointyButton, ProgressBar, RadioButton, RadioButtonGroup, RedX, RoundButton, ScratchOut, SearchBox, StickyNote, Switch, TabBar, TagCloud, TextArea, TextInput, Title, TitleWindow, Tooltip, Tree, VerticalTabBar, VerticalScrollBar, VideoPlayer, VCurly, VSplitter, VolumeSlider, VRule, VSlider, Webcam

Here's a full list of the icon IDs supported as of today (case-sensitive): AddPageIcon, AlarmClockIcon, Alert2Icon, AlertIcon, ArchiveIcon, BackSpaceIcon, BaloonIcon, BatteryIcon, BoldIcon, BookIcon, BulletsIcon, CalendarIcon, CameraIcon, CartIcon, CellBarsIcon, CellPhoneIcon, CheckMarkIcon, CircledMinusIcon, CircledPlusIcon, CircledXIcon, ClockIcon, ColumnsIcon, ContactIcon, ContactsIcon, CopyIcon, CopyrightIcon, CoverFlowIcon, CreativeCommonsIcon, CursorIcon, CutIcon, DashIcon, DataBaseIcon, DeliciousIcon, DocEmptyIcon, DocExcelIcon, DocPDFIcon, DocWordIcon, DollarIcon, DotIcon, DownArrowIcon, DownFillTriangleIcon, DownLeftArrowIcon, DownloadIcon, DownRightArrowIcon, DownTriangleIcon, EllipsisIcon, EmailIcon, EmoticonIcon, EuroIcon, EyeIcon, FileIcon, FlagIcon, FolderClosed, FolderIcon, ForwardChapterIcon, ForwardIcon, FullScreenIcon, GearIcon, GeoLocationIcon, GridIcon, GtCircledIcon, GtIcon, HandClosedIcon, HandOpenIcon, HandPointIcon, HelpIcon, HLinesIcon, HomeIcon, HourGlassIcon, ImageIcon, IndentIcon, Info2Icon, InfoIcon, ItalicIcon, JewelIcon, JumpBackIcon, JumpOutIcon, LeftArrowIcon, LeftFillTriangleIcon, LeftTriangleIcon, LightBulbIcon, LineIcon, LinkGlobeIcon, LinkIcon, ListIcon, LockIcon, LockOpenIcon, MicIcon, MinusIcon, NumberedListIcon, OutdentIcon, PagesIcon, PaperClipIcon, PasteIcon, PauseIcon, PencilIcon, PlusBigIcon, PlusIcon, PortletEditIcon, PortletHelpIcon, PortletMaximizeIcon, PortletMinimizeIcon, PoundIcon, PrintIcon, PushPinIcon, RedoIcon, RegisteredIcon, ReloadIcon, RewindChapterIcon, RewindIcon, RightArrowIcon, RightFillTriangleIcon, RightTriangleIcon, RSSIcon, SadFaceIcon, SaveIcon, ScreenIcon, SearchIcon, ShapesIcon, ShiftIcon, SkypeIcon, SmallClockIcon, SpinningIcon, SquaredMinusIcon, SquaredPlusIcon, StarIcon, StopIcon, StrikeThroughIcon, TableIcon, TapeIcon, TelephoneIcon, TextAlignCenterIcon, TextAlignLeftIcon, TextAlignRightIcon, ThreeGIcon, ThumbnailsIcon, TrademarkIcon, TrashIcon, UnderlineIcon, UndoIcon, UpArrowIcon, UpFillTriangleIcon, UpLeftArrowIcon, UpRightArrowIcon, UpTriangleIcon, UserIcon, UsersIcon, VideoCameraIcon, VLinesIcon, VolumeIcon, WirelessIcon, WriteIcon, XIcon

back to top