Working with Documents in Altium Designer

Parent page: Getting Familiar with the Altium Design Environment

Once a project is established design documents can be added, edited or removed from the active project. These operations can be performed within the Projects panel, which provides an organized view of the project structure and its constituent design documents. The panel's right-click context menus offer the majority of commands required for working with design documents.

Note that the presentation of documents in the Projects panel does not reflect how they are stored on the hard drive or elsewhere. The panel's contents can be considered as a logical representation of the project, whereas the physical location and organization of the document file storage (and its type) are up to you – the documents might be stored in a folder on your local machine or a LAN, and of course, hosted in a version-controlled repository provided by a basic Git/SVN VCS system or a fully managed system such an Altium Workspace.

Add or Remove a Design Document

The simplest way to add new design documents to a project is to right-click on the project name in the Projects panel and select Add New to Project from the context menu options. Alternatively, choose the required document type from the Project » Add New to Project sub-menu of the main menus to add a new document to the active project.

Add a specific or another type of document to a project.

Other types of project-relevant documents can also be added to a project, such as text files, PDFs, spreadsheets, etc. To do so, use the Add Existing to Project option (or the Project » Add Existing to Project command from the main menu of the active document's editor) and set the File Type drop-down list in the Choose Document to Add browser dialog to All Files (*.*) so all file types can be accessed.

To remove a document from the project structure, right-click on its name in the Projects panel and select the Remove from Project menu option or choose the Project » Exclude from Project command from the main menus. You will be prompted to choose:

• Delete File – to permanently remove the source document file itself.

• Exclude from Project – to remove the project's link to that document (and not delete the source document file itself). If it is currently open in the design editor window, it will be removed from its parent project but remain open in the panel as a free document. If, however, it is not currently open in the design editor window, removal will effectively close it.

  

To open an instance of Windows Explorer, at the location where a project document is stored, right-click its entry in the Projects panel and select the Explore command. For the document focused in the Projects panel, it can be done by clicking the  control at the top of the panel.

Opening a Document

To open a document, double-click it in the Projects panel or right-click its entry and select Open command from the context menu. Multiple documents may be opened simultaneously and each open document has its own tab on the Documents Bar at the top of the design window.

You can also open documents as follows:

• By choosing the File » Open command from an editor's main menus (the  button on the Quick Access Bar; shortcut: Ctrl+O). Any document that is opened this way will be opened as a free document (appearing in the relevant sub-folder of the Free Documents folder in the Projects panel) and made the active document in the main design window. Any project file that is opened will be added to the Projects panel and made the focused project.
• All documents within the focused category (sub-folder) in the Projects panel can be opened by right-clicking on the entry for the required category, then choosing the Open All command from the context menu.
• All schematic documents of the focused project can be opened by right-clicking on a Source Document folder that contains schematic documents, then selecting the Open All Schematic Documents command from the context menus.
• One or more documents, either in the currently focused project or all open projects in the active design project groups, can be opened by choosing the Project » Project Documents command from the main menus (shortcut: Alt+Ctrl+O).

  After launching the command, the Open Project Documents dialog will open. Use this dialog to select the documents that you want to open. You can restrict the view to only list documents in the project that is currently focused in the Projects panel or all projects open in the active design project groups. Use the standard Windows shortcuts (Ctrl+Click and Shift+Click) to select multiple items from the list. With the required document(s) selected, clicking OK will cause those documents to be opened.

  • All selected documents will be opened as tabbed document views in the main design window. The last document selected will be the last document opened, with its parent project becoming the active project (and also the focused project) in the Projects panel.
  • To display the current status of documents in the Projects panel, click the  button at the top of the panel, then enable the Open/modified status option within the Sorting grouping of pop-up controls. Alternatively, enable this option on the System - Projects Panel page of the Preferences dialog.

Displaying Documents

Open Versus Active Documents

When you open a document, it becomes the active document. In Altium Designer, you are allowed to have as many documents open as you wish, however, only one document can be the 'active' document. The active document is open in the design space allowing you to make any required updates. The tab of the currently active document displays with a medium gray background; documents that are open and not currently active display with a charcoal gray/black background.

Right-click on any document tab to access a drop-down of commands to close the document on which you right-clicked, close all documents of the same editor (e.g., all PcbDoc, all SchLib, or all PcbLib documents) as the one on which you right-clicked, close all open documents, split, tile or merge documents.

To make another open document the active document, click on its tab. Alternatively, use the Ctrl+Tab or Ctrl+Shift+Tab keys to cycle forward or backward (respectively) through all open documents, in accordance with the order in which they were originally opened.

The list of currently open documents is also available from most editors, at the bottom of the main Window menu (the documents are listed in the order that they were opened). Up to a maximum of nine documents can be accessed in this manner. Use a command to make the indicated, open document, the active document in the main design window.

If you have a large number of documents open, you can choose to group them by enabling the Group documents if need option in the Documents Bar options on the System - View page of the Preferences dialog. Documents can be grouped by document kind or by project. Documents grouped by document kind are sorted alphabetically in a grouped tab. Documents grouped by project are sorted alphabetically within each document kind sub-group in a grouped tab.

Document Window Management

With Altium Designer, you are not limited to viewing and working with a single design document at a time. Various commands are provided that allow you to effectively manage the open documents and tailor their display to your preferred working habits.

Right-click on a document tab to access various commands for managing the document. These commands include those affecting the display of all open documents within the main design window, as shown below. Commands for splitting the main design window vertically (Split Vertical) or horizontally (Split Horizontal) are invaluable when performing cross-document tasks, such as cross-probing between a schematic and its PCB.

When split, the regions are treated as though they are individual windows. One document may be active in each region, but only one document, across all regions, can have the focus at any given time. When a new document is added, or an existing document is opened, it will be opened as part of the region in which the currently focused document resides. The image below shows the design space split vertically; the highlighted schematic document is the currently active document.

The right-click commands also allow you to tile the documents (Tile All, shortcut: Shift+F4), which opens each document in the design space as shown in the below image. In the image, the highlighted PCB document is the currently active document.

Use the Merge All command to 'merge' all documents back into a single design window.

You can also open a document in its own separate design window by right-clicking on its tab then choosing Open In New Window from the menu or by clicking on its tab and dragging it to a point outside of the current Altium Designer window.

Altium Designer Window Management

When multiple Altium Designer windows are opened, you can use the Window » Arrange All Windows Horizontally or Window » Arrange All Windows Vertically command from the main menus to arrange all Altium Designer windows on the desktop horizontally or vertically, respectively, so that they are all visible and do not overlap. After launching the command, all Altium Designer windows that exist on the desktop and are not minimized will be tiled horizontally/vertically, allowing you to see all windows at once.

Navigating a Document

When working with a graphical document, such as a schematic sheet, PCB document, or Draftsman document, you can zoom and pan the document to focus on a specific document area. The basic shortcuts that can be used to do this are:

• Ctrl+Mouse Wheel to zoom in and out
• Right-Click, Hold&Drag to slide the document around

The View main menu includes a number of commands that can be used to control the view of the current document.

Use commands of the View main menu to control the view of your document. In the top image, the View menu of the schematic editor is shown. In the bottom image, the View menu of the PCB editor is shown.

These commands include:

• Fit Document - display the entire area of the current document.
• Fit All Objects - display all design objects on the current document.
• Area - zoom into a user-defined area of the current document.
• Around Point - redefine the display area about a specified point in the current document.
• Selected Objects - change the view in the design space, such that all selected objects are visible.
• Zoom In - bring the design closer to you, relative to the cursor position, in the current document.
• Zoom Out - move the design away from you, relative to the cursor position, in the current document.
• Zoom Last - return the display to the previous view of the screen, in the current document.

Jump to Location

Using the commands of the Edit » Jump sub-menu from the main menus of the schematic, schematic symbol, PCB or PCB footprint editor, you can jump to a specific point in the active document. For example, you can jump to:

• the document's origin coordinate (for a schematic sheet, the origin point corresponds to the bottom-left corner);
• any location within the current document, based on user-specified XY coordinates - select the Edit » Jump » New Location command to enter values for the X and Y coordinates within the design space, for the location you wish the cursor to jump to, in the Jump To Location dialog that appears;
• an object within the document. Use the following commands to jump to an object of interest:

  • a component on the schematic sheet - Edit » Jump » Jump Component. After launching the command, the Component Designator dialog will appear. Enter the component designator for the component you wish to jump to. If the designator is valid and the component exists on a schematic source document within the active project, then the relevant schematic document will be made the active document, and the target component will be zoomed and centered (where possible) within the main design window.

    When targeting a multi-part component, only enter the root designator. Do not include the part suffix. For example to jump to a 2-part IC component, whose parts are designated IC1_CPA and IC1_CPB, enter IC1_CP into the Component Designator dialog. For a multi-part component, the first part will be highlighted, with the Find Text - Jump dialog opened. Use this dialog to jump between sub-parts of the component.
    Enable the Physical option in the Component Designator dialog to confine the jump feature to only physical component designators - those appearing on the Compiled Document tabbed views of the source schematic documents, after the project has been compiled. With this option disabled, the jump feature will only consider logical designators - those appearing on the Editor tabbed views of the source schematic documents.

• a position in the current schematic or PCB document, whose coordinates have been previously stored in the indicated location marker - select the Edit » Jump » Location Marks » n command to jump to the position that has been stored in the indicated location marker using the Edit » Jump » Set Location Marks » n command.

  A stored location is only available while the document remains open (active or not). If the document is closed and opened again, the location marker will be empty.

Indicating Document Status

As you work with project documents in Altium Designer, the Projects panel provides a visual summary of which document files are modified or saved through status icons that are associated with each design document, and the main project file. This provides a quick visual summary of which documents are modified, saved, whether they are Workspace or local, and their version control status. The document icons and meanings are listed below.

Open/Modified Status Icons

 

 

 

 

 

[blank]	The document is closed.
	Open – The document is open as a tabbed document in the design editor window.
	Open/Modified – The document is open and has been modified (yet to be saved). A modified document is flagged by an asterisk suffix next to its entry in the Projects panel. A modified document also has an asterisk next to its name in its open document tab (or on the associated pop-up menu if documents are grouped).
	The document file is open and locked by this instance of Altium Designer.
	The document file is open and has been locked by another instance of Altium Designer.
	The document is being edited by another user.
	The document being edited by another user is currently open in the editor.

Version Control Status Icons

The version control system essentially monitors and compares the files in the working folder to their counterparts in the design repository. Altium Designer both requests and exchanges information with the version control system via its VCS interface, and responds to the comparative file status conditions accordingly. In practice, this manifests itself in the Projects file icons, through a range of VCS alerts, and by appropriate changes in the available file management commands.

The icons and their meaning are as follows:

[blank]	N/A	The file is not under version control in a VCS repository,
	No modification	The local copy of the file matches the file in the repository and is up to date.
	Scheduled for Addition	A file has been added to version control but not yet Committed (checked in) to the VCS repository.
	Modified	The local copy of the file has been modified and saved to the working folder. Commit the file to create a new revision in the repository.
	Out of date	The local copy of the file (in the working folder) is older than its counterpart in the repository and is therefore out of date. Use the Update or Update Whole Project command from the History & Version Control right-click menu of the Projects panel or the Projects » History & Version Control main menu to retrieve the latest file from the repository or save the file, which will create a Conflict condition.
	Conflict	The file has been committed by another user before you have committed your own edited and saved version of that file. Use the Version Control Update or Resolve command to determine which version of the file will become the latest revision in the repository.
	Ahead of server (Git)	The file in the local working repository is newer than its counterpart in the remote Git repository. This occurs when a local file has been modified, saved and committed to the local repository, but not yet Pushed to the remote repository.
	Scheduled for Deletion	The project file has been removed from version control and will be deleted from the VCS repository and database during the Version Control Commit process. This icon also appears when a file is missing from the local working folder (it has been deleted, renamed or moved), which is resolved by re-populating the folder from the repository with the History & Version Control » Update command.

Saving a Document

The currently active document can be saved locally by:

• Choosing the File » Save command, from the main menus.
• Clicking the  button on the Quick Access Bar.
• Clicking the  button on the editor's main toolbar.
• Using the Ctrl+S keyboard shortcut.

The currently focused document in the Projects panel (if the document is actually open) can also be saved by right-clicking on its entry in the panel and choosing the Save command, from the context menu.

The currently focused item (document, project, or project group) in the Projects panel can be saved by clicking the button at the top of the Projects panel. When the focused item is a project, only the project document is saved. The constituent design documents are not saved by this command. When the focused item is the design project group, only the design Project Group document is saved (*.DsnWrk). The constituent projects and their design documents are not saved by this command.

A document in a modified state can also be saved by using the corresponding command from its document tab - right-click on the tab to access a context menu of commands. Note that this command will not be available if multiple documents of the same type are open and currently grouped.

An open project document can be saved under a new name using the File » Save As command or the Save As command from the right-click menu of the document entry in the Projects panel, which creates a copy of the document file under the nominated new name. This process automatically adds (links) the new document copy to the active project in place of the existing (source) document, which remains intact in the source folder.  If the open document is not part of a project – a free document – the new copy is simply opened in the editor in place of the original document.

After launching the command, the standard Windows Save As dialog appears. Use this dialog to browse to a particular destination in which to save the file, give the file a new name (if required) and also to select the format in which to store the file (where available). The newly saved file will be opened in place of the original file as the active document.

If the intention is just to make a backup copy of a document, use the Save Copy As option. This creates a named copy of the document file without affecting its host project. After launching the command, the standard Windows Save A Copy Of dialog appears. Use this dialog to browse to a particular destination in which to save the file, give the file a new name (if required) and also to select the format in which to store the file (where available). The newly saved file will not be opened in place of the original file.

All projects and documents that have been modified can be saved by:

• Choosing the File » Save All command, from an editor's main menus.
• Clicking the  button on the Quick Access Bar.
• Right-clicking on the entry for the design project group in the Projects panel, and choosing the Save All command, from the context menu.

If the projects are part of an existing (previously saved) Project Group, and project membership has changed (projects added or removed since last save), then the Project Group document (*.DsnWrk) will also be saved.

To save all documents that are currently open within the focused category (sub-folder) in the Projects panel or descendant folders thereof, right-click on the entry for the required category (sub-folder) and choose the Save All command, from the context menu.

Managing Project Documents

Change Project Document Order

Documents in the Projects panel are automatically arranged in logical groups or 'folders', such as Source documents (Schematic, PCB, etc.), Settings documents (Harness, Outjob, etc.,) and in the case of a hierarchical design, top-level schematic documents. The documents within each folder group are displayed, by default, in the order they were added, but can be dragged and dropped to a new order position within the group.

In the case of a new hierarchical design, the parent-child relationship between documents will be displayed in the Projects panel. Note that the connectivity relationships cannot be defined by dragging and dropping schematic documents since the inter-sheet connections and design hierarchy are in fact defined by Sheet Symbols and Port definitions.

► For more information about project hierarchy, see Creating Connectivity and the Net Identifier Scope section in the Options tab of the Project Options dialog.

Document Renaming

You can directly change the name of any of PCB project constituent design files (*.PcbDoc, *.SchDoc, etc.), the PCB project itself (*.PrjPcb) or the project group (*.DsnWrk) by using the Rename command – available from the right-click context menu for a project in the Projects panel.

Examples of renaming a project and one of its design files, locally from within Altium Designer. Those changes will be synchronized with the Workspace when you save and send the changes to that Workspace.

With renaming performed, save the changes to the Workspace using the Save to Server command (available from the same context menu for the project). File rename synchronization is maintained between the local working copy of the project and its counterpart in the Workspace. Additionally, when the project file name has been renamed and the project saved to the server, the Workspace automatically changes the managed project's Name parameter to match.

Conversely, when the name of a managed project is updated through the Workspace's browser interface, the change is propagated to Altium Designer when the project is next opened.

To edit the properties of an existing managed project in the Workspace, select its entry on the Projects page, click the control above the listing of projects, and choose the Edit entry on the associated menu. Change the name for the project in the subsequent Edit Project window that appears.

When the updated project is opened in Altium Designer (File » Open Project), an initial dialog provides the option to align the local project file name with the new project Name, or force the server project Name to match the existing project file name.

Options available if you have renamed the project on the Workspace side.

Share Documents Between Projects

Because an Altium Designer project defines and saves links to stored document files, any number of projects can be created that link to those same document files.

While this may be a convenient way to re-use established design documents – say, including a standard power supply schematic in several projects – it is not recommended practice because a change in the document will affect all projects it is linked to. A far better approach for design reuse is to establish and apply Managed Sheets.

► For more information about design document reuse and Managed Sheets, see the Managed Sheets page.

Compare Local Documents with Commit or Release Data

For projects hosted by an Altium 365 Workspace, you can compare locally saved schematic and PCB documents with the data of a commit or release of this project. Commands for selecting a required data set with which the local documents should be compared can be chosen from the following locations:

• the History & Version Control » Compare right-click menu of the project or project document in the Projects panel;
• the Compare button menu in the Save to Server dialog;
• the  control menu of the Local Changes tile of the Project History view.

❯ ❮

Javascript

When the Latest Commit or Latest Release command is selected, the project data comparison with those from the latest commit/release entry will start. When the Select Commit or Release command is selected, the Project History view will open for the selected project. Select the tile of a commit or release to compare the locally saved data with the data of this commit/release.

Once complete, the comparison results are presented in the Compare view, which opens as a new tab in your default browser.

Clipboard Panel

To store and display copied objects that can be added (pasted) to Altium Designer documents at any stage, allowing for multiple copy/paste operations, the Clipboard panel can be used.

View and apply (paste) Clipboard panel content for all design data types.