Your own libraries¶

This is the part of the app for people who want to twist SimpleDiagrams to their own machinations. If that's you, read on. If not, you can safely skip this page forever.

SimpleDiagrams calls these custom libraries, and that's the name you'll see in the app. They sit beside the built-in libraries that come with SimpleDiagrams and the downloaded libraries you install from simplediagrams.com or from a file someone sends you. A custom library is the only kind you can change; to change a downloaded one, make your own copy with Duplicate Library….

Making a library¶

Click the books icon at the top of the Library panel and choose New Library…. You get the Edit Library sheet on Library Settings. The Library Name field is ready for you to replace the suggested name.

Type the name, then start adding artwork.

Adding artwork¶

Add Artwork… accepts SVG files, ordinary images (PNG, JPEG), and native SimpleDiagrams vectors. Up to 32 files at a time. You can also just drag files into the sheet. An empty library shows a drop hint in the Shapes sidebar while Library Settings is open.

Each SVG asks the same question as dropping one on the canvas: Keep as SVG Artwork or Convert to Editable Shape. See Importing artwork for what each one means. When you add several SVGs at once, tick Use this choice for the other SVG files to answer once for the lot. An SVG that can't be converted still asks, so you can keep it as artwork, and so does one that can't be kept as artwork because of a fill too slow to draw. Cancel adds nothing from that batch.

Select a shape in the library window. Details shows its name, slug, artwork type, keywords, description, default label, default text position and size. Appearance holds its starting colours and line style. The editor shows:

Per-shape actions live in the ⋯ (Shape Actions) menu below the Shapes list: Copy Shape, Paste Shape, Replace Artwork… and Delete Shape. You can also right-click (or Control-click) a shape in the list for the same commands, press Del to delete the selected shape, and use Cmd+C and Cmd+V to copy and paste shapes while the list is selected.

To remove a shape, select it and press Del (or choose Delete Shape), then Save. Until you save, Cancel brings it back. Shapes in a library you downloaded can be copied but not deleted or replaced; use Duplicate Library… to make your own copy.

Appearance¶

Select a shape's Appearance tab. Turn on Custom Default Paint to choose how the shape starts out. Pick a Stroke and Fill colour with the chip, or type a hex value such as #4E97D2 in the field beside it. Line Width takes a number from 0 to 100. The two texture menus add a pattern to the line or the fill. The preview on the right shows the shape with your choices as you make them.

These are only starting values. Every placed shape can still be recoloured on the canvas, and changing them here doesn't recolour shapes already in your diagrams.

Connection points¶

This is the bit that turns a picture into a proper diagram shape.

The Connection Points tab lets you place the spots where connectors will attach. Drag a point to move it. Double-click the picture to add one where you clicked, or click Add Point to put one in the middle. Shift-click a point to remove it, as you would on a connector; while you hold Shift, each point shows a red ✕ to warn you. Delete Point also appears beside Add Point while a point is selected. Default Points goes back to the standard ring around the edge.

Custom points are saved in the .sdlibrary package and copied into each new shape you place. You can define up to 128 points per shape. Editing a placed shape's points changes only that instance, leaving these library defaults unchanged. See Changing a shape's connection points for the canvas editing workflow and its Undo behavior.

Standard points are fine for a box. For anything with a distinct shape — a cylinder, a person, an arrow — putting the points where the artwork actually has edges makes a real difference.

Text region¶

On the Text Region tab, turn on Custom Text Region to choose where typed text sits inside the shape. Drag a corner of the outlined area to resize it, or drag inside it to move it. Turn it off to go back to the standard position.

You can also type the area's position and size instead of dragging. The X, Y, Width and Height fields below the shape take percentages of its size: X is how far the area starts from the shape's left edge, and Y from its top edge. The area always stays inside the shape and is never smaller than 5% across or down, so a number that goes past either limit stops there, and the field shows the value it stopped at. Press Tab to move between the fields.

Only shapes with editable vector artwork can hold text. Other artwork shows a short message instead.

Turning a drawing into a library shape¶

You don't have to start in the Edit Library sheet. Draw something on the canvas with the Polyshape tool, select it, right-click, and choose Add to Library….

Give it an Item Name, pick which Library it goes in, and click Add.

This only works for a single selected closed path — the app needs a shape, not a sketch.

Editing a library later¶

Click the books icon on the library's heading and choose Edit Library…, or use books menu ▸ Edit Library ▸ pick the library. Same sheet, same controls. Nothing is saved until you click Save.

Slugs¶

Every shape in a library has a slug: a short, permanent name such as big-pump. Your diagrams keep it, and other programs can use it to name the shape, so it stays put when you rename the shape.

You don't have to think about slugs. A new shape gets one from its name when you save the library. If you'd like a better one (say the shape started life as “Untitled Shape”), select the shape and change Slug on its Details tab. Lower-case letters, digits and single hyphens only.

A slug you give up is retired, and no other shape in that library can take it. That way a script that named your old pump never ends up pointing at your new valve.

Libraries you installed from someone else show their slugs, where they have them, but only their creator can change them. Libraries from the website have them too, even ones you installed before slugs existed.

Duplicating, exporting, sharing¶

From the library's heading menu (Duplicate and Export) or the books menu:

• Duplicate Library… — an editable custom copy, named “(custom copy)”.
• Export Library — writes a .sdlibrary package to send to someone.

See Using libraries for importing on the other end.

Inspecting what you've got¶

Select a single shape on the canvas and choose Edit ▸ Repair Selected Artwork… to see its size, ID, format and licence facts. If something's gone missing or is only an approximation, that dialog also offers Replace Artwork….

Limits¶

If you're anywhere near these, I'd genuinely like to hear what you're building.