SpaceClaim Add-in Style Guide

November 2014
 SpaceClaim Add-in Style Guide

Contents
Introduction ....................................................................................................................................1
Customizing the SpaceClaim UI for Add-ins ..............................................................................2
Workflow .........................................................................................................................................3
Interactive workflow steps ..................................................................................................................... 3
Auto-complete workflow steps.............................................................................................................. 4
Manual complete workflow steps ......................................................................................................... 4
Immediate action workflow steps ......................................................................................................... 5
Selection .................................................................................................................................................. 5
Preview .................................................................................................................................................... 5
Dialog launcher ....................................................................................................................................... 5
Tabs and Groups ...........................................................................................................................6
Organization ............................................................................................................................................ 6
Text labels ............................................................................................................................................... 6
Controls ..........................................................................................................................................7
Types of controls available ................................................................................................................... 7
Layout....................................................................................................................................................... 8
Tooltips..................................................................................................................................................... 8
Progress bars .......................................................................................................................................... 9
Active vs. inactive controls .................................................................................................................... 9
Other UI Elements ........................................................................................................................ 10
Options panel ........................................................................................................................................ 10
Tool guides ............................................................................................................................................ 10
Dialog boxes ......................................................................................................................................... 11
Mini-toolbar ............................................................................................................................................ 11
Cursors................................................................................................................................................... 11
Errors and warnings ............................................................................................................................. 12
Application menu .................................................................................................................................. 12
Context menu ........................................................................................................................................ 13
Icons .............................................................................................................................................. 14
Icon sizes ............................................................................................................................................... 14
File formats ............................................................................................................................................ 14
Colors ..................................................................................................................................................... 14
Common icon elements....................................................................................................................... 15
_________________________________________________________________________________________________________

www.SpaceClaim.com Page i
 SpaceClaim Add-in Style Guide

3D orientation and shading ................................................................................................................. 15

Adobe Illustrator files ........................................................................................................................... 15

_________________________________________________________________________________________________________

www.SpaceClaim.com Page ii
 SpaceClaim Add-in Style Guide

Introduction

This document contains requirements and recommendations for developing user interface
elements for SpaceClaim add-ins using the SpaceClaim API.

These guidelines should be used in addition to the 2007 Microsoft Office System User Interface
Design Guidelines, which you can find at http://msdn.microsoft.com/officeui.

_________________________________________________________________________________________________________

www.SpaceClaim.com Page 1
 SpaceClaim Add-in Style Guide

Customizing the SpaceClaim UI for Add-ins

Your SpaceClaim add-in can include:

• New tabs, groups, and controls in the Ribbon.

• Buttons to the application menu.
• Entries to the context (right-click) menu.
• Status bar text.
• Messages that are written to the message log.
• Modal or modeless pop-up forms.

_________________________________________________________________________________________________________

www.SpaceClaim.com Page 2
 SpaceClaim Add-in Style Guide

Workflow
Before you start on your add-in tool, you should consider its workflow.

There are four types of workflow:

1. Interactive (Pull, Move, sketch tools, etc.): This workflow is used when the user can
drag an object to make a change.

2. Auto-complete (Combine, Split Solid, Shell, etc.): This workflow is used when you can
determine that the operation should be applied based on the user's selection, and when
the change doesn't require dragging.

3. Manual complete (Prepare>Midsurface, Prepare>Volume, etc.): This workflow is used

when you can't determine when the user is ready to apply the operation based on their
selection, and when the command doesn't require dragging.

4. Immediate action (Fill, Plane, Axis, etc.): This workflow is used when the user selects
an object and then clicks the button. The action is applied immediately, without any user
interaction.

The type of tool you create depends on the workflow that is required for the tool. Use the
following sections to determine which type of workflow to create for your tool.

Interactive workflow steps

These tools show a preview and complete in real time. This approach should be used whenever
possible.

