From bd9e6617827818fd043452c08c606f07b78014a0 Mon Sep 17 00:00:00 2001 From: toma Date: Wed, 25 Nov 2009 17:56:58 +0000 Subject: Copy the KDE 3.5 branch to branches/trinity for new KDE 3.5 features. BUG:215923 git-svn-id: svn://anonsvn.kde.org/home/kde/branches/trinity/kdesdk@1054174 283d02a7-25f6-0310-bc7c-ecb5cbfe19da --- doc/umbrello/Makefile.am | 2 + doc/umbrello/activity-diagram.png | Bin 0 -> 62231 bytes doc/umbrello/add-remove-languages.png | Bin 0 -> 41025 bytes doc/umbrello/aggregation.png | Bin 0 -> 1502 bytes doc/umbrello/association.png | Bin 0 -> 2102 bytes doc/umbrello/authors.docbook | 41 ++ doc/umbrello/class-diagram.png | Bin 0 -> 44071 bytes doc/umbrello/class.png | Bin 0 -> 4323 bytes doc/umbrello/code-import.png | Bin 0 -> 28877 bytes doc/umbrello/code_import_and_generation.docbook | 170 +++++++ doc/umbrello/collaboration-diagram.png | Bin 0 -> 70040 bytes doc/umbrello/composition.png | Bin 0 -> 1971 bytes doc/umbrello/credits.docbook | 12 + doc/umbrello/folders.png | Bin 0 -> 57871 bytes doc/umbrello/generalization.png | Bin 0 -> 1805 bytes doc/umbrello/generation-options.png | Bin 0 -> 47137 bytes doc/umbrello/index.docbook | 69 +++ doc/umbrello/introduction.docbook | 43 ++ doc/umbrello/other_features.docbook | 61 +++ doc/umbrello/sequence-diagram.png | Bin 0 -> 49267 bytes doc/umbrello/state-diagram.png | Bin 0 -> 44030 bytes doc/umbrello/umbrello-main-screen.png | Bin 0 -> 29106 bytes doc/umbrello/umbrello-ui-clean.png | Bin 0 -> 28962 bytes doc/umbrello/umbrello-ui.png | Bin 0 -> 31697 bytes doc/umbrello/uml_basics.docbook | 616 ++++++++++++++++++++++++ doc/umbrello/use-case-diagram.png | Bin 0 -> 44945 bytes doc/umbrello/working_with_umbrello.docbook | 448 +++++++++++++++++ 27 files changed, 1462 insertions(+) create mode 100644 doc/umbrello/Makefile.am create mode 100644 doc/umbrello/activity-diagram.png create mode 100644 doc/umbrello/add-remove-languages.png create mode 100644 doc/umbrello/aggregation.png create mode 100644 doc/umbrello/association.png create mode 100644 doc/umbrello/authors.docbook create mode 100644 doc/umbrello/class-diagram.png create mode 100644 doc/umbrello/class.png create mode 100644 doc/umbrello/code-import.png create mode 100644 doc/umbrello/code_import_and_generation.docbook create mode 100644 doc/umbrello/collaboration-diagram.png create mode 100644 doc/umbrello/composition.png create mode 100644 doc/umbrello/credits.docbook create mode 100644 doc/umbrello/folders.png create mode 100644 doc/umbrello/generalization.png create mode 100644 doc/umbrello/generation-options.png create mode 100644 doc/umbrello/index.docbook create mode 100644 doc/umbrello/introduction.docbook create mode 100644 doc/umbrello/other_features.docbook create mode 100644 doc/umbrello/sequence-diagram.png create mode 100644 doc/umbrello/state-diagram.png create mode 100644 doc/umbrello/umbrello-main-screen.png create mode 100644 doc/umbrello/umbrello-ui-clean.png create mode 100644 doc/umbrello/umbrello-ui.png create mode 100644 doc/umbrello/uml_basics.docbook create mode 100644 doc/umbrello/use-case-diagram.png create mode 100644 doc/umbrello/working_with_umbrello.docbook (limited to 'doc/umbrello') diff --git a/doc/umbrello/Makefile.am b/doc/umbrello/Makefile.am new file mode 100644 index 00000000..45fb6fde --- /dev/null +++ b/doc/umbrello/Makefile.am @@ -0,0 +1,2 @@ +KDE_LANG = en +KDE_DOCS = umbrello diff --git a/doc/umbrello/activity-diagram.png b/doc/umbrello/activity-diagram.png new file mode 100644 index 00000000..75234476 Binary files /dev/null and b/doc/umbrello/activity-diagram.png differ diff --git a/doc/umbrello/add-remove-languages.png b/doc/umbrello/add-remove-languages.png new file mode 100644 index 00000000..42c1d908 Binary files /dev/null and b/doc/umbrello/add-remove-languages.png differ diff --git a/doc/umbrello/aggregation.png b/doc/umbrello/aggregation.png new file mode 100644 index 00000000..46050842 Binary files /dev/null and b/doc/umbrello/aggregation.png differ diff --git a/doc/umbrello/association.png b/doc/umbrello/association.png new file mode 100644 index 00000000..ac984111 Binary files /dev/null and b/doc/umbrello/association.png differ diff --git a/doc/umbrello/authors.docbook b/doc/umbrello/authors.docbook new file mode 100644 index 00000000..1a079f02 --- /dev/null +++ b/doc/umbrello/authors.docbook @@ -0,0 +1,41 @@ + +Authors and History + +This project was started by Paul Hensgen as one of his University projects. +The original name of the application was UML Modeller. Paul did +all the development until the end of 2001 when the program reached version 1.0. + + +Version 1.0 already offered a lot of functionality, but after the project had been reviewed at +Paul's University, other developers could join and they started making valuable contributions +to UML Modeller, like switching from a binary file format to an &XML; file, support for more +types of &UML; Diagrams, Code Generation and Code Import just to name a few. + + +Paul had to retire from the development team in Summer 2002 but, as Free and Open Source Software, the +program continues to improve and evolve and is being maintained by a group of developers from different +parts of the world. In September 2002 the project changed its name from &UML; Modeller, to +&umbrello;. There are several reasons for the change of names, the most +important ones being that just uml — as it was commonly known — was a much too generic name +and caused problems with some distributions. The other important reason is that the developers think +Umbrello is a much cooler name. + + +The development of &umbrello; as well as discussions as to where the program should head for future versions +is open and takes place over the Internet. If you would like to contribute to the project, please do not +hesitate to contact the developers. There are many ways in which you can help &umbrello;: + + +Reporting bugs or improvements suggestions +Fixing bugs or adding features +Writing good documentation or translating it to other languages +And of course...coding with us! + + +As you see, there are many ways in which you can contribute. All of them are very important and +everyone is welcome to participate. + + +The &umbrello; developers can be reached at uml-devel@lists.sourceforge.net. + + diff --git a/doc/umbrello/class-diagram.png b/doc/umbrello/class-diagram.png new file mode 100644 index 00000000..3b12a4f6 Binary files /dev/null and b/doc/umbrello/class-diagram.png differ diff --git a/doc/umbrello/class.png b/doc/umbrello/class.png new file mode 100644 index 00000000..9c12a849 Binary files /dev/null and b/doc/umbrello/class.png differ diff --git a/doc/umbrello/code-import.png b/doc/umbrello/code-import.png new file mode 100644 index 00000000..49f477e5 Binary files /dev/null and b/doc/umbrello/code-import.png differ diff --git a/doc/umbrello/code_import_and_generation.docbook b/doc/umbrello/code_import_and_generation.docbook new file mode 100644 index 00000000..8beffcc3 --- /dev/null +++ b/doc/umbrello/code_import_and_generation.docbook @@ -0,0 +1,170 @@ + +Code Import and Code Generation + +&umbrello; is a &UML; modelling tool, and as such its main purpose is to help you in the +analysis and design of your systems. However, to make the transition +between your design and your implementation, &umbrello; allows you to +generate source code in different programming languages to get you started. Also, if you +want to start using &UML; in an already started C++ project, &umbrello; can help you create a model +of your system from the source code by analysing your source code and importing the classes +found in it. + + +Code Generation + +&umbrello; can generate source code for various programming languages based on your &UML; Model +to help you get started with the implementation of your project. The code generated consists +of the class declarations, with their methods and attributes so you can fill in the +blanks by providing the functionality of your classes' operations. + + +&umbrello; 1.2 comes with code generation support for ActionScript, Ada, C++, CORBA IDL, &Java;, JavaScript, PHP, Perl, Python, SQL and XMLSchema. + + +Generating Code + +In order to generate code with &umbrello;, you first need to create or load a Model +containing at least one class. When you are ready to start writing some code, select the +Code Generation Wizard entry from the Code menu to +start a wizard which will guide you trough the code generation process. + + +The first step is to select the classes for which you want to generate source code. +By default all the classes of your model are selected, and you can remove the ones +for which you do not want to generate code by moving them to the left-hand side list. + + +The next step of the wizard allows you to modify the parameters the Code Generator uses +while writing your code. The following options are available: + + + +Code Generation Options + + + + + + Options for the Code Generation in &umbrello; + + + Options for the Code Generation in &umbrello; + + + + + + +Generation Options + + + +Code Verbosity + +The option Write documentation comments even if empty instructs the + Code Generator to write comments of the /** blah */ style even if the comment blocks are empty. +If you added documentation to your classes, methods or attributes in your Model, the +Code Generator will write these comments as Doxygen documentation regardless of what you set here, but +if you select this option &umbrello; will write comment blocks for all classes, methods and attributes +even if there is no documentation in the Model, in which case you should document your classes +later directly in the source code. + + +Write comments for sections even if section is empty causes &umbrello; to write comments +in the source code to delimit the different sections of a class. For example public methods + or Attributes before the corresponding sections. If you select this option &umbrello; + will write comments for all sections of the class even if the section is empty. For example, + it would write a comment saying protected methods even if there are no protected + methods in your class. + + + +Folders + +Write all generated files to folder. Here you should select the folder +where you want &umbrello; to put the generated sources. + + +The Include heading files from folder option allows you to insert a +heading at the beginning of each generated file. Heading files can contain copyright or licensing + information and contain variables that are evaluated at generation time. You can take a look + at the template heading files shipped with &umbrello; to see how to use this variables for replacing + your name or the current date at generation time. + + + +Overwrite Policy + + +This option tells &umbrello; what to do if the file it wants to create already exists in +the destination folder. &umbrello; cannot modify existing source files, +so you have to choose between overwriting the existing file, skipping the generation of +that particular file or letting &umbrello; choose a different file name. If you choose the option +to use a different name, &umbrello; will add a suffix to the file name. + + + +Language + +&umbrello; will by default generate code in the language you have selected as Active Language, but +with the Code Generation Wizard you have the option to change this to another language. + + + + +Generation Wizard Generation + +The third and last step of the wizard shows the status of the Code Generation process. +You need only to click on the Generate button to get your classes written for you. + + +Note that the Options you select during the Code Generation Wizard are only valid for the current +generation. The next time you run the wizard you will need to re-select all the options +(your headings folder, overwrite policy, and so on). You can set the defaults used by &umbrello; +in the Code Generation section of the &umbrello; settings, available +at SettingsConfigure &umbrello;... + + +If you have set your Code Generation options to the right settings and want to generate +some code right away without going through the wizard, you can select the entire +Generate All Code from the Code menu. +This will generate code for all the classes in your Model using the current settings +(including Output Folder and Overwrite Policy, so use with care). + + + + + +Code Import + +&umbrello; can import source code from your existing projects to help you build Model of +your systems. &umbrello; 1.2 supports only C++ source code, but other languages +should be available in future versions. + + +To import classes into your Model, select the entry Import Classes... from +the Code menu. In the file dialog select the files containing the C++ +class declarations and press OK. The classes will be imported and you will find them as part of +your Model in the Tree View. Note that &umbrello; will not create any kind of Diagram for showing +your classes, they will only be imported into your Model so that you can use them later in any +diagram you want. + + + +Code Import + + + + + + Menu for importing source code in &umbrello; + + + Menu for importing source code in &umbrello; + + + + + + + diff --git a/doc/umbrello/collaboration-diagram.png b/doc/umbrello/collaboration-diagram.png new file mode 100644 index 00000000..681d5c77 Binary files /dev/null and b/doc/umbrello/collaboration-diagram.png differ diff --git a/doc/umbrello/composition.png b/doc/umbrello/composition.png new file mode 100644 index 00000000..ad07e1d9 Binary files /dev/null and b/doc/umbrello/composition.png differ diff --git a/doc/umbrello/credits.docbook b/doc/umbrello/credits.docbook new file mode 100644 index 00000000..807089a5 --- /dev/null +++ b/doc/umbrello/credits.docbook @@ -0,0 +1,12 @@ + +Copyright + +Copyright 2001, Paul Hensgen +Copyright 2002, 2003 The &umbrello; Authors. See +http://uml.sf.net/developers.php +for more information + +&underFDL; +&underGPL; + + diff --git a/doc/umbrello/folders.png b/doc/umbrello/folders.png new file mode 100644 index 00000000..59680d97 Binary files /dev/null and b/doc/umbrello/folders.png differ diff --git a/doc/umbrello/generalization.png b/doc/umbrello/generalization.png new file mode 100644 index 00000000..8236cca3 Binary files /dev/null and b/doc/umbrello/generalization.png differ diff --git a/doc/umbrello/generation-options.png b/doc/umbrello/generation-options.png new file mode 100644 index 00000000..37c05697 Binary files /dev/null and b/doc/umbrello/generation-options.png differ diff --git a/doc/umbrello/index.docbook b/doc/umbrello/index.docbook new file mode 100644 index 00000000..0da7c91e --- /dev/null +++ b/doc/umbrello/index.docbook @@ -0,0 +1,69 @@ + +Umbrello &UML; Modeller"> + + + UML"> + + + + + + + + + + +]> + + + +&umbrello; Handbook + + +&umbrello; Authors + + + +2001 +Paul Hensgen + + +2002, 2003 +&umbrello; Authors + + + +2003-10-15 +1.2 + + + +&umbrello; helps the software development +process by using the industry standard Unified Modelling Language (&UML;) +to enable you to create diagrams for designing and documenting your systems. + + + + +KDE +UML +modelling +diagrams +software development +development + + + + +&introduction-chapter; +¨-basics-chapter; +&working-with-umbrello-chapter; +&code-import-and-generation-chapter; +&other-features-chapter; +&authors-chapter; +&credits-chapter; + + diff --git a/doc/umbrello/introduction.docbook b/doc/umbrello/introduction.docbook new file mode 100644 index 00000000..3af9f719 --- /dev/null +++ b/doc/umbrello/introduction.docbook @@ -0,0 +1,43 @@ + +Introduction + + +&umbrello; is a &UML; diagram tool that can support you +in the software development process. +Especially during the analysis and design phases of this process, &umbrello; will help you to +get a high quality product. &UML; can also be used to document your software designs to help you and your +fellow developers. + + +Having a good model of your software is the best way to communicate with +other developers working on the project and with your customers. A good model +is extremely important for medium and big-size projects, but it is also very useful +for small ones. Even if you are working on a small one man project you +will benefit from a good model because it will give you an overview that will help +you code things right the first time. + + +&UML; is the diagramming language used to describing such models. You can represent your ideas in &UML; +using different types of diagrams. &umbrello; 1.2 supports the following types: + + +Class Diagram +Sequence Diagram +Collaboration Diagram +Use Case Diagram +State Diagram +Activity Diagram +Component Diagram +Deployment Diagram + + +More information about &UML; can be found at the website of +OMG, http://www.omg.org who create the &UML; standard. + + +We hope you enjoy &umbrello; and that it helps you create high quality software. +&umbrello; is Free Software and available at no cost, the only thing we ask from you is to report any bugs, problems, or suggestions +to the &umbrello; developers at uml-devel@lists.sourceforge.net or +http://bugs.kde.org. + + diff --git a/doc/umbrello/other_features.docbook b/doc/umbrello/other_features.docbook new file mode 100644 index 00000000..1f368622 --- /dev/null +++ b/doc/umbrello/other_features.docbook @@ -0,0 +1,61 @@ + +Other Features + +Other &umbrello; Features +This chapter will briefly explain some other features &umbrello; offers you. + +Copying objects as PNG images + +Apart from offering you the normal copy, cut and paste functionality that you would expect to copy +objects between different diagrams, &umbrello; can copy the objects as PNG pictures so that you can +insert them into any other type of document. You do not need to do anything special to use this feature, +just select an object from a diagram (Class, Actor, &etc;) and copy it (&Ctrl;C, + or using the menu), then open a &kword; document (or any program into which you can paste images) and select Paste. This is a great feature +to export parts of your diagram as simple pictures. + + + +Exporting to an Image + +You can also export a complete diagram as an image. The only thing you need to do is select +the diagram you want to export, and then the option Export as Picture... from +the Diagram menu. + + + +Printing + +&umbrello; allows you to print individual diagrams. Press the Print button on the + application toolbar or selecting the Print option from the +File menu will give you a standard &kde; Print dialog from where you can print +your diagrams. + + + +Logical Folders + +To better organize your model, especially for larger projects, you can create logical folders in +the Tree View. Just select the option NewFolder from the context menu +of the default folders in the Tree View to create them. Folders can be nested, and you can +move objects around by dragging them from one folder and dropping them into another. + + + +Organizing your Model with Folders + + + + + + Organizing a Model with Logical Folders in &umbrello; + + + Organizing a Model with Logical Folders in &umbrello; + + + + + + + + diff --git a/doc/umbrello/sequence-diagram.png b/doc/umbrello/sequence-diagram.png new file mode 100644 index 00000000..a5f9fbbc Binary files /dev/null and b/doc/umbrello/sequence-diagram.png differ diff --git a/doc/umbrello/state-diagram.png b/doc/umbrello/state-diagram.png new file mode 100644 index 00000000..610b2133 Binary files /dev/null and b/doc/umbrello/state-diagram.png differ diff --git a/doc/umbrello/umbrello-main-screen.png b/doc/umbrello/umbrello-main-screen.png new file mode 100644 index 00000000..52c48734 Binary files /dev/null and b/doc/umbrello/umbrello-main-screen.png differ diff --git a/doc/umbrello/umbrello-ui-clean.png b/doc/umbrello/umbrello-ui-clean.png new file mode 100644 index 00000000..8b147866 Binary files /dev/null and b/doc/umbrello/umbrello-ui-clean.png differ diff --git a/doc/umbrello/umbrello-ui.png b/doc/umbrello/umbrello-ui.png new file mode 100644 index 00000000..ee3d5911 Binary files /dev/null and b/doc/umbrello/umbrello-ui.png differ diff --git a/doc/umbrello/uml_basics.docbook b/doc/umbrello/uml_basics.docbook new file mode 100644 index 00000000..e9ad0d0d --- /dev/null +++ b/doc/umbrello/uml_basics.docbook @@ -0,0 +1,616 @@ + +&UML; Basics + +About &UML; + +This chapter will give you a quick overview of the basics of &UML;. Keep in mind +that this is not a comprehensive tutorial on &UML; but rather a brief introduction to &UML; which can be read as a &UML; tutorial. +If you would like to learn more about the +Unified Modelling Language, or in general about software analysis and design, refer to one of the +many books available on the topic. There are also a lot of tutorials on the Internet which you +can take as a starting point. + + + +The Unified Modelling Language (&UML;) is a diagramming language or notation to specify, visualize and document +models of Object Orientated software systems. &UML; is not a development method, that means it does not tell you +what to do first and what to do next or how to design your system, but it helps you to visualize +your design and communicate with others. &UML; is controlled by the Object Management Group (OMG) and is the +industry standard for graphically describing software. + + +&UML; is designed for Object Orientated software design and has limited use for other programming paradigms. + + +&UML; is composed of many model elements that represent the different parts of a software system. +The &UML; elements are used to create diagrams, which represent a certain part, or a point of view of +the system. +The following types of diagrams are supported by &umbrello;: + + + + +Use Case +Diagrams show actors (people or other users of the +system), use cases (the scenarios when they use the system), and their +relationships + +Class +Diagrams show classes and the relationships between +them + +Sequence +Diagrams show objects and a sequence of method calls +they make to other objects. + +Collaboration +Diagrams show objects and their relationship, + putting emphasis on the objects that participate in the message exchange + + +State +Diagrams show states, state changes and events in an +object or a part of the system + +Activity +Diagrams show activities and the changes from one +activity to another with the events occurring in some part of the +system + +Component +Diagrams show the high level programming components +(such as KParts or Java Beans). + +Deployment Diagrams show +the instances of the components and their +relationships. + + + + + + +&UML; Elements + +Use Case Diagram +Use Case Diagrams describe the relationships and dependencies between a group of Use Cases +and the Actors participating in the process. +It is important to notice that Use Case Diagrams are not suited to represent the design, +and cannot describe the internals of a system. Use Case Diagrams are meant to facilitate the communication +with the future users of the system, and with the customer, and are specially helpful to determine the required +features the system is to have. Use Case Diagrams tell, what the system +should do but do not — and cannot — specify how this is to be achieved. + + +An example Use Case diagram. + + + + + + &umbrello; showing a Use Case Diagram + + + &umbrello; showing a Use Case Diagram + + + + + + +Use Case +A Use Case describes — from the point of view of the actors — a group of activities +in a system that produces a concrete, tangible result. + +Use Cases are descriptions of the typical interactions between the users of a system and the system itself. +They represent the external interface of the system and specify a form of requirements of what the +system has to do (remember, only what, not how). + +When working with Use Cases, it is important to remember some simple rules: + + Each Use Case is related to at least one actor + Each Use Case has an initiator (&ie; an actor) + Each Use Case leads to a relevant result (a result with business value) + + + + +Use Cases can also have relationships with other Use Cases. The three most typical types of relationships +between Use Cases are: + +<<include>> which specifies that a Use Case takes place inside +another Use Case +<<extends>> which specifies that in certain situations, or at some point (called an +extension point) a Use Case will be extended by another. +Generalization specifies that a Use Case inherits the characteristics +of the Super-Use Case, and can override some of them or add new ones in a similar way as the +inheritance between classes. + + + + + +Actor + +An actor is an external entity (outside of the system) that interacts with the system by participating +(and often initiating) a Use Case. Actors can be in real life people (for example users of the system), +other computer systems or external events. + + +Actors do not represent the physical people or systems, but their role. +This means that when a person interacts with the system in different ways (assuming different roles) he will be +represented by several actors. For example a person that gives customer support by the telephone and takes +orders from the customer into the system would be represented by an actor Support Staff and +an actor Sales Representative + + + +Use Case Description + +Use Case Descriptions are textual narratives of the Use Case. They usually take the form of a note or +a document that is somehow linked to the Use Case, and explains the processes or activities that take +place in the Use Case. + + + + + +Class Diagram + +Class Diagrams show the different classes that make up a system and how they relate to each other. Class Diagrams +are said to be static diagrams because they show the classes, along with their methods and +attributes as well as the static relationships between them: which classes know about which classes +or which classes are part of another class, but do not show the method calls +between them. + + + +An example of a Class Diagram + + + + + + &umbrello; showing a Class Diagram + + + &umbrello; showing a Class Diagram + + + + + + +Class + +A Class defines the attributes and the methods of a set of objects. All objects of this class (instances +of this class) share the same behavior, and have the same set of attributes (each object has its own set). +The term Type is sometimes used instead of Class, but it is important to mention that these +two are not the same, and Type is a more general term. + + +In &UML;, Classes are represented by rectangles, with the name of the class, and can also show +the attributes and operations of the class in two other compartments inside the rectangle. + + + +A Class in &UML; + + + + + + Visual representation of a Class in &UML; + + + Visual representation of a Class in &UML; + + + + + + +Attributes + +In &UML;, Attributes are shown with at least their name, and can also show their type, initial value and +other properties. +Attributes can also be displayed with their visibility: + + ++ Stands for public attributes +# Stands for protected attributes +- Stands for private attributes + + + +Operations + +Operations (methods) are also displayed with at least their name, and can also show their parameters and return +types. +Operations can, just as Attributes, display their visibility: + ++ Stands for public operations +# Stands for protected operations +- Stands for private operations + + + + + +Templates + +Classes can have templates, a value which is used for an unspecified class or type. The template type is specified +when a class is initiated (&ie; an object is created). Templates exist in modern C++ and will be introduced in Java 1.5 where +they will be called Generics. + + + + + +Class Associations +Classes can relate (be associated with) to each other in different ways: + +Generalization +Inheritance is one of the fundamental concepts of Object Orientated programming, in which a class +gains all of the attributes and operations of the class it inherits from, and can +override/modify some of them, as well as add more attributes and operations of its own. + +In &UML;, a Generalization association between two classes puts them in a hierarchy +representing the concept of inheritance of a derived class from a base class. In &UML;, Generalizations are +represented by a line connecting the two classes, with an arrow on the side of the base class. + +Generalization + + + + + + Visual representation of a generalization in &UML; + + + Visual representation of a generalization in &UML; + + + + + + + + +Associations +An association represents a relationship between classes, and gives the common semantics and structure +for many types of connections between objects. +Associations are the mechanism that allows objects to communicate to each other. It describes the connection +between different classes (the connection between the actual objects is called object connection, or +link. + + +Associations can have a role that specifies the purpose of the association and can be uni- or bidirectional +(indicates if the two objects participating in the relationship can send messages to the other, of if only +one of them knows about the other). Each end of the association also has a multiplicity value, which dictates +how many objects on this side of the association can relate to one object on the other side. + + +In &UML;, associations are represented as lines connecting the classes participating in the relationship, +and can also show the role and the multiplicity of each of the participants. Multiplicity is displayed as a +range [min..max] of non-negative values, with a star (*) on the maximum side representing infinite. + +&UML; Association + + + + + + Visual representation of an Association in &UML; + + + Visual representation of an Association in &UML; + + + + + + + + +Aggregation +Aggregations are a special type of associations in which the two participating classes don't have +an equal status, but make a whole-part relationship. An Aggregation describes how the class +that takes the role of the whole, is composed (has) of other classes, which take the role of the parts. +For Aggregations, the class acting as the whole always has a multiplicity of one. + + +In &UML;, Aggregations are represented by an association that shows a rhomb on the side of the whole. + +Aggregation + + + + + + Visual representation of an Aggregation relationship in &UML; + + + Visual representation of an Aggregation relationship in &UML; + + + + + + + +Composition +Compositions are associations that represent very strong aggregations. This means, +Compositions form whole-part relationships as well, but the relationship is so strong that the parts cannot +exist on its own. They exist only inside the whole, and if the whole is destroyed the parts die too. +In &UML;, Compositions are represented by a solid rhomb on the side of the whole. + + +Composition + + + + + + Visual representation of a Composition relationship in &UML; + + + + + + + +Other Class Diagram Items +Class diagrams can contain several other items besides classes. + +Interfaces +Interfaces are abstract classes which means instances can not be directly created of them. They can contain operations but no attributes. Classes can inherit from interfaces (through a realisation association) and instances can then be made of these diagrams. + + + +Datatypes +Datatypes are primitives which are typically built into a programming language. Common examples include integers and booleans. +They can not have relationships to classes but classes can have relationships to them. + + + +Enums +Enums are a simple list of values. A typical example is an enum for days of the week. The options of an enum are called Enum Literals. +Like datatypes they can not have relationships to classes but classes can have relationships to them. + + + +Packages +Packages represent a namespace in a programming language. In a diagram +they are used to represent parts of a system which contain more than one class, maybe hundereds of classes. + + + + + + + +Sequence Diagrams + + Sequence Diagrams show the message exchange (&ie; method call) +between several Objects in a specific time-delimited +situation. Objects are instances of classes. +Sequence Diagrams put special emphasis in the order and the +times in which the messages to the objects are sent. + + +In Sequence Diagrams objects are represented through vertical dashed lines, with the name of the Object +on the top. The time axis is also vertical, increasing downwards, so that messages are sent from one Object +to another in the form of arrows with the operation and parameters name. + + + + +Sequence Diagram + + + + + + &umbrello; showing a Sequence Diagram + + + &umbrello; showing a Sequence Diagram + + + + + +Messages can be either synchronous, the normal type of message call where control is passed to the called object until that +method has finished running, or asynchronous where control is passed back directly to the calling object. Synchronous messages have +a vertical box on the side of the called object to show the flow of program control. + + + +Collaboration Diagrams + +Collaboration Diagrams show the interactions occurring between the objects participating in a specific +situation. This is more or less the same information shown by Sequence Diagrams but there the emphasis is +put on how the interactions occur in time while the Collaboration Diagrams +put the relationships between the objects and their topology in the foreground. + +In Collaboration Diagrams messages sent from one object to another are represented by arrows, showing +the message name, parameters, and the sequence of the message. Collaboration Diagrams are specially well suited +to showing a specific program flow or situation and are one of the best diagram types to quickly demonstrate +or explain one process in the program logic. + + + +Collaboration + + + + + + &umbrello; showing a Collaboration Diagram + + + &umbrello; showing a Collaboration Diagram + + + + + + + + +State Diagram +State Diagrams show the different states of an Object during its life and the stimuli that +cause the Object to change its state. + +State Diagrams view Objects as state machines or finite automates that can +be in one of a set of finite states and that can change its state via one of a finite set of stimuli. For example +an Object of type NetServer can be in one of following states during its life: + + +Ready +Listening +Working +Stopped + +and the events that can cause the Object to change states are + +Object is created +Object receives message listen +A Client requests a connection over the network +A Client terminates a request +The request is executed and terminated +Object receives message stop +etc + + + +State Diagram + + + + + + &umbrello; showing a State Diagram + + + &umbrello; showing a State Diagram + + + + + + +State +States are the building block of State Diagrams. A State belongs to exactly one class and represents +a summary of the values the attributes of a class can take. A &UML; State describes the internal state of an +object of one particular class + +Note that not every change in one of the attributes of an object should be represented by a State +but only those changes that can significantly affect the workings of the object + +There are two special types of States: Start and End. They are special in that there is no event that +can cause an Object to return to its Start state, in the same way as there is no event that can possible take +an Object out of its End state once it has reached it. + + + + + + +Activity Diagram +Activity Diagrams describe the sequence of activities in a system with the +help of Activities. Activity Diagrams are a special form of State Diagrams, that only (or mostly) contains +Activities. + + + +An example Activity Diagram. + + + + + + &umbrello; showing an Activity Diagram + + + &umbrello; showing an Activity Diagram + + + + + +Activity Diagrams are similar to procedural Flux Diagrams, with the difference that all Activities +are clearly attached to Objects. + +Activity Diagrams are always associated to a +Class, an Operation or a +Use Case. + +Activity Diagrams support sequential as well as parallel Activities. Parallel execution is represented +via Fork/Wait icons, and for the Activities running +in parallel, it is not important the order in which they are carried out (they can be executed at the same +time or one after the other) + +Activity +An Activity is a single step in a process. One Activity is one state +in the system with internal activity and, at least, one outgoing transition. Activities can also have +more than one outgoing transition if they have different conditions. + +Activities can form hierarchies, this means that an Activity can be composed of several detail +Activities, in which case the incoming and outgoing transitions should match the incoming and outgoing transitions +of the detail diagram. + + + + + + +Helper Elements +There are a few elements in &UML; that have no real semantic value for the model, but help to clarify +parts of the diagram. These elements are + +Text lines +Text Notes and anchors +Boxes + + +Text lines are useful to add short text information to a diagram. It is free-standing text and has no +meaning to the Model itself. + + + +Notes are useful to add more detailed information about an +object or a specific situation. They have the great advantage that +notes can be anchored to &UML; Elements to show that the note +belongs to a specific object or situation. + + +Boxes are free-standing rectangles which can be used to group items together to make diagrams more readable. They +have no logical meaning in the model. + + + + + +Component Diagrams +Component Diagrams show the software components (either component technologies such as KParts, CORBA components or Java Beans or +just sections of the system which are clearly distinguishable) and the artifacts they +are made out of such as source code files, programming libraries or relational database tables. + +Components can have interfaces (&ie; abstract classes with operations) that allow associations between components. + + + +Deployment Diagrams + +Deployment diagrams show the runtime component instances and their +associations. They include Nodes which are physical resources, +typically a single computer. They also show interfaces and objects (class instances). + + + + + diff --git a/doc/umbrello/use-case-diagram.png b/doc/umbrello/use-case-diagram.png new file mode 100644 index 00000000..36f4320d Binary files /dev/null and b/doc/umbrello/use-case-diagram.png differ diff --git a/doc/umbrello/working_with_umbrello.docbook b/doc/umbrello/working_with_umbrello.docbook new file mode 100644 index 00000000..3cf32f83 --- /dev/null +++ b/doc/umbrello/working_with_umbrello.docbook @@ -0,0 +1,448 @@ + +Working with &umbrello; + + + +This chapter will introduce you to &umbrello;'s user interface and will +tell you all you need to know to start modelling. All actions in &umbrello; are accessible via the menu and +the toolbars, but &umbrello; also makes extensive use of &RMB; context menus. You can &RMB; click on almost any element in +&umbrello;'s work area or tree view to get a menu with the most useful +functions that can be applied to the particular element you are +working on. Some users find this a little confusing at the beginning because they are more used to working with the menu or tool bars, but +once you get used to right clicking it will greatly speed up your work. + + + +User Interface + +&umbrello;'s main window is divided in three areas that will help you keep an overview of your entire system +and access the different diagrams quickly while working on your model. + +These areas are called: + +Tree View +Work Area +Documentation Window + + + +&umbrello;'s User Interface + + + + + + &umbrello;'s User Interface + + + &umbrello;'s User Interface + + + + + + +Tree View + +The Tree View is usually located on the top left hand side of the window and shows the all the diagrams, +classes, actors and use cases that build up your model. +The Tree View allows you to have a quick overview of the elements composing your model. The Tree View also +gives you a quick way to switch between the different diagrams in your model and inserting elements from +your model into the current diagram. + + +If you are working on a model with more than just a few classes and diagrams, the Tree View may help +you stay on top of things by organizing your model elements in folders. You can create +folders by selecting the appropriate option from the context menu (&RMB; click on one of the folders +in the tree view) and you can organize your elements by moving them to the appropriate folder (drag and drop) + + + + + +Documentation Window + +The Documentation Window is the small window located on the left bottom of &umbrello;, and it gives +you a quick preview of the documentation for the currently selected item. The Documentation Window is +rather small because it is intended to allow you just a quick pick into the element's documentation while +taking as little screen space as possible. If you need to view the documentation in more detail you can always +open the item's properties. + + + +Work Area + +The Work Area is the main window in &umbrello; and is where the real action takes place. You use the Work Area +to edit and view the diagrams in your model. The Work Area shows the currently active diagram. Currently +only one diagram can be shown on the Work Area at any time. + + + + +Creating, Loading and Saving Models + +The first thing you need to start doing something useful with &umbrello; is to create a model to work on. +When you start &umbrello; it always loads the last used model or creates a new, empty model (depending on +your preferences set in the configuration dialog). This will allow you to start working right away. + + +New Model + +If at any time you need to create a new model you can do this by selecting the New entry from the +File menu, or by clicking on the New icon from the application toolbar. If you are currently working on +a model which has been modified &umbrello; will ask you if it should save your changes before loading the +new model. + + + +Save Model + +You can save your model at any time by selecting the option Save from the File Menu or by clicking +on the Save button from the application toolbar. If you need to save your model under a different name +you can use the option Save As from the File Menu. + +For your convenience &umbrello; also offers you the option to automatically save your work +each certain time period. You can configure if you want this option as well as the time intervals +in the Settings from &umbrello; + + +Load Model + +For loading an already existing model you may select the option Open from the File Menu or click on the Open +icon from the application toolbar. The most recently used models are also available under the submenu +Open Recent in the File Menu to speed up access to your most frequently used models. + + +&umbrello; can only work on one model at a time, so if you ask the program to load a model for you and your +current model has been modified since the last time you save it, &umbrello; will ask you whether your changes +should be saved to prevent any loss of work. You can start two or more instances of &umbrello; at any one time, you can also copy and paste between instances. + + + + +Editing Models + +In &umbrello;, there are basically two ways for editing the elements in your model. + +Edit model elements directly through the Tree View +Edit model elements through a Diagram + + + +Using the context menu of the different items in the Tree View you are able to add, remove, +and modify almost all the elements in your model. Right clicking on the folders in the Tree View +will give you options for creating the different types of diagrams as well as, depending on whether +the folder is a Use Case View or a Logical View, Actors, +Use Cases, Classes, etc. + + +Once you have added elements to your model you can also edit an element by accessing its properties +dialog, which you find by selecting the option Properties from the context menu +shown when right clicking on the items in the Tree View. + + +You can also edit your model by creating or modifying elements through diagrams. More details on how +to do this are given in the following sections. + + + +Adding and Removing Diagrams + +Your &UML; model consists of a set of &UML; elements and associations between them. However you cannot see the model +directly, you use Diagrams to look at it. + + +Creating Diagrams + +To create a new diagram in your model simply select the diagram type you need from the New submenu in the Diagram menu and give a name to it. The diagram will be created and made active, and you will immediately +see it in the tree view. + + +Remember that &umbrello; makes extensive use of context menus: you can also &RMB; click on a folder in the Tree +View and select the appropriate diagram type from the New submenu in the context menu. Note that you can create +Use Case Diagrams only in Use Case View folders, and the other types of diagram can only be created in the +Logical View folders. + + + +Removing Diagrams + +Should you need to remove a diagram from your model, you can do this by making it active and selecting +Delete from the Diagram Menu. You can also achieve this by selecting Delete from the diagrams context menu +in the Tree View + +Since deleting a diagram is something serious that could cause loss of work if done by accident, &umbrello; +will ask you to confirm the delete operation before actually removing the Diagram. Once a diagram has been +deleted and the file has been saved there is no way to undo this action. + + + +Renaming Diagrams + +If you want to change the name of an existing diagram you can easily do this by selecting the Rename option +from its &RMB; menu in the Tree View. + +Another way to rename a diagram is to do this via its properties dialog, which you obtain by +selecting Properties from its Context Menu or by double clicking on it in the Tree View. + + + + +Editing Diagrams + +When working on a diagram, &umbrello; will try to guide you by applying some simple rules as to which +elements are valid in the different types of diagrams, as well as the relationships that can exist +between them. If you are an &UML; expert you will probably not even notice it, but this will help +&UML; novices create standard-conformant diagrams. + + +Once you have created your diagrams it is time to start editing them. Here you should notice +the (for beginners subtle) difference between editing your diagram, and editing the +model. As you already know, Diagrams are views of your model. +For example, if you create a class by editing a Class Diagram, you are really editing both, your +Diagram and your model. If you change the color or other display options of a Class in your Class +Diagram, you are only editing the Diagram, but nothing is changed in your model. + + +Insert Elements + +One of the first things you will do when editing a new diagram is to insert elements into them (Classes, +Actors, Use Cases, &etc;) There is basically two ways of doing this: + +Dragging existing elements in your model from the Tree View +Creating new elements in your model and adding them to your diagram at the +same time, by using one of the edit Tools in the Work Toolbar + + +To insert elements that already exist in your model, just drag them from the Tree View and +drop them where you want them to be in your diagram. You can always move elements around +in your Diagram using the Select Tool + + +The second way of adding elements to your diagram is by using the Work Toolbar's edit tools (note +that this will also add the elements to your model). + + +The Work Toolbar was by default located on the far right of the application window, &umbrello; 1.2 has moved this to the top of the window. +You can dock it into other edge or have it floating around if you prefer. The tools available +on this toolbar (the buttons you see on it) change depending on the type of diagram +you are currently working on. The button for the currently +selected tool is activated in the toolbar. You can switch to the select tool +by pressing the &Esc; key. + + +When you have selected an edit tool from the Work Toolbar (for example, the tool to insert classes) +the mouse pointer changes to a cross, and you can insert the elements in your model by single clicking +in your diagram. Note that elements in &UML; must have a Unique Name. So that if +you have a class in one diagram whose name is ClassA and then you use the insert Class +tool to insert a class into another diagram you cannot name this new class ClassA as well. +If these two are supposed to be two different elements, you have to give them a unique name. If you are +trying to add the same element to your diagram, then the Insert Class is not +the right tool for that. You should drag and drop the class from the Tree View instead. + + + +Deleting Elements + +You can delete any element by selecting the option Delete from its context menu. + + +Again, there is a big difference between removing an object from a diagram, and +deleting an object from your model: +If you delete an object from within a diagram, you are only removing the object from that particular +diagram: the element will still be part of your model and if there are other diagrams using the same +element they will not suffer any change. +If, on the other hand, you delete the element from the Tree View, you are actually deleting the +element from your model. Since the element no longer exist in your model, +it will be automatically removed from all the diagrams it appears in. + + + +Editing Elements + +You can edit most of the &UML; elements in your model and diagrams by opening its Properties dialog +and selecting the appropriate options. +To edit the properties of an object, select Properties from its context menu (&RMB; click). Each element has a dialog consisting of several pages where you can configure the options +corresponding to that element. For some elements, like actors you can only set a couple of options, +like the object name and documentation, while for other elements, like classes, you can edit its +attributes and operations, select what you want to be shown in the diagram (whole operation signature +or just operation names, etc) and even the colors you want to use for the line and fill of the class' +representation on the diagram. + + + +For most &UML; elements you can also open the properties dialog by +double clicking on it if you are using the selection tool (arrow). The +exception to this is Associations, in which case a double click +creates an anchor point. For associations you need to use the &RMB; context menu to get the properties dialog. + + + +Note that you can also select the properties option from the context +menu of the elements in the Tree View. This allows you to also edit +the properties for the diagrams, like setting whether the grid should +be shown or not. + + + +Editing Classes + +Even though editing the properties of all objects was already covered in the previous section, +classes deserve a special section because they are a bit more complicated and have more options +than most of the other &UML; elements. + + +In the properties dialog for a class you can set everything, from the color it uses to the operations +and attributes it has. + + +Class General Settings + +The General Settings page of the properties dialog is self-explanatory. Here you can change the +class' name, visibility, documentation, &etc; +This page is always available. + + + +Class Attribute Settings + +In the Attributes Settings page you can add, edit, or delete attributes (variables) of the class. +You can move attributes up and down the list by pressing the arrow button +on the side. +This page is always available. + + + +Class Operations Settings + +Similar to the Attribute Settings Page, in the Operation Settings Page you can add, edit, or +remove operations for your class. When adding or editing an operation, you enter the basic data in +the Operation Properties dialog. If you want to add parameters to your operation +you need to click the New Parameter button, which will show the +Parameter Properties dialog. +This page is always available + + + +Class Template Settings + +This page allows you to add class templates which are unspecified classes or datatypes. In Java 1.5 these will be called Generics. + + + +Class Associations Page + +The Class Associations page shows all the associations of this class +in the current diagram. Double clicking on an association shows its properties, and depending +on the type of association you may modify some parameters here such as setting multiplicity and Role +name. If the association does not allow such options be be modified, the Association Properties dialog +is read-only and you can only modify the documentation associated with this association. + + +This page is only available if you open the Class Properties from within a diagram. If you select +the class properties from the context menu in the Tree View this page is not available. + + + +Class Display Page + +In the Display Options page, you can set what is to be shown in the diagram. +A class can be shown as only one rectangle with the class name in it (useful if you have many +classes in your diagram, or are for the moment not interested in the details of each class) or +as complete as showing packages, stereotypes, and attributes and operations with full signature and +visibility + +Depending on the amount of information you want to see you can select the corresponding +options in this page. The changes you make here are only display options +for the diagram. This means that hiding a class' operations only makes them +not to be shown in the diagram, but the operation are still there as part of your model. +This option is only available if you select the class properties from within a Diagram. If you open +the class properties from the Tree View this page is missing since such Display Options do not make sense +in that case + + +Class Color Page + +In the Widget Color page you can configure the colors you want for the line +and the fill of the widget. This option obviously makes sense only for classes displayed in diagrams, +and is missing if you open the class' properties dialog from the Tree View. + + + + + +Associations + +Associations relate two &UML; objects to each other. Normally associations are defined between two classes, +but some types of associations can also exists between use cases and actors. + + +To create an association select the appropriate tool from the Work Toolbar (generic Association, +Generalization, Aggregation, &etc;) and single click on the first element participating in the association +and then single click on the second item participating. Note that those are two clicks, one on each +on the objects participating in the association, it is not a drag from one object +to the other. + + +If you try to use an association in a way against the &UML; specification &umbrello; will refuse to create +the association and you will get an error message. This would be the case if, for example, a Generalization +exists from class A to class B and then you try to create another Generalization from Class B to class A + + +Right clicking on an association will show a context menu with the actions you can apply on it. If you need to delete an association simply select the Delete option from this context menu. +You can also select the Properties option and, depending on the association type +edit attributes such as roles and multiplicity. + + +Anchor Points + +Associations are drawn, by default, as a straight line connecting the two objects in the diagram. + + +You can add anchor points to bend an association by double clicking some where along the association line. This will insert +an anchor point (displayed as a blue point when the association line is selected) which you can move +around to give shape to the association + + +If you need to remove an anchor point, double click on it again to remove it + + +Note that the only way to edit the properties of an association is through the context menu. If you +try to double click on it as with other &UML; objects, this will only insert an anchor point. + + + + + +Notes, Text and Boxes + +Notes, Lines Of Text and Boxes are elements that can be present in any type of diagram and have no real +semantic value, but are very helpful to add extra comments or explanations that can make your +diagram easier to understand. + + +To add a Note or a Line Of Text, select the corresponding tool from the Work Toolbar and single click +on the diagram where you want to put your comment. You can edit the text by opening the element through +its context menu or in the case of notes by double clicking on them as well. + + +Anchors + +Anchors are used to link a text note and another &UML; Element together. For example, you normally +use a text note to explain or make some comment about a class or a particular association, in which +case you can use the anchor to make it clear that the note belongs to that particular +element. + + +To add an anchor between a note and another &UML; element, use the anchor tool from the work toolbar. +You first need to click on the note and then click on the &UML; element you want the note to be linked +to. + + + + + + -- cgit v1.2.1