Balsamiq Mockups Online Help

Overall Application Structure

Balsamiq Mockups is made up of three major blocks. From top to bottom: the application bar, the UI library and the mockup canvas. Each is described below.

The Application Bar

The application bar includes menus, the Quick Add tool and the toolbar. Each is described below.

The Menus

The Mockups menus should be pretty self-explanatory. The only tricky bit is that the Mockup menu contains different items depending on what version of Balsamiq Mockups you are using. In general, that's where you'll find the About Box and commands related to your mockup as a whole, like saving, exporting to XML or PNG, etc.

The Quick Add Tool

The Quick Add tool is the fastest way to add UI controls to your mockup. To use it, simply type a few letters from the name of the UI control you wish to add and Quick Add will show you a list of suggestions. Use your mouse or arrow keys to scroll down the list to the UI control you wish to add, hit the ENTER key and voila', a new control is placed on the mockup canvas for you. For instance, typing "bu" shows a list containing "Button", "Button Bar", "Help Button", "Radio Button" and "Round Button". Typing "hel", on the other hand, only returns "Help Button". Pressing the ESCape key makes the list disappear, as one would expect.

Try out Quick Add now! As you become familiar with it, you could even hide the UI Library (through the View menu) and simply use Quick Add to add UI elements to your mockup. This maximizes both your mockup canvas area and your speed!

The Toolbar

The toolbar includes most of the same commands as the Edit menu: undo, redo, duplicate, cut, copy, paste and delete. Not all versions of Balsamiq Mockups support the same keyboard shortcuts (more info here), so the Toolbar gives you a handy way to perform common actions. Notice that you'll find the same commands in the Property Inspector as well.

The UI Library

The UI Library, or UI Controls Library, is the long strip of UI Controls just below the Application Bar. It lists all of the different UI control types that Mockups supports, alphabetically. The main goal of the UI Library is to let you add UI Controls to the mockup canvas, but you can also use it to see what's possible and to get inspiration for your UI mockup.

To add a new UI control to the canvas, simply select the control type you wish to add, then you can either "drag and drop" it to the mockup canvas below or simply double-click and Balsamiq Mockups will place it on the mockup canvas for you.

The Mockup Canvas

This is the main working area of Balsamiq Mockups, where your UI mockup comes to life. Once you add UI controls to it, you can move them, resize them and tweak them to your heart's content until your UI mockup is ready. See the sections below for instructions.

The mockup canvas grows and shrinks with your browser or application window, so you can make room for bigger mockups if you need to.

back to top

 

Working with UI Controls

Adding UI Controls

To add new UI controls to your mockup, you can use the UI Library or the Quick Add tool, described above.

Another way to add new Ui control is to duplicate the selected controls. You can either use copy and paste to do so, or the duplicate menu command or button, or simply hold down the ALT key (OPTION key on a Mac) and drag the selection. This will duplicate it in place and let you move it all at once.

Selecting UI Controls

There are a few different ways to select UI controls. If you are familiar with graphics software, these should be of no surprise.

• Clicking on a UI control selects it.
• Dragging a rectangle which encloses many UI controls selects them
• SHIFT+CLICK on a control adds it to the selection
• CTRL+CLICK on a selected control removes it from the selection
• Hold ALT to ignore items behind the mouse and drag-select, as shown in this short video

Moving UI Controls

Once you have selected one or more UI controls, there are a few different ways to move it on the canvas.

• you can drag it with your mouse.
• you can "nudge it" a few pixels with your keyboard's UP/DOWN/LEFT/RIGHT keys
• you can "nudge it" with bigger steps by holding down SHIFT and using your keyboard's UP/DOWN/LEFT/RIGHT keys
• you can move your controls to be aligned in one direction by using the align tools found in the Property Inspector.

Resizing UI Controls

Resizing the selected controls is easy. You can just grab one of the 8 little squares of the selection rectangle and drag it. If you want to constrain proportions while dragging from a corner square, hold the SHIFT key while dragging.

Another way to resize some controls to their "natural size" is to use the Auto-Size function found in the Property Inspector.