1. Click the tool in the Ribbon (e.g., click Pull).

2. Select the object or objects you want to work with (e.g., click on a surface that you want
to extrude). This is the primary selection.

3. (Optional) Use a tool guide or hold Alt to select secondary objects (e.g., hold Alt and
select an edge to set the pull direction). These objects usually control direction or they
anchor the operation.

4. Select options in the Options panel (e.g., click the Both Sides option to pull the surface in
both directions at once).

_________________________________________________________________________________________________________

www.SpaceClaim.com Page 3
 SpaceClaim Add-in Style Guide

5. Drag the primary selected object in the Design window to make the change (e.g., drag
the surface into a solid). The change can be seen as a preview in real time, and is
completed when you finish dragging and release the mouse button.

There are alternate workflows for using most tools, such as selecting the objects to work with
before starting the tool, but the procedure outlined above is the standard method.

Auto-complete workflow steps

If a set number of objects are required to define an operation, then you should automatically
apply the command when the required objects are selected.

1. Click the tool in the Ribbon (e.g., click Shell).

2. Select options in the Options panel (Shell doesn't have options, but this is when the user
would select them).

3. Select the objects required for the operation (e.g., select the face you want removed on
the solid you want to shell). The tool instantly applies the change when the correct
objects are selected.

Manual complete workflow steps

Use this method when you cannot determine when the user is ready to apply the command,
such as when an indeterminate number of objects need to be selected. The operation is
completed with a Complete tool guide.

1. Click the tool in the Ribbon (e.g., click Midsurface on the Prepare tab).

2. Select objects and options, and use tool guides as required (e.g., select one or more
face pairs using the Select Faces tool guide, then use the Swap Sides tool guide to
swap the sides on two face pairs). The exact order of selection is not easily predictable.

3. Click the Complete tool guide to finish the operation. The design should be temporarily
highlighted to show the change after this step whenever possible.

_________________________________________________________________________________________________________

www.SpaceClaim.com Page 4
 SpaceClaim Add-in Style Guide

Immediate action workflow steps

Use this method when the user selects one object (or optionally selects multiple objects) and
then applies a command. No options or further selection is necessary.

1. Select an object in the Design window or Structure tree (e.g., select the face of a hole in
a solid).

2. Click the tool in the Ribbon (e.g., click Fill).

3. You should only use this workflow for very simple and straightforward operations. If a
command requires the user to select multiple objects, then you should probably follow a
different workflow.

Selection
The user should be able to select objects before he or she invokes a tool.

Use the following guidelines for selection with your add-in:

• You should restrict selection so only appropriate objects can be selected for each step.

• The user should always be able to box-select.

• Always add a tool guide when a secondary (or Alt-selection) is required for a tool.

Preview
The SpaceClaim API provides facilities for rendering previews. You should provide previews
whenever a tool creates or changes geometry based on user selection or options. You can see
an example of a preview if you use the Enclosure tool on the Prepare tab.

Dialog launcher
A tool can launch a dialog box when your add-in requires more sophisticated input than can be
captured on the ribbon. For an example, see the Dimension Editor sample add-in.

_________________________________________________________________________________________________________

www.SpaceClaim.com Page 5
 SpaceClaim Add-in Style Guide

Tabs and Groups

The Ribbon is the primary menu in the 2007 Microsoft Office UI. The SpaceClaim API provides
a simple method to add tabs and controls to the Ribbon.

Groups are created by adding an entry to the Ribbon.xml file, and the SpaceClaim API creates
and positions the group for you. The following guidelines will help you create tabs and groups
that conform to Microsoft standards and blend seamlessly with the SpaceClaim UI.

Organization
According to the 2007 Microsoft Office UI guidelines, you must organize controls into groups,
even when a group only contains one control.

Groups should contain controls that are logically related. You should avoid creating a new group
for every control, and you should not put too many controls in a single group.

