The Projects panel displays all projects that are currently open, along with their constituent documents contained therein. Any open documents that have not been created as part of a project or added to an existing open project will also be listed.
Content and Use
As you open an existing project or create a new one, an entry for it will appear in the Projects panel. Any existing documents that are part of a project and any new ones that have be added will appear under sub-folders, according to their purpose and/or type. For example, the following common folders and content document types can appear under a project:
- Source Documents - core design documents (e.g. schematics, PCBs, HDL files, embedded source code documents, source script documents, CAM documents, etc)
- Settings - documents that are used to store design options or preferences used in document generation. Documents are further sub-divided based on type (e.g. database link files, output job files, constraint files, etc)
- Libraries - source library documents for a project. Documents are further sub-divided based on library type (e.g. schematic libraries, PCB libraries, VHDL libraries, etc)
- Generated - documents generated as output. Documents are further sub-divided based on type (e.g. CAM documents, VHDL documents, Waveform documents, Text documents, etc). As project output is generated, the corresponding sub-folders in the main tree will be created and become populated.
Any documents that are opened independently of a project will appear as Free Documents. Again, depending on the document type, free documents will appear under corresponding sub-folders.
As well as allowing multiple documents to be open for editing, the environment also supports multiple projects being open at the same time. These could be unrelated projects, or they could be related projects. In the figure there are three related projects – a PCB project which includes an FPGA on it, the project for that FPGA which includes a soft-core processor, and an embedded project for the software that runs on the soft-core processor inside the FPGA.
Displaying the Projects Panel
If the Projects panel is not currently visible, you can open it by clicking the System button at the bottom right of the workspace, and selecting Projects from the menu that appears, as shown below.
The top field in the panel reflects the currently open design workspace (*.DsnWrk). As you open projects, they are not automatically part of a design workspace. By default, the field will list the name (Workspace1.DsnWrk) that would be used if you wish to save the open projects as a design workspace. This name can, of course, be changed at save time.
Opening a saved design workspace would load the given name for that workspace into this field. Use the Workspace button to the right of the field to access a menu of commands associated with design workspaces, such as adding new or existing projects to the workspace, opening all documents for all projects in the workspace, compiling all projects in the workspace and saving.
Active vs Focused
The second field from the top of the panel reflects the currently active project. In the main tree, the active project is highlighted using the Windows Active Title Bar color for your system.
When there are no documents open in the design editor window, the field becomes a drop-down, allowing you to select the active project from a list of all currently open projects in the panel. As soon as a project document is opened, the parent project of that document automatically becomes the active project. In this case, the field reverts to a non-drop-down, informational field, displaying the name of that project.
The active document in the design editor window will also be highlighted in the panel, using the Windows Selected Items color for your system.
With numerous documents open in the design editor window, changing the active document using document tabs will cause the Projects panel to update accordingly, to reflect both the active document and the active project (if the document you make active does not reside in the same project as the previously active document). Conversely, clicking on the entry for a document that is already open (and which belongs to a non-active project) will make the parent project of that document the active project.
Only one project and document may be active at any given time, however the panel allows you to focus and perform actions on any project or document. Right-clicking on the entry for a non-active project or a non-active document, will bring up a menu with commands targeting that focused project or focused document, respectively.
Alternatively, click on the required project or document entry, to focus it, and use the Project button to the right of the active project display field to access a menu of commands available specifically for the focused project or document. In the case of focusing a document, the document will only become focused if it is closed or hidden, otherwise it will become the active document and its parent project will become the active project. For example, in the image below the active project is Mixer.PrjPcb and the active document is Auxiliary.SchDoc. The focused document is 4 Port UART and Line Drivers.SchDoc (distinguished in the panel by a dotted outline box). Pressing the Project button pops-up a menu with commands targeting this focused document.
To compile all open projects currently listed in the panel, click on the button.
Using the Panel's Structure Editor
For the most part, the Projects panel would typically be configured in File View mode (File View option enabled on the panel). Indeed, this is the default configuration for the panel. However when the structure of a design incorporates different sub-projects, for example an FPGA project linked to a PCB project and an embedded software project linked to a processor core in the FPGA design project, there needs to be some visual way of quickly interrogating/controlling the overall design hierarchy/structure. This is achieved by placing the panel in Structure Editor mode (by enabling the Structure Editor option on the panel).
The hierarchical structure within projects will be reflected in the panel. The entries that appear in this view can include documents, sheet symbols and Nexus components. Any or all of these can be included in the view by enabling the appropriate Structure View options (see next section).
Note: The option to display Nexus components is enabled by default, as it is required to be able to set up the structure.
The lower region of the Projects panel, when configured in this mode, contains all the valid sub-projects that are open in the workspace. This includes FPGA, Embedded and Core projects. For FPGA projects, their defined configurations will also be listed along with constraint files associated to each.
Within this region of the panel, constraint files can be moved from one configuration to another by performing a drag-and-drop. The constraint file will be disassociated from the source configuration and newly associated to the target configuration. To copy a constraint file to another configuration, hold down the CTRL key whilst performing the drag-and-drop.
To purely disassociate a constraint file from a configuration, drag the entry for the constraint into free space within the lower region of the panel.
Double-clicking on a configuration entry will launch the Configuration Manager dialog for the parent FPGA project.
Linking of FPGA and PCB projects can be carried out directly from within the panel and is achieved in one of the following ways:
- Dragging a configuration defined for the FPGA project from the lower region of the Projects panel and dropping it onto the entry for the FPGA component in the PCB project
- Dragging the FPGA project - from either the upper or lower regions of the panel - and dropping it onto the FPGA component entry in the PCB project
- Right-clicking on the entry for the FPGA component in the PCB project and choosing the Set Sub Project command from the pop-up menu that appears. This will open the Select Sub Project dialog, from where you can browse to and open the desired FPGA sub-project. This method is particularly useful if the desired sub-project is not currently open in the Projects panel.
In the first two cases, as you start to drag, the possible FPGA component entries (that reside on a schematic sheet(s) within one or more PCB projects) that you can validly drop onto are highlighted in pale blue. As the cursor passes onto a valid 'drop zone' it will change from a no-entry symbol to a document symbol.
If you choose to drag the entire FPGA project entry onto the target schematic FPGA component and more than one valid configuration exists for that project - i.e. more than one configuration contains an associated constraint file targeting the FPGA device - the Select Configuration dialog will appear from where you can choose which specific configuration to use.
When the required configuration has been assigned, the parent FPGA project will become linked to the PCB project and is shown in the structure hierarchy as a sub-design of the schematic FPGA component.
To break the link between the two projects, click and drag the FPGA project entry into free space within the panel (below the last entry).
Panel Display Options
Various display options can be defined with respect to the panel. The default display mode is to show project documents grouped into separate display folders, such as Source Documents, Libraries, Settings, and so on.
To access your display options to customize the way your Projects Panel looks, click on the drop-down arrow to the right of the panel's compile button.
These options are configured in the Projects Panel page in the System section of the Altium Designer Environment Preferences dialog (DXP menu). A quick way to access these Project panel settings is to click the button at the top of the panel.
The various display options are divided into the following seven categories. Click on the entry for a category and enable/disable the available options as required.
- General - provides options including iconic display of document open/modified and Version Control status
- File View - provides options to display Project and/or document structure when the panel is configured in File View mode
- Structure View - provides options to define which objects are displayed when the panel is configured in Structure Editor mode (Documents and/or Sheet Symbols and/or Nexus Components)
- Sorting - provides various options to control how documents in the panel are sorted (e.g. by project order, alphabetically, by open/modified status) and whether sorting is ascending or descending
- Grouping - provides options to determine how documents are grouped - either by class or by document type or no grouping at all
- Default Expansion - provides options to control the level of folder expansion applied by default
- Single Click - configure what happens when you click once over a document entry in the panel (do nothing, make the open document active, or open document and make active).
All panel display options can also be defined on the System - Projects Panel page of the Preferences dialog. Use the dialog's 'What's This Help' feature to obtain detailed information about each of the options available. Click on the question mark button at the top right of the dialog and then click over an option to pop-up information specific to that option.
Iconic Status Display
As part of the General panel options (previous section), you can enable the iconic display of document open/modified and Version Control status. This provides a quick visual summary, allowing you to see which documents are modified, which are hidden and, in the case of version control, which documents are checked in or out. The icons used are listed for ease of reference below. The entry in brackets shows the textual confirmation that appears when hovering the cursor over the icon.
Open/Modified Status Icons
the document is open as a tabbed document in the design editor window
the document is hidden
the document is open and has been modified (yet to be saved)
this icon appears next to the main project document only, to show that the project has been modified (yet to be saved)
A closed document is represented by no icon.
Version Control Status Icons
If the Show VCS Status is enabled then the current VCS status of each file that is under version control is displayed next to the file's name in the Projects panel. The status is dependent on which VCS method you are using, and it can be one of the following:
- [blank] Version control disabled - file has not been added to the VCS.
- [blank] Not in version control - -i.e. has not been added to the VCS.
- No modification- The file is checked in to the repository, and your local copy is up to date. Depending on the provider, your local copy may be marked read-only so that it cannot be modified until you Check Out.
- Out of date- The file is checked in to the repository, but your local copy is out of date. Use Get Latest Version to update your local copy.
- Checked out exclusively by me - You have checked out the file exclusively, but there are no changes to check in. Use Undo Check Out when you are finished with the file and want to allow other people to check it out.
- Modified exclusively by me - You have checked out the file exclusively and modified it. Use Check In to check your changes into the repository or Undo Check Out to discard them.
- Locked exclusively - Someone else has checked out the file exclusively. You cannot check out the file until he or she selects Undo Check Out. Depending on the provider, your local copy may be marked read-only so that it cannot be modified.
- Locked exclusively by me - You have somehow managed to check out the file exclusively somewhere else (perhaps in another directory). Refer to the documentation for your Source Code Control plug-in on how to remove the lock.
CVS and Subversion
- [blank] Version control disabled - file has not been added to the VCS.
- [blank] Not in version control - -i.e. has not been added to the VCS.
- No modification - The file is checked in to the repository, and your local copy is up to date. Depending on the provider, your local copy may be marked read-only so that it cannot be modified until you Check Out.
- Out of date - The file is checked in to the repository, but your local copy is out of date. Use Get Latest Version to update your local copy.
- Modified - the checked out file is locally modified by you. Save the file and check in / commit the file to the repository.
- Conflict - the file has been committed by some one else before you had a chance to commit this file.
- Missing - the file is present in the repository but not in your working folder. Use Restore menu item from the menu item by right clicking on the Storage Manager panel to obtain a copy from the repository in your working folder.
You can right click and select Refresh Status to refresh the current VCS status of each file on the Projects panel. A document that is not in the version control database is represented by no icon.
Accessing the FPGA Workspace Map
Clicking on the button gives you access to the FPGA Workspace Map dialog.
This dialog gives you the ability to check the state of a design across linked FPGA and PCB projects and the means to propagate design changes between the two.
For detailed information with respect to linking FPGA and PCB projects and maintaining synchronicity using the FPGA Workspace Map dialog, refer to the Application Note, Linking an FPGA Project to a PCB Project, which can be found in the FPGA Hardware Design area of the Altium Designer Documentation Library.
- With no project documents open in the design editor window, opening an additional project will automatically make it the active project in the panel.
- A free document can be added into a project. Conversely, a project document can be removed from that project. If it is 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.
- A modified document, project or design workspace that has yet to be saved is also distinguished by an asterisk next to its entry in the panel. Modified documents are also indicated by an asterisk inside their tab in the design editor window.
- The panel supports drag and drop, meaning that you can open a project (add it to the panel) or an individual document, by dragging it from Windows Explorer and dropping it onto the panel.
- You can transfer documents between projects in the panel by clicking and dragging. You do not have to drag the document to the correct sub-folder, it will be placed correctly within the project structure automatically.
- Documents are hidden in order to prevent clutter in the tabbed area of the design editor window. When a document is hidden, it is still open from the point of view of processes such as compilation/synchronization/annotation, It is just not displayed as a tabbed-document in the design editor window. All hidden documents can be accessed by clicking on the drop-down button at the far right of the Document bar (containing all individual tabbed views).
- The keyboard shortcuts Up Arrow, HOME, END and Down Arrow, can be used to display the previous, first, last and next entry in the panel, respectively. Use the Right Arrow and Left Arrow keys to expand and collapse a top-level entry or sub-folder therein, respectively.