Layering UI Controls

You can layer controls as if they were pieces of paper on the mockup canvas. To do so, you select the controls you want to layer and select one of four layering commands available via the Property Inspector: bring to front, send to back, bring forward and send backward.

Deleting UI Controls

To remove some UI controls from the mockup canvas, select them and hit the DELETE key. Alternatively you can click on the eraser button in the toolbar or select "delete" from the Edit menu.

Grouping UI Controls

Sometimes you might wish to group some controls to better align them or to move them all at once. To group a set of controls, select them and hit CTRL+g on your keyboard. Once grouped, the controls will behave as one when moving or aligning. Note that you will not be able to edit the controls text or other properties once they are grouped. To ungroup controls, you hit CTRL+SHIFT+g on your keyboard. Groups can be nested.

back to top

 

Working with Text

Some UI controls, such as Button, Label or DataGrid, have text in them. To edit the text, double-click on the control and start typing. Or if you have the control selected, simply hit ENTER or F2 to start editing. To commit the text you typed, simply click anywhere other than the text field you typed in or hit Enter or CTRL+Enter. If you want to discard the text changes you just made, hit the ESCape key.

A note on special characters: some controls use some characters as separators. For instance, to create multiple buttons in a button bar, you separate them with a comma. Or a space character separates tags in a Tag Cloud control. Some other controls, like the Tree, use other characters alltogether. In such cases the default text for the Control includes explanations on how to use it.

Basic formatting: you can use the following notation to format only certain parts of your control’s text:

• for italic, use _this notation_
• for a link, use [this notation]
• for bold, use *this notation*
• for disabled, use -this notation-

Here’s a screenshot of what the above text looks like in a Paragraph control, for instance:

The shortcuts will work almost everywhere, where it makes sense, and you can combine them, so to make an italic link use [_this_] or _[this]_.

Most of the text in the controls of Mockups is bold by default, so bolding some text within it won’t make a difference. Some controls like Paragraph or Label allow you to “unbold” the text via the properties panel. If you do so, the words you *bolded* will stay bold. I know this is not consistent everywhere, but I think simplicity (i.e. less options) trumps consistency in some cases.

You can escape *, _, -, [ and ] characters with \*, \_, \-, \[ and \], so if you want to write “this [is] some text” and don’t want the “is” to become a link, just type “this \[is\] some text”.

A note about groups: at the moment you cannot edit text in a control that is part of a group. Ungroup the control first to edit it.

back to top

 

Working with Icons

Balsamiq Mockups comes packed with over 70 hand-drawn icons for you to use. The UI controls that support icons are: "Icon", "Icon and Text Label", "Button", "Menu Bar" and "ComboBox". There are two ways to select an icon to use, the icon search and the icon library.

Icon Search: if the controls you selected support icons, you will see the icon search box in the property inspector. This works much like the Quick Add tool: just type a few letters from the name of the icon you are looking for and a list of suggestions will pop up. In this case, the list is a grid of icons to choose from. Just click on the one you want to select it.

The Icon Library: if you'd like to explore all the icons that are available, click on the little down-pointing arrow to the right of the icon-search box. This will bring out the icon library. The icon library is pretty self-explanatory, let me know if you'd like more detailed info about it. One little trick is to double-click on the icon you'd like to select, instead of clicking and clicking on the "Select" button.

Once you have selected an icon, you can resize it, or remove it, via the Property Inspector.

back to top

 

Working with Images

The video below gives a good introduction of the Image Import feature and what it enables:

The feature is simple to use and yet very powerful, enabling a number of different use-cases. For instance:

• improving an existing interface: take a screenshot of the current UI and import it into Mockups to tweak or use as reference, like this:
• you can import images of custom icons or custom control types, like this:
• advanced feature: since images are linked in and not embedded, you can use the image import feature to create "master slides" and component templates, as shown in the video below. I realize it's a bit tricky, but I think this is an advanced use-case so I think it's OK, at least for now.

Aside from the Image control, you can also embed images in the Cover Flow component (as seen in the video at the top)