The buttons in the sample add-in are organized into small groups of logically related tools.

Text labels
SpaceClaim follows the Microsoft guidelines for UI capitalization:

• Use title style capitalization for the names of tabs, groups, and controls, and for the titles
of dialogs and the options panel—capitalize nouns, verbs, adjectives, adverbs,
pronouns, and the first and last words.

• Use sentence style capitalization for tooltips, elements within dialogs, and options
panels—only capitalize the first word and proper nouns.

You can find the complete guidelines in the Windows User Experience Interaction Guidelines
document at http://msdn.microsoft.com/en-us/library/aa974176.aspx.

_________________________________________________________________________________________________________

www.SpaceClaim.com Page 6
 SpaceClaim Add-in Style Guide

Controls
A control is an object on the Ribbon that the user interacts with to make something happen. It is
the equivalent of a command in older UI styles.

Like groups, controls are defined in the Ribbon.xml file, and the SpaceClaim API handles their
positioning. You have some control over the size and layout of controls.

Types of controls available

You can create the following types of controls:

• Large and small buttons

• Submenus of buttons

• Check boxes

Examples of the controls available in the API

_________________________________________________________________________________________________________

www.SpaceClaim.com Page 7
 SpaceClaim Add-in Style Guide

Layout
Use large icons unless space becomes limited. In that case, more frequently used tools should
have large icons. Use smaller icons for less frequently used tools or for tools that are related
and can be grouped together logically.

Tooltips
You should write tooltips (or hints) for controls. A tooltip is the text that pops up when you hover
over a control, an icon in the mini-toolbar, and an option in the Options panel.

• Tooltips should be written in a resources file so they can be localized.

• A tooltip should be written as one or more complete sentences that briefly explain how to
use the tool.

The tooltip for the Pull tool

DisableHint is an optional additional hint that is displayed when the control is disabled. It should
tell the user why the control is disabled and how to enable it. Some examples of this are the
Paste and Align buttons, both on the Design tab.

_________________________________________________________________________________________________________

www.SpaceClaim.com Page 8
 SpaceClaim Add-in Style Guide

The second paragraph in the tooltip for Paste is the DisableHint text.

Progress bars
You should include a progress bar and a wait cursor when the operation will take more than
about five seconds to complete.
The text labels for progress bars should include an ellipse at the end of the string. An ellipse is
made by typing three periods, like this: ...

Active vs. inactive controls

When a tool cannot be used because the necessary objects are not selected or do not exist,
then the control should be disabled. Inactive tools are gray and they can't be activated.

For example, when you open a new design that doesn't have any geometry, most of the Sketch
tools are active but the Edit tools are inactive, as shown below.

Active and inactive tools in the Ribbon

_________________________________________________________________________________________________________

www.SpaceClaim.com Page 9
 SpaceClaim Add-in Style Guide

Other UI Elements
Some tools perform an operation without any input from the user, but most will require some
user interaction. The following guidelines tell you when and how to use UI elements that are
available for your custom tools.

Options panel
You will need to create an Options panel for your tool if the user can set options.

The title of the Options panel should read, "Options - <Tool Name>". The options panel title and
group titles should be capitalized like a book title, but other labels in the panel are capitalized
like a sentence, as shown in the example below.

Options panel for the Combine tool

Tool guides
You should create a tool guide when your tool requires the user to select something in the
Design window or Structure tree.

Although SpaceClaim displays three sizes and three color schemes for tool guide icons, you
only have to make one image that is 48 x 48 pixels. The image will be resized and tinted
automatically.

The name of a tool guide is capitalized like a book title, but its tooltip is written and capitalized
as a sentence.

_________________________________________________________________________________________________________

www.SpaceClaim.com Page 10
 SpaceClaim Add-in Style Guide

Dialog boxes
You should follow the Microsoft style guidelines for dialog boxes, which can be found on MSDN
at http://msdn.microsoft.com/en-us/library/aa511268.aspx.

