Plandroid Help Documentation

A part definition contains a description of the basic geometry of a part and information about how it can be used. Typically, a definition will be scaled in size to represent a family of similar parts in a catalog.

Part definitions specify some default information that can be modified when used in a catalog (for example the icon to use and the connection sizes), and some information that is integral to the part and cannot be changed in the catalog (for example the part's function and connection placements and types). A definition for a part can optionally be included locally in a catalog file (with the menu item Tools -> Add Local Definitions), but if part definitions are likely to be used in more than one catalog, it is convenient to collect them together into a dedicated external definition file where it can be referred to from any catalog file that needs to use it.

Plandroid comes with a wide range of pre-defined parts, grouped broadly by use type, in a number of definition files. It would be unusual to need to create your own part definitions, and we recommend that you contact us at support to discuss the best way to proceed before you commit to creating your own definitions.

A parts definition file is marked with the symbol Definition header in the editor to differentiate it from a catalog file.

Definition Editor Layout
Definition Editor Layout

Part definition files are edited in a definition tab as shown. The definition tab contains the following panels:

The toolbar button Show Definition Details can be toggled to show additional details about each definition, including its function, number of connections, and how many times it has been used in the catalogs.

Creating New Definitions

The toolbar button Add Definition can be used to add a new part definition to the definition file you are currently editing. Or you can copy and paste an existing definition to create a new one using that part as a starting point.

The Mouse Wheel Edits Most Values

For most values in a part definition, you can use your mouse wheel to edit them when they are selected. This allows you to move a connection over an icon, for example, so you can get it into the correct position. Holding down the [Shift] key while you scroll will make the value change in large steps.

Toolbar Tools

Just as for the catalog editor, there are tools available from the toolbar which include:

Sync to Parts (sync button) - If you have edited a part definition that is used in your currently loaded catalogs, you can use this tool to synchronise your edits to the Design -> Parts catalog in Plandroid. You can then switch back to the designer to see the results of your edits directly in the design canvas.

Catalog Info (info button) - Opens a dialog for you to edit the metadata for a file. This includes the name and version number of the catalog, and the dates that the catalog is valid for.

Global Operations

Part definitions may be used by many parts across many catalog files. For this reason editing definitions must be done carefully and the catalog editor will warn you about or prevent operations that could cause problems. These operations are called Global Operations, because they may affect parts across the whole library of catalogs. Because Global Operations may have to modify files on disk that are not currently open it is not possible to undo them, so any current undo actions will be cleared. Hence it is very important to proceed carefully when performing a global operation, and we recommend that you make a backup of all your catalog files before you do so.

The Usage button label will show you how many parts are currently using the definition you are editing, and pressing the button will show you in which catalog files those parts are. Clicking on the filename will open that file in the editor and filter on that definition.

The Show Parts button will take you to any catalog files that you currently have open in the editor that are using that part definition and filter on that definition.

The following are all the different Global Operations you can do. If the definition is not used in any catalogs these operations do not count as global and so you can do them directly without any risk. That means you can safely edit any definitions that you have just created and not yet used.

Global operation should only be performed in exceptional circumstances. If you see the warning for a global operation think carefully about whether that is what you intended to do. These operations would normally only be used when a new definition is being created for a new type of part.

Editing Connections

Connections have the following properties that are shown and can be edited in the connection list panel:

The connection list supports copy and paste with the standard keyboard shortcuts ([Ctrl] + X, [Ctrl] + C, [Ctrl] + V).

Connection Categories

Categories are organised into types. Different types of categories are usually incompatible. The following connection categories are defined:

It is important to understand that the Air Inlet and Air Outlet directions are given from the point of view of the part itself. So a part which is an outlet will normally have a connection that is an Air Inlet, because that connection allows air to flow into the part from its connection, which is then dispersed into a zone.

Part Function

The part Function determines how the part behaves in Plandroid. Function values include, but may not be limited to:

In addition, the following functions specify different forms of units:

Checking Your File

Clicking on the status icon, on the right-hand side of the status bar, will report any errors that the program has found in your file. Double click on any error entry to go to the location in the file that is causing that error.

Catalog File Directory Organisation

Plandroid catalog files are all stored in a directory with the following structure:

Note that the catalog editor can only open files from within a single catalog directory at a time. This is because the definition files from the local directory must also be loaded, and this is only done once. In most cases this is not important as you will normally only have one catalog directory on your computer, but in advanced editing situations it may be necessary to close all the of the existing files if you wish to switch to editing files from a different catalog directory.