back to top

 

The Property Inspector

The property inspector is the little floating rectangle that appears once you select one or more UI controls. It allows you to perform some common functions such as copying/pasting, layering, and aligning controls, as well as some control-specific customizations.

The Property Inspector fades in and out of view in an effort to be out of your way. You can also drag and drop the Property Inspector to move it, it will re-appear where you left it next time you need it.

Common Inspectors

Editing Inspector	Always present, always at the top. From left to right: undo, redo, duplicate, cut, copy, paste, delete, group, ungroup, lock
Layering and Position & Size	Always present, always in the second row (below the editing inspector). Layering, from left to right: bring to front, send to back, bring forward, send backward. Position and size shows you the size and position of the selection, in pixels. Clicking on the numbers lets you edit them. The format is "X,Y WxH" where X is the x position, Y is the y position (0,0 is top-left, growing right and down), W is the width and H is the height of the selection.
Align	Shown whenever more than one control is selected. Lets you align the selected elements horizontally to the left, center and right and vertically to the top, middle and bottom. The last two icons on the right distribute the centers of the selected items horizontally or vertically.

Other inspectors

Arrow	Lets you decide the direction and curvature of the arrow, as well as whether to show or hide arrow pointers.
Auto-Size	Clicking on the autosize button will resize the component to its natural size, with everything showing and no extra space
Border	Shows or hides the selected controls; border
Color	Lets you select the foreground or background color of the selected controls (depending on the control type), as well as the background color's opacity (only in some controls, see right).
Icon	The icon inspector lets you select, resize and remove an icon to the selected controls. You simply click on the search field, start typing the name of the icon you need and you'll be presented with suggestions that match your string. Use the arrow keys or your mouse to select the icon you want, then use the slider to resize it. To remove an icon, click on the eraser icon next to the slider. To see the full list of icons available, click the little triangle which will open the Icon Library.
Icon Label Position	Lets you specify whether the label should be positioned below or to the right of the icon
Image	The Image inspector lets you select which image to use for the selected image controls. You can select the default placeholder, add a new image or select from a list of images already present in the mockup. You can additionally "sketch" the image to make it look a bit more hand-drawn by selecting the "Sketch it!" checkbox.
Links	Lets you link a mockup to another. See below for more info.
List and DataGrid	Lets you specify whether the selected controls should have a header row, two colors for alternating row backgrounds, the height of the row and which row should be selected, if any. In the DataGrid control, you can additionally toggle the visibility of vertical and horizontal dividing your table's columns and rows.
Progress Bar Type	Lets you toggle between a progressive and an indeterminate (candy-cane) progress bar.
Scrollbar	Lets you quickly add a scrollbar to the selected controls.
Selection	Lets you specify which elements of the selected control should be selected, if any.
State	Lets you specify the state of your control, whether it's in focus, selected, disabled etc. Different control types support different states.
Horizontal Curly Brace Direction	Lets you specify whether the horizontal curly brace should point up or down
Tabs Position	Lets you specify whether the tabs should be above or below the canvas, as well as their horizontal alignment relative to the canvas.
Text Styles	Lets you specify whether the font of the text in the selected controls should be bold, italic or underlined, as well as its horizontal alignment and point size.
Vertical Curly Brace Direction	Lets you specify whether the vertical curly brace should point left or right
Vertical Tabs Position	Lets you specify whether the tabs should be to the left or right of the canvas.
Window / Dialog	Lets you toggle window chrome controls like minimize, maximize and close, as well as a dragging affordance. You can also specify the height of the top and bottom bars.

back to top

 

Keyboards Shortcuts

Below is a list of all the keyboard shortcuts and modifiers which you can use in Balsamiq Mockups. While all of the shortcuts will work in the Desktop version, some might not work when you edit mockups in a browser.

If you are running OS X, you can use the Command Key (the Apple Key) wherever you read CTRL in the list below.

