# Get Started with Gaphor Gaphor is more than a diagram editor: it's a modeling environment. Where simple diagram editors such as Microsoft Visio and [draw.io](https://draw.io) allow you to create pictures, Gaphor actually keeps track of the elements you add to the model. In Gaphor you can create diagrams to track and visualize different aspects of the system you're developing. Enough talk, let's get started. You can find installers for Gaphor on the [Gaphor Website](https://gaphor.org/download). Gaphor can be installed on Linux (Flatpak), Windows, and macOS. Once Gaphor is launched, it provides you a welcome screen. It shows you previously opened models and model templates. ![Gaphor's welcome screen showing recently opened models and model templates.](images/getting-started-greeter.png) You can select a template to get started. - **Generic:** a blank model to start with - **UML:** A template for the *Unified Modeling Language* for modeling a software system - **SysML:** A template for the *Systems Modeling Language* for modeling a wide range of systems and systems-of-systems - **RAAML:** A template for the *Risk Analysis and Assessment Modeling language* for safety and reliability analysis - **C4 Model:** A template for *Context, Containers, Components, and Code* which is for lean modeling of software architecture Once the model interface is loaded you'll see the modeling interface. ![The Gaphor main window, with numbers refering to parts of the UI.](images/getting-started-new-model.png) The layout of the Gaphor interface is divided into four sections, namely: 1. Model Browser 2. Diagram Element Toolbox 3. Diagrams 4. Property Editor Each section has its own specific function. ## Model Browser The Model Browser section of the interface displays a hierarchical view of your model. Every model element you create will be inserted into the Model Browser. This view acts as a tree where you can expand and collapse different elements of your model. This provides an easy way to view the elements of your model from an elided perspective. That is, you can collapse those model elements that are irrelevant to the task at hand. In the figure above, you will see that there are two elements in the Model Browser. The root element, _New Model_ is a package. Notice the small arrow beside _New Model_ that is pointing downward. This indicates that the element is expanded. You will also notice the two sub-elements are slightly indented in relation to _New Model_. The _main_ element is a diagram. In the Model Browser view, you can also right-click the model elements to get a context menu. This context menu allows you to find out in which diagram model elements are shown, add new diagrams and packages, and delete an element. Double-clicking on a diagram element will show it in the Diagram section. Elements such as classes and packages can be dragged from the tree view on the diagrams. ## Toolbox The toolbox is used to add new items to a diagram. Select the element you want to add by clicking on it. When you click on the diagram, the selected element is created. The arrow is selected again, so the element can be manipulated. Tools can be selected by simply left-clicking on them. By default, the pointer tool is selected after every item placement. This can be changed by disabling the "Reset tool" option in the Preferences window. Tools can also be selected by keyboard shortcuts. The keyboard shortcut can be displayed as a tooltip by hovering over the tool button in the toolbox. Finally, it is also possible to drag elements on the Diagram from the toolbox. ## Diagrams The diagram section contains diagrams of the model and takes up the most space in the UI because it is where most of the modeling is done. Diagrams consist of items placed on the diagram. There are two main types of items: 1. Elements 2. Relationships Multiple diagrams can be opened at once: they are shown in tabs. Tabs can be closed by pressing Ctrl+w or left-clicking on the x in the diagram tab. ### Elements Elements are the shapes that you add to a diagram, and together with Relations, allow you to build up a model. To resize an element on the diagram, left-click on the element to select it and then drag the resize handles that appear at each corner. To move an element on the diagram, drag the element where you want to place it by pressing and holding the left mouse button, and moving the mouse before releasing the button. ### Relations Relations are line-like items that form relationships between elements in the diagram. Each end of a relation is in one of two states: 1. Connected to an element and the handle turns red 2. Disconnected from an element and the handle turns green If both ends of a relation are disconnected, the relation can be moved by left-clicking and dragging it. A new segment in a relation can be added by left-clicking on the relation to select it and then by hovering your mouse over it. A green handle will appear in the middle of the line segments that exist. Drag the handle to add another segment. For example, when you first create a new relation, it will have only one segment. If you drag the segment handle, then it will now have two segments with the knee of the two segments where the handle was. ### Copy and Paste As stated before, Gaphor is a modeling environment. This means that every _item_ in a diagram is backed by a _model element_ found in the model browser. This means that you can show the same _model element_ in different diagrams. * Ctrl+v is used to paste _only_ the presentation element. * Ctrl+Shift+v is used to paste a new presentation with a new model element. ```{important} Ctrl+v does a "shallow" paste. Ctrl+Shift+v does a "deep" paste. ``` ### Undo and Redo Undo a change press Ctrl+z or left-click on the back arrow at the top of the Property Editor. To re-do a change, hit Ctrl+Shift+z or press the forward arrow at the top of the Property Editor. ## Property Editor The Property Editor is present on the right side of the diagrams. When no item is selected in the diagram, it shows you some tips and tricks. When an item is selected on the diagram, it contains the item details like name, attributes and stereotypes. It can be opened with F9 and the ![Icon for showing and hiding the Property Editor.](images/sidebar-show-right-symbolic.svg) icon in the header bar. The properties that are shown depend on the item that is selected. ## Model Preferences The Property Editor also contains model preferences: Click the ![Document with wrench icon for model specific configuration.](images/document-properties-symbolic.svg) button. ### Reset Tool Automatically By default, the pointer tool is selected after an element is placed from the toolbox. If this option is turned off, the same type of element will be placed by clicking in the diagram until another element is selected in the toolbox. ### Remove Unused Elements By default, elements that are not part of any diagram in the model will be removed. If this option is turned off, elements remain in the model and may be found in the model browser. ### Diagram Language The diagram language modifier is only applicable to the loaded model and how it is shown in the diagram. The diagram language setting is saved as part of the model and defaults to English. The UI language of Gaphor is controlled by the operating system. ```{note} Gaphor considers the ``LANG`` environment variable on Linux, Windows and macOS. On Windows and macOS it can be set independently of the operating system's language settings to a different language. ``` ### Style Sheet The [style sheet](style_sheets) allows to change the visual appearance of diagrams and model elements.