Using libraries¶

The six built-in libraries 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 or Imported 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.

Two file types work:

• .sdlibrary — the native SimpleDiagrams 5 library package.
• .sdlp — the legacy library plugin format from version 3 and 4.

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.

Updating a library you already have¶

Import a package with the same identity as one you've already got and the app asks Update ? rather than creating a duplicate.

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 library you didn't make¶

There are three kinds of library. Packaged libraries come with the app. Installed libraries are ones you downloaded. The rest are yours, created in the app. Edit Library… opens all three in the same window; controls you can't change are dimmed, and hovering over one says why.

An installed 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.

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 your own editable copy on this Mac, named “(user copy)”. It works for any library you've added, including ones you downloaded, and you can edit the copy exactly like a library you made yourself.

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.