Working with Controls
Add to selection	SHIFT+CLICK
Toggle selection	CTRL+CLICK
Select All	SHIFT+A
Edit the selected control's text	ENTER or F2
Resize maintanining aspect ratio	Hold SHIFT
Disable snapping during move or resize	Hold CTRL
Nudge selection 2px	arrow keys
Nudge selection 20px	SHIFT+arrow keys
Nudge-Resize selection 2px	CTRL+ALT+arrow keys
Nudge-Resize selection 20px	CTRL+ALT+SHIFT+arrow keys
Clone selection	ALT+drag
Undo last command	CTRL+Z
Redo last command	CTRL+Y
Cut the selected controls	CTRL+X
Copy the selected controls	CTRL+C
Paste	CTRL+V
Paste In Place	CTRL+SHIFT+V
Delete the selected controls	DELETE or BACKSPACE
Duplicate the selected controls	CTRL+D
Select All	CTRL+A
Group the selected controls	CTRL+G
Ungroup the selected groups	CTRL+SHIFT+G
Lock the selected controls	CTRL+2
Unlock all locked controls	CTRL+ALT+2
Align selected controls left	CTRL+ALT+1
Align selected controls center	CTRL+ALT+SHIFT+2
Align selected controls right	CTRL+ALT+3
Align selected controls top	CTRL+ALT+4
Align selected controls middle	CTRL+ALT+5
Align selected controls bottom	CTRL+ALT+6
Quick Add
Sending focus to Quick Add	/ (forward slash) or + (plus sign)
Navigating the Suggestion List	arrow keys
Closing the Suggestion List	ESCAPE
Sending focus back to the Canvas	ESCAPE
Working with Icons
Navigating the Suggestion List	arrow keys
Using the selected icon	ENTER
Closing the Icons Library	ESCAPE
Closing the Suggestion List	ESCAPE
Editing Text
Start Editing text of the selected control	ENTER or F2
Committing the current text	ENTER (single-line controls), CTRL+ENTER (multi-line controls) or click anywhere
Ignoring the current edit	ESCAPE
Working with Mockup Files
New Blank Mockup	CTRL+N
New Clone of Current Mockup	CTRL+SHIFT+N
Open a mockup file	CTRL+O
Save the current mockup file	CTRL+S
Save all open mockups	CTRL+SHIFT+S
Close current mockup	CTRL+W
Close all mockups	CTRL+SHIFT+W
Export this mockup's XML	CTRL+E
Import mockup	CTRL+SHIFT+E
Export Snapshot to Clipboard	CTRL+SHIFT+C
Export Snapshot to PNG	CTRL+R
Export All Snapshots to PNG	CTRL+SHIFT+R
Print mockup	CTRL+P
Quit Balsamiq Mockups	CTRL+Q
Looping through the open files in Mockups for Desktop	CTRL+TAB and CTRL+SHIFT+TAB
Other
Hide/Show the UI Library	CTRL+L
Enter Full Screen View	CTRL+F
Exit Full Screen View	ESC
Lorem-Ipsum generator	type "lorem" in a Paragraph or Text Area

back to top

 

Importing and Exporting

Exporting and Importing via XML

Balsamiq Mockup gives you the ability to export your mockup as an XML file, which is useful for creating copies of your mockup, or emailing the mockup to someone else, or possibly exporting it to another format (bring your own code for this).

Exporting a mockup is easy, just select "Export Mockup..." from the Mockup menu, and you'll see this dialog:

Once you have the XML, you can use it to create a new mockup by just importing it via the "Import Mockup" dialog:

Note that importing a mockup will erase the contents of your mockup canvas

Exporting to an image

If you just want to get an image of your mockup to send around, you can simply select the "Download PNG image" command from the Mockup menu.

back to top

 

Linking Mockups Together

Starting with version 1.6 it is possible to link different mockups together in order to create a simple prototype for your site or software application.

At the moment the linking feature only works in the Desktop version, but we are actively working on adding linking capabilities to the plugin versions of Mockups as well.

Linking two mockups together is now as easy as choosing a file name from a pull-down menu. Simply click on a control that supports linking (most do), and you’ll see a new “Link” pull-down in the floating property inspector