A dialog box title is capitalized like a book title, but other labels in the dialog are capitalized like
a sentence.

A dialog box with proper capitalization

Mini-toolbar
Icons for the mini-toolbar should be 16 x 16 pixels. The tooltips that is displayed in the mini-
toolbar is the same as the tooltip displayed for the tool in the Ribbon.

Cursors
You should change the cursor to a wait cursor when the operation is likely to take more than five
seconds to complete.

The error pop-up is displayed in the status bar message log

_________________________________________________________________________________________________________

www.SpaceClaim.com Page 11
 SpaceClaim Add-in Style Guide

Errors and warnings

Error and warning messages are displayed briefly in a pop-up bubble and are recorded in the
Message Log. An error message should be written as a short but complete sentence.

You can also set the severity (error, warning, or information), which sets the title and icon used
by the balloon.

Application menu
Icons for the application menu are 32 x 32 pixels.

The name of an application menu command is capitalized like a book title, but its tooltip is
written and capitalized as a sentence. The tooltip (or hint) is used as the pop-up tooltip as well
as the description displayed in the menu. The title at the top of a new application menu page is
capitalized like a sentence (e.g., "Create a new document" in the image below).

_________________________________________________________________________________________________________

www.SpaceClaim.com Page 12
 SpaceClaim Add-in Style Guide

Context menu
The name of a context menu command is capitalized like a book title, but its tooltip is written
and capitalized as a sentence.

_________________________________________________________________________________________________________

www.SpaceClaim.com Page 13
 SpaceClaim Add-in Style Guide

Icons
You should follow the guidelines in this section when you create icons for your add-in.

SpaceClaim provides Adobe Illustrator files with common icon elements for you to use in your
own icons. These templates also include lines that will help you orient 3-dimensional icons to
the correct angles.

Icon sizes
You can use three sizes of icons in your add-in. The size of the icon you should create depends
on where the icon will be used:

• 32 x 32 pixel images are used for large buttons that are not vertically stacked.

• 24 x 24 pixel images are used where two commands are vertically stacked.

• 16 x 16 pixel images are used where three commands are vertically stacked and in the
Options panel when an option does not have a checkbox.

• 48 x 48 pixel images are used for tool guides.

File formats
Icons must be saved as JPG or PNG images for use in the add-in. PNGs with transparency are
preferred.

Colors
The color of elements within an icon have the following meanings:

• Green elements indicate that the tool creates something.

• Red elements indicate that the tool deletes or removes something.

General icon color meanings in SpaceClaim:

• View-related tools are usually blue.

• Tool guides for secondary (Alt) selection are usually blue.

Two-dimensional icons, like the File Save icon, are shaded so they don't look flat when used
beside 3D icons.

_________________________________________________________________________________________________________

www.SpaceClaim.com Page 14
 SpaceClaim Add-in Style Guide

Common icon elements

Several icons in SpaceClaim use the following graphical devices:

An asterisk (*) is used in an icon when the tool creates a new relationship or
performs automatic inferencing. Notice that the asterisk looks more diamond
shaped in the 16 x 16 version.
A green plus (+) is used when the tool creates a new object.

A red X is used in the icon when the tool deletes or removes something.

These elements are included in the Adobe Illustrator files.

3D orientation and shading

Icons that appear three-dimensional are made with the same shade on the left front side and
top (A), and a slightly darker shade on the right front side (B).

Adobe Illustrator files

Use the Adobe Illustrator files at the following link to make your own icons.
http://files.spaceclaim.com/Api/doc/StyleGuideIcons.zip

_________________________________________________________________________________________________________

www.SpaceClaim.com Page 15
© Copyright 2012 SpaceClaim Corporation. SpaceClaim and the SpaceClaim logo are trademarks of SpaceClaim Corporation. All other names mentioned herein are either
trademarks or registered trademarks of their respective owners.