Using libraries¶

The eight libraries that come with the app, and the Complex Shapes, Database and Notes and Cards sections, are described in Shapes. This page is about managing the list — hiding what you don't use, reordering it, and adding libraries from elsewhere.

Manage Libraries¶

Click the books icon at the top of the Library panel. You get a menu with:

• New Library…
• Import Library…
• Manage Libraries…
• Search Online Libraries ↗ — opens the shape-library page on simplediagrams.com in your web browser

…plus Edit, Duplicate, Export and Remove submenus once you have libraries of your own.

Manage Libraries… opens a sheet listing every library with a checkbox and a drag handle. Untick a library to take it out of the panel; drag to change the order shapes appear in. Each one is marked Built-in, Downloaded (from simplediagrams.com or a file someone sent you) or Custom (one you made, which only you can change) so you know what you're looking at.

Built-in libraries can be hidden but not removed — they're part of the app.

The library heading menu¶

Each library in the panel has its own small books icon at the right of its heading. Click it for a menu that names the library at the top, then offers:

• Edit Library…
• Hide Library — takes it out of the panel straight away. Bring it back with the checkbox in Manage Libraries….
• Duplicate Library…
• Export Library…
• Remove Library…

Built-in libraries only offer Edit and Hide. Permanently deleting a library isn't in this menu — do that from Manage Libraries…, where you can see everything you're about to lose.

Adding a library¶

Three ways:

• Import Library… from the books menu.
• Double-click a library file in the Finder.
• Drag a library file anywhere in a SimpleDiagrams document window.

While you drag, a message over the window says what dropping will do: Import Library, Import Visio Stencil, or Open Visio Drawing for a Visio diagram, which opens as a new document rather than a library. Drag in one of Visio's older files and the message says it can't be used. Drop it anyway and you're told how to get a copy that works. A file that's too large, or isn't really a library, is turned down straight away.

These file types work:

• .sdlibrary — the native SimpleDiagrams 5 library package.
• .sdlp — the legacy library plugin format from version 3 and 4.
• .vssx and .vssm — a Microsoft Visio stencil, with or without macros. Its shapes become a library of your own. See Visio drawings and stencils.

About legacy .sdlp libraries¶

Your old library plugins still work. When you import one, every SVG inside is compiled into the app's native vector format — you'll see an Importing Library… progress bar while it works, and a confirmation when it's done.

It's all or nothing: if any single shape can't be converted, the whole import stops rather than quietly giving you a library with holes in it.

Limits, in case you have something enormous: 10,000 items, 16 MB per shape, 100 MB total, and bitmap images of up to 4,096 × 4,096 pixels, about 64 full-size ones per library.

Updating a library you already have¶

Import a library you've already got, such as a newer copy of one you downloaded or a Visio stencil you imported before, and the app asks Update “name”? rather than adding a second copy.

The sheet says what will happen, in plain words. The library's shapes will be replaced with the ones in the file, and it tells you how many of each. If the file gives the library a new name, it says that too. Shapes you've already placed in diagrams keep their look, because every diagram carries its own copy of its shapes. The library's current shapes aren't kept, so if you might want them back, export the library before you click Update.

Libraries that carry information¶

Some libraries come with fields already set up on their shapes. For example, every plant in the Green Walls library knows its botanical name and growth habit, and has a Unit cost for you to fill in and a Quantity that starts at 1. Place a shape and its fields appear in the Shape Data panel. Choose Window ▸ Panels ▸ Page Data ▸ Show (Option+Cmd+8) to see the whole page as a table, and export it as CSV for a plant schedule or a quote.

Values the library supplies as facts, like a botanical name, are dimmed and can't be edited. The others are yours to change on each placed shape.

You can add fields of your own to any library, too. Shape data covers fields, the data panels, syncing and export.

These libraries need SimpleDiagrams 5.0.5 or later. An older version tells you to update when you try to import one.

Choosing your own starting colours¶

Some libraries let you choose the colours their shapes start with. Green Walls does: each plant starts in its foliage colour, but if you'd rather your ferns start in a darker green, you can make that stick.

1. Choose Edit Library… from the library's heading menu.
2. Select the shape, then open the Appearance tab.
3. Change the fill, line colour or line width under Default Appearance. The preview beside the controls shows the shape as you go.
4. Click Save.

Only new placements use your colours. Shapes already in your diagrams keep theirs, and you can always recolour any placed shape directly. Library Setting puts back the library's own colours and line width. Library updates never overwrite your choice.

In libraries that don't allow this, Default Appearance is dimmed. Use Duplicate Library… to make your own copy if you want full control.

Changing a built-in or downloaded library¶

There are three kinds of library. Built-in libraries come with the app. Downloaded libraries come from simplediagrams.com. Custom libraries are the ones you make with New Library… or import, and they're the only kind you can change freely. Edit Library… opens all three in the same window; controls you can't change are dimmed, and hovering over one says why.

A downloaded library may also let you choose starting colours, as described above.

Changes "on this Mac" are kept beside the library and used for new shapes. The library itself is not changed, so it can still be updated, and exporting it does not include them. Shapes already in a diagram keep their points and text region until you sync them.

Word Bubbles and 3D Basic (Hatch) use text areas chosen for their drawings where the shapes provide them. A new label starts and wraps inside that area; you can still drag it afterwards. Updating the app leaves labels in saved diagrams where you put them. Applying the library's connection points and text position during a sync also applies its text area, which can move an existing label.

On Connection Points or Text Region, Library Setting puts back the library's own. If a library update or an app update changes a shape's artwork after you moved its points, the tab says so. Check the points, then choose Keep My Points or Library Setting. Nothing is discarded until you choose.

The editing itself works as it does in your own libraries. To change anything else, use Duplicate Library… to make your own version.

Initial colours¶

Every library has one setting that's entirely yours: which colours its shapes start with when you place them.

1. Choose Edit Library… from the library's heading menu.
2. Select Library Settings at the top of the list.
3. Under When a shape from this library is placed on the canvas..., set Initial colors.
4. Click Save.

You rarely need to touch it. Left to decide, the Basic shapes follow your colours and the Azure icons stay Azure blue. Change it when you want, say, every Azure icon in your brand colour.

This works for every library — the ones built in, the ones you've installed and the ones you've made — and a library can't lock it. It's kept on your Mac, so it doesn't travel with a library you export. Only new placements are affected.

Whichever you choose, holding Alt while you drag a shape out of the library gives you the other result for that one shape.

Removing a library¶

Choose Remove Library… from the library's heading menu, or use Remove Library from the books menu. You'll be asked to confirm.

Removing a library deletes it from this Mac, along with any personal changes you made to its shapes. Diagrams that already use those shapes keep working, because their artwork is embedded in the document. If you just want the library out of the way, hide it in Manage Libraries instead. To keep a copy before removing, use Export Library.

A library always holds just its current contents: saving your edits, or installing an update, replaces it. SimpleDiagrams doesn't keep older versions.

Exporting and sharing a library¶

Export Library writes a .sdlibrary package you can send to someone else, put in a shared folder, or keep as a backup.

Duplicate Library… makes an editable custom copy on this Mac, named “(custom copy)”. It works for any library, including downloaded ones, and you can edit the copy like any custom library.

Where libraries live on disk¶

Inside the app's sandbox container:

~/Library/Containers/com.simplediagrams.desktop/Data/Library/
    Application Support/SimpleDiagrams/Custom Libraries/

You don't normally need to go in there — but if you're backing things up or moving to a new Mac, that's the folder.