If you don't see the pull-down, you should click on the "Show Link Inspector" link:

If the pull-down is disabled, please save your mockup and select the control you want to link from again.

The list is pre-populated with the names of all the BMML files found in the same folder as the file you’re editing. As long as you keep all the related mockups in the same folder (I have one per project I’m working on, and I keep them in DropBox), this should be all you need. BTW, it’s a best practice to also keep all images related to a project in an “images” folder next to BMML files.

For controls that can have multiple targets, you’ll see something like this instead:

Once you have selected a mockup to link to from the pull-down menu, the control will show a little arrow icon at their bottom-right corner, as shown in this screenshot:

When you're happy with your link structure simply enter Full Screen Presentation mode (see details below) and you'll be able to click on the links you set up to test your prototype.

Controls with links will have a little blue overlay on them as well as the link icon and mousing over them will show a big hand pointer with the name of the target file for this link, like so:

Simply click on a link to load up the referenced mockup file.

Actually, there’s one more thing: you can use the left and right arrow keys to go back and forth between the mockups you have visited in your run-through.

Here’s a quick screencast (38 seconds, no audio) of linking up three existing mockups and running through the resulting prototype:

back to top

 

Presenting Your Work

Mockups includes a "Full Screen Presentation" mode for those times when you need to present your wireframes to other stakeholders.

To enter Full Screen Presentation mode, just click on the full-screen icon in the top-right corner of Mockups, or select "Full Screen Presentation" from the View menu, or simply hit CTRL+F.

Mockups will expand to take up your whole screen (to eliminate distractions), and your mockup will be centered on the screen.

You will also see a big blue arrow pointer appear. The pointer will point towards the center of the screen in order to always stay out of the way of your mockup as much as possible.

You will also see two little toggle buttons in the lower-right corner of your screen. They’ll fade out in a few seconds, but you can always bring them back by mousing over the bottom-right corner of the screen.

The first toggle is for showing and hiding linking hints and the big pointers. You can now turn them off if you’re using the presentation mode to test a new UI on some user and don’t want to give them hints on where to click, or simply if you find the big pointer distracting.

The second toggle is for showing and hiding markup elements, such as Sticky Notes, Arrows and Callouts (any control under the “Markup” tab in the UI Library). This is useful if you want to just look at your UI without the annotations that surround it.

The state of the two toggles is remembered across sessions, and in the Desktop version you can use the “m” (or “M”) and “l” (or “L”) keys to toggle the two settings as well.

To exit Full Screen Presentation mode, just hit the ESC key.

back to top

 

Confluence Integration

Please refer to the Balsamiq Mockups for Confluence Online Help page.

back to top

 

JIRA Integration

Please refer to the Balsamiq Mockups for JIRA Online Help page.

back to top

 

XWiki Integration

Please refer to the Balsamiq Mockups for XWiki Online Help page.

back to top

 

FogBugz Integration

Please refer to the Balsamiq Mockups for FogBugz Online Help page.

back to top

 

The Desktop Version

The Desktop version of Balsamiq Mockups allows you to work on your mockups when you are not connected to the Internet. It also supports all keyboard shortcuts and some say it performs faster than the online version.

The Mockup menu for the Desktop version includes some extra commands:

New: creates a new empty mockup.

Open: Lets you select an XML file from your computer to load a mockup

Save: Saves the current mockup in an XML file.

Save As...: Same as "Save" but lets you specify a name for your mockup. Don't forget to specify XML as a file extension or you won't be able to open the mockup file again unless you manually rename it.

Export PNG snapshot: Exports the mockup to an image file on your desktop.

The BalsamiqMockups.cfg configuration file

Balsamiq for Desktop allows for some customization via a simple XML file called BalsamiqMockups.cfg. You create the file in a text editor (you can use this sample BalsamiqMockups.cfg file as a starting point) and save it in the following location:

• On Windows XP: C:\Documents and Settings\<username>\Application Data\BalsamiqMockupsForDesktop.#numbers#\Local Store
• On Mac OS X: <your user home>/Library/Preferences/BalsamiqMockupsForDesktop.#numbers#/Local Store
• On Windows Vista: C:\Users\<yourusername>\AppData\Roaming\BalsamiqMockupsForDesktop.#numbers#\Local Store
• On Linux: ~/.appdata/BalsamiqMockupsForDesktop.#numbers#/Local Store

The config file might look like this:

<config>
	<fontFace>Architect Small Block</fontFace>
	<rememberWindowSize>false</rememberWindowSize>
	<useCookies>false</useCookies>
	<documentsPath>C:\Documents And Settings\Administrator\Desktop</documentsPath>
	<snappingEnabled>false</snappingEnabled>
</config>

• the fontFace tag allows you to specify the name of a font face on your computer to use instead of Comic Sans MS
• set the rememberWindowSize tag to false if you'd like Mockups to not try to remember the size and position of the application window (some video card drivers don't play well with Adobe AIR and Mockups won't start unless you set this to false)
• set useCookies to false if you'd like Mockups to not save any of your preferences on the current computer (preferences include the state of "show UI Library", "Show Notebook" and others
• if you don't want to use the classical "My Documents" folder (often because it is on a remote server, not always connected) for the shared data of Mockups, then you can set documentsPath to the path of a folder of your choice.
• set snappingEnabled to false if you'd like to turn off snapping alltogether in the app.

back to top

 

Installing The Desktop Version on Linux

Mockups uses Adobe AIR as the underlying technology to bring web applications to the desktop. Unfortunately the linux version of AIR is still in beta, which means that you need to go through some trouble in order to install Mockups, and some of its features of Mockups won't work (nothing critical). Adobe is actively working on linux support for AIR so we can expect these inconveniences to be temporary.

Here's how to install Mockups on your linux machine. I tested on Ubuntu 7.04 but I think the instructions should apply to all modern linux distributions:

1. Install Adobe AIR: http://get.adobe.com/air/ - I had to make sure I closed Firefox before running the installer, and I had to run it as root.
2. Using Firefox, download the Mockups For Desktop .air file: MockupsForDesktop.air - you should be prompted to open the file in AIR.
3. Follow the quick installation instructions (basically say Yes, Approve, Launch whenever prompted) and Mockups for Desktop should start up automatically after installation.

If you hit a error that says "Sorry, an error occurred. The application could not be installed because the AIR file is damaged. Try obtaining a new AIR file from the application author.", it's likely due to an old AIR installation. Clean-up instructions here.

back to top

 

Command Line Options

Mockups for Desktop can be controlled via the command line with the following commands:

     Balsamiq Mockups export <inputXMLFilePath> <outputImageFilePath>

exports the provided xml file to a PNG file

     Balsamiq Mockups register <organizationName> <serialKey>

registers this Mockups copy with the provided serial key info

     Balsamiq Mockups unregister

un-registers Mockups from this computer

     Balsamiq Mockups version

prints the current version of Mockups for Desktop

     Balsamiq Mockups <file_1.bmml> <file_2.bmml> ...

opens Mockups for Desktop and loads the specified files (use absolute paths)

You only need to register your copy once per machine, then you can export PNGs from your Mockups' XML files whenever you need to.

The export process is near-instantaneous, and you should only see a quick “flashing” of the app.

The output of the application run will be in a BalsamiqMockups.log file which you can find in the following locations:

• On Windows XP: C:\Documents and Settings\<username>\Application Data\BalsamiqMockupsForDesktop.#numbers#\Local Store
• On Mac OS X: <your user home>/Library/Preferences/BalsamiqMockupsForDesktop.#numbers#/Local Store
• On Windows Vista: C:\Users\<yourusername>\AppData\Roaming\BalsamiqMockupsForDesktop.#numbers#\Local Store
• On Linux: ~/.appdata/BalsamiqMockupsForDesktop.#numbers#/Local Store

You can find some scripts to export multiple mockups using the command-line here.

back to top

 

BMML Specification

Mockups uses a flavor of XML called BMML (Balsamiq Mockups Markup Language) to save its data.

You can find a full specification of the BMML file format here.